updated packer agendas
This commit is contained in:
parent
8c930c3d2e
commit
4aef6cdaeb
SSH Key Fingerprint:
SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
@ -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`.
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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
|
||||
Loading…
x
Reference in New Issue
Block a user