Add Memory Core repair dry-run exportability report

Context

This leaf exists because #13999 is the active P0 backup-exportability regression, but the first safe implementation slice is narrower than the parent: before any live Memory Core collection mutation, operators need a non-mutating report path that runs the same full-enumeration extraction/re-embed logic and proves whether the repair would be clean or would abort.

Parent #13999 requires the actual production repair and a successful canonical backup with row-count parity. A PR that only adds the dry-run/report primitive must not magic-close that parent. This ticket is the close target for that bounded slice.

Live latest-open sweep: checked the latest 20 open GitHub issues at 2026-06-25T13:13:54Z; no equivalent open leaf found. The closest open item was parent #13999 itself. Recent open issues #14000, #13994, #13983, and #13936 do not cover Memory Core repair dry-run/report behavior.

A2A in-flight sweep: checked the latest 30 all-status messages at 2026-06-25T13:13:54Z. The only overlapping claims were my own #13999 dry-run/report claims; no competing peer claim or in-flight ticket filing was present.

KB/local sweep: semantic ticket search for Memory Core repair dry-run exportability report shadow promotion returned older closed repair prerequisites plus parent #13999, not an equivalent open leaf. Exact local search surfaced closed/archived dry-run patterns and the older closed #13496/#13612 repair-diagnostic work, but no current open issue for this specific report-mode close target.

Release classification: ON Project 12 — this is a P0 backup-regression safety precondition. It enables non-mutating proof before the copy/shadow repair path is used against live Memory Core data.

The Problem

The existing Memory Core repair-defrag path can perform a full-enumeration extract, re-embed rows whose vectors are missing, and shadow-promote a repaired collection when clean. That mutating path is intentionally guarded by --allow-memory-core because Memory Core is an irreplaceable Agent OS store.

For the current #13999 incident, jumping straight from diagnosis to promotion is the wrong operator shape. The system needs a report mode that exercises the same extraction/re-embed seam, returns the same clean-versus-unrecoverable truth, and refuses to write defrag state markers or promote shadow collections.

Without this leaf, the parent repair lane has only two unsatisfying choices: run a mutating repair to discover unrecoverable rows, or keep relying on diagnostics that do not prove the actual repair extraction path.

The Architectural Reality

Relevant surfaces:

• ai/scripts/maintenance/defragChromaDB.mjs owns the guarded Memory Core repair-defrag orchestration and the repairMemoryCoreCollectionsViaFullEnumeration() helper.
• The prior #13634 path established full-enumeration audit -> extraction/re-embed -> shadow-promotion behind --allow-memory-core.
• Parent #13999 now needs the same path to support a non-mutating preflight report before live repair.
• The report mode must not weaken #13583's fail-loud partial-export behavior and must not treat MC/KB healthcheck success as exportability proof.

The Fix

Add a Memory Core repair dry-run/report mode to the existing maintenance script:

1. Thread a dryRun option through repairMemoryCoreCollectionsViaFullEnumeration().
2. In dry-run mode, run the full enumeration and extraction/re-embed report, then return per-collection counts without invoking shadow promotion.
3. If extraction finds unrecoverable rows, report the collection as aborted and keep the same fail-loud predicate so the CLI exits non-zero.
4. Do not clear or write durable defrag state markers during dry-run.
5. Add CLI help for --dry-run on the Memory Core target.
6. Add focused unit coverage for clean dry-run and unrecoverable dry-run behavior.

Contract Ledger Matrix

Decision Record impact

none. This is a maintenance safety/reporting leaf inside the existing ADR 0017 Chroma topology and the #13634 guarded repair path. It does not change AiConfig ownership or daemon topology.

Acceptance Criteria

• repairMemoryCoreCollectionsViaFullEnumeration() accepts a dryRun option and reports clean extraction counts without promoting a shadow collection.
• Dry-run mode does not clear or write durable defrag state markers.
• Dry-run mode reports unrecoverable rows as aborted and preserves the existing fail-loud predicate.
• The Memory Core CLI exposes a --dry-run option for the repair-defrag target.
• Focused unit coverage proves both clean and unrecoverable dry-run behavior.
• Parent #13999 remains open for actual live repair execution and canonical backup row-count parity.

Out of Scope

• Running the live Memory Core repair against production data.
• Claiming the canonical backup is fixed before row-count parity is observed.
• Changing #13583 fail-loud backup behavior.
• Fixing DatabaseService.#exportCollection() collection identity diagnostics; that is covered separately by PR #14004.
• Treating ordinary MC/KB healthchecks as proof of exportability.

Avoided Traps

• Do not use Resolves #13999 for the dry-run/report PR; the parent requires live repair and backup parity.
• Do not write state markers during a report-only mode.
• Do not make dry-run skip extraction/re-embed, because then it would not prove the repair path.
• Do not soften unrecoverable rows into warnings; they must remain repair blockers.

Related

Parent: #13999 Related: #13496 Related: #13612 Related: #13634 Related: #13583 Related: #14004

Origin Session ID: f4d00667-a65a-4285-83f5-6761f3aea394

Handoff Retrieval Hints

• query_raw_memories("#13999 Memory Core repair dry-run report mode full enumeration extraction no promotion")
• query_raw_memories("repairMemoryCoreCollectionsViaFullEnumeration dryRun no shadow promotion state marker")
• Branch anchor: codex/13999-memory-core-repair-dry-run
• Commit anchor: 1e7a7ddacc50e8cdff0206626542e09a5ff30bcd