ruvnet-brain 4.6.4 → 4.7.0

package/plugin/scripts/project-progression-producer.mjs

@@ -1,309 +0,0 @@
-/**
- * project-progression-producer.mjs — the thing that was missing.
- *
- * `captureProjectTransition` has always been able to store a complete project snapshot. Nothing ever
- * BUILT one: it was only reachable when a host payload already carried a `projectProgression`
- * extension, and no host emits one. So the North Star's "append-only full project snapshots" had a
- * verified writer, a verified reader, and no producer — which is why the canonical store held zero
- * rows in the project-progression namespace while 378 hand-written `project-state-current` notes
- * accumulated beside it. This module is the producer.
- *
- * EVERY FIELD CARRIES PROVENANCE, and the order of authority is fixed:
- *
- *   ledger             the user's own work ledger — they wrote it, so it wins
- *   owner-note         the newest `project-state-current%` note — the owner's own narrative
- *   prior-head         the previous snapshot: sequence, parent links, carried acceptance
- *   git                branch / HEAD / the three tree digests — mechanical, never inferred
- *   transcript-derived a bounded single-sentence reduction, used ONLY where nothing above spoke
- *
- * Anything derived from the transcript or from repository contents is marked
- * `authoritative: false`. A later session reading this snapshot can then tell the difference between
- * "the user said this" and "we guessed this from the tail of a conversation" — a distinction that
- * disappears the moment provenance is dropped, and whose disappearance is how an inferred goal ends
- * up being obeyed as an instruction.
- *
- * THE PRIVACY BOUNDARY. The user's prompt and the assistant's reply are never persisted. The
- * transcript contributes a REFERENCE (path, byte span, record count, sha256 of the exact bytes read)
- * and at most two derived sentences of DERIVED_TEXT_LIMIT each. redactProgression then runs over the
- * whole snapshot inside createProgressionSnapshot, so secret-shaped material cannot survive even
- * within those bounds.
- */
-import crypto from 'node:crypto';
-import { enrichStateWithObservation } from './project-progression-hook.mjs';
-import fs from 'node:fs';
-import path from 'node:path';
-import { digestCanonical, fieldAuthorityAllows, redactProgression, restoreProjectProgression } from './project-progression-contract.mjs';
-import { readOwnerNote, readSourceIdentity, readTranscriptReference, readWorkLedger } from './project-progression-sources.mjs';
-import { withProgressionReader } from './project-progression-reader.mjs';
-import os from 'node:os';
-import { resolveTurnDb } from './turn-outcome-capture.mjs';
-import { privateProgressionState, maskExcludedPaths } from './turn-capture-privacy.mjs';
-
-const PROGRESSION_NAMESPACE = 'project-progression';
-const OWNER_NOTE_NAMESPACES = Object.freeze(['default']);
-
-/**
- * `none` is not a filler value, it is the honest answer to "where did this come from?" when the
- * answer is "nowhere — no source had one". Labelling an empty goal `git` (as the first version did,
- * simply because git was the last branch in the chain) claims a provenance the field does not have,
- * and provenance that can be wrong is worse than no provenance at all.
- */
-export const PROVENANCE_SOURCES = Object.freeze([
-  'ledger', 'owner-note', 'prior-head', 'git', 'transcript-derived', 'model-checkpoint', 'none',
-]);
-
-const AUTHORITATIVE = Object.freeze({
-  ledger: true,
-  'owner-note': true,
-  'prior-head': true,
-  git: true,
-  'transcript-derived': false,
-  'model-checkpoint': false,
-  none: false,
-});
-
-function marker(source) {
-  if (!PROVENANCE_SOURCES.includes(source)) throw new Error(`unknown provenance source: ${source}`);
-  return { source, authoritative: AUTHORITATIVE[source] };
-}
-
-/**
- * Read the owner's `project-state-current%` notes from the canonical store WITHOUT a CLI spawn.
- * The owner's convention writes them into the project's own namespace and into `default`; both are
- * checked, because which one a given session used depends on whether `-n` was passed.
- */
-function ownerNoteRows(canonicalAgentDbPath, projectNamespace, options = {}) {
-  const namespaces = [...new Set([projectNamespace, ...OWNER_NOTE_NAMESPACES].filter(Boolean))];
-  const result = withProgressionReader(canonicalAgentDbPath, (reader) => {
-    const rows = [];
-    for (const namespace of namespaces) {
-      for (const key of reader.listKeys(namespace)) {
-        if (!key.startsWith('project-state-current')) continue;
-        const content = reader.readContent(namespace, key);
-        if (typeof content === 'string') rows.push({ key, namespace, content });
-      }
-    }
-    return rows;
-  }, options);
-  return result.ok ? result.value : [];
-}
-
-/** The committed heads, computed the same way a restore computes them. Empty store → no heads. */
-function committedHeads(canonicalAgentDbPath, projectIdentity, options = {}) {
-  const result = withProgressionReader(canonicalAgentDbPath, (reader) => {
-    const snapshots = [];
-    for (const key of reader.listKeys(PROGRESSION_NAMESPACE)) {
-      const content = reader.readContent(PROGRESSION_NAMESPACE, key);
-      if (typeof content !== 'string') continue;
-      try { snapshots.push(JSON.parse(content)); } catch { /* a malformed row is the restore's problem */ }
-    }
-    return snapshots;
-  }, options);
-  if (!result.ok) {
-    if (fs.existsSync(canonicalAgentDbPath)) throw new Error(`prior progression read unavailable: ${result.reason}`);
-    return { heads: [], state: null, readPath: `unavailable (${result.reason})` };
-  }
-  const restored = restoreProjectProgression(result.value, { expectedProjectIdentity: projectIdentity });
-  if (result.value.length && !restored.ok) throw new Error('prior progression has no verifiable coherent state');
-  const byKey = new Map(result.value.map((snapshot) => [snapshot?.eventKey, snapshot]));
-  return { heads: restored.heads.map((key) => byKey.get(key)).filter(Boolean), state: restored.state, readPath: 'node:sqlite' };
-}
-
-function uniqueStrings(values) {
-  return [...new Set(values.filter((value) => typeof value === 'string' && value.trim()))];
-}
-
-/**
- * Build the `projectProgression` extension for one host payload.
- *
- * @returns {{ projectProgression: object, provenance: object, skipped?: { reason: string } }}
- *   `skipped` is set when this capture would add nothing: a snapshot whose complete project state
- *   and source identity are byte-identical to the previous head is a no-op, and writing it would let
- *   three capture boundaries per session grow memory.db without bound for sessions that changed
- *   nothing. The caller does not write when `skipped` is present.
- */
-export function buildProjectProgression({
-  resolution,
-  projectDir = resolution?.checkoutRoot,
-  payload = {},
-  host = 'claude',
-  env = process.env,
-  now = () => new Date().toISOString(),
-  trigger = payload.hook_event_name,
-  deadlineAt = Infinity,
-  signal,
-} = {}) {
-  if (!resolution || typeof resolution !== 'object') throw new TypeError('resolution must be a project store resolution');
-  const options = { deadlineAt, signal };
-  const checkDeadline = () => { if (signal?.aborted || Date.now() >= deadlineAt) throw new Error('restore deadline exceeded'); };
-  checkDeadline();
-  const source = readSourceIdentity({ checkoutRoot: resolution.checkoutRoot, kind: resolution.kind, ...options });
-  source.identity.capturePath = fs.realpathSync.native(projectDir);
-  const ledger = readWorkLedger({ projectId: resolution.projectIdentity.id, env });
-  const note = readOwnerNote(() => ownerNoteRows(resolution.canonicalAgentDbPath, path.basename(resolution.projectRoot), options));
-  const transcript = readTranscriptReference(payload.transcript_path, { host });
-  const { heads, state: priorState } = committedHeads(resolution.canonicalAgentDbPath, resolution.projectIdentity, options);
-  checkDeadline();
-
-  const priorSequence = heads.reduce((highest, head) => Math.max(highest, head.sequence ?? 0), 0);
-
-  const provenance = { ...(priorState?.provenance ?? {}) };
-  const record = (field, sourceName) => {
-    if (sourceName !== 'none' && !fieldAuthorityAllows(field === 'sourceIdentity' ? 'sourceIdentity' : field, sourceName)) {
-      throw new Error(`source ${sourceName} is not authoritative for progression field ${field}`);
-    }
-    provenance[field] = sourceName === 'prior-head' && priorState?.provenance?.[field]
-      ? priorState.provenance[field] : marker(sourceName);
-  };
-
-  // GOAL — the ledger's oldest open item is what the user actually committed to. A coherent prior
-  // head carries that commitment forward; an owner note or transcript can provide context only when
-  // no durable goal exists. Neither contextual source is an instruction.
-  let currentGoal = ledger.open[0] ?? null;
-  if (currentGoal) record('currentGoal', 'ledger');
-  else if (priorState) {
-    currentGoal = priorState.currentGoal;
-    record('currentGoal', 'prior-head');
-  } else if (note?.excerpt) {
-    currentGoal = note.excerpt.split('\n')[0].slice(0, 240);
-    record('currentGoal', 'owner-note');
-  } else if (transcript.derivedGoal) {
-    currentGoal = transcript.derivedGoal;
-    record('currentGoal', 'transcript-derived');
-  } else record('currentGoal', 'none');
-
-  // NEXT ACTION — only a ledger commitment or coherent prior state may become a resumable action.
-  // Transcript text is evidence/context, never an invented structured action.
-  let nextAction = ledger.open[1] ?? ledger.open[0] ?? null;
-  if (nextAction) record('nextAction', 'ledger');
-  else if (priorState) {
-    nextAction = priorState.nextAction;
-    record('nextAction', 'prior-head');
-  } else record('nextAction', 'none');
-
-  const decisions = [...(priorState?.decisions ?? [])];
-  if (ledger.objective && typeof ledger.objective.text === 'string' && ledger.objective.text) {
-    decisions.push({ text: ledger.objective.text, state: ledger.objective.state ?? null, source: 'ledger' });
-    record('decisions', 'ledger');
-  } else if (note?.excerpt) {
-    decisions.push({ text: note.excerpt, note: note.key, truncated: note.truncated, source: 'owner-note' });
-    record('decisions', 'owner-note');
-  } else record('decisions', 'prior-head');
-
-  // A partial ledger speaks only for its own matching items; absence is not deletion.
-  const priorPlan = priorState?.plan ?? [];
-  const doneIds = new Set(ledger.done.map((text) => text.slice(0, 64)));
-  const openIds = new Set(ledger.open.map((text) => text.slice(0, 64)));
-  const ownedDone = new Set(priorPlan.filter((item) => item?.source === 'ledger' && doneIds.has(item.id)).map((item) => item.id));
-  const plan = priorPlan.map((item) => item?.source !== 'ledger' ? item
-    : doneIds.has(item.id) ? { ...item, status: 'done' }
-      : openIds.has(item.id) ? { ...item, status: 'open' } : item);
-  for (const text of ledger.open) {
-    const id = text.slice(0, 64);
-    if (!plan.some((item) => item?.source === 'ledger' && item.id === id)) plan.push({ id, status: 'open', source: 'ledger' });
-  }
-  const completed = [...(priorState?.completed ?? [])];
-  for (const text of ledger.done) if (!completed.includes(text)) completed.push(text);
-  const inProgress = uniqueStrings([...(priorState?.inProgress ?? []).filter((text) => !ownedDone.has(text.slice(0, 64))), ...ledger.open]);
-  for (const field of ['plan', 'completed', 'inProgress']) {
-    record(field, ledger.open.length || ledger.done.length ? 'ledger' : 'prior-head');
-    if (priorState && (ledger.open.length || ledger.done.length)) provenance[field] = { source: 'prior-head', authoritative: priorState.provenance?.[field]?.authoritative ?? true, sources: ['prior-head', 'ledger'] };
-  }
-  record('changedFiles', 'git');
-  record('sourceIdentity', 'git');
-
-  // Reducer annotations describe the prior heads, not application state in the new snapshot.
-  const { sourceIdentity: priorSource, journalHeads: priorHeads, ...carriedState } = priorState ?? {};
-  let completeProjectState = {
-    ...carriedState,
-    currentGoal,
-    nextAction,
-    acceptanceContract: priorState?.acceptanceContract ?? null,
-    activeProcess: priorState ? priorState.activeProcess : 'ProjectContinuity',
-    activeStep: priorState ? priorState.activeStep : trigger ?? 'unknown',
-    plan,
-    completed,
-    inProgress,
-    blockers: priorState?.blockers ?? [],
-    failures: priorState?.failures ?? [],
-    decisions: [...new Map(decisions.map((decision) => [digestCanonical(decision), decision])).values()],
-    // Retain previously recorded paths; the new tree's digests never invent additional filenames.
-    changedFiles: priorState?.changedFiles ?? [],
-    commands: priorState?.commands ?? [],
-    proofArtifacts: priorState?.proofArtifacts ?? [],
-    untested: priorState?.untested ?? [],
-    resumeConflicts: priorState?.resumeConflicts ?? [],
-    provenance,
-    evidence: {
-      workLedger: { file: ledger.file, present: ledger.present, open: ledger.open.length, done: ledger.done.length },
-      ownerNote: note ? { key: note.key, excerptSha256: note.excerptSha256, truncated: note.truncated } : null,
-      transcript: transcript.reference ?? { skipped: transcript.skipped },
-      sourceCapture: { headStable: source.headStable, headAfter: source.headAfter ?? source.identity.head, kind: source.kind },
-    },
-  };
-
-  const privacy = resolveTurnDb({ projectDir, brainHome: env.RUVNET_BRAIN_HOME || path.join(env.HOME || os.homedir(), '.cache', 'ruvnet-brain') });
-  // Pure derivation may run before adoption; the capture boundary still refuses an absent store.
-  if (privacy.skipped && !privacy.skipped.startsWith('no project memory db')) return { skipped: { reason: privacy.skipped } };
-  if ([...ledger.open, ...ledger.done].some((text) => maskExcludedPaths(text, privacy.contentPathExcludes, projectDir) !== text)) throw new Error('content exclusion conflicts with immutable work-ledger plan binding');
-  completeProjectState = privateProgressionState(completeProjectState, privacy.contentPathExcludes, projectDir);
-
-  // REDACT HERE, NOT ONLY AT THE STORE.
-  //
-  // createProgressionSnapshot already redacts, so the STORED row was always safe. What was not safe
-  // was everything between: this function's return value is passed through a hook payload, appears
-  // in a receipt, and is exactly the kind of object a diagnostic line prints. A secret that is
-  // scrubbed on the way into the database but readable on the way there has not been protected, it
-  // has been moved. Redacting at the point of derivation makes the store's own pass a no-op second
-  // check rather than the only one (redactProgression is idempotent, so running it twice is free).
-  const { value: redactedProgression } = redactProgression({
-    canonicalAgentDbPath: resolution.canonicalAgentDbPath,
-    sourceIdentity: source.identity,
-    sequence: priorSequence + 1,
-    occurredAt: now(),
-    parentEventKeys: heads.map((head) => head.eventKey),
-    dedupId: `${host}:${payload.session_id ?? 'unknown-session'}:${trigger ?? 'unknown'}:${priorSequence + 1}`,
-    completeProjectState,
-  });
-  const projectProgression = redactedProgression;
-  // Compare the same redacted observation the native writer will append, without returning it
-  // twice. Tool input and terminal evidence must participate before the no-op decision.
-  const observedState = redactProgression(enrichStateWithObservation(
-    projectProgression.completeProjectState, { ...payload, hook_event_name: trigger },
-    { contentPathExcludes: privacy.contentPathExcludes, projectDir },
-  )).value;
-  // A committed sequence is not an event identity: several boundaries may freeze before replay.
-  // Bind all immutable captured fields (including the native observation and occurrence time).
-  projectProgression.dedupId += `:${digestCanonical({
-    ...projectProgression, completeProjectState: observedState,
-  })}`;
-
-  // RETENTION (ADR-073). Three capture boundaries per session times every session is unbounded
-  // growth unless a capture that changes nothing writes nothing. Compare what a snapshot MEANS —
-  // the project state and the tree it describes — while deliberately ignoring the fields that always
-  // differ (sequence, timestamp, dedup id, the trigger that happens to be firing, and the evidence
-  // block's own timestamps), because comparing those would make every capture look novel.
-  const meaning = digestCanonical({
-    state: { ...observedState, activeStep: null, evidence: null },
-    source: projectProgression.sourceIdentity,
-  });
-  const priorMeaning = heads.length === 1 ? digestCanonical({
-    state: { ...carriedState, activeStep: null, evidence: null },
-    source: heads[0].sourceIdentity,
-  }) : null;
-
-  return {
-    projectProgression,
-    provenance,
-    meaningDigest: meaning,
-    // Compaction requires a fresh durable boundary even when application state is unchanged.
-    ...(trigger !== 'PreCompact' && priorMeaning === meaning
-      ? { skipped: { reason: 'no-op capture: project state and source identity are identical to the current head' } }
-      : {}),
-  };
-}
-
-/** Stable identifier for one produced snapshot, for logs and receipts. */
-export function producedDigest(produced) {
-  return crypto.createHash('sha256').update(JSON.stringify(produced.projectProgression)).digest('hex');
-}

