ruvnet-brain 4.3.20 → 4.3.25

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

@@ -0,0 +1,271 @@
+/**
+ * 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 { createRequire } from 'node:module';
+
+/** Rows that `ruflo memory` itself considers live (memory-initializer.js ACTIVE_MEMORY_ROW_SQL). */
+const ACTIVE_ROW_SQL = "(status = 'active' OR status IS NULL)";
+
+/**
+ * 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 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}`);
+  }
+  if (columns.join(',') !== SCHEMA_FINGERPRINT.columns.join(',')) {
+    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 {
+      sqliteBinding = createRequire(import.meta.url)('node:sqlite').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) {
+  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;
+  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 = ?`);
+  } catch (error) {
+    try { database.close(); } catch { /* the open failure is the news */ }
+    throw error;
+  }
+
+  const query = (statement, params) => {
+    try { return statement.all(...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 } = {}) {
+      if (!Number.isSafeInteger(maxEntries) || maxEntries < 1) throw new TypeError('maxEntries must be a positive safe integer');
+      const 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) {
+      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;
+    },
+
+    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) {
+  let reader;
+  try {
+    reader = openProgressionReader(dbPath);
+  } 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();
+  }
+}

package/plugin/scripts/project-progression-session-start.mjs

@@ -3,6 +3,9 @@ import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { ProjectProgressionStore } from './project-progression-store.mjs';
 import { resolveProjectStore } from './project-store-resolver.mjs';
+import { withProgressionReader } from './project-progression-reader.mjs';
+
+const PROGRESSION_NAMESPACE = 'project-progression';
 
 export const SESSION_CONTINUITY_LIMIT_BYTES = 8 * 1024;
 export const SESSION_CONTINUITY_DEADLINE_MS = 2_500;
@@ -21,17 +24,56 @@ const UNKNOWN_EXPLANATIONS = Object.freeze({
   'output-bound': 'The verified resume payload exceeds the host context bound.',
   'no-coherent-state': 'No coherent progression head survived validation.',
   'restore-failed': 'The exact structural restore did not complete.',
+  // MEASURED, and named rather than hidden. The in-process read path costs ~15ms for six snapshots;
+  // the `ruflo memory` CLI fallback costs 3634ms for the same six and does NOT fit the 2500ms
+  // restore deadline. Both produce an identical result, so this is a SPEED limit, not a correctness
+  // one — but a user whose store is encrypted, or whose Node lacks node:sqlite, will lose continuity
+  // past a handful of snapshots, and they deserve to be told which of the two it was.
+  'fallback-too-slow': 'The in-process read path was unavailable, and the managed Ruflo CLI fallback'
+    + ' could not finish inside the restore deadline.',
 });
 
