prometeu-studio/docs/packer/agendas/01.2. Asset Specification, Raw Assets, and Virtual Asset Contract Agenda.md

Asset Specification, Raw Assets, and Virtual Asset Contract Agenda

Status

Closed

Resolved by 002-asset-specification-raw-assets-and-virtual-asset-contract-decision.md.

Purpose

Define the contract of asset.json, including the split between raw assets, virtual assets, and format-specific output specs.

Context

The draft already proposes:

• asset.json as the anchor spec,
• common fields for all assets,
• explicit pipeline declaration for virtual assets,
• future format families such as TILES/indexed_v1 and SOUNDS/pcm16le_v1.

This needs decomposition into a stable common contract plus future format-specific specs.

This agenda assumes the managed asset is the asset root described by one asset.json. That root may aggregate multiple source inputs.

Important example:

• an atlas or image bank asset may contain many source sprites plus one or more palettes;
• one asset.json describes the whole managed asset and its final packed output;
• the internal source files are inputs of that asset, not separate assets unless explicitly modeled that way.

The runtime-facing extraction path also depends on codec information. Because codec affects how runtime opens, decodes, or materializes payload bytes, codec must be explicit in the asset contract rather than hidden inside format naming.

Preload intent is also asset-level information. Each managed asset should carry an explicit entry indicating whether it participates in preload, so preload inclusion is declared intentionally rather than inferred indirectly later in the pipeline.

Source Sections

• 5.3 Asset Types (Bank Targets)
• 5.4 Raw vs Virtual Assets
• 7. Asset Specification: asset.json
• 14. Virtual Assets (Deep Explanation)

Key Questions

1. Which fields belong to every asset.json regardless of type?
2. Which parts of the file are common packer contract versus format-specific contract?
3. How explicit must virtual build steps be?
4. Where should defaults live, and when must they be materialized?
5. Is type the bank target, the user-facing kind, or both?
6. How should packer version output formats independently from registry and descriptor schemas?
7. How should one asset.json declare many internal inputs that together form one virtual asset, such as an atlas plus palettes?
8. Should codec be part of output.format, or a separate explicit field in the output contract?
9. How should each asset declare preload intent so the packer can materialize runtime preload entries deterministically?

Options

Option A

Keep a small common asset.json contract and push all output-specific rules into dedicated format specs.

Option B

Keep a richer monolithic asset.json contract in one central spec.

Tradeoffs

• Option A scales better as new asset formats are added.
• Option A keeps the core packer spec smaller and more stable.
• Option B looks simpler initially but becomes harder to evolve without coupling unrelated formats together.

Recommendation

Adopt Option A:

• a compact common asset.json contract,
• format-specific normative specs for each output family,
• explicit virtual asset declarations with deterministic materialization rules.

Also adopt this modeling direction:

• asset.json describes the managed output unit;
• many internal source files may feed that single managed output;
• atlas/image-bank style assets should be modeled as one asset with many inputs rather than many implicit sibling assets.

Also adopt this output-contract direction:

• output.format identifies the semantic/runtime format contract;
• output.codec identifies how payload bytes are stored for extraction/materialization;
• codec must remain explicit because it affects runtime extraction behavior;
• codec should not be smuggled into format naming when it represents a distinct storage concern.

Also adopt this preload direction:

• each managed asset must expose an explicit preload-related declaration entry;
• preload participation must be declared, not inferred from ad hoc conventions;
• packer build must use that declaration to decide whether preload data is emitted into the runtime-facing artifact contract.
• preload.enabled should be the required runtime-relevant boolean;
• richer packer-side preload metadata may exist, but it must not change runtime behavior until separately specified.

Current recommended shape:

{
  "preload": {
    "enabled": true,
    "policy": "boot_critical"
  }
}

Direction:

• enabled is the normative yes/no input for runtime preload emission;
• optional fields such as policy are packer-side hints for Studio, diagnostics, planning, or future evolution;
• packer-side preload hints must not silently alter the current runtime-facing preload contract.

Expected Decisions to Produce

1. Common asset.json schema boundary.
2. Raw versus virtual asset contract.
3. Versioning strategy for asset format specs.
4. Rules for defaults and explicit materialization.
5. Multi-input asset declaration model for atlas, bank, and similar grouped assets.
6. Explicit separation between output format and codec in the asset contract.
7. Asset-level preload declaration model.

Expected Spec Follow-up

• Common asset specification spec.
• Virtual asset contract spec.
• Format-specific specs such as TILES/indexed_v1.

Non-Goals

• Final CLI UX for authoring these files.
• Incremental build internals.
• Cartridge builder consumption details.