218 lines
6.8 KiB
Markdown
218 lines
6.8 KiB
Markdown
# 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
|