updated packer agendas
This commit is contained in:
@@ -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
|
||||
|
||||
|
||||
+17
@@ -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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user