asset preload alignment

This commit is contained in:
2026-03-24 13:40:54 +00:00
parent d7c970a3e2
commit d576f7ddbd
11 changed files with 367 additions and 22 deletions
+8
View File
@@ -109,6 +109,13 @@ The JSON header carries:
`asset_table` and `preload` are therefore no longer the primary runtime contract of `manifest.json`.
`preload` is structurally validated as part of `assets.pa` bootstrap:
- each preload entry is `{ asset_id, slot }`;
- `asset_id` uses 32-bit signed integer semantics;
- each `preload.asset_id` must resolve to an entry in the same `asset_table`;
- no two preload entries may claim the same `(bank_type, slot)` pair once `bank_type` is resolved from `asset_table`.
Runtime lifecycle:
- `asset_table` is loaded from `assets.pa` and remains live while the cartridge is running;
@@ -119,6 +126,7 @@ 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`;
- `assets.pa` with invalid preload references or preload slot clashes is structurally invalid;
- failure must occur as early as cartridge bootstrap, before preload execution.
## 7 Runtime Forms
+22
View File
@@ -96,6 +96,8 @@ AssetEntry {
This table describes content identity and storage layout, not live residency.
`asset_id` is the stable runtime-facing asset identity and uses 32-bit signed integer semantics compatible with Java `int`.
`offset` is relative to the start of the payload region inside `assets.pa`.
## 5 Banks and Slots
@@ -180,13 +182,33 @@ These metrics support debugging, telemetry, and certification-oriented inspectio
`preload` is stored in the JSON header of `assets.pa`.
The normative preload shape is:
```text
PreloadEntry {
asset_id
slot
}
```
These preload entries are consumed during cartridge initialization so the asset manager can establish initial residency before normal execution flow.
Validation rules:
- `preload` is resolved by `asset_id`, not by `asset_name`;
- every `preload.asset_id` must exist in the same `asset_table`;
- no two preload entries may resolve to the same `(bank_type, slot)` pair;
- legacy preload keyed by `asset_name` is invalid for the current contract.
Lifecycle rule:
- `preload` is boot-time input only;
- it does not need to remain live after initialization completes.
Bootstrap rule:
- invalid preload is a structural cartridge error and must fail cartridge bootstrap before normal execution begins.
## 10 Relationship to Other Specs
- [`13-cartridge.md`](13-cartridge.md) defines the cartridge package and the requirement that `assets.pa` carries its own asset header.