Skip to content

Readme.md

Latest commit

 

History

History
191 lines (152 loc) · 6.81 KB

Readme.md

File metadata and controls

191 lines (152 loc) · 6.81 KB

FROG logo

Reference FIR Derivation Rule Families

Bounded source-pattern families used by the non-normative reference deriver
FROG — Free Open Graphical Language

Purpose

This directory documents the bounded source-pattern rules currently recognized by the reference deriver. The purpose is to keep the .frog -> FIR corridor explicit while avoiding the weaker posture where derivation is selected only by an example identifier.

These documents are non-normative reference-implementation material. They do not replace IR/Derivation rules.md, IR/Execution IR.md, Expression/, or Language/.

Current Rule-Selection Posture

canonical .frog source
  -> source structure inspection
  -> bounded source-pattern recognition
  -> exactly one matching derivation rule
  -> published FIR artifact

The reference deriver attempts all registered rules and accepts a source only when exactly one rule matches. The metadata.name field may be reported in diagnostics, but it is not the authority used to select the derivation rule.

Current Rule Families

Rule family Current rule id Published example Recognized source shape Derived FIR unit kind
Pure public-interface arithmetic pure_public_addition 01_pure_addition Two public f64 inputs connected to one frog.core.add primitive and one public f64 output. pure_dataflow_arithmetic_unit
Natural widget-value dataflow ui_value_roundtrip 02_ui_value_roundtrip Two control widget_value sources connected to frog.core.add, with result published to one indicator widget_value. ui_value_roundtrip_unit
Object-style UI property effect ui_property_write 03_ui_property_write One public string input and one widget reference feeding one frog.ui.property_write effect. ui_property_write_unit
Explicit delay-backed state stateful_feedback_delay 04_stateful_feedback_delay One explicit frog.core.delay state carrier with initial value, feeding a valid feedback add step. stateful_feedback_delay_unit
Bounded UI accumulator bounded_ui_accumulator 05_bounded_ui_accumulator One public u16 input, one public u16 output, widget-value bindings, property writes, bounded loop, and explicit accumulator state. bounded_stateful_ui_unit

Family Boundaries

Pure public-interface arithmetic

This family derives public-boundary arithmetic graphs without UI participation or explicit state. It preserves public inputs, public outputs, primitive identity, directed dependency structure, and publication to the public output boundary.

Natural widget-value dataflow

This family derives ordinary value participation by front-panel widgets. It preserves the distinction between widget_value participation and public interface participation. It does not treat widget values as public interface ports.

Object-style UI property effect

This family derives object-style UI interactions. It preserves the distinction between widget_reference participation and the actual UI primitive operation, such as frog.ui.property_write.

Explicit delay-backed state

This family derives a valid feedback cycle only when an explicit local-memory carrier provides the required initial state and commit boundary. It must not infer hidden state from a cycle that lacks such a carrier.

Bounded UI accumulator

This family composes the earlier concerns in a bounded form: public IO, widget-value binding, widget-reference property writes, bounded loop posture, and explicit accumulator state. It is the richest current source-to-FIR derivation slice, but it remains deliberately narrow.

Preconditions Shared by the Current Rules

  • The source must be loadable JSON.
  • The source must expose metadata, interface, and diagram objects as required by the current examples.
  • The diagram.nodes and diagram.edges collections must be arrays.
  • Node identifiers must be unique strings.
  • Edge endpoints must expose string node and port members.
  • Each recognized rule must find its required nodes, edges, public interface shape, widget-value participants, property-write participants, or explicit state carriers.

Failure Modes

  • No matching rule: derivation fails with diagnostics from all attempted rules.
  • Multiple matching rules: derivation fails as ambiguous.
  • Malformed source structure: derivation fails before a FIR artifact is produced.
  • Unsupported source family: derivation fails explicitly rather than guessing a FIR shape.

Out of Scope

  • general FROG compiler completeness,
  • automatic derivation for arbitrary graph shapes,
  • general type inference,
  • general structured-control lowering,
  • general UI host semantics,
  • general widget realization consumption,
  • runtime scheduling,
  • LLVM emission,
  • backend contract generation.

Next Stabilization Direction

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

recognized source family
  -> shared extraction helpers
  -> shared FIR construction helpers
  -> narrower example-specific constants

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