updated packer agendas

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`.

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
 

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
 

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,
+- required core services,
-- optional commands,
+- optional adapters,
-- future commands not yet in the normative CLI contract.
+- 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.
 

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