mdkg 0.3.6 → 0.3.7

package/CHANGELOG.md

@@ -8,6 +8,75 @@ mdkg is pre-v1 public alpha software. Command, graph, cache, bundle, and DAL con
 
 ## Unreleased
 
+## 0.3.7 - 2026-06-20
+
+### Added
+
+- Added `context_refs` and `evidence_refs` as generic semantic reference
+  fields for mdkg work nodes, with indexing, validation, search/show output,
+  pack traversal, SQLite cache support, subgraph projection, and visibility
+  enforcement.
+- Added `mdkg graph refs <id-or-qid> --json` to summarize inbound and outbound
+  scope, context, evidence, blocker, related, and structural references for
+  local graph nodes and read-only subgraph qids.
+- Added richer checkpoint kinds for implementation milestones, test proof, goal
+  closeout, read-only audits, and handoffs. Generated checkpoint bodies now
+  include sections for evidence, validation, known warnings, changed surfaces,
+  boundaries, and follow-up references.
+- Added `mdkg work validate [<id-or-qid>] --type ... --json` for focused
+  SPEC, WORK, WORK_ORDER, RECEIPT, FEEDBACK, DISPUTE, and PROPOSAL semantic
+  mirror diagnostics.
+- Added validation warning categories plus `mdkg validate --changed-only` for
+  changed-file warning review while preserving full-graph error checking.
+- Added `mdkg format --headings --dry-run|--apply --json` to preview or apply
+  recommended heading migrations for historical mdkg Markdown nodes.
+- Added `mdkg db queue contract --json` as the public project DB queue adapter
+  contract covering payload hashing, dedupe, claim ordering, lease-owner
+  settlement, retry/dead-letter behavior, expired lease release, pause/resume,
+  snapshot policies, and stats semantics.
+- Added `mdkg handoff create <id-or-qid>` for sanitized, copy-ready agent
+  handoff prompts built from pack context, goal state, latest checkpoints,
+  required checks, semantic refs, and raw-content warnings.
+- Added packed temp-repo smokes for semantic refs, checkpoint templates,
+  handoffs, and the full integration UX flow.
+
+### Changed
+
+- Completed goals now move the final `active_node` to `last_active_node` when
+  marked done or archived, so historical routing state is preserved without
+  leaving completed goals actionable.
+- `mdkg goal next <done-goal> --json` now returns `node: null` without
+  misleading stale `active_node` warnings for achieved goals.
+- Goal and pack workflows now distinguish executable `scope_refs` from
+  contextual and evidence references, reducing validation noise when goals cite
+  checkpoints, design evidence, prerequisite goals, or external proof refs.
+- README, init assets, command matrix, generated command contract metadata,
+  help targets, and publish-readiness assertions now document the new semantic
+  refs, handoff, workflow validation, checkpoint, queue contract, and warning
+  migration surfaces.
+- Upgrade behavior now migrates legacy achieved goals that still have
+  `active_node` into the new `last_active_node` shape.
+
+### Fixed
+
+- Reduced false-positive operational friction for completed goals and
+  intentional contextual refs without weakening missing-reference or invalid
+  graph-edge validation.
+- Strengthened cross-subgraph blocker diagnostics so read-only external graph
+  nodes are reported as planning context instead of locally actionable work.
+
+### Security
+
+- Handoff generation omits raw node body content for nodes with obvious raw
+  prompt, payload, or secret markers and reports typed raw-marker warnings
+  instead.
+- Workflow validation and checkpoint validation warn on obvious raw secret,
+  prompt, token, or payload markers without turning mdkg into a broad secret
+  scanner or blocking operator review.
+- The public queue contract explicitly states that queue payloads should be
+  compact refs or redacted envelopes, not raw secrets, prompts, provider
+  payloads, or bulky runtime artifacts.
+
 ## 0.3.6 - 2026-06-17
 
 ### Added

package/CLI_COMMAND_MATRIX.md

@@ -23,6 +23,7 @@ Primary commands:
 - `list`
 - `search`
 - `pack`
+- `handoff`
 - `skill`
 - `capability`
 - `spec`
@@ -349,6 +350,10 @@ Allowed formats:
 - `toon`
 - `xml`
 
