Files
prometeu-studio/docs/specs/packer/4. Build Artifacts and Deterministic Packing Specification.md
T
bquarkz 1471b427f1
Test / Tests and coverage occurred while executing withChecks step.
Intrepid/Prometeu/Studio/pipeline/pr-master There was a failure building this commit
feat(studio): deliver asset authoring and automation workflows
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.
2026-11-11 01:21:25 +00:00

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

  1. assets.pa is the authoritative runtime-facing artifact.
  2. Companion JSON files do not replace the internal header as the runtime contract.
  3. The global asset table order is deterministic by increasing asset_id.
  4. The runtime-facing asset_id is the same stable asset_id allocated by the packer registry.

assets.pa Structure

Baseline structure:

[fixed binary prelude]
[canonical JSON header]
[binary payload region]

Prelude Fields

The baseline prelude includes:

  • magic
  • schema_version
  • header_len
  • payload_offset
  • flags
  • reserved

Rules:

  • flags and reserved exist from day 1;
  • flags = 0 unless later specified otherwise;
  • reserved = 0 unless later specified otherwise;
  • header_checksum is 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_table
  • preload

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_name may remain present as logical/API-facing metadata;
  • asset_name is 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.metadata materializes at the metadata root;
  • output.codec_configuration materializes under metadata.codec;
  • output.pipeline remains tooling-only and must not materialize under asset_table[].metadata by 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[].codec MUST use SCREAMING_SNAKE_CASE;
  • the current known NONE value serializes as NONE.

Preload

Preload is emitted deterministically from per-asset declaration.

Rules:

  • assets with preload.enabled = false do not appear in emitted preload data;
  • assets with preload.enabled = true do appear;
  • preload ordering is deterministic by increasing asset_id.

Companion Artifacts

The baseline companion artifacts are:

  • 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 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[].size describe payload slicing inside assets.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 tile in v1;
  • artifacts are normalized by ascending artifacts[*].index;
  • emitted tile_id equals 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 256 in v1;
  • tile placement within that emitted sheet is row-major;
  • runtime width and height for the bank entry therefore refer to the full emitted sheet, not one individual artifact;
  • resulting per-bank capacities are:
    • tile_size = 8 -> 1024 tiles
    • tile_size = 16 -> 256 tiles
    • tile_size = 32 -> 64 tiles
  • capacity overflow is a build-blocking structural failure.

Payload Layout

Rules:

  • the serialized payload for GLYPH/indexed_v1 is:
    1. one packed u4 pixel plane for the full emitted sheet;
    2. one palette block of palette_count * 16 * 4 bytes;
  • 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, A order;
  • payload interpretation must not depend on incidental per-artifact boundaries.

Runtime Entry Derivation

Rules:

  • emitted tile-bank entries use:
    • bank_type = GLYPH
    • codec = NONE
  • tile-bank v1 metadata must expose at least:
    • tile_size
    • width
    • height
    • palette_count
  • tile-bank v1 requires palette_count in the inclusive range 1..=64;
  • palette_count is 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 * 4
    • decoded_size = (width * height) + palette_count * 16 * 4
  • fixed 64-palette padding is not a compatibility mode unless palette_count = 64 and the payload directly satisfies the v1 contract;
  • GLYPH/indexed_v2 must 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 rgba8888 entries interpreted as 0xRRGGBBAA;
  • 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 0 is 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 SCENE payloads.

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 4 layer entries in wave 1;
  • tile_count is derived from width * height;
  • glyph_asset_id is the runtime-facing glyph dependency identity carried by the scene payload;
  • active at layer scope determines whether the layer participates in emitted scene output;
  • active at tile scope determines whether the tile contributes an active tile record to the emitted scene payload;
  • palette_id uses a layer-owned editorial default with optional per-tile override before the request reaches packer;
  • packer consumes only the resolved per-tile palette_id values 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.