clean up
This commit is contained in:
@@ -1,197 +0,0 @@
|
||||
# Asset Workspace, Registry, and Stable Identity Decision
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Date
|
||||
|
||||
2026-03-11
|
||||
|
||||
## Context
|
||||
|
||||
This decision closes the architectural questions raised in [`01.1. Asset Workspace, Registry, and Stable Identity Agenda`](../agendas/01.1.%20Asset%20Workspace,%20Registry,%20and%20Stable%20Identity%20Agenda.md).
|
||||
|
||||
The packer needs a stable model for:
|
||||
|
||||
- what counts as a managed asset;
|
||||
- how local asset declaration relates to workspace registry state;
|
||||
- how asset identity survives rename and relocation;
|
||||
- how adoption and diagnostics distinguish registered from unregistered asset roots.
|
||||
|
||||
If this model remains ambiguous, later specs for `asset.json`, virtual assets, diagnostics, build outputs, and Studio services will inherit unstable semantics.
|
||||
|
||||
## Decision
|
||||
|
||||
The packer adopts a `registry-authoritative, anchor-declared, identity-stable, path-mutable` model.
|
||||
|
||||
### 1. Managed asset unit
|
||||
|
||||
A managed asset is one asset root directory.
|
||||
|
||||
Rules:
|
||||
|
||||
- one managed asset maps to one dedicated asset root directory;
|
||||
- one asset root contains exactly one anchor `asset.json`;
|
||||
- files and subdirectories under that root are inputs or support files of that managed asset unless explicitly modeled otherwise in future specs;
|
||||
- individual source files are not separate managed assets by default.
|
||||
|
||||
This allows grouped assets such as atlases, image banks, or palette-driven bundles to be modeled as one managed asset with many inputs.
|
||||
|
||||
### 2. Registry authority
|
||||
|
||||
`assets/.prometeu/index.json` is the authoritative workspace registry for managed assets.
|
||||
|
||||
It defines:
|
||||
|
||||
- which assets are officially managed by the packer;
|
||||
- their stable project-local identities;
|
||||
- their current registered root locations;
|
||||
- allocator state and registry-owned metadata.
|
||||
|
||||
If an asset root is not present in `index.json`, it is not part of the managed build set.
|
||||
|
||||
### 3. Asset-local declaration
|
||||
|
||||
`asset.json` is the asset-local declaration anchored at the asset root.
|
||||
|
||||
It defines the local declaration of the asset, including the asset contract that later specs will refine.
|
||||
|
||||
`asset.json` does not, by itself, make an asset managed.
|
||||
Registration and build inclusion remain registry-owned concerns.
|
||||
|
||||
### 4. Identity model
|
||||
|
||||
Each managed asset has:
|
||||
|
||||
- `asset_id`: stable project-local identity;
|
||||
- `asset_uuid`: stable long-lived identity for tooling and migration scenarios.
|
||||
|
||||
The following are not primary identity:
|
||||
|
||||
- display name;
|
||||
- filesystem path;
|
||||
- internal input filenames.
|
||||
|
||||
Name and path are mutable presentation or location fields.
|
||||
|
||||
However, `asset_name` may still participate in authoring and runtime-facing APIs as a logical reference label.
|
||||
That does not make it the stable identity of the asset.
|
||||
|
||||
Practical consequence:
|
||||
|
||||
- changing `asset_name` does not create a new asset identity;
|
||||
- but changing `asset_name` may still require source-level or tooling-level reference updates where game/runtime APIs refer to assets by name.
|
||||
|
||||
### 5. Relocation and rename
|
||||
|
||||
Moving or renaming an asset root does not create a new asset.
|
||||
|
||||
Rules:
|
||||
|
||||
- `asset_id` must remain unchanged;
|
||||
- `asset_uuid` must remain unchanged;
|
||||
- registry location is updated to the new asset root;
|
||||
- this is treated as relocation, not recreation.
|
||||
|
||||
### 6. Orphan anchor behavior
|
||||
|
||||
An `asset.json` without a corresponding registry entry is an orphan asset declaration.
|
||||
|
||||
Rules:
|
||||
|
||||
- it does not enter the build automatically;
|
||||
- it must be surfaced by workspace diagnostics such as `doctor --workspace`;
|
||||
- it may be incorporated only through explicit adoption flow.
|
||||
|
||||
### 7. `asset_id` allocation
|
||||
|
||||
`asset_id` allocation is registry-owned and strictly monotonic within the project.
|
||||
|
||||
Rules:
|
||||
|
||||
- allocation happens once at registration time;
|
||||
- previously issued IDs must not be silently recycled;
|
||||
- allocator state is persisted in `index.json`;
|
||||
- allocator rollback is not allowed as normal behavior.
|
||||
|
||||
If audit metadata is useful, it should be recorded separately, for example as creation metadata.
|
||||
Time should not be encoded into the runtime-facing identity model without a concrete future need.
|
||||
|
||||
### 8. Manual copy and identity collision
|
||||
|
||||
Manual copy of an asset root that duplicates identity-bearing content must not be reconciled implicitly.
|
||||
|
||||
Rules:
|
||||
|
||||
- packer must surface identity collision or duplicate-anchor diagnostics explicitly;
|
||||
- packer must not silently guess whether the copy is a rename, clone, or replacement;
|
||||
- resolution must happen through explicit user action or future dedicated workflows.
|
||||
|
||||
## Invariants and Constraints
|
||||
|
||||
The following invariants now apply:
|
||||
|
||||
1. One managed asset equals one asset root.
|
||||
2. One managed asset root contains exactly one anchor `asset.json`.
|
||||
3. `index.json` is the authoritative managed registry.
|
||||
4. `asset.json` is the authoritative asset-local declaration.
|
||||
5. `asset_id` is stable, monotonic, and non-recycled.
|
||||
6. `asset_uuid` is stable across relocation.
|
||||
7. Path and display name are mutable and not primary identity.
|
||||
8. Orphan `asset.json` declarations are diagnosable but not build-active.
|
||||
9. Copy-induced identity collisions are explicit errors, not heuristic reconciliation cases.
|
||||
|
||||
## Explicit Non-Decisions
|
||||
|
||||
This decision does not yet define:
|
||||
|
||||
- the detailed schema of `asset.json`;
|
||||
- the field-level boundary between common asset declaration and format-specific declaration;
|
||||
- CLI or Studio service APIs;
|
||||
- detailed adoption UX;
|
||||
- detailed garbage collection and quarantine behavior;
|
||||
- runtime artifact formats such as `assets.pa`.
|
||||
|
||||
Those belong to later decisions and specs.
|
||||
|
||||
## Propagation Targets
|
||||
|
||||
This decision must propagate to:
|
||||
|
||||
- packer workspace and control files specs;
|
||||
- packer managed asset and identity specs;
|
||||
- packer registry consistency and diagnostics specs;
|
||||
- future Studio service contracts for adoption, registration, move, rename, and inspection;
|
||||
- future implementation of registry persistence and identity allocation.
|
||||
|
||||
## Validation Notes
|
||||
|
||||
Example: grouped atlas asset
|
||||
|
||||
```text
|
||||
assets/
|
||||
ui_atlas/
|
||||
asset.json
|
||||
sprites/
|
||||
confirm.png
|
||||
cancel.png
|
||||
palettes/
|
||||
ui_main.pal
|
||||
```
|
||||
|
||||
This is one managed asset, not many.
|
||||
The internal files are inputs of the asset root declared by `asset.json`.
|
||||
|
||||
Example: relocation
|
||||
|
||||
- `assets/ui_atlas/` moves to `assets/ui/common_atlas/`
|
||||
- `asset_id` remains the same
|
||||
- `asset_uuid` remains the same
|
||||
- only the registered root path changes
|
||||
|
||||
Example: orphan anchor
|
||||
|
||||
- `assets/wip/new_bank/asset.json` exists
|
||||
- no corresponding registry entry exists in `index.json`
|
||||
- the asset is diagnosable and adoptable, but not part of the managed build set
|
||||
-282
@@ -1,282 +0,0 @@
|
||||
# Asset Specification, Raw Assets, and Virtual Asset Contract Decision
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Date
|
||||
|
||||
2026-03-11
|
||||
|
||||
## Context
|
||||
|
||||
This decision closes the architectural questions raised in [`01.2. Asset Specification, Raw Assets, and Virtual Asset Contract Agenda`](../agendas/01.2.%20Asset%20Specification,%20Raw%20Assets,%20and%20Virtual%20Asset%20Contract%20Agenda.md).
|
||||
|
||||
The packer needs a stable baseline contract for `asset.json` before detailed format-specific specs are written.
|
||||
|
||||
This contract must:
|
||||
|
||||
- support one managed asset root with many internal inputs;
|
||||
- distinguish raw assets from virtual assets without making the common schema monolithic;
|
||||
- expose runtime-relevant output information explicitly;
|
||||
- declare preload intent deterministically;
|
||||
- leave room for future format families without coupling all formats together.
|
||||
|
||||
## Decision
|
||||
|
||||
The packer adopts a compact common `asset.json` contract with explicit separation between:
|
||||
|
||||
- authoring asset family;
|
||||
- grouped input declaration;
|
||||
- runtime-facing output contract;
|
||||
- preload declaration;
|
||||
- optional build/process hints.
|
||||
|
||||
### 1. Common top-level shape
|
||||
|
||||
The common `asset.json` contract includes these required top-level fields:
|
||||
|
||||
- `schema_version`
|
||||
- `name`
|
||||
- `type`
|
||||
- `inputs`
|
||||
- `output`
|
||||
- `preload`
|
||||
|
||||
The common contract may additionally include:
|
||||
|
||||
- `build`
|
||||
|
||||
`build` is optional in the shared baseline schema.
|
||||
|
||||
### 2. Meaning of `type`
|
||||
|
||||
`type` identifies the authoring-side asset family.
|
||||
|
||||
It is not the runtime bank target.
|
||||
|
||||
Examples of valid family-style values:
|
||||
|
||||
- `image_bank`
|
||||
- `sound_bank`
|
||||
|
||||
The runtime-facing technical target belongs in `output.format`, not in `type`.
|
||||
|
||||
`name` remains the required logical asset reference label.
|
||||
|
||||
Meaning:
|
||||
|
||||
- `name` is not the stable artifact identity;
|
||||
- `name` is the human-facing and code-facing reference used by asset-oriented APIs unless a future compile-time rewrite model replaces it;
|
||||
- renaming `name` is an API-visible change even though it does not change `asset_id`.
|
||||
|
||||
### 3. Input declaration model
|
||||
|
||||
`inputs` is a structured object keyed by semantic role.
|
||||
|
||||
Rules:
|
||||
|
||||
- each key identifies 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, not as a scalar.
|
||||
|
||||
This avoids shape ambiguity and supports grouped virtual assets cleanly.
|
||||
|
||||
Example:
|
||||
|
||||
```json
|
||||
"inputs": {
|
||||
"sprites": [
|
||||
"sprites/confirm.png",
|
||||
"sprites/cancel.png"
|
||||
],
|
||||
"palettes": [
|
||||
"palettes/ui_main.pal"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Output contract
|
||||
|
||||
`output` is the runtime-relevant output declaration.
|
||||
|
||||
The common baseline requires:
|
||||
|
||||
- `output.format`
|
||||
- `output.codec`
|
||||
|
||||
`output.metadata` is optional in the common schema, but becomes required whenever the selected format spec requires additional normative parameters.
|
||||
|
||||
Meaning:
|
||||
|
||||
- `output.format` identifies the semantic/runtime format contract;
|
||||
- `output.codec` identifies how payload bytes are stored for extraction and materialization;
|
||||
- `output.metadata` carries format-specific runtime-relevant details.
|
||||
|
||||
Codec must remain explicit.
|
||||
It must not be hidden inside format naming when it represents a distinct storage concern.
|
||||
|
||||
### 5. Raw and virtual asset contract
|
||||
|
||||
The common schema must support both raw and virtual assets.
|
||||
|
||||
Rules:
|
||||
|
||||
- raw assets may declare a direct input-to-output path with minimal build metadata;
|
||||
- virtual assets may declare multiple grouped inputs and optional build/process configuration;
|
||||
- the common schema remains small, while detailed format behavior is defined in dedicated format specs.
|
||||
|
||||
### 6. Build/process hints
|
||||
|
||||
`build` is optional and carries process-oriented configuration.
|
||||
|
||||
Rules:
|
||||
|
||||
- `build` may describe how the packer should transform or organize authoring inputs;
|
||||
- if a parameter affects the runtime-facing output contract, it belongs in `output.metadata`;
|
||||
- `build` must not become a hidden substitute for runtime-relevant output definition.
|
||||
|
||||
Practical interpretation:
|
||||
|
||||
- `output.metadata` describes the contract of the produced payload;
|
||||
- `build` describes how the packer gets there.
|
||||
|
||||
### 7. Preload declaration
|
||||
|
||||
Each managed asset must declare preload intent explicitly.
|
||||
|
||||
The baseline shape is:
|
||||
|
||||
```json
|
||||
"preload": {
|
||||
"enabled": true
|
||||
}
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- `preload.enabled` is required and boolean;
|
||||
- preload participation is declared, not inferred;
|
||||
- packer build uses this field to determine whether preload data is emitted into the runtime-facing artifact contract;
|
||||
- richer preload policy fields are deferred to future decisions and must not be implied silently now.
|
||||
|
||||
### 8. Defaults and materialization
|
||||
|
||||
Defaults may exist in specs, but defaults that affect reproducibility, compatibility, preload, or runtime-visible output must not remain invisible.
|
||||
|
||||
Rules:
|
||||
|
||||
- runtime-relevant defaults should be materialized in `asset.json` whenever practical;
|
||||
- if materialization occurs later in the pipeline, the resulting artifact must still expose the effective value explicitly;
|
||||
- packer must not rely on hidden defaults to produce runtime-visible behavior.
|
||||
|
||||
### 9. Versioning boundary
|
||||
|
||||
Versioning is split by concern.
|
||||
|
||||
Rules:
|
||||
|
||||
- `asset.json` carries its own `schema_version`;
|
||||
- registry schemas are versioned independently;
|
||||
- runtime-facing artifact schemas are versioned independently;
|
||||
- format contracts are versioned independently through `output.format` values such as `TILES/indexed_v1` or `SOUNDS/pcm16le_v1`.
|
||||
|
||||
This prevents unrelated schema evolution from being coupled together.
|
||||
|
||||
## Invariants and Constraints
|
||||
|
||||
The following invariants now apply:
|
||||
|
||||
1. The common `asset.json` contract remains compact.
|
||||
2. `type` is authoring-side family identity, not runtime bank identity.
|
||||
3. `inputs` is structured by semantic role.
|
||||
4. Input path values are always lists.
|
||||
5. `name` remains a logical asset reference label even though it is not the stable artifact identity.
|
||||
6. `output.format` and `output.codec` are separate required concerns.
|
||||
7. Runtime-relevant format details belong in `output.metadata`.
|
||||
8. `build` is optional and must not hide runtime-facing output semantics.
|
||||
9. `preload.enabled` is the only preload field closed in the current baseline.
|
||||
10. Defaults affecting runtime-visible behavior must be materialized explicitly.
|
||||
11. Format evolution is versioned independently from registry and artifact schema evolution.
|
||||
|
||||
## Explicit Non-Decisions
|
||||
|
||||
This decision does not yet define:
|
||||
|
||||
- the full field-level schema of each format family;
|
||||
- richer preload policies beyond `preload.enabled`;
|
||||
- globbing support, input discovery shortcuts, or non-path input locators;
|
||||
- CLI or Studio editor UX for authoring `asset.json`;
|
||||
- exact `assets.pa` payload layout details;
|
||||
- exact runtime preload record encoding.
|
||||
|
||||
Those belong to later decisions and specs.
|
||||
|
||||
## Propagation Targets
|
||||
|
||||
This decision must propagate to:
|
||||
|
||||
- common asset declaration spec;
|
||||
- virtual asset contract spec;
|
||||
- format-specific specs such as `TILES/indexed_v1` and `SOUNDS/pcm16le_v1`;
|
||||
- preload emission and artifact mapping specs;
|
||||
- Studio service contracts for asset authoring and validation;
|
||||
- future implementation of asset parsing, validation, and deterministic build planning.
|
||||
|
||||
## Validation Notes
|
||||
|
||||
Example: grouped image asset
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": 1,
|
||||
"name": "ui_atlas",
|
||||
"type": "image_bank",
|
||||
"inputs": {
|
||||
"sprites": [
|
||||
"sprites/confirm.png",
|
||||
"sprites/cancel.png"
|
||||
],
|
||||
"palettes": [
|
||||
"palettes/ui_main.pal"
|
||||
]
|
||||
},
|
||||
"output": {
|
||||
"format": "TILES/indexed_v1",
|
||||
"codec": "RAW",
|
||||
"metadata": {
|
||||
"tile_size": [8, 8]
|
||||
}
|
||||
},
|
||||
"preload": {
|
||||
"enabled": true
|
||||
},
|
||||
"build": {
|
||||
"layout": "atlas"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Example: grouped sound asset
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": 1,
|
||||
"name": "ui_sounds",
|
||||
"type": "sound_bank",
|
||||
"inputs": {
|
||||
"sources": [
|
||||
"wav/click.wav",
|
||||
"wav/confirm.wav"
|
||||
]
|
||||
},
|
||||
"output": {
|
||||
"format": "SOUNDS/pcm16le_v1",
|
||||
"codec": "RAW"
|
||||
},
|
||||
"preload": {
|
||||
"enabled": false
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -1,250 +0,0 @@
|
||||
# Build Artifacts and Deterministic Packing Decision
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Date
|
||||
|
||||
2026-03-11
|
||||
|
||||
## Context
|
||||
|
||||
This decision closes the architectural questions raised in [`01.3. Build Artifacts and Deterministic Packing Agenda`](../agendas/01.3.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Agenda.md).
|
||||
|
||||
The packer must produce build artifacts that are:
|
||||
|
||||
- deterministic;
|
||||
- aligned with the runtime-facing `assets.pa` contract already established in `../runtime`;
|
||||
- usable by Studio and tooling without creating a second source of truth;
|
||||
- stable enough to support future specs and implementation.
|
||||
|
||||
The runtime-side contract already establishes that:
|
||||
|
||||
- `assets.pa` is the runtime-facing artifact;
|
||||
- `asset_table` and `preload` live in the internal JSON header;
|
||||
- offsets are relative to the payload region;
|
||||
- preload is boot-time input only.
|
||||
|
||||
This decision closes how the packer should produce these artifacts.
|
||||
|
||||
## Decision
|
||||
|
||||
The packer adopts an `assets.pa`-authoritative, deterministically ordered, canonical-header model.
|
||||
|
||||
### 1. Artifact authority
|
||||
|
||||
`assets.pa` is the authoritative runtime-facing artifact.
|
||||
|
||||
Rules:
|
||||
|
||||
- the `assets.pa` header is the runtime-facing source of truth for `asset_table` and `preload`;
|
||||
- `build/asset_table.json` and other JSON outputs are companion artifacts only;
|
||||
- runtime must not depend on companion JSON files as its primary contract.
|
||||
|
||||
### 2. Companion artifacts
|
||||
|
||||
The packer emits separate companion artifacts for tooling and debugging.
|
||||
|
||||
Baseline companion outputs:
|
||||
|
||||
- `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 and may carry richer packer metadata;
|
||||
- richer tooling data must not be smuggled into the runtime-facing mirror files.
|
||||
|
||||
### 3. `assets.pa` v1 prelude
|
||||
|
||||
The baseline packer-side prelude for `assets.pa` v1 includes:
|
||||
|
||||
- `magic`
|
||||
- `schema_version`
|
||||
- `header_len`
|
||||
- `payload_offset`
|
||||
- `flags`
|
||||
- `reserved`
|
||||
|
||||
Rules:
|
||||
|
||||
- `flags` exists from day 1 for forward compatibility;
|
||||
- `reserved` exists from day 1 for forward compatibility;
|
||||
- `flags = 0` in the current baseline unless a future spec says otherwise;
|
||||
- `reserved = 0` in the current baseline unless a future spec says otherwise;
|
||||
- `header_checksum` is not part of the baseline `assets.pa` envelope contract.
|
||||
|
||||
### 4. Checksum policy
|
||||
|
||||
Header checksum is not part of the baseline runtime-facing envelope.
|
||||
|
||||
Rules:
|
||||
|
||||
- runtime validation does not depend on header checksum;
|
||||
- cartridge-level integrity may be handled elsewhere;
|
||||
- Studio/tooling may compute checks or hashes separately if needed;
|
||||
- such checks must not redefine the runtime-facing `assets.pa` envelope.
|
||||
|
||||
### 5. Canonical JSON header
|
||||
|
||||
The JSON header of `assets.pa` must be serialized canonically.
|
||||
|
||||
Canonicalization rules:
|
||||
|
||||
- UTF-8 encoding;
|
||||
- no extra whitespace;
|
||||
- object keys sorted lexicographically;
|
||||
- arrays preserve declared order;
|
||||
- canonicalization applies recursively, including nested metadata objects;
|
||||
- runtime-facing header values in v1 must avoid floating-point numbers.
|
||||
|
||||
This is required so equivalent inputs produce byte-identical headers and therefore byte-reproducible artifacts.
|
||||
|
||||
### 6. Ordering and determinism
|
||||
|
||||
The global `asset_table` order is deterministic by increasing `asset_id`.
|
||||
|
||||
Rules:
|
||||
|
||||
- usage-based or hot-first packing is not part of the baseline contract;
|
||||
- format-specific heuristics must not reorder the global asset list;
|
||||
- deterministic ordering is preferred over physical-layout heuristics;
|
||||
- future locality optimization requires a separate explicit decision and spec.
|
||||
|
||||
### 7. `asset_id` continuity
|
||||
|
||||
The `asset_id` used in runtime-facing artifacts is the same stable `asset_id` allocated by the packer registry.
|
||||
|
||||
Rules:
|
||||
|
||||
- the packer does not generate a second runtime-only asset identity;
|
||||
- `preload` refers to the same `asset_id` values that appear in `asset_table`;
|
||||
- table position does not define identity;
|
||||
- cross-build identity stability comes from `asset_id`, not from table index.
|
||||
|
||||
### 8. Asset table shape
|
||||
|
||||
`asset_table` is emitted as a deterministically ordered list of asset entries.
|
||||
|
||||
Rules:
|
||||
|
||||
- one emitted entry per managed asset in the build set;
|
||||
- no synthetic dense reindexing layer is introduced;
|
||||
- omission of removed assets happens naturally because the emitted table reflects the current build set only;
|
||||
- the runtime sees a normal contiguous list of entries, but the IDs inside it remain the stable packer IDs.
|
||||
|
||||
### 9. `asset_name` in runtime-facing artifacts
|
||||
|
||||
`asset_name` remains present in `asset_table`.
|
||||
|
||||
Meaning:
|
||||
|
||||
- `asset_name` is logical descriptive and API-facing metadata;
|
||||
- current runtime/game-facing calls may still use it for normal asset lookup;
|
||||
- preload/bootstrap integrity relies on `asset_id`, not `asset_name`;
|
||||
- renaming `asset_name` is an API-visible/content-visible change, but not an asset identity change.
|
||||
|
||||
### 10. Preload mapping
|
||||
|
||||
Preload emission is derived deterministically from per-asset declaration.
|
||||
|
||||
Rules:
|
||||
|
||||
- assets with `preload.enabled = false` do not appear in emitted preload data;
|
||||
- assets with `preload.enabled = true` produce preload entries in the runtime-facing preload list;
|
||||
- emitted preload ordering is deterministic by increasing `asset_id`;
|
||||
- preload is boot-time input only and must be emitted in a form consistent with the runtime contract.
|
||||
|
||||
### 11. Alignment
|
||||
|
||||
Alignment exists only when explicitly required by spec.
|
||||
|
||||
Rules:
|
||||
|
||||
- there is no implicit baseline alignment beyond what is required by the envelope and chosen formats;
|
||||
- if a format requires alignment, the requirement must be normative and visible in the relevant spec;
|
||||
- computed offsets must always be emitted explicitly in the runtime-facing descriptor.
|
||||
|
||||
### 12. Offsets
|
||||
|
||||
All emitted asset offsets are relative to the payload region.
|
||||
|
||||
Rules:
|
||||
|
||||
- offsets are never relative to the start of the whole `assets.pa` file;
|
||||
- this rule must be preserved consistently across packer outputs and specs;
|
||||
- companion artifacts must mirror the same offset semantics.
|
||||
|
||||
## Invariants and Constraints
|
||||
|
||||
The following invariants now apply:
|
||||
|
||||
1. `assets.pa` is the authoritative runtime-facing artifact.
|
||||
2. Companion JSON files do not replace the internal `assets.pa` header.
|
||||
3. `build/asset_table.json` mirrors `header.asset_table` 1:1.
|
||||
4. `build/preload.json` mirrors `header.preload` 1:1.
|
||||
5. `build/asset_table_metadata.json` is tooling-only.
|
||||
6. The prelude includes `magic`, `schema_version`, `header_len`, `payload_offset`, `flags`, and `reserved`.
|
||||
7. `header_checksum` is not part of the baseline envelope contract.
|
||||
8. Header JSON is canonicalized.
|
||||
9. Global asset ordering is deterministic by increasing `asset_id`.
|
||||
10. The runtime-facing `asset_id` is the same stable packer `asset_id`.
|
||||
11. `asset_table` is a deterministically ordered list, not a second identity system.
|
||||
12. `asset_name` remains present as logical/API-facing metadata.
|
||||
13. Preload is emitted deterministically from `preload.enabled`.
|
||||
14. Offsets are relative to the payload region only.
|
||||
|
||||
## Explicit Non-Decisions
|
||||
|
||||
This decision does not yet define:
|
||||
|
||||
- the exact field-level metadata contract of each output format;
|
||||
- richer preload policies beyond the current baseline;
|
||||
- future physical locality optimization;
|
||||
- game-language lowering of asset references from names to IDs;
|
||||
- cartridge-level integrity/signature strategy.
|
||||
|
||||
Those belong to later decisions and specs.
|
||||
|
||||
## Propagation Targets
|
||||
|
||||
This decision must propagate to:
|
||||
|
||||
- packer artifact and envelope specs;
|
||||
- packer determinism and reproducibility specs;
|
||||
- packer preload emission specs;
|
||||
- Studio tooling expectations for companion artifacts;
|
||||
- future implementation of canonical header generation and companion-file emission.
|
||||
|
||||
## Validation Notes
|
||||
|
||||
Example: artifact relationship
|
||||
|
||||
```text
|
||||
assets.pa
|
||||
prelude
|
||||
canonical header JSON
|
||||
asset_table
|
||||
preload
|
||||
payload bytes
|
||||
|
||||
build/asset_table.json
|
||||
mirrors header.asset_table
|
||||
|
||||
build/preload.json
|
||||
mirrors header.preload
|
||||
|
||||
build/asset_table_metadata.json
|
||||
tooling-only enrichment
|
||||
```
|
||||
|
||||
Example: stable identity
|
||||
|
||||
- packer registry assigns asset IDs `3`, `7`, and `11`
|
||||
- emitted `asset_table` is ordered `[3, 7, 11]`
|
||||
- runtime-facing preload entries reference `3`, `7`, or `11`
|
||||
- no additional dense runtime ID layer is introduced
|
||||
-217
@@ -1,217 +0,0 @@
|
||||
# Diagnostics, Doctor, Quarantine, and Workspace Hygiene Decision
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Date
|
||||
|
||||
2026-03-11
|
||||
|
||||
## Context
|
||||
|
||||
This decision closes the architectural questions raised in [`01.4. Diagnostics, Doctor, Quarantine, and Workspace Hygiene Agenda`](../agendas/01.4.%20Diagnostics,%20Doctor,%20Quarantine,%20and%20Workspace%20Hygiene%20Agenda.md).
|
||||
|
||||
The packer is expected to operate as a sanity guardian over a potentially messy `assets/` workspace while still preserving trust and predictability.
|
||||
|
||||
This means the packer must:
|
||||
|
||||
- protect the correctness of managed builds;
|
||||
- surface hygiene problems in the broader workspace;
|
||||
- avoid surprising destructive or reorganizing mutations;
|
||||
- keep recovery and auditability stronger than convenience heuristics.
|
||||
|
||||
## Decision
|
||||
|
||||
The packer adopts a `validate-the-managed-world, inspect-the-workspace, mutate-only-with-consent` model.
|
||||
|
||||
### 1. Diagnostic classes
|
||||
|
||||
Diagnostics are divided into two major classes:
|
||||
|
||||
- build-blocking structural errors;
|
||||
- advisory workspace hygiene diagnostics.
|
||||
|
||||
Build-blocking structural errors include, at minimum:
|
||||
|
||||
- registered asset root missing its anchor `asset.json`;
|
||||
- invalid `asset.json`;
|
||||
- missing required inputs for a managed asset;
|
||||
- output contract inconsistency;
|
||||
- invalid preload-related artifact state;
|
||||
- structural identity collisions or ambiguous ownership.
|
||||
|
||||
Advisory workspace hygiene diagnostics include, at minimum:
|
||||
|
||||
- orphan `asset.json` declarations;
|
||||
- duplicate source content by hash;
|
||||
- large unused files;
|
||||
- assets not currently referenced by managed build inputs;
|
||||
- naming or organization hints.
|
||||
|
||||
### 2. Registry validation versus workspace scanning
|
||||
|
||||
Registry validation and workspace scanning are distinct surfaces.
|
||||
|
||||
Rules:
|
||||
|
||||
- build-time validation is scoped to the managed world defined by the registry;
|
||||
- workspace scanning is a broader hygiene pass over `assets/`;
|
||||
- `doctor` without wider scope flags validates the managed world;
|
||||
- `doctor --workspace` expands visibility to broader workspace chaos.
|
||||
|
||||
The build must not silently turn into a full workspace scanner.
|
||||
|
||||
### 3. Safety model for automatic fixes
|
||||
|
||||
Automatic fixes are allowed only for corrections that are mechanical, deterministic, and safe.
|
||||
|
||||
Safe automatic fixes include:
|
||||
|
||||
- path normalization;
|
||||
- explicit materialization of already-determined defaults;
|
||||
- canonical ordering or formatting of declaration data;
|
||||
- strictly mechanical regeneration of control-file content when explicitly requested.
|
||||
|
||||
Unsafe automatic fixes are not baseline-safe:
|
||||
|
||||
- moving user content;
|
||||
- deleting user content;
|
||||
- deduplicating content by rewriting authoring files;
|
||||
- renaming assets;
|
||||
- auto-registering or auto-adopting assets without explicit consent.
|
||||
|
||||
### 4. Explicit consent policy
|
||||
|
||||
Any operation that mutates user-controlled workspace content requires explicit consent.
|
||||
|
||||
This includes:
|
||||
|
||||
- quarantine moves;
|
||||
- deletion;
|
||||
- adoption/registration of previously unmanaged assets;
|
||||
- changes in physical file location;
|
||||
- changes that alter declared authoring intent rather than only normalizing control data.
|
||||
|
||||
### 5. Quarantine model
|
||||
|
||||
Quarantine is a reversible staging area, not a magic trash bin.
|
||||
|
||||
Rules:
|
||||
|
||||
- quarantine is never automatic by default;
|
||||
- the packer must explain what is being moved and why;
|
||||
- recovery must remain possible;
|
||||
- quarantine exists to support explicit hygiene workflows, not hidden cleanup.
|
||||
|
||||
### 6. Detection aggressiveness
|
||||
|
||||
The packer should be aggressive in detection and conservative in action.
|
||||
|
||||
Meaning:
|
||||
|
||||
- detect broadly when scanning workspace hygiene;
|
||||
- report clearly and specifically;
|
||||
- avoid mutating content unless the action is explicitly requested and safe.
|
||||
|
||||
### 7. `doctor --fix`
|
||||
|
||||
`doctor --fix` is limited to safe mechanical corrections in the baseline contract.
|
||||
|
||||
Rules:
|
||||
|
||||
- it must not mutate authoring content as a baseline behavior;
|
||||
- it must not move or delete content without a stronger explicit operation;
|
||||
- it must remain predictable enough that users can trust it in Studio and CLI-adapter workflows.
|
||||
|
||||
### 8. Structural conflicts
|
||||
|
||||
Conflicts between registry state, anchor files, and managed identity are structural errors.
|
||||
|
||||
Examples:
|
||||
|
||||
- two asset roots competing for the same identity;
|
||||
- registered root without anchor;
|
||||
- duplicated or ambiguous anchor declarations under managed expectations.
|
||||
|
||||
These are not advisory hygiene warnings.
|
||||
They invalidate the managed build contract.
|
||||
|
||||
### 9. Duplicate content policy
|
||||
|
||||
Duplicate source content by hash is not a structural build error in the baseline contract.
|
||||
|
||||
Rules:
|
||||
|
||||
- it is a hygiene warning or hint;
|
||||
- it may inform cost, cleanup, or optimization workflows;
|
||||
- it does not imply semantic invalidity by itself.
|
||||
|
||||
### 10. Orphan asset policy
|
||||
|
||||
Orphan `asset.json` declarations do not block the baseline build.
|
||||
|
||||
Rules:
|
||||
|
||||
- they belong to workspace hygiene surfaces;
|
||||
- they should be visible in `doctor --workspace`;
|
||||
- they do not become managed assets automatically;
|
||||
- stricter policy can be added later, but it is not part of the current baseline.
|
||||
|
||||
## Invariants and Constraints
|
||||
|
||||
The following invariants now apply:
|
||||
|
||||
1. The build validates the managed registry-defined world, not the entire workspace by default.
|
||||
2. Workspace hygiene scanning is broader than build validation.
|
||||
3. Structural managed-world errors block builds.
|
||||
4. Hygiene findings do not block builds by default unless separately elevated by policy.
|
||||
5. `doctor --fix` is limited to safe mechanical corrections.
|
||||
6. Quarantine is explicit and reversible.
|
||||
7. Destructive or relocational mutations require explicit consent.
|
||||
8. Duplicate content is advisory, not structurally invalid by itself.
|
||||
9. Orphan anchors are diagnosable, not build-active.
|
||||
10. Trust and reversibility are preferred over aggressive automatic remediation.
|
||||
|
||||
## Explicit Non-Decisions
|
||||
|
||||
This decision does not yet define:
|
||||
|
||||
- the full taxonomy and numbering of diagnostic codes;
|
||||
- richer policy knobs such as strict workspace modes by profile;
|
||||
- detailed UI presentation in Studio;
|
||||
- watch-mode-specific hygiene behavior;
|
||||
- detailed garbage collection flows beyond the baseline safety model.
|
||||
|
||||
Those belong to later decisions and specs.
|
||||
|
||||
## Propagation Targets
|
||||
|
||||
This decision must propagate to:
|
||||
|
||||
- packer diagnostics contract spec;
|
||||
- doctor and workspace scanning spec;
|
||||
- quarantine and garbage collection spec;
|
||||
- Studio service behavior for inspection, fix, and cleanup actions;
|
||||
- future implementation of safe fix classification and explicit-consent workflows.
|
||||
|
||||
## Validation Notes
|
||||
|
||||
Example: orphan anchor
|
||||
|
||||
- `assets/wip/new_bank/asset.json` exists
|
||||
- it is not registered in the managed registry
|
||||
- build does not fail by default
|
||||
- `doctor --workspace` must surface it
|
||||
|
||||
Example: unsafe fix
|
||||
|
||||
- two large duplicate PNGs are detected in workspace
|
||||
- packer may report them
|
||||
- packer must not delete or move either file automatically in baseline behavior
|
||||
|
||||
Example: structural error
|
||||
|
||||
- a registered asset root no longer contains its anchor `asset.json`
|
||||
- this is a managed-world integrity failure
|
||||
- build validation must fail
|
||||
@@ -1,201 +0,0 @@
|
||||
# Incremental Build, Cache, and Watch Model Decision
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Date
|
||||
|
||||
2026-03-11
|
||||
|
||||
## Context
|
||||
|
||||
This decision closes the architectural questions raised in [`01.5. Incremental Build, Cache, and Watch Model Agenda`](../agendas/01.5.%20Incremental%20Build,%20Cache,%20and%20Watch%20Model%20Agenda.md).
|
||||
|
||||
The packer should support incremental work and future watch-driven workflows, but only under a strict rule:
|
||||
|
||||
- optimization must never redefine build semantics.
|
||||
|
||||
Incremental behavior, cache reuse, and watch mode must remain subordinate to deterministic artifact production.
|
||||
|
||||
## Decision
|
||||
|
||||
The packer adopts a `determinism-first, cache-as-optimization, watch-as-optional-trigger` model.
|
||||
|
||||
### 1. Fingerprint model
|
||||
|
||||
Input tracking uses three levels of signal:
|
||||
|
||||
- `size`
|
||||
- `mtime`
|
||||
- `strong_hash`
|
||||
|
||||
Roles:
|
||||
|
||||
- `size` and `mtime` are fast-change hints;
|
||||
- `strong_hash` is the authoritative content identity signal.
|
||||
|
||||
### 2. Authority of fingerprint signals
|
||||
|
||||
`size` and `mtime` are not sufficient as final truth for cache reuse.
|
||||
|
||||
Rules:
|
||||
|
||||
- they may be used to avoid unnecessary hashing in the fast path;
|
||||
- they may indicate that a strong hash check is required;
|
||||
- when reuse affects emitted output, strong hash is the authoritative content check.
|
||||
|
||||
### 3. Cache reuse rule
|
||||
|
||||
Cached work may be reused only when the full effective build inputs remain equivalent.
|
||||
|
||||
This includes, at minimum:
|
||||
|
||||
- source inputs;
|
||||
- selected output format;
|
||||
- codec;
|
||||
- runtime-facing metadata;
|
||||
- build configuration that affects emitted bytes;
|
||||
- materialized defaults or effective derived configuration.
|
||||
|
||||
If any of these change, the relevant output must be rebuilt.
|
||||
|
||||
### 4. Incremental equivalence
|
||||
|
||||
Incremental build is an execution optimization only.
|
||||
|
||||
Rules:
|
||||
|
||||
- full build and incremental build must produce the same observable results;
|
||||
- byte output, header content, offsets, preload data, and other runtime-facing artifacts must match;
|
||||
- any semantic difference between full and incremental build is a bug.
|
||||
|
||||
### 5. Cache scope
|
||||
|
||||
The packer may persist:
|
||||
|
||||
- fingerprint data;
|
||||
- derived build results;
|
||||
- internal cache metadata.
|
||||
|
||||
But:
|
||||
|
||||
- cache internals are not the source of truth;
|
||||
- runtime-facing artifacts remain authoritative;
|
||||
- cache structure is not frozen as a normative external contract in the current baseline.
|
||||
|
||||
### 6. Cache explainability
|
||||
|
||||
The packer must be able to explain reuse and rebuild decisions.
|
||||
|
||||
At minimum, the model should support reasons equivalent to:
|
||||
|
||||
- cache hit;
|
||||
- rebuild because input changed;
|
||||
- rebuild because config changed;
|
||||
- rebuild because format or schema contract changed;
|
||||
- rebuild because cache state is missing or invalid.
|
||||
|
||||
This does not require always-on verbosity, but the capability must exist for diagnostics and Studio tooling.
|
||||
|
||||
### 7. Watch mode
|
||||
|
||||
Watch mode is optional in the current baseline contract.
|
||||
|
||||
Rules:
|
||||
|
||||
- watch may exist as a supported capability;
|
||||
- watch must trigger rebuild and/or revalidation behavior equivalent to normal packer execution;
|
||||
- watch is not the place to freeze detailed UI, timing, or orchestration policy yet.
|
||||
|
||||
### 8. Watch safety
|
||||
|
||||
Watch mode must not become a silent mutation engine.
|
||||
|
||||
Rules:
|
||||
|
||||
- baseline watch behavior is observe, detect, validate, and rebuild;
|
||||
- watch does not imply auto-fix, quarantine, adoption, or destructive cleanup;
|
||||
- any broader mutation policy requires explicit later design.
|
||||
|
||||
### 9. Strong hash timing
|
||||
|
||||
Strong hash calculation is performed pragmatically, but remains authoritative.
|
||||
|
||||
Rules:
|
||||
|
||||
- fast hints may be checked first;
|
||||
- when hints indicate possible change, strong hash resolves the question;
|
||||
- when cache trust is insufficient, strong hash may be recomputed even if hints appear unchanged.
|
||||
|
||||
### 10. Cache portability
|
||||
|
||||
Cross-machine cache portability is not part of the current baseline contract.
|
||||
|
||||
Rules:
|
||||
|
||||
- cache is treated as local to the workspace/runtime environment by default;
|
||||
- portability, remote reuse, or shareable cache semantics require later explicit design.
|
||||
|
||||
## Invariants and Constraints
|
||||
|
||||
The following invariants now apply:
|
||||
|
||||
1. Deterministic output has priority over cache reuse.
|
||||
2. `size` and `mtime` are hints, not final truth.
|
||||
3. Strong hash is the authoritative content identity signal for reuse decisions.
|
||||
4. Cache reuse is allowed only when effective build inputs are equivalent.
|
||||
5. Full and incremental builds must be observably equivalent.
|
||||
6. Cache is an optimization layer, not a semantic authority.
|
||||
7. The packer must be able to explain rebuild/reuse decisions.
|
||||
8. Watch mode is optional in the baseline contract.
|
||||
9. Watch mode does not imply silent mutation of authoring content.
|
||||
10. Cache portability is deferred.
|
||||
|
||||
## Explicit Non-Decisions
|
||||
|
||||
This decision does not yet define:
|
||||
|
||||
- the exact on-disk schema of every cache file;
|
||||
- detailed watch UX or scheduling behavior;
|
||||
- remote/shared cache design;
|
||||
- background worker orchestration;
|
||||
- policy for multi-user cache coordination.
|
||||
|
||||
Those belong to later decisions and specs.
|
||||
|
||||
## Propagation Targets
|
||||
|
||||
This decision must propagate to:
|
||||
|
||||
- packer cache and fingerprint specs;
|
||||
- incremental build guarantees spec;
|
||||
- watch mode spec or deferred capability note;
|
||||
- Studio diagnostics for build-reason visibility;
|
||||
- future implementation of fingerprint persistence and cache invalidation.
|
||||
|
||||
## Validation Notes
|
||||
|
||||
Example: changed input
|
||||
|
||||
- source file timestamp changed
|
||||
- strong hash also changed
|
||||
- cached derived result must be invalidated
|
||||
|
||||
Example: misleading timestamp
|
||||
|
||||
- `mtime` changed
|
||||
- strong hash remains identical
|
||||
- packer may treat the content as unchanged after authoritative hash confirmation
|
||||
|
||||
Example: config change
|
||||
|
||||
- source inputs are identical
|
||||
- `output.format` or runtime-facing metadata changed
|
||||
- cached result must be invalidated because emitted bytes may differ
|
||||
|
||||
Example: watch behavior
|
||||
|
||||
- file changes while watch is active
|
||||
- packer revalidates or rebuilds
|
||||
- watch does not automatically move, delete, or adopt workspace content
|
||||
@@ -1,278 +0,0 @@
|
||||
# Studio-First Asset Services and Event Lane Decision
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Date
|
||||
|
||||
2026-03-11
|
||||
|
||||
## Context
|
||||
|
||||
This decision closes the architectural questions raised in [`01.6. CLI Surface and Mutating Operations Agenda`](../agendas/01.6.%20CLI%20Surface%20and%20Mutating%20Operations%20Agenda.md).
|
||||
|
||||
The original packer framing was CLI-oriented.
|
||||
That is no longer the design center.
|
||||
|
||||
The current target is Studio integration:
|
||||
|
||||
- asset UI and packer behavior should evolve together;
|
||||
- packer operations should exist as Studio-consumable services first;
|
||||
- background asset activity should be observable in the UI through structured events;
|
||||
- any future CLI should be an adapter over those services rather than the architecture driver.
|
||||
|
||||
## Decision
|
||||
|
||||
The packer adopts a `Studio-first services + structured event lane` model.
|
||||
|
||||
### 1. Primary integration model
|
||||
|
||||
Studio is the primary integration target.
|
||||
|
||||
Rules:
|
||||
|
||||
- service contracts are the normative operational surface;
|
||||
- UI workflows are first-class design inputs;
|
||||
- CLI is not the baseline architecture contract in the current phase;
|
||||
- if a CLI exists later, it adapts these services rather than redefining them.
|
||||
|
||||
### 2. Core v1 services
|
||||
|
||||
The baseline Studio service surface includes:
|
||||
|
||||
- `init_workspace`
|
||||
- `register_asset`
|
||||
- `adopt_asset`
|
||||
- `forget_asset`
|
||||
- `remove_asset`
|
||||
- `list_assets`
|
||||
- `get_asset_details`
|
||||
- `doctor`
|
||||
- `build`
|
||||
|
||||
Later or optional capabilities may include:
|
||||
|
||||
- `watch`
|
||||
- `gc`
|
||||
- `quarantine`
|
||||
- more advanced bulk refactor flows
|
||||
|
||||
### 3. Identifier expectations
|
||||
|
||||
For normal Studio-facing workflows, the preferred identifiers are:
|
||||
|
||||
- `asset_name`
|
||||
- `asset_root`
|
||||
- `asset_id` when already resolved internally
|
||||
|
||||
`asset_uuid` may still exist for migration or internal tooling purposes, but it is not required as the primary UX identifier for the baseline flow.
|
||||
|
||||
### 4. Read-only versus mutating services
|
||||
|
||||
The service contract must distinguish clearly between:
|
||||
|
||||
- read-only operations;
|
||||
- registry mutations;
|
||||
- workspace mutations.
|
||||
|
||||
Baseline interpretation:
|
||||
|
||||
- read-only:
|
||||
- `list_assets`
|
||||
- `get_asset_details`
|
||||
- `doctor`
|
||||
- registry mutations:
|
||||
- `register_asset`
|
||||
- `adopt_asset`
|
||||
- `forget_asset`
|
||||
- workspace mutations:
|
||||
- `remove_asset`
|
||||
- future quarantine/move/delete flows
|
||||
|
||||
This distinction is part of the service semantics and must be visible to the UI.
|
||||
|
||||
### 5. Preview/apply model
|
||||
|
||||
Sensitive mutating workflows use staged intent rather than immediate blind mutation.
|
||||
|
||||
Rules:
|
||||
|
||||
- operations with significant mutation potential should support analysis or preview before apply;
|
||||
- broad, destructive, or relocational actions require explicit user confirmation;
|
||||
- safe-fix flows should be modeled as services such as:
|
||||
- analyze
|
||||
- propose fixes
|
||||
- apply safe fixes
|
||||
|
||||
This replaces CLI-centric flag thinking as the architectural baseline.
|
||||
|
||||
### 6. Structured service responses
|
||||
|
||||
Service responses must be structured for UI and automation.
|
||||
|
||||
At minimum, the model should support fields equivalent to:
|
||||
|
||||
- `status`
|
||||
- `summary`
|
||||
- `affected_assets`
|
||||
- `diagnostics`
|
||||
- `proposed_actions`
|
||||
- `applied_actions`
|
||||
- `blockers`
|
||||
|
||||
Human-readable strings may still exist, but they must not be the only contract the UI depends on.
|
||||
|
||||
### 7. `forget` versus `remove`
|
||||
|
||||
`forget_asset` and `remove_asset` remain distinct operations.
|
||||
|
||||
Meaning:
|
||||
|
||||
- `forget_asset` leaves the managed set without deleting authoring content;
|
||||
- `remove_asset` expresses a stronger mutation intent and may affect workspace content depending on policy.
|
||||
|
||||
The UI must present this difference explicitly.
|
||||
|
||||
### 8. Adoption is core
|
||||
|
||||
`adopt_asset` is part of the baseline service set.
|
||||
|
||||
Rationale:
|
||||
|
||||
- orphan `asset.json` declarations are a normal part of the packer model;
|
||||
- adoption is not an edge-case maintenance feature;
|
||||
- Studio needs a first-class path from discovery to managed registration.
|
||||
|
||||
### 9. Asset workspace event lane
|
||||
|
||||
The system includes a dedicated asset workspace event lane for Studio integration.
|
||||
|
||||
This is an architectural event/reporting contract, not a commitment to one specific implementation primitive.
|
||||
|
||||
Responsibilities:
|
||||
|
||||
- observe relevant changes in the asset workspace and registry;
|
||||
- trigger analysis, refresh, rebuild, or rescan workflows when appropriate;
|
||||
- publish structured events for UI logging, status, and live refresh;
|
||||
- avoid blocking the UI thread on asset work.
|
||||
|
||||
### 10. Mutation serialization
|
||||
|
||||
Mutating asset operations are serialized semantically.
|
||||
|
||||
Rules:
|
||||
|
||||
- the event lane and service model must not allow conflicting asset mutations to race arbitrarily;
|
||||
- internal implementation may use controlled parallelism where safe;
|
||||
- but the observable mutation model should behave as if sensitive workspace operations are serialized.
|
||||
|
||||
This keeps Studio state coherent and avoids hard-to-debug race conditions between watch, doctor, build, and explicit user actions.
|
||||
|
||||
### 11. Event model
|
||||
|
||||
The initial structured event set should include, at minimum:
|
||||
|
||||
- `asset_discovered`
|
||||
- `asset_changed`
|
||||
- `diagnostics_updated`
|
||||
- `build_started`
|
||||
- `build_finished`
|
||||
- `cache_hit`
|
||||
- `cache_miss`
|
||||
- `preview_ready`
|
||||
- `action_applied`
|
||||
- `action_failed`
|
||||
- `progress_updated`
|
||||
|
||||
`progress_updated` exists to support visible progress reporting such as progress bars and long-running asset activity feedback in the UI.
|
||||
|
||||
### 12. Event lane safety
|
||||
|
||||
The background event lane is not an autonomous mutation engine.
|
||||
|
||||
Rules:
|
||||
|
||||
- it may observe, analyze, report, and trigger safe refresh/rebuild behavior;
|
||||
- it must not silently apply dangerous mutations;
|
||||
- explicit user intent remains required for destructive, relocational, or adoption-related changes unless separately designed later.
|
||||
|
||||
### 13. Future CLI boundary
|
||||
|
||||
Any future CLI should remain a secondary adapter.
|
||||
|
||||
Rules:
|
||||
|
||||
- CLI should consume the same service semantics;
|
||||
- CLI text output is not the canonical contract;
|
||||
- if stable automation output is needed, it should be derived from the same structured response model used by Studio.
|
||||
|
||||
## Invariants and Constraints
|
||||
|
||||
The following invariants now apply:
|
||||
|
||||
1. Studio integration is the primary target.
|
||||
2. Services are the normative operational surface.
|
||||
3. UI and services are designed together.
|
||||
4. CLI is deferred to adapter status.
|
||||
5. Core asset operations are service-defined, not command-defined.
|
||||
6. Sensitive mutations use preview/apply semantics where appropriate.
|
||||
7. Structured responses are required for UI consumption.
|
||||
8. `forget_asset` and `remove_asset` remain distinct.
|
||||
9. Adoption is part of the baseline service model.
|
||||
10. A dedicated asset event lane exists as an architectural integration surface.
|
||||
11. Mutating asset workflows are serialized semantically.
|
||||
12. Initial asset event reporting includes progress updates.
|
||||
13. Background reporting does not authorize silent dangerous mutation.
|
||||
|
||||
## Explicit Non-Decisions
|
||||
|
||||
This decision does not yet define:
|
||||
|
||||
- the exact transport or IPC mechanism for services;
|
||||
- the exact threading/runtime primitive used for the event lane;
|
||||
- final visual design of Studio asset panels;
|
||||
- detailed watch-mode orchestration beyond the baseline event model;
|
||||
- a future CLI command grammar.
|
||||
|
||||
Those belong to later decisions and specs.
|
||||
|
||||
## Propagation Targets
|
||||
|
||||
This decision must propagate to:
|
||||
|
||||
- packer service operation spec;
|
||||
- Studio asset workflow integration spec;
|
||||
- mutation and confirmation policy spec;
|
||||
- structured response contract spec;
|
||||
- asset event/reporting integration spec;
|
||||
- future implementation of the asset workspace event lane and progress reporting.
|
||||
|
||||
## Validation Notes
|
||||
|
||||
Example: safe inspection flow
|
||||
|
||||
- Studio requests `list_assets`
|
||||
- service returns structured asset summaries
|
||||
- event lane may emit `diagnostics_updated` or `asset_changed` as background state evolves
|
||||
|
||||
Example: staged mutation flow
|
||||
|
||||
- Studio requests doctor analysis
|
||||
- service returns diagnostics plus proposed safe fixes
|
||||
- user confirms apply
|
||||
- service performs safe changes
|
||||
- event lane emits `action_applied` and `progress_updated`
|
||||
|
||||
Example: background rebuild
|
||||
|
||||
- asset source changes
|
||||
- event lane observes the change
|
||||
- analysis/rebuild is triggered according to service policy
|
||||
- UI receives `build_started`, `progress_updated`, and `build_finished`
|
||||
|
||||
Example: dangerous mutation boundary
|
||||
|
||||
- user has not confirmed quarantine or deletion
|
||||
- background lane may report the issue and propose the action
|
||||
- background lane must not perform the mutation by itself
|
||||
@@ -1,223 +0,0 @@
|
||||
# Shipper Integration, Versioning, and Trust Model Decision
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Date
|
||||
|
||||
2026-03-11
|
||||
|
||||
## Context
|
||||
|
||||
This decision closes the architectural questions raised in [`01.7. Builder Integration, Versioning, and Trust Model Agenda`](../agendas/01.7.%20Builder%20Integration,%20Versioning,%20and%20Trust%20Model%20Agenda.md).
|
||||
|
||||
The packer must define:
|
||||
|
||||
- how its artifacts are versioned;
|
||||
- what migration obligations it owns;
|
||||
- what trust boundaries apply to asset tooling;
|
||||
- how a future shipper will consume packer outputs without becoming part of the packer architecture now.
|
||||
|
||||
The important clarification is:
|
||||
|
||||
- the shipper does not exist yet as part of the current packer work;
|
||||
- shipper integration is therefore a future consumer boundary, not a present operational dependency.
|
||||
|
||||
## Decision
|
||||
|
||||
The packer adopts a `future-shipper-consumer, explicit-versioning, conservative-trust` model.
|
||||
|
||||
### 1. Current shipper boundary
|
||||
|
||||
The shipper is not part of the current packer architecture.
|
||||
|
||||
Rules:
|
||||
|
||||
- the packer must not depend on a concrete shipper implementation;
|
||||
- the packer should emit stable, documented artifacts that a future shipper can consume;
|
||||
- current packer design must stop at artifact publication, not at cartridge shipping orchestration.
|
||||
|
||||
### 2. Ownership boundary
|
||||
|
||||
Current ownership is split as follows:
|
||||
|
||||
- packer owns artifact production;
|
||||
- runtime owns runtime-side artifact reading semantics;
|
||||
- future shipper will own cartridge shipping/publication concerns.
|
||||
|
||||
This means:
|
||||
|
||||
- runtime-facing reading contract for `assets.pa` belongs to runtime specs;
|
||||
- writer-side production contract for `assets.pa` belongs to packer specs;
|
||||
- a future shipper consumes these artifacts but does not redefine the asset contract.
|
||||
|
||||
### 3. Packer-owned artifacts
|
||||
|
||||
The packer is responsible for emitting and versioning at least:
|
||||
|
||||
- `assets.pa`
|
||||
- `build/asset_table.json`
|
||||
- `build/preload.json`
|
||||
- `build/asset_table_metadata.json`
|
||||
- `asset.json`
|
||||
- `index.json`
|
||||
- packer-owned cache and control data
|
||||
|
||||
These are the boundaries a future shipper may consume, but they remain packer-owned artifacts.
|
||||
|
||||
### 4. Minimal future shipper contract
|
||||
|
||||
The future shipper contract should remain minimal for now.
|
||||
|
||||
Baseline contract:
|
||||
|
||||
- which packer artifacts are published;
|
||||
- where they are expected to exist;
|
||||
- which artifacts are runtime-facing versus tooling-only;
|
||||
- which artifacts are authoritative versus derived.
|
||||
|
||||
Detailed shipping workflow is deferred until the shipper exists.
|
||||
|
||||
### 5. Versioning policy
|
||||
|
||||
Versioning is explicit and per-artifact/per-schema.
|
||||
|
||||
Rules:
|
||||
|
||||
- `asset.json` has explicit schema versioning;
|
||||
- `index.json` has explicit schema versioning;
|
||||
- `assets.pa` has explicit runtime-facing envelope versioning;
|
||||
- companion artifacts may have their own schema versioning where needed;
|
||||
- version evolution is tracked per concern, not by one global version number for the whole domain.
|
||||
|
||||
### 6. Migration policy
|
||||
|
||||
The packer migrates only artifacts it owns.
|
||||
|
||||
This includes, at minimum:
|
||||
|
||||
- `asset.json`
|
||||
- `index.json`
|
||||
- packer-owned caches and control files
|
||||
|
||||
Rules:
|
||||
|
||||
- migration may be automatic within a supported window;
|
||||
- outside the supported window, the packer fails with actionable diagnostics;
|
||||
- the packer does not assume a cooperative migration workflow with a shipper that does not yet exist.
|
||||
|
||||
### 7. Compatibility window
|
||||
|
||||
Backward compatibility is provided through an explicit support window, not an open-ended forever policy.
|
||||
|
||||
Rules:
|
||||
|
||||
- the packer must define which previous versions it can read or migrate;
|
||||
- unsupported versions fail clearly and early;
|
||||
- CI and Studio should be able to surface unsupported-version failures deterministically.
|
||||
|
||||
### 8. Runtime compatibility guarantees
|
||||
|
||||
The packer must preserve compatibility guarantees relevant to `../runtime`.
|
||||
|
||||
These include:
|
||||
|
||||
- `assets.pa` emitted according to the runtime-facing reader contract;
|
||||
- offsets relative to payload region;
|
||||
- canonical header semantics where required by packer-side production rules;
|
||||
- stable `asset_id` continuity end-to-end;
|
||||
- preload emitted according to the current runtime-facing contract.
|
||||
|
||||
The runtime must not depend on companion JSON artifacts for correctness.
|
||||
|
||||
### 9. Trusted versus untrusted inputs
|
||||
|
||||
The packer uses a conservative trust model.
|
||||
|
||||
Untrusted until validated:
|
||||
|
||||
- source asset files;
|
||||
- manually edited or legacy `asset.json`;
|
||||
- legacy registry/control data;
|
||||
- imported artifacts and external project content.
|
||||
|
||||
Trusted only after:
|
||||
|
||||
- strict parse;
|
||||
- structural validation;
|
||||
- semantic validation;
|
||||
- version compatibility check.
|
||||
|
||||
### 10. No plugin/script execution baseline
|
||||
|
||||
The packer must not execute arbitrary external plugins or scripts in the baseline architecture.
|
||||
|
||||
Rules:
|
||||
|
||||
- no script execution as part of normal asset transformation contract;
|
||||
- no untrusted extension hooks;
|
||||
- no implicit foreign code execution during build.
|
||||
|
||||
Any future extensibility model requires a separate decision.
|
||||
|
||||
### 11. Shipper as consumer, not co-author
|
||||
|
||||
A future shipper consumes packer outputs but must not silently reinterpret or repair the asset contract.
|
||||
|
||||
Rules:
|
||||
|
||||
- shipper does not redefine `assets.pa`;
|
||||
- shipper does not become the source of truth for `asset_table` or preload semantics;
|
||||
- if an asset artifact is invalid, the issue belongs back to packer production, not to shipper-side correction.
|
||||
|
||||
## Invariants and Constraints
|
||||
|
||||
The following invariants now apply:
|
||||
|
||||
1. The shipper is a future consumer, not a current packer dependency.
|
||||
2. Packer stops at artifact production.
|
||||
3. Runtime owns reader semantics of the runtime-facing artifact.
|
||||
4. Packer owns writer semantics and companion artifacts on the production side.
|
||||
5. Versioning is explicit per artifact/schema.
|
||||
6. Migration applies only to artifacts the packer owns.
|
||||
7. Compatibility is governed by a support window, not indefinite backward promises.
|
||||
8. Inputs are untrusted until validated.
|
||||
9. Baseline packer architecture does not execute arbitrary plugins or scripts.
|
||||
10. A future shipper is a consumer, not a co-author of the asset contract.
|
||||
|
||||
## Explicit Non-Decisions
|
||||
|
||||
This decision does not yet define:
|
||||
|
||||
- the concrete shipper implementation;
|
||||
- cartridge shipping workflow details;
|
||||
- packaging formats beyond the currently documented runtime forms;
|
||||
- artifact signing or distribution security policy;
|
||||
- remote/shared artifact registry behavior.
|
||||
|
||||
Those belong to later decisions and future shipper work.
|
||||
|
||||
## Propagation Targets
|
||||
|
||||
This decision must propagate to:
|
||||
|
||||
- packer versioning and migration specs;
|
||||
- packer trust/security model spec;
|
||||
- future shipper integration spec;
|
||||
- Studio diagnostics for unsupported versions and migration failures;
|
||||
- future implementation of schema migration boundaries and compatibility checks.
|
||||
|
||||
## Validation Notes
|
||||
|
||||
Example: unsupported registry version
|
||||
|
||||
- `index.json` version is outside the supported migration window
|
||||
- packer reports explicit version mismatch and migration failure
|
||||
- build does not continue
|
||||
|
||||
Example: future shipper consumption
|
||||
|
||||
- packer emits `assets.pa` and companion build artifacts
|
||||
- future shipper consumes those artifacts to assemble a cartridge
|
||||
- shipper does not reinterpret asset semantics or rewrite packer-owned artifact meaning
|
||||
@@ -2,6 +2,13 @@
|
||||
|
||||
This directory contains packer decision records.
|
||||
|
||||
There are currently no retained packer decision records.
|
||||
|
||||
The first packer decision wave was already consolidated into:
|
||||
|
||||
- normative specifications under [`../specs/`](../specs/)
|
||||
- didactic material under [`../learn/`](../learn/)
|
||||
|
||||
## Purpose
|
||||
|
||||
A decision record is the bridge between packer discussion and packer execution.
|
||||
|
||||
Reference in New Issue
Block a user