discussion framework migration
This commit is contained in:
@@ -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.
|
||||
+257
@@ -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.
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user