discussion framework migration

This commit is contained in:
2026-03-26 18:45:46 +00:00
parent e78b72f61a
commit 38d8c25bba
90 changed files with 1150 additions and 2585 deletions
@@ -0,0 +1,72 @@
# 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 consolidates the initial packer agenda and decision wave into normative form.
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/`
- registered 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,145 @@
# Workspace, Registry, and Asset Identity Specification
Status: Draft
Scope: Registered asset roots, registry authority, and stable identity
Purpose: Define how the packer recognizes, tracks, and preserves asset identity.
## Authority and Precedence
This specification consolidates the initial packer agenda and decision wave into normative form.
## Normative Inputs
- `assets/`
- `assets/.prometeu/index.json`
- per-asset `asset.json`
## Core Rules
1. One registered 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 registered assets.
4. `asset.json` is the authoritative asset-local declaration.
5. `asset.json` must carry the stable `asset_uuid` identity anchor for that asset root.
6. An asset root absent from the registry is `unregistered`.
7. `unregistered` assets are always `excluded` from build participation.
8. Registered assets may be `included` or `excluded` from build participation without losing identity.
9. The baseline build set includes registered assets whose registry entry is marked as build-included.
## Identity Model
Each registered asset has:
- `asset_id`: stable project-local identity
- `asset_uuid`: stable long-lived identity for migration/tooling scenarios
- `included_in_build`: build participation flag persisted in the registry
Identity authority is intentionally split:
- `asset_uuid` is anchored locally in `asset.json`;
- `asset_id` is allocated and persisted by the registry;
- registry-managed location and build participation remain catalog concerns in `index.json`.
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.
## Local Identity Anchor
`asset_uuid` is the stable asset-local identity anchor.
Rules:
- `asset_uuid` must be present in `asset.json`;
- `asset_uuid` is stable across relocate and rename flows;
- `asset_uuid` is not allocated from path shape or `asset_name`;
- `asset_uuid` allows the packer to reconcile manual workspace changes with the registry/catalog model;
- `asset_uuid` does not replace registry authority over `asset_id`, build participation, or managed root tracking.
## 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.
## Unregistered Roots
An `asset.json` without a corresponding registry entry is an unregistered asset root.
Rules:
- it is excluded from the build automatically;
- it is diagnosable;
- it becomes registered only through explicit flow;
- its local `asset_uuid` still matters for structural validation and future reconcile behavior.
## Build Participation
Build participation is registry-owned for registered assets.
Rules:
- excluding a registered asset from builds does not remove `asset_id`;
- excluding a registered asset from builds does not remove `asset_uuid`;
- inclusion changes must preserve asset identity and registry location;
- unregistered assets cannot be marked as build-included.
## 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 registered expectations;
- manual copy that creates identity collision;
- registered root missing anchor;
- duplicate `asset_uuid` across different asset roots;
- registry/catalog location that no longer matches the asset root carrying the expected `asset_uuid`;
- `asset.json` missing or malformed in a root expected to preserve identity.
## Reconcile Expectations
The packer may need to reconcile registry/catalog state against the authoring workspace.
Rules:
- manual move or rename of an asset root must not imply identity loss by itself;
- reconcile should prefer `asset_uuid` when matching a durable asset identity across changed paths;
- path drift must not silently rebind one registered asset to another distinct `asset_uuid`;
- unresolved identity drift remains diagnosable until explicit repair or successful reconcile.
## Non-Goals
- full `asset.json` schema
- asset format-specific metadata
- UI/editor workflow detail
## Exit Criteria
This specification is complete enough when:
- registered asset boundaries are unambiguous;
- registry authority is explicit;
- identity survives relocation without ambiguity.
@@ -0,0 +1,217 @@
# 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 consolidates the initial packer agenda and decision wave into normative form.
## Core Rules
The common `asset.json` contract requires these top-level fields:
- `schema_version`
- `asset_uuid`
- `name`
- `type`
- `inputs`
- `output`
- `preload`
The common contract may also include:
- `build`
## Meaning of `asset_uuid`
`asset_uuid` is the stable asset-local identity anchor.
Rules:
- it is required;
- it must be stable across relocate and rename flows;
- it is not the project-local runtime artifact identity;
- it is not a substitute for registry-owned `asset_id`;
- it exists so the asset root can preserve identity even when path-based assumptions drift;
- it must remain compatible with packer reconcile behavior and migration flows.
## 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:
- `tile_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`
- `output.pipeline`
Rules:
- `output.format` defines the semantic/runtime format contract;
- `output.codec` defines storage/extraction behavior;
- `output.metadata` carries runtime-relevant format-specific detail;
- `output.pipeline` carries pipeline-injected metadata kept separate at authoring time;
- codec must remain explicit and must not be hidden inside format naming.
### Explicit Index Collections
When `output.pipeline` carries ordered collections whose members need stable semantic identity, that identity must not depend on raw list position alone.
Rules:
- collections such as `output.pipeline.palettes` may remain JSON arrays for authoring ergonomics;
- when a collection member has runtime- or packing-relevant identity, each entry must carry an explicit `index`;
- `output.pipeline.palettes` entries must use the shape `{ "index": <int>, "palette": { ... } }`;
- the packer must sort such entries by numeric `index`, not by physical array position;
- duplicate or malformed indices are structural errors;
- missing or malformed `palette` payloads are structural errors;
- editorial reordering of the JSON array alone must not change semantic meaning.
Example:
```json
{
"output": {
"pipeline": {
"palettes": [
{
"index": 0,
"palette": {
"originalArgb8888": [4294901760, 4278255360],
"convertedRgb565": [63488, 2016]
}
}
]
}
}
}
```
## Metadata Source Segmentation and Runtime Sink
`asset.json` may keep metadata segmented by concern during authoring.
Rules:
- declaration-time metadata may come from multiple sources under the asset contract (for example, format metadata, codec-related metadata, and build/pipeline-derived declarations);
- `output.pipeline` may carry nested pipeline-derived metadata objects;
- this segmentation exists for authoring clarity and does not define multiple runtime sinks;
- runtime consumers must read effective metadata from the runtime asset entry metadata sink (`AssetEntry.metadata`);
- convergence/normalization behavior is normative in the build artifact specification.
## 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.
## Operational State Exclusion
`asset.json` is a declaration artifact, not a catalog cache.
Rules:
- transient UI state must not be stored in `asset.json`;
- registry-managed fields such as `asset_id` and `included_in_build` must not be duplicated into `asset.json`;
- packer cache or snapshot bookkeeping must not be materialized into `asset.json` as normal operational state;
- `asset.json` should remain focused on identity anchoring plus declared authoring/packing behavior.
## Preload
Each registered 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,231 @@
# 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 consolidates the initial packer agenda and decision wave into normative form.
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 included 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.
### Asset Entry Metadata Convergence
Each emitted asset entry has one runtime metadata sink: `AssetEntry.metadata`.
Rules:
- packer materialization must normalize all runtime-consumable metadata-producing sources into `asset_table[].metadata`;
- equivalent declaration/build inputs must produce equivalent normalized metadata;
- metadata key collisions across independent sources must fail build unless the family/format spec declares an explicit merge rule;
- normalization behavior must be testable and covered by conformance-oriented tests.
Baseline normalized metadata segmentation:
- `output.metadata` materializes at the metadata root;
- `output.codec_configuration` materializes under `metadata.codec`;
- `output.pipeline` materializes under `metadata.pipeline`;
- format-specific runtime-required fields may remain directly readable at the metadata root when the runtime consumer requires them there.
### 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.
Offset ambiguity guardrail:
- `asset_table[].offset`/`asset_table[].size` describe payload slicing inside `assets.pa`;
- internal pipeline indexing data (for example per-sample ranges for audio banks) must live under `asset_table[].metadata`;
- internal indexing fields must not be interpreted as payload slicing fields.
## Format-Specific Baseline: `TILES/indexed_v1`
The first-wave producer contract for `TILES/indexed_v1` is fixed and runtime-aligned.
### Tile Selection and Identity
Rules:
- only selected artifacts participate in the emitted tile bank;
- `1 artifact = 1 tile` in v1;
- artifacts are normalized by ascending `artifacts[*].index`;
- emitted `tile_id` equals the normalized artifact index;
- duplicate or gapped artifact indices are build-blocking structural failures.
### Emitted Sheet Shape
Rules:
- the emitted tile-bank sheet is always `256 x 256` in v1;
- tile placement within that emitted sheet is row-major;
- runtime `width` and `height` for the bank entry therefore refer to the full emitted sheet, not one individual artifact;
- resulting per-bank capacities are:
- `tile_size = 8` -> `1024` tiles
- `tile_size = 16` -> `256` tiles
- `tile_size = 32` -> `64` tiles
- capacity overflow is a build-blocking structural failure.
### Payload Layout
Rules:
- the serialized payload for `TILES/indexed_v1` is:
1. one packed `u4` pixel plane for the full emitted sheet;
2. one palette block of `64 * 16 * 2 = 2048` bytes;
- packed pixel bytes must be emitted by the packer, not inferred later by the runtime;
- the palette block is serialized as `RGB565` `u16` values;
- palette bytes must be emitted in little-endian order;
- payload interpretation must not depend on incidental per-artifact boundaries.
### Runtime Entry Derivation
Rules:
- emitted tile-bank entries use:
- `bank_type = TILES`
- `codec = NONE`
- tile-bank v1 metadata must expose at least:
- `tile_size`
- `width`
- `height`
- `palette_count`
- tile-bank v1 requires `palette_count = 64`;
- tile-bank v1 size formulas are:
- `size = ceil(width * height / 2) + 2048`
- `decoded_size = (width * height) + 2048`
### Palette Contract
Rules:
- bank palettes are declared under `output.pipeline.palettes`;
- each palette declaration uses the shape `{ "index": <int>, "palette": { ... } }`;
- palette ordering is ascending numeric `index`, never raw array position;
- palette ids in the emitted tile bank are the normalized declared palette indices;
- any tile in the bank may be rendered with any palette in the bank at runtime;
- palette selection is a runtime draw concern, not a tile-payload embedding concern.
## 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,257 @@
# 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 consolidates the initial packer agenda and decision wave into normative form.
## Diagnostics Model
Diagnostics are divided into:
- structural registered-world errors;
- advisory workspace hygiene diagnostics.
Rules:
- structural registered-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:
- registered-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;
- unregistered asset roots are diagnosable and remain excluded from builds.
## Studio-First Service Surface
The normative operational surface is service-based.
The packer is a filesystem-first operational runtime.
Rules:
- the active project may maintain a coherent in-memory operational snapshot;
- normal read requests should be served from that coherent snapshot when the runtime is active;
- the runtime snapshot is an operational projection of packer-owned workspace artifacts, not a replacement authoring store;
- the durable authoring workspace remains the persisted source of truth after successful commit.
### Embedded Bootstrap Rule
When the packer is embedded inside another host such as Studio, the host must bootstrap the packer integration explicitly.
Rules:
- the embedded packer runtime must receive a typed event bus reference from the host when shared host visibility is part of the integration contract;
- that reference is the baseline path for packer publish/subscribe integration in the embedded host;
- the embedded packer runtime must not quietly create a disconnected parallel event system when host integration expects shared operational visibility;
- in Studio, this shared typed event bus reference is owned by the Studio `Container`.
Baseline core services:
- `init_workspace`
- `register_asset`
- `include_asset_in_build`
- `exclude_asset_from_build`
- `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.
## Runtime State and Visibility
The packer runtime must make operational freshness explicit.
At minimum, the model should support states equivalent to:
- `healthy`
- `stale`
- `diverged`
- `committing`
- `reconciling`
- `failed`
Rules:
- successful durable commit defines the visibility boundary for committed write state;
- reads must not present torn in-progress writes as committed truth;
- background divergence detection may move a project or asset view into stale/diverged/reconciling state;
- Studio may render these states, but must not invent their semantics.
## Concurrency Model
The packer concurrency model is conservative and project-scoped.
Rules:
- observable correctness takes priority over speculative parallelism;
- operations are coordinated per project workspace, not globally across unrelated projects;
- Studio is a consumer of packer coordination results, not the owner of packer concurrency policy.
### Baseline Operation Matrix
- read/read may run concurrently when each read observes a coherent snapshot;
- read/write must not expose torn intermediate state to consumers;
- write/write on the same project is serialized;
- build/write on the same project is serialized unless a future spec introduces an explicit transactional coordination model;
- background observation may continue while a serialized write lane is active, but it must not publish misleading post-state before commit visibility.
### Write Ownership
- writes on one project execute through a packer-owned write lane;
- caller timing must not define final write interleaving semantics;
- preview generation may occur before the final commit section when safe;
- apply/commit remains the packer-owned visibility boundary.
## 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;
- `exclude_asset_from_build` and `remove_asset` remain distinct operations.
## Structured Responses
Service responses must be structured.
At minimum, the model should support fields equivalent to:
- `status`
- `summary`
- `runtime_state`
- `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.
- surface operational freshness and reconcile transitions when they affect Studio-visible state.
### 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`
Additional runtime/reconcile state events may exist as the operational runtime evolves, but adapters must preserve their causal meaning instead of collapsing them into generic refresh noise.
### 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.
- the baseline write policy is a single-writer semantic lane per project;
- preview generation may run outside the final commit section, but apply/commit remains serialized;
- build and sensitive mutation apply must not interleave on the same project in a way that obscures final state;
- cancellation or failure must leave the observable project state in a coherent post-operation condition.
- divergence detection must not silently rewrite user-authored workspace content as if it were a normal mutation apply.
### Event Envelope
Packer events must be structured enough for adapters to preserve causality and user-facing meaning.
At minimum, each event must carry fields equivalent to:
- `project_id` or workspace identity
- `operation_id`
- `sequence`
- `kind`
- `timestamp`
- `summary`
- `progress` when applicable
- `affected_assets` when applicable
Rules:
- `operation_id` is stable for the full lifecycle of one logical operation;
- `sequence` is monotonic within one operation;
- adapters may remap event shapes for UI consumption, but must not invent causal relationships not present in packer events.
- embedded hosts should preserve the same typed event bus reference across packer bootstrap and adapter wiring so subscription and publication stay causally coherent.
### Event Ordering and Coalescing
Rules:
- events emitted for one operation must be observable in causal order;
- repeated progress updates may be coalesced by adapters or sinks;
- lifecycle boundaries such as preview-ready, apply-success, apply-failure, build-started, and build-finished must remain individually observable;
- low-value repeated observation events must not drown out actionable failures or terminal state.
## 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,124 @@
# 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 consolidates the initial packer agenda and decision wave into normative form.
## 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.
- migration may need to preserve or repair identity-bearing fields such as `asset_uuid` without fabricating a different asset identity silently.
## 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.
- runtime snapshot observations that have not yet been reconciled against changed workspace files.
Trusted only after:
- strict parse;
- structural validation;
- semantic validation;
- version compatibility check.
- reconcile or refresh when divergence between snapshot and filesystem has been detected.
## 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 identity-bearing fields or registry/catalog alignment were implicated;
- 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.
+75
View File
@@ -0,0 +1,75 @@
# Packer Specs
This directory contains the normative packer specification set.
## Purpose
Specs define the official packer contract.
They exist to make behavior, constraints, interfaces, and artifact guarantees stable across implementation and review.
The packer normative content is maintained directly in this `specs/` corpus.
## Expected Format
The exact structure may vary by document, but a packer spec should usually contain:
1. Title
2. Status
3. Scope or Applies To
4. Purpose
5. Authority and Precedence
6. Normative Inputs
7. Core Rules
8. Non-Goals
9. Exit Criteria
Some specs may also include:
- artifact schemas,
- invariants,
- diagnostic contracts,
- examples,
- migration notes,
- explicit TODO sections for tracked unresolved items.
## Writing Rules
- Write in normative language.
- Integrate only decisions that have already been closed.
- Keep debate history and option analysis out of the spec body.
- Preserve clear boundaries between adjacent packer specs.
- Use TODO only for explicitly tracked unresolved items, not as a substitute for agenda work.
## Upstream Rule
Specs should normally be fed by:
1. agendas that frame the open topic,
2. decisions that close the architectural question,
3. pull-request plans that define propagation,
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.