+Allowed pack edges:
+- `parent`, `epic`, `relates`, `blocked_by`, `blocks`, `prev`, `next`
+- `context_refs` and `evidence_refs` for non-executable semantic references
+
 Profiles:
 - `standard`
 - `concise`
@@ -363,6 +368,26 @@ Visibility:
 - `--visibility internal` includes public/internal records and fails when included records reference private records
 - `--visibility private` records explicit private intent and may include all records
 - visibility filtering does not inspect or redact arbitrary Markdown body text
+- `context_refs` and `evidence_refs` are indexed semantic refs, not executable goal queues; include them with `--edges context_refs,evidence_refs` when a handoff needs background or proof nodes
+
+### `mdkg handoff`
+
+When to use:
+- create a sanitized, copy-ready agent handoff prompt from graph context
+- summarize goal/work state, included pack nodes, latest checkpoint, boundaries, required checks, and next actions
+
+Usage:
+- `mdkg handoff create <id-or-qid> [--ws <alias>] [--depth <n>] [--out <path>] [--json]`
+
+Notes:
+- uses pack traversal with `context_refs` and `evidence_refs`
+- does not copy raw node bodies into the handoff
+- reports raw secret, prompt, token, or payload marker warnings without including raw marker content
+- `--out` must stay inside the repo root
+- the command does not execute work, mutate graph nodes, or generate detailed node content
+
+Receipts:
+- `handoff-created`: `{ action, ok, mdkg_version, target, output_path, content_sha256, raw_marker_warning_count, raw_marker_warnings, latest_checkpoint_qid, included_qids, pack, content }`
 
 ### `mdkg skill`
 
@@ -624,12 +649,14 @@ JSON receipts:
 When to use:
 - clone or fork a complete mdkg graph into a separate target directory while preserving IDs
 - import a template graph into the current repo with deterministic ID/link rewrites
+- inspect inbound and outbound graph references across local and read-only subgraph qids
 - prepare selected-goal demo handoffs from reusable graph templates
 
 Usage:
 - `mdkg graph clone <source-bundle-or-mdkg-dir> --target <path> [--json]`
 - `mdkg graph fork <source-bundle-or-mdkg-dir> --target <path> [--start-goal <goal-id>] [--json]`
 - `mdkg graph import-template <source-bundle-or-mdkg-dir> [--start-goal <goal-id>] [--select-goal] [--id-prefix <prefix>] [--dry-run] [--apply] [--json]`
+- `mdkg graph refs <id-or-qid> [--ws <alias>] [--json]`
 
 Flags:
 - `--target <path>`
@@ -638,6 +665,7 @@ Flags:
 - `--id-prefix <prefix>`
 - `--dry-run`
 - `--apply`
+- `--ws <alias>`
 - `--json`
 
 Notes:
@@ -651,12 +679,14 @@ Notes:
 - colliding semantic template IDs require `--id-prefix`
 - `--select-goal` requires `--start-goal`; on apply it activates the imported start goal, pauses competing active root goals, validates, then writes selected-goal state
 - importing active template goals without `--select-goal` fails before writing when it would create multiple active root goals
+- `graph refs` is read-only; it reports `scope_refs`, `context_refs`, `evidence_refs`, blockers, related refs, and structural inbound/outbound links
 - subgraphs remain read-only bundle projections for orchestration context; use `graph clone|fork|import-template` when authored graph state should be created
 
 JSON receipts:
 - `clone`: `{ action: "graph.clone", ok, mode, source, target, source_hash, preserved_ids, files_written, skipped_paths, index, validation, warnings }`
 - `fork`: `{ action: "graph.fork", ok, mode, source, target, source_hash, preserved_ids, files_written, skipped_paths, start_goal?, selected_goal?, index, validation, warnings }`
 - `import-template`: `{ action: "graph.import_template", ok, mode, source, source_hash, preserved_ids: false, rewritten_ids, rewritten_refs, planned_paths, files_written, skipped_paths, start_goal?, selected_goal?, activated_goal?, paused_goals, index?, validation?, warnings }`
+- `refs`: `{ action: "graph.refs", ok, target, outgoing, incoming, warnings }`
 
 ### `mdkg subgraph`
 
