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
@@ -75,6 +75,14 @@ The following are not primary identity:
Name and path are mutable presentation or location fields.
However, `asset_name` may still participate in authoring and runtime-facing APIs as a logical reference label.
That does not make it the stable identity of the asset.
Practical consequence:
- changing `asset_name` does not create a new asset identity;
- but changing `asset_name` may still require source-level or tooling-level reference updates where game/runtime APIs refer to assets by name.
### 5. Relocation and rename
Moving or renaming an asset root does not create a new asset.
@@ -0,0 +1,282 @@
# Asset Specification, Raw Assets, and Virtual Asset Contract Decision
## Status
Accepted
## Date
2026-03-11
## Context
This decision closes the architectural questions raised in [`01.2. Asset Specification, Raw Assets, and Virtual Asset Contract Agenda`](../agendas/01.2.%20Asset%20Specification,%20Raw%20Assets,%20and%20Virtual%20Asset%20Contract%20Agenda.md).
The packer needs a stable baseline contract for `asset.json` before detailed format-specific specs are written.
This contract must:
- support one managed asset root with many internal inputs;
- distinguish raw assets from virtual assets without making the common schema monolithic;
- expose runtime-relevant output information explicitly;
- declare preload intent deterministically;
- leave room for future format families without coupling all formats together.
## Decision
The packer adopts a compact common `asset.json` contract with explicit separation between:
- authoring asset family;
- grouped input declaration;
- runtime-facing output contract;
- preload declaration;
- optional build/process hints.
### 1. Common top-level shape
The common `asset.json` contract includes these required top-level fields:
- `schema_version`
- `name`
- `type`
- `inputs`
- `output`
- `preload`
The common contract may additionally include:
- `build`
`build` is optional in the shared baseline schema.
### 2. Meaning of `type`
`type` identifies the authoring-side asset family.
It is not the runtime bank target.
Examples of valid family-style values:
- `image_bank`
- `sound_bank`
The runtime-facing technical target belongs in `output.format`, not in `type`.
`name` remains the required logical asset reference label.
Meaning:
- `name` is not the stable artifact identity;
- `name` is the human-facing and code-facing reference used by asset-oriented APIs unless a future compile-time rewrite model replaces it;
- renaming `name` is an API-visible change even though it does not change `asset_id`.
### 3. Input declaration model
`inputs` is a structured object keyed by semantic role.
Rules:
- each key identifies an input role such as `sprites`, `palettes`, or `sources`;
- each value is a list of paths;
- paths are relative to the asset root;
- even a single input is represented as a list, not as a scalar.
This avoids shape ambiguity and supports grouped virtual assets cleanly.
Example:
```json
"inputs": {
"sprites": [
"sprites/confirm.png",
"sprites/cancel.png"
],
"palettes": [
"palettes/ui_main.pal"
]
}
```
### 4. Output contract
`output` is the runtime-relevant output declaration.
The common baseline requires:
- `output.format`
- `output.codec`
`output.metadata` is optional in the common schema, but becomes required whenever the selected format spec requires additional normative parameters.
Meaning:
- `output.format` identifies the semantic/runtime format contract;
- `output.codec` identifies how payload bytes are stored for extraction and materialization;
- `output.metadata` carries format-specific runtime-relevant details.
Codec must remain explicit.
It must not be hidden inside format naming when it represents a distinct storage concern.
### 5. Raw and virtual asset contract
The common schema must support both raw and virtual assets.
Rules:
- raw assets may declare a direct input-to-output path with minimal build metadata;
- virtual assets may declare multiple grouped inputs and optional build/process configuration;
- the common schema remains small, while detailed format behavior is defined in dedicated format specs.
### 6. Build/process hints
`build` is optional and carries process-oriented configuration.
Rules:
- `build` may describe how the packer should transform or organize authoring inputs;
- if a parameter affects the runtime-facing output contract, it belongs in `output.metadata`;
- `build` must not become a hidden substitute for runtime-relevant output definition.
Practical interpretation:
- `output.metadata` describes the contract of the produced payload;
- `build` describes how the packer gets there.
### 7. Preload declaration
Each managed asset must declare preload intent explicitly.
The baseline shape is:
```json
"preload": {
"enabled": true
}
```
Rules:
- `preload.enabled` is required and boolean;
- preload participation is declared, not inferred;
- packer build uses this field to determine whether preload data is emitted into the runtime-facing artifact contract;
- richer preload policy fields are deferred to future decisions and must not be implied silently now.
### 8. Defaults and materialization
Defaults may exist in specs, but defaults that affect reproducibility, compatibility, preload, or runtime-visible output must not remain invisible.
Rules:
- runtime-relevant defaults should be materialized in `asset.json` whenever practical;
- if materialization occurs later in the pipeline, the resulting artifact must still expose the effective value explicitly;
- packer must not rely on hidden defaults to produce runtime-visible behavior.
### 9. Versioning boundary
Versioning is split by concern.
Rules:
- `asset.json` carries its own `schema_version`;
- registry schemas are versioned independently;
- runtime-facing artifact schemas are versioned independently;
- format contracts are versioned independently through `output.format` values such as `TILES/indexed_v1` or `SOUNDS/pcm16le_v1`.
This prevents unrelated schema evolution from being coupled together.
## Invariants and Constraints
The following invariants now apply:
1. The common `asset.json` contract remains compact.
2. `type` is authoring-side family identity, not runtime bank identity.
3. `inputs` is structured by semantic role.
4. Input path values are always lists.
5. `name` remains a logical asset reference label even though it is not the stable artifact identity.
6. `output.format` and `output.codec` are separate required concerns.
7. Runtime-relevant format details belong in `output.metadata`.
8. `build` is optional and must not hide runtime-facing output semantics.
9. `preload.enabled` is the only preload field closed in the current baseline.
10. Defaults affecting runtime-visible behavior must be materialized explicitly.
11. Format evolution is versioned independently from registry and artifact schema evolution.
## Explicit Non-Decisions
This decision does not yet define:
- the full field-level schema of each format family;
- richer preload policies beyond `preload.enabled`;
- globbing support, input discovery shortcuts, or non-path input locators;
- CLI or Studio editor UX for authoring `asset.json`;
- exact `assets.pa` payload layout details;
- exact runtime preload record encoding.
Those belong to later decisions and specs.
## Propagation Targets
This decision must propagate to:
- common asset declaration spec;
- virtual asset contract spec;
- format-specific specs such as `TILES/indexed_v1` and `SOUNDS/pcm16le_v1`;
- preload emission and artifact mapping specs;
- Studio service contracts for asset authoring and validation;
- future implementation of asset parsing, validation, and deterministic build planning.
## Validation Notes
Example: grouped image asset
```json
{
"schema_version": 1,
"name": "ui_atlas",
"type": "image_bank",
"inputs": {
"sprites": [
"sprites/confirm.png",
"sprites/cancel.png"
],
"palettes": [
"palettes/ui_main.pal"
]
},
"output": {
"format": "TILES/indexed_v1",
"codec": "RAW",
"metadata": {
"tile_size": [8, 8]
}
},
"preload": {
"enabled": true
},
"build": {
"layout": "atlas"
}
}
```
Example: grouped sound asset
```json
{
"schema_version": 1,
"name": "ui_sounds",
"type": "sound_bank",
"inputs": {
"sources": [
"wav/click.wav",
"wav/confirm.wav"
]
},
"output": {
"format": "SOUNDS/pcm16le_v1",
"codec": "RAW"
},
"preload": {
"enabled": false
}
}
```
@@ -0,0 +1,250 @@
# Build Artifacts and Deterministic Packing Decision
## Status
Accepted
## Date
2026-03-11
## Context
This decision closes the architectural questions raised in [`01.3. Build Artifacts and Deterministic Packing Agenda`](../agendas/01.3.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Agenda.md).
The packer must produce build artifacts that are:
- deterministic;
- aligned with the runtime-facing `assets.pa` contract already established in `../runtime`;
- usable by Studio and tooling without creating a second source of truth;
- stable enough to support future specs and implementation.
The runtime-side contract already establishes that:
- `assets.pa` is the runtime-facing artifact;
- `asset_table` and `preload` live in the internal JSON header;
- offsets are relative to the payload region;
- preload is boot-time input only.
This decision closes how the packer should produce these artifacts.
## Decision
The packer adopts an `assets.pa`-authoritative, deterministically ordered, canonical-header model.
### 1. Artifact authority
`assets.pa` is the authoritative runtime-facing artifact.
Rules:
- the `assets.pa` header is the runtime-facing source of truth for `asset_table` and `preload`;
- `build/asset_table.json` and other JSON outputs are companion artifacts only;
- runtime must not depend on companion JSON files as its primary contract.
### 2. Companion artifacts
The packer emits separate companion artifacts for tooling and debugging.
Baseline companion outputs:
- `build/asset_table.json`
- `build/preload.json`
- `build/asset_table_metadata.json`
Rules:
- `build/asset_table.json` mirrors `header.asset_table` 1:1;
- `build/preload.json` mirrors `header.preload` 1:1;
- `build/asset_table_metadata.json` is tooling-only and may carry richer packer metadata;
- richer tooling data must not be smuggled into the runtime-facing mirror files.
### 3. `assets.pa` v1 prelude
The baseline packer-side prelude for `assets.pa` v1 includes:
- `magic`
- `schema_version`
- `header_len`
- `payload_offset`
- `flags`
- `reserved`
Rules:
- `flags` exists from day 1 for forward compatibility;
- `reserved` exists from day 1 for forward compatibility;
- `flags = 0` in the current baseline unless a future spec says otherwise;
- `reserved = 0` in the current baseline unless a future spec says otherwise;
- `header_checksum` is not part of the baseline `assets.pa` envelope contract.
### 4. Checksum policy
Header checksum is not part of the baseline runtime-facing envelope.
Rules:
- runtime validation does not depend on header checksum;
- cartridge-level integrity may be handled elsewhere;
- Studio/tooling may compute checks or hashes separately if needed;
- such checks must not redefine the runtime-facing `assets.pa` envelope.
### 5. Canonical JSON header
The JSON header of `assets.pa` must be serialized canonically.
Canonicalization rules:
- UTF-8 encoding;
- no extra whitespace;
- object keys sorted lexicographically;
- arrays preserve declared order;
- canonicalization applies recursively, including nested metadata objects;
- runtime-facing header values in v1 must avoid floating-point numbers.
This is required so equivalent inputs produce byte-identical headers and therefore byte-reproducible artifacts.
### 6. Ordering and determinism
The global `asset_table` order is deterministic by increasing `asset_id`.
Rules:
- usage-based or hot-first packing is not part of the baseline contract;
- format-specific heuristics must not reorder the global asset list;
- deterministic ordering is preferred over physical-layout heuristics;
- future locality optimization requires a separate explicit decision and spec.
### 7. `asset_id` continuity
The `asset_id` used in runtime-facing artifacts is the same stable `asset_id` allocated by the packer registry.
Rules:
- the packer does not generate a second runtime-only asset identity;
- `preload` refers to the same `asset_id` values that appear in `asset_table`;
- table position does not define identity;
- cross-build identity stability comes from `asset_id`, not from table index.
### 8. Asset table shape
`asset_table` is emitted as a deterministically ordered list of asset entries.
Rules:
- one emitted entry per managed asset in the build set;
- no synthetic dense reindexing layer is introduced;
- omission of removed assets happens naturally because the emitted table reflects the current build set only;
- the runtime sees a normal contiguous list of entries, but the IDs inside it remain the stable packer IDs.
### 9. `asset_name` in runtime-facing artifacts
`asset_name` remains present in `asset_table`.
Meaning:
- `asset_name` is logical descriptive and API-facing metadata;
- current runtime/game-facing calls may still use it for normal asset lookup;
- preload/bootstrap integrity relies on `asset_id`, not `asset_name`;
- renaming `asset_name` is an API-visible/content-visible change, but not an asset identity change.
### 10. Preload mapping
Preload emission is derived deterministically from per-asset declaration.
Rules:
- assets with `preload.enabled = false` do not appear in emitted preload data;
- assets with `preload.enabled = true` produce preload entries in the runtime-facing preload list;
- emitted preload ordering is deterministic by increasing `asset_id`;
- preload is boot-time input only and must be emitted in a form consistent with the runtime contract.
### 11. Alignment
Alignment exists only when explicitly required by spec.
Rules:
- there is no implicit baseline alignment beyond what is required by the envelope and chosen formats;
- if a format requires alignment, the requirement must be normative and visible in the relevant spec;
- computed offsets must always be emitted explicitly in the runtime-facing descriptor.
### 12. Offsets
All emitted asset offsets are relative to the payload region.
Rules:
- offsets are never relative to the start of the whole `assets.pa` file;
- this rule must be preserved consistently across packer outputs and specs;
- companion artifacts must mirror the same offset semantics.
## Invariants and Constraints
The following invariants now apply:
1. `assets.pa` is the authoritative runtime-facing artifact.
2. Companion JSON files do not replace the internal `assets.pa` header.
3. `build/asset_table.json` mirrors `header.asset_table` 1:1.
4. `build/preload.json` mirrors `header.preload` 1:1.
5. `build/asset_table_metadata.json` is tooling-only.
6. The prelude includes `magic`, `schema_version`, `header_len`, `payload_offset`, `flags`, and `reserved`.
7. `header_checksum` is not part of the baseline envelope contract.
8. Header JSON is canonicalized.
9. Global asset ordering is deterministic by increasing `asset_id`.
10. The runtime-facing `asset_id` is the same stable packer `asset_id`.
11. `asset_table` is a deterministically ordered list, not a second identity system.
12. `asset_name` remains present as logical/API-facing metadata.
13. Preload is emitted deterministically from `preload.enabled`.
14. Offsets are relative to the payload region only.
## Explicit Non-Decisions
This decision does not yet define:
- the exact field-level metadata contract of each output format;
- richer preload policies beyond the current baseline;
- future physical locality optimization;
- game-language lowering of asset references from names to IDs;
- cartridge-level integrity/signature strategy.
Those belong to later decisions and specs.
## Propagation Targets
This decision must propagate to:
- packer artifact and envelope specs;
- packer determinism and reproducibility specs;
- packer preload emission specs;
- Studio tooling expectations for companion artifacts;
- future implementation of canonical header generation and companion-file emission.
## Validation Notes
Example: artifact relationship
```text
assets.pa
prelude
canonical header JSON
asset_table
preload
payload bytes
build/asset_table.json
mirrors header.asset_table
build/preload.json
mirrors header.preload
build/asset_table_metadata.json
tooling-only enrichment
```
Example: stable identity
- packer registry assigns asset IDs `3`, `7`, and `11`
- emitted `asset_table` is ordered `[3, 7, 11]`
- runtime-facing preload entries reference `3`, `7`, or `11`
- no additional dense runtime ID layer is introduced