implements PR-011a assets.pa spec propagation

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.

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.