@@ -745,6 +775,8 @@ Usage:
 - `mdkg work receipt verify <id-or-qid> [--json]`
 - `mdkg work receipt update <id-or-qid> [--receipt-status <status>] [--add-artifacts <...>] [--add-proof-refs <...>] [--add-attestation-refs <...>] [--add-evidence-hashes <sha256:...>] [--json]`
 - `mdkg work artifact add <order-or-receipt-id-or-qid> <file> [--id <archive.id>] [--kind source|artifact] [--json]`
+- `mdkg work validate [<id-or-qid>] [--type <workflow-type>] [--json]`
+- `mdkg work validate [<id-or-qid>] [--type spec|work|work_order|receipt|feedback|dispute|proposal] [--json]`
 
 Notes:
 - work commands mutate semantic mirror files only
@@ -758,6 +790,7 @@ Notes:
 - `work order status` is read-only and reports deterministic order state plus linked receipts
 - `work receipt new` accepts URI-style cost/proof/attestation refs, explicit redaction policy, and SHA-256 evidence/input/output hash refs
 - `work receipt verify` is read-only and reports linkage, evidence, archive ref, hash, outcome, and redaction-policy checks; invalid receipts print JSON before exiting nonzero
+- `work validate` is read-only and reports typed diagnostics for SPEC.md, WORK.md, WORK_ORDER.md, RECEIPT.md, FEEDBACK.md, DISPUTE.md, and PROPOSAL.md mirrors; obvious raw secret, prompt, token, or payload markers are warnings, not hard failures
 - `work artifact add` calls `mdkg archive add`, then attaches the resulting `archive://...` ref to the target order or receipt
 - `work order update`, `work receipt update`, and `work artifact add` accept local ids or local qids; subgraph qids are read-only and must be changed in their source workspace
 
@@ -767,6 +800,7 @@ JSON receipts:
 - `order status`: `{ kind: "work_order_status", order, receipt_count, receipts }`
 - `receipt verify`: `{ kind: "work_receipt_verify", ok, receipt, work_order?, checks, errors, warnings }`
 - `artifact add`: `{ action: "artifact_registered", target, archive }`
+- `validate` work-validate-receipt: `{ action: "work.validate", ok, type, target?, checked_count, nodes, warning_count, error_count, warnings, errors, diagnostics }`
 
 ### `mdkg goal`
 
@@ -799,7 +833,7 @@ Usage:
 - `mdkg goal archive <goal-id-or-qid> [--ws <alias>] [--json]`
 
 Behavior:
-- `goal show` reports goal condition, goal state, scope refs, active node, required skills, required checks, and source path.
+- `goal show` reports goal condition, goal state, scope refs, active node, last active node, required skills, required checks, and source path.
 - `goal select` writes local ignored selected-goal state so `goal next` can omit the goal id.
 - `goal activate` makes one local root goal active, pauses competing local active goals in the same workspace, and writes selected-goal state.
 - `goal current` shows the selected goal or unique active goal fallback.
@@ -807,7 +841,7 @@ Behavior:
 - `goal next` is read-only and selects feature, task, bug, test, or spike work inside explicit `scope_refs`; epics are recursive containers, not executable returns.
 - `goal claim` mutates only `active_node` after the work item is confirmed inside the goal scope.
 - `goal evaluate` is report-only and never runs commands from `required_checks`.
-- `goal pause`, `goal resume`, and `goal done` update `goal_state`, compatible work status, and `updated`.
+- `goal pause`, `goal resume`, and `goal done` update `goal_state`, compatible work status, and `updated`; done goals move any current `active_node` to `last_active_node` and no longer emit stale active-node routing warnings.
 - `goal archive` marks a superseded historical goal as `status: archived` and `goal_state: archived`; archived goals remain show/search/list readable but are excluded from active routing.
 - subgraph goal qids are read-only; update the source workspace instead.
 
@@ -832,7 +866,7 @@ When to use:
 Usage:
 - `mdkg task start <id-or-qid> [--ws <alias>] [--run-id <id>] [--note "<text>"] [--json]`
 - `mdkg task update <id-or-qid> [options] [--json]`
-- `mdkg task done <id-or-qid> [--checkpoint "<title>"] [options] [--json]`
+- `mdkg task done <id-or-qid> [--checkpoint "<title>"] [--checkpoint-kind implementation|test-proof|goal-closeout|audit|handoff] [options] [--json]`
 
 #### `mdkg task start`
 
@@ -868,12 +902,13 @@ JSON receipt:
 
 Usage:
 - `mdkg task done <id-or-qid> [--ws <alias>] [--add-artifacts <a,...>] [--add-links <l,...>]`
