docs: replace ephemeral workflow references with durable lessons

This commit is contained in:
2026-10-08 08:34:32 +01:00
parent d48978988e
commit 8381800fce
11 changed files with 54 additions and 59 deletions
@@ -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.
+5 -4
View File
@@ -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
+4 -2
View File
@@ -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
+1 -1
View File
@@ -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
+2 -3
View File
@@ -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
+2 -2
View File
@@ -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.
+4 -10
View File
@@ -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.
+20 -28
View File
@@ -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