Skip to content

frogc.md

Latest commit

 

History

History
387 lines (296 loc) · 10.1 KB

frogc.md

File metadata and controls

387 lines (296 loc) · 10.1 KB

FROG logo

frogc Command Surface

Stage-aware command-line surface for the non-normative FROG reference pipeline
FROG — Free Open Graphical Language

Contents

1. Overview

frogc is the command-line surface of the non-normative FROG reference pipeline. Its purpose is to expose the published stage boundaries explicitly rather than hide them behind one opaque execution command.

The reference command shape is: 

frogc validate <file.frog>
frogc derive-ir <file.frog>
frogc lower <file.frog> [--backend-family <family_id>]
frogc emit-contract <file.frog> [--backend-family <family_id>]
frogc run <file.frog> [--backend-family <family_id>]

2. Status and Boundary

frogc is not a specification layer. It is a convenience surface over the reference implementation modules under: 

Implementations/Reference/

Accordingly, frogc must not:

  • become the owner of source validity,
  • become the owner of semantic truth,
  • replace the open FROG Execution IR,
  • replace backend contract emission with hidden runtime behavior.

3. Current Primary Example

The current primary reference example is: 

Examples/05_bounded_ui_accumulator/main.frog

This example is the current preferred anchor because it exercises, in one coherent corridor:

  • front-panel widgets,
  • widget_value,
  • widget_reference,
  • frog.ui.property_write,
  • canonical for_loop structure,
  • explicit local memory through frog.core.delay,
  • public output exposure,
  • and first end-to-end runtime execution posture.

4. Command Summary

# validate canonical source against the supported reference subset
frogc validate Examples/05_bounded_ui_accumulator/main.frog

# derive open execution-facing IR
frogc derive-ir Examples/05_bounded_ui_accumulator/main.frog

# lower for the selected backend family
frogc lower Examples/05_bounded_ui_accumulator/main.frog --backend-family llvm_cpu_v1

# emit the backend-facing contract
frogc emit-contract Examples/05_bounded_ui_accumulator/main.frog --backend-family llvm_cpu_v1

# execute through the reference runtime path
frogc run Examples/05_bounded_ui_accumulator/main.frog --backend-family llvm_cpu_v1

5. validate

The validate command checks whether the source belongs to the supported validated reference subset.

Typical responsibilities include:

  • top-level section validation,
  • interface validation,
  • front-panel widget validation,
  • presentation metadata validation,
  • diagram-node validation,
  • canonical for_loop structure validation,
  • explicit local-memory validation,
  • widget_reference and property-write validation.

Example: 

frogc validate Examples/05_bounded_ui_accumulator/main.frog

Expected output posture:

  • a validation artifact,
  • validated subset flags,
  • and explicit diagnostics if validation fails.

6. derive-ir

The derive-ir command derives an open execution-facing representation from the validated source.

For the current slice, the derived IR should preserve at least:

  • widget_value participation,
  • widget_reference participation,
  • frog.ui.property_write object intent,
  • canonical for_loop identity,
  • body-region structure,
  • explicit local memory,
  • public output attribution,
  • front-panel declarations as non-semantic UI metadata.

Example: 

frogc derive-ir Examples/05_bounded_ui_accumulator/main.frog

7. lower

The lower command specializes the open Execution IR for a selected backend family.

This step may:

  • specialize the loop representation,
  • specialize explicit state handling,
  • materialize UI-binding operations,
  • prepare backend-oriented assumptions,
  • but it must not collapse FROG itself into the backend family.

Example: 

frogc lower Examples/05_bounded_ui_accumulator/main.frog --backend-family llvm_cpu_v1

For the first executable slice, the lowered form should still preserve:

  • bounded loop identity,
  • explicit local memory,
  • natural UI value paths,
  • object-style UI write operations,
  • non-semantic front-face metadata preservation.

8. emit-contract

The emit-contract command emits the backend-facing handoff artifact consumed by a backend or runtime family.

This is the explicit downstream boundary after lowering. The emitted contract should remain attributable to:

  • the original source,
  • the selected backend family,
  • the preserved loop and state model,
  • the preserved UI participation model.

Example: 

frogc emit-contract Examples/05_bounded_ui_accumulator/main.frog --backend-family llvm_cpu_v1

For the current slice, the emitted contract should make explicit:

  • one bounded loop of five iterations,
  • one explicit local state cell initialized to zero,
  • one control input value,
  • one indicator output value,
  • one public output value,
  • minimal object-style UI writes for face_color,
  • and preserved non-semantic UI metadata.

9. run

The run command executes through the runtime-side consumption of the emitted or implied backend contract.

For the first executable slice, the conservative reference reading is:

  1. load source,
  2. validate,
  3. derive IR,
  4. lower,
  5. emit backend contract,
  6. prepare runtime-side execution,
  7. sample the control value,
  8. apply explicit UI property writes,
  9. run the bounded accumulation loop,
  10. publish the final indicator value,
  11. publish the same public output value.

Example: 

frogc run Examples/05_bounded_ui_accumulator/main.frog --backend-family llvm_cpu_v1

10. Backend-Family Selection

Backend-family selection is explicit whenever lowering, contract emission, or runtime execution depends on it.

The recommended first LLVM-oriented family id is: 

llvm_cpu_v1

This identifier means:

  • an LLVM-oriented downstream backend-family target,
  • not the definition of FROG,
  • not a replacement for open FROG IR,
  • not a collapse of backend contract into one private runtime implementation.

11. Artifact Visibility

A key role of frogc is artifact visibility. A user should be able to inspect the result of each stage rather than rely on hidden transitions.

At minimum, the current reference path should make visible:

  • validation result,
  • derived Execution IR,
  • lowered form,
  • backend contract,
  • runtime result.

12. Design Rules

  • Keep stage boundaries explicit.
  • Prefer inspectability over hidden convenience.
  • Fail explicitly when a stage is unsupported.
  • Do not silently bypass validation, derivation, lowering, or contract emission.
  • Keep the command surface small enough to audit.
  • Keep backend-family choice explicit when it matters.
  • Do not turn front-face metadata into hidden semantic law.

13. Summary

frogc is the visible command surface of the non-normative reference pipeline. Its job is to expose a small, stage-aware, inspectable corridor across:

  • validation,
  • Execution IR derivation,
  • lowering,
  • backend contract emission,
  • runtime execution.

For the current campaign, it should be centered primarily on: 

Examples/05_bounded_ui_accumulator/main.frog

That keeps the command surface aligned with the repository’s most important near-term proof target: one fully explicit executable vertical slice.