updated packer specs

This commit is contained in:
2026-03-24 13:42:38 +00:00
parent f27b28c516
commit e3389e78b6
10 changed files with 951 additions and 0 deletions
@@ -0,0 +1,76 @@
# Domain and Artifact Boundary Specification
Status: Draft
Scope: Packer domain core boundary
Purpose: Define what the packer owns, what it emits, and where its responsibility stops.
## Authority and Precedence
This specification is grounded in:
- [`001-asset-workspace-registry-and-stable-identity-decision.md`](../decisions/001-asset-workspace-registry-and-stable-identity-decision.md)
- [`003-build-artifacts-and-deterministic-packing-decision.md`](../decisions/003-build-artifacts-and-deterministic-packing-decision.md)
- [`007-shipper-integration-versioning-and-trust-model-decision.md`](../decisions/007-shipper-integration-versioning-and-trust-model-decision.md)
Runtime-side reading semantics for `assets.pa` are defined upstream in `../runtime/docs/runtime/specs/13-cartridge.md` and `../runtime/docs/runtime/specs/15-asset-management.md`.
## Normative Inputs
- project workspace with `assets/`
- packer registry and control data under `assets/.prometeu/`
- managed asset roots anchored by `asset.json`
## Core Rules
1. The packer owns asset workspace management and artifact production.
2. The packer emits the runtime-facing asset artifact `assets.pa`.
3. The packer may emit companion build artifacts for Studio and tooling.
4. The packer does not own cartridge shipping/publication.
5. A future shipper is a consumer of packer artifacts, not a co-author of the asset contract.
6. Runtime reading semantics are not redefined by the packer.
7. The packer must stop at artifact publication, not cartridge assembly.
## Packer-Owned Artifacts
The packer owns production of at least:
- `assets.pa`
- `build/asset_table.json`
- `build/preload.json`
- `build/asset_table_metadata.json`
- `asset.json`
- `assets/.prometeu/index.json`
## Runtime-Facing Boundary
`assets.pa` is the authoritative runtime-facing artifact.
Rules:
- the internal header of `assets.pa` is the runtime-facing source of truth for asset table and preload data;
- companion JSON outputs must not replace the internal header as the runtime contract;
- offsets and preload semantics must remain aligned with runtime specs.
## Future Shipper Boundary
The future shipper may consume packer artifacts to assemble cartridges.
Rules:
- the packer must not depend on a concrete shipper implementation now;
- shipper-specific workflow detail is deferred;
- published artifact names and meanings must remain documented and stable enough for later consumption.
## Non-Goals
- cartridge assembly flow
- package distribution format design
- runtime asset loading implementation detail
## Exit Criteria
This specification is complete enough when:
- packer ownership is unambiguous;
- runtime-facing artifact authority is explicit;
- future shipper integration is bounded without overdesign.
@@ -0,0 +1,98 @@
# Workspace, Registry, and Asset Identity Specification
Status: Draft
Scope: Managed asset roots, registry authority, and stable identity
Purpose: Define how the packer recognizes, tracks, and preserves asset identity.
## Authority and Precedence
This specification is grounded in:
- [`001-asset-workspace-registry-and-stable-identity-decision.md`](../decisions/001-asset-workspace-registry-and-stable-identity-decision.md)
## Normative Inputs
- `assets/`
- `assets/.prometeu/index.json`
- per-asset `asset.json`
## Core Rules
1. One managed asset equals one asset root directory.
2. One asset root contains exactly one anchor `asset.json`.
3. `assets/.prometeu/index.json` is the authoritative registry of managed assets.
4. `asset.json` is the authoritative asset-local declaration.
5. An asset root absent from the registry is not part of the managed build set.
## Identity Model
Each managed asset has:
- `asset_id`: stable project-local identity
- `asset_uuid`: stable long-lived identity for migration/tooling scenarios
The following are not primary identity:
- `asset_name`
- filesystem path
- internal input file names
`asset_name` may still be used by authoring and runtime-facing APIs as a logical reference label.
## Relocation and Rename
Moving or renaming an asset root does not change identity.
Rules:
- `asset_id` remains unchanged;
- `asset_uuid` remains unchanged;
- registry location is updated;
- relocation is not recreation.
Renaming `asset_name` is an API-visible change, but not an identity change.
## Orphan Anchors
An `asset.json` without a corresponding registry entry is an orphan declaration.
Rules:
- it does not enter the build automatically;
- it is diagnosable;
- it is adoptable only through explicit flow.
## Asset ID Allocation
`asset_id` allocation is registry-owned and strictly monotonic within a project.
Rules:
- allocation occurs at registration time;
- issued IDs are not silently recycled;
- allocator state is persisted in the registry;
- rollback is not baseline behavior.
## Structural Conflicts
Identity-bearing conflicts are structural errors.
Examples:
- duplicate or ambiguous anchors under managed expectations;
- manual copy that creates identity collision;
- registered root missing anchor.
## Non-Goals
- full `asset.json` schema
- asset format-specific metadata
- UI/editor workflow detail
## Exit Criteria
This specification is complete enough when:
- managed asset boundaries are unambiguous;
- registry authority is explicit;
- identity survives relocation without ambiguity.
@@ -0,0 +1,146 @@
# Asset Declaration and Virtual Asset Contract Specification
Status: Draft
Scope: Common `asset.json` contract
Purpose: Define the shared declaration model for raw and virtual assets.
## Authority and Precedence
This specification is grounded in:
- [`002-asset-specification-raw-assets-and-virtual-asset-contract-decision.md`](../decisions/002-asset-specification-raw-assets-and-virtual-asset-contract-decision.md)
## Core Rules
The common `asset.json` contract requires these top-level fields:
- `schema_version`
- `name`
- `type`
- `inputs`
- `output`
- `preload`
The common contract may also include:
- `build`
## Meaning of `name`
`name` is the logical asset reference label.
Rules:
- it is required;
- it is not the stable artifact identity;
- it may still be used by runtime-facing APIs and source-level workflows.
## Meaning of `type`
`type` identifies the authoring-side asset family.
Rules:
- it is not the runtime bank identity;
- the runtime-facing technical target belongs in `output.format`.
Examples:
- `image_bank`
- `sound_bank`
## Inputs
`inputs` is a structured object keyed by semantic role.
Rules:
- each key names an input role such as `sprites`, `palettes`, or `sources`;
- each value is a list of paths;
- paths are relative to the asset root;
- even a single input is represented as a list.
This model supports grouped virtual assets such as atlases and bank-style assets.
## Output
`output` is the runtime-relevant output declaration.
Required baseline fields:
- `output.format`
- `output.codec`
Optional baseline field:
- `output.metadata`
Rules:
- `output.format` defines the semantic/runtime format contract;
- `output.codec` defines storage/extraction behavior;
- `output.metadata` carries runtime-relevant format-specific detail;
- codec must remain explicit and must not be hidden inside format naming.
## Build
`build` is optional and process-oriented.
Rules:
- it may describe how authoring inputs are transformed or organized;
- if a parameter affects the runtime-facing output contract, it belongs in `output.metadata`;
- `build` must not hide runtime-relevant semantics.
## Preload
Each managed asset must declare preload intent explicitly.
Baseline shape:
```json
{
"preload": {
"enabled": true
}
}
```
Rules:
- `preload.enabled` is required and boolean;
- preload participation is declared, not inferred;
- richer preload policy fields are deferred.
## Defaults and Materialization
Defaults that affect runtime-visible behavior must not remain hidden.
Rules:
- runtime-relevant defaults should be materialized in `asset.json` whenever practical;
- if materialized later, the resulting artifact must expose effective values explicitly.
## Versioning
The `asset.json` schema is versioned independently from:
- registry schema
- runtime-facing artifact schema
- format contract versions
Format-specific contracts evolve through values such as `TILES/indexed_v1`.
## Non-Goals
- field-level format schemas for every output family
- rich preload policies
- source-language lowering behavior for asset references
## Exit Criteria
This specification is complete enough when:
- the common `asset.json` shape is stable;
- raw and virtual assets share a coherent baseline contract;
- format-specific specs can build on it cleanly.
@@ -0,0 +1,142 @@
# Build Artifacts and Deterministic Packing Specification
Status: Draft
Scope: Runtime-facing artifacts and deterministic build behavior
Purpose: Define how the packer emits `assets.pa` and companion artifacts.
## Authority and Precedence
This specification is grounded in:
- [`003-build-artifacts-and-deterministic-packing-decision.md`](../decisions/003-build-artifacts-and-deterministic-packing-decision.md)
Runtime-side reading semantics remain upstream in:
- `../runtime/docs/runtime/specs/13-cartridge.md`
- `../runtime/docs/runtime/specs/15-asset-management.md`
## Core Rules
1. `assets.pa` is the authoritative runtime-facing artifact.
2. Companion JSON files do not replace the internal header as the runtime contract.
3. The global asset table order is deterministic by increasing `asset_id`.
4. The runtime-facing `asset_id` is the same stable `asset_id` allocated by the packer registry.
## `assets.pa` Structure
Baseline structure:
```text
[fixed binary prelude]
[canonical JSON header]
[binary payload region]
```
### Prelude Fields
The baseline prelude includes:
- `magic`
- `schema_version`
- `header_len`
- `payload_offset`
- `flags`
- `reserved`
Rules:
- `flags` and `reserved` exist from day 1;
- `flags = 0` unless later specified otherwise;
- `reserved = 0` unless later specified otherwise;
- `header_checksum` is not part of the baseline envelope contract.
## Canonical JSON Header
The header is serialized canonically.
Rules:
- UTF-8 encoding;
- no extra whitespace;
- object keys sorted lexicographically;
- arrays preserve declared order;
- canonicalization applies recursively;
- runtime-facing header values in v1 must avoid floating-point numbers.
## Header Contents
The header carries:
- `asset_table`
- `preload`
### Asset Table
`asset_table` is emitted as a deterministically ordered list of asset entries.
Rules:
- one entry per managed asset in the current build set;
- no secondary runtime-only identity layer;
- no synthetic dense reindexing layer;
- `asset_name` remains present as logical/API-facing metadata.
### Preload
Preload is emitted deterministically from per-asset declaration.
Rules:
- assets with `preload.enabled = false` do not appear in emitted preload data;
- assets with `preload.enabled = true` do appear;
- preload ordering is deterministic by increasing `asset_id`.
## Companion Artifacts
The baseline companion artifacts are:
- `build/asset_table.json`
- `build/preload.json`
- `build/asset_table_metadata.json`
Rules:
- `build/asset_table.json` mirrors `header.asset_table` 1:1;
- `build/preload.json` mirrors `header.preload` 1:1;
- `build/asset_table_metadata.json` is tooling-only;
- richer tooling data must not be added to the 1:1 mirror files.
## Alignment and Offsets
Alignment exists only when explicitly required by spec.
Rules:
- there is no implicit baseline alignment beyond envelope and format requirements;
- any required alignment must be normative and visible;
- emitted offsets are always relative to the payload region, never the start of the full file.
## Determinism
Equivalent build inputs must produce equivalent outputs.
Rules:
- no filesystem iteration dependence;
- no hidden defaults that affect output;
- no usage-based hot-first packing in the baseline contract;
- determinism is preferred over speculative physical-layout optimization.
## Non-Goals
- per-format payload internals for every output family
- future locality optimization policy
- cartridge-level integrity/signature strategy
## Exit Criteria
This specification is complete enough when:
- runtime-facing artifact authority is explicit;
- companion artifacts are bounded;
- emitted ordering and header behavior are deterministic.
@@ -0,0 +1,156 @@
# Diagnostics, Operations, and Studio Integration Specification
Status: Draft
Scope: Diagnostics, service operations, and Studio-facing event/reporting model
Purpose: Define how the packer exposes safe operational behavior to Studio and tooling.
## Authority and Precedence
This specification is grounded in:
- [`004-diagnostics-doctor-quarantine-and-workspace-hygiene-decision.md`](../decisions/004-diagnostics-doctor-quarantine-and-workspace-hygiene-decision.md)
- [`005-incremental-build-cache-and-watch-model-decision.md`](../decisions/005-incremental-build-cache-and-watch-model-decision.md)
- [`006-studio-first-asset-services-and-event-lane-decision.md`](../decisions/006-studio-first-asset-services-and-event-lane-decision.md)
## Diagnostics Model
Diagnostics are divided into:
- structural managed-world errors;
- advisory workspace hygiene diagnostics.
Rules:
- structural managed-world errors block builds;
- hygiene findings do not block baseline builds by default;
- workspace scanning is broader than build validation.
## Doctor Model
Baseline doctor behavior:
- managed-world validation by default;
- broader workspace hygiene scanning in expanded workspace mode;
- safe mechanical fix application only for baseline fix flows.
Unsafe automatic mutation is out of scope for baseline doctor behavior.
## Safety and Consent
Rules:
- destructive or relocational mutations require explicit consent;
- quarantine is explicit and reversible;
- duplicate content detection is advisory, not structurally invalid by itself;
- orphan anchors are diagnosable, not build-active.
## Studio-First Service Surface
The normative operational surface is service-based.
Baseline core services:
- `init_workspace`
- `register_asset`
- `adopt_asset`
- `forget_asset`
- `remove_asset`
- `list_assets`
- `get_asset_details`
- `doctor`
- `build`
## Operation Classes
Operations must distinguish:
- read-only operations;
- registry mutations;
- workspace mutations.
This distinction is part of the service semantics and must be visible to the UI.
## Preview/Apply Model
Sensitive mutations use staged intent.
Rules:
- preview or analysis precedes broad mutation where appropriate;
- safe-fix flows are modeled as services, not merely terminal flags;
- `forget_asset` and `remove_asset` remain distinct operations.
## Structured Responses
Service responses must be structured.
At minimum, the model should support fields equivalent to:
- `status`
- `summary`
- `affected_assets`
- `diagnostics`
- `proposed_actions`
- `applied_actions`
- `blockers`
## Asset Event Lane
The system includes a dedicated asset workspace event/reporting lane.
Responsibilities:
- observe relevant asset and registry changes;
- report diagnostics/build/cache activity to the UI;
- support live refresh and progress reporting;
- avoid blocking the main UI thread.
### Initial Event Set
The initial structured event set includes:
- `asset_discovered`
- `asset_changed`
- `diagnostics_updated`
- `build_started`
- `build_finished`
- `cache_hit`
- `cache_miss`
- `preview_ready`
- `action_applied`
- `action_failed`
- `progress_updated`
### Mutation Serialization
Mutating asset workflows are serialized semantically.
Rules:
- background observation and reporting may be continuous;
- conflicting sensitive mutations must not race arbitrarily;
- observable mutation behavior remains coherent from the UI perspective.
## Incremental and Watch Integration
Incremental behavior is an optimization only.
Rules:
- full and incremental builds must be observably equivalent;
- watch mode is optional in the baseline contract;
- watch does not authorize silent dangerous mutation.
## Non-Goals
- final visual design of Studio asset panels
- future CLI grammar
- remote/shared cache orchestration
## Exit Criteria
This specification is complete enough when:
- Studio-facing operational semantics are explicit;
- safety/preview/apply behavior is clear;
- event/reporting integration has a stable baseline.
@@ -0,0 +1,122 @@
# Versioning, Migration, and Trust Model Specification
Status: Draft
Scope: Artifact/schema versioning, migration ownership, and conservative trust boundaries
Purpose: Define how the packer evolves safely over time and what trust assumptions it makes.
## Authority and Precedence
This specification is grounded in:
- [`007-shipper-integration-versioning-and-trust-model-decision.md`](../decisions/007-shipper-integration-versioning-and-trust-model-decision.md)
## Core Rules
1. Versioning is explicit and per artifact/schema.
2. Migration applies only to artifacts the packer owns.
3. Compatibility is governed by a support window, not indefinite backward guarantees.
4. Inputs are untrusted until validated.
5. Baseline packer architecture does not execute arbitrary plugins or scripts.
## Explicit Versioning Surfaces
The packer versioning model applies to at least:
- `asset.json`
- `index.json`
- `assets.pa`
- the `assets.pa` header contract
- companion build artifacts where a stable reader exists
- packer-owned cache/control schemas where migration is supported
## Migration Ownership
The packer owns migration of artifacts it controls.
This includes:
- `asset.json`
- `index.json`
- packer-owned caches and control files
Rules:
- migration may be automatic within the supported window;
- unsupported versions fail clearly and early;
- migration failures must be diagnosable in Studio and CI.
## Runtime Compatibility Boundary
Runtime reading semantics for `assets.pa` belong upstream to runtime specs.
Rules:
- the packer implements the corresponding writer-side production contract;
- the packer must not redefine runtime reader semantics;
- companion artifacts do not redefine the runtime-facing contract.
## Future Shipper Boundary
The future shipper is a consumer of packer artifacts.
Rules:
- the shipper is not a current packer dependency;
- the shipper must not become a silent repair layer for invalid packer artifacts;
- shipper workflow detail is deferred until the shipper exists.
## Trust Model
The trust posture is conservative.
Untrusted until validated:
- source asset files;
- hand-edited or legacy declarations;
- imported external project content;
- legacy packer artifacts and control data.
Trusted only after:
- strict parse;
- structural validation;
- semantic validation;
- version compatibility check.
## Plugin and Script Execution
The baseline packer contract forbids arbitrary external execution as part of normal asset processing.
Rules:
- no untrusted plugins;
- no ad hoc script execution;
- no implicit foreign-code extension hooks.
Any future extensibility model requires a separate decision.
## Failure Surfacing
Version and migration failures must be actionable.
At minimum, diagnostics should make clear:
- the version found;
- the supported range or expectation;
- whether migration was attempted;
- whether manual action is required;
- whether the failure blocks build or Studio workflow.
## Non-Goals
- artifact signing strategy
- distribution security beyond current tooling trust posture
- remote/shared artifact registry behavior
## Exit Criteria
This specification is complete enough when:
- artifact versioning boundaries are explicit;
- migration ownership is unambiguous;
- trust assumptions are conservative and enforceable.
+22
View File
@@ -52,3 +52,25 @@ Specs should normally be fed by:
4. then spec integration.
If a spec edit would require guessing an unresolved design choice, stop and surface the missing decision first.
## Current Corpus
The current packer core corpus is:
1. [`1. Domain and Artifact Boundary Specification.md`](./1.%20Domain%20and%20Artifact%20Boundary%20Specification.md)
2. [`2. Workspace, Registry, and Asset Identity Specification.md`](./2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md)
3. [`3. Asset Declaration and Virtual Asset Contract Specification.md`](./3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md)
4. [`4. Build Artifacts and Deterministic Packing Specification.md`](./4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
5. [`5. Diagnostics, Operations, and Studio Integration Specification.md`](./5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
6. [`6. Versioning, Migration, and Trust Model Specification.md`](./6.%20Versioning,%20Migration,%20and%20Trust%20Model%20Specification.md)
## Reading Order
Recommended order:
1. domain and artifact boundary;
2. workspace and identity;
3. asset declaration;
4. build artifacts;
5. diagnostics and Studio operation model;
6. versioning and trust.