diff --git a/discussion/lessons/DSC-0058-program-registry-type-and-function-metadata/LSN-0059-registry-boundaries-and-owned-values.md b/discussion/lessons/DSC-0058-program-registry-type-and-function-metadata/LSN-0059-registry-boundaries-and-owned-values.md new file mode 100644 index 0000000..f29f047 --- /dev/null +++ b/discussion/lessons/DSC-0058-program-registry-type-and-function-metadata/LSN-0059-registry-boundaries-and-owned-values.md @@ -0,0 +1,119 @@ +--- +id: LSN-0059 +ticket: program-registry-type-and-function-metadata +title: Registry Boundaries and Owned Values +created: 2026-10-08 +tags: [vm, bytecode, registry, ownership, planning] +--- + +## Context + +DEC-0045, accepted from AGD-0061, established an image-owned Type/Function Registry, +typed signatures, PBX v1, compact stored values and bounded resource ownership. +PLN-0176 delivered the independent foundation and its sealed execution path. On +2026-10-08 the user corrected the plan's scope to its originating agenda and +closed that delivery. Coordinated production activation was explicitly received +as future-plan suggestions in AGD-0055. Closing this delivery does not mean the +old production loader or version-0 example generators were migrated. + +The normative reference is [Program Registry and PBX v1](../../../docs/specs/runtime/02c-program-registry-and-pbx-v1.md). +The [permanent handoff](../../../docs/vm-arch/registry-producer-handoff.md) records +delivered APIs, producer oracles and pending integration ownership. This lesson +explains published mechanisms; it does not define callable/capture policy. + +## Key Decisions and Published Patterns + +### Identity, Execution Width and Stored Layout Have Different Jobs + +A Registry TypeId identifies a semantic type within an image. Execution still +uses tagged Value slots; storage uses resolved size, alignment, defaults and +ownership maps. A vec2 occupies two Float execution slots and sixteen inline +array bytes. An array of Struct values holds generational references to objects. +Equal native carriers or names do not make semantic types equivalent. + +This separation avoids scalar boxing per array element while preserving simple +stack roots. A stored Dynamic slot is larger because it preserves the semantic +tag and payload ownership. + +### Publication Is an Ownership Boundary + +ValidatedProgramImage::load decodes under bounded work/capacity budgets, resolves +metadata, binds native calls and performs structural/height/type-flow verification +before publishing a shared image. Sessions retain the same immutable Registry, +code, constants and debug owners. Rejected loads restore provisional ownership +counters while attempted work remains charged. + +Conformance through that factory proves its behavior, but cannot prove that a +different production entry point already uses it. Keep activation distinct from +the provider API in handoff and validation evidence. + +### Complete Groups Prevent Partial Type Checks + +Typed CALL/RET/native entry validates ordered parameter/result groups, including +multi-slot values. A trait's receiver and ImplementationId are one group; a +Dynamic tag and payload are another. Validating only one carrier permits malformed +combinations to cross boundaries. Conservative verifier joins may produce Unknown; +runtime checks still validate complete groups before consuming operands or +publishing frames/results. + +### String Sharing Requires Domain Ownership + +Arc identity shares content, but an Arc alone does not explain which quota owns +it. Image constants and session-created strings have separate Weak ledgers. +Cloning within a domain preserves one allocation charge; equal independently +created content has independent ownership. Cross-session import copies and +accounts content in the destination domain. + +Native ValueSnapshot owners retain provenance after the VM closes, while +serialization exports ordinary values. A String field and direct Dynamic field +can share one allocation; removing one storage owner keeps its charge alive until +the last owner disappears and reconciliation releases it. Content reservations +and temporary/result coexistence precede materialization. + +### Dynamic Boxes Preserve Existing Receiver Identity + +Single-slot Dynamic payloads remain direct. Present multi-slot values use an +immutable, exact-width Value box with Registry identity and TypeId. Copies and +repacking share its handle. Typed-null traits allocate no box. A box is an internal +category rather than a user object or collection receiver. + +The real FRAME_SYNC test removes original receiver roots and retains the receiver +only through the operand-stack Dynamic pair and its trait box. Once unpack/POP +removes those roots, permitted GC invalidates both handles. Actual safepoint +execution proves more than constructing a box and checking its contents. + +## Evidence and Its Limits + +Independent literal PBX fixtures complement writer/reader roundtrips. The named +argument oracle evaluates y before x, records effect order 21, marshals x/y in +signature order and returns 1020. It checks runtime behavior without claiming an +external frontend implementation. + +Baseline dd35942 passed 899 workspace tests with zero failures and nine ignored +tests; the two new ignored probes were explicitly run in release. Ownership, +quota rollback, stale handles, exact diagnostics and decoded conversion costs +have focused evidence. [Technical measurements](../../../docs/vm-arch/registry-layout-evidence.md) +record native representation, load high-water capacity and dense/sparse GC behavior. +These observations do not establish process RSS, game headroom or long-run stability. + +## Pitfalls + +Plan ownership was initially mixed: production migration depended on a callable +contract assigned to another agenda, yet remained a completion gate of the +Registry plan. Moving only the callable opcode step left that dependency in loader +activation, producer regeneration and final audits. + +The correction preserves both facts: the foundation is delivered and integration +is pending with a named owner. It transfers exact targets and acceptance to +AGD-0055's future plan. It does not approve that agenda's proposal, weaken the +final PBX contract or label transferred code as executed. Other agendas retain +their own collection/string/stress/game obligations. + +## Takeaways + +- Keep each plan atomic to its originating agenda and identify integration ownership before execution. +- Distinguish validated publication APIs from activation of every production consumer. +- Treat semantic identity, execution carriers and compact storage as separate contracts. +- Preserve quota provenance for shared native owners and test release at the final owner. +- Use independent bytes and actual safepoints to substantiate boundary behavior. +- Close a user-corrected delivery with explicit handoff; future work belongs to its owner's plan. diff --git a/docs/vm-arch/ARCHITECTURE.md b/docs/vm-arch/ARCHITECTURE.md index 7ea575d..349db59 100644 --- a/docs/vm-arch/ARCHITECTURE.md +++ b/docs/vm-arch/ARCHITECTURE.md @@ -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. Production `initialize` and the existing example generators still await coordinated migration with the callable contract. 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. 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. diff --git a/docs/vm-arch/registry-layout-evidence.md b/docs/vm-arch/registry-layout-evidence.md index 8c5f8d2..4fb223a 100644 --- a/docs/vm-arch/registry-layout-evidence.md +++ b/docs/vm-arch/registry-layout-evidence.md @@ -92,6 +92,12 @@ 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 whole plan and final publication audit remain in progress. +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. -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 complete workflow closure is claimed by this report. +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. diff --git a/docs/vm-arch/registry-producer-handoff.md b/docs/vm-arch/registry-producer-handoff.md index 0cc5691..0de5c70 100644 --- a/docs/vm-arch/registry-producer-handoff.md +++ b/docs/vm-arch/registry-producer-handoff.md @@ -14,6 +14,30 @@ migration and both regenerated runtime examples remain pending. Existing closure receivers need the separate AGD-0055 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. + +| Original Registry steps | Pending integration owned by AGD-0055 | +| --- | --- | +| 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. | + +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. + The external Studio handoff targets are the build-pipeline `backend/bytecode/BytecodeModule.java` and `backend/irvm/IRVMIntrinsicRegistry.java`, compiler-core `source/tables/IntrinsicTableReader.java`, PBS