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

Open

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.

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?

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.

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.

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.