From 9b65005ffb10ac7a8f4c74724065773816af06e0 Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Wed, 11 Mar 2026 06:42:14 +0000 Subject: [PATCH] implements PR-011a assets.pa spec propagation --- docs/runtime/specs/13-cartridge.md | 46 ++++++++++-- docs/runtime/specs/15-asset-management.md | 86 ++++++++++++++++++++--- 2 files changed, 115 insertions(+), 17 deletions(-) diff --git a/docs/runtime/specs/13-cartridge.md b/docs/runtime/specs/13-cartridge.md index c3d8fb57..d2a42de0 100644 --- a/docs/runtime/specs/13-cartridge.md +++ b/docs/runtime/specs/13-cartridge.md @@ -36,8 +36,6 @@ The runtime currently expects the following manifest fields: Additional manifest-supported fields include: - `capabilities` -- `asset_table` -- `preload` ## 3 Required Fields @@ -68,6 +66,7 @@ The current loader validates: - manifest parse validity - capability normalization - presence of `program.pbx` +- when `Asset` capability is declared, presence of valid `assets.pa` before asset bootstrap If validation fails, cartridge loading is rejected before execution. @@ -82,12 +81,45 @@ If validation fails, cartridge loading is rejected before execution. ## 6 Assets and Preload -If present, the manifest may provide: +`assets.pa` is the runtime-facing asset artifact consumed by the current runtime. -- `asset_table`: runtime asset descriptors; -- `preload`: initial residency requests. +`assets.pa` v1 is an autocontained binary with: -If `assets.pa` exists, its bytes become the cartridge asset payload used by the asset manager during cartridge initialization. +- fixed binary prelude; +- JSON header; +- binary payload region. + +The fixed prelude includes, at minimum: + +- `magic` +- `schema_version` +- `header_len` +- `payload_offset` + +It may additionally include: + +- `flags` +- `reserved` +- `header_checksum` + +The JSON header carries: + +- `asset_table` +- `preload` + +`asset_table` and `preload` are therefore no longer the primary runtime contract of `manifest.json`. + +Runtime lifecycle: + +- `asset_table` is loaded from `assets.pa` and remains live while the cartridge is running; +- `preload` is loaded from `assets.pa`, consumed during cartridge initialization, and may be discarded after boot; +- payload bytes are resolved from the payload region using offsets relative to `payload_offset`. + +Runtime loading policy: + +- cartridges without `assets.pa` remain valid when `Asset` capability is not declared; +- cartridges that declare `Asset` capability must provide valid `assets.pa`; +- failure must occur as early as cartridge bootstrap, before preload execution. ## 7 Runtime Forms @@ -108,4 +140,4 @@ The cartridge spec therefore distinguishes: - [`12-firmware-pos-and-prometeuhub.md`](12-firmware-pos-and-prometeuhub.md) defines how firmware consumes cartridge metadata. - [`14-boot-profiles.md`](14-boot-profiles.md) defines cartridge selection at boot. -- [`15-asset-management.md`](15-asset-management.md) defines asset table and residency semantics. +- [`15-asset-management.md`](15-asset-management.md) defines the `assets.pa` envelope, asset table semantics, preload lifecycle, and residency semantics. diff --git a/docs/runtime/specs/15-asset-management.md b/docs/runtime/specs/15-asset-management.md index 4141c6ec..3281d1af 100644 --- a/docs/runtime/specs/15-asset-management.md +++ b/docs/runtime/specs/15-asset-management.md @@ -26,14 +26,56 @@ This chapter describes the runtime contract currently visible in the codebase. I 4. loading and activation are explicit operations; 5. asset memory does not participate in GC. -## 3 Cartridge Asset Surfaces +## 3 Cartridge Asset Artifact -The runtime currently consumes two cartridge asset surfaces: +The runtime currently consumes one primary cartridge asset artifact: + +- `assets.pa`: autocontained asset artifact. + +`assets.pa` carries, inside the same binary: + +- fixed binary prelude; +- JSON header; +- payload bytes. + +The JSON header carries: - `asset_table`: metadata entries describing asset content; -- `assets.pa`: packed asset bytes. +- `preload`: optional initial residency requests consumed during cartridge initialization. -An optional `preload` list may request initial slot residency during cartridge initialization. +This chapter describes the runtime-facing asset contract. It does not define the Studio packer workflow or the shipper pipeline that publishes the cartridge. + +### 3.1 `assets.pa` v1 envelope + +`assets.pa` v1 is structured as: + +```text +[fixed binary prelude] +[json header] +[binary payload region] +``` + +The fixed binary prelude contains, at minimum: + +- `magic` +- `schema_version` +- `header_len` +- `payload_offset` + +It may additionally include: + +- `flags` +- `reserved` +- `header_checksum` + +### 3.2 Header and payload contract + +The runtime loads: + +- `asset_table` from the JSON header and keeps it live during cartridge execution; +- `preload` from the JSON header and consumes it only during boot. + +Payload bytes are addressed from the payload region using offsets relative to `payload_offset`, not relative to the start of the whole file. ## 4 Asset Table @@ -54,6 +96,8 @@ AssetEntry { This table describes content identity and storage layout, not live residency. +`offset` is relative to the start of the payload region inside `assets.pa`. + ## 5 Banks and Slots The current runtime exposes bank types: @@ -85,10 +129,26 @@ The runtime asset manager exposes a staged lifecycle: High-level flow: 1. request load of an asset into a slot; -2. perform read/decode/materialization work; -3. mark the load `READY`; -4. explicitly `commit`; -5. activate the resident asset in the slot. +2. resolve the asset entry from live `asset_table`; +3. open the payload slice in `assets.pa`; +4. perform read/decode/materialization work; +5. mark the load `READY`; +6. explicitly `commit`; +7. activate the resident asset in the slot. + +The canonical payload paths are: + +- `ROM -> open_slice -> CODEX/decode -> Bank` +- `ROM -> open_slice -> temporary in-memory blob -> CODEX/decode -> Bank` + +`open_slice` is the runtime-facing concept for opening a limited view over a payload slice. The runtime must not require the whole `assets.pa` payload to remain resident in RAM as its baseline operating mode. + +`OP_MODE` selects between direct slice consumption and temporary materialization in memory. + +For v1: + +- `OP_MODE` is derived from `codec`/CODEX; +- explicit per-asset hinting is not part of the baseline contract. The runtime does not treat asset installation as implicit side effect. @@ -101,6 +161,7 @@ Therefore: - VM heap does not own asset residency; - GC does not scan asset bank memory; - shutting down a cartridge can release bank residency independently of VM heap behavior. +- the runtime must not keep the full `assets.pa` payload resident in RAM as a baseline requirement. ## 8 Bank Telemetry @@ -117,13 +178,18 @@ These metrics support debugging, telemetry, and certification-oriented inspectio ## 9 Preload -The cartridge may declare preload requests. +`preload` is stored in the JSON header of `assets.pa`. These preload entries are consumed during cartridge initialization so the asset manager can establish initial residency before normal execution flow. +Lifecycle rule: + +- `preload` is boot-time input only; +- it does not need to remain live after initialization completes. + ## 10 Relationship to Other Specs -- [`13-cartridge.md`](13-cartridge.md) defines cartridge fields that carry `asset_table`, `preload`, and `assets.pa`. +- [`13-cartridge.md`](13-cartridge.md) defines the cartridge package and the requirement that `assets.pa` carries its own asset header. - [`16-host-abi-and-syscalls.md`](16-host-abi-and-syscalls.md) defines the syscall boundary used to manipulate assets. - [`03-memory-stack-heap-and-allocation.md`](03-memory-stack-heap-and-allocation.md) defines the distinction between VM heap memory and host-owned memory.