From 4aef6cdaeb32b8cc029da45a96e3c22cc97b6972 Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Wed, 11 Mar 2026 07:29:03 +0000 Subject: [PATCH] updated packer agendas --- ... Boundaries, and Golden Pipeline Agenda.md | 9 +- ...e, Registry, and Stable Identity Agenda.md | 56 +++++- ...sets, and Virtual Asset Contract Agenda.md | 17 ++ ... Surface and Mutating Operations Agenda.md | 34 ++-- ...e-registry-and-stable-identity-decision.md | 189 ++++++++++++++++++ 5 files changed, 291 insertions(+), 14 deletions(-) create mode 100644 docs/packer/decisions/001-asset-workspace-registry-and-stable-identity-decision.md 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 index 0e74af21..578872b3 100644 --- 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 @@ -16,6 +16,7 @@ Define the architectural boundary of the `packer` domain before the draft is dec - 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, - cartridge builder consumes packer outputs later. @@ -56,7 +57,7 @@ These points are already normative on the runtime side and should be treated as ## Key Questions 1. What is the exact ownership boundary between `packer` and `cartridge builder`? -2. Should `packer` be defined purely as offline asset tooling, or also as a reusable library surface for IDE and watch integrations? +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? @@ -83,11 +84,17 @@ Allow packer to absorb more cartridge preparation responsibilities over time. Adopt Option A and make the packer/builder 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`. 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 index 0fa61955..60cf97aa 100644 --- 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 @@ -2,7 +2,9 @@ ## Status -Open +Closed + +Resolved by [`001-asset-workspace-registry-and-stable-identity-decision.md`](../decisions/001-asset-workspace-registry-and-stable-identity-decision.md). ## Purpose @@ -19,6 +21,14 @@ The draft proposes a Git-like workspace: 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` @@ -33,6 +43,36 @@ This is the core model of the packer. If it stays vague, all later specs become 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 @@ -58,12 +98,26 @@ Adopt Option A: - `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 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 index 4e51243e..c0108371 100644 --- 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 @@ -19,6 +19,15 @@ The draft already proposes: 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. + ## Source Sections - `5.3 Asset Types (Bank Targets)` @@ -34,6 +43,7 @@ This needs decomposition into a stable common contract plus future format-specif 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? ## Options @@ -59,12 +69,19 @@ Adopt Option A: - 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. + ## 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. ## Expected Spec Follow-up 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 index 1a87dd38..277b6edb 100644 --- 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 @@ -6,7 +6,7 @@ Open ## Purpose -Define the stable CLI contract for packer commands, especially commands that mutate registry state or user files. +Define the stable service and adapter contract for packer operations, especially operations that mutate registry state or user files. ## Context @@ -25,7 +25,14 @@ The draft already lists a substantial command surface: - `gc` - `quarantine` -This is enough surface area that command semantics need architectural review before turning into normative CLI specs. +Historically, packer was framed as a CLI-first tool. +The current direction is different: + +- packer should be fully integrated with Studio; +- operations should exist as services; +- CLI, if retained, should be an adapter over those services. + +This is enough surface area that operation semantics need architectural review before turning into normative service and CLI contracts. ## Source Sections @@ -33,18 +40,19 @@ This is enough surface area that command semantics need architectural review bef ## Key Questions -1. Which commands are core v1 and which are aspirational? +1. Which operations are core v1 and which are aspirational? 2. Which identifiers must every command accept: name, id, uuid, path? -3. Which commands mutate registry only versus mutate workspace files? +3. Which operations mutate registry only versus mutate workspace files? 4. What requires confirmation, force flags, or dry-run support? 5. How explicit should `--fix` and auto-materialization behavior be? -6. Should CLI output contracts be stable for automation, or only JSON/structured output modes? +6. Which parts of the contract belong to Studio services versus optional CLI adapters? +7. Should adapter output contracts be stable for automation, or only JSON/structured output modes? ## Options ### Option A -Define a minimal stable v1 CLI and mark the rest as future or optional. +Define a minimal stable v1 service surface and mark the rest as future or optional. ### Option B @@ -53,6 +61,7 @@ Freeze the larger command catalog immediately. ## Tradeoffs - Option A lowers the early compatibility burden. +- Option A matches the Studio-integrated direction better because services can stabilize before adapters. - 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. @@ -60,20 +69,21 @@ Freeze the larger command catalog immediately. Adopt Option A and distinguish: -- required core commands, -- optional commands, -- future commands not yet in the normative CLI contract. +- required core services, +- optional adapters, +- future operations not yet in the normative contract. ## Expected Decisions to Produce -1. Core v1 command set. +1. Core v1 service set. 2. Mutation safety model. 3. Identifier resolution rules. -4. Structured output and automation expectations. +4. Adapter and structured output expectations. ## Expected Spec Follow-up -- CLI command contract spec. +- Service operation contract spec. +- CLI adapter contract spec. - Mutation and confirmation policy spec. - Command output contract spec. 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 new file mode 100644 index 00000000..505908b1 --- /dev/null +++ b/docs/packer/decisions/001-asset-workspace-registry-and-stable-identity-decision.md @@ -0,0 +1,189 @@ +# 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. + +### 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