Skip to content

responsibilities.md

Latest commit

 

History

History
353 lines (272 loc) · 11.3 KB

responsibilities.md

File metadata and controls

353 lines (272 loc) · 11.3 KB

FROG logo

Reference Runtime Responsibilities

Ownership map for parent-level runtime-family material and language-specific runtime consumers in the non-normative FROG reference implementation
FROG — Free Open Graphical Language

Contents

1. Overview

This file explains responsibility boundaries inside: 

Implementations/Reference/Runtime/

The purpose of this file is not to restate language semantics. Its purpose is to make ownership explicit between:

  • parent-level runtime-family material,
  • the Python runtime consumer,
  • the Rust runtime consumer,
  • the C/C++ runtime consumer,
  • and the shared Example 05 corridor they are expected to consume.

This matters because the reference runtime is now visibly multi-language at repository level, but those language-specific consumers do not all own the same things and do not currently close the corridor at the same maturity level.

2. Why This File Exists

When a runtime family grows across several implementation languages, ambiguity appears easily:

  • parent-level helpers may be mistaken for the whole runtime,
  • one language realization may be mistaken for the definition of FROG,
  • rendered UI work may be mistaken for canonical widget law,
  • compiler-family work may be mistaken for runtime-family work.

This file exists to prevent those collapses. It keeps the ownership map explicit and makes the runtime-family corridor easier to audit.

3. Current Runtime-Family Scope

The first published runtime family is: 

reference_host_runtime_ui_binding

At the current repository state, the runtime-family directory contains:

  • parent-level runtime-family material,
  • a Python consumer family,
  • a Rust consumer family,
  • a C/C++ consumer family.

The corridor currently targeted most concretely is: 

Examples/05_bounded_ui_accumulator/

4. Parent-Level Ownership

The parent runtime directory owns:

  • the runtime-family posture for the reference runtime family,
  • parent-level explanations of accepted-contract execution,
  • parent-level shared helpers used by the bounded corridor,
  • parent-level coordination across runtime-language consumers,
  • the repository-visible reference point for the shared contract-driven corridor.

At parent level, the key responsibilities are:

  • make the backend-family consumer posture explicit,
  • state what all consumers are expected to preserve,
  • avoid turning one language-specific implementation into semantic truth,
  • keep contract-family expectations aligned across Python, Rust, and C/C++.

5. Parent-Level Non-Ownership

The parent runtime directory does not own:

  • the FROG language definition,
  • the canonical .frog source model,
  • the semantic acceptance boundary,
  • the FIR architecture,
  • the lowering boundary,
  • the backend contract emission boundary,
  • widget class law,
  • .wfrog package law,
  • the LLVM-oriented compiler-family path.

The parent directory is downstream from those layers. It consumes their outputs. It must not redefine them. 

validated meaning != runtime-family implementation
backend contract != runtime-private structures
reference runtime != universal FROG runtime

6. Python Consumer Responsibilities

The Python consumer currently has the most operational closure. Its responsibilities include:

  • consume the published Example 05 contract corridor,
  • provide direct contract-driven execution,
  • provide the first bounded rendered UI corridor,
  • load the example-local .wfrog package for the rendered slice,
  • preserve the same bounded accumulation behavior as the shared corridor,
  • preserve explicit widget-value and widget-reference behavior for the supported subset.

The Python consumer does not thereby become the owner of widget semantics. It remains only one consumer realization with the strongest current operational proof path.

7. Rust Consumer Responsibilities

The Rust consumer currently has the strongest secondary proof posture after Python. Its responsibilities include:

  • load and validate the published Example 05 contract,
  • preserve the same bounded execution behavior,
  • preserve the same final observable result,
  • make the Rust-side runtime split explicit through dedicated source files,
  • stay aligned with the same contract-family assumptions as Python.

At the current stage, its strongest proof surface remains test-driven. That is acceptable for the bounded corridor, but it is not yet the same thing as a fully polished example-facing runner posture.

8. C/C++ Consumer Responsibilities

The C/C++ consumer is now structurally present in the repository. Its responsibilities are:

  • provide a third language-level runtime-family consumer posture,
  • stay aligned with the same contract-family assumptions as Python and Rust,
  • preserve the same bounded Example 05 behavior,
  • make contract loading, execution, and UI binding boundaries explicit at header and source level,
  • close the same corridor without inventing a parallel semantic story.

At the current stage, the C/C++ consumer is structurally real but not yet operationally closed at the same example-facing level as Python.

9. Shared Runtime Obligations

All runtime-language consumers are expected to preserve the same shared obligations for the bounded corridor:

  • accept or reject the published contract explicitly,
  • preserve explicit-state meaning,
  • preserve bounded-loop meaning,
  • preserve public input and output binding obligations,
  • preserve indicator publication obligations,
  • preserve the bounded object-style UI interaction subset declared by the corridor,
  • reject unsupported operations explicitly rather than silently reinterpret them.

Private helper structures may differ. Observed contract behavior must not drift.

10. Example 05 Corridor Responsibilities

For Example 05, responsibility boundaries should be read as follows:

  • main.frog owns canonical program meaning and widget participation.
  • accumulator_panel.wfrog owns peripheral widget-oriented realization packaging.
  • main.fir.json owns example-local execution-facing readability.
  • main.lowering.json owns example-local lowered posture.
  • the emitted contract artifact owns the runtime-family handoff surface.
  • the runtime-family consumers own private execution of the accepted handoff surface.

That separation must remain recoverable in every runtime-language implementation.

11. Rendered UI Boundary

Rendered UI work belongs to the runtime-consumer realization layer, not to canonical language ownership.

Accordingly:

  • a rendered host window is a runtime-side proof surface,
  • widget private objects are runtime-private realization structures,
  • visual assets remain downstream realization resources,
  • rendered UI success does not redefine widget class law.

At the current repository state, the rendered-host proof path is strongest on the Python side. That does not make Python the owner of widget truth.

12. LLVM Boundary

The LLVM-oriented path belongs to a separate compiler-family corridor. It is downstream from FIR and lowering, but it is not part of the runtime-family ownership surface.

That means:

  • runtime-family consumers execute accepted backend contracts,
  • compiler-family consumers transform lowered artifacts toward native executables,
  • those two downstream families must remain conceptually separate even when they target the same example.

13. Design Rules

  • Keep parent-level runtime-family posture separate from language-specific consumer implementation details.
  • Keep one language realization from becoming semantic truth by convenience.
  • Keep rendered UI realization separate from widget class law.
  • Keep compiler-family LLVM work separate from runtime-family ownership.
  • Keep Example 05 corridor artifacts attributable to their proper upstream layers.
  • Prefer explicit rejection over silent reinterpretation when a consumer does not support a declared surface.

14. Summary

This file exists to make runtime-family ownership explicit inside the reference implementation. The parent runtime directory coordinates a shared contract-consumption posture. Python, Rust, and C/C++ are parallel consumers of that posture with different current maturity levels.

The key architectural rule is simple: 

shared corridor truth
    !=
one language-specific runtime implementation

That distinction is what keeps the runtime family modular, auditable, and aligned with the broader FROG architecture.