Skip to content

pipeline.md

Latest commit

 

History

History
242 lines (199 loc) · 8.22 KB

pipeline.md

File metadata and controls

242 lines (199 loc) · 8.22 KB

FROG logo

Reference Pipeline

Executable pipeline for the Examples 01-15 public reference runtime closure
FROG — Free Open Graphical Language

Current Pipeline

Examples 01-15
  widget layer validation
    -> .frog
    -> FIR
    -> lowering
    -> backend contract
    -> runtime acceptance
    -> LLVM module / native proof

The widget-layer validator is included by default because the current Examples 01-15 corridor depends on a stable published UI/widget layer, especially through widget_value, widget_reference, frog.ui.property_write, the Example 05 front-panel package, and the Example 06-15 Default realization packages.

This named pipeline keeps the public reference runtime closure reproducible at the source/FIR/lowering/contract/LLVM boundary. The historical runtime acceptance stage still covers Examples 01 through 10; Examples 11 through 15 are additionally covered by runtime-family tests and native-kernel bridge checks documented under Implementations/Reference/Runtime/.

How the Current Reference Corridor Runs

This section describes the current reference corridor as a non-normative implementation-facing shape. It explains how the published artifacts are wired together for the bounded public reference runtime closure. It does not define the FROG language, widget law, runtime law, LLVM law, or future production implementation strategy. 

main.frog
  -> loadability
  -> structural validation
  -> semantic validation
  -> main.fir.json
  -> main.lowering.json
  -> backend contract
  -> runtime acceptance
  -> LLVM-oriented module / native proof where applicable
  -> runtime orchestration
  -> host UI / front-panel update where applicable

The current UI and native-proof corridor has two visible branches that meet at the runtime boundary. 

+----------------------+
| .frog                |
| canonical source     |
+----------+-----------+
           |
           v
+----------------------+
| structural validation|
+----------+-----------+
           |
           v
+----------------------+
| semantic validation  |
+----------+-----------+
           |
           v
+----------------------+
| FIR                  |
| open Execution IR    |
+------+-------+-------+
       |       |
       |       +----------------------------+
       |                                    |
       v                                    v
+----------------------+        +----------------------+
| lowering             |        | widget realization   |
| backend contract     |        | .wfrog + SVG         |
+----------+-----------+        +----------+-----------+
           |                               |
           v                               v
+----------------------+        +----------------------+
| LLVM backend         |        | UI host              |
| native artifact      |        | replaceable host     |
+----------+-----------+        +----------+-----------+
           |                               |
           +---------------+---------------+
                           |
                           v
                 +----------------------+
                 | runtime              |
                 | orchestration        |
                 | bindings             |
                 | scheduling           |
                 | diagnostics          |
                 +----------------------+

The diagram and computation branch is: 

.frog diagram
  -> loadability / structural validation
  -> semantic validation
  -> FIR / Execution IR
  -> lowering
  -> backend contract
  -> LLVM-oriented module or native loadable artifact where applicable
  -> runtime call/load boundary

The front-panel and widget branch is: 

.frog front_panel
  -> widget instances and diagram/widget bindings
  -> .wfrog packages or realization packages
  -> SVG/assets and realization resources
  -> host UI

The runtime joins those branches by consuming explicit published artifacts rather than by becoming the owner of language semantics. In the current reference corridor, runtime-family consumers may:

  • consume FIR, lowering artifacts, backend contracts, manifests, and realization package references,
  • load or call compiled artifacts where the backend contract and manifest declare such an artifact,
  • bind widget_value and widget_reference surfaces to execution-facing values, properties, or calls,
  • sample input widget values on Run/Execute where the example uses a run-on-demand host loop,
  • publish output values, property updates, events, snapshots, or diagnostics back to the host surface,
  • preserve source attribution and diagnostic recoverability where the FIR and downstream artifacts expose it.

LLVM remains one compiler-family proof path in this repository. It may consume lowered material to produce an LLVM-oriented module or native proof artifact, but it does not replace FIR, does not define FROG semantics, and does not make the runtime LLVM-specific.

Command

python Implementations/Reference/Pipeline/check_examples01_10_full.py

With native LLVM builds: 

python Implementations/Reference/Pipeline/check_examples01_10_full.py --include-llvm-build

To validate only the widget layer through the workspace entry point: 

python Implementations/Reference/check_reference_workspace.py --widget-layer-only

To skip widget validation for narrow debugging of unrelated stages: 

python Implementations/Reference/Pipeline/check_examples01_10_full.py --skip-widget-validator

Stage Order

  1. Artifact preflight for Examples 01-10.
  2. Widget-layer validation.
  3. .frog -> FIR for Examples 01-15.
  4. FIR -> lowering for Examples 01-15.
  5. lowering -> backend contract for Examples 01-04 through the shared contract emitter.
  6. lowering -> backend contract for Examples 05-15 through the host-runtime UI-binding contract emitter.
  7. contract -> runtime acceptance for the historical Examples 01-10 acceptance surface.
  8. lowering -> LLVM module for Examples 01-15.
  9. Optional native LLVM build proof.

Current Rule-Handoff Discipline

.frog source pattern
  -> FIR unit.kind
  -> lowered_unit.kind
  -> backend/runtime/LLVM consumers

The reference pipeline protects this handoff discipline by checking source-to-FIR derivation, FIR-to-lowering projection, backend-contract emission, runtime acceptance, and lowered-unit-kind LLVM module emission.

Widget-Layer Validation Scope

The widget-layer validation stage checks repository hygiene for:

  • widget class-law documents under Libraries/Widgets/,
  • Default realization documents under Libraries/Realizations/Default/,
  • *.default.wfrog manifests,
  • target class references,
  • resource references,
  • SVG data-frog-part markers,
  • public-part alignment,
  • part / property / method / event binding posture,
  • composition resource references,
  • host-native replacement boundaries.

Boundary

The pipeline is non-normative. It verifies published artifacts and implementation-stage coherence. It does not define the FROG language, widget semantics, realization semantics, runtime semantics, backend contract semantics, or compiler semantics.