diff --git a/docs/specs/runtime/02c-program-registry-and-pbx-v1.md b/docs/specs/runtime/02c-program-registry-and-pbx-v1.md index 926c8ef..f2ef1be 100644 --- a/docs/specs/runtime/02c-program-registry-and-pbx-v1.md +++ b/docs/specs/runtime/02c-program-registry-and-pbx-v1.md @@ -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. diff --git a/docs/specs/runtime/04-gfx-peripheral.md b/docs/specs/runtime/04-gfx-peripheral.md index 8f75102..d78c5ca 100644 --- a/docs/specs/runtime/04-gfx-peripheral.md +++ b/docs/specs/runtime/04-gfx-peripheral.md @@ -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 diff --git a/docs/specs/runtime/10-debug-inspection-and-profiling.md b/docs/specs/runtime/10-debug-inspection-and-profiling.md index 137beca..6ed93d4 100644 --- a/docs/specs/runtime/10-debug-inspection-and-profiling.md +++ b/docs/specs/runtime/10-debug-inspection-and-profiling.md @@ -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: diff --git a/docs/specs/runtime/11a-headless-automation-protocol.md b/docs/specs/runtime/11a-headless-automation-protocol.md index a4eb74f..fa8e0b1 100644 --- a/docs/specs/runtime/11a-headless-automation-protocol.md +++ b/docs/specs/runtime/11a-headless-automation-protocol.md @@ -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 diff --git a/docs/specs/runtime/15-asset-management.md b/docs/specs/runtime/15-asset-management.md index 43e6982..6c73891 100644 --- a/docs/specs/runtime/15-asset-management.md +++ b/docs/specs/runtime/15-asset-management.md @@ -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: diff --git a/docs/specs/runtime/16-host-abi-and-syscalls.md b/docs/specs/runtime/16-host-abi-and-syscalls.md index 206bab0..6308850 100644 --- a/docs/specs/runtime/16-host-abi-and-syscalls.md +++ b/docs/specs/runtime/16-host-abi-and-syscalls.md @@ -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 diff --git a/docs/specs/runtime/16a-syscall-policies.md b/docs/specs/runtime/16a-syscall-policies.md index 71e58c4..f6981c4 100644 --- a/docs/specs/runtime/16a-syscall-policies.md +++ b/docs/specs/runtime/16a-syscall-policies.md @@ -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 diff --git a/docs/specs/runtime/README.md b/docs/specs/runtime/README.md index 5be2e26..0e98295 100644 --- a/docs/specs/runtime/README.md +++ b/docs/specs/runtime/README.md @@ -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 diff --git a/docs/vm-arch/ARCHITECTURE.md b/docs/vm-arch/ARCHITECTURE.md index 349db59..1aec073 100644 --- a/docs/vm-arch/ARCHITECTURE.md +++ b/docs/vm-arch/ARCHITECTURE.md @@ -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. diff --git a/docs/vm-arch/registry-layout-evidence.md b/docs/vm-arch/registry-layout-evidence.md index 4fb223a..42bf6d2 100644 --- a/docs/vm-arch/registry-layout-evidence.md +++ b/docs/vm-arch/registry-layout-evidence.md @@ -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. diff --git a/docs/vm-arch/registry-producer-handoff.md b/docs/vm-arch/registry-producer-handoff.md index 0de5c70..d687030 100644 --- a/docs/vm-arch/registry-producer-handoff.md +++ b/docs/vm-arch/registry-producer-handoff.md @@ -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