Add shared human/task asset batches with reviewed atomic publication, explicit reference rebinds, ownership inspection and qualified glyph/scene budgets. Expose the same authoring and capacity results through Assets and MCP. Deliver isolated guest test targets, retained visual evidence and immutable runtime lifecycle/control observations. Preserve provider qualification and installed authoring examples alongside the completed discussion lessons. Close AGD-106 coordination and the delivered discussion workflows through housekeeping, updating lesson references and preserving qualification limits. Sound remains outside the asset delivery wave. Validation: 579 module tests and 31 additional desktop, process and installed checks passed; native glyph/scene 16/17 boundaries qualified. Discussion validation passed after housekeeping.
13 KiB
Build Artifacts and Deterministic Packing Specification
Status: Draft
Scope: Runtime-facing artifacts and deterministic build behavior
Purpose: Define how the packer emits assets.pa and companion artifacts.
Authority and Precedence
This specification consolidates the initial packer agenda and decision wave into normative form.
Runtime-side reading semantics remain upstream in:
../runtime/docs/runtime/specs/13-cartridge.md../runtime/docs/runtime/specs/15-asset-management.md
Core Rules
assets.pais the authoritative runtime-facing artifact.- Companion JSON files do not replace the internal header as the runtime contract.
- The global asset table order is deterministic by increasing
asset_id. - The runtime-facing
asset_idis the same stableasset_idallocated by the packer registry.
assets.pa Structure
Baseline structure:
[fixed binary prelude]
[canonical JSON header]
[binary payload region]
Prelude Fields
The baseline prelude includes:
magicschema_versionheader_lenpayload_offsetflagsreserved
Rules:
flagsandreservedexist from day 1;flags = 0unless later specified otherwise;reserved = 0unless later specified otherwise;header_checksumis not part of the baseline envelope contract.
Canonical JSON Header
The header is serialized canonically.
Rules:
- UTF-8 encoding;
- no extra whitespace;
- object keys sorted lexicographically;
- arrays preserve declared order;
- canonicalization applies recursively;
- runtime-facing header values in v1 must avoid floating-point numbers.
Header Contents
The header carries:
asset_tablepreload
Asset Table
asset_table is emitted as a deterministically ordered list of asset entries.
Rules:
- one entry per included asset in the current build set;
- no secondary runtime-only identity layer;
- no synthetic dense reindexing layer;
asset_namemay remain present as logical/API-facing metadata;asset_nameis not the operational compile-time identity used by backend-owned symbolic asset surfaces.
Asset Entry Metadata Convergence
Each emitted asset entry has one runtime metadata sink: AssetEntry.metadata.
Rules:
- packer materialization must normalize all runtime-consumable metadata-producing sources into
asset_table[].metadata; - equivalent declaration/build inputs must produce equivalent normalized metadata;
- metadata key collisions across independent sources must fail build unless the family/format spec declares an explicit merge rule;
- normalization behavior must be testable and covered by conformance-oriented tests.
Baseline normalized metadata segmentation:
output.metadatamaterializes at the metadata root;output.codec_configurationmaterializes undermetadata.codec;output.pipelineremains tooling-only and must not materialize underasset_table[].metadataby default;- pipeline-derived runtime-required values must be promoted explicitly into normative runtime-owned metadata fields;
- format-specific runtime-required fields may remain directly readable at the metadata root when the runtime consumer requires them there.
Asset entry codec serialization:
asset_table[].codecMUST useSCREAMING_SNAKE_CASE;- the current known
NONEvalue serializes asNONE.
Preload
Preload is emitted deterministically from per-asset declaration.
Rules:
- assets with
preload.enabled = falsedo not appear in emitted preload data; - assets with
preload.enabled = truedo appear; - preload ordering is deterministic by increasing
asset_id.
Companion Artifacts
The baseline companion artifacts are:
build/asset_table.jsonbuild/preload.jsonbuild/asset_table_metadata.json
Rules:
build/asset_table.jsonmirrorsheader.asset_table1:1;build/preload.jsonmirrorsheader.preload1:1;build/asset_table_metadata.jsonis tooling-only and may retain pipeline/build provenance that is intentionally excluded from the runtime header;- richer tooling data must not be added to the 1:1 mirror files.
Alignment and Offsets
Alignment exists only when explicitly required by spec.
Rules:
- there is no implicit baseline alignment beyond envelope and format requirements;
- any required alignment must be normative and visible;
- emitted offsets are always relative to the payload region, never the start of the full file.
Offset ambiguity guardrail:
asset_table[].offset/asset_table[].sizedescribe payload slicing insideassets.pa;- internal pipeline indexing data (for example per-sample ranges for audio banks) must live under
asset_table[].metadata; - internal indexing fields must not be interpreted as payload slicing fields.
Format-Specific Baseline: GLYPH/indexed_v1
The producer contract for GLYPH/indexed_v1 is runtime-aligned and uses a
variable RGBA8888 palette block.
Tile Selection and Identity
Rules:
- only selected artifacts participate in the emitted glyph bank;
1 artifact = 1 tilein v1;- artifacts are normalized by ascending
artifacts[*].index; - emitted
tile_idequals the normalized artifact index; - duplicate or gapped artifact indices are build-blocking structural failures.
Emitted Sheet Shape
Rules:
- the emitted tile-bank sheet is always
256 x 256in v1; - tile placement within that emitted sheet is row-major;
- runtime
widthandheightfor the bank entry therefore refer to the full emitted sheet, not one individual artifact; - resulting per-bank capacities are:
tile_size = 8->1024tilestile_size = 16->256tilestile_size = 32->64tiles
- capacity overflow is a build-blocking structural failure.
Payload Layout
Rules:
- the serialized payload for
GLYPH/indexed_v1is:- one packed
u4pixel plane for the full emitted sheet; - one palette block of
palette_count * 16 * 4bytes;
- one packed
- packed pixel bytes must be emitted by the packer, not inferred later by the runtime;
- the palette block is serialized as RGBA8888 values in runtime RGBA channel order;
- each palette entry is emitted as four bytes in
R,G,B,Aorder; - payload interpretation must not depend on incidental per-artifact boundaries.
Runtime Entry Derivation
Rules:
- emitted tile-bank entries use:
bank_type = GLYPHcodec = NONE
- tile-bank v1 metadata must expose at least:
tile_sizewidthheightpalette_count
- tile-bank v1 requires
palette_countin the inclusive range1..=64; palette_countis the number of serialized palettes and resident runtime palettes for the bank;- tile-bank v1 size formulas are:
size = ceil(width * height / 2) + palette_count * 16 * 4decoded_size = (width * height) + palette_count * 16 * 4
- fixed 64-palette padding is not a compatibility mode unless
palette_count = 64and the payload directly satisfies the v1 contract; GLYPH/indexed_v2must not be introduced for this palette-count correction.
Palette Contract
Rules:
- bank palettes are declared under
output.pipeline.palettes; - each palette declaration uses the shape
{ "index": <int>, "palette": { ... } }; - each palette payload uses canonical
rgba8888entries interpreted as0xRRGGBBAA; - palette ordering is ascending numeric
index, never raw array position; - palette ids in the emitted glyph bank are direct declared palette indices;
- v1 has no sparse-to-dense palette remapping metadata;
- palette index
0is ordinary and may carry any RGBA8888 value; - glyph palettes have 16 usable entries;
- transparency and partial transparency are encoded only by RGBA alpha;
- magenta color-key behavior is not part of the normal glyph-bank contract;
- any tile in the bank may be rendered with any palette in the bank at runtime;
- palette selection is a runtime draw concern, not a tile-payload embedding concern.
Format-Specific Baseline: SCENE/tilemap_v1
SCENE/tilemap_v1 is the wave-1 Scene Bank publication format.
Canonical Build Input
Rules:
- packer receives a canonical editor-agnostic Scene Bank request as its publication input;
- packer must not parse
TMX,TSX, or other editor-specific source files directly as part of runtime scene publication; - the request is produced by Studio from canonical scene state after canonical validation;
- equivalent requests must produce equivalent emitted
SCENEpayloads.
Baseline request shape:
ScenePackRequest
- version: int
- layers: [ScenePackLayerRequest; 4]
ScenePackLayerRequest
- active: bool
- glyph_asset_id: int
- tile_size: int
- parallax_factor_x: float
- parallax_factor_y: float
- width: int
- height: int
- tiles: List<ScenePackTileRequest>
ScenePackTileRequest
- active: bool
- glyph_id: int
- palette_id: int
- flip_x: bool
- flip_y: bool
Request Semantics
Rules:
- the request always materializes exactly
4layer entries in wave 1; tile_countis derived fromwidth * height;glyph_asset_idis the runtime-facing glyph dependency identity carried by the scene payload;activeat layer scope determines whether the layer participates in emitted scene output;activeat tile scope determines whether the tile contributes an active tile record to the emitted scene payload;palette_iduses a layer-owned editorial default with optional per-tile override before the request reaches packer;- packer consumes only the resolved per-tile
palette_idvalues present in the canonical request; - request-to-binary projection should remain as close to isomorphic as possible.
Wave-1 Constraints
Rules:
- wave 1 remains limited to exactly one logical tileset/glyph source per layer before request emission;
- packer does not own editor-format interoperability rules; it trusts the canonical request boundary once the request is structurally valid;
- binary reserved fields must not require corresponding request fields unless a later decision gives them editorial meaning.
Determinism
Equivalent build inputs must produce equivalent outputs.
Rules:
- no filesystem iteration dependence;
- no hidden defaults that affect output;
- no usage-based hot-first packing in the baseline contract;
- determinism is preferred over speculative physical-layout optimization.
Non-Goals
- per-format payload internals for every output family
- future locality optimization policy
- cartridge-level integrity/signature strategy
Exit Criteria
This specification is complete enough when:
- runtime-facing artifact authority is explicit;
- companion artifacts are bounded;
- emitted ordering and header behavior are deterministic.
Animation integration contract
Expose the effective selected glyph layout through Packer API: asset UUID and stable artifact ID to glyph ID/fingerprint mapping from the same composition used for pack. Exclude animations.studio.json from glyph candidates and binary payload. The sidecar references existing identities and does not create an asset type, header or animation binary format. Reorder/removal/content drift requires explicit revision-checked rebind by authoring services; never retarget by path/order.
See the complete animation contract.
Qualified global bank budgets and publication
Bank-content format limits and global residency limits are separate checks. The final deterministic packer preload list is the authority for effective slots per bank type; individual glyphs, logical scenes and stages do not add bank slots. Report existing, build-included, effective-preload and potential dynamic views separately. Cold scene dependencies follow the existing runtime residency contract, preserving AssetId identity rather than converting it into a slot. Potential dynamic excess is a warning about possible loads, not proof of simultaneous residency.
Global limits MUST come from a distributed versioned profile qualified against the exact selected installed executable. The profile includes contract/runtime versions, executable digest, per-type limits and retained positive/boundary evidence. Publish the initial 16-slot profile only after the selected executable passes 16/17 qualification for glyph and scene. Sound is outside this wave; profiles MUST contain only bank types with actual boundary evidence. An absent/incompatible profile is unknown, never unlimited or a silent constant/family fallback.
With a known profile, validate effective preloads before final cartridge publication. Excess MUST retain the previous valid output and report the type, limit, responsible slots/AssetIds/paths and profile. A build without a selected compatible profile may publish with explicit unknown qualification, but MUST NOT claim qualified capacity. Managed execution requires a matching profile and valid budget through the same shared preflight. Runtime selection or effective input changes invalidate the previous check. Record the checked profile and input revision in build provenance; ordinary builds MUST NOT inspect runtime checkout sources to obtain limits.
The bundled macOS arm64 profile macos-arm64-cli-0.1.0-18423f7-glyph-scene-v1
is qualified for glyph=16 and scene=16 against exact dispatcher, headless and
desktop component hashes. Runtime version 0.1.0 alone does not select it.
The distributed catalog includes hashed boundary evidence. Managed start and each
headless BOOT MUST recheck the selected component fingerprints, the complete
profile/evidence identity, and hashes of actual cartridge files. Admission reads
the serialized assets.pa table/preload; auxiliary JSON never replaces it.
A changed executable, evidence or build requires a new qualified build.