docs: replace ephemeral workflow references with durable lessons
This commit is contained in:
@@ -3,7 +3,9 @@
|
||||
Domain: VM program metadata, binary format, typed storage and resource boundaries
|
||||
Function: normative
|
||||
|
||||
This chapter publishes DEC-0045 through PLN-0176. It defines the required v1 contract; implementation is being migrated and this publication is not a claim that all execution paths already satisfy it. The callable/closure/coroutine type boundary remains separately specified: no provisional untyped reference type is authorized. Existing closure/coroutine behavior must be preserved until its approved replacement can be integrated.
|
||||
This chapter defines the required v1 contract; implementation is being migrated and this publication is not a claim that all execution paths already satisfy it. The callable/closure/coroutine type boundary remains separately specified: no provisional untyped reference type is authorized. Existing closure/coroutine behavior must be preserved until its approved replacement can be integrated.
|
||||
|
||||
Didactic companion: [Registry Boundaries and Owned Values](../../../discussion/lessons/DSC-0058-program-registry-type-and-function-metadata/LSN-0059-registry-boundaries-and-owned-values.md).
|
||||
|
||||
The requirements below use MUST/MUST NOT semantics. The Registry owns type/function identity, storage shapes and signatures; other chapters retain authority over scheduling, collection operations, cartridge boot and host ABI behavior outside these requirements.
|
||||
|
||||
|
||||
@@ -9,8 +9,7 @@ Didactic companion: [`../learn/mental-model-gfx.md`](../runtime/learn/mental-mod
|
||||
|
||||
The **GFX** peripheral is responsible for generating images in PROMETEU.
|
||||
|
||||
`DEC-0030` defines the current logical render boundary. PROMETEU render
|
||||
production is split from render implementation:
|
||||
PROMETEU logical render production is separate from render implementation:
|
||||
|
||||
```text
|
||||
domain buffers during logical frame
|
||||
@@ -121,8 +120,10 @@ This guarantees:
|
||||
|
||||
## 4. Asynchronous Render Boundary
|
||||
|
||||
`DEC-0031` defines the asynchronous render boundary. The contract applies even
|
||||
when the current implementation consumes submissions synchronously.
|
||||
The asynchronous render boundary applies even when the current implementation
|
||||
consumes submissions synchronously. [Render Workers Need a Closed Packet Contract](../../../discussion/lessons/DSC-0040-vm-render-parallel-execution-boundary/LSN-0048-render-workers-need-a-closed-packet-contract.md)
|
||||
explains the packet and ownership model; [Render Workers Publish Frames, Hosts Present Them](../../../discussion/lessons/DSC-0042-real-render-worker-establishment/LSN-0049-render-worker-publication-boundary.md)
|
||||
explains its worker/publication implementation.
|
||||
|
||||
### 4.1 Complete packet contract
|
||||
|
||||
|
||||
@@ -7,9 +7,9 @@ Didactic companion: [`../learn/mental-model-observability-and-debugging.md`](../
|
||||
|
||||
## 1 Scope
|
||||
|
||||
This chapter defines the machine-visible diagnostics and profiling surface of PROMETEU after `DEC-0009`.
|
||||
This chapter defines the machine-visible diagnostics and profiling surface of PROMETEU.
|
||||
|
||||
`DEC-0009` locks debug tooling and certification output as host-owned concerns. The runtime machine contract therefore exposes only bounded operational diagnostics and deterministic telemetry production, not a general-purpose guest-visible debug surface.
|
||||
Debug tooling and certification output are host-owned concerns. The runtime machine contract therefore exposes only bounded operational diagnostics and deterministic telemetry production, not a general-purpose guest-visible debug surface. The rationale is explained in [Host-Owned Debug Boundaries and Cheap Machine Diagnostics](../../../discussion/lessons/DSC-0012-perf-runtime-introspection-syscalls/LSN-0034-host-owned-debug-boundaries.md).
|
||||
|
||||
It covers:
|
||||
|
||||
|
||||
@@ -2,9 +2,11 @@
|
||||
|
||||
**Domain:** runtime host tooling. **Function:** normative.
|
||||
|
||||
This chapter implements Studio DSC-0068 / DEC-0060 baseline v1, runtime phase
|
||||
of PLN-0139. The host owns this wire contract. It does not change guest ABI,
|
||||
firmware, VM, frame/input semantics or the desktop DevTools protocol.
|
||||
This chapter defines the v1 automation wire contract owned by the headless host.
|
||||
It does not change guest ABI, firmware, VM, frame/input semantics or the desktop
|
||||
DevTools protocol.
|
||||
|
||||
The observation model is explained in [Deterministic Observation Must Follow the Active Producer](../../../discussion/lessons/DSC-0050-headless-automation-host-hardening/LSN-0058-deterministic-observation-must-follow-the-active-producer.md).
|
||||
|
||||
## Process and transport
|
||||
|
||||
|
||||
@@ -129,7 +129,7 @@ Even with `codec = NONE`, `GLYPH` still requires bank-specific decode from its s
|
||||
|
||||
#### 4.1.1 Metadata Normalization
|
||||
|
||||
Following `DEC-0004`, the `AssetEntry.metadata` field must be structured in segmented form to avoid ambiguity.
|
||||
The `AssetEntry.metadata` field must be structured in segmented form to avoid ambiguity. [Typed Helpers for Asset Metadata](../../../discussion/lessons/DSC-0017-asset-metadata-normalization/LSN-0023-typed-asset-metadata-helpers.md) explains the typed parsing pattern for this structure.
|
||||
|
||||
Required effective metadata fields for `GLYPH` at the root level:
|
||||
|
||||
@@ -281,9 +281,11 @@ Rules:
|
||||
- the visible contract MUST NOT expose byte-oriented bank occupancy as the canonical summary;
|
||||
- canonical bank names are `GLYPH` and `SOUNDS`;
|
||||
- detailed occupancy inspection remains host-owned and slot-based through slot references, not bank byte totals;
|
||||
- public runtime specs MUST NOT treat `bank.slot_info` or JSON bank inspection payloads as the long-term guest ABI after `DEC-0009`;
|
||||
- public runtime specs MUST NOT treat `bank.slot_info` or JSON bank inspection payloads as the long-term guest ABI;
|
||||
- any residual byte accounting MAY exist internally, but it is not part of the visible bank telemetry contract.
|
||||
|
||||
The rationale for this boundary is explained in [Host-Owned Debug Boundaries and Cheap Machine Diagnostics](../../../discussion/lessons/DSC-0012-perf-runtime-introspection-syscalls/LSN-0034-host-owned-debug-boundaries.md).
|
||||
|
||||
## 6 Load Lifecycle
|
||||
|
||||
The runtime asset manager exposes a staged lifecycle:
|
||||
|
||||
@@ -15,7 +15,7 @@ It focuses on:
|
||||
|
||||
Operational policies such as capabilities, fault classes, determinism, GC interaction, budgeting, and blocking are split into a companion chapter.
|
||||
|
||||
Per `DEC-0009`, debug tooling and certification are host-owned concerns. This chapter therefore excludes general-purpose guest-visible debug syscalls from the canonical public ABI.
|
||||
Debug tooling and certification are host-owned concerns. This chapter therefore excludes general-purpose guest-visible debug syscalls from the canonical public ABI. The rationale is explained in [Host-Owned Debug Boundaries and Cheap Machine Diagnostics](../../../discussion/lessons/DSC-0012-perf-runtime-introspection-syscalls/LSN-0034-host-owned-debug-boundaries.md).
|
||||
|
||||
## 1 Design Principles
|
||||
|
||||
@@ -246,7 +246,7 @@ ordering model.
|
||||
|
||||
### Bank diagnostics surface (`bank`, v1)
|
||||
|
||||
`DEC-0009` narrows the public bank contract:
|
||||
The public bank contract is bounded:
|
||||
|
||||
- `bank.info(bank_type) -> (used_slots, total_slots)` is the only surviving public bank diagnostic shape in v1;
|
||||
- `bank.info` exists only as a cheap deterministic operational summary aligned with the slot-first bank telemetry contract from [`15-asset-management.md`](15-asset-management.md);
|
||||
@@ -256,10 +256,13 @@ ordering model.
|
||||
|
||||
### Render surfaces (`composer`, `gfx2d`, `gfxui`, v1)
|
||||
|
||||
`DEC-0030` splits logical render production from render implementation. Public
|
||||
Logical render production is separate from render implementation. Public
|
||||
render syscalls mutate app-mode-specific domain buffers. They do not directly
|
||||
publish a framebuffer and do not call host presentation APIs.
|
||||
|
||||
[Render Workers Publish Frames, Hosts Present Them](../../../discussion/lessons/DSC-0042-real-render-worker-establishment/LSN-0049-render-worker-publication-boundary.md)
|
||||
explains the ownership and publication model.
|
||||
|
||||
The canonical flow is:
|
||||
|
||||
```text
|
||||
|
||||
@@ -9,7 +9,7 @@ It complements [`16-host-abi-and-syscalls.md`](16-host-abi-and-syscalls.md), whi
|
||||
|
||||
Unless a domain chapter explicitly narrows behavior further, this chapter is the transversal policy for all syscalls in v1.
|
||||
|
||||
Per `DEC-0009`, guest-visible syscalls must not exist merely for debug convenience or certification plumbing. Those concerns belong to host-owned tooling.
|
||||
Guest-visible syscalls must not exist merely for debug convenience or certification plumbing. Those concerns belong to host-owned tooling, as explained in [Host-Owned Debug Boundaries and Cheap Machine Diagnostics](../../../discussion/lessons/DSC-0012-perf-runtime-introspection-syscalls/LSN-0034-host-owned-debug-boundaries.md).
|
||||
|
||||
## 1 Error Model: Faults vs Status Returns
|
||||
|
||||
|
||||
@@ -23,9 +23,8 @@ Does not belong in `docs/specs/runtime/` as the primary canonical source:
|
||||
- bytecode-level ISA:
|
||||
[`../virtual-machine/ISA_CORE.md`](../../vm-arch/ISA_CORE.md);
|
||||
- pedagogical guides and learning material:
|
||||
[`../learn/README.md`](../runtime/learn/README.md);
|
||||
- agendas, proposals, and plans:
|
||||
`discussion/workflow/agendas/`, `discussion/workflow/decisions/` and `discussion/workflow/plans/`.
|
||||
[`../learn/README.md`](../runtime/learn/README.md) and
|
||||
[published lessons](../../../discussion/lessons/).
|
||||
|
||||
## Organization Rules
|
||||
|
||||
|
||||
@@ -15,7 +15,7 @@ Document roles:
|
||||
|
||||
- This file is normative for VM/runtime architecture.
|
||||
- Detailed domain specifications may live under `docs/runtime/specs/`, but they must not contradict this document where VM/runtime invariants are concerned.
|
||||
- Roadmaps, agendas, and PR proposals may discuss future changes, but they are not authoritative until this document is updated.
|
||||
- Future architectural changes become authoritative when this document is updated.
|
||||
- The machine-wide fantasy console framing lives in the runtime specs manual and related domain specs; those documents are complementary, not competing VM architecture sources.
|
||||
|
||||
Maintenance rule:
|
||||
@@ -188,4 +188,4 @@ The verifier statically checks bytecode for structural safety and stack‑shape
|
||||
|
||||
The [Program Registry contract](../specs/runtime/02c-program-registry-and-pbx-v1.md) defines immutable image-owned Type/Function metadata linked by dense IDs. Descriptors are native metadata outside guest GC; nominal identity does not depend on names. Stack/local execution retains Value, while typed storage uses resolved aligned layouts. PBX v1 is the sole target format; publication requires full bounded validation. Callable/closure/coroutine typed integration awaits its separate contract and must preserve existing behavior until then.
|
||||
|
||||
`ValidatedProgramImage::load` publishes a shared image only after bounded decoding, native binding and Registry verification; `VirtualMachine::from_image` creates sessions that consume its typed signatures, constants and conversion instructions. The independent Registry delivery is closed. Production `initialize` and the existing example generators remain pending integration in AGD-0055's future plan, after its callable contract is accepted. The [producer handoff](registry-producer-handoff.md) documents schema, input IDs and named-argument order, while [layout evidence](registry-layout-evidence.md) records reproducible load/access/GC measurements and the current publication boundary.
|
||||
`ValidatedProgramImage::load` publishes a shared image only after bounded decoding, native binding and Registry verification; `VirtualMachine::from_image` creates sessions that consume its typed signatures, constants and conversion instructions. Production `initialize` and the existing example generators remain pending coordinated migration that preserves typed callable behavior. [Registry Boundaries and Owned Values](../../discussion/lessons/DSC-0058-program-registry-type-and-function-metadata/LSN-0059-registry-boundaries-and-owned-values.md) explains the published mechanisms. The [producer handoff](registry-producer-handoff.md) documents schema, input IDs and named-argument order, while [layout evidence](registry-layout-evidence.md) records reproducible load/access/GC measurements and the current publication boundary.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Registry layout, load and GC evidence
|
||||
|
||||
This report records bounded technical fixtures for DEC-0045 / PLN-0176 step 35. The normative contract is [Program Registry and PBX v1](../specs/runtime/02c-program-registry-and-pbx-v1.md); producer obligations and publication status are in the [producer handoff](registry-producer-handoff.md).
|
||||
This report records bounded technical fixtures for Registry layout, loading and GC. The normative contract is [Program Registry and PBX v1](../specs/runtime/02c-program-registry-and-pbx-v1.md); producer obligations and publication status are in the [producer handoff](registry-producer-handoff.md). [Registry Boundaries and Owned Values](../../discussion/lessons/DSC-0058-program-registry-type-and-function-metadata/LSN-0059-registry-boundaries-and-owned-values.md) explains the published mechanisms.
|
||||
|
||||
Measured on 2026-10-07: Darwin arm64, Rust 1.98.1 (`48a229cea`), host `aarch64-apple-darwin`, LLVM 22.1.8, optimized Cargo release profile. The code baseline is `c6fff08`; this report's commit also contains the load high-water instrumentation and measurement fixtures. Wall-clock values are single observations, not thresholds or statistically established throughput. No timing assertion is used.
|
||||
|
||||
@@ -13,7 +13,7 @@ cargo test -p prometeu-vm --release --lib decoded_trait_box_is_the_only_receiver
|
||||
cargo test -p prometeu-vm --lib ownership_tests --quiet
|
||||
```
|
||||
|
||||
The first probe compares ownership-map traversal with a synthetic bitmap. The second executes complete sealed-image loading, typed-array allocation/access, object tracing and native-owner cleanup. Its tests run sequentially. Fixtures construct internal typed containers because guest collection allocation/read/write operations belong to AGD-0054. No new collection instruction or cost is inferred from native helper timings.
|
||||
The first probe compares ownership-map traversal with a synthetic bitmap. The second executes complete sealed-image loading, typed-array allocation/access, object tracing and native-owner cleanup. Its tests run sequentially. Fixtures construct internal typed containers; guest collection allocation/read/write operations are outside the measured instruction surface. No new collection instruction or cost is inferred from native helper timings.
|
||||
|
||||
## Native representation and typed-array access
|
||||
|
||||
@@ -92,12 +92,6 @@ The native fixture stores one session-imported 13-byte String in both a String f
|
||||
|
||||
## Publication boundary
|
||||
|
||||
The sealed v1 image, bounded verifier, typed direct calls, Dynamic/reference execution, metered native strings and structured host diagnostics have executable evidence. Production `VirtualMachine::initialize` still uses the old loader, and existing generators still emit version 0. Their coordinated migration must preserve existing closures and awaits AGD-0055's callable contract; the producer handoff records that dependency.
|
||||
The sealed v1 image, bounded verifier, typed direct calls, Dynamic/reference execution, metered native strings and structured host diagnostics have executable evidence. Production `VirtualMachine::initialize` still uses the old loader, and existing generators still emit version 0. Their coordinated migration must preserve existing closures and requires a typed callable contract; the producer handoff records pending implementation targets and validation requirements.
|
||||
|
||||
The independent Registry delivery was closed by the user's scope correction on
|
||||
2026-10-08. Production activation and its final audit are received as future-plan
|
||||
suggestions in AGD-0055, with targets and acceptance in the permanent handoff.
|
||||
They remain pending; the callable proposal is unaccepted. This delivery no longer
|
||||
waits for another agenda's closure.
|
||||
|
||||
These measurements cover bounded layout/load/access/ownership/GC behavior. Representative-game capacity and headroom belong to AGD-0060; coordinated long-run stress belongs to AGD-0059. No external compiler implementation, cross-host stress acceptance, regenerated production PBX smoke or final production activation is claimed by this report.
|
||||
These measurements cover bounded layout/load/access/ownership/GC behavior. Representative-game capacity/headroom and coordinated long-run stress require separate workloads and evidence. No external compiler implementation, cross-host stress acceptance, regenerated production PBX smoke or final production activation is claimed by this report.
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
# Registry v1 producer and consumer handoff
|
||||
|
||||
This is an implementation handoff for DEC-0045 / PLN-0176. The normative contract
|
||||
This document describes the Registry v1 producer and consumer interfaces. The normative contract
|
||||
is [Program Registry and PBX v1](../specs/runtime/02c-program-registry-and-pbx-v1.md).
|
||||
It does not approve the separate callable proposal or claim Studio propagation.
|
||||
The rationale and published mechanisms are explained in [Registry Boundaries and Owned Values](../../discussion/lessons/DSC-0058-program-registry-type-and-function-metadata/LSN-0059-registry-boundaries-and-owned-values.md).
|
||||
|
||||
## Publication state
|
||||
|
||||
@@ -11,32 +11,24 @@ session factory, typed direct-call/return boundaries, Dynamic/reference executio
|
||||
fixed input catalogue and string accounting have executable tests. The production
|
||||
`initialize` transition, removal of old unchecked entry points, all producer
|
||||
migration and both regenerated runtime examples remain pending. Existing closure
|
||||
receivers need the separate AGD-0055 contract; none of the four accepted Registry
|
||||
receivers need a typed callable contract; none of the four accepted Registry
|
||||
categories may be used as a provisional closure type.
|
||||
|
||||
On 2026-10-08 the user closed the independent AGD-0061 / PLN-0176 delivery and
|
||||
required each plan to be atomic to its originating agenda. Coordinated activation
|
||||
and its producer/example audits were handed to AGD-0055 as suggestions for its
|
||||
future plan. The Registry delivery ends without requiring that agenda to close
|
||||
first. The final v1-only target remains normative; integration below is unexecuted.
|
||||
This scope correction does not accept a callable proposal.
|
||||
### Pending production integration
|
||||
|
||||
| Original Registry steps | Pending integration owned by AGD-0055 |
|
||||
| Component | Pending implementation and validation |
|
||||
| --- | --- |
|
||||
| 09 / 14 | Switch production initialize to the sealed strict v1 factory; retire old decoder and unchecked entry points while preserving approved callable behavior. |
|
||||
| 19 | Complete image/constant provenance on migrated production entry points using the delivered ledgers and native retention domains. |
|
||||
| 24 / 25 | Route production loads through bounded Registry verification; remove the old verifier while adding the callable contract's checks. |
|
||||
| 28 | Audit structured load/runtime/native diagnostics through the final active loader and hosts. |
|
||||
| 29 / 30 | Migrate producers/fixtures, regenerate dummy-boy and stress-console PBX files, and execute both through the active runtime. These generators are ordinary programs sharing the production consumer being migrated. |
|
||||
| 31 / 32 | Add migrated producer/example/callable evidence to this handoff and the existing conformance matrix. |
|
||||
| 35 | Audit final coordinated publication, legacy removal, traceability and migrated workspace/examples. |
|
||||
| Loader and image | Switch production initialize to the sealed strict v1 factory; retire old decoder and unchecked entry points while preserving typed callable behavior. |
|
||||
| Constant ownership | Complete image/constant provenance on migrated production entry points using the delivered ledgers and native retention domains. |
|
||||
| Verification | Route production loads through bounded Registry verification; remove the old verifier while adding typed callable checks. |
|
||||
| Diagnostics | Audit structured load/runtime/native diagnostics through the final active loader and hosts. |
|
||||
| Producers and examples | Migrate producers/fixtures, regenerate dummy-boy and stress-console PBX files, and execute both through the active runtime. These generators are ordinary programs sharing the production consumer being migrated. |
|
||||
| Conformance | Add migrated producer/example/callable evidence to this handoff and the existing conformance matrix. |
|
||||
| Publication | Audit final coordinated publication, legacy removal, traceability and migrated workspace/examples. |
|
||||
|
||||
AGD-0055 records concrete targets and acceptance for this handoff. Its future plan
|
||||
follows its own accepted decision and reuses the Registry foundation. Guest
|
||||
collection operations stay with AGD-0054, new strings/bytes/save with AGD-0057,
|
||||
coordinated stress with AGD-0059 and representative-game headroom with AGD-0060.
|
||||
The [delivery lesson](../../discussion/lessons/DSC-0058-program-registry-type-and-function-metadata/LSN-0059-registry-boundaries-and-owned-values.md)
|
||||
explains published mechanisms and the scope correction.
|
||||
This integration reuses the delivered Registry foundation. Guest collection
|
||||
operations, new strings/bytes/save APIs, coordinated stress and representative-game
|
||||
headroom each require their own technical contract or validation workload.
|
||||
|
||||
The external Studio handoff targets are the build-pipeline
|
||||
`backend/bytecode/BytecodeModule.java` and `backend/irvm/IRVMIntrinsicRegistry.java`,
|
||||
@@ -138,11 +130,11 @@ human wording or manufacture runtime PCs for rejected loads.
|
||||
| Consumer | Accepted handoff | Status / remaining ownership |
|
||||
| --- | --- | --- |
|
||||
| Studio/PBS | PBX schema, signatures/names, effect-order and binary oracles, nine imports, all input IDs and diagnostics | External implementation and source-language tests pending; no external edits claimed |
|
||||
| AGD-0054 collections | Typed aligned layouts/defaults, exact storage groups, reference/native maps and checked adapters | Internal containers are tested; future guest collection operations/costs/GC integration belong to its decision/plan |
|
||||
| AGD-0055 callables | Function/implementation tables and direct-call contracts; exact trait views | Open Callable/capture/dispatch/coroutine contract; affected producer migration remains dependent on it |
|
||||
| AGD-0057 strings/bytes/save | Arc strings, image/session Weak ledgers, bounded native writers and explicit import/export provenance | Existing string paths are integrated; new operations and their operation-specific evidence remain suggestions |
|
||||
| AGD-0059 stability | Product ceilings, generational handles, fallible capacity reservations and structured faults | Focused ownership/quota rollback is core evidence; coordinated long-run/cross-host stress remains a suggestion |
|
||||
| AGD-0060 reference game | Runtime contract, example migration requirement and technical measurements | Game workload/headroom/readiness acceptance remains a suggestion, not measured by unit tests |
|
||||
| Collections | Typed aligned layouts/defaults, exact storage groups, reference/native maps and checked adapters | Internal containers are tested; guest collection operations/costs/GC integration require a complete operation contract |
|
||||
| Callables | Function/implementation tables and direct-call contracts; exact trait views | Callable/capture/dispatch/coroutine semantics and coordinated producer migration remain pending |
|
||||
| Strings/bytes/save | Arc strings, image/session Weak ledgers, bounded native writers and explicit import/export provenance | Existing string paths are integrated; new operations and their operation-specific evidence remain pending |
|
||||
| Resource stability | Product ceilings, generational handles, fallible capacity reservations and structured faults | Focused ownership/quota rollback is core evidence; coordinated long-run/cross-host stress requires separate workloads |
|
||||
| Reference game | Runtime contract, example migration requirement and technical measurements | Game workload/headroom/readiness requires representative-game evidence, not unit test counts |
|
||||
|
||||
Image constant allocations are shared between sessions without a session-content
|
||||
charge. New/imported runtime allocations belong to their session; equal text does
|
||||
|
||||
Reference in New Issue
Block a user