-- `                 [--add-refs <id,...>] [--checkpoint "<title>"] [--run-id <id>] [--note "<text>"] [--json]`
+- `                 [--add-refs <id,...>] [--checkpoint "<title>"] [--checkpoint-kind implementation|test-proof|goal-closeout|audit|handoff] [--run-id <id>] [--note "<text>"] [--json]`
 
 Behavior:
 - supports task-like `feat`, `task`, `bug`, `test`, and `spike` nodes
 - sets `status: done`
 - `--checkpoint` creates a related checkpoint
+- `--checkpoint-kind` selects the evidence template for the related checkpoint
 - if `events.jsonl` is missing for the workspace, prints a short `stderr` reminder about `mdkg event enable`
 
 JSON receipt:
@@ -902,7 +937,9 @@ When to use:
 - run the repo trust gate before calling work done
 
 Usage:
-- `mdkg validate [--out <path>] [--quiet] [--json]`
+- `mdkg validate [--out <path>] [--quiet] [--changed-only] [--json]`
+- `--changed-only` filters warning presentation to changed `.mdkg` files while full graph errors still run
+- JSON receipts include `warning_diagnostics` with warning ids, categories, severity, paths, refs, and remediation text
 
 Flags:
 - `--out <path>`
@@ -959,11 +996,12 @@ JSON receipt:
 ### `mdkg checkpoint`
 
 Usage:
-- `mdkg checkpoint new <title> [--ws <alias>] [--json]`
+- `mdkg checkpoint new <title> [--kind implementation|test-proof|goal-closeout|audit|handoff] [--ws <alias>] [--json]`
 - `        [--relates <id,id,...>] [--scope <id,id,...>] [--run-id <id>] [--note "<text>"]`
+- checkpoint kinds render bodies with command evidence, pass/fail status, known warnings, changed surfaces, boundaries, and follow-up refs
 
 JSON receipt:
-- `{ action: "created", checkpoint: { workspace, id, qid, path } }`
+- `{ action: "created", checkpoint: { workspace, id, qid, path, kind } }`
 
 ### `mdkg index`
 
@@ -1003,6 +1041,7 @@ Usage:
 - `mdkg db queue list <queue> [--status ready|leased|acked|dead_letter|all] [--limit <n>] [--json]`
 - `mdkg db queue show <queue> <message-id> [--json]`
 - `mdkg db queue stats|list|show ... [--json]`
+- `mdkg db queue contract [--json]`
 - `mdkg db snapshot seal [--queue-policy drain|paused] [--json]`
 - `mdkg db snapshot verify [--json]`
 - `mdkg db snapshot status [--json]`
@@ -1023,6 +1062,10 @@ Boundaries:
   in the configured migration table
 - `mdkg db queue ...` exposes durable local delivery operations backed by
   node:sqlite; queue rows are delivery state, not canonical event history
+- `mdkg db queue contract --json` returns the public adapter contract covering
+  canonical payload hashing, dedupe semantics, oldest-ready claim order,
+  lease-owner checked settlement, retry/dead-letter behavior, release-expired,
+  pause/resume, snapshot queue policy, stats, and boundary guidance
 - paused queues reject enqueue and claim, but ack/fail/dead-letter and
   release-expired remain available so leased work can settle
 - event tables are durable local history for project DB state transitions;
@@ -1064,6 +1107,12 @@ Usage:
 
 Usage:
 - `mdkg format`
+- `mdkg format --headings [--dry-run|--apply] [--json]`
+
+Notes:
+- default `mdkg format` normalizes frontmatter in place
+- `mdkg format --headings` defaults to dry-run and returns planned missing-heading additions
+- `mdkg format --headings --apply` appends missing recommended body headings and returns a migration receipt
 
 ### `mdkg status`
 

package/README.md

@@ -29,9 +29,21 @@ The primary loop is:
 4. build a deterministic pack
 5. validate before closing the loop
 
-If an agent is involved, the default handoff primitive is `mdkg pack <id>`.
+If an agent is involved, use `mdkg pack <id>` for deterministic context and
+`mdkg handoff create <id-or-qid> --json` for a sanitized, copy-ready agent
+handoff prompt. Handoffs summarize goal/work state, included pack nodes, latest
+checkpoint, boundaries, required checks, next actions, and raw-content marker
+warnings without copying raw node bodies into the prompt.
 If a repo needs repeatable procedures, author them as first-class skills under `.mdkg/skills/`.
 