package/plugin/scripts/project-progression-reader.mjs

@@ -1,304 +0,0 @@
-/**
- * project-progression-reader.mjs — the READ-ONLY fast path for project continuity restoration.
- *
- * WHY THIS EXISTS (measured, not supposed). `restoreProgressionForSession` gives the whole restore
- * SESSION_CONTINUITY_DEADLINE_MS = 2500ms, and every read it performs is a separate `ruflo memory`
- * PROCESS. Measured on this machine (ruflo 3.41.2, Node v24.18.0, warm Transformers cache), in an
- * isolated temp git repo, with `plugin/scripts/project-progression-session-start.mjs` unchanged:
- *
- *     1 snapshot  → restore 923 / 952 / 1001 ms   → "PROJECT CONTINUITY RESTORED"
- *     6 snapshots → restore 2519 / 2530 / 3181 ms → "PROJECT CONTINUITY UNKNOWN" (restore-failed)
- *
- * The cost is O(N) PROCESS SPAWNS: one `memory list` plus one `memory retrieve` per snapshot, each
- * ~400ms of Node + CLI boot. So continuity does not fail loudly on day one — it decays silently as
- * the journal grows, and the seventh checkpoint is the one that switches a project's memory off.
- * A grep of the installed CLI (memory/memory-initializer.js, commands/memory.js, memory/memory-bridge.js)
- * found exactly three memory env switches — CLAUDE_FLOW_DB_PATH, CLAUDE_FLOW_DISABLE_BRIDGE,
- * CLAUDE_FLOW_MEMORY_PATH (plus RUFLO_MEMORY_SCAN_ON_WRITE) — and none of them skips CLI boot, so
- * there is no flag to reach for. The per-call floor stays ~400ms however it is invoked.
- *
- * WHAT THIS DOES. Node 24 ships `node:sqlite`, so the same rows can be read in-process, read-only,
- * in about a millisecond. `~/.claude/hooks/agentdb-ensure.sh` already reads this exact file directly
- * with `sqlite3`, so direct reads of memory.db are the established precedent, not a new liberty.
- *
- * WHAT THIS DELIBERATELY DOES NOT DO. It never writes. `ruflo memory store` remains the ONLY writer
- * of memory.db (upstream #2786/#3155/#3196 keep memory.db and agentdb-memory.db separate on purpose;
- * a second writer is exactly the two-writers-one-path footgun the memory policy exists to stop). It
- * is also strictly a FALLBACK-ABLE optimisation: any reason it cannot answer authoritatively —
- * no node:sqlite, absent file, an encrypted image (CLAUDE_FLOW_ENCRYPT_AT_REST writes an "RFE1"
- * blob, not a SQLite file), a WAL sidecar it cannot open read-only, a schema that is not this one —
- * raises ProgressionReaderUnavailable, and the caller replays the whole operation through the CLI.
- *
- * Reading directly also AVOIDS a hazard the CLI has: `getEntry` bumps access_count and then rewrites
- * the WHOLE database image (memory-initializer.js:3070-3077). Every "read" during a restore is
- * therefore a full-image write under a lock. This path takes no lock and mutates nothing.
- *
- * STRUCTURAL GUARANTEES ARE UNCHANGED, because they are the point of the restore and not negotiable:
- *   • COMPLETE ENUMERATION — one statement returns every active row in the namespace; a count past
- *     the caller's bound is an error, never a silent truncation (the CLI path's own failure mode).
- *   • EXACT KEY/PAYLOAD IDENTITY — rows are fetched by (namespace, key); two active rows sharing one
- *     key is a structural error, not a LIMIT-1 coin toss.
- *   • DIGEST VERIFICATION — untouched: the caller still validates payloadDigest on every snapshot.
- */
-import fs from 'node:fs';
-import { loadNodeSqlite } from './node-sqlite.mjs';
-
-/** Installed Ruflo live-memory-row.js visibility; bind current time on every read. */
-const ACTIVE_ROW_SQL = "(status = 'active' OR status IS NULL) AND (expires_at IS NULL OR expires_at > ?)";
-
-/**
- * Every SQLite database file begins with this 16-byte header (sqlite.org/fileformat.html §1.3):
- * the ASCII text "SQLite format 3" followed by one NUL. Built from bytes rather than written as a
- * string escape so no editor, patch tool, or copy-paste can silently turn that NUL into a space —
- * which would make the header never match and quietly disable this whole fast path.
- */
-const SQLITE_HEADER = Buffer.concat([Buffer.from('SQLite format 3', 'latin1'), Buffer.of(0)]);
-
-/**
- * Raised when this reader cannot answer AUTHORITATIVELY. It is never a verdict about the data — it
- * means "ask the CLI instead". A structural violation of the guarantees above throws a plain Error,
- * which must propagate: downgrading "two rows claim one key" to a CLI retry would convert a
- * detectable corruption into a silent, successful, wrong restore.
- */
-export class ProgressionReaderUnavailable extends Error {
-  constructor(reason) {
-    super(`canonical progression reader unavailable: ${reason}`);
-    this.name = 'ProgressionReaderUnavailable';
-    this.reason = reason;
-  }
-}
-
-/**
- * THE PINNED SCHEMA FINGERPRINT — captured from the REAL canonical store on this machine
- * (ruflo 3.41.2, a real project's own <project>/.swarm/memory.db), not transcribed from source:
- *
- *     PRAGMA user_version                -> 0
- *     PRAGMA table_info(memory_entries)  -> the 18 columns below
- *
- * WHY PIN IT. Reading someone else's table is only safe while it is the table you measured. If a
- * later ruflo renames `content`, adds a second liveness column, or partitions rows, a reader that
- * merely SELECTs would answer confidently and WRONGLY — and the wrong answer here is "this project
- * has no history", which is indistinguishable from a fresh project. So a fingerprint mismatch is not
- * an error: it is this module standing down so the CLI, which OWNS the schema, answers instead.
- * Slower is a cost. Silently empty is a lie.
- */
-const SCHEMA_FINGERPRINT = Object.freeze({
-  userVersion: 0,
-  columns: Object.freeze([
-    'access_count', 'content', 'created_at', 'embedding', 'embedding_dimensions', 'embedding_model',
-    'expires_at', 'id', 'key', 'last_accessed_at', 'metadata', 'namespace', 'owner_id',
-    'provenance_type', 'status', 'tags', 'type', 'updated_at',
-  ]),
-});
-
-// The current managed store on the host also carries `session_id` on memory_entries, although the
-// installed Ruflo memory_entries DDL does not declare it. This reader has no reason to attribute
-// that column to Ruflo: it is an observed local compatibility shape only. It is safe for this
-// projection because the reader never selects or interprets it; every required column must still
-// match, and every other addition remains a hard fallback to the managed CLI.
-const OBSERVED_COMPATIBILITY_COLUMNS = Object.freeze(['session_id']);
-
-/** The fingerprint this module requires, so the doctor and tests can name it exactly. */
-export function expectedSchemaFingerprint() {
-  return { userVersion: SCHEMA_FINGERPRINT.userVersion, columns: [...SCHEMA_FINGERPRINT.columns] };
-}
-
-function assertSchemaFingerprint(database) {
-  let columns;
-  let userVersion;
-  try {
-    columns = database.prepare('PRAGMA table_info(memory_entries)').all().map((row) => String(row.name)).sort();
-    userVersion = database.prepare('PRAGMA user_version').get()?.user_version;
-  } catch (error) {
-    throw new ProgressionReaderUnavailable(`schema mismatch: ${error.message}`);
-  }
-  if (columns.length === 0) throw new ProgressionReaderUnavailable('schema mismatch: memory_entries is absent');
-  if (userVersion !== SCHEMA_FINGERPRINT.userVersion) {
-    throw new ProgressionReaderUnavailable(
-      `schema fingerprint mismatch: user_version ${userVersion} is not ${SCHEMA_FINGERPRINT.userVersion}`);
-  }
-  const required = SCHEMA_FINGERPRINT.columns;
-  const compatibleObservedShape = columns.length === required.length + 1
-    && OBSERVED_COMPATIBILITY_COLUMNS.every((name) => columns.includes(name))
-    && required.every((name) => columns.includes(name));
-  if (columns.join(',') !== required.join(',') && !compatibleObservedShape) {
-    const missing = SCHEMA_FINGERPRINT.columns.filter((name) => !columns.includes(name));
-    const added = columns.filter((name) => !SCHEMA_FINGERPRINT.columns.includes(name));
-    throw new ProgressionReaderUnavailable('schema fingerprint mismatch: memory_entries columns differ'
-      + `${missing.length ? ` (missing ${missing.join('/')})` : ''}`
-      + `${added.length ? ` (unexpected ${added.join('/')})` : ''}`);
-  }
-}
-
-let sqliteBinding;
-function databaseSync() {
-  if (sqliteBinding === undefined) {
-    try {
-      // node-sqlite.mjs: loaded on first real use and without Node 22's SQLite ExperimentalWarning,
-      // which otherwise lands in every SessionStart hook's output.
-      sqliteBinding = loadNodeSqlite()?.DatabaseSync ?? null;
-    } catch { sqliteBinding = null; }
-  }
-  return sqliteBinding;
-}
-
-/** True when this Node build exposes node:sqlite at all. Exported for diagnostics and tests. */
-export function canonicalReaderSupported() {
-  return typeof databaseSync() === 'function';
-}
-
-function looksLikeSqliteFile(dbPath) {
-  let handle;
-  try {
-    handle = fs.openSync(dbPath, 'r');
-  } catch {
-    return false;
-  }
-  try {
-    const head = Buffer.alloc(SQLITE_HEADER.length);
-    const read = fs.readSync(handle, head, 0, head.length, 0);
-    return read === head.length && head.equals(SQLITE_HEADER);
-  } catch {
-    return false;
-  } finally {
-    fs.closeSync(handle);
-  }
-}
-
-function requireKey(value) {
-  if (typeof value !== 'string' || !value) throw new Error('malformed progression row: missing key');
-  return value;
-}
-
-/**
- * Open a read-only view of one canonical memory.db.
- *
- * @returns {{ listKeys: Function, readContent: Function, close: Function }}
- * @throws {ProgressionReaderUnavailable} when the CLI must be used instead.
- */
-export function openProgressionReader(dbPath, { deadlineAt = Infinity, signal } = {}) {
-  const checkDeadline = () => { if (signal?.aborted || Date.now() >= deadlineAt) throw new Error('restore deadline exceeded'); };
-  checkDeadline();
-  const DatabaseSync = databaseSync();
-  if (typeof DatabaseSync !== 'function') throw new ProgressionReaderUnavailable('node:sqlite is unavailable');
-  if (typeof dbPath !== 'string' || !dbPath) throw new ProgressionReaderUnavailable('no canonical store path');
-  let stat;
-  try { stat = fs.statSync(dbPath); } catch { throw new ProgressionReaderUnavailable('canonical store does not exist'); }
-  if (!stat.isFile()) throw new ProgressionReaderUnavailable('canonical store is not a regular file');
-  // An encrypted image (CLAUDE_FLOW_ENCRYPT_AT_REST) starts with the vault's "RFE1" magic, so the
-  // header check covers encryption, truncation and any other non-SQLite blob in one test — before
-  // node:sqlite gets a chance to report the generic "file is not a database".
-  if (!looksLikeSqliteFile(dbPath)) throw new ProgressionReaderUnavailable('canonical store is not a plain SQLite image');
-
-  let database;
-  try {
-    database = new DatabaseSync(dbPath, { readOnly: true });
-  } catch (error) {
-    throw new ProgressionReaderUnavailable(`read-only open failed: ${error.message}`);
-  }
-
-  try {
-    assertSchemaFingerprint(database);
-  } catch (error) {
-    try { database.close(); } catch { /* the fingerprint verdict is the news */ }
-    throw error;
-  }
-
-  const prepare = (sql) => {
-    try { return database.prepare(sql); } catch (error) {
-      throw new ProgressionReaderUnavailable(`schema mismatch: ${error.message}`);
-    }
-  };
-  let listStatement;
-  let readStatement;
-  let allStatement;
-  try {
-    // Prepared eagerly so an unexpected schema (or a WAL image this process cannot read) is
-    // reported as UNAVAILABLE now, before the caller has committed to the fast path.
-    listStatement = prepare(`SELECT key FROM memory_entries WHERE ${ACTIVE_ROW_SQL} AND namespace = ? ORDER BY key`);
-    readStatement = prepare(`SELECT content FROM memory_entries WHERE ${ACTIVE_ROW_SQL} AND namespace = ? AND key = ?`);
-    allStatement = prepare(`SELECT namespace, key, content FROM memory_entries WHERE ${ACTIVE_ROW_SQL} ORDER BY namespace, key`);
-  } catch (error) {
-    try { database.close(); } catch { /* the open failure is the news */ }
-    throw error;
-  }
-
-  const query = (statement, params) => {
-    try { return statement.all(Date.now(), ...params); } catch (error) {
-      throw new ProgressionReaderUnavailable(`read failed: ${error.message}`);
-    }
-  };
-
-  return {
-    /** Every active key in `namespace`, sorted, deduplicated-by-error, bounded. */
-    listKeys(namespace, { maxEntries = 10_000 } = {}) {
-      checkDeadline();
-      if (!Number.isSafeInteger(maxEntries) || maxEntries < 1) throw new TypeError('maxEntries must be a positive safe integer');
-      let rows = [];
-      if (Number.isFinite(deadlineAt) || signal) {
-        for (const row of listStatement.iterate(Date.now(), namespace)) {
-          checkDeadline(); rows.push(row);
-          if (rows.length > maxEntries) throw new Error('progression enumeration exceeds its bound');
-        }
-      } else rows = query(listStatement, [namespace]);
-      if (rows.length > maxEntries) throw new Error('progression enumeration exceeds its bound');
-      const keys = [];
-      const seen = new Set();
-      for (const row of rows) {
-        const key = requireKey(row?.key);
-        if (seen.has(key)) throw new Error(`duplicate progression key in store: ${key}`);
-        seen.add(key);
-        keys.push(key);
-      }
-      return keys;
-    },
-
-    /** The exact stored value for one (namespace, key), or null when that row does not exist. */
-    readContent(namespace, key) {
-      checkDeadline();
-      requireKey(key);
-      const rows = query(readStatement, [namespace, key]);
-      if (rows.length === 0) return null;
-      if (rows.length > 1) throw new Error(`duplicate progression key in store: ${key}`);
-      const content = rows[0]?.content;
-      // A non-text column is not this schema; fall back rather than guess at an encoding.
-      if (typeof content !== 'string') throw new ProgressionReaderUnavailable('progression row content is not text');
-      return content;
-    },
-
-    /** Every active (namespace, key, content) row — bounded, never truncated (past the bound is an error). */
-    allRows({ maxRows = 100_000 } = {}) {
-      const rows = query(allStatement, []);
-      if (rows.length > maxRows) throw new ProgressionReaderUnavailable(`store holds more than ${maxRows} active rows`);
-      return rows.map((row) => ({ namespace: String(row.namespace ?? ''), key: String(row.key ?? ''),
-        content: typeof row.content === 'string' ? row.content : null }));
-    },
-
-    close() {
-      try { database.close(); } catch { /* closing a spent read handle is never news */ }
-    },
-  };
-}
-
-/**
- * Run `work(reader)` against a read-only view, closing it afterwards.
- * Returns `{ ok: true, value }`, or `{ ok: false, reason }` when the CLI must be used instead.
- * Structural errors are NOT converted — they propagate, by design (see ProgressionReaderUnavailable).
- */
-export function withProgressionReader(dbPath, work, options = {}) {
-  let reader;
-  try {
-    reader = openProgressionReader(dbPath, options);
-  } catch (error) {
-    if (error instanceof ProgressionReaderUnavailable) return { ok: false, reason: error.reason };
-    throw error;
-  }
-  try {
-    return { ok: true, value: work(reader) };
-  } catch (error) {
-    if (error instanceof ProgressionReaderUnavailable) return { ok: false, reason: error.reason };
-    throw error;
-  } finally {
-    reader.close();
-  }
-}