This commit is contained in:
2026-03-24 13:42:38 +00:00
parent e3389e78b6
commit 11ca697fa4
24 changed files with 23 additions and 2622 deletions
@@ -1,113 +0,0 @@
# Packer Scope, Boundaries, and Golden Pipeline Agenda
## Status
Open
## Purpose
Define the architectural boundary of the `packer` domain before the draft is decomposed into normative specs.
## Context
`Prometeu Packer.md` already establishes a strong direction:
- packer owns asset management,
- 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,
- shipper consumes packer outputs later.
This is a good draft direction, but it still needs to be closed as an explicit domain contract.
The interface between packer outputs and `../runtime` should be documented first, before it is treated as implementation detail.
The runtime already exposes normative constraints that the packer must treat as upstream contract, not as optional design space.
## Source Sections
- `1. Goals and Non-Goals`
- `2. Repository / Project Layout (Golden Pipeline)`
- `3. Crate Topology`
- `15. Integration with Cartridge Shipper`
## Runtime Normative Inputs
From `../runtime/docs/runtime/specs/13-cartridge.md`:
- `assets.pa` is the runtime-facing asset artifact consumed by the current runtime;
- cartridges that declare `Asset` capability must provide valid `assets.pa`;
- runtime bootstrap must fail early when the asset capability is declared but `assets.pa` is missing or invalid;
- `assets.pa` v1 is autocontained and contains:
- fixed binary prelude,
- JSON header,
- binary payload region.
From `../runtime/docs/runtime/specs/15-asset-management.md`:
- the runtime consumes `assets.pa` as the primary cartridge asset artifact;
- the runtime-facing contract is bank-centric;
- `asset_table` and `preload` are loaded from inside `assets.pa`;
- payload slices are resolved relative to `payload_offset`;
- the runtime must not require the full `assets.pa` payload to remain resident in RAM as its baseline operating mode.
These points are already normative on the runtime side and should be treated as hard inputs for packer-side discussion.
## Key Questions
1. What is the exact ownership boundary between `packer` and `shipper`?
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?
6. Which packer-produced artifact is the runtime-facing contract, and what must be documented before code depends on it?
7. Which parts of the runtime-facing `assets.pa` contract are already closed by runtime specs and therefore outside packer-side redesign scope?
## Options
### Option A
Keep packer strictly scoped to `assets/` workspace management and production of packer outputs only.
### Option B
Allow packer to absorb more cartridge preparation responsibilities over time.
## Tradeoffs
- Option A keeps the architecture cleaner and reduces domain leakage.
- Option A makes shipper integration more explicit and easier to spec.
- Option B may feel convenient short-term, but it risks collapsing packer and shipper concerns into one blurred tool boundary.
## Recommendation
Adopt Option A and make the packer/shipper 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`.
## Expected Spec Follow-up
- Packer domain charter or overview spec.
- Shipper integration spec.
- Artifact ownership and responsibility spec.
- Runtime artifact interface spec.
## Non-Goals
- Defining the detailed schema of `asset_table.json`.
- Defining individual asset formats.
- Designing cartridge shipper internals.
@@ -1,132 +0,0 @@
# Asset Workspace, Registry, and Stable Identity Agenda
## Status
Closed
Resolved by [`001-asset-workspace-registry-and-stable-identity-decision.md`](../decisions/001-asset-workspace-registry-and-stable-identity-decision.md).
## Purpose
Close the packer model for managed assets, registry truth, anchor files, and stable asset identity.
## Context
The draft proposes a Git-like workspace:
- `assets/` may be messy,
- `assets/.prometeu/index.json` is the source of truth,
- a managed asset is anchored by `asset.json`,
- each asset has `asset_id` and `asset_uuid`.
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`
- `5. Core Concepts`
- `6. Directory Structure and Control Files`
## Key Questions
1. Is `index.json` the sole source of truth, or does `asset.json` also carry authority?
2. What is the exact relationship between registry entry and anchor file?
3. Which fields are stable identity and which are mutable presentation?
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
### Option A
Treat `index.json` as the authoritative registry and `asset.json` as the asset-local contract.
### Option B
Treat both as co-authoritative and reconcile divergences dynamically.
## Tradeoffs
- Option A is easier to reason about and easier to validate.
- Option A enables clean diagnostics when local anchor and registry diverge.
- Option B increases reconciliation complexity and invites ambiguous conflict handling.
## Recommendation
Adopt Option A:
- `index.json` is the authoritative registry,
- `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
- Workspace and control files spec.
- Managed asset and identity spec.
- Registry consistency and validation spec.
## Non-Goals
- Detailed build output layout.
- CLI syntax for every command.
- Format-specific `asset.json` payload definitions.
@@ -1,140 +0,0 @@
# Asset Specification, Raw Assets, and Virtual Asset Contract Agenda
## Status
Closed
Resolved by [`002-asset-specification-raw-assets-and-virtual-asset-contract-decision.md`](../decisions/002-asset-specification-raw-assets-and-virtual-asset-contract-decision.md).
## Purpose
Define the contract of `asset.json`, including the split between raw assets, virtual assets, and format-specific output specs.
## Context
The draft already proposes:
- `asset.json` as the anchor spec,
- common fields for all assets,
- explicit pipeline declaration for virtual assets,
- future format families such as `TILES/indexed_v1` and `SOUNDS/pcm16le_v1`.
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.
The runtime-facing extraction path also depends on codec information.
Because codec affects how runtime opens, decodes, or materializes payload bytes, codec must be explicit in the asset contract rather than hidden inside format naming.
Preload intent is also asset-level information.
Each managed asset should carry an explicit entry indicating whether it participates in preload, so preload inclusion is declared intentionally rather than inferred indirectly later in the pipeline.
## Source Sections
- `5.3 Asset Types (Bank Targets)`
- `5.4 Raw vs Virtual Assets`
- `7. Asset Specification: asset.json`
- `14. Virtual Assets (Deep Explanation)`
## Key Questions
1. Which fields belong to every `asset.json` regardless of type?
2. Which parts of the file are common packer contract versus format-specific contract?
3. How explicit must virtual build steps be?
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?
8. Should codec be part of `output.format`, or a separate explicit field in the output contract?
9. How should each asset declare preload intent so the packer can materialize runtime preload entries deterministically?
## Options
### Option A
Keep a small common `asset.json` contract and push all output-specific rules into dedicated format specs.
### Option B
Keep a richer monolithic `asset.json` contract in one central spec.
## Tradeoffs
- Option A scales better as new asset formats are added.
- Option A keeps the core packer spec smaller and more stable.
- Option B looks simpler initially but becomes harder to evolve without coupling unrelated formats together.
## Recommendation
Adopt Option A:
- a compact common `asset.json` contract,
- 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.
Also adopt this output-contract direction:
- `output.format` identifies the semantic/runtime format contract;
- `output.codec` identifies how payload bytes are stored for extraction/materialization;
- codec must remain explicit because it affects runtime extraction behavior;
- codec should not be smuggled into format naming when it represents a distinct storage concern.
Also adopt this preload direction:
- each managed asset must expose an explicit preload-related declaration entry;
- preload participation must be declared, not inferred from ad hoc conventions;
- packer build must use that declaration to decide whether preload data is emitted into the runtime-facing artifact contract.
- `preload.enabled` should be the required runtime-relevant boolean;
- richer packer-side preload metadata may exist, but it must not change runtime behavior until separately specified.
Current recommended shape:
```json
{
"preload": {
"enabled": true,
"policy": "boot_critical"
}
}
```
Direction:
- `enabled` is the normative yes/no input for runtime preload emission;
- optional fields such as `policy` are packer-side hints for Studio, diagnostics, planning, or future evolution;
- packer-side preload hints must not silently alter the current runtime-facing preload contract.
## 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.
6. Explicit separation between output format and codec in the asset contract.
7. Asset-level preload declaration model.
## Expected Spec Follow-up
- Common asset specification spec.
- Virtual asset contract spec.
- Format-specific specs such as `TILES/indexed_v1`.
## Non-Goals
- Final CLI UX for authoring these files.
- Incremental build internals.
- Cartridge shipper consumption details.
@@ -1,179 +0,0 @@
# Build Artifacts and Deterministic Packing Agenda
## Status
Closed
Resolved by [`003-build-artifacts-and-deterministic-packing-decision.md`](../decisions/003-build-artifacts-and-deterministic-packing-decision.md).
## Purpose
Close the contract for packer build outputs and the determinism rules that make them reproducible.
## Context
The draft proposes two core build artifacts:
- `build/assets.pa`
- `build/asset_table.json`
At least one of these artifacts must form a documented interface that `../runtime` can consume safely.
That runtime-facing contract should be specified before the implementation hardens around incidental file structure.
It also states strong determinism requirements:
- deterministic asset order,
- deterministic derived outputs,
- explicit materialization of inferred defaults.
This is a strong basis for normative packer output specs.
## Source Sections
- `8. Build Artifacts Produced by the Packer`
- `9. Determinism Rules`
## Runtime Normative Inputs
From `../runtime/docs/runtime/specs/13-cartridge.md`:
- `assets.pa` is the runtime-facing artifact;
- `assets.pa` v1 is an autocontained binary with:
- fixed binary prelude,
- JSON header,
- binary payload region;
- the fixed prelude contains, at minimum:
- `magic`,
- `schema_version`,
- `header_len`,
- `payload_offset`;
- the JSON header carries:
- `asset_table`,
- `preload`.
From `../runtime/docs/runtime/specs/15-asset-management.md`:
- `asset_table` entries currently expose:
- `asset_id`,
- `asset_name`,
- `bank_type`,
- `offset`,
- `size`,
- `decoded_size`,
- `codec`,
- `metadata`;
- `offset` is relative to the payload region inside `assets.pa`, not to the start of the full file;
- `preload` is boot-time input only;
- runtime loading is based on `open_slice` over payload slices;
- the runtime must not require the entire payload to stay resident in RAM.
These are already normative runtime-facing requirements and should be treated as baseline constraints for packer output design.
For this agenda, the intended direction is:
- `assets.pa` is the authoritative runtime-facing artifact;
- `build/asset_table.json` is a companion tooling artifact derived from the same build result;
- runtime must not depend on `build/asset_table.json` as its primary source of truth.
Current runtime code now resolves preload by `asset_id`, but game-facing runtime APIs still refer to assets by `asset_name`.
Therefore this agenda distinguishes:
- `asset_id` as stable artifact identity for preload/bootstrap and asset-table integrity;
- `asset_name` as logical API-level identifier used by game/runtime-facing calls today.
This agenda does not introduce a second runtime-only asset identity.
The `asset_id` emitted by the packer is the same `asset_id` used in the runtime-facing artifact contract.
## Key Questions
1. How should the packer spec mirror the already normative `assets.pa` v1 envelope from runtime specs 13 and 15?
2. Which fields in `build/asset_table.json` are companion tooling data versus runtime-facing contract data?
3. Should global asset packing order be deterministic by `asset_id`, or influenced by usage and format-specific heuristics?
4. How should alignment be expressed and validated?
5. What exactly counts as determinism for virtual asset pipelines?
6. Which inferred values must be written back versus only emitted in build outputs?
7. Which packer-side metadata is intentionally excluded from the runtime-facing contract?
8. How should packer document `preload` lifecycle and `offset` semantics so they match runtime reader behavior?
9. How should per-asset preload declarations be transformed into the `preload` section of `assets.pa` deterministically?
10. How should the packer preserve both `asset_id` integrity and `asset_name` lookup semantics in runtime-facing artifacts?
11. Should `asset_table` be modeled as a deterministically ordered asset list that preserves packer `asset_id` values end-to-end?
12. Which envelope fields are runtime-validated versus emitted only for Studio/tooling use?
## Options
### Option A
Keep `assets.pa` as the authoritative autocontained runtime-facing artifact and emit `build/asset_table.json` as a derived companion artifact for Studio and tooling.
### Option B
Keep runtime-facing structure split across `assets.pa` and `build/asset_table.json`.
## Tradeoffs
- Option A matches the runtime specs already in force.
- Option A keeps runtime authority in one artifact and prevents contract drift.
- Option A still allows rich tooling through a derived companion file.
- Option B risks splitting authority across artifacts and making runtime/tooling divergence easier.
## Recommendation
Adopt Option A with these fixed directions:
- `assets.pa` is the authoritative runtime-facing artifact;
- the `assets.pa` header is the authoritative runtime-facing descriptor;
- `build/asset_table.json` is a derived companion artifact for Studio, debugging, inspection, and shipper/tooling integration;
- global packing order is deterministic by increasing `asset_id`;
- preload emission is derived deterministically from per-asset `preload.enabled`;
- alignment exists only when explicitly required by spec;
- offsets are always relative to the payload region, never to the start of the full file;
- checksum is not part of the baseline `assets.pa` envelope contract.
Also adopt this performance direction:
- usage-based hot-first packing is not part of the baseline contract;
- deterministic stable ordering is preferred over heuristic physical reordering;
- future locality optimization may be introduced only through an explicit later decision and spec, not as an implementation shortcut now.
Also adopt this identity direction:
- runtime-facing preload entries should migrate to stable `asset_id` instead of mutable `asset_name`;
- runtime-facing preload/bootstrap integrity should treat `asset_id` as primary identity;
- `asset_name` remains present in `asset_table` as logical descriptive and API-facing metadata used by current runtime/game-facing calls;
- `asset_table` should be generated deterministically on every build from the current managed asset set;
- `asset_table` should be emitted as a deterministically ordered list of asset entries;
- the runtime-facing `asset_id` is exactly the stable `asset_id` allocated by the packer registry;
- stable cross-build identity comes from `asset_id`, not from table position;
- rename of `asset_name` is therefore an API-visible/content-visible change, but not an identity change.
Also adopt this companion-artifact direction:
- `build/asset_table.json` should mirror the runtime-facing header data 1:1 for debugging and inspection;
- if richer tooling artifacts are needed, they should be emitted as separate files instead of overloading `build/asset_table.json`.
## Expected Decisions to Produce
1. v1 artifact boundary and ownership.
2. Deterministic ordering and alignment rules.
3. Descriptor schema responsibilities.
4. Materialization requirements for inferred values.
5. Runtime-facing artifact contract and reader expectations.
6. Packer-side restatement of the runtime-owned `assets.pa` envelope and slice semantics.
7. Deterministic mapping from asset declarations to runtime preload data.
8. Explicit exclusion of usage-based packing heuristics from the baseline contract.
9. Migration of preload/bootstrap integrity toward `asset_id`-based identity while preserving `asset_name` as current API-facing metadata.
10. Deterministically ordered `asset_table` preserving packer `asset_id` values end-to-end.
11. Separation between runtime-validated envelope fields and non-envelope tooling concerns.
## Expected Spec Follow-up
- Packed ROM artifact spec.
- Asset table descriptor spec.
- Determinism and reproducibility spec.
- Runtime consumption interface spec.
## Non-Goals
- Asset workspace mutation commands.
- Quarantine behavior.
- Shipper packaging flow.
@@ -1,82 +0,0 @@
# Diagnostics, Doctor, Quarantine, and Workspace Hygiene Agenda
## Status
Closed
Resolved by [`004-diagnostics-doctor-quarantine-and-workspace-hygiene-decision.md`](../decisions/004-diagnostics-doctor-quarantine-and-workspace-hygiene-decision.md).
## Purpose
Define the packer as a "sanity guardian" with explicit diagnostics, workspace scanning, quarantine, and garbage collection behavior.
## Context
One of the strongest ideas in the draft is that packer should help users survive a messy `assets/` workspace.
The document already sketches:
- structured diagnostics,
- `doctor` modes,
- orphan and duplicate detection,
- quarantine,
- garbage collection.
This deserves a dedicated decision because it strongly shapes user trust in the tool.
## Source Sections
- `10. Diagnostics and the "Sanity Guardian" Chain`
- `12. Quarantine and Garbage Collection`
## Key Questions
1. Which diagnostics are build-blocking versus advisory?
2. What is the normative distinction between registry validation and workspace hygiene scanning?
3. Which automatic fixes are considered safe?
4. What operations require explicit consent?
5. How should quarantine be modeled: reversible staging area or semi-managed trash bin?
6. How aggressive should duplicate and orphan detection be?
## Options
### Option A
Keep a strict separation:
- registry errors block builds,
- workspace hygiene warnings inform users,
- destructive or moving operations always require explicit consent.
### Option B
Let doctor apply broader automatic remediation by default.
## Tradeoffs
- Option A is safer and easier to trust.
- Option A aligns with the draft's explicit-user-consent direction.
- Option B may save time in some cases, but it raises risk of surprising workspace mutations.
## Recommendation
Adopt Option A and make reversibility plus explicit consent core packer invariants.
## Expected Decisions to Produce
1. Diagnostic classes and severities.
2. Scope and modes of `doctor`.
3. Safety model for `--fix`, `gc`, and quarantine.
4. Workspace hygiene responsibilities of the packer.
## Expected Spec Follow-up
- Diagnostics contract spec.
- Doctor and workspace scan spec.
- Quarantine and garbage collection spec.
## Non-Goals
- Detailed asset format validation rules.
- Final watch mode design.
- Runtime-facing artifact schemas.
@@ -1,79 +0,0 @@
# Incremental Build, Cache, and Watch Model Agenda
## Status
Closed
Resolved by [`005-incremental-build-cache-and-watch-model-decision.md`](../decisions/005-incremental-build-cache-and-watch-model-decision.md).
## Purpose
Define how packer caches, fingerprints, and optional watch behavior should work without compromising determinism.
## Context
The draft proposes:
- fingerprint tracking in `assets/.prometeu/cache/fingerprints.json`,
- incremental rebuilds,
- strong hashing,
- optional watch mode.
This area is operationally important but easy to underspecify.
## Source Sections
- `11. Incremental Build, Cache, and Fingerprints`
- `13.10 prometeu packer watch`
## Key Questions
1. Which fingerprints are authoritative for cache invalidation?
2. When are `mtime` and size only hints versus hard cache keys?
3. What outputs may be reused from cache, and under which conditions?
4. Does watch mode belong in v1 spec or only as non-normative future work?
5. How should cache invalidation be surfaced to users and diagnostics?
6. How do we guarantee that incremental behavior never changes final outputs?
## Options
### Option A
Specify cache behavior conservatively and keep watch mode optional or non-normative in the first wave.
### Option B
Make watch mode and aggressive incremental behavior part of the early normative contract.
## Tradeoffs
- Option A reduces spec risk and keeps determinism easier to enforce.
- Option A allows cache internals to evolve while the artifact contract stabilizes first.
- Option B may be attractive for UX, but it increases the amount of behavior that must be frozen too early.
## Recommendation
Adopt Option A:
- deterministic outputs first,
- conservative cache spec,
- watch mode optional until the underlying invariants are stable.
## Expected Decisions to Produce
1. Cache authority and invalidation model.
2. Fingerprint contract.
3. Normative versus non-normative status of watch mode.
4. Safety rules for incremental reuse.
## Expected Spec Follow-up
- Cache and fingerprints spec.
- Incremental build guarantees spec.
- Optional watch mode spec or deferred note.
## Non-Goals
- Full CLI command catalog.
- Asset registry identity rules.
- Cartridge shipper integration.
@@ -1,118 +0,0 @@
# CLI Surface and Mutating Operations Agenda
## Status
Closed
Resolved by [`006-studio-first-asset-services-and-event-lane-decision.md`](../decisions/006-studio-first-asset-services-and-event-lane-decision.md).
## Purpose
Define the stable Studio-facing service contract for packer operations, especially operations that mutate registry state or user files.
## Context
The draft already lists a substantial command surface:
- `init`
- `add`
- `adopt`
- `forget`
- `rm`
- `list`
- `show`
- `doctor`
- `build`
- `watch`
- `gc`
- `quarantine`
Historically, packer was framed as a CLI-first tool.
The current target is different:
- packer should be fully integrated with Studio;
- asset UI and packer services should evolve together;
- operations should exist as Studio-consumable services first;
- asset workflows should be observable through a dedicated background event lane for UI integration;
- CLI, if retained, should be treated as a later adapter rather than the design center.
This means the architectural work should focus on service semantics and UI integration points first, not on freezing a command-line contract too early.
## Source Sections
- `13. CLI Commands (Comprehensive)`
## Key Questions
1. Which packer operations are core Studio services in v1 and which are later capabilities?
2. Which identifiers should Studio-facing services accept for normal asset workflows: name, id, uuid, root path?
3. Which operations mutate registry only versus mutate workspace files?
4. What requires explicit confirmation, preview, or staged apply behavior in Studio?
5. How should safe fix flows be exposed as service operations rather than CLI flags?
6. Which responses must be structured for UI consumption and automation?
7. What, if anything, should remain CLI-specific in the future adapter layer?
8. Should assets have a dedicated background event lane that reports changes, diagnostics, and build activity to the UI?
## Options
### Option A
Define a minimal stable v1 Studio service surface and mark the rest as future or optional.
### Option B
Freeze a larger command catalog immediately.
## Tradeoffs
- Option A lowers the early compatibility burden.
- Option A matches the Studio-integrated direction better because services and UI can stabilize together before any CLI freeze.
- 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 around the wrong adapter.
## Recommendation
Adopt Option A and distinguish:
- required core services,
- optional future adapters,
- future operations not yet in the normative contract.
Current design target:
- Studio integration is primary;
- asset UI and packer services should be designed together;
- service contracts should describe intent, preview, apply, and result models suitable for UI workflows;
- asset-oriented operations should publish structured background events suitable for logs, progress, and live UI refresh;
- CLI should not drive the core architecture in this phase.
Also adopt this integration direction:
- the system should have a dedicated asset workspace event lane;
- this lane observes relevant asset and registry changes, triggers analysis/rebuild workflows as appropriate, and reports structured events to the UI;
- the architectural contract is the event/reporting surface, not a commitment to a specific threading primitive;
- dangerous mutations still require explicit user intent and must not be silently auto-applied by the background lane.
## Expected Decisions to Produce
1. Core v1 Studio service set.
2. Mutation safety and preview/apply model.
3. Identifier resolution rules.
4. Structured response contracts for UI and automation.
5. Boundary between core services and future adapters.
6. Asset workspace event lane and structured event model for UI reporting.
## Expected Spec Follow-up
- Service operation contract spec.
- Studio asset workflow integration spec.
- Mutation and confirmation policy spec.
- Structured response/output contract spec.
- Asset event/reporting integration spec.
## Non-Goals
- Asset payload binary layout.
- Format-specific `asset.json` rules.
- Detailed cache internals.
- Freezing a comprehensive CLI contract in the current phase.
@@ -1,103 +0,0 @@
# Shipper Integration, Versioning, and Trust Model Agenda
## Status
Closed
Resolved by [`007-shipper-integration-versioning-and-trust-model-decision.md`](../decisions/007-shipper-integration-versioning-and-trust-model-decision.md).
## Purpose
Close the cross-domain contracts around shipper integration, schema versioning, migrations, and the packer trust model.
## Context
The tail of the draft contains several cross-cutting commitments:
- shipper consumes packer outputs,
- `../runtime` must be able to read the packer-produced artifact contract,
- multiple JSON artifacts carry `schema_version`,
- packer must migrate older schemas or emit actionable diagnostics,
- packer is offline tooling and must not execute untrusted scripts.
These topics are cross-domain and should be discussed together before hardening the specs.
The first step should be to document the runtime-facing interface explicitly instead of leaving it implicit in tooling behavior.
## Source Sections
- `15. Integration with Cartridge Shipper`
- `16. Compatibility and Versioning`
- `17. Security and Trust Model`
## Runtime Normative Inputs
From `../runtime/docs/runtime/specs/13-cartridge.md`:
- cartridges may contain optional `assets.pa`;
- when `Asset` capability is declared, valid `assets.pa` is required before asset bootstrap;
- runtime validation failure must happen before preload execution;
- `assets.pa` is the runtime-facing asset artifact for the current runtime.
From `../runtime/docs/runtime/specs/15-asset-management.md`:
- the runtime-facing asset model is bank-centric;
- `preload` is boot-time input only;
- runtime residency and bank ownership are independent from VM heap ownership;
- asset loading uses slice-based access over `assets.pa`;
- schema-bearing runtime-facing structures already exist and must be versioned carefully.
These runtime specs already constrain packer evolution. The packer discussion should focus on how to honor and document this contract on the tooling side.
## Key Questions
1. Which integration points with shipper are packer-owned versus shared contracts?
2. Which artifacts need explicit migration policy?
3. Is backward compatibility required for all schema versions or only within a support window?
4. What counts as trusted configuration versus untrusted input data?
5. Can packer ever execute plugin-like transformations, or is that forbidden by architecture?
6. How should migration failures be surfaced to users and CI?
7. How should the runtime reader contract be versioned and documented?
8. Which compatibility guarantees apply specifically to `../runtime` consumption?
9. Which parts of the runtime-facing contract are owned by runtime specs versus packer-owned companion specs?
## Options
### Option A
Keep shipper integration narrow, schema versioning explicit, and trust model conservative.
### Option B
Allow broader extensibility and looser compatibility commitments.
## Tradeoffs
- Option A is easier to secure and specify.
- Option A supports reliable CI and migration diagnostics.
- Option B may feel more flexible, but it introduces major review and safety burden early.
## Recommendation
Adopt Option A and treat schema evolution plus trust boundaries as first-class contracts.
## Expected Decisions to Produce
1. Shipper integration boundary.
2. Schema versioning and migration policy.
3. Compatibility guarantees.
4. Security and trust invariants.
5. Runtime consumption contract and versioning boundary.
6. Ownership split between runtime normative specs and packer-side companion documentation.
## Expected Spec Follow-up
- Shipper integration spec.
- Schema versioning and migration spec.
- Security and trust model spec.
- Runtime reader and compatibility interface spec.
## Non-Goals
- CLI ergonomics for all commands.
- Detailed asset format transformation pipelines.
- Workspace hygiene behavior.
+1 -1
View File
@@ -6,7 +6,7 @@ This directory contains active packer discussion agendas.
There are currently no active packer agendas.
The first packer agenda wave (`01.0` through `01.7`) has been closed into decision records under [`../decisions/`](../decisions/).
The first packer agenda wave was consolidated into normative specs under [`../specs/`](../specs/) and didactic material under [`../learn/`](../learn/).
## Purpose