Skip to content

frogc.md

Latest commit

 

History

History
405 lines (313 loc) · 12.3 KB

frogc.md

File metadata and controls

405 lines (313 loc) · 12.3 KB

FROG logo

frogc

Reference pipeline entry point for the first bounded executable corridor in the non-normative FROG reference workspace
FROG — Free Open Graphical Language

Contents

1. Overview

frogc is the reference pipeline entry point of the non-normative FROG reference workspace. Its purpose is to expose one inspectable command-facing route through the currently published bounded executable corridor.

In the current published state, frogc should be understood first as the façade for the closed corridor centered on: 

Examples/05_bounded_ui_accumulator/

It is therefore not merely a generic future compiler name. It is the first command-facing entry point for a real repository-visible corridor from canonical source to emitted backend contract to reference runtime consumption.

2. Non-Normative Status

frogc is part of the non-normative reference implementation workspace. It is not the language definition. It is not the universal command-line interface for all future FROG implementations.

Its role is to orchestrate the reference stages that consume published specification layers without owning them. That keeps the ownership chain explicit: 

published specification layers
   -> define and bound meaning

frogc
   -> drives a reference-family executable corridor through explicit stages

3. Why frogc Exists

A stage-separated reference workspace benefits from one visible orchestration surface. Without that façade, the repository can still contain all the right stages while remaining harder to inspect as one coherent executable path.

frogc therefore exists to:

  • load canonical source,
  • drive bounded validation,
  • drive bounded Execution IR derivation,
  • drive backend-family lowering,
  • drive backend contract emission,
  • and optionally hand the emitted contract to a reference runtime consumer.

For the current closure target, its value is not breadth. Its value is that one reader can follow one small real corridor through one visible entry point.

4. Current Closure Target

The current closure target for frogc is the first bounded applicative corridor: 

Examples/05_bounded_ui_accumulator/

That example is the current anchor because it already combines:

  • front-panel value participation,
  • minimal object-style UI access,
  • bounded structured control,
  • explicit state,
  • public output publication,
  • a published backend contract artifact,
  • and published downstream reference runtime consumers.

Accordingly, the first serious reading of frogc is: 

frogc = reference driver for the first closed bounded corridor

It should not yet be described as a broadly closed front-end for arbitrary FROG programs if the workspace does not publish that broader support.

5. Architectural Position

canonical .frog source
      |
      v
Loader
      |
      v
Validator
      |
      v
Deriver
      |
      v
Lowerer
      |
      v
ContractEmitter
      |
      v
Runtime
      ^
      |
    frogc
(reference orchestration entry point)

The key rule is that frogc orchestrates the stages. It does not erase them. It does not collapse lowering, contract emission, and runtime into one hidden action with unclear boundaries.

6. First Supported Reading

In the current repository state, the first supported reading of frogc is conservative:

  • take one canonical source file for the bounded slice,
  • run the reference stages against the supported subset,
  • materialize the backend handoff artifact for the selected family,
  • and optionally pass that contract to a reference runtime family consumer.

The currently preferred family for that first closed corridor remains: 

reference_host_runtime_ui_binding

This is the family already used by the published contract artifact and the published reference runtime posture.

7. Published Corridor Anchor

The first published corridor that frogc should be understood to drive is: 

Examples/05_bounded_ui_accumulator/
      |
      v
Implementations/Reference/ContractEmitter/examples/
05_bounded_ui_accumulator.reference_host_runtime_ui_binding.contract.json
      |
      v
Implementations/Reference/Runtime/

That matters because frogc is no longer describing a purely hypothetical route. It can now be read against a source anchor, a published emitted contract, and published runtime-family consumers.

8. Recommended Stage Flow

