updated packer agendas
This commit is contained in:
@@ -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.
|
||||
|
||||
+282
@@ -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
|
||||
Reference in New Issue
Block a user