Files
prometeu-studio/docs/vm-arch/README.md
T
bquarkz 71fb80efc3
Test / Tests and coverage occurred while executing withChecks step.
Intrepid/Prometeu/Studio/pipeline/head There was a failure building this commit
feat(studio): ship JavaFX 2 Play and delegate integration tooling
Launch the JavaFX 2 project shell on Java 25 with an interactive viewport,
managed Play lifecycle and project mutation guards. Preserve headless/MCP and
save compatibility, and qualify exact runtime executable bundles.
Separate unit JaCoCo gates from opt-in integration suites and use the internal
Pong fixture for the headless visual pilot.
Move maintenance and native conformance tools into tooling; retain the VS Code
extension and update current navigation links.

Validation: tooling make verify passed, including 1064 Studio unit tests,
JaCoCo thresholds and 22 headless integration tests.
2026-11-19 17:32:03 +00:00

63 lines
3.0 KiB
Markdown

# VM Architecture Mirror Policy
The Prometeu runtime repository is the normative authority for PBX binary
layout, Core ISA, loader behavior, verification, and PVM execution semantics.
The files in this directory are convenience mirrors for Studio-side compiler
and integration work; they are not an independent architectural authority.
Canonical runtime sources:
- `../runtime/docs/vm-arch/ARCHITECTURE.md`
- `../runtime/docs/vm-arch/ISA_CORE.md`
- `../runtime/docs/vm-arch/INTRINSICS.csv`
- `../runtime/docs/vm-arch/BUILTIN_CONSTANTS.csv`
When these mirrors are retained, an integration change that updates a canonical
runtime source MUST update the corresponding Studio mirror in the same logical
change. Verify synchronization from the Studio repository root with:
```bash
diff -u docs/vm-arch/ARCHITECTURE.md ../runtime/docs/vm-arch/ARCHITECTURE.md
diff -u docs/vm-arch/ISA_CORE.md ../runtime/docs/vm-arch/ISA_CORE.md
diff -u docs/vm-arch/INTRINSICS.csv ../runtime/docs/vm-arch/INTRINSICS.csv
diff -u docs/vm-arch/BUILTIN_CONSTANTS.csv ../runtime/docs/vm-arch/BUILTIN_CONSTANTS.csv
```
All four commands MUST exit successfully with no output before a change claims
that the mirrors are synchronized. If the runtime repository is not available
in the same checkout, synchronization evidence must be produced against the
canonical runtime revision before merging.
Compiler-owned transformation contracts remain under `docs/specs/compiler`.
Those specifications define `IRBackend -> IRVM -> PBX` emission, but they MUST
conform to the runtime-owned PBX and ISA contracts and MUST NOT redefine runtime
execution semantics.
## Catalog provenance
`runtime-catalog.properties` identifies the selected provider revision and hashes
of both CSVs. The compiler and PBS SDK package these artifacts with their own
resource namespaces. Catalog synchronization alone does not claim the other
architecture mirrors are synchronized or that all PBS facades are implemented.
Run the explicit source/exporter verification from the Studio root:
```sh
../tooling/.venv/bin/python ../tooling/scripts/runtime-catalog/verify.py --studio . --runtime ../runtime
```
This command requires a clean checkout of the recorded provider revision, compares
committed bytes and hashes, and runs its real catalog exporter parity test with
build output in a temporary directory. Missing or different evidence sources fail
explicitly. Ordinary builds and local catalog tests never invoke this command.
The manual port and consumer requirements are defined in
[Runtime catalog support](../specs/compiler/24.%20Runtime%20Catalog%20Support%20Specification.md).
The selected provider publishes intrinsic schema 2 (25 columns). Manual compiler
metadata must retain every nullable bit, invocation/scratch/context profile and
cost parameter, including entries without PBS source facades. Storage producer
qualification uses the minimal ISA: ARRAY_LEN and ARRAY_COPY remain; 0xA7, 0xA8,
0xAA and 0xAB are unsupported. Compiler/SDK conformance must be regenerated for
the selected revision rather than reusing evidence from earlier providers.