Intrepid/prometeu-studio
Intrepid/prometeu-studio
3
0
Fork 0
Code Pull Requests 1 Activity

clean up

Browse Source
This commit is contained in:
bQUARKz 2026-03-11 09:51:43 +00:00
parent e3389e78b6
commit 11ca697fa4
Signed by: bquarkz
SSH Key Fingerprint: SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
24 changed files with 23 additions and 2622 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
docs/packer/README.md
View File

@ -1,6 +1,6 @@
# Packer Documentation
This directory contains the working, planning, and normative documentation for the `packer` domain.
This directory contains the working, planning, normative, and didactic documentation for the `packer` domain.
`packer` is a standalone domain. It follows the same documentary cycle used elsewhere in the repository:
@ -35,7 +35,7 @@ This document is useful as a draft source, but it should not become a permanent
### `agendas/`
`agendas/` contains open packer topics.
`agendas/` is a transient staging area for open packer topics.
Use it to:
@ -45,10 +45,11 @@ Use it to:
- drive discussions toward a decision.
An agenda is a discussion artifact, not a final contract.
When a topic is fully propagated into specs and learn, the corresponding agenda should leave the retained set.
### `decisions/`
`decisions/` contains closed packer decision records.
`decisions/` is a transient staging area for closed packer decisions before full consolidation.
Use it to:
@ -58,6 +59,7 @@ Use it to:
- identify which specs, plans, or code paths must be updated.
Decisions close debate. They are not brainstorming notes.
Once their content is fully absorbed into specs and learn, they should not be retained just as historical residue.
### `pull-requests/`
@ -107,10 +109,12 @@ The preferred packer documentation flow is:
## Practical Rule
- `agendas/` stores open questions.
- `decisions/` stores closed answers.
- `agendas/` stores currently open questions only.
- `decisions/` stores only decisions that still need propagation.
- `pull-requests/` stores execution plans.
- `specs/` stores the normative packer contract.
- `learn/` stores teaching-oriented consolidation.
The current packer core has already been consolidated into [`specs/`](./specs/) and [`learn/`](./learn/). The `agendas/` and `decisions/` directories remain available for future cycles.
If implementation exposes a missing architectural choice, stop and return to `agendas/` or `decisions/`.

113
docs/packer/agendas/01.0. Packer Scope, Boundaries, and Golden Pipeline Agenda.md
View File

@ -1,113 +0,0 @@
# Packer Scope, Boundaries, and Golden Pipeline Agenda
## Status
Open
## Purpose
Define the architectural boundary of the `packer` domain before the draft is decomposed into normative specs.
## Context
`Prometeu Packer.md` already establishes a strong direction:
- packer owns asset management,
- packer produces `build/assets.pa`,
- packer produces `build/asset_table.json`,
- packer must produce artifacts that can be consumed by `../runtime`,
- packer operations must be available as Studio-integrated services,
- packer does not build the cartridge,
- shipper consumes packer outputs later.
This is a good draft direction, but it still needs to be closed as an explicit domain contract.
The interface between packer outputs and `../runtime` should be documented first, before it is treated as implementation detail.
The runtime already exposes normative constraints that the packer must treat as upstream contract, not as optional design space.
## Source Sections
- `1. Goals and Non-Goals`
- `2. Repository / Project Layout (Golden Pipeline)`
- `3. Crate Topology`
- `15. Integration with Cartridge Shipper`
## Runtime Normative Inputs
From `../runtime/docs/runtime/specs/13-cartridge.md`:
- `assets.pa` is the runtime-facing asset artifact consumed by the current runtime;
- cartridges that declare `Asset` capability must provide valid `assets.pa`;
- runtime bootstrap must fail early when the asset capability is declared but `assets.pa` is missing or invalid;
- `assets.pa` v1 is autocontained and contains:
- fixed binary prelude,
- JSON header,
- binary payload region.
From `../runtime/docs/runtime/specs/15-asset-management.md`:
- the runtime consumes `assets.pa` as the primary cartridge asset artifact;
- the runtime-facing contract is bank-centric;
- `asset_table` and `preload` are loaded from inside `assets.pa`;
- payload slices are resolved relative to `payload_offset`;
- the runtime must not require the full `assets.pa` payload to remain resident in RAM as its baseline operating mode.
These points are already normative on the runtime side and should be treated as hard inputs for packer-side discussion.
## Key Questions
1. What is the exact ownership boundary between `packer` and `shipper`?
2. Should `packer` be defined purely as offline asset tooling, or as a Studio-integrated service surface with optional CLI adapters?
3. Which project directories are normative for packer behavior, and which are merely conventional?
4. Should packer be allowed to read `src/` or compiler outputs at all, or only operate on `assets/` plus project metadata?
5. Is `build/asset_table.json` a packer-owned artifact contract or a shared cross-domain contract?
6. Which packer-produced artifact is the runtime-facing contract, and what must be documented before code depends on it?
7. Which parts of the runtime-facing `assets.pa` contract are already closed by runtime specs and therefore outside packer-side redesign scope?
## Options
### Option A
Keep packer strictly scoped to `assets/` workspace management and production of packer outputs only.
### Option B
Allow packer to absorb more cartridge preparation responsibilities over time.
## Tradeoffs
- Option A keeps the architecture cleaner and reduces domain leakage.
- Option A makes shipper integration more explicit and easier to spec.
- Option B may feel convenient short-term, but it risks collapsing packer and shipper concerns into one blurred tool boundary.
## Recommendation
Adopt Option A and make the packer/shipper boundary explicit as a first-class architectural invariant.
Also adopt this operational direction:
- packer capabilities should be modeled as services first;
- any CLI surface should be treated as an adapter over those services, not as the architectural center of the domain.
## Expected Decisions to Produce
1. Packer domain boundary.
2. Ownership of `assets.pa` and `asset_table.json`.
3. Relationship between CLI, core library, and future integrations.
3. Relationship between services, CLI adapters, and future integrations.
4. Normative project layout expectations.
5. Runtime-facing artifact ownership and documentation responsibility.
6. Explicit statement that runtime specs 13 and 15 are upstream constraints for `assets.pa`.
## Expected Spec Follow-up
- Packer domain charter or overview spec.
- Shipper integration spec.
- Artifact ownership and responsibility spec.
- Runtime artifact interface spec.
## Non-Goals
- Defining the detailed schema of `asset_table.json`.
- Defining individual asset formats.
- Designing cartridge shipper internals.

132
docs/packer/agendas/01.1. Asset Workspace, Registry, and Stable Identity Agenda.md
View File

@ -1,132 +0,0 @@
# Asset Workspace, Registry, and Stable Identity Agenda
## Status
Closed
Resolved by [`001-asset-workspace-registry-and-stable-identity-decision.md`](../decisions/001-asset-workspace-registry-and-stable-identity-decision.md).
## Purpose
Close the packer model for managed assets, registry truth, anchor files, and stable asset identity.
## Context
The draft proposes a Git-like workspace:
- `assets/` may be messy,
- `assets/.prometeu/index.json` is the source of truth,
- a managed asset is anchored by `asset.json`,
- each asset has `asset_id` and `asset_uuid`.
This is the core model of the packer. If it stays vague, all later specs become unstable.
For this agenda, the intended unit of management is the asset root, not each individual source file.
That means one managed asset should have one dedicated root directory containing one anchor `asset.json`, while that asset may aggregate many internal input files.
Example consequence:
- an image atlas asset may own many sprite source images and palette files under the same asset root;
- those internal files are inputs of the managed asset, not separate managed assets by default.
## Source Sections
- `4. Mental Model: A "Git-like" Asset Workspace`
- `5. Core Concepts`
- `6. Directory Structure and Control Files`
## Key Questions
1. Is `index.json` the sole source of truth, or does `asset.json` also carry authority?
2. What is the exact relationship between registry entry and anchor file?
3. Which fields are stable identity and which are mutable presentation?
4. Can an asset move directories without changing identity?
5. How should orphaned `asset.json` files be interpreted?
6. What is the normative lifecycle of `asset_id` allocation and persistence?
7. Is the unit of management a single source file or an asset root directory containing many inputs?
## Closed Answers
The following points are considered directionally closed for this agenda:
1. `index.json` is the authoritative registry of managed assets.
2. `asset.json` is the asset-local declaration anchored at the asset root.
3. One managed asset maps to one asset root directory containing exactly one anchor `asset.json`.
4. A managed asset may aggregate many internal input files without making each input a separate managed asset.
5. `asset_id` is stable within the project and must never be silently recycled.
6. Move or rename of the asset root must not change `asset_id` or `asset_uuid`.
7. Orphaned `asset.json` files do not enter the build automatically; they are surfaced by diagnostics and adoption flows.
## Allocation Direction
`asset_id` should be allocated by a strictly monotonic project-local allocator recorded in `index.json`.
Current recommendation:
- no reuse of prior IDs;
- no silent rollback of the counter;
- allocator state persisted in `index.json`;
- if creation metadata is useful, record creation date separately instead of encoding date logic into the identity itself.
Rationale:
- the runtime-facing ID should stay simple and stable;
- a plain monotonic numeric allocator is easier to audit and reason about than a day-scoped composite allocator;
- practical `u32` exhaustion is not a realistic concern for normal project lifecycles.
## Options
### Option A
Treat `index.json` as the authoritative registry and `asset.json` as the asset-local contract.
### Option B
Treat both as co-authoritative and reconcile divergences dynamically.
## Tradeoffs
- Option A is easier to reason about and easier to validate.
- Option A enables clean diagnostics when local anchor and registry diverge.
- Option B increases reconciliation complexity and invites ambiguous conflict handling.
## Recommendation
Adopt Option A:
- `index.json` is the authoritative registry,
- `asset.json` is the authoritative asset-local declaration,
- divergence between them must be explicit and diagnosable.
Also adopt this structural rule:
- one managed asset maps to one asset root directory;
- that asset root contains exactly one anchor `asset.json`;
- the asset may contain many internal input files without making each input a separate managed asset.
Also adopt this identity rule:
- `asset_id` is allocated once and never reused silently within the project;
- allocator state is registry-owned;
- date or audit metadata may exist, but it should not complicate the runtime-facing identity model unless a concrete need appears later.
## Expected Decisions to Produce
1. Registry authority model.
2. Managed asset lifecycle.
3. Identity model for `asset_id`, `asset_uuid`, name, and path.
4. Rules for relocation, adoption, forgetting, and removal.
5. Asset root as the normative unit of management.
6. Monotonic, non-recycled `asset_id` allocation owned by the registry.
## Expected Spec Follow-up
- Workspace and control files spec.
- Managed asset and identity spec.
- Registry consistency and validation spec.
## Non-Goals
- Detailed build output layout.
- CLI syntax for every command.
- Format-specific `asset.json` payload definitions.

140
docs/packer/agendas/01.2. Asset Specification, Raw Assets, and Virtual Asset Contract Agenda.md
View File

@ -1,140 +0,0 @@
# Asset Specification, Raw Assets, and Virtual Asset Contract Agenda
## Status
Closed
Resolved by [`002-asset-specification-raw-assets-and-virtual-asset-contract-decision.md`](../decisions/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:
```json
{
"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 shipper consumption details.

179
docs/packer/agendas/01.3. Build Artifacts and Deterministic Packing Agenda.md
View File

@ -1,179 +0,0 @@
# Build Artifacts and Deterministic Packing Agenda
## Status
Closed
Resolved by [`003-build-artifacts-and-deterministic-packing-decision.md`](../decisions/003-build-artifacts-and-deterministic-packing-decision.md).
## 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.
For this agenda, the intended direction is:
- `assets.pa` is the authoritative runtime-facing artifact;
- `build/asset_table.json` is a companion tooling artifact derived from the same build result;
- runtime must not depend on `build/asset_table.json` as its primary source of truth.
Current runtime code now resolves preload by `asset_id`, but game-facing runtime APIs still refer to assets by `asset_name`.
Therefore this agenda distinguishes:
- `asset_id` as stable artifact identity for preload/bootstrap and asset-table integrity;
- `asset_name` as logical API-level identifier used by game/runtime-facing calls today.
This agenda does not introduce a second runtime-only asset identity.
The `asset_id` emitted by the packer is the same `asset_id` used in the runtime-facing artifact contract.
## 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 `build/asset_table.json` are companion tooling data versus runtime-facing contract data?
3. Should global asset packing order be deterministic by `asset_id`, or influenced by usage and format-specific heuristics?
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?
9. How should per-asset preload declarations be transformed into the `preload` section of `assets.pa` deterministically?
10. How should the packer preserve both `asset_id` integrity and `asset_name` lookup semantics in runtime-facing artifacts?
11. Should `asset_table` be modeled as a deterministically ordered asset list that preserves packer `asset_id` values end-to-end?
12. Which envelope fields are runtime-validated versus emitted only for Studio/tooling use?
## Options
### Option A
Keep `assets.pa` as the authoritative autocontained runtime-facing artifact and emit `build/asset_table.json` as a derived companion artifact for Studio and tooling.
### Option B
Keep runtime-facing structure split across `assets.pa` and `build/asset_table.json`.
## Tradeoffs
- Option A matches the runtime specs already in force.
- Option A keeps runtime authority in one artifact and prevents contract drift.
- Option A still allows rich tooling through a derived companion file.
- Option B risks splitting authority across artifacts and making runtime/tooling divergence easier.
## Recommendation
Adopt Option A with these fixed directions:
- `assets.pa` is the authoritative runtime-facing artifact;
- the `assets.pa` header is the authoritative runtime-facing descriptor;
- `build/asset_table.json` is a derived companion artifact for Studio, debugging, inspection, and shipper/tooling integration;
- global packing order is deterministic by increasing `asset_id`;
- preload emission is derived deterministically from per-asset `preload.enabled`;
- alignment exists only when explicitly required by spec;
- offsets are always relative to the payload region, never to the start of the full file;
- checksum is not part of the baseline `assets.pa` envelope contract.
Also adopt this performance direction:
- usage-based hot-first packing is not part of the baseline contract;
- deterministic stable ordering is preferred over heuristic physical reordering;
- future locality optimization may be introduced only through an explicit later decision and spec, not as an implementation shortcut now.
Also adopt this identity direction:
- runtime-facing preload entries should migrate to stable `asset_id` instead of mutable `asset_name`;
- runtime-facing preload/bootstrap integrity should treat `asset_id` as primary identity;
- `asset_name` remains present in `asset_table` as logical descriptive and API-facing metadata used by current runtime/game-facing calls;
- `asset_table` should be generated deterministically on every build from the current managed asset set;
- `asset_table` should be emitted as a deterministically ordered list of asset entries;
- the runtime-facing `asset_id` is exactly the stable `asset_id` allocated by the packer registry;
- stable cross-build identity comes from `asset_id`, not from table position;
- rename of `asset_name` is therefore an API-visible/content-visible change, but not an identity change.
Also adopt this companion-artifact direction:
- `build/asset_table.json` should mirror the runtime-facing header data 1:1 for debugging and inspection;
- if richer tooling artifacts are needed, they should be emitted as separate files instead of overloading `build/asset_table.json`.
## 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.
7. Deterministic mapping from asset declarations to runtime preload data.
8. Explicit exclusion of usage-based packing heuristics from the baseline contract.
9. Migration of preload/bootstrap integrity toward `asset_id`-based identity while preserving `asset_name` as current API-facing metadata.
10. Deterministically ordered `asset_table` preserving packer `asset_id` values end-to-end.
11. Separation between runtime-validated envelope fields and non-envelope tooling concerns.
## 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.
- Shipper packaging flow.

82
docs/packer/agendas/01.4. Diagnostics, Doctor, Quarantine, and Workspace Hygiene Agenda.md
View File

@ -1,82 +0,0 @@
# Diagnostics, Doctor, Quarantine, and Workspace Hygiene Agenda
## Status
Closed
Resolved by [`004-diagnostics-doctor-quarantine-and-workspace-hygiene-decision.md`](../decisions/004-diagnostics-doctor-quarantine-and-workspace-hygiene-decision.md).
## Purpose
Define the packer as a "sanity guardian" with explicit diagnostics, workspace scanning, quarantine, and garbage collection behavior.
## Context
One of the strongest ideas in the draft is that packer should help users survive a messy `assets/` workspace.
The document already sketches:
- structured diagnostics,
- `doctor` modes,
- orphan and duplicate detection,
- quarantine,
- garbage collection.
This deserves a dedicated decision because it strongly shapes user trust in the tool.
## Source Sections
- `10. Diagnostics and the "Sanity Guardian" Chain`
- `12. Quarantine and Garbage Collection`
## Key Questions
1. Which diagnostics are build-blocking versus advisory?
2. What is the normative distinction between registry validation and workspace hygiene scanning?
3. Which automatic fixes are considered safe?
4. What operations require explicit consent?
5. How should quarantine be modeled: reversible staging area or semi-managed trash bin?
6. How aggressive should duplicate and orphan detection be?
## Options
### Option A
Keep a strict separation:
- registry errors block builds,
- workspace hygiene warnings inform users,
- destructive or moving operations always require explicit consent.
### Option B
Let doctor apply broader automatic remediation by default.
## Tradeoffs
- Option A is safer and easier to trust.
- Option A aligns with the draft's explicit-user-consent direction.
- Option B may save time in some cases, but it raises risk of surprising workspace mutations.
## Recommendation
Adopt Option A and make reversibility plus explicit consent core packer invariants.
## Expected Decisions to Produce
1. Diagnostic classes and severities.
2. Scope and modes of `doctor`.
3. Safety model for `--fix`, `gc`, and quarantine.
4. Workspace hygiene responsibilities of the packer.
## Expected Spec Follow-up
- Diagnostics contract spec.
- Doctor and workspace scan spec.
- Quarantine and garbage collection spec.
## Non-Goals
- Detailed asset format validation rules.
- Final watch mode design.
- Runtime-facing artifact schemas.

79
docs/packer/agendas/01.5. Incremental Build, Cache, and Watch Model Agenda.md
View File

@ -1,79 +0,0 @@
# Incremental Build, Cache, and Watch Model Agenda
## Status
Closed
Resolved by [`005-incremental-build-cache-and-watch-model-decision.md`](../decisions/005-incremental-build-cache-and-watch-model-decision.md).
## Purpose
Define how packer caches, fingerprints, and optional watch behavior should work without compromising determinism.
## Context
The draft proposes:
- fingerprint tracking in `assets/.prometeu/cache/fingerprints.json`,
- incremental rebuilds,
- strong hashing,
- optional watch mode.
This area is operationally important but easy to underspecify.
## Source Sections
- `11. Incremental Build, Cache, and Fingerprints`
- `13.10 prometeu packer watch`
## Key Questions
1. Which fingerprints are authoritative for cache invalidation?
2. When are `mtime` and size only hints versus hard cache keys?
3. What outputs may be reused from cache, and under which conditions?
4. Does watch mode belong in v1 spec or only as non-normative future work?
5. How should cache invalidation be surfaced to users and diagnostics?
6. How do we guarantee that incremental behavior never changes final outputs?
## Options
### Option A
Specify cache behavior conservatively and keep watch mode optional or non-normative in the first wave.
### Option B
Make watch mode and aggressive incremental behavior part of the early normative contract.
## Tradeoffs
- Option A reduces spec risk and keeps determinism easier to enforce.
- Option A allows cache internals to evolve while the artifact contract stabilizes first.
- Option B may be attractive for UX, but it increases the amount of behavior that must be frozen too early.
## Recommendation
Adopt Option A:
- deterministic outputs first,
- conservative cache spec,
- watch mode optional until the underlying invariants are stable.
## Expected Decisions to Produce
1. Cache authority and invalidation model.
2. Fingerprint contract.
3. Normative versus non-normative status of watch mode.
4. Safety rules for incremental reuse.
## Expected Spec Follow-up
- Cache and fingerprints spec.
- Incremental build guarantees spec.
- Optional watch mode spec or deferred note.
## Non-Goals
- Full CLI command catalog.
- Asset registry identity rules.
- Cartridge shipper integration.

118
docs/packer/agendas/01.6. CLI Surface and Mutating Operations Agenda.md
View File

@ -1,118 +0,0 @@
# CLI Surface and Mutating Operations Agenda
## Status
Closed
Resolved by [`006-studio-first-asset-services-and-event-lane-decision.md`](../decisions/006-studio-first-asset-services-and-event-lane-decision.md).
## Purpose
Define the stable Studio-facing service contract for packer operations, especially operations that mutate registry state or user files.
## Context
The draft already lists a substantial command surface:
- `init`
- `add`
- `adopt`
- `forget`
- `rm`
- `list`
- `show`
- `doctor`
- `build`
- `watch`
- `gc`
- `quarantine`
Historically, packer was framed as a CLI-first tool.
The current target is different:
- packer should be fully integrated with Studio;
- asset UI and packer services should evolve together;
- operations should exist as Studio-consumable services first;
- asset workflows should be observable through a dedicated background event lane for UI integration;
- CLI, if retained, should be treated as a later adapter rather than the design center.
This means the architectural work should focus on service semantics and UI integration points first, not on freezing a command-line contract too early.
## Source Sections
- `13. CLI Commands (Comprehensive)`
## Key Questions
1. Which packer operations are core Studio services in v1 and which are later capabilities?
2. Which identifiers should Studio-facing services accept for normal asset workflows: name, id, uuid, root path?
3. Which operations mutate registry only versus mutate workspace files?
4. What requires explicit confirmation, preview, or staged apply behavior in Studio?
5. How should safe fix flows be exposed as service operations rather than CLI flags?
6. Which responses must be structured for UI consumption and automation?
7. What, if anything, should remain CLI-specific in the future adapter layer?
8. Should assets have a dedicated background event lane that reports changes, diagnostics, and build activity to the UI?
## Options
### Option A
Define a minimal stable v1 Studio service surface and mark the rest as future or optional.
### Option B
Freeze a larger command catalog immediately.
## Tradeoffs
- Option A lowers the early compatibility burden.
- Option A matches the Studio-integrated direction better because services and UI can stabilize together before any CLI freeze.
- Option A gives room to validate mutating operations safely before promising too much.
- Option B gives a bigger product surface up front, but it increases long-term compatibility cost around the wrong adapter.
## Recommendation
Adopt Option A and distinguish:
- required core services,
- optional future adapters,
- future operations not yet in the normative contract.
Current design target:
- Studio integration is primary;
- asset UI and packer services should be designed together;
- service contracts should describe intent, preview, apply, and result models suitable for UI workflows;
- asset-oriented operations should publish structured background events suitable for logs, progress, and live UI refresh;
- CLI should not drive the core architecture in this phase.
Also adopt this integration direction:
- the system should have a dedicated asset workspace event lane;
- this lane observes relevant asset and registry changes, triggers analysis/rebuild workflows as appropriate, and reports structured events to the UI;
- the architectural contract is the event/reporting surface, not a commitment to a specific threading primitive;
- dangerous mutations still require explicit user intent and must not be silently auto-applied by the background lane.
## Expected Decisions to Produce
1. Core v1 Studio service set.
2. Mutation safety and preview/apply model.
3. Identifier resolution rules.
4. Structured response contracts for UI and automation.
5. Boundary between core services and future adapters.
6. Asset workspace event lane and structured event model for UI reporting.
## Expected Spec Follow-up
- Service operation contract spec.
- Studio asset workflow integration spec.
- Mutation and confirmation policy spec.
- Structured response/output contract spec.
- Asset event/reporting integration spec.
## Non-Goals
- Asset payload binary layout.
- Format-specific `asset.json` rules.
- Detailed cache internals.
- Freezing a comprehensive CLI contract in the current phase.

103
docs/packer/agendas/01.7. Builder Integration, Versioning, and Trust Model Agenda.md
View File

@ -1,103 +0,0 @@
# Shipper Integration, Versioning, and Trust Model Agenda
## Status
Closed
Resolved by [`007-shipper-integration-versioning-and-trust-model-decision.md`](../decisions/007-shipper-integration-versioning-and-trust-model-decision.md).
## Purpose
Close the cross-domain contracts around shipper integration, schema versioning, migrations, and the packer trust model.
## Context
The tail of the draft contains several cross-cutting commitments:
- shipper consumes packer outputs,
- `../runtime` must be able to read the packer-produced artifact contract,
- multiple JSON artifacts carry `schema_version`,
- packer must migrate older schemas or emit actionable diagnostics,
- packer is offline tooling and must not execute untrusted scripts.
These topics are cross-domain and should be discussed together before hardening the specs.
The first step should be to document the runtime-facing interface explicitly instead of leaving it implicit in tooling behavior.
## Source Sections
- `15. Integration with Cartridge Shipper`
- `16. Compatibility and Versioning`
- `17. Security and Trust Model`
## Runtime Normative Inputs
From `../runtime/docs/runtime/specs/13-cartridge.md`:
- cartridges may contain optional `assets.pa`;
- when `Asset` capability is declared, valid `assets.pa` is required before asset bootstrap;
- runtime validation failure must happen before preload execution;
- `assets.pa` is the runtime-facing asset artifact for the current runtime.
From `../runtime/docs/runtime/specs/15-asset-management.md`:
- the runtime-facing asset model is bank-centric;
- `preload` is boot-time input only;
- runtime residency and bank ownership are independent from VM heap ownership;
- asset loading uses slice-based access over `assets.pa`;
- schema-bearing runtime-facing structures already exist and must be versioned carefully.
These runtime specs already constrain packer evolution. The packer discussion should focus on how to honor and document this contract on the tooling side.
## Key Questions
1. Which integration points with shipper are packer-owned versus shared contracts?
2. Which artifacts need explicit migration policy?
3. Is backward compatibility required for all schema versions or only within a support window?
4. What counts as trusted configuration versus untrusted input data?
5. Can packer ever execute plugin-like transformations, or is that forbidden by architecture?
6. How should migration failures be surfaced to users and CI?
7. How should the runtime reader contract be versioned and documented?
8. Which compatibility guarantees apply specifically to `../runtime` consumption?
9. Which parts of the runtime-facing contract are owned by runtime specs versus packer-owned companion specs?
## Options
### Option A
Keep shipper integration narrow, schema versioning explicit, and trust model conservative.
### Option B
Allow broader extensibility and looser compatibility commitments.
## Tradeoffs
- Option A is easier to secure and specify.
- Option A supports reliable CI and migration diagnostics.
- Option B may feel more flexible, but it introduces major review and safety burden early.
## Recommendation
Adopt Option A and treat schema evolution plus trust boundaries as first-class contracts.
## Expected Decisions to Produce
1. Shipper integration boundary.
2. Schema versioning and migration policy.
3. Compatibility guarantees.
4. Security and trust invariants.
5. Runtime consumption contract and versioning boundary.
6. Ownership split between runtime normative specs and packer-side companion documentation.
## Expected Spec Follow-up
- Shipper integration spec.
- Schema versioning and migration spec.
- Security and trust model spec.
- Runtime reader and compatibility interface spec.
## Non-Goals
- CLI ergonomics for all commands.
- Detailed asset format transformation pipelines.
- Workspace hygiene behavior.

2
docs/packer/agendas/README.md
View File

@ -6,7 +6,7 @@ This directory contains active packer discussion agendas.
There are currently no active packer agendas.
The first packer agenda wave (`01.0` through `01.7`) has been closed into decision records under [`../decisions/`](../decisions/).
The first packer agenda wave was consolidated into normative specs under [`../specs/`](../specs/) and didactic material under [`../learn/`](../learn/).
## Purpose

197
docs/packer/decisions/001-asset-workspace-registry-and-stable-identity-decision.md
View File

@ -1,197 +0,0 @@
# Asset Workspace, Registry, and Stable Identity Decision
## Status
Accepted
## Date
2026-03-11
## Context
This decision closes the architectural questions raised in [`01.1. Asset Workspace, Registry, and Stable Identity Agenda`](../agendas/01.1.%20Asset%20Workspace,%20Registry,%20and%20Stable%20Identity%20Agenda.md).
The packer needs a stable model for:
- what counts as a managed asset;
- how local asset declaration relates to workspace registry state;
- how asset identity survives rename and relocation;
- how adoption and diagnostics distinguish registered from unregistered asset roots.
If this model remains ambiguous, later specs for `asset.json`, virtual assets, diagnostics, build outputs, and Studio services will inherit unstable semantics.
## Decision
The packer adopts a `registry-authoritative, anchor-declared, identity-stable, path-mutable` model.
### 1. Managed asset unit
A managed asset is one asset root directory.
Rules:
- one managed asset maps to one dedicated asset root directory;
- one asset root contains exactly one anchor `asset.json`;
- files and subdirectories under that root are inputs or support files of that managed asset unless explicitly modeled otherwise in future specs;
- individual source files are not separate managed assets by default.
This allows grouped assets such as atlases, image banks, or palette-driven bundles to be modeled as one managed asset with many inputs.
### 2. Registry authority
`assets/.prometeu/index.json` is the authoritative workspace registry for managed assets.
It defines:
- which assets are officially managed by the packer;
- their stable project-local identities;
- their current registered root locations;
- allocator state and registry-owned metadata.
If an asset root is not present in `index.json`, it is not part of the managed build set.
### 3. Asset-local declaration
`asset.json` is the asset-local declaration anchored at the asset root.
It defines the local declaration of the asset, including the asset contract that later specs will refine.
`asset.json` does not, by itself, make an asset managed.
Registration and build inclusion remain registry-owned concerns.
### 4. Identity model
Each managed asset has:
- `asset_id`: stable project-local identity;
- `asset_uuid`: stable long-lived identity for tooling and migration scenarios.
The following are not primary identity:
- display name;
- filesystem path;
- internal input filenames.
Name and path are mutable presentation or location fields.
However, `asset_name` may still participate in authoring and runtime-facing APIs as a logical reference label.
That does not make it the stable identity of the asset.
Practical consequence:
- changing `asset_name` does not create a new asset identity;
- but changing `asset_name` may still require source-level or tooling-level reference updates where game/runtime APIs refer to assets by name.
### 5. Relocation and rename
Moving or renaming an asset root does not create a new asset.
Rules:
- `asset_id` must remain unchanged;
- `asset_uuid` must remain unchanged;
- registry location is updated to the new asset root;
- this is treated as relocation, not recreation.
### 6. Orphan anchor behavior
An `asset.json` without a corresponding registry entry is an orphan asset declaration.
Rules:
- it does not enter the build automatically;
- it must be surfaced by workspace diagnostics such as `doctor --workspace`;
- it may be incorporated only through explicit adoption flow.
### 7. `asset_id` allocation
`asset_id` allocation is registry-owned and strictly monotonic within the project.
Rules:
- allocation happens once at registration time;
- previously issued IDs must not be silently recycled;
- allocator state is persisted in `index.json`;
- allocator rollback is not allowed as normal behavior.
If audit metadata is useful, it should be recorded separately, for example as creation metadata.
Time should not be encoded into the runtime-facing identity model without a concrete future need.
### 8. Manual copy and identity collision
Manual copy of an asset root that duplicates identity-bearing content must not be reconciled implicitly.
Rules:
- packer must surface identity collision or duplicate-anchor diagnostics explicitly;
- packer must not silently guess whether the copy is a rename, clone, or replacement;
- resolution must happen through explicit user action or future dedicated workflows.
## Invariants and Constraints
The following invariants now apply:
1. One managed asset equals one asset root.
2. One managed asset root contains exactly one anchor `asset.json`.
3. `index.json` is the authoritative managed registry.
4. `asset.json` is the authoritative asset-local declaration.
5. `asset_id` is stable, monotonic, and non-recycled.
6. `asset_uuid` is stable across relocation.
7. Path and display name are mutable and not primary identity.
8. Orphan `asset.json` declarations are diagnosable but not build-active.
9. Copy-induced identity collisions are explicit errors, not heuristic reconciliation cases.
## Explicit Non-Decisions
This decision does not yet define:
- the detailed schema of `asset.json`;
- the field-level boundary between common asset declaration and format-specific declaration;
- CLI or Studio service APIs;
- detailed adoption UX;
- detailed garbage collection and quarantine behavior;
- runtime artifact formats such as `assets.pa`.
Those belong to later decisions and specs.
## Propagation Targets
This decision must propagate to:
- packer workspace and control files specs;
- packer managed asset and identity specs;
- packer registry consistency and diagnostics specs;
- future Studio service contracts for adoption, registration, move, rename, and inspection;
- future implementation of registry persistence and identity allocation.
## Validation Notes
Example: grouped atlas asset
```text
assets/
ui_atlas/
asset.json
sprites/
confirm.png
cancel.png
palettes/
ui_main.pal
```
This is one managed asset, not many.
The internal files are inputs of the asset root declared by `asset.json`.
Example: relocation
- `assets/ui_atlas/` moves to `assets/ui/common_atlas/`
- `asset_id` remains the same
- `asset_uuid` remains the same
- only the registered root path changes
Example: orphan anchor
- `assets/wip/new_bank/asset.json` exists
- no corresponding registry entry exists in `index.json`
- the asset is diagnosable and adoptable, but not part of the managed build set

282
docs/packer/decisions/002-asset-specification-raw-assets-and-virtual-asset-contract-decision.md
View File

@ -1,282 +0,0 @@
# Asset Specification, Raw Assets, and Virtual Asset Contract Decision
## Status
Accepted
## Date
2026-03-11
## Context
This decision closes the architectural questions raised in [`01.2. Asset Specification, Raw Assets, and Virtual Asset Contract Agenda`](../agendas/01.2.%20Asset%20Specification,%20Raw%20Assets,%20and%20Virtual%20Asset%20Contract%20Agenda.md).
The packer needs a stable baseline contract for `asset.json` before detailed format-specific specs are written.
This contract must:
- support one managed asset root with many internal inputs;
- distinguish raw assets from virtual assets without making the common schema monolithic;
- expose runtime-relevant output information explicitly;
- declare preload intent deterministically;
- leave room for future format families without coupling all formats together.
## Decision
The packer adopts a compact common `asset.json` contract with explicit separation between:
- authoring asset family;
- grouped input declaration;
- runtime-facing output contract;
- preload declaration;
- optional build/process hints.
### 1. Common top-level shape
The common `asset.json` contract includes these required top-level fields:
- `schema_version`
- `name`
- `type`
- `inputs`
- `output`
- `preload`
The common contract may additionally include:
- `build`
`build` is optional in the shared baseline schema.
### 2. Meaning of `type`
`type` identifies the authoring-side asset family.
It is not the runtime bank target.
Examples of valid family-style values:
- `image_bank`
- `sound_bank`
The runtime-facing technical target belongs in `output.format`, not in `type`.
`name` remains the required logical asset reference label.
Meaning:
- `name` is not the stable artifact identity;
- `name` is the human-facing and code-facing reference used by asset-oriented APIs unless a future compile-time rewrite model replaces it;
- renaming `name` is an API-visible change even though it does not change `asset_id`.
### 3. Input declaration model
`inputs` is a structured object keyed by semantic role.
Rules:
- each key identifies an input role such as `sprites`, `palettes`, or `sources`;
- each value is a list of paths;
- paths are relative to the asset root;
- even a single input is represented as a list, not as a scalar.
This avoids shape ambiguity and supports grouped virtual assets cleanly.
Example:
```json
"inputs": {
"sprites": [
"sprites/confirm.png",
"sprites/cancel.png"
],
"palettes": [
"palettes/ui_main.pal"
]
}
```
### 4. Output contract
`output` is the runtime-relevant output declaration.
The common baseline requires:
- `output.format`
- `output.codec`
`output.metadata` is optional in the common schema, but becomes required whenever the selected format spec requires additional normative parameters.
Meaning:
- `output.format` identifies the semantic/runtime format contract;
- `output.codec` identifies how payload bytes are stored for extraction and materialization;
- `output.metadata` carries format-specific runtime-relevant details.
Codec must remain explicit.
It must not be hidden inside format naming when it represents a distinct storage concern.
### 5. Raw and virtual asset contract
The common schema must support both raw and virtual assets.
Rules:
- raw assets may declare a direct input-to-output path with minimal build metadata;
- virtual assets may declare multiple grouped inputs and optional build/process configuration;
- the common schema remains small, while detailed format behavior is defined in dedicated format specs.
### 6. Build/process hints
`build` is optional and carries process-oriented configuration.
Rules:
- `build` may describe how the packer should transform or organize authoring inputs;
- if a parameter affects the runtime-facing output contract, it belongs in `output.metadata`;
- `build` must not become a hidden substitute for runtime-relevant output definition.
Practical interpretation:
- `output.metadata` describes the contract of the produced payload;
- `build` describes how the packer gets there.
### 7. Preload declaration
Each managed asset must declare preload intent explicitly.
The baseline shape is:
```json
"preload": {
"enabled": true
}
```
Rules:
- `preload.enabled` is required and boolean;
- preload participation is declared, not inferred;
- packer build uses this field to determine whether preload data is emitted into the runtime-facing artifact contract;
- richer preload policy fields are deferred to future decisions and must not be implied silently now.
### 8. Defaults and materialization
Defaults may exist in specs, but defaults that affect reproducibility, compatibility, preload, or runtime-visible output must not remain invisible.
Rules:
- runtime-relevant defaults should be materialized in `asset.json` whenever practical;
- if materialization occurs later in the pipeline, the resulting artifact must still expose the effective value explicitly;
- packer must not rely on hidden defaults to produce runtime-visible behavior.
### 9. Versioning boundary
Versioning is split by concern.
Rules:
- `asset.json` carries its own `schema_version`;
- registry schemas are versioned independently;
- runtime-facing artifact schemas are versioned independently;
- format contracts are versioned independently through `output.format` values such as `TILES/indexed_v1` or `SOUNDS/pcm16le_v1`.
This prevents unrelated schema evolution from being coupled together.
## Invariants and Constraints
The following invariants now apply:
1. The common `asset.json` contract remains compact.
2. `type` is authoring-side family identity, not runtime bank identity.
3. `inputs` is structured by semantic role.
4. Input path values are always lists.
5. `name` remains a logical asset reference label even though it is not the stable artifact identity.
6. `output.format` and `output.codec` are separate required concerns.
7. Runtime-relevant format details belong in `output.metadata`.
8. `build` is optional and must not hide runtime-facing output semantics.
9. `preload.enabled` is the only preload field closed in the current baseline.
10. Defaults affecting runtime-visible behavior must be materialized explicitly.
11. Format evolution is versioned independently from registry and artifact schema evolution.
## Explicit Non-Decisions
This decision does not yet define:
- the full field-level schema of each format family;
- richer preload policies beyond `preload.enabled`;
- globbing support, input discovery shortcuts, or non-path input locators;
- CLI or Studio editor UX for authoring `asset.json`;
- exact `assets.pa` payload layout details;
- exact runtime preload record encoding.
Those belong to later decisions and specs.
## Propagation Targets
This decision must propagate to:
- common asset declaration spec;
- virtual asset contract spec;
- format-specific specs such as `TILES/indexed_v1` and `SOUNDS/pcm16le_v1`;
- preload emission and artifact mapping specs;
- Studio service contracts for asset authoring and validation;
- future implementation of asset parsing, validation, and deterministic build planning.
## Validation Notes
Example: grouped image asset
```json
{
"schema_version": 1,
"name": "ui_atlas",
"type": "image_bank",
"inputs": {
"sprites": [
"sprites/confirm.png",
"sprites/cancel.png"
],
"palettes": [
"palettes/ui_main.pal"
]
},
"output": {
"format": "TILES/indexed_v1",
"codec": "RAW",
"metadata": {
"tile_size": [8, 8]
}
},
"preload": {
"enabled": true
},
"build": {
"layout": "atlas"
}
}
```
Example: grouped sound asset
```json
{
"schema_version": 1,
"name": "ui_sounds",
"type": "sound_bank",
"inputs": {
"sources": [
"wav/click.wav",
"wav/confirm.wav"
]
},
"output": {
"format": "SOUNDS/pcm16le_v1",
"codec": "RAW"
},
"preload": {
"enabled": false
}
}
```

250
docs/packer/decisions/003-build-artifacts-and-deterministic-packing-decision.md
View File

@ -1,250 +0,0 @@
# Build Artifacts and Deterministic Packing Decision
## Status
Accepted
## Date
2026-03-11
## Context
This decision closes the architectural questions raised in [`01.3. Build Artifacts and Deterministic Packing Agenda`](../agendas/01.3.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Agenda.md).
The packer must produce build artifacts that are:
- deterministic;
- aligned with the runtime-facing `assets.pa` contract already established in `../runtime`;
- usable by Studio and tooling without creating a second source of truth;
- stable enough to support future specs and implementation.
The runtime-side contract already establishes that:
- `assets.pa` is the runtime-facing artifact;
- `asset_table` and `preload` live in the internal JSON header;
- offsets are relative to the payload region;
- preload is boot-time input only.
This decision closes how the packer should produce these artifacts.
## Decision
The packer adopts an `assets.pa`-authoritative, deterministically ordered, canonical-header model.
### 1. Artifact authority
`assets.pa` is the authoritative runtime-facing artifact.
Rules:
- the `assets.pa` header is the runtime-facing source of truth for `asset_table` and `preload`;
- `build/asset_table.json` and other JSON outputs are companion artifacts only;
- runtime must not depend on companion JSON files as its primary contract.
### 2. Companion artifacts
The packer emits separate companion artifacts for tooling and debugging.
Baseline companion outputs:
- `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 carry richer packer metadata;
- richer tooling data must not be smuggled into the runtime-facing mirror files.
### 3. `assets.pa` v1 prelude
The baseline packer-side prelude for `assets.pa` v1 includes:
- `magic`
- `schema_version`
- `header_len`
- `payload_offset`
- `flags`
- `reserved`
Rules:
- `flags` exists from day 1 for forward compatibility;
- `reserved` exists from day 1 for forward compatibility;
- `flags = 0` in the current baseline unless a future spec says otherwise;
- `reserved = 0` in the current baseline unless a future spec says otherwise;
- `header_checksum` is not part of the baseline `assets.pa` envelope contract.
### 4. Checksum policy
Header checksum is not part of the baseline runtime-facing envelope.
Rules:
- runtime validation does not depend on header checksum;
- cartridge-level integrity may be handled elsewhere;
- Studio/tooling may compute checks or hashes separately if needed;
- such checks must not redefine the runtime-facing `assets.pa` envelope.
### 5. Canonical JSON header
The JSON header of `assets.pa` must be serialized canonically.
Canonicalization rules:
- UTF-8 encoding;
- no extra whitespace;
- object keys sorted lexicographically;
- arrays preserve declared order;
- canonicalization applies recursively, including nested metadata objects;
- runtime-facing header values in v1 must avoid floating-point numbers.
This is required so equivalent inputs produce byte-identical headers and therefore byte-reproducible artifacts.
### 6. Ordering and determinism
The global `asset_table` order is deterministic by increasing `asset_id`.
Rules:
- usage-based or hot-first packing is not part of the baseline contract;
- format-specific heuristics must not reorder the global asset list;
- deterministic ordering is preferred over physical-layout heuristics;
- future locality optimization requires a separate explicit decision and spec.
### 7. `asset_id` continuity
The `asset_id` used in runtime-facing artifacts is the same stable `asset_id` allocated by the packer registry.
Rules:
- the packer does not generate a second runtime-only asset identity;
- `preload` refers to the same `asset_id` values that appear in `asset_table`;
- table position does not define identity;
- cross-build identity stability comes from `asset_id`, not from table index.
### 8. Asset table shape
`asset_table` is emitted as a deterministically ordered list of asset entries.
Rules:
- one emitted entry per managed asset in the build set;
- no synthetic dense reindexing layer is introduced;
- omission of removed assets happens naturally because the emitted table reflects the current build set only;
- the runtime sees a normal contiguous list of entries, but the IDs inside it remain the stable packer IDs.
### 9. `asset_name` in runtime-facing artifacts
`asset_name` remains present in `asset_table`.
Meaning:
- `asset_name` is logical descriptive and API-facing metadata;
- current runtime/game-facing calls may still use it for normal asset lookup;
- preload/bootstrap integrity relies on `asset_id`, not `asset_name`;
- renaming `asset_name` is an API-visible/content-visible change, but not an asset identity change.
### 10. Preload mapping
Preload emission is derived deterministically from per-asset declaration.
Rules:
- assets with `preload.enabled = false` do not appear in emitted preload data;
- assets with `preload.enabled = true` produce preload entries in the runtime-facing preload list;
- emitted preload ordering is deterministic by increasing `asset_id`;
- preload is boot-time input only and must be emitted in a form consistent with the runtime contract.
### 11. Alignment
Alignment exists only when explicitly required by spec.
Rules:
- there is no implicit baseline alignment beyond what is required by the envelope and chosen formats;
- if a format requires alignment, the requirement must be normative and visible in the relevant spec;
- computed offsets must always be emitted explicitly in the runtime-facing descriptor.
### 12. Offsets
All emitted asset offsets are relative to the payload region.
Rules:
- offsets are never relative to the start of the whole `assets.pa` file;
- this rule must be preserved consistently across packer outputs and specs;
- companion artifacts must mirror the same offset semantics.
## Invariants and Constraints
The following invariants now apply:
1. `assets.pa` is the authoritative runtime-facing artifact.
2. Companion JSON files do not replace the internal `assets.pa` header.
3. `build/asset_table.json` mirrors `header.asset_table` 1:1.
4. `build/preload.json` mirrors `header.preload` 1:1.
5. `build/asset_table_metadata.json` is tooling-only.
6. The prelude includes `magic`, `schema_version`, `header_len`, `payload_offset`, `flags`, and `reserved`.
7. `header_checksum` is not part of the baseline envelope contract.
8. Header JSON is canonicalized.
9. Global asset ordering is deterministic by increasing `asset_id`.
10. The runtime-facing `asset_id` is the same stable packer `asset_id`.
11. `asset_table` is a deterministically ordered list, not a second identity system.
12. `asset_name` remains present as logical/API-facing metadata.
13. Preload is emitted deterministically from `preload.enabled`.
14. Offsets are relative to the payload region only.
## Explicit Non-Decisions
This decision does not yet define:
- the exact field-level metadata contract of each output format;
- richer preload policies beyond the current baseline;
- future physical locality optimization;
- game-language lowering of asset references from names to IDs;
- cartridge-level integrity/signature strategy.
Those belong to later decisions and specs.
## Propagation Targets
This decision must propagate to:
- packer artifact and envelope specs;
- packer determinism and reproducibility specs;
- packer preload emission specs;
- Studio tooling expectations for companion artifacts;
- future implementation of canonical header generation and companion-file emission.
## Validation Notes
Example: artifact relationship
```text
assets.pa
prelude
canonical header JSON
asset_table
preload
payload bytes
build/asset_table.json
mirrors header.asset_table
build/preload.json
mirrors header.preload
build/asset_table_metadata.json
tooling-only enrichment
```
Example: stable identity
- packer registry assigns asset IDs `3`, `7`, and `11`
- emitted `asset_table` is ordered `[3, 7, 11]`
- runtime-facing preload entries reference `3`, `7`, or `11`
- no additional dense runtime ID layer is introduced

217
docs/packer/decisions/004-diagnostics-doctor-quarantine-and-workspace-hygiene-decision.md
View File

@ -1,217 +0,0 @@
# Diagnostics, Doctor, Quarantine, and Workspace Hygiene Decision
## Status
Accepted
## Date
2026-03-11
## Context
This decision closes the architectural questions raised in [`01.4. Diagnostics, Doctor, Quarantine, and Workspace Hygiene Agenda`](../agendas/01.4.%20Diagnostics,%20Doctor,%20Quarantine,%20and%20Workspace%20Hygiene%20Agenda.md).
The packer is expected to operate as a sanity guardian over a potentially messy `assets/` workspace while still preserving trust and predictability.
This means the packer must:
- protect the correctness of managed builds;
- surface hygiene problems in the broader workspace;
- avoid surprising destructive or reorganizing mutations;
- keep recovery and auditability stronger than convenience heuristics.
## Decision
The packer adopts a `validate-the-managed-world, inspect-the-workspace, mutate-only-with-consent` model.
### 1. Diagnostic classes
Diagnostics are divided into two major classes:
- build-blocking structural errors;
- advisory workspace hygiene diagnostics.
Build-blocking structural errors include, at minimum:
- registered asset root missing its anchor `asset.json`;
- invalid `asset.json`;
- missing required inputs for a managed asset;
- output contract inconsistency;
- invalid preload-related artifact state;
- structural identity collisions or ambiguous ownership.
Advisory workspace hygiene diagnostics include, at minimum:
- orphan `asset.json` declarations;
- duplicate source content by hash;
- large unused files;
- assets not currently referenced by managed build inputs;
- naming or organization hints.
### 2. Registry validation versus workspace scanning
Registry validation and workspace scanning are distinct surfaces.
Rules:
- build-time validation is scoped to the managed world defined by the registry;
- workspace scanning is a broader hygiene pass over `assets/`;
- `doctor` without wider scope flags validates the managed world;
- `doctor --workspace` expands visibility to broader workspace chaos.
The build must not silently turn into a full workspace scanner.
### 3. Safety model for automatic fixes
Automatic fixes are allowed only for corrections that are mechanical, deterministic, and safe.
Safe automatic fixes include:
- path normalization;
- explicit materialization of already-determined defaults;
- canonical ordering or formatting of declaration data;
- strictly mechanical regeneration of control-file content when explicitly requested.
Unsafe automatic fixes are not baseline-safe:
- moving user content;
- deleting user content;
- deduplicating content by rewriting authoring files;
- renaming assets;
- auto-registering or auto-adopting assets without explicit consent.
### 4. Explicit consent policy
Any operation that mutates user-controlled workspace content requires explicit consent.
This includes:
- quarantine moves;
- deletion;
- adoption/registration of previously unmanaged assets;
- changes in physical file location;
- changes that alter declared authoring intent rather than only normalizing control data.
### 5. Quarantine model
Quarantine is a reversible staging area, not a magic trash bin.
Rules:
- quarantine is never automatic by default;
- the packer must explain what is being moved and why;
- recovery must remain possible;
- quarantine exists to support explicit hygiene workflows, not hidden cleanup.
### 6. Detection aggressiveness
The packer should be aggressive in detection and conservative in action.
Meaning:
- detect broadly when scanning workspace hygiene;
- report clearly and specifically;
- avoid mutating content unless the action is explicitly requested and safe.
### 7. `doctor --fix`
`doctor --fix` is limited to safe mechanical corrections in the baseline contract.
Rules:
- it must not mutate authoring content as a baseline behavior;
- it must not move or delete content without a stronger explicit operation;
- it must remain predictable enough that users can trust it in Studio and CLI-adapter workflows.
### 8. Structural conflicts
Conflicts between registry state, anchor files, and managed identity are structural errors.
Examples:
- two asset roots competing for the same identity;
- registered root without anchor;
- duplicated or ambiguous anchor declarations under managed expectations.
These are not advisory hygiene warnings.
They invalidate the managed build contract.
### 9. Duplicate content policy
Duplicate source content by hash is not a structural build error in the baseline contract.
Rules:
- it is a hygiene warning or hint;
- it may inform cost, cleanup, or optimization workflows;
- it does not imply semantic invalidity by itself.
### 10. Orphan asset policy
Orphan `asset.json` declarations do not block the baseline build.
Rules:
- they belong to workspace hygiene surfaces;
- they should be visible in `doctor --workspace`;
- they do not become managed assets automatically;
- stricter policy can be added later, but it is not part of the current baseline.
## Invariants and Constraints
The following invariants now apply:
1. The build validates the managed registry-defined world, not the entire workspace by default.
2. Workspace hygiene scanning is broader than build validation.
3. Structural managed-world errors block builds.
4. Hygiene findings do not block builds by default unless separately elevated by policy.
5. `doctor --fix` is limited to safe mechanical corrections.
6. Quarantine is explicit and reversible.
7. Destructive or relocational mutations require explicit consent.
8. Duplicate content is advisory, not structurally invalid by itself.
9. Orphan anchors are diagnosable, not build-active.
10. Trust and reversibility are preferred over aggressive automatic remediation.
## Explicit Non-Decisions
This decision does not yet define:
- the full taxonomy and numbering of diagnostic codes;
- richer policy knobs such as strict workspace modes by profile;
- detailed UI presentation in Studio;
- watch-mode-specific hygiene behavior;
- detailed garbage collection flows beyond the baseline safety model.
Those belong to later decisions and specs.
## Propagation Targets
This decision must propagate to:
- packer diagnostics contract spec;
- doctor and workspace scanning spec;
- quarantine and garbage collection spec;
- Studio service behavior for inspection, fix, and cleanup actions;
- future implementation of safe fix classification and explicit-consent workflows.
## Validation Notes
Example: orphan anchor
- `assets/wip/new_bank/asset.json` exists
- it is not registered in the managed registry
- build does not fail by default
- `doctor --workspace` must surface it
Example: unsafe fix
- two large duplicate PNGs are detected in workspace
- packer may report them
- packer must not delete or move either file automatically in baseline behavior
Example: structural error
- a registered asset root no longer contains its anchor `asset.json`
- this is a managed-world integrity failure
- build validation must fail

201
docs/packer/decisions/005-incremental-build-cache-and-watch-model-decision.md
View File

@ -1,201 +0,0 @@
# Incremental Build, Cache, and Watch Model Decision
## Status
Accepted
## Date
2026-03-11
## Context
This decision closes the architectural questions raised in [`01.5. Incremental Build, Cache, and Watch Model Agenda`](../agendas/01.5.%20Incremental%20Build,%20Cache,%20and%20Watch%20Model%20Agenda.md).
The packer should support incremental work and future watch-driven workflows, but only under a strict rule:
- optimization must never redefine build semantics.
Incremental behavior, cache reuse, and watch mode must remain subordinate to deterministic artifact production.
## Decision
The packer adopts a `determinism-first, cache-as-optimization, watch-as-optional-trigger` model.
### 1. Fingerprint model
Input tracking uses three levels of signal:
- `size`
- `mtime`
- `strong_hash`
Roles:
- `size` and `mtime` are fast-change hints;
- `strong_hash` is the authoritative content identity signal.
### 2. Authority of fingerprint signals
`size` and `mtime` are not sufficient as final truth for cache reuse.
Rules:
- they may be used to avoid unnecessary hashing in the fast path;
- they may indicate that a strong hash check is required;
- when reuse affects emitted output, strong hash is the authoritative content check.
### 3. Cache reuse rule
Cached work may be reused only when the full effective build inputs remain equivalent.
This includes, at minimum:
- source inputs;
- selected output format;
- codec;
- runtime-facing metadata;
- build configuration that affects emitted bytes;
- materialized defaults or effective derived configuration.
If any of these change, the relevant output must be rebuilt.
### 4. Incremental equivalence
Incremental build is an execution optimization only.
Rules:
- full build and incremental build must produce the same observable results;
- byte output, header content, offsets, preload data, and other runtime-facing artifacts must match;
- any semantic difference between full and incremental build is a bug.
### 5. Cache scope
The packer may persist:
- fingerprint data;
- derived build results;
- internal cache metadata.
But:
- cache internals are not the source of truth;
- runtime-facing artifacts remain authoritative;
- cache structure is not frozen as a normative external contract in the current baseline.
### 6. Cache explainability
The packer must be able to explain reuse and rebuild decisions.
At minimum, the model should support reasons equivalent to:
- cache hit;
- rebuild because input changed;
- rebuild because config changed;
- rebuild because format or schema contract changed;
- rebuild because cache state is missing or invalid.
This does not require always-on verbosity, but the capability must exist for diagnostics and Studio tooling.
### 7. Watch mode
Watch mode is optional in the current baseline contract.
Rules:
- watch may exist as a supported capability;
- watch must trigger rebuild and/or revalidation behavior equivalent to normal packer execution;
- watch is not the place to freeze detailed UI, timing, or orchestration policy yet.
### 8. Watch safety
Watch mode must not become a silent mutation engine.
Rules:
- baseline watch behavior is observe, detect, validate, and rebuild;
- watch does not imply auto-fix, quarantine, adoption, or destructive cleanup;
- any broader mutation policy requires explicit later design.
### 9. Strong hash timing
Strong hash calculation is performed pragmatically, but remains authoritative.
Rules:
- fast hints may be checked first;
- when hints indicate possible change, strong hash resolves the question;
- when cache trust is insufficient, strong hash may be recomputed even if hints appear unchanged.
### 10. Cache portability
Cross-machine cache portability is not part of the current baseline contract.
Rules:
- cache is treated as local to the workspace/runtime environment by default;
- portability, remote reuse, or shareable cache semantics require later explicit design.
## Invariants and Constraints
The following invariants now apply:
1. Deterministic output has priority over cache reuse.
2. `size` and `mtime` are hints, not final truth.
3. Strong hash is the authoritative content identity signal for reuse decisions.
4. Cache reuse is allowed only when effective build inputs are equivalent.
5. Full and incremental builds must be observably equivalent.
6. Cache is an optimization layer, not a semantic authority.
7. The packer must be able to explain rebuild/reuse decisions.
8. Watch mode is optional in the baseline contract.
9. Watch mode does not imply silent mutation of authoring content.
10. Cache portability is deferred.
## Explicit Non-Decisions
This decision does not yet define:
- the exact on-disk schema of every cache file;
- detailed watch UX or scheduling behavior;
- remote/shared cache design;
- background worker orchestration;
- policy for multi-user cache coordination.
Those belong to later decisions and specs.
## Propagation Targets
This decision must propagate to:
- packer cache and fingerprint specs;
- incremental build guarantees spec;
- watch mode spec or deferred capability note;
- Studio diagnostics for build-reason visibility;
- future implementation of fingerprint persistence and cache invalidation.
## Validation Notes
Example: changed input
- source file timestamp changed
- strong hash also changed
- cached derived result must be invalidated
Example: misleading timestamp
- `mtime` changed
- strong hash remains identical
- packer may treat the content as unchanged after authoritative hash confirmation
Example: config change
- source inputs are identical
- `output.format` or runtime-facing metadata changed
- cached result must be invalidated because emitted bytes may differ
Example: watch behavior
- file changes while watch is active
- packer revalidates or rebuilds
- watch does not automatically move, delete, or adopt workspace content

278
docs/packer/decisions/006-studio-first-asset-services-and-event-lane-decision.md
View File

@ -1,278 +0,0 @@
# Studio-First Asset Services and Event Lane Decision
## Status
Accepted
## Date
2026-03-11
## Context
This decision closes the architectural questions raised in [`01.6. CLI Surface and Mutating Operations Agenda`](../agendas/01.6.%20CLI%20Surface%20and%20Mutating%20Operations%20Agenda.md).
The original packer framing was CLI-oriented.
That is no longer the design center.
The current target is Studio integration:
- asset UI and packer behavior should evolve together;
- packer operations should exist as Studio-consumable services first;
- background asset activity should be observable in the UI through structured events;
- any future CLI should be an adapter over those services rather than the architecture driver.
## Decision
The packer adopts a `Studio-first services + structured event lane` model.
### 1. Primary integration model
Studio is the primary integration target.
Rules:
- service contracts are the normative operational surface;
- UI workflows are first-class design inputs;
- CLI is not the baseline architecture contract in the current phase;
- if a CLI exists later, it adapts these services rather than redefining them.
### 2. Core v1 services
The baseline Studio service surface includes:
- `init_workspace`
- `register_asset`
- `adopt_asset`
- `forget_asset`
- `remove_asset`
- `list_assets`
- `get_asset_details`
- `doctor`
- `build`
Later or optional capabilities may include:
- `watch`
- `gc`
- `quarantine`
- more advanced bulk refactor flows
### 3. Identifier expectations
For normal Studio-facing workflows, the preferred identifiers are:
- `asset_name`
- `asset_root`
- `asset_id` when already resolved internally
`asset_uuid` may still exist for migration or internal tooling purposes, but it is not required as the primary UX identifier for the baseline flow.
### 4. Read-only versus mutating services
The service contract must distinguish clearly between:
- read-only operations;
- registry mutations;
- workspace mutations.
Baseline interpretation:
- read-only:
- `list_assets`
- `get_asset_details`
- `doctor`
- registry mutations:
- `register_asset`
- `adopt_asset`
- `forget_asset`
- workspace mutations:
- `remove_asset`
- future quarantine/move/delete flows
This distinction is part of the service semantics and must be visible to the UI.
### 5. Preview/apply model
Sensitive mutating workflows use staged intent rather than immediate blind mutation.
Rules:
- operations with significant mutation potential should support analysis or preview before apply;
- broad, destructive, or relocational actions require explicit user confirmation;
- safe-fix flows should be modeled as services such as:
- analyze
- propose fixes
- apply safe fixes
This replaces CLI-centric flag thinking as the architectural baseline.
### 6. Structured service responses
Service responses must be structured for UI and automation.
At minimum, the model should support fields equivalent to:
- `status`
- `summary`
- `affected_assets`
- `diagnostics`
- `proposed_actions`
- `applied_actions`
- `blockers`
Human-readable strings may still exist, but they must not be the only contract the UI depends on.
### 7. `forget` versus `remove`
`forget_asset` and `remove_asset` remain distinct operations.
Meaning:
- `forget_asset` leaves the managed set without deleting authoring content;
- `remove_asset` expresses a stronger mutation intent and may affect workspace content depending on policy.
The UI must present this difference explicitly.
### 8. Adoption is core
`adopt_asset` is part of the baseline service set.
Rationale:
- orphan `asset.json` declarations are a normal part of the packer model;
- adoption is not an edge-case maintenance feature;
- Studio needs a first-class path from discovery to managed registration.
### 9. Asset workspace event lane
The system includes a dedicated asset workspace event lane for Studio integration.
This is an architectural event/reporting contract, not a commitment to one specific implementation primitive.
Responsibilities:
- observe relevant changes in the asset workspace and registry;
- trigger analysis, refresh, rebuild, or rescan workflows when appropriate;
- publish structured events for UI logging, status, and live refresh;
- avoid blocking the UI thread on asset work.
### 10. Mutation serialization
Mutating asset operations are serialized semantically.
Rules:
- the event lane and service model must not allow conflicting asset mutations to race arbitrarily;
- internal implementation may use controlled parallelism where safe;
- but the observable mutation model should behave as if sensitive workspace operations are serialized.
This keeps Studio state coherent and avoids hard-to-debug race conditions between watch, doctor, build, and explicit user actions.
### 11. Event model
The initial structured event set should include, at minimum:
- `asset_discovered`
- `asset_changed`
- `diagnostics_updated`
- `build_started`
- `build_finished`
- `cache_hit`
- `cache_miss`
- `preview_ready`
- `action_applied`
- `action_failed`
- `progress_updated`
`progress_updated` exists to support visible progress reporting such as progress bars and long-running asset activity feedback in the UI.
### 12. Event lane safety
The background event lane is not an autonomous mutation engine.
Rules:
- it may observe, analyze, report, and trigger safe refresh/rebuild behavior;
- it must not silently apply dangerous mutations;
- explicit user intent remains required for destructive, relocational, or adoption-related changes unless separately designed later.
### 13. Future CLI boundary
Any future CLI should remain a secondary adapter.
Rules:
- CLI should consume the same service semantics;
- CLI text output is not the canonical contract;
- if stable automation output is needed, it should be derived from the same structured response model used by Studio.
## Invariants and Constraints
The following invariants now apply:
1. Studio integration is the primary target.
2. Services are the normative operational surface.
3. UI and services are designed together.
4. CLI is deferred to adapter status.
5. Core asset operations are service-defined, not command-defined.
6. Sensitive mutations use preview/apply semantics where appropriate.
7. Structured responses are required for UI consumption.
8. `forget_asset` and `remove_asset` remain distinct.
9. Adoption is part of the baseline service model.
10. A dedicated asset event lane exists as an architectural integration surface.
11. Mutating asset workflows are serialized semantically.
12. Initial asset event reporting includes progress updates.
13. Background reporting does not authorize silent dangerous mutation.
## Explicit Non-Decisions
This decision does not yet define:
- the exact transport or IPC mechanism for services;
- the exact threading/runtime primitive used for the event lane;
- final visual design of Studio asset panels;
- detailed watch-mode orchestration beyond the baseline event model;
- a future CLI command grammar.
Those belong to later decisions and specs.
## Propagation Targets
This decision must propagate to:
- packer service operation spec;
- Studio asset workflow integration spec;
- mutation and confirmation policy spec;
- structured response contract spec;
- asset event/reporting integration spec;
- future implementation of the asset workspace event lane and progress reporting.
## Validation Notes
Example: safe inspection flow
- Studio requests `list_assets`
- service returns structured asset summaries
- event lane may emit `diagnostics_updated` or `asset_changed` as background state evolves
Example: staged mutation flow
- Studio requests doctor analysis
- service returns diagnostics plus proposed safe fixes
- user confirms apply
- service performs safe changes
- event lane emits `action_applied` and `progress_updated`
Example: background rebuild
- asset source changes
- event lane observes the change
- analysis/rebuild is triggered according to service policy
- UI receives `build_started`, `progress_updated`, and `build_finished`
Example: dangerous mutation boundary
- user has not confirmed quarantine or deletion
- background lane may report the issue and propose the action
- background lane must not perform the mutation by itself

223
docs/packer/decisions/007-shipper-integration-versioning-and-trust-model-decision.md
View File

@ -1,223 +0,0 @@
# Shipper Integration, Versioning, and Trust Model Decision
## Status
Accepted
## Date
2026-03-11
## Context
This decision closes the architectural questions raised in [`01.7. Builder Integration, Versioning, and Trust Model Agenda`](../agendas/01.7.%20Builder%20Integration,%20Versioning,%20and%20Trust%20Model%20Agenda.md).
The packer must define:
- how its artifacts are versioned;
- what migration obligations it owns;
- what trust boundaries apply to asset tooling;
- how a future shipper will consume packer outputs without becoming part of the packer architecture now.
The important clarification is:
- the shipper does not exist yet as part of the current packer work;
- shipper integration is therefore a future consumer boundary, not a present operational dependency.
## Decision
The packer adopts a `future-shipper-consumer, explicit-versioning, conservative-trust` model.
### 1. Current shipper boundary
The shipper is not part of the current packer architecture.
Rules:
- the packer must not depend on a concrete shipper implementation;
- the packer should emit stable, documented artifacts that a future shipper can consume;
- current packer design must stop at artifact publication, not at cartridge shipping orchestration.
### 2. Ownership boundary
Current ownership is split as follows:
- packer owns artifact production;
- runtime owns runtime-side artifact reading semantics;
- future shipper will own cartridge shipping/publication concerns.
This means:
- runtime-facing reading contract for `assets.pa` belongs to runtime specs;
- writer-side production contract for `assets.pa` belongs to packer specs;
- a future shipper consumes these artifacts but does not redefine the asset contract.
### 3. Packer-owned artifacts
The packer is responsible for emitting and versioning at least:
- `assets.pa`
- `build/asset_table.json`
- `build/preload.json`
- `build/asset_table_metadata.json`
- `asset.json`
- `index.json`
- packer-owned cache and control data
These are the boundaries a future shipper may consume, but they remain packer-owned artifacts.
### 4. Minimal future shipper contract
The future shipper contract should remain minimal for now.
Baseline contract:
- which packer artifacts are published;
- where they are expected to exist;
- which artifacts are runtime-facing versus tooling-only;
- which artifacts are authoritative versus derived.
Detailed shipping workflow is deferred until the shipper exists.
### 5. Versioning policy
Versioning is explicit and per-artifact/per-schema.
Rules:
- `asset.json` has explicit schema versioning;
- `index.json` has explicit schema versioning;
- `assets.pa` has explicit runtime-facing envelope versioning;
- companion artifacts may have their own schema versioning where needed;
- version evolution is tracked per concern, not by one global version number for the whole domain.
### 6. Migration policy
The packer migrates only artifacts it owns.
This includes, at minimum:
- `asset.json`
- `index.json`
- packer-owned caches and control files
Rules:
- migration may be automatic within a supported window;
- outside the supported window, the packer fails with actionable diagnostics;
- the packer does not assume a cooperative migration workflow with a shipper that does not yet exist.
### 7. Compatibility window
Backward compatibility is provided through an explicit support window, not an open-ended forever policy.
Rules:
- the packer must define which previous versions it can read or migrate;
- unsupported versions fail clearly and early;
- CI and Studio should be able to surface unsupported-version failures deterministically.
### 8. Runtime compatibility guarantees
The packer must preserve compatibility guarantees relevant to `../runtime`.
These include:
- `assets.pa` emitted according to the runtime-facing reader contract;
- offsets relative to payload region;
- canonical header semantics where required by packer-side production rules;
- stable `asset_id` continuity end-to-end;
- preload emitted according to the current runtime-facing contract.
The runtime must not depend on companion JSON artifacts for correctness.
### 9. Trusted versus untrusted inputs
The packer uses a conservative trust model.
Untrusted until validated:
- source asset files;
- manually edited or legacy `asset.json`;
- legacy registry/control data;
- imported artifacts and external project content.
Trusted only after:
- strict parse;
- structural validation;
- semantic validation;
- version compatibility check.
### 10. No plugin/script execution baseline
The packer must not execute arbitrary external plugins or scripts in the baseline architecture.
Rules:
- no script execution as part of normal asset transformation contract;
- no untrusted extension hooks;
- no implicit foreign code execution during build.
Any future extensibility model requires a separate decision.
### 11. Shipper as consumer, not co-author
A future shipper consumes packer outputs but must not silently reinterpret or repair the asset contract.
Rules:
- shipper does not redefine `assets.pa`;
- shipper does not become the source of truth for `asset_table` or preload semantics;
- if an asset artifact is invalid, the issue belongs back to packer production, not to shipper-side correction.
## Invariants and Constraints
The following invariants now apply:
1. The shipper is a future consumer, not a current packer dependency.
2. Packer stops at artifact production.
3. Runtime owns reader semantics of the runtime-facing artifact.
4. Packer owns writer semantics and companion artifacts on the production side.
5. Versioning is explicit per artifact/schema.
6. Migration applies only to artifacts the packer owns.
7. Compatibility is governed by a support window, not indefinite backward promises.
8. Inputs are untrusted until validated.
9. Baseline packer architecture does not execute arbitrary plugins or scripts.
10. A future shipper is a consumer, not a co-author of the asset contract.
## Explicit Non-Decisions
This decision does not yet define:
- the concrete shipper implementation;
- cartridge shipping workflow details;
- packaging formats beyond the currently documented runtime forms;
- artifact signing or distribution security policy;
- remote/shared artifact registry behavior.
Those belong to later decisions and future shipper work.
## Propagation Targets
This decision must propagate to:
- packer versioning and migration specs;
- packer trust/security model spec;
- future shipper integration spec;
- Studio diagnostics for unsupported versions and migration failures;
- future implementation of schema migration boundaries and compatibility checks.
## Validation Notes
Example: unsupported registry version
- `index.json` version is outside the supported migration window
- packer reports explicit version mismatch and migration failure
- build does not continue
Example: future shipper consumption
- packer emits `assets.pa` and companion build artifacts
- future shipper consumes those artifacts to assemble a cartridge
- shipper does not reinterpret asset semantics or rewrite packer-owned artifact meaning

7
docs/packer/decisions/README.md
View File

@ -2,6 +2,13 @@
This directory contains packer decision records.
There are currently no retained packer decision records.
The first packer decision wave was already consolidated into:
- normative specifications under [`../specs/`](../specs/)
- didactic material under [`../learn/`](../learn/)
## Purpose
A decision record is the bridge between packer discussion and packer execution.

6
docs/packer/specs/1. Domain and Artifact Boundary Specification.md
View File

@ -6,11 +6,7 @@ Purpose: Define what the packer owns, what it emits, and where its responsibilit
## Authority and Precedence
This specification is grounded in:
- [`001-asset-workspace-registry-and-stable-identity-decision.md`](../decisions/001-asset-workspace-registry-and-stable-identity-decision.md)
- [`003-build-artifacts-and-deterministic-packing-decision.md`](../decisions/003-build-artifacts-and-deterministic-packing-decision.md)
- [`007-shipper-integration-versioning-and-trust-model-decision.md`](../decisions/007-shipper-integration-versioning-and-trust-model-decision.md)
This specification consolidates the initial packer agenda and decision wave into normative form.
Runtime-side reading semantics for `assets.pa` are defined upstream in `../runtime/docs/runtime/specs/13-cartridge.md` and `../runtime/docs/runtime/specs/15-asset-management.md`.

4
docs/packer/specs/2. Workspace, Registry, and Asset Identity Specification.md
View File

@ -6,9 +6,7 @@ Purpose: Define how the packer recognizes, tracks, and preserves asset identity.
## Authority and Precedence
This specification is grounded in:
- [`001-asset-workspace-registry-and-stable-identity-decision.md`](../decisions/001-asset-workspace-registry-and-stable-identity-decision.md)
This specification consolidates the initial packer agenda and decision wave into normative form.
## Normative Inputs

4
docs/packer/specs/3. Asset Declaration and Virtual Asset Contract Specification.md
View File

@ -6,9 +6,7 @@ Purpose: Define the shared declaration model for raw and virtual assets.
## Authority and Precedence
This specification is grounded in:
- [`002-asset-specification-raw-assets-and-virtual-asset-contract-decision.md`](../decisions/002-asset-specification-raw-assets-and-virtual-asset-contract-decision.md)
This specification consolidates the initial packer agenda and decision wave into normative form.
## Core Rules

4
docs/packer/specs/4. Build Artifacts and Deterministic Packing Specification.md
View File

@ -6,9 +6,7 @@ Purpose: Define how the packer emits `assets.pa` and companion artifacts.
## Authority and Precedence
This specification is grounded in:
- [`003-build-artifacts-and-deterministic-packing-decision.md`](../decisions/003-build-artifacts-and-deterministic-packing-decision.md)
This specification consolidates the initial packer agenda and decision wave into normative form.
Runtime-side reading semantics remain upstream in:

6
docs/packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md
View File

@ -6,11 +6,7 @@ Purpose: Define how the packer exposes safe operational behavior to Studio and t
## Authority and Precedence
This specification is grounded in:
- [`004-diagnostics-doctor-quarantine-and-workspace-hygiene-decision.md`](../decisions/004-diagnostics-doctor-quarantine-and-workspace-hygiene-decision.md)
- [`005-incremental-build-cache-and-watch-model-decision.md`](../decisions/005-incremental-build-cache-and-watch-model-decision.md)
- [`006-studio-first-asset-services-and-event-lane-decision.md`](../decisions/006-studio-first-asset-services-and-event-lane-decision.md)
This specification consolidates the initial packer agenda and decision wave into normative form.
## Diagnostics Model

4
docs/packer/specs/6. Versioning, Migration, and Trust Model Specification.md
View File

@ -6,9 +6,7 @@ Purpose: Define how the packer evolves safely over time and what trust assumptio
## Authority and Precedence
This specification is grounded in:
- [`007-shipper-integration-versioning-and-trust-model-decision.md`](../decisions/007-shipper-integration-versioning-and-trust-model-decision.md)
This specification consolidates the initial packer agenda and decision wave into normative form.
## Core Rules