From 762f60e00fe7b914ace36d9dcdcc429314ea775b Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Mon, 20 Apr 2026 08:51:36 +0100 Subject: [PATCH] implement PLN-0035 spec wording for materialization --- discussion/index.ndjson | 2 +- ...ec-wording-for-materialization-vs-copy-pressure.md | 4 ++-- .../runtime/02a-vm-values-and-calling-convention.md | 11 +++++++++++ .../runtime/03-memory-stack-heap-and-allocation.md | 10 ++++++++++ .../runtime/10-debug-inspection-and-profiling.md | 9 +++++++++ 5 files changed, 33 insertions(+), 3 deletions(-) diff --git a/discussion/index.ndjson b/discussion/index.ndjson index 1b2e90cb..85c3808e 100644 --- a/discussion/index.ndjson +++ b/discussion/index.ndjson @@ -21,7 +21,7 @@ {"type":"discussion","id":"DSC-0026","status":"done","ticket":"render-all-scene-cache-and-camera-integration","title":"Integrate render_all with Scene Cache and Camera","created_at":"2026-04-14","updated_at":"2026-04-18","tags":["gfx","runtime","render","camera","scene"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0031","file":"lessons/DSC-0026-render-all-scene-cache-and-camera-integration/LSN-0031-frame-composition-belongs-above-the-render-backend.md","status":"done","created_at":"2026-04-18","updated_at":"2026-04-18"}]} {"type":"discussion","id":"DSC-0027","status":"done","ticket":"frame-composer-public-syscall-surface","title":"Agenda - FrameComposer Public Syscall Surface","created_at":"2026-04-17","updated_at":"2026-04-18","tags":["gfx","runtime","syscall","abi","frame-composer","scene","camera","sprites"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0032","file":"lessons/DSC-0027-frame-composer-public-syscall-surface/LSN-0032-public-abi-must-follow-the-canonical-service-boundary.md","status":"done","created_at":"2026-04-18","updated_at":"2026-04-18"}]} {"type":"discussion","id":"DSC-0028","status":"done","ticket":"deferred-overlay-and-primitive-composition","title":"Deferred Overlay and Primitive Composition over FrameComposer","created_at":"2026-04-18","updated_at":"2026-04-18","tags":["gfx","runtime","render","frame-composer","overlay","primitives","hud"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0033","file":"lessons/DSC-0028-deferred-overlay-and-primitive-composition/LSN-0033-debug-primitives-should-be-a-final-overlay-not-part-of-game-composition.md","status":"done","created_at":"2026-04-18","updated_at":"2026-04-18"}]} -{"type":"discussion","id":"DSC-0014","status":"in_progress","ticket":"perf-vm-allocation-and-copy-pressure","title":"Agenda - [PERF] VM Allocation and Copy Pressure","created_at":"2026-03-27","updated_at":"2026-04-20","tags":[],"agendas":[{"id":"AGD-0013","file":"workflow/agendas/AGD-0013-perf-vm-allocation-and-copy-pressure.md","status":"accepted","created_at":"2026-03-27","updated_at":"2026-04-20","_override_reason":"User explicitly requested emitting a decision from the resolved agenda in this turn."}],"decisions":[{"id":"DEC-0018","file":"workflow/decisions/DEC-0018-vm-allocation-and-copy-pressure-baseline.md","status":"in_progress","created_at":"2026-04-20","updated_at":"2026-04-20","ref_agenda":"AGD-0013","_override_reason":"User explicitly requested emitting and then accepting the decision, followed by plan generation."}],"plans":[{"id":"PLN-0033","file":"PLN-0033-vm-hot-path-ownership-and-string-copy-pressure.md","status":"done","created_at":"2026-04-20","updated_at":"2026-04-20","ref_decisions":["DEC-0018"]},{"id":"PLN-0034","file":"PLN-0034-internal-allocation-evidence-and-hot-path-measurement.md","status":"done","created_at":"2026-04-20","updated_at":"2026-04-20","ref_decisions":["DEC-0018"]},{"id":"PLN-0035","file":"PLN-0035-runtime-spec-wording-for-materialization-vs-copy-pressure.md","status":"review","created_at":"2026-04-20","updated_at":"2026-04-20","ref_decisions":["DEC-0018"]}],"lessons":[]} +{"type":"discussion","id":"DSC-0014","status":"in_progress","ticket":"perf-vm-allocation-and-copy-pressure","title":"Agenda - [PERF] VM Allocation and Copy Pressure","created_at":"2026-03-27","updated_at":"2026-04-20","tags":[],"agendas":[{"id":"AGD-0013","file":"workflow/agendas/AGD-0013-perf-vm-allocation-and-copy-pressure.md","status":"accepted","created_at":"2026-03-27","updated_at":"2026-04-20","_override_reason":"User explicitly requested emitting a decision from the resolved agenda in this turn."}],"decisions":[{"id":"DEC-0018","file":"workflow/decisions/DEC-0018-vm-allocation-and-copy-pressure-baseline.md","status":"in_progress","created_at":"2026-04-20","updated_at":"2026-04-20","ref_agenda":"AGD-0013","_override_reason":"User explicitly requested emitting and then accepting the decision, followed by plan generation."}],"plans":[{"id":"PLN-0033","file":"PLN-0033-vm-hot-path-ownership-and-string-copy-pressure.md","status":"done","created_at":"2026-04-20","updated_at":"2026-04-20","ref_decisions":["DEC-0018"]},{"id":"PLN-0034","file":"PLN-0034-internal-allocation-evidence-and-hot-path-measurement.md","status":"done","created_at":"2026-04-20","updated_at":"2026-04-20","ref_decisions":["DEC-0018"]},{"id":"PLN-0035","file":"PLN-0035-runtime-spec-wording-for-materialization-vs-copy-pressure.md","status":"done","created_at":"2026-04-20","updated_at":"2026-04-20","ref_decisions":["DEC-0018"]}],"lessons":[]} {"type":"discussion","id":"DSC-0015","status":"open","ticket":"perf-cartridge-boot-and-program-ownership","title":"Agenda - [PERF] Cartridge Boot and Program Ownership","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0014","file":"workflow/agendas/AGD-0014-perf-cartridge-boot-and-program-ownership.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]} {"type":"discussion","id":"DSC-0016","status":"done","ticket":"tilemap-empty-cell-vs-tile-id-zero","title":"Tilemap Empty Cell vs Tile ID Zero","created_at":"2026-03-27","updated_at":"2026-04-09","tags":[],"agendas":[{"id":"AGD-0015","file":"workflow/agendas/AGD-0015-tilemap-empty-cell-vs-tile-id-zero.md","status":"done","created_at":"2026-03-27","updated_at":"2026-04-09"}],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0022","file":"lessons/DSC-0016-tilemap-empty-cell-semantics/LSN-0022-tilemap-empty-cell-convergence.md","status":"done","created_at":"2026-04-09","updated_at":"2026-04-09"}]} {"type":"discussion","id":"DSC-0017","status":"done","ticket":"asset-entry-metadata-normalization-contract","title":"Asset Entry Metadata Normalization Contract","created_at":"2026-03-27","updated_at":"2026-04-09","tags":[],"agendas":[{"id":"AGD-0016","file":"workflow/agendas/AGD-0016-asset-entry-metadata-normalization-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-04-09"}],"decisions":[{"id":"DEC-0004","file":"workflow/decisions/DEC-0004-asset-entry-metadata-normalization-contract.md","status":"accepted","created_at":"2026-04-09","updated_at":"2026-04-09"}],"plans":[],"lessons":[{"id":"LSN-0023","file":"lessons/DSC-0017-asset-metadata-normalization/LSN-0023-typed-asset-metadata-helpers.md","status":"done","created_at":"2026-04-09","updated_at":"2026-04-09"}]} diff --git a/discussion/workflow/plans/PLN-0035-runtime-spec-wording-for-materialization-vs-copy-pressure.md b/discussion/workflow/plans/PLN-0035-runtime-spec-wording-for-materialization-vs-copy-pressure.md index 807d2f58..d25d43d7 100644 --- a/discussion/workflow/plans/PLN-0035-runtime-spec-wording-for-materialization-vs-copy-pressure.md +++ b/discussion/workflow/plans/PLN-0035-runtime-spec-wording-for-materialization-vs-copy-pressure.md @@ -2,9 +2,9 @@ id: PLN-0035 ticket: perf-vm-allocation-and-copy-pressure title: Plan - Runtime Spec Wording for Materialization vs Copy Pressure -status: review +status: done created: 2026-04-20 -completed: +completed: 2026-04-20 tags: [spec, runtime, memory, strings, perf] --- diff --git a/docs/specs/runtime/02a-vm-values-and-calling-convention.md b/docs/specs/runtime/02a-vm-values-and-calling-convention.md index da2efd9d..1be23abd 100644 --- a/docs/specs/runtime/02a-vm-values-and-calling-convention.md +++ b/docs/specs/runtime/02a-vm-values-and-calling-convention.md @@ -17,6 +17,17 @@ All runtime values are stored in VM slots as `Value`. | `bool` | Boolean value | | `float` | 64-bit floating point | +### String values + +PROMETEU supports string values in the VM language surface. + +String rules: + +- hardcoded strings may be materialized once during build/load through constant-pool-backed storage; +- runtime-created strings may materialize at the point where a new string value is semantically created; +- the public value model does not require repeated payload copies after first materialization; +- reducing repeated string copy pressure is an internal runtime concern and MUST NOT be interpreted as a guest-visible ABI distinction. + ### Built-in vector and graphics types These are treated as VM values with stable layout semantics. diff --git a/docs/specs/runtime/03-memory-stack-heap-and-allocation.md b/docs/specs/runtime/03-memory-stack-heap-and-allocation.md index 8f4ae92b..92a755e6 100644 --- a/docs/specs/runtime/03-memory-stack-heap-and-allocation.md +++ b/docs/specs/runtime/03-memory-stack-heap-and-allocation.md @@ -27,6 +27,7 @@ The stack stores transient execution values and frame-scoped data. The stack may contain: - primitive values; +- string values; - built-in fixed-layout values; - heap handles; - tuple-shaped multi-return values. @@ -155,6 +156,15 @@ Heap allocation conceptually performs: 2. create or reuse gate entry; 3. return validated handle. +First materialization cost is distinct from repeated hot-path copy pressure. + +Implications: + +- constant-pool-backed values may pay materialization cost before execution begins; +- runtime-created values may pay materialization cost when a new value is semantically produced; +- the runtime SHOULD minimize repeated implicit copying on hot paths after that first materialization; +- zero-allocation happy-path work is an engineering optimization target, not a published compatibility guarantee by itself. + If allocation fails: - the VM may trigger GC; diff --git a/docs/specs/runtime/10-debug-inspection-and-profiling.md b/docs/specs/runtime/10-debug-inspection-and-profiling.md index 4f140f23..1c656380 100644 --- a/docs/specs/runtime/10-debug-inspection-and-profiling.md +++ b/docs/specs/runtime/10-debug-inspection-and-profiling.md @@ -188,6 +188,15 @@ Limit:32KB These data feed host-owned certification. +The profiling boundary MUST distinguish public certification input from internal engineering evidence. + +In particular: + +- host-owned certification may consume stable runtime counters such as heap usage and GC-related pressure; +- internal counters for allocation events or string materialization may exist to guide implementation work; +- such internal counters MUST NOT be treated as a guest-visible certification promise unless a separate decision explicitly promotes them; +- zero-allocation happy-path goals remain internal engineering targets unless promoted to a public certification contract. + ### 7.1 Bank Occupancy Profiling Bank occupancy diagnostics are slot-first.