updated packer agendas

This commit is contained in:
2026-03-24 13:42:38 +00:00
parent 8c930c3d2e
commit 4aef6cdaeb
5 changed files with 291 additions and 14 deletions
@@ -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.