-function unknown(reason) {
+/**
+ * UNKNOWN IS NOT NEUTRAL WHEN THERE WAS SOMETHING TO FIND.
+ *
+ * "I could not read your store" and "your store is empty" render almost identically to a reader, and
+ * the first is a FAILURE: verified progression exists on disk and the session is about to proceed
+ * without it. So when the canonical store exists and holds progression rows, the banner says so in
+ * as many words and the result carries `severity: 'error'` for any surface that colours its output.
+ * When we cannot even count the rows, the severity stays 'warning' — claiming a failure we cannot
+ * evidence would be the same sin one step over.
+ */
+function unknown(reason, { rowCount = null } = {}) {
   const explanation = UNKNOWN_EXPLANATIONS[reason] ?? UNKNOWN_EXPLANATIONS['restore-failed'];
+  const failing = Number.isInteger(rowCount) && rowCount > 0;
+  const header = failing ? `${UNKNOWN_HEADER} — RESTORE FAILED` : UNKNOWN_HEADER;
+  const evidence = failing
+    ? ` ${rowCount} verified progression row(s) are present in the canonical store and could NOT be restored;`
+      + ' treat this as a failure to recover known state, not as a project without history.'
+    : '';
   return {
     status: 'unknown',
     reason,
-    context: `${UNKNOWN_HEADER}\n${explanation} Do not claim project state was restored; verify the canonical store before relying on remembered state.`,
+    severity: failing ? 'error' : 'warning',
+    rowCount,
+    context: `${header}\n${explanation}${evidence}`
+      + ' Do not claim project state was restored; verify the canonical store before relying on remembered state.',
   };
 }
 
+/**
+ * Count committed progression rows WITHOUT paying for a restore. Used only to decide how loudly an
+ * UNKNOWN should speak, so it never throws and never falls back to a CLI spawn: a count we cannot
+ * take cheaply is reported as null ("cannot tell"), which downgrades the banner rather than the run.
+ */
+function committedRowCount(canonicalAgentDbPath) {
+  try {
+    const result = withProgressionReader(canonicalAgentDbPath,
+      (reader) => reader.listKeys(PROGRESSION_NAMESPACE).length);
+    return result.ok ? result.value : null;
+  } catch { return null; }
+}
+
 function classify(error) {
   const message = String(error?.message ?? error ?? '');
   if (/ruflo was not found|managed global ruflo/i.test(message)) return 'managed-ruflo-unavailable';
@@ -95,16 +137,33 @@ function initializeCanonicalStore(store, resolution) {
   }
 }
 
+/**
+ * One line, only when there is something to say. Durable-but-uncommitted snapshots are evidence the
+ * session must know about: they will be committed at the next capture boundary, and until then the
+ * restored head is not the newest thing that happened.
+ */
+function pendingNotice(pendingReplay) {
+  if (!Number.isInteger(pendingReplay) || pendingReplay < 1) return '';
+  return `\n${pendingReplay} uncommitted snapshot(s) pending replay; they commit at the next capture`
+    + ' boundary (Stop / PreCompact / SessionEnd) or when you run /ruvnet-brain:checkpoint.';
+}
+
 function isProject(resolution) {
   if (resolution.kind === 'git') return true;
   return ['.swarm', '.claude-flow', 'package.json', 'pyproject.toml', 'Cargo.toml', 'go.mod']
     .some((name) => fs.existsSync(path.join(resolution.projectRoot, name)));
 }
 
-function availableContext(reason) {
+/**
+ * ADR-073 §6 — continuity-unavailable. A directory that is not a writable adopted project has no
+ * continuity to restore and no store to blame, so this is neither a success nor a failure: it is the
+ * absence of the question. Distinct from `unknown`, which means the question was asked and missed.
+ */
+function unavailable(reason) {
   return {
     status: 'unavailable',
     reason,
+    severity: 'info',
     context: '[RuvNet Brain — PROJECT CONTINUITY UNAVAILABLE]\n'
       + 'This working directory is not a writable adopted project. No AgentDB store was created and no project state was restored.',
   };
@@ -132,14 +191,17 @@ export function restoreProgressionForSession({
     return unknown('canonical-path');
   }
 
-  if (!isProject(resolution)) return availableContext('non-project');
-  if (!writable(resolution.projectRoot)) return availableContext('read-only');
+  if (!isProject(resolution)) return unavailable('non-project');
+  if (!writable(resolution.projectRoot)) return unavailable('read-only');
   const initializing = !fs.existsSync(resolution.canonicalAgentDbPath);
+  const rowCount = initializing ? 0 : committedRowCount(resolution.canonicalAgentDbPath);
+  const miss = (reason) => unknown(reason, { rowCount });
 
   const prefix = `${RESTORED_HEADER}\n`;
   const payloadLimit = maxOutputBytes - Buffer.byteLength(prefix, 'utf8');
-  if (!Number.isSafeInteger(payloadLimit) || payloadLimit < 1) return unknown('output-bound');
+  if (!Number.isSafeInteger(payloadLimit) || payloadLimit < 1) return miss('output-bound');
 
+  let store;
   try {
     const deadlineAt = Date.now() + deadlineMs;
     const boundedRunner = (binary, args, options) => {
@@ -153,7 +215,7 @@ export function restoreProgressionForSession({
       ...options,
       runner: boundedRunner,
     }));
-    const store = makeStore({
+    store = makeStore({
       projectDir,
       requestedStorePath: resolution.canonicalAgentDbPath,
     });
@@ -161,23 +223,38 @@ export function restoreProgressionForSession({
       fs.mkdirSync(path.dirname(resolution.canonicalAgentDbPath), { recursive: true, mode: 0o700 });
       initializeCanonicalStore(store, resolution);
     }
-    const restored = store.restoreLatest({ maxOutputBytes: payloadLimit });
-    if (!validResume(restored)) return unknown('malformed-store');
-    const context = `${prefix}${restored.rendered}`;
-    if (Buffer.byteLength(context, 'utf8') > maxOutputBytes) return unknown('output-bound');
-    return { status: 'restored', context };
+    // COMMITTED ROWS ONLY (ADR-073 §5). Replay is a write, a write is a `ruflo memory store`
+    // process, and one of those costs more than this entire boundary's budget. Pending durable
+    // snapshots are REPORTED below and replayed at the next capture boundary or by /checkpoint.
+    const restored = store.restoreLatest({ maxOutputBytes: payloadLimit, replayPending: false });
+    if (!validResume(restored)) return miss('malformed-store');
+    const context = `${prefix}${restored.rendered}${pendingNotice(restored.pendingReplay)}`;
+    if (Buffer.byteLength(context, 'utf8') > maxOutputBytes) return miss('output-bound');
+    return { status: 'restored', severity: 'info', pendingReplay: restored.pendingReplay, context };
   } catch (error) {
     // A structurally enumerated, genuinely empty namespace is normal for a newly adopted project.
     if (/no coherent progression state/i.test(String(error?.message ?? ''))
       && Array.isArray(error?.rejectedCandidates) && error.rejectedCandidates.length === 0) {
-      if (initializing && !fs.existsSync(resolution.canonicalAgentDbPath)) return unknown('initialization-failed');
+      if (initializing && !fs.existsSync(resolution.canonicalAgentDbPath)) return miss('initialization-failed');
+      const pending = pendingNotice(error?.pendingReplay);
       return {
         status: initializing ? 'initialized' : 'empty',
-        context: initializing
+        severity: 'info',
+        pendingReplay: error?.pendingReplay ?? 0,
+        context: (initializing
           ? '[RuvNet Brain — PROJECT CONTINUITY INITIALIZED]\nThe canonical AgentDB store is ready; no prior progression snapshot exists yet.'
-          : '[RuvNet Brain — PROJECT CONTINUITY EMPTY]\nThe canonical AgentDB store was structurally enumerated and contains no prior progression snapshot.',
+          : '[RuvNet Brain — PROJECT CONTINUITY EMPTY]\nThe canonical AgentDB store was structurally enumerated and contains no prior progression snapshot.')
+          + pending,
       };
     }
-    return unknown(classify(error));
+    // NAME WHICH PATH RAN OUT OF TIME. "restore-failed" over a store full of rows tells the user
+    // nothing they can act on; "the fast path was unavailable because <reason>, and the CLI fallback
+    // is too slow for this deadline" tells them exactly what to fix.
+    const readPath = typeof store?.lastReadPath === 'string' ? store.lastReadPath : '';
+    if (/deadline exceeded/i.test(String(error?.message ?? '')) && readPath.startsWith('ruflo-cli')) {
+      const missed = miss('fallback-too-slow');
+      return { ...missed, context: `${missed.context} Read path: ${readPath}.` };
+    }
+    return miss(classify(error));
   }
 }

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

@@ -0,0 +1,220 @@
+/**
+ * project-progression-sources.mjs — where a snapshot's facts actually come from.
+ *
+ * Every field a capture stores must be traceable to a REAL source: the git index, the user's own
+ * work ledger, the owner's own `project-state-current` note, the previous snapshot head, or a
+ * bounded transcript reference. Nothing here invents state, and nothing here copies the
+ * conversation: the transcript contributes a REFERENCE (path + line/byte span + a sha256 of the
+ * exact excerpt read) plus tightly-bounded DERIVED strings, never the prompt or the reply itself.
+ *
+ * Kept separate from the producer so each file stays small and so the readers can be tested against
+ * real fixtures without constructing a whole snapshot.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+/** The transcript-derived bound. Deliberately far below the hook's 4096-byte observation limit. */
+export const DERIVED_TEXT_LIMIT = 240;
+/** How much of a transcript tail may be READ (never stored) to derive those bounded strings. */
+export const TRANSCRIPT_TAIL_BYTES = 256 * 1024;
+
+const sha256 = (value) => crypto.createHash('sha256').update(value).digest('hex');
+
+/** A stable digest for "there is genuinely nothing to digest here", never an empty string. */
+const ABSENT_DIGEST = sha256('ruvnet-brain:absent');
+
+function git(cwd, args) {
+  try {
+    return execFileSync('git', args, {
+      cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 64 * 1024 * 1024,
+    });
+  } catch { return null; }
+}
+
+/**
+ * The source identity, with each digest defined EXACTLY:
+ *   trackedDigest   sha256 of `git ls-files -s` (mode + blob oid + stage + path for every tracked file)
+ *   untrackedDigest sha256 of one `<content-sha256> <path>` line per untracked, non-ignored file —
+ *                   the NAMES alone would call two different working trees identical
+ *   dirtyTreeDigest sha256 of `git diff HEAD` (staged AND unstaged, against the commit)
+ *
+ * KNOWN RACE, recorded rather than pretended away: the working tree can change while these three
+ * commands run. HEAD is read before and after; when they differ, `headStable` is false and the
+ * digests describe a tree that existed at no single instant. A capture still happens — a slightly
+ * smeared snapshot is worth far more than no snapshot — but it never claims to be atomic.
+ */
+export function readSourceIdentity({ checkoutRoot, kind = 'git' } = {}) {
+  const worktreeId = sha256(checkoutRoot);
+  if (kind !== 'git') {
+    // A non-git project has no index, no HEAD and no diff. Say that in the fields rather than
+    // fabricating hashes of nothing, and keep every value a non-empty string as the contract requires.
+    return {
+      identity: {
+        checkoutPath: checkoutRoot, worktreeId, branch: 'non-git', head: 'non-git',
+        trackedDigest: ABSENT_DIGEST, untrackedDigest: ABSENT_DIGEST, dirtyTreeDigest: ABSENT_DIGEST,
+      },
+      headStable: true,
+      kind,
+    };
+  }
+
+  const headBefore = git(checkoutRoot, ['rev-parse', 'HEAD'])?.trim() || 'unborn';
+  const branch = git(checkoutRoot, ['rev-parse', '--abbrev-ref', 'HEAD'])?.trim() || 'detached';
+  const tracked = git(checkoutRoot, ['ls-files', '-s']);
+  const untrackedList = git(checkoutRoot, ['ls-files', '--others', '--exclude-standard']);
+  const diff = git(checkoutRoot, ['diff', 'HEAD']);
+  const headAfter = git(checkoutRoot, ['rev-parse', 'HEAD'])?.trim() || 'unborn';
+
+  const untrackedLines = String(untrackedList ?? '').split('\n').filter(Boolean).map((relative) => {
+    let content;
+    try { content = fs.readFileSync(path.join(checkoutRoot, relative)); } catch { return `unreadable ${relative}`; }
+    return `${sha256(content)} ${relative}`;
+  });
+
+  return {
+    identity: {
+      checkoutPath: checkoutRoot,
+      worktreeId,
+      branch,
+      head: headBefore,
+      trackedDigest: tracked === null ? ABSENT_DIGEST : sha256(tracked),
+      untrackedDigest: untrackedList === null ? ABSENT_DIGEST : sha256(untrackedLines.join('\n')),
+      dirtyTreeDigest: diff === null ? ABSENT_DIGEST : sha256(diff),
+    },
+    headStable: headBefore === headAfter,
+    headAfter,
+    kind,
+  };
+}
+
+/**
+ * The user's own work ledger, read-only, resolved exactly as continuation-gate.mjs resolves it:
+ * RUVNET_WORK_LEDGER, else ~/.config/ruvnet-brain/work-ledgers/<projectId with ':' → '-'>.json.
+ * This is the AUTHORITATIVE source for open work, because the user put it there.
+ */
+export function readWorkLedger({ projectId, env = process.env, home = os.homedir() } = {}) {
+  const file = env.RUVNET_WORK_LEDGER
+    || path.join(home, '.config', 'ruvnet-brain', 'work-ledgers', `${String(projectId).replace(':', '-')}.json`);
+  let parsed;
+  try { parsed = JSON.parse(fs.readFileSync(file, 'utf8')); } catch {
+    return { file, present: false, open: [], done: [], objective: null };
+  }
+  const items = Array.isArray(parsed?.items) ? parsed.items : [];
+  const text = (item) => (typeof item?.text === 'string' ? item.text : '');
+  return {
+    file,
+    present: true,
+    open: items.filter((item) => item && !item.done).map(text).filter(Boolean),
+    done: items.filter((item) => item?.done).map(text).filter(Boolean),
+    objective: parsed?.objective && typeof parsed.objective === 'object' ? parsed.objective : null,
+  };
+}
+
+/**
+ * The owner's own convention: append-only `project-state-current-<epochms>[-slug]` free-text notes.
+ * 378 of them exist in this repo's canonical store. They are narrative, not schema, so only the head
+ * of the newest one is carried, as CONTEXT — never as an instruction and never as authority.
+ */
+export function readOwnerNote(readRows, { limit = 600 } = {}) {
+  let rows;
+  try { rows = readRows(); } catch { return null; }
+  if (!Array.isArray(rows) || rows.length === 0) return null;
+  const newest = rows
+    .filter((row) => typeof row?.key === 'string' && row.key.startsWith('project-state-current'))
+    .sort((left, right) => String(left.key).localeCompare(String(right.key)))
+    .at(-1);
+  if (!newest || typeof newest.content !== 'string' || !newest.content.trim()) return null;
+  const excerpt = newest.content.slice(0, limit);
+  return {
+    key: newest.key,
+    namespace: newest.namespace ?? null,
+    excerpt,
+    truncated: newest.content.length > limit,
+    excerptSha256: sha256(excerpt),
+  };
+}
+
+function firstSentence(value) {
+  const collapsed = String(value).replace(/\s+/g, ' ').trim();
+  if (!collapsed) return '';
+  const stop = collapsed.search(/[.!?](\s|$)/);
+  const sentence = stop > 0 ? collapsed.slice(0, stop + 1) : collapsed;
+  return sentence.length <= DERIVED_TEXT_LIMIT ? sentence : `${sentence.slice(0, DERIVED_TEXT_LIMIT)}…`;
+}
+
+function claudeTranscriptRows(text) {
+  const rows = [];
+  const lines = text.split('\n');
+  // The first line of a mid-file tail is almost always a fragment; dropping it is correct, not lossy.
+  for (const line of lines.slice(1)) {
+    if (!line.trim()) continue;
+    try { rows.push(JSON.parse(line)); } catch { /* a partial line in a live-appended file */ }
+  }
+  return rows;
+}
+
+function textOf(message) {
+  if (typeof message?.content === 'string') return message.content;
+  if (!Array.isArray(message?.content)) return '';
+  return message.content.filter((block) => block?.type === 'text' && typeof block.text === 'string')
+    .map((block) => block.text).join('\n');
+}
+
+/**
+ * A BOUNDED, NON-VERBATIM reading of the transcript tail.
+ *
+ * THE PRIVACY BOUNDARY, stated as a rule rather than a hope: the prompt and the assistant's reply
+ * are READ here and are NEVER RETURNED. What comes back is a REFERENCE (path, line span, byte span,
+ * and the sha256 of the exact bytes read, so an auditor can prove what was consulted) plus at most
+ * two DERIVED single sentences, each capped at DERIVED_TEXT_LIMIT. Anything inferred this way is
+ * marked non-authoritative by the producer; the ledger and the owner's note outrank it always.
+ *
+ * Unknown or unreadable formats return `skipped` with a reason. A host whose transcript we cannot
+ * parse must cost the capture nothing at all.
+ */
+export function readTranscriptReference(transcriptPath, { host = 'claude', tailBytes = TRANSCRIPT_TAIL_BYTES } = {}) {
+  if (typeof transcriptPath !== 'string' || !transcriptPath) {
+    return { skipped: 'no transcript path supplied' };
+  }
+  if (host !== 'claude') return { skipped: `transcript format unknown for host ${host}` };
+  let stat;
+  try { stat = fs.statSync(transcriptPath); } catch { return { skipped: 'transcript is unreadable' }; }
+  if (!stat.isFile() || stat.size === 0) return { skipped: 'transcript is empty or not a file' };
+  if (!/\.jsonl$/i.test(transcriptPath)) return { skipped: 'transcript is not a JSONL transcript' };
+
+  const byteOffset = Math.max(0, stat.size - tailBytes);
+  const byteLength = stat.size - byteOffset;
+  let buffer;
+  try {
+    const handle = fs.openSync(transcriptPath, 'r');
+    try {
+      buffer = Buffer.alloc(byteLength);
+      fs.readSync(handle, buffer, 0, byteLength, byteOffset);
+    } finally { fs.closeSync(handle); }
+  } catch { return { skipped: 'transcript tail could not be read' }; }
+
+  const rows = claudeTranscriptRows(buffer.toString('utf8'));
+  if (rows.length === 0) return { skipped: 'transcript tail contained no parseable records' };
+  const lastUser = [...rows].reverse()
+    .find((row) => row?.type === 'user' && row.message?.role === 'user' && textOf(row.message).trim());
+  const lastAssistant = [...rows].reverse()
+    .find((row) => row?.type === 'assistant' && textOf(row.message).trim());
+
+  return {
+    reference: {
+      path: transcriptPath,
+      byteOffset,
+      byteLength,
+      recordsRead: rows.length,
+      excerptSha256: sha256(buffer),
+      format: 'claude-jsonl',
+    },
+    // DERIVED ONLY. Callers must not treat these as the user's words; they are a bounded
+    // single-sentence reduction, recorded so an abandoned session still knows what it was doing.
+    derivedGoal: lastUser ? firstSentence(textOf(lastUser.message)) : '',
+    derivedNextAction: lastAssistant ? firstSentence(textOf(lastAssistant.message)) : '',
+  };
+}