updated packer agendas

This commit is contained in:
2026-03-24 13:42:38 +00:00
parent 900a7e17dd
commit f27b28c516
14 changed files with 1008 additions and 64 deletions
@@ -0,0 +1,217 @@
# 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
@@ -0,0 +1,201 @@
# 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
@@ -0,0 +1,278 @@
# 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
@@ -0,0 +1,223 @@
# 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