clean up
This commit is contained in:
@@ -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.
|
||||
-140
@@ -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.
|
||||
-82
@@ -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.
|
||||
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user