updated packer agendas

This commit is contained in:
2026-03-24 13:42:38 +00:00
parent 4aef6cdaeb
commit 900a7e17dd
7 changed files with 768 additions and 10 deletions
@@ -2,7 +2,9 @@
## Status
Open
Closed
Resolved by [`002-asset-specification-raw-assets-and-virtual-asset-contract-decision.md`](../decisions/002-asset-specification-raw-assets-and-virtual-asset-contract-decision.md).
## Purpose
@@ -28,6 +30,12 @@ Important example:
- one `asset.json` describes the whole managed asset and its final packed output;
- the internal source files are inputs of that asset, not separate assets unless explicitly modeled that way.
The runtime-facing extraction path also depends on codec information.
Because codec affects how runtime opens, decodes, or materializes payload bytes, codec must be explicit in the asset contract rather than hidden inside format naming.
Preload intent is also asset-level information.
Each managed asset should carry an explicit entry indicating whether it participates in preload, so preload inclusion is declared intentionally rather than inferred indirectly later in the pipeline.
## Source Sections
- `5.3 Asset Types (Bank Targets)`
@@ -44,6 +52,8 @@ Important example:
5. Is `type` the bank target, the user-facing kind, or both?
6. How should packer version output formats independently from registry and descriptor schemas?
7. How should one `asset.json` declare many internal inputs that together form one virtual asset, such as an atlas plus palettes?
8. Should codec be part of `output.format`, or a separate explicit field in the output contract?
9. How should each asset declare preload intent so the packer can materialize runtime preload entries deterministically?
## Options
@@ -75,6 +85,38 @@ Also adopt this modeling direction:
- many internal source files may feed that single managed output;
- atlas/image-bank style assets should be modeled as one asset with many inputs rather than many implicit sibling assets.
Also adopt this output-contract direction:
- `output.format` identifies the semantic/runtime format contract;
- `output.codec` identifies how payload bytes are stored for extraction/materialization;
- codec must remain explicit because it affects runtime extraction behavior;
- codec should not be smuggled into format naming when it represents a distinct storage concern.
Also adopt this preload direction:
- each managed asset must expose an explicit preload-related declaration entry;
- preload participation must be declared, not inferred from ad hoc conventions;
- packer build must use that declaration to decide whether preload data is emitted into the runtime-facing artifact contract.
- `preload.enabled` should be the required runtime-relevant boolean;
- richer packer-side preload metadata may exist, but it must not change runtime behavior until separately specified.
Current recommended shape:
```json
{
"preload": {
"enabled": true,
"policy": "boot_critical"
}
}
```
Direction:
- `enabled` is the normative yes/no input for runtime preload emission;
- optional fields such as `policy` are packer-side hints for Studio, diagnostics, planning, or future evolution;
- packer-side preload hints must not silently alter the current runtime-facing preload contract.
## Expected Decisions to Produce
1. Common `asset.json` schema boundary.
@@ -82,6 +124,8 @@ Also adopt this modeling direction:
3. Versioning strategy for asset format specs.
4. Rules for defaults and explicit materialization.
5. Multi-input asset declaration model for atlas, bank, and similar grouped assets.
6. Explicit separation between output format and codec in the asset contract.
7. Asset-level preload declaration model.
## Expected Spec Follow-up
@@ -2,7 +2,9 @@
## Status
Open
Closed
Resolved by [`003-build-artifacts-and-deterministic-packing-decision.md`](../decisions/003-build-artifacts-and-deterministic-packing-decision.md).
## Purpose
@@ -67,36 +69,87 @@ From `../runtime/docs/runtime/specs/15-asset-management.md`:
These are already normative runtime-facing requirements and should be treated as baseline constraints for packer output design.
For this agenda, the intended direction is:
- `assets.pa` is the authoritative runtime-facing artifact;
- `build/asset_table.json` is a companion tooling artifact derived from the same build result;
- runtime must not depend on `build/asset_table.json` as its primary source of truth.
Current runtime code now resolves preload by `asset_id`, but game-facing runtime APIs still refer to assets by `asset_name`.
Therefore this agenda distinguishes:
- `asset_id` as stable artifact identity for preload/bootstrap and asset-table integrity;
- `asset_name` as logical API-level identifier used by game/runtime-facing calls today.
This agenda does not introduce a second runtime-only asset identity.
The `asset_id` emitted by the packer is the same `asset_id` used in the runtime-facing artifact contract.
## Key Questions
1. How should the packer spec mirror the already normative `assets.pa` v1 envelope from runtime specs 13 and 15?
2. Which fields in `asset_table.json` are still tooling-only if the runtime-facing contract lives primarily inside `assets.pa`?
3. Is asset order always `asset_id` order, or can format-specific constraints override it?
2. Which fields in `build/asset_table.json` are companion tooling data versus runtime-facing contract data?
3. Should global asset packing order be deterministic by `asset_id`, or influenced by usage and format-specific heuristics?
4. How should alignment be expressed and validated?
5. What exactly counts as determinism for virtual asset pipelines?
6. Which inferred values must be written back versus only emitted in build outputs?
7. Which packer-side metadata is intentionally excluded from the runtime-facing contract?
8. How should packer document `preload` lifecycle and `offset` semantics so they match runtime reader behavior?
9. How should per-asset preload declarations be transformed into the `preload` section of `assets.pa` deterministically?
10. How should the packer preserve both `asset_id` integrity and `asset_name` lookup semantics in runtime-facing artifacts?
11. Should `asset_table` be modeled as a deterministically ordered asset list that preserves packer `asset_id` values end-to-end?
12. Which envelope fields are runtime-validated versus emitted only for Studio/tooling use?
## Options
### Option A
Keep `assets.pa` simple and push structure into `asset_table.json`.
Keep `assets.pa` as the authoritative autocontained runtime-facing artifact and emit `build/asset_table.json` as a derived companion artifact for Studio and tooling.
### Option B
Embed more self-description into `assets.pa` itself.
Keep runtime-facing structure split across `assets.pa` and `build/asset_table.json`.
## Tradeoffs
- Option A keeps runtime payload compact and keeps metadata easier to evolve.
- Option A matches the current draft direction and reduces double-modeling.
- Option B may help standalone introspection, but it risks splitting authority across two artifacts.
- Option A matches the runtime specs already in force.
- Option A keeps runtime authority in one artifact and prevents contract drift.
- Option A still allows rich tooling through a derived companion file.
- Option B risks splitting authority across artifacts and making runtime/tooling divergence easier.
## Recommendation
Adopt Option A and make `asset_table.json` the authoritative descriptor for ROM slice structure.
Adopt Option A with these fixed directions:
- `assets.pa` is the authoritative runtime-facing artifact;
- the `assets.pa` header is the authoritative runtime-facing descriptor;
- `build/asset_table.json` is a derived companion artifact for Studio, debugging, inspection, and builder/tooling integration;
- global packing order is deterministic by increasing `asset_id`;
- preload emission is derived deterministically from per-asset `preload.enabled`;
- alignment exists only when explicitly required by spec;
- offsets are always relative to the payload region, never to the start of the full file;
- checksum is not part of the baseline `assets.pa` envelope contract.
Also adopt this performance direction:
- usage-based hot-first packing is not part of the baseline contract;
- deterministic stable ordering is preferred over heuristic physical reordering;
- future locality optimization may be introduced only through an explicit later decision and spec, not as an implementation shortcut now.
Also adopt this identity direction:
- runtime-facing preload entries should migrate to stable `asset_id` instead of mutable `asset_name`;
- runtime-facing preload/bootstrap integrity should treat `asset_id` as primary identity;
- `asset_name` remains present in `asset_table` as logical descriptive and API-facing metadata used by current runtime/game-facing calls;
- `asset_table` should be generated deterministically on every build from the current managed asset set;
- `asset_table` should be emitted as a deterministically ordered list of asset entries;
- the runtime-facing `asset_id` is exactly the stable `asset_id` allocated by the packer registry;
- stable cross-build identity comes from `asset_id`, not from table position;
- rename of `asset_name` is therefore an API-visible/content-visible change, but not an identity change.
Also adopt this companion-artifact direction:
- `build/asset_table.json` should mirror the runtime-facing header data 1:1 for debugging and inspection;
- if richer tooling artifacts are needed, they should be emitted as separate files instead of overloading `build/asset_table.json`.
## Expected Decisions to Produce
@@ -106,6 +159,11 @@ Adopt Option A and make `asset_table.json` the authoritative descriptor for ROM
4. Materialization requirements for inferred values.
5. Runtime-facing artifact contract and reader expectations.
6. Packer-side restatement of the runtime-owned `assets.pa` envelope and slice semantics.
7. Deterministic mapping from asset declarations to runtime preload data.
8. Explicit exclusion of usage-based packing heuristics from the baseline contract.
9. Migration of preload/bootstrap integrity toward `asset_id`-based identity while preserving `asset_name` as current API-facing metadata.
10. Deterministically ordered `asset_table` preserving packer `asset_id` values end-to-end.
11. Separation between runtime-validated envelope fields and non-envelope tooling concerns.
## Expected Spec Follow-up