+Work nodes can separate semantic background from executable scope with
+`context_refs` and `evidence_refs`. Use `context_refs` for related plans,
+external docs, subgraph qids, or URI references that explain why work exists.
+Use `evidence_refs` for proof, audit, receipt, checkpoint, archive, or URI
+references. These fields are indexed, validated, shown, and packable, but they
+do not make referenced nodes actionable goal work; keep executable queues in
+goal `scope_refs`.
+
 ## Install
 
 ```bash
@@ -136,6 +148,7 @@ Build deterministic context:
 mdkg pack task-1
 mdkg pack task-1 --profile concise --dry-run --stats
 mdkg pack task-1 --visibility public --dry-run
+mdkg pack task-1 --edges context_refs,evidence_refs --format json
 ```
 
 Create a full `.mdkg` graph snapshot bundle for root or child orchestration:
@@ -208,6 +221,8 @@ Materialized trees are generated local state, ignored by graph indexing/search/v
 
 Subgraph nodes are projected under the subgraph alias, for example `child_repo:task-1`. They are available to `list`, `search`, `show`, `pack`, capability discovery, and `capability resolve`, but remain read-only; mutate the child repo and sync its root-owned bundle snapshot to change subgraph content. Root-authored relationship and reference fields can point at configured subgraph qids such as `child_repo:work.example`; local ownership fields such as `epic`, `parent`, `prev`, and `next` stay local-only. Stale subgraphs warn during planning reads and fail `mdkg subgraph verify`. Public or internal subgraphs must be backed by public bundle profiles; private subgraphs stay private planning context.
 
+Use `mdkg graph refs <id-or-qid> --json` to inspect inbound and outbound scope, context, evidence, blocker, related, and structural links for local or read-only subgraph qids without mutating either graph.
+
 Launch a local read-only MCP server when an MCP-capable agent should inspect a
 specific mdkg graph without receiving mutation tools:
 
@@ -226,6 +241,7 @@ Validate before handoff or commit:
 
 ```bash
 mdkg validate
+mdkg handoff create <id-or-qid> --out .mdkg/handoffs/example.md
 ```
 
 Discover cached capability surfaces:
@@ -280,8 +296,11 @@ Update structured task state and evidence while keeping body and narrative edits
 mdkg task start task-1 --run-id run_local_1
 mdkg task update task-1 --add-artifacts tests://unit.txt --add-tags release
 mdkg task done task-1 --checkpoint "release readiness milestone"
+mdkg task done task-1 --checkpoint "goal complete" --checkpoint-kind goal-closeout
 ```
 
+Checkpoint kinds are `implementation`, `test-proof`, `goal-closeout`, `audit`, and `handoff`; generated checkpoint bodies include command evidence, pass/fail status, known warnings, changed surfaces, boundaries, and follow-up refs.
+
 Ensure and append baseline event memory:
 
 ```bash
@@ -359,6 +378,11 @@ Advanced / maintenance commands still exist, but they are not the first-run stor
 - `mdkg fix plan --json`
 - `mdkg workspace`
 
+For large historical graphs, use `mdkg validate --changed-only --json` to keep
+warning review focused on changed `.mdkg` files while full graph errors still
+run. Use `mdkg format --headings --dry-run --json` to review missing recommended
+heading additions before applying them with `--apply`.
+
 ## Operator health
 
 Use `mdkg status --json` for a read-only operator summary before mutating a
@@ -478,6 +502,12 @@ rows are durable local project DB history; receipts, reducers, writer leases,
 and materializers remain internal helper surfaces in this release, with no
 public `mdkg db event`, `mdkg db reducer`, `mdkg db lease`, or
 `mdkg db materializer` CLI yet.
+`mdkg db queue contract --json` is the read-only public adapter contract for
+downstream integrations. It documents canonical payload hashing, dedupe keys,
+oldest-ready claim order, lease-owner checked ack/fail/dead-letter, retry
+delay, expired lease reclaim, max-attempt dead-letter behavior, pause/resume,
+snapshot queue policy, and stats without exposing raw SQL or making queue rows
+canonical runtime history.
 `mdkg work trigger --enqueue <queue>` can bridge a submitted work order mirror
 into an explicitly created active project DB queue; it writes local delivery
 state only and never executes work.
