Skip to content

Readme.md

Latest commit

 

History

History
203 lines (164 loc) · 7.24 KB

Readme.md

File metadata and controls

203 lines (164 loc) · 7.24 KB

FROG logo

Reference FIR-to-Lowering Rule Families

Bounded FIR-unit-kind lowering families used by the non-normative reference lowerer
FROG — Free Open Graphical Language

Purpose

This directory documents the bounded FIR-to-lowering rule families currently recognized by the reference lowerer. The purpose is to keep the FIR -> lowering corridor explicit while avoiding the weaker posture where lowering is selected only by an example identifier.

These documents are non-normative reference-implementation material. They do not replace IR/Lowering.md, IR/Backend contract.md, IR/Execution IR.md, or the canonical source and language layers.

Current Rule-Selection Posture

FIR artifact
  -> artifact_kind == frog_fir_unit
  -> exactly one FIR unit
  -> FIR units[0].kind
  -> matching bounded lowering rule
  -> lowered_unit.kind
  -> backend / runtime / LLVM-compatible lowered surface

The reference lowerer dispatches by units[0].kind. The source example identifier remains preserved in source_ref, but it is no longer the lowering-rule authority.

Current Lowering Rule Families

Lowering family Current rule id Input FIR unit kind Output lowered unit kind Backend-family target Compiler-family target
Pure public-interface arithmetic lower_pure_dataflow_arithmetic pure_dataflow_arithmetic_unit pure_addition_kernel reference_pure_dataflow_arithmetic llvm_oriented_native_path
Natural widget-value dataflow lower_ui_value_roundtrip ui_value_roundtrip_unit ui_value_roundtrip_kernel reference_ui_value_roundtrip None currently declared
Object-style UI property effect lower_ui_property_write ui_property_write_unit ui_property_write_effect_unit reference_ui_property_write None currently declared
Explicit delay-backed state lower_stateful_feedback_delay stateful_feedback_delay_unit stateful_feedback_delay_kernel reference_stateful_feedback_delay llvm_oriented_native_path
Bounded stateful UI lower_bounded_stateful_ui bounded_stateful_ui_unit bounded_accumulator_kernel_with_ui_bindings reference_host_runtime_ui_binding llvm_oriented_native_path

Shared Lowering Invariants

  • The input artifact must declare artifact_kind = frog_fir_unit.
  • The input artifact must contain exactly one FIR unit.
  • The FIR unit must expose a string kind.
  • The FIR unit kind must match exactly one registered lowering rule.
  • The output artifact must declare artifact_kind = frog_lowered_unit.
  • The output artifact must carry artifact_governance_ref pointing to centralized version governance.
  • The output artifact must preserve source_ref.
  • The output artifact must carry fir_ref pointing back to the input FIR artifact and unit id.
  • The output artifact must contain exactly one lowered unit for the current bounded corridor.
  • The lowered unit kind must match the registered rule's declared output kind.

Family Boundaries

Pure public-interface arithmetic

This family projects a pure FIR arithmetic unit into a compact executable kernel with public IO, one add operation, and one final publication. It is consumable by the generic runtime contract executor and the LLVM-oriented native proof path.

Natural widget-value dataflow

This family preserves widget-value bindings while projecting the computation into a compact UI-value kernel. It keeps widget-value participation distinct from public interface IO.

Object-style UI property effect

This family projects an object-style UI effect into an explicit lowered effect unit. It keeps widget_reference support distinct from frog.ui.property_write execution effects.

Explicit delay-backed state

This family projects explicit delay-backed state into a stateful lowered kernel with initial state, state type, step body, commit rule, and final publication. It must not infer state where the FIR does not provide explicit state.

Bounded stateful UI

This family projects the bounded accumulator FIR into a lowered unit that can be consumed by the reference host-runtime UI-binding backend and the LLVM-oriented native proof path. It preserves public IO, widget bindings, explicit state, iteration count, iteration body, commit rule, and final publications.

Failure Modes

  • Invalid artifact kind: lowering fails before rule selection.
  • Missing or non-string FIR unit kind: lowering fails before rule selection.
  • Unsupported FIR unit kind: lowering fails with the list of supported unit kinds.
  • Ambiguous FIR unit kind: lowering fails if multiple registered rules claim the same FIR unit kind.
  • Malformed FIR unit structure: the selected rule fails before producing a lowered artifact.
  • Lowered kind mismatch: lowering fails if a rule produces a lowered unit kind different from the registered output kind.

Out of Scope

  • general lowering for arbitrary FIR units,
  • backend-specific optimization,
  • runtime scheduling,
  • native ABI definition,
  • general UI host lowering,
  • general widget realization lowering,
  • LLVM code generation itself,
  • backend-contract generation itself.

Next Stabilization Direction

The next safe improvement is to keep the current rule families but progressively factor repeated lowering concepts out of example-shaped functions: 

FIR unit kind
  -> shared validation helpers
  -> shared lowered artifact construction helpers
  -> narrower family-specific kernel projection

Only after that step should the reference implementation attempt broader lowering behavior.