@cleocode/core 2026.6.7 → 2026.6.9

package/dist/store/exodus/abort-events.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Typed, process-local event channel for exodus-on-open ABORTS (T11828 · DHQ-059).
+ *
+ * ## Why this exists
+ *
+ * The exodus-on-open data-continuity gate ({@link maybeRunExodusOnOpen}) can
+ * ABORT a first-open auto-migration when the parity verify fails or the copy
+ * errors mid-flight. On abort the consolidated `cleo.db` is rolled back to EMPTY
+ * and the legacy fleet is kept as the source of truth — so the handle the
+ * chokepoint hands back is live and success-shaped, but the data the caller
+ * expected is NOT in it.
+ *
+ * Before T11828 that abort surfaced ONLY as a `log.warn(...)` inside the open
+ * chokepoint. A MUTATING caller (e.g. `tasks.add`) therefore had no programmatic
+ * signal that its write was about to land in a consolidated DB that does not
+ * contain the user's real data — i.e. the write may not be durable against the
+ * source of truth. This module is the out-of-band surface: every abort is
+ * broadcast here so daemon/session/diagnostic subscribers can react, AND the
+ * abort detail is stamped onto the returned {@link DualScopeDbHandle} so a
+ * mutation path can detect it synchronously via {@link assertWriteDurable}.
+ *
+ * Read-only callers ignore the marker entirely — they get a valid handle and the
+ * empty-but-consistent consolidated DB, exactly as before.
+ *
+ * @module
+ * @task T11828 (DHQ-059 — surface exodus-on-open abort to mutating callers)
+ * @epic T11833
+ * @saga T11242 (SG-DB-SUBSTRATE-V2)
+ * @see packages/core/src/store/exodus/on-open.ts — where the abort originates
+ * @see packages/core/src/store/dual-scope-db.ts — where the marker is stamped + assertWriteDurable
+ */
+import { EventEmitter } from 'node:events';
+import type { DualScope } from '../dual-scope-db.js';
+/**
+ * Structured detail of an exodus-on-open abort, stamped onto the returned
+ * {@link DualScopeDbHandle} and broadcast on the {@link exodusAbortEvents}
+ * channel.
+ *
+ * @task T11828
+ * @public
+ */
+export interface ExodusAbortDetail {
+    /** The scope whose first-open auto-migration aborted. */
+    readonly scope: DualScope;
+    /** Absolute path to the consolidated `cleo.db` for that scope. */
+    readonly dbPath: string;
+    /** Human-readable abort reason (parity deficit, mid-copy failure, …). */
+    readonly reason: string;
+    /** Epoch-ms timestamp the abort was observed. */
+    readonly at: number;
+}
+/**
+ * Map of event name → listener argument tuple for the exodus-abort channel.
+ *
+ * @task T11828
+ */
+interface ExodusAbortEventMap {
+    /** Emitted once per exodus-on-open abort, after rollback completes. */
+    abort: [detail: ExodusAbortDetail];
+}
+/**
+ * Process-local emitter broadcasting every exodus-on-open ABORT.
+ *
+ * Subscribers (daemon liveness, session lifecycle, `cleo doctor exodus-health`)
+ * MAY listen for `'abort'` to react to a degraded first-open without coupling to
+ * the store chokepoint. Emission is best-effort and never throws into the open
+ * path — listener errors are swallowed by {@link emitExodusAbort}.
+ *
+ * @task T11828
+ * @public
+ */
+export declare const exodusAbortEvents: EventEmitter<ExodusAbortEventMap>;
+/**
+ * Broadcast an exodus-on-open abort on the {@link exodusAbortEvents} channel and
+ * record it in the process-local per-scope registry.
+ *
+ * Best-effort: a throwing/synchronous listener must NOT propagate into the DB
+ * open path, so emission is wrapped. Returns `true` if at least one listener was
+ * notified (matching `EventEmitter.emit` semantics) — informational only.
+ *
+ * @param detail - The structured abort detail to broadcast.
+ * @returns `true` when the event had listeners; `false` otherwise.
+ *
+ * @task T11828
+ * @public
+ */
+export declare function emitExodusAbort(detail: ExodusAbortDetail): boolean;
+/**
+ * Return the recorded abort detail for `scope`, or — when `scope` is omitted —
+ * the most-recent abort across any scope. `undefined` when no abort is recorded.
+ *
+ * Used by the write-side guard to reject a mutation that would land in a
+ * consolidated DB the exodus-on-open gate left empty.
+ *
+ * @param scope - Optional scope filter; when omitted, returns any recorded abort.
+ * @returns The {@link ExodusAbortDetail}, or `undefined`.
+ *
+ * @task T11828
+ * @public
+ */
+export declare function getRecordedExodusAbort(scope?: DualScope): ExodusAbortDetail | undefined;
+/**
+ * Clear recorded aborts — all scopes, or a single `scope`.
+ *
+ * Call after the aborted migration is resolved (a subsequent successful
+ * `cleo exodus migrate` / `cleo doctor repair`) so writes are no longer rejected,
+ * and in test teardown to isolate cases.
+ *
+ * @param scope - Optional scope to clear; when omitted, clears every scope.
+ *
+ * @task T11828
+ * @public
+ */
+export declare function clearExodusAborts(scope?: DualScope): void;
+export {};
+//# sourceMappingURL=abort-events.d.ts.map