The first bounded execution flow for frogc should be read as:

  1. load Examples/05_bounded_ui_accumulator/main.frog,
  2. validate the bounded supported subset,
  3. derive the open execution-facing representation,
  4. lower for reference_host_runtime_ui_binding,
  5. emit the backend contract artifact,
  6. optionally hand the emitted contract to a selected reference runtime realization,
  7. return explicit success, rejection, or failure with stage attribution.

If the contract is already published and selected directly, a runtime-facing entry may also start at the contract artifact rather than at canonical source. That does not change the ownership model. It only changes the entry stage.

9. Minimum Expected Behavior

For the current closure target, frogc should be expected to preserve at least:

  • the bounded loop identity,
  • the exact iteration count of five,
  • the explicit local-memory requirement,
  • the deterministic initial state of 0,
  • the sampled numeric control value as input,
  • the final public output publication,
  • the final indicator publication,
  • and the minimal object-style UI property-write surface for face_color.

For this first corridor, the relevant carried value domain is u16. The reference path driven by frogc should therefore remain coherent with a first bounded scalar surface that includes u16.

10. Explicit Non-Goals

At the current published stage, frogc does not need to claim:

  • full-language universal source support,
  • all widget families,
  • all property / method / event UI interaction forms,
  • all backend families,
  • all runtime families,
  • or universal deployment packaging.

Its current job is narrower and more important: to make the first closed bounded executable corridor explicit and inspectable.

11. Interface Shape

The exact CLI syntax may evolve. However, the command-facing contract of frogc should already distinguish clearly between:

  • source-oriented entry,
  • contract-emission entry,
  • and runtime-driving entry where that runtime handoff is explicitly requested.

A conservative conceptual shape is: 

frogc validate <program.frog>
frogc derive-ir <program.frog>
frogc lower --family reference_host_runtime_ui_binding <program.frog>
frogc emit-contract --family reference_host_runtime_ui_binding <program.frog>
frogc run --family reference_host_runtime_ui_binding <program.frog>
frogc run-contract <contract.json>

This is an interface posture, not a claim that every command is already implemented identically in the published workspace. The important point is that the stage boundaries remain legible.

12. Illustrative Command Posture

For the first closed corridor, the most important command-facing readings are: 

frogc emit-contract \
  --family reference_host_runtime_ui_binding \
  Examples/05_bounded_ui_accumulator/main.frog

frogc run \
  --family reference_host_runtime_ui_binding \
  Examples/05_bounded_ui_accumulator/main.frog

frogc run-contract \
  Implementations/Reference/ContractEmitter/examples/05_bounded_ui_accumulator.reference_host_runtime_ui_binding.contract.json

The third form is especially important for the current published state because the contract artifact is already repository-visible and the runtime-family consumers are already published against that handoff surface.

13. Error Posture

frogc should report failures with explicit stage attribution. A useful minimal model is:

  • load failure,
  • validate failure,
  • derive-ir failure,
  • lower failure,
  • emit-contract failure,
  • runtime-accept rejection,
  • run failure.

This matters because a closed corridor remains inspectable only if failures remain attributable rather than collapsing into one opaque “compile failed” message.

14. Multi-Runtime Posture

frogc must not collapse the language into one runtime realization. For the current corridor, the intended posture is:

  • one named source slice,
  • one emitted backend contract family,
  • one bounded execution meaning,
  • and more than one published downstream runtime consumer where available.

For the current published state, that means a Python consumer and a Rust consumer may both remain downstream of the same handoff surface. frogc should therefore be read as the driver of a corridor that stays open above runtime implementation language.

15. Summary

frogc is the reference orchestration entry point of the non-normative FROG reference workspace. Its current architectural value is not broad genericity. Its current value is that it can now be read against one materially closed bounded corridor.

That corridor is: 

Examples/05_bounded_ui_accumulator/
  -> ContractEmitter/examples/...contract.json
  -> Runtime/

Accordingly, frogc should now be described first as the command-facing façade of that first closed source-to-contract-to-runtime reference corridor, while keeping the stage boundaries and ownership boundaries explicit.