122 lines
3.7 KiB
Markdown
122 lines
3.7 KiB
Markdown
# Build Artifacts and Deterministic Packing Agenda
|
|
|
|
## Status
|
|
|
|
Open
|
|
|
|
## Purpose
|
|
|
|
Close the contract for packer build outputs and the determinism rules that make them reproducible.
|
|
|
|
## Context
|
|
|
|
The draft proposes two core build artifacts:
|
|
|
|
- `build/assets.pa`
|
|
- `build/asset_table.json`
|
|
|
|
At least one of these artifacts must form a documented interface that `../runtime` can consume safely.
|
|
That runtime-facing contract should be specified before the implementation hardens around incidental file structure.
|
|
|
|
It also states strong determinism requirements:
|
|
|
|
- deterministic asset order,
|
|
- deterministic derived outputs,
|
|
- explicit materialization of inferred defaults.
|
|
|
|
This is a strong basis for normative packer output specs.
|
|
|
|
## Source Sections
|
|
|
|
- `8. Build Artifacts Produced by the Packer`
|
|
- `9. Determinism Rules`
|
|
|
|
## Runtime Normative Inputs
|
|
|
|
From `../runtime/docs/runtime/specs/13-cartridge.md`:
|
|
|
|
- `assets.pa` is the runtime-facing artifact;
|
|
- `assets.pa` v1 is an autocontained binary with:
|
|
- fixed binary prelude,
|
|
- JSON header,
|
|
- binary payload region;
|
|
- the fixed prelude contains, at minimum:
|
|
- `magic`,
|
|
- `schema_version`,
|
|
- `header_len`,
|
|
- `payload_offset`;
|
|
- the JSON header carries:
|
|
- `asset_table`,
|
|
- `preload`.
|
|
|
|
From `../runtime/docs/runtime/specs/15-asset-management.md`:
|
|
|
|
- `asset_table` entries currently expose:
|
|
- `asset_id`,
|
|
- `asset_name`,
|
|
- `bank_type`,
|
|
- `offset`,
|
|
- `size`,
|
|
- `decoded_size`,
|
|
- `codec`,
|
|
- `metadata`;
|
|
- `offset` is relative to the payload region inside `assets.pa`, not to the start of the full file;
|
|
- `preload` is boot-time input only;
|
|
- runtime loading is based on `open_slice` over payload slices;
|
|
- the runtime must not require the entire payload to stay resident in RAM.
|
|
|
|
These are already normative runtime-facing requirements and should be treated as baseline constraints for packer output design.
|
|
|
|
## 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?
|
|
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?
|
|
|
|
## Options
|
|
|
|
### Option A
|
|
|
|
Keep `assets.pa` simple and push structure into `asset_table.json`.
|
|
|
|
### Option B
|
|
|
|
Embed more self-description into `assets.pa` itself.
|
|
|
|
## 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.
|
|
|
|
## Recommendation
|
|
|
|
Adopt Option A and make `asset_table.json` the authoritative descriptor for ROM slice structure.
|
|
|
|
## Expected Decisions to Produce
|
|
|
|
1. v1 artifact boundary and ownership.
|
|
2. Deterministic ordering and alignment rules.
|
|
3. Descriptor schema responsibilities.
|
|
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.
|
|
|
|
## Expected Spec Follow-up
|
|
|
|
- Packed ROM artifact spec.
|
|
- Asset table descriptor spec.
|
|
- Determinism and reproducibility spec.
|
|
- Runtime consumption interface spec.
|
|
|
|
## Non-Goals
|
|
|
|
- Asset workspace mutation commands.
|
|
- Quarantine behavior.
|
|
- Builder packaging flow.
|