updated packer agendas
This commit is contained in:
+217
@@ -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
|
||||
Reference in New Issue
Block a user