@@ -505,7 +535,7 @@ Goal nodes are durable recursive objective contracts. Use `mdkg new goal "<objec
 
 `goal` is work-like but distinct from `task`: it can have status, priority, graph links, skills, explicit `scope_refs`, and structured goal fields, but normal `mdkg next` does not select goals. Use `mdkg goal activate <goal-id>` to make one local root goal active, pause competing local active goals, and select it for future `goal next` calls. Use `mdkg goal select <goal-id>` only when you want to change the local ignored selected-goal pointer without changing lifecycle state. `mdkg goal next <goal-id>` remains available for explicit selection. Epics organize goal scope recursively but are not returned as executable work.
 
-Use `mdkg goal claim [goal-id] <work-id>` to durably set `active_node` after choosing the next scoped item. `goal next` is read-only. Use `mdkg goal pause|resume|done` to update goal state after review, and `mdkg goal archive` for superseded historical roadmap goals that should remain readable but non-actionable.
+Use `mdkg goal claim [goal-id] <work-id>` to durably set `active_node` after choosing the next scoped item. `goal next` is read-only. Use `mdkg goal pause|resume|done` to update goal state after review; closing a goal moves the final `active_node` to `last_active_node` so completed goals keep history without staying actionable. Use `mdkg goal archive` for superseded historical roadmap goals that should remain readable but non-actionable.
 
 Required checks are stored as report-only guidance. Agents should run the checks themselves, record evidence in the goal or active work item, then use `mdkg goal evaluate` to summarize the current evidence state. During normal goal execution, skill improvements should be recorded as improvement candidates or proposal nodes; edit `SKILL.md` files only when the active node is explicit skill-maintenance work.
 
@@ -545,7 +575,7 @@ Use `mdkg new spec|work|work_order|receipt|feedback|dispute|proposal "<title>"`
 
 Relational templates contain editable placeholder refs. `spec` and `work` scaffold as validation-clean standalone docs; `work_order`, `receipt`, `feedback`, `dispute`, and `proposal` need real refs before strict `mdkg validate` passes.
 
-For executable or purchasable capability mirrors, prefer the lifecycle helpers under `mdkg work ...`. They create and update `WORK.md`, `WORK_ORDER.md`, and `RECEIPT.md` semantic mirror files only. `mdkg work trigger` creates a deterministic submitted `WORK_ORDER.md` from a WORK contract or a SPEC with exactly one resolvable work contract. `mdkg work order status` and `mdkg work receipt verify` are read-only review helpers for deterministic closeout. `mdkg work trigger --enqueue <queue>` optionally writes a local project DB queue delivery message after the queue has been explicitly created and is active; it still does not execute work. Production order state, receipt state, feedback, disputes, payments, ledgers, marketplace inventory, fulfillment records, and execution state remain canonical outside mdkg, such as in Postgres or another application database. Do not store raw secrets, credentials, live payment state, ledger mutations, canonical marketplace state, or bulky raw payloads in these mirrors.
+For executable or purchasable capability mirrors, prefer the lifecycle helpers under `mdkg work ...`. They create and update `WORK.md`, `WORK_ORDER.md`, and `RECEIPT.md` semantic mirror files only. `mdkg work trigger` creates a deterministic submitted `WORK_ORDER.md` from a WORK contract or a SPEC with exactly one resolvable work contract. `mdkg work order status` and `mdkg work receipt verify` are read-only review helpers for deterministic closeout. `mdkg work validate [<id-or-qid>] [--type spec|work|work_order|receipt|feedback|dispute|proposal] --json` is a read-only focused validator for agent workflow mirrors; it returns typed diagnostics and warns on obvious raw secret, prompt, token, or payload markers. `mdkg work trigger --enqueue <queue>` optionally writes a local project DB queue delivery message after the queue has been explicitly created and is active; it still does not execute work. Production order state, receipt state, feedback, disputes, payments, ledgers, marketplace inventory, fulfillment records, and execution state remain canonical outside mdkg, such as in Postgres or another application database. Do not store raw secrets, credentials, live payment state, ledger mutations, canonical marketplace state, or bulky raw payloads in these mirrors.
 
 ## Archive sidecars