package/dist/store/exodus/abort-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort-events.d.ts","sourceRoot":"","sources":["../../../src/store/exodus/abort-events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,yDAAyD;IACzD,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,UAAU,mBAAmB;IAC3B,uEAAuE;IACvE,KAAK,EAAE,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;CACpC;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,mCAA0C,CAAC;AAsBzE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAQlE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,CAAC,EAAE,SAAS,GAAG,iBAAiB,GAAG,SAAS,CAQvF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,CAAC,EAAE,SAAS,GAAG,IAAI,CAMzD"}

package/dist/store/exodus/abort-events.js

@@ -0,0 +1,130 @@
+/**
+ * Typed, process-local event channel for exodus-on-open ABORTS (T11828 · DHQ-059).
+ *
+ * ## Why this exists
+ *
+ * The exodus-on-open data-continuity gate ({@link maybeRunExodusOnOpen}) can
+ * ABORT a first-open auto-migration when the parity verify fails or the copy
+ * errors mid-flight. On abort the consolidated `cleo.db` is rolled back to EMPTY
+ * and the legacy fleet is kept as the source of truth — so the handle the
+ * chokepoint hands back is live and success-shaped, but the data the caller
+ * expected is NOT in it.
+ *
+ * Before T11828 that abort surfaced ONLY as a `log.warn(...)` inside the open
+ * chokepoint. A MUTATING caller (e.g. `tasks.add`) therefore had no programmatic
+ * signal that its write was about to land in a consolidated DB that does not
+ * contain the user's real data — i.e. the write may not be durable against the
+ * source of truth. This module is the out-of-band surface: every abort is
+ * broadcast here so daemon/session/diagnostic subscribers can react, AND the
+ * abort detail is stamped onto the returned {@link DualScopeDbHandle} so a
+ * mutation path can detect it synchronously via {@link assertWriteDurable}.
+ *
+ * Read-only callers ignore the marker entirely — they get a valid handle and the
+ * empty-but-consistent consolidated DB, exactly as before.
+ *
+ * @module
+ * @task T11828 (DHQ-059 — surface exodus-on-open abort to mutating callers)
+ * @epic T11833
+ * @saga T11242 (SG-DB-SUBSTRATE-V2)
+ * @see packages/core/src/store/exodus/on-open.ts — where the abort originates
+ * @see packages/core/src/store/dual-scope-db.ts — where the marker is stamped + assertWriteDurable
+ */
+import { EventEmitter } from 'node:events';
+/**
+ * Process-local emitter broadcasting every exodus-on-open ABORT.
+ *
+ * Subscribers (daemon liveness, session lifecycle, `cleo doctor exodus-health`)
+ * MAY listen for `'abort'` to react to a degraded first-open without coupling to
+ * the store chokepoint. Emission is best-effort and never throws into the open
+ * path — listener errors are swallowed by {@link emitExodusAbort}.
+ *
+ * @task T11828
+ * @public
+ */
+export const exodusAbortEvents = new EventEmitter();
+// An aborted first-open install can legitimately have many domain opens fire in
+// one process (tasks, brain, conduit, …); each would re-broadcast. Raise the cap
+// modestly above the default 10 so a busy session does not emit a spurious
+// MaxListenersExceededWarning, while still flagging a genuine listener leak.
+exodusAbortEvents.setMaxListeners(50);
+/**
+/**
+ * Process-local registry of the most recent abort detail per scope.
+ *
+ * Recorded on every {@link emitExodusAbort} so the write-side guard
+ * (`assertWriteDurable` via {@link insertIdempotent} / {@link upsertIdempotent})
+ * can detect a degraded first-open even when the caller no longer holds the
+ * original {@link DualScopeDbHandle} (e.g. domain modules that extract the native
+ * handle and discard the wrapper). Cleared by {@link clearExodusAborts} once the
+ * underlying migration is resolved (successful `cleo exodus migrate` / recovery)
+ * or in test teardown.
+ */
+const _abortedScopes = new Map();
+/**
+ * Broadcast an exodus-on-open abort on the {@link exodusAbortEvents} channel and
+ * record it in the process-local per-scope registry.
+ *
+ * Best-effort: a throwing/synchronous listener must NOT propagate into the DB
+ * open path, so emission is wrapped. Returns `true` if at least one listener was
+ * notified (matching `EventEmitter.emit` semantics) — informational only.
+ *
+ * @param detail - The structured abort detail to broadcast.
+ * @returns `true` when the event had listeners; `false` otherwise.
+ *
+ * @task T11828
+ * @public
+ */
+export function emitExodusAbort(detail) {
+    _abortedScopes.set(detail.scope, detail);
+    try {
+        return exodusAbortEvents.emit('abort', detail);
+    }
+    catch {
+        // A misbehaving listener must never break the open path.
+        return false;
+    }
+}
+/**
+ * Return the recorded abort detail for `scope`, or — when `scope` is omitted —
+ * the most-recent abort across any scope. `undefined` when no abort is recorded.
+ *
+ * Used by the write-side guard to reject a mutation that would land in a
+ * consolidated DB the exodus-on-open gate left empty.
+ *
+ * @param scope - Optional scope filter; when omitted, returns any recorded abort.
+ * @returns The {@link ExodusAbortDetail}, or `undefined`.
+ *
+ * @task T11828
+ * @public
+ */
+export function getRecordedExodusAbort(scope) {
+    if (scope !== undefined)
+        return _abortedScopes.get(scope);
+    // Most-recent across scopes (Map preserves insertion order; emit overwrites).
+    let latest;
+    for (const detail of _abortedScopes.values()) {
+        if (!latest || detail.at >= latest.at)
+            latest = detail;
+    }
+    return latest;
+}
+/**
+ * Clear recorded aborts — all scopes, or a single `scope`.
+ *
+ * Call after the aborted migration is resolved (a subsequent successful
+ * `cleo exodus migrate` / `cleo doctor repair`) so writes are no longer rejected,
+ * and in test teardown to isolate cases.
+ *
+ * @param scope - Optional scope to clear; when omitted, clears every scope.
+ *
+ * @task T11828
+ * @public
+ */
+export function clearExodusAborts(scope) {
+    if (scope !== undefined) {
+        _abortedScopes.delete(scope);
+        return;
+    }
+    _abortedScopes.clear();
+}
+//# sourceMappingURL=abort-events.js.map

package/dist/store/exodus/abort-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort-events.js","sourceRoot":"","sources":["../../../src/store/exodus/abort-events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAgC3C;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,YAAY,EAAuB,CAAC;AAEzE,gFAAgF;AAChF,iFAAiF;AACjF,2EAA2E;AAC3E,6EAA6E;AAC7E,iBAAiB,CAAC,eAAe,CAAC,EAAE,CAAC,CAAC;AAEtC;;;;;;;;;;;GAWG;AACH,MAAM,cAAc,GAAG,IAAI,GAAG,EAAgC,CAAC;AAE/D;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,eAAe,CAAC,MAAyB;IACvD,cAAc,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IACzC,IAAI,CAAC;QACH,OAAO,iBAAiB,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACjD,CAAC;IAAC,MAAM,CAAC;QACP,yDAAyD;QACzD,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAiB;IACtD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAC1D,8EAA8E;IAC9E,IAAI,MAAqC,CAAC;IAC1C,KAAK,MAAM,MAAM,IAAI,cAAc,CAAC,MAAM,EAAE,EAAE,CAAC;QAC7C,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,EAAE,IAAI,MAAM,CAAC,EAAE;YAAE,MAAM,GAAG,MAAM,CAAC;IACzD,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAiB;IACjD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,cAAc,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC7B,OAAO;IACT,CAAC;IACD,cAAc,CAAC,KAAK,EAAE,CAAC;AACzB,CAAC"}

package/dist/store/exodus/index.d.ts

@@ -8,6 +8,7 @@
  * @task T11248 (E5 · SG-DB-SUBSTRATE-V2)
  * @saga T11242
  */
+export { clearExodusAborts, type ExodusAbortDetail, emitExodusAbort, exodusAbortEvents, getRecordedExodusAbort, } from './abort-events.js';
 export { type ArchivedSourceResult, type ArchiveMigratedSourcesResult, archiveMigratedSources, archiveSourceDb, archiveStrandedResidue, detectStrandedResidue, type ExodusCompleteMarker, exodusArchiveDir, exodusMarkerPath, hasExodusCompleteMarker, type StrandedResidueEntry, writeExodusCompleteMarker, } from './archive.js';
 export { type CountParityEntry, type CountParityResult, computeCountParity, } from './count-parity.js';
 export { buildExodusHealth, type ExodusHealth, type ExodusScopeHealth, type ExodusScopeState, type ExodusSourceHealth, } from './health.js';

package/dist/store/exodus/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/store/exodus/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,4BAA4B,EACjC,sBAAsB,EACtB,eAAe,EACf,sBAAsB,EACtB,qBAAqB,EACrB,KAAK,oBAAoB,EACzB,gBAAgB,EAChB,gBAAgB,EAChB,uBAAuB,EACvB,KAAK,oBAAoB,EACzB,yBAAyB,GAC1B,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,kBAAkB,GACnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,iBAAiB,EACjB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,GACxB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACpE,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAClF,OAAO,EACL,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,UAAU,GACX,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EACL,wBAAwB,EACxB,4BAA4B,EAC5B,aAAa,EACb,KAAK,mBAAmB,GACzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,4BAA4B,EAC5B,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,GACvB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/store/exodus/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,iBAAiB,EACjB,KAAK,iBAAiB,EACtB,eAAe,EACf,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,4BAA4B,EACjC,sBAAsB,EACtB,eAAe,EACf,sBAAsB,EACtB,qBAAqB,EACrB,KAAK,oBAAoB,EACzB,gBAAgB,EAChB,gBAAgB,EAChB,uBAAuB,EACvB,KAAK,oBAAoB,EACzB,yBAAyB,GAC1B,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,kBAAkB,GACnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,iBAAiB,EACjB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,GACxB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACpE,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAClF,OAAO,EACL,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,UAAU,GACX,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EACL,wBAAwB,EACxB,4BAA4B,EAC5B,aAAa,EACb,KAAK,mBAAmB,GACzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,4BAA4B,EAC5B,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,GACvB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/store/exodus/index.js

@@ -8,6 +8,7 @@
  * @task T11248 (E5 · SG-DB-SUBSTRATE-V2)
  * @saga T11242
  */
+export { clearExodusAborts, emitExodusAbort, exodusAbortEvents, getRecordedExodusAbort, } from './abort-events.js';
 export { archiveMigratedSources, archiveSourceDb, archiveStrandedResidue, detectStrandedResidue, exodusArchiveDir, exodusMarkerPath, hasExodusCompleteMarker, writeExodusCompleteMarker, } from './archive.js';
 export { computeCountParity, } from './count-parity.js';
 export { buildExodusHealth, } from './health.js';

package/dist/store/exodus/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/store/exodus/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAGL,sBAAsB,EACtB,eAAe,EACf,sBAAsB,EACtB,qBAAqB,EAErB,gBAAgB,EAChB,gBAAgB,EAChB,uBAAuB,EAEvB,yBAAyB,GAC1B,MAAM,cAAc,CAAC;AACtB,OAAO,EAGL,kBAAkB,GACnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,iBAAiB,GAKlB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACpE,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAClF,OAAO,EAIL,UAAU,GACX,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EACL,wBAAwB,EACxB,4BAA4B,EAC5B,aAAa,GAEd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,4BAA4B,GAY7B,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/store/exodus/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,iBAAiB,EAEjB,eAAe,EACf,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAGL,sBAAsB,EACtB,eAAe,EACf,sBAAsB,EACtB,qBAAqB,EAErB,gBAAgB,EAChB,gBAAgB,EAChB,uBAAuB,EAEvB,yBAAyB,GAC1B,MAAM,cAAc,CAAC;AACtB,OAAO,EAGL,kBAAkB,GACnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,iBAAiB,GAKlB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACpE,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAClF,OAAO,EAIL,UAAU,GACX,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EACL,wBAAwB,EACxB,4BAA4B,EAC5B,aAAa,GAEd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,4BAA4B,GAY7B,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/store/repair-malformed-dbs.d.ts

@@ -0,0 +1,87 @@
+/**
+ * `cleo doctor repair` orchestrator — detect malformed CLEO databases and
+ * restore each from its freshest validated snapshot (T11829 · DHQ-060).
+ *
+ * ## Why this exists
+ *
+ * The corruption-resilience pipeline ALREADY existed before T11829:
+ *
+ *  - {@link recoverMalformedDb} (quarantine → snapshot-restore → `quick_check`),
+ *  - `autoRecoverFromBackup` (catches `"database disk image is malformed"` at
+ *    open and restores the freshest VACUUM snapshot), and
+ *  - the operator verb `cleo backup recover <role>` ({@link runBackupRecover}).
+ *
+ * The ONLY gap vs the DHQ-060 ask was a discoverable `cleo doctor` entry point
+ * that DETECTS corruption across the fleet and repairs only what is broken. This
+ * module is that orchestrator — it adds NO new recovery logic. It probes each
+ * role's live DB with `PRAGMA quick_check` (the same probe the pipeline runs on
+ * snapshot candidates, via {@link probeSnapshot}) and delegates every actual
+ * repair to {@link runBackupRecover} → {@link recoverMalformedDb}.
+ *
+ * ## WAL-specific corruption is covered
+ *
+ * A torn WAL frame surfaces as `"database disk image is malformed"` and makes
+ * `PRAGMA quick_check` return a non-`ok` result — so {@link probeSnapshot}
+ * detects it. The quarantine step ({@link quarantineCorruptDb}) already moves the
+ * `-wal`/`-shm` sidecars alongside the main file, so the WAL case is fully
+ * handled by the existing pipeline; this orchestrator does not need to special-case it.
+ *
+ * @module
+ * @task T11829 (DHQ-060 — `cleo doctor repair` entry point over the recovery pipeline)
+ * @epic T11833
+ * @saga T11242 (SG-DB-SUBSTRATE-V2)
+ * @see packages/core/src/store/recover-malformed-db.ts — the recovery pipeline
+ * @see packages/core/src/store/backup-recover.ts — `cleo backup recover <role>` wrapper
+ */
+import { type DbRole, type DoctorRepairResult } from '@cleocode/contracts';
+import { type RecoveryLogger } from './recover-malformed-db.js';
+/**
+ * Options accepted by {@link repairMalformedDbs}.
+ *
+ * @task T11829
+ * @public
+ */
+export interface RepairMalformedDbsOptions {
+    /** Absolute path to the project root (resolves `<projectRoot>` inventory tokens). */
+    projectRoot: string;
+    /**
+     * Roles to inspect. When omitted, EVERY role in {@link DB_INVENTORY} whose live
+     * file exists is probed. An explicit single-role list (from `--role`) is probed
+     * even when absent (so the operator gets a clear "not present" report).
+     */
+    roles?: DbRole[];
+    /**
+     * When `true`, detect + plan only — corruption is reported with
+     * `action: 'would-repair'` but NO quarantine/restore is performed.
+     *
+     * @default false
+     */
+    dryRun?: boolean;
+    /** Pino-shaped logger for recovery announcements. */
+    logger: RecoveryLogger;
+}
+/**
+ * Detect and repair malformed CLEO databases across the fleet (T11829 · DHQ-060).
+ *
+ * For each requested role (or every present role in {@link DB_INVENTORY} when none
+ * are specified) this probes the live DB with `PRAGMA quick_check` and, when
+ * corruption is found, restores the freshest validated snapshot via the existing
+ * {@link runBackupRecover} pipeline. No new recovery logic is introduced — this is
+ * the discoverable `cleo doctor repair` entry point requested by DHQ-060.
+ *
+ * @param opts - Repair inputs (project root, optional role filter, dry-run, logger).
+ * @returns A {@link DoctorRepairResult} aggregate with per-role outcomes.
+ *
+ * @example
+ * ```ts
+ * const report = repairMalformedDbs({ projectRoot: '/repo', logger });
+ * if (report.failedCount > 0) process.exitCode = 1;
+ * ```
+ *
+ * @task T11829
+ * @epic T11833
+ * @saga T11242
+ * @public
+ */
+export declare function repairMalformedDbs(opts: RepairMalformedDbsOptions): DoctorRepairResult;
+//# sourceMappingURL=repair-malformed-dbs.d.ts.map

package/dist/store/repair-malformed-dbs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repair-malformed-dbs.d.ts","sourceRoot":"","sources":["../../src/store/repair-malformed-dbs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAGH,OAAO,EAAgB,KAAK,MAAM,EAAE,KAAK,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEzF,OAAO,EAAiB,KAAK,cAAc,EAAqB,MAAM,2BAA2B,CAAC;AAElG;;;;;GAKG;AACH,MAAM,WAAW,yBAAyB;IACxC,qFAAqF;IACrF,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,qDAAqD;IACrD,MAAM,EAAE,cAAc,CAAC;CACxB;AA2HD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,yBAAyB,GAAG,kBAAkB,CAiBtF"}

package/dist/store/repair-malformed-dbs.js

@@ -0,0 +1,188 @@
+/**
+ * `cleo doctor repair` orchestrator — detect malformed CLEO databases and
+ * restore each from its freshest validated snapshot (T11829 · DHQ-060).
+ *
+ * ## Why this exists
+ *
+ * The corruption-resilience pipeline ALREADY existed before T11829:
+ *
+ *  - {@link recoverMalformedDb} (quarantine → snapshot-restore → `quick_check`),
+ *  - `autoRecoverFromBackup` (catches `"database disk image is malformed"` at
+ *    open and restores the freshest VACUUM snapshot), and
+ *  - the operator verb `cleo backup recover <role>` ({@link runBackupRecover}).
+ *
+ * The ONLY gap vs the DHQ-060 ask was a discoverable `cleo doctor` entry point
+ * that DETECTS corruption across the fleet and repairs only what is broken. This
+ * module is that orchestrator — it adds NO new recovery logic. It probes each
+ * role's live DB with `PRAGMA quick_check` (the same probe the pipeline runs on
+ * snapshot candidates, via {@link probeSnapshot}) and delegates every actual
+ * repair to {@link runBackupRecover} → {@link recoverMalformedDb}.
+ *
+ * ## WAL-specific corruption is covered
+ *
+ * A torn WAL frame surfaces as `"database disk image is malformed"` and makes
+ * `PRAGMA quick_check` return a non-`ok` result — so {@link probeSnapshot}
+ * detects it. The quarantine step ({@link quarantineCorruptDb}) already moves the
+ * `-wal`/`-shm` sidecars alongside the main file, so the WAL case is fully
+ * handled by the existing pipeline; this orchestrator does not need to special-case it.
+ *
+ * @module
+ * @task T11829 (DHQ-060 — `cleo doctor repair` entry point over the recovery pipeline)
+ * @epic T11833
+ * @saga T11242 (SG-DB-SUBSTRATE-V2)
+ * @see packages/core/src/store/recover-malformed-db.ts — the recovery pipeline
+ * @see packages/core/src/store/backup-recover.ts — `cleo backup recover <role>` wrapper
+ */
+import { existsSync } from 'node:fs';
+import { DB_INVENTORY } from '@cleocode/contracts';
+import { BackupRecoverError, runBackupRecover } from './backup-recover.js';
+import { probeSnapshot, resolveRoleDbPath } from './recover-malformed-db.js';
+/**
+ * Probe a single role's live DB and, when malformed, repair it from snapshot.
+ *
+ * Pure delegation: detection via {@link probeSnapshot} (`PRAGMA quick_check`),
+ * repair via {@link runBackupRecover}. Never throws — a recovery failure is
+ * captured in the returned record's `action: 'failed'`.
+ *
+ * @internal
+ */
+function repairOneRole(role, opts) {
+    const dbPath = resolveRoleDbPath(role, { projectRoot: opts.projectRoot });
+    const present = existsSync(dbPath);
+    if (!present) {
+        return {
+            role,
+            dbPath,
+            present: false,
+            healthy: true,
+            action: 'skipped',
+            restoredFrom: null,
+            quarantinedTo: null,
+            dataLossWindowHours: null,
+            detail: 'live DB file not present on disk (nothing to repair)',
+        };
+    }
+    // DETECT — the same `PRAGMA quick_check` the pipeline runs on snapshots. A
+    // torn WAL frame ("database disk image is malformed") fails this probe.
+    const probe = probeSnapshot(dbPath);
+    if (probe.ok) {
+        return {
+            role,
+            dbPath,
+            present: true,
+            healthy: true,
+            action: 'skipped',
+            restoredFrom: null,
+            quarantinedTo: null,
+            dataLossWindowHours: null,
+            detail: 'PRAGMA quick_check passed — DB is healthy',
+        };
+    }
+    // MALFORMED — plan or repair.
+    if (opts.dryRun === true) {
+        try {
+            // Dry-run delegates to the SAME pipeline (no mutation) for an honest plan.
+            const plan = runBackupRecover({
+                role,
+                projectRoot: opts.projectRoot,
+                logger: opts.logger,
+                dryRun: true,
+            });
+            return {
+                role,
+                dbPath,
+                present: true,
+                healthy: false,
+                action: 'would-repair',
+                restoredFrom: plan.restoredFrom || null,
+                quarantinedTo: null,
+                dataLossWindowHours: plan.dataLossWindowHours,
+                detail: `malformed — would restore from ${plan.restoredFrom} (re-run without --dry-run to repair)`,
+            };
+        }
+        catch (err) {
+            return {
+                role,
+                dbPath,
+                present: true,
+                healthy: false,
+                action: 'failed',
+                restoredFrom: null,
+                quarantinedTo: null,
+                dataLossWindowHours: null,
+                detail: `malformed but NO valid snapshot to restore from: ${err instanceof BackupRecoverError ? err.message : String(err)}`,
+            };
+        }
+    }
+    // EXECUTE — quarantine + restore + verify via the existing pipeline.
+    try {
+        const result = runBackupRecover({
+            role,
+            projectRoot: opts.projectRoot,
+            logger: opts.logger,
+            dryRun: false,
+        });
+        return {
+            role,
+            dbPath,
+            present: true,
+            healthy: false,
+            action: 'repaired',
+            restoredFrom: result.restoredFrom || null,
+            quarantinedTo: result.quarantinedTo || null,
+            dataLossWindowHours: result.dataLossWindowHours,
+            detail: `repaired — restored from ${result.restoredFrom}; corrupt DB quarantined at ${result.quarantinedTo}`,
+        };
+    }
+    catch (err) {
+        return {
+            role,
+            dbPath,
+            present: true,
+            healthy: false,
+            action: 'failed',
+            restoredFrom: null,
+            quarantinedTo: null,
+            dataLossWindowHours: null,
+            detail: `malformed — recovery FAILED: ${err instanceof BackupRecoverError ? err.message : String(err)}`,
+        };
+    }
+}
+/**
+ * Detect and repair malformed CLEO databases across the fleet (T11829 · DHQ-060).
+ *
+ * For each requested role (or every present role in {@link DB_INVENTORY} when none
+ * are specified) this probes the live DB with `PRAGMA quick_check` and, when
+ * corruption is found, restores the freshest validated snapshot via the existing
+ * {@link runBackupRecover} pipeline. No new recovery logic is introduced — this is
+ * the discoverable `cleo doctor repair` entry point requested by DHQ-060.
+ *
+ * @param opts - Repair inputs (project root, optional role filter, dry-run, logger).
+ * @returns A {@link DoctorRepairResult} aggregate with per-role outcomes.
+ *
+ * @example
+ * ```ts
+ * const report = repairMalformedDbs({ projectRoot: '/repo', logger });
+ * if (report.failedCount > 0) process.exitCode = 1;
+ * ```
+ *
+ * @task T11829
+ * @epic T11833
+ * @saga T11242
+ * @public
+ */
+export function repairMalformedDbs(opts) {
+    const explicit = opts.roles !== undefined && opts.roles.length > 0;
+    const candidateRoles = explicit
+        ? opts.roles
+        : DB_INVENTORY.map((e) => e.role).filter((role) => existsSync(resolveRoleDbPath(role, { projectRoot: opts.projectRoot })));
+    const roles = candidateRoles.map((role) => repairOneRole(role, opts));
+    return {
+        dryRun: opts.dryRun === true,
+        roles,
+        malformedCount: roles.filter((r) => !r.healthy).length,
+        repairedCount: roles.filter((r) => r.action === 'repaired').length,
+        failedCount: roles.filter((r) => r.action === 'failed').length,
+    };
+}
+//# sourceMappingURL=repair-malformed-dbs.js.map

package/dist/store/repair-malformed-dbs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repair-malformed-dbs.js","sourceRoot":"","sources":["../../src/store/repair-malformed-dbs.ts"],"names":[],"mappings":"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"}