This commit is contained in:
2026-03-24 13:42:38 +00:00
parent e3389e78b6
commit 11ca697fa4
24 changed files with 23 additions and 2622 deletions
@@ -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
@@ -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
@@ -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
+7
View File
@@ -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.