From 11ca697fa479382f08a9cd5b771e826e37201244 Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Wed, 11 Mar 2026 09:51:43 +0000 Subject: [PATCH] clean up --- docs/packer/README.md | 14 +- ... Boundaries, and Golden Pipeline Agenda.md | 113 ------- ...e, Registry, and Stable Identity Agenda.md | 132 -------- ...sets, and Virtual Asset Contract Agenda.md | 140 --------- ...ifacts and Deterministic Packing Agenda.md | 179 ----------- ...uarantine, and Workspace Hygiene Agenda.md | 82 ----- ...al Build, Cache, and Watch Model Agenda.md | 79 ----- ... Surface and Mutating Operations Agenda.md | 118 -------- ...ion, Versioning, and Trust Model Agenda.md | 103 ------- docs/packer/agendas/README.md | 2 +- ...e-registry-and-stable-identity-decision.md | 197 ------------ ...ets-and-virtual-asset-contract-decision.md | 282 ------------------ ...acts-and-deterministic-packing-decision.md | 250 ---------------- ...arantine-and-workspace-hygiene-decision.md | 217 -------------- ...al-build-cache-and-watch-model-decision.md | 201 ------------- ...-asset-services-and-event-lane-decision.md | 278 ----------------- ...ion-versioning-and-trust-model-decision.md | 223 -------------- docs/packer/decisions/README.md | 7 + ...ain and Artifact Boundary Specification.md | 6 +- ...istry, and Asset Identity Specification.md | 4 +- ...nd Virtual Asset Contract Specification.md | 4 +- ...and Deterministic Packing Specification.md | 4 +- ...s, and Studio Integration Specification.md | 6 +- ...igration, and Trust Model Specification.md | 4 +- 24 files changed, 23 insertions(+), 2622 deletions(-) delete mode 100644 docs/packer/agendas/01.0. Packer Scope, Boundaries, and Golden Pipeline Agenda.md delete mode 100644 docs/packer/agendas/01.1. Asset Workspace, Registry, and Stable Identity Agenda.md delete mode 100644 docs/packer/agendas/01.2. Asset Specification, Raw Assets, and Virtual Asset Contract Agenda.md delete mode 100644 docs/packer/agendas/01.3. Build Artifacts and Deterministic Packing Agenda.md delete mode 100644 docs/packer/agendas/01.4. Diagnostics, Doctor, Quarantine, and Workspace Hygiene Agenda.md delete mode 100644 docs/packer/agendas/01.5. Incremental Build, Cache, and Watch Model Agenda.md delete mode 100644 docs/packer/agendas/01.6. CLI Surface and Mutating Operations Agenda.md delete mode 100644 docs/packer/agendas/01.7. Builder Integration, Versioning, and Trust Model Agenda.md delete mode 100644 docs/packer/decisions/001-asset-workspace-registry-and-stable-identity-decision.md delete mode 100644 docs/packer/decisions/002-asset-specification-raw-assets-and-virtual-asset-contract-decision.md delete mode 100644 docs/packer/decisions/003-build-artifacts-and-deterministic-packing-decision.md delete mode 100644 docs/packer/decisions/004-diagnostics-doctor-quarantine-and-workspace-hygiene-decision.md delete mode 100644 docs/packer/decisions/005-incremental-build-cache-and-watch-model-decision.md delete mode 100644 docs/packer/decisions/006-studio-first-asset-services-and-event-lane-decision.md delete mode 100644 docs/packer/decisions/007-shipper-integration-versioning-and-trust-model-decision.md diff --git a/docs/packer/README.md b/docs/packer/README.md index 7b006cac..8e99734e 100644 --- a/docs/packer/README.md +++ b/docs/packer/README.md @@ -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/`. diff --git a/docs/packer/agendas/01.0. Packer Scope, Boundaries, and Golden Pipeline Agenda.md b/docs/packer/agendas/01.0. Packer Scope, Boundaries, and Golden Pipeline Agenda.md deleted file mode 100644 index 8662598a..00000000 --- a/docs/packer/agendas/01.0. Packer Scope, Boundaries, and Golden Pipeline Agenda.md +++ /dev/null @@ -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. diff --git a/docs/packer/agendas/01.1. Asset Workspace, Registry, and Stable Identity Agenda.md b/docs/packer/agendas/01.1. Asset Workspace, Registry, and Stable Identity Agenda.md deleted file mode 100644 index 60cf97aa..00000000 --- a/docs/packer/agendas/01.1. Asset Workspace, Registry, and Stable Identity Agenda.md +++ /dev/null @@ -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. diff --git a/docs/packer/agendas/01.2. Asset Specification, Raw Assets, and Virtual Asset Contract Agenda.md b/docs/packer/agendas/01.2. Asset Specification, Raw Assets, and Virtual Asset Contract Agenda.md deleted file mode 100644 index 24572ca8..00000000 --- a/docs/packer/agendas/01.2. Asset Specification, Raw Assets, and Virtual Asset Contract Agenda.md +++ /dev/null @@ -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. diff --git a/docs/packer/agendas/01.3. Build Artifacts and Deterministic Packing Agenda.md b/docs/packer/agendas/01.3. Build Artifacts and Deterministic Packing Agenda.md deleted file mode 100644 index 3808a903..00000000 --- a/docs/packer/agendas/01.3. Build Artifacts and Deterministic Packing Agenda.md +++ /dev/null @@ -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. diff --git a/docs/packer/agendas/01.4. Diagnostics, Doctor, Quarantine, and Workspace Hygiene Agenda.md b/docs/packer/agendas/01.4. Diagnostics, Doctor, Quarantine, and Workspace Hygiene Agenda.md deleted file mode 100644 index c96116d4..00000000 --- a/docs/packer/agendas/01.4. Diagnostics, Doctor, Quarantine, and Workspace Hygiene Agenda.md +++ /dev/null @@ -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. diff --git a/docs/packer/agendas/01.5. Incremental Build, Cache, and Watch Model Agenda.md b/docs/packer/agendas/01.5. Incremental Build, Cache, and Watch Model Agenda.md deleted file mode 100644 index 25b1dfa8..00000000 --- a/docs/packer/agendas/01.5. Incremental Build, Cache, and Watch Model Agenda.md +++ /dev/null @@ -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. diff --git a/docs/packer/agendas/01.6. CLI Surface and Mutating Operations Agenda.md b/docs/packer/agendas/01.6. CLI Surface and Mutating Operations Agenda.md deleted file mode 100644 index 672c1786..00000000 --- a/docs/packer/agendas/01.6. CLI Surface and Mutating Operations Agenda.md +++ /dev/null @@ -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. diff --git a/docs/packer/agendas/01.7. Builder Integration, Versioning, and Trust Model Agenda.md b/docs/packer/agendas/01.7. Builder Integration, Versioning, and Trust Model Agenda.md deleted file mode 100644 index c1a1a2c7..00000000 --- a/docs/packer/agendas/01.7. Builder Integration, Versioning, and Trust Model Agenda.md +++ /dev/null @@ -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. diff --git a/docs/packer/agendas/README.md b/docs/packer/agendas/README.md index e6d33384..a93075eb 100644 --- a/docs/packer/agendas/README.md +++ b/docs/packer/agendas/README.md @@ -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 diff --git a/docs/packer/decisions/001-asset-workspace-registry-and-stable-identity-decision.md b/docs/packer/decisions/001-asset-workspace-registry-and-stable-identity-decision.md deleted file mode 100644 index 66272863..00000000 --- a/docs/packer/decisions/001-asset-workspace-registry-and-stable-identity-decision.md +++ /dev/null @@ -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 diff --git a/docs/packer/decisions/002-asset-specification-raw-assets-and-virtual-asset-contract-decision.md b/docs/packer/decisions/002-asset-specification-raw-assets-and-virtual-asset-contract-decision.md deleted file mode 100644 index 50e30b70..00000000 --- a/docs/packer/decisions/002-asset-specification-raw-assets-and-virtual-asset-contract-decision.md +++ /dev/null @@ -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 - } -} -``` diff --git a/docs/packer/decisions/003-build-artifacts-and-deterministic-packing-decision.md b/docs/packer/decisions/003-build-artifacts-and-deterministic-packing-decision.md deleted file mode 100644 index f0768f68..00000000 --- a/docs/packer/decisions/003-build-artifacts-and-deterministic-packing-decision.md +++ /dev/null @@ -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 diff --git a/docs/packer/decisions/004-diagnostics-doctor-quarantine-and-workspace-hygiene-decision.md b/docs/packer/decisions/004-diagnostics-doctor-quarantine-and-workspace-hygiene-decision.md deleted file mode 100644 index 1b8695c4..00000000 --- a/docs/packer/decisions/004-diagnostics-doctor-quarantine-and-workspace-hygiene-decision.md +++ /dev/null @@ -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 diff --git a/docs/packer/decisions/005-incremental-build-cache-and-watch-model-decision.md b/docs/packer/decisions/005-incremental-build-cache-and-watch-model-decision.md deleted file mode 100644 index 38840d32..00000000 --- a/docs/packer/decisions/005-incremental-build-cache-and-watch-model-decision.md +++ /dev/null @@ -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 diff --git a/docs/packer/decisions/006-studio-first-asset-services-and-event-lane-decision.md b/docs/packer/decisions/006-studio-first-asset-services-and-event-lane-decision.md deleted file mode 100644 index 02e0ef82..00000000 --- a/docs/packer/decisions/006-studio-first-asset-services-and-event-lane-decision.md +++ /dev/null @@ -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 diff --git a/docs/packer/decisions/007-shipper-integration-versioning-and-trust-model-decision.md b/docs/packer/decisions/007-shipper-integration-versioning-and-trust-model-decision.md deleted file mode 100644 index aa0fc0bb..00000000 --- a/docs/packer/decisions/007-shipper-integration-versioning-and-trust-model-decision.md +++ /dev/null @@ -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 diff --git a/docs/packer/decisions/README.md b/docs/packer/decisions/README.md index e07fbaaf..ff2ef279 100644 --- a/docs/packer/decisions/README.md +++ b/docs/packer/decisions/README.md @@ -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. diff --git a/docs/packer/specs/1. Domain and Artifact Boundary Specification.md b/docs/packer/specs/1. Domain and Artifact Boundary Specification.md index cf19b5e3..e420351f 100644 --- a/docs/packer/specs/1. Domain and Artifact Boundary Specification.md +++ b/docs/packer/specs/1. Domain and Artifact Boundary Specification.md @@ -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`. diff --git a/docs/packer/specs/2. Workspace, Registry, and Asset Identity Specification.md b/docs/packer/specs/2. Workspace, Registry, and Asset Identity Specification.md index f51e8fc5..a6afd363 100644 --- a/docs/packer/specs/2. Workspace, Registry, and Asset Identity Specification.md +++ b/docs/packer/specs/2. Workspace, Registry, and Asset Identity Specification.md @@ -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 diff --git a/docs/packer/specs/3. Asset Declaration and Virtual Asset Contract Specification.md b/docs/packer/specs/3. Asset Declaration and Virtual Asset Contract Specification.md index b42f0390..59a2e521 100644 --- a/docs/packer/specs/3. Asset Declaration and Virtual Asset Contract Specification.md +++ b/docs/packer/specs/3. Asset Declaration and Virtual Asset Contract Specification.md @@ -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 diff --git a/docs/packer/specs/4. Build Artifacts and Deterministic Packing Specification.md b/docs/packer/specs/4. Build Artifacts and Deterministic Packing Specification.md index b9dff515..e74e8183 100644 --- a/docs/packer/specs/4. Build Artifacts and Deterministic Packing Specification.md +++ b/docs/packer/specs/4. Build Artifacts and Deterministic Packing Specification.md @@ -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: diff --git a/docs/packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md b/docs/packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md index 8dc626ea..69290121 100644 --- a/docs/packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md +++ b/docs/packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md @@ -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 diff --git a/docs/packer/specs/6. Versioning, Migration, and Trust Model Specification.md b/docs/packer/specs/6. Versioning, Migration, and Trust Model Specification.md index e8c04760..e784b958 100644 --- a/docs/packer/specs/6. Versioning, Migration, and Trust Model Specification.md +++ b/docs/packer/specs/6. Versioning, Migration, and Trust Model Specification.md @@ -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