prometeu-studio/docs/packer/agendas/01.3. Build Artifacts and Deterministic Packing Agenda.md

Build Artifacts and Deterministic Packing Agenda

Status

Open

Purpose

Close the contract for packer build outputs and the determinism rules that make them reproducible.

Context

The draft proposes two core build artifacts:

• build/assets.pa
• build/asset_table.json

At least one of these artifacts must form a documented interface that ../runtime can consume safely. That runtime-facing contract should be specified before the implementation hardens around incidental file structure.

It also states strong determinism requirements:

• deterministic asset order,
• deterministic derived outputs,
• explicit materialization of inferred defaults.

This is a strong basis for normative packer output specs.

Source Sections

• 8. Build Artifacts Produced by the Packer
• 9. Determinism Rules

Runtime Normative Inputs

From ../runtime/docs/runtime/specs/13-cartridge.md:

• assets.pa is the runtime-facing artifact;
• assets.pa v1 is an autocontained binary with:
  • fixed binary prelude,
  • JSON header,
  • binary payload region;
• the fixed prelude contains, at minimum:
  • magic,
  • schema_version,
  • header_len,
  • payload_offset;
• the JSON header carries:
  • asset_table,
  • preload.

From ../runtime/docs/runtime/specs/15-asset-management.md:

• asset_table entries currently expose:
  • asset_id,
  • asset_name,
  • bank_type,
  • offset,
  • size,
  • decoded_size,
  • codec,
  • metadata;
• offset is relative to the payload region inside assets.pa, not to the start of the full file;
• preload is boot-time input only;
• runtime loading is based on open_slice over payload slices;
• the runtime must not require the entire payload to stay resident in RAM.

These are already normative runtime-facing requirements and should be treated as baseline constraints for packer output design.

Key Questions

1. How should the packer spec mirror the already normative assets.pa v1 envelope from runtime specs 13 and 15?
2. Which fields in asset_table.json are still tooling-only if the runtime-facing contract lives primarily inside assets.pa?
3. Is asset order always asset_id order, or can format-specific constraints override it?
4. How should alignment be expressed and validated?
5. What exactly counts as determinism for virtual asset pipelines?
6. Which inferred values must be written back versus only emitted in build outputs?
7. Which packer-side metadata is intentionally excluded from the runtime-facing contract?
8. How should packer document preload lifecycle and offset semantics so they match runtime reader behavior?

Options

Option A

Keep assets.pa simple and push structure into asset_table.json.

Option B

Embed more self-description into assets.pa itself.

Tradeoffs

• Option A keeps runtime payload compact and keeps metadata easier to evolve.
• Option A matches the current draft direction and reduces double-modeling.
• Option B may help standalone introspection, but it risks splitting authority across two artifacts.

Recommendation

Adopt Option A and make asset_table.json the authoritative descriptor for ROM slice structure.

Expected Decisions to Produce

1. v1 artifact boundary and ownership.
2. Deterministic ordering and alignment rules.
3. Descriptor schema responsibilities.
4. Materialization requirements for inferred values.
5. Runtime-facing artifact contract and reader expectations.
6. Packer-side restatement of the runtime-owned assets.pa envelope and slice semantics.

Expected Spec Follow-up

• Packed ROM artifact spec.
• Asset table descriptor spec.
• Determinism and reproducibility spec.
• Runtime consumption interface spec.

Non-Goals

• Asset workspace mutation commands.
• Quarantine behavior.
• Builder packaging flow.