Skip to content

Readme.md

Latest commit

 

History

History
192 lines (145 loc) · 6.31 KB

Readme.md

File metadata and controls

192 lines (145 loc) · 6.31 KB
Raw

Reference Runtime (Python)

Python realization of the published reference_host_runtime_ui_binding family.

Repository governance and publication state are centralized in Versioning/Readme.md.

Directory navigation

Implementations/Reference/Runtime/python/
├── Readme.md
├── __init__.py
├── cli.py
├── execute_contract.py
├── run_slice05_ui.py
├── runtime_core.py
├── ui_runtime.py
└── tests/
    ├── test_runtime_slice05.py
    └── test_runtime_ui_slice05.py

Generated cache directories such as tests/__pycache__/ are not part of the intended source surface of this runtime and should not be versioned.

Role

This directory contains the Python consumer for the published Example 05 runtime corridor. It accepts the emitted backend contract, loads the published .wfrog package, resolves the referenced SVG assets, executes the bounded kernel, and can expose the panel through a minimal browser-host UI.

This directory is downstream from: 

main.frog
  -> main.fir.json
  -> main.lowering.json
  -> reference_host_runtime_ui_binding contract

It is not a source parser, not a lowering stage, and not a language-definition layer.

Current published entry points

cli.py

The main entry point for this directory. It exposes two modes:

  • run — headless contract + .wfrog execution.
  • ui — browser-host UI service for the same runtime core.

Examples from the repository root:

python -m Implementations.Reference.Runtime.python.cli run 3
python -m Implementations.Reference.Runtime.python.cli ui
python -m Implementations.Reference.Runtime.python.cli ui --host 127.0.0.1 --port 8080 --no-open-browser

run_slice05_ui.py

Convenience wrapper that starts the same browser-host UI path as cli.py ui. It is still useful as a small example-specific launcher, but cli.py is the primary surface.

execute_contract.py and runtime_core.py

These files hold the actual execution path. The current runtime core validates the bounded Example 05 contract and package shape, then produces a runtime result artifact.

ui_runtime.py

Browser-host realization for the same runtime core. The published tests exercise HTML rendering and the JSON snapshot endpoint.

Current bounded surface

The Python runtime is intentionally strict. The currently published bounded surface is:

  • backend family reference_host_runtime_ui_binding,
  • one contract unit named main,
  • one public input input_value : u16,
  • one public output result : u16,
  • one explicit state carrier based on frog.core.delay,
  • exactly five loop iterations,
  • two widget classes: frog.widgets.numeric_control and frog.widgets.numeric_indicator,
  • five supported widget properties: value, label, visible, enabled, and foreground_color,
  • two bounded method accepts: ctrl_input.focus and ind_result.reset_to_default_style.

The current accepted slice also requires widget-value and widget-reference binding support for the published members it consumes. The Python runtime reads those requirements from the emitted contract and the accepted package shape before execution begins.

Inputs and outputs

Inputs

  • The emitted contract artifact under Implementations/Reference/ContractEmitter/examples/.
  • The Example 05 package Examples/05_bounded_ui_accumulator/ui/accumulator_panel.wfrog.
  • The SVG assets referenced by that package.
  • The shared acceptance reading posture under Implementations/Reference/Runtime/acceptance/.

Outputs

  • A headless runtime result artifact.
  • A browser-host page driven by the same runtime core.
  • A runtime snapshot JSON surface for the accepted Example 05 slice.

Acceptance-driven tests

From the repository root: 

python -m pytest Implementations/Reference/Runtime/python/tests/test_runtime_slice05.py
python -m pytest Implementations/Reference/Runtime/python/tests/test_runtime_ui_slice05.py

The published Python tests are acceptance-driven and should remain aligned with Implementations/Reference/Runtime/acceptance/Readme.md.

  • test_runtime_slice05.py checks headless acceptance for the bounded runtime corridor.
  • test_runtime_ui_slice05.py checks browser-host HTML rendering and snapshot acceptance for the same corridor.

Legacy pre-acceptance smoke tests should not be kept in parallel once the acceptance-driven line is the published source of truth.

Relationship to the other runtime consumers

This directory should remain aligned with the Rust and C/C++ consumers on:

  • contract acceptance,
  • package acceptance,
  • execution semantics for the bounded accumulator slice,
  • the minimal widget-property surface,
  • the browser-host UI shape for Example 05,
  • the shared acceptance artifacts for the runtime family.

The parent runtime-family definition is documented in Implementations/Reference/Runtime/Readme.md.

Non-goals

  • General runtime support for arbitrary contracts.
  • Widget-law ownership.
  • Compiler-family responsibilities.
  • Native compiled UI closure.

Summary

Read this directory as the Python consumer of the current runtime family: 

contract + .wfrog + SVG assets
=> Python runtime core
=> headless result or browser-host UI