Readme.md

Reference Lowerer

Non-normative reference lowering workspace for projecting FIR into lowered backend-oriented forms
FROG — Free Open Graphical Language

---

Purpose

This directory contains the current non-normative reference lowerer for the FROG implementation workspace. It exists to make the published FIR -> lowering corridor executable and checkable for the bounded Examples 01-15 public reference runtime closure and the post-boundary Example 16 Picture lowering slice without claiming general lowering completeness.

The lowerer is downstream from FIR and upstream from backend contracts, runtime consumers, and compiler-family consumers. It does not define FROG source semantics, validated meaning, backend contract law, runtime behavior, or LLVM behavior.

---

Current Lowering Posture

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

Rule selection is based on the FIR unit kind rather than the source example identifier. The source_ref remains preserved for traceability, but it is not the lowering-rule authority.

---

Supported Lowering Targets

• Examples/01_pure_addition/main.fir.json -> main.lowering.json
• Examples/02_ui_value_roundtrip/main.fir.json -> main.lowering.json
• Examples/03_ui_property_write/main.fir.json -> main.lowering.json
• Examples/04_stateful_feedback_delay/main.fir.json -> main.lowering.json
• Examples/05_bounded_ui_accumulator/main.fir.json -> main.lowering.json
• Examples/06_boolean_value_roundtrip/main.fir.json -> main.lowering.json
• Examples/07_string_value_roundtrip/main.fir.json -> main.lowering.json
• Examples/08_enum_value_roundtrip/main.fir.json -> main.lowering.json
• Examples/09_path_value_roundtrip/main.fir.json -> main.lowering.json
• Examples/10_button_press_to_boolean/main.fir.json -> main.lowering.json
• Examples/11_button_switch_when_pressed/main.fir.json -> main.lowering.json
• Examples/12_button_switch_when_released/main.fir.json -> main.lowering.json
• Examples/13_button_latch_when_pressed/main.fir.json -> main.lowering.json
• Examples/14_button_latch_when_released/main.fir.json -> main.lowering.json
• Examples/15_button_latch_until_released/main.fir.json -> main.lowering.json
• Examples/16_picture_logo_jpeg/main.fir.json -> main.lowering.json

---

Commands

Generic FIR-to-lowering check

python Implementations/Reference/Lowerer/lower_fir.py \
  --fir Examples/01_pure_addition/main.fir.json \
  --expected Examples/01_pure_addition/main.lowering.json \
  --check

Example 05 legacy helper

python Implementations/Reference/Lowerer/lower_example05_fir.py --check

The legacy helper remains available for focused Example 05 debugging. The generic lower_fir.py entry point is the preferred path for supported examples.

---

Rule Family Documentation

• Reference FIR-to-lowering rule-family index

---

Current Family-to-Lowered Mapping

FIR unit kind	Lowered unit kind	Backend-family target	Compiler-family target
pure_dataflow_arithmetic_unit	pure_addition_kernel	reference_pure_dataflow_arithmetic	llvm_oriented_native_path
ui_value_roundtrip_unit	ui_value_roundtrip_kernel	reference_ui_value_roundtrip	None currently declared
ui_property_write_unit	ui_property_write_effect_unit	reference_ui_property_write	None currently declared
stateful_feedback_delay_unit	stateful_feedback_delay_kernel	reference_stateful_feedback_delay	llvm_oriented_native_path
bounded_stateful_ui_unit	bounded_accumulator_kernel_with_ui_bindings	reference_host_runtime_ui_binding	llvm_oriented_native_path
boolean_value_roundtrip_ui_unit	boolean_value_roundtrip_kernel_with_ui_bindings	reference_host_runtime_ui_binding	llvm_native_kernel_bridge
string_value_roundtrip_ui_unit	string_value_roundtrip_kernel_with_ui_bindings	reference_host_runtime_ui_binding	llvm_native_kernel_bridge
enum_value_roundtrip_ui_unit	enum_value_roundtrip_kernel_with_ui_bindings	reference_host_runtime_ui_binding	llvm_native_kernel_bridge
path_value_roundtrip_ui_unit	path_value_roundtrip_kernel_with_ui_bindings	reference_host_runtime_ui_binding	llvm_native_kernel_bridge
button_press_to_boolean_ui_unit	button_press_to_boolean_kernel_with_ui_bindings	reference_host_runtime_ui_binding	llvm_native_kernel_bridge
picture_path_to_image_ui_unit	picture_path_to_image_with_ui_bindings	llvm_native_kernel_with_standard_provider	manifest-declared standard provider

---

Boundary

The lowerer is a reference implementation tool that protects the current published FIR-to-lowering corridor. It does not define source law, semantic law, FIR law, backend contract law, runtime behavior, or compiler-family behavior.