@mindrian_os/install 1.13.0-beta.16 → 1.13.0-beta.19

package/lib/core/breakthrough/resurfacing.cjs

@@ -0,0 +1,150 @@
+'use strict';
+/*
+ * Phase 120-02 Wave 2 Task 1 -- D-13..D-15 resurfacing rules. Per CONTEXT.md verbatim:
+ *
+ *   D-13 (dismissed): 7-day cooldown MINIMUM, AND only if new artifacts have accumulated
+ *                     since the dismiss. BOTH conditions REQUIRED. Time passing alone
+ *                     does NOT license resurfacing (user verbatim 2026-05-16:
+ *                     "that's manipulation").
+ *
+ *   D-14 (confirmed): once-only. Never resurface. Resurfacing what the user already
+ *                     accepted is patronizing.
+ *
+ *   D-15 (filed-as-decision): never resurface as breakthrough. May be referenced as
+ *                              ENABLES in future related breakthroughs via Phase 88
+ *                              decision-log machinery -- the decision becomes load-bearing
+ *                              for future patterns.
+ *
+ * Canon Part 8: pure LOCAL; no Brain coupling; no cross-room aggregation.
+ *   ALL reads via navigation.cjs::findRecentChanges chokepoint (Canon Part 9 D-06).
+ *
+ * Canon Part 9: SQL is the local mind; resurfacing is a read-only function over the
+ *   event log. The composite isEligibleForSurfacing is a pure predicate -- no writes,
+ *   no side effects.
+ *
+ * Em-dash HARD RULE (CLAUDE.md feedback_no_emdashes): use "--" not U+2014.
+ *
+ * Pure CJS, node built-ins only, zero deps.
+ */
+
+const navigation = require('../navigation.cjs');
+
+// CONTEXT.md D-13 verbatim: 7 days * 24 hours * 3600 sec * 1000 ms = 604800000 ms.
+const SEVEN_DAY_COOLDOWN_MS = 7 * 24 * 3600 * 1000;
+
+// 90-day search window for resurfacing lookups (older events stay in log but the
+// resurfacing predicates only look at trailing 90 days for memory locality + perf).
+const RESURFACING_WINDOW_MS = 90 * 24 * 3600 * 1000;
+const RESURFACING_QUERY_LIMIT = 500;
+
+// findFirstEventForBreakthrough -- chokepoint-routed lookup for a specific event type
+// against a specific breakthrough_id. Returns the most-recent matching event (since
+// findRecentChanges orders DESC) or null if none. Graceful-degradation on any throw.
+function findFirstEventForBreakthrough(id, eventType, db) {
+  try {
+    if (!db || typeof id !== 'string' || typeof eventType !== 'string') return null;
+    const since = Date.now() - RESURFACING_WINDOW_MS;
+    const events = navigation.findRecentChanges(db, since, {
+      eventType: eventType,
+      limit: RESURFACING_QUERY_LIMIT,
+    }) || [];
+    return events.find(function (e) {
+      return e && e.properties && e.properties.breakthrough_id === id;
+    }) || null;
+  } catch (_e) {
+    return null;
+  }
+}
+
+// D-14 once-only marker. A breakthrough that has ever been confirmed cannot resurface
+// as a breakthrough -- the user already accepted it; re-surfacing is patronizing.
+function hasBeenConfirmed(id, db) {
+  return !!findFirstEventForBreakthrough(id, 'breakthrough_confirmed', db);
+}
+
+// D-15 never-resurface marker. A breakthrough that has been filed as a decision is
+// now a first-class decision (Canon Part 4 bridge via Phase 88 decision-log).
+// Re-surfacing it as a breakthrough would conflate two different graph entities.
+function hasBeenFiledAsDecision(id, db) {
+  return !!findFirstEventForBreakthrough(id, 'breakthrough_filed_as_decision', db);
+}
+
+// D-13 first half. Returns true when EITHER (a) the breakthrough has never been
+// dismissed (vacuously eligible) OR (b) the most-recent dismiss is older than 7 days.
+function dismissalCooldownExpired(id, db) {
+  const dismiss = findFirstEventForBreakthrough(id, 'breakthrough_dismissed', db);
+  if (!dismiss) return true; // vacuously eligible re: cooldown
+  const ts = (typeof dismiss.createdAt === 'number') ? dismiss.createdAt : 0;
+  const ageMs = Date.now() - ts;
+  return ageMs >= SEVEN_DAY_COOLDOWN_MS;
+}
+
+// D-13 second half. The scanner passes the CURRENT candidate's artifact_ids[] length
+// via opts.current_artifact_count; this function compares it against the baseline
+// stored in the breakthrough_dismissed event's properties.artifact_ids_at_dismiss[].
+// Returns true IFF current > baseline. Returns false on missing baseline (defensive).
+//
+// Note: callers should normally use isEligibleForSurfacing (the composite gate). This
+// helper is exported for granular telemetry + per-rule unit tests.
+function newArtifactsAccumulated(id, db, opts) {
+  const dismiss = findFirstEventForBreakthrough(id, 'breakthrough_dismissed', db);
+  if (!dismiss) return false; // cannot measure delta without baseline
+  const baselineIds = (dismiss.properties && Array.isArray(dismiss.properties.artifact_ids_at_dismiss))
+    ? dismiss.properties.artifact_ids_at_dismiss : [];
+  const baselineCount = baselineIds.length;
+  const currentCount = (opts && Number.isInteger(opts.current_artifact_count))
+    ? opts.current_artifact_count : 0;
+  return currentCount > baselineCount;
+}
+
+// Composite resurfacing gate. Encodes D-13 BOTH-condition + D-14 + D-15.
+//
+// Priority order (highest precedence first):
+//   1. D-14 confirmed once-only -> reason: 'confirmed_once_only'
+//   2. D-15 filed-as-decision   -> reason: 'filed_as_decision_never_resurfaces'
+//   3. D-13 first half (cooldown active) -> reason: 'dismiss_cooldown_active'
+//   4. D-13 second half (no new artifacts) -> reason: 'dismiss_no_new_artifacts'
+//   5. Eligible -> { eligible: true }
+//
+// The BOTH-condition rule for D-13 is structurally enforced by two SEPARATE checks
+// joined with explicit AND semantics (priority 3 must clear before priority 4 is
+// even checked). This prevents the OR drift that would land if a single helper
+// merged the two conditions. User verbatim: "that's manipulation".
+function isEligibleForSurfacing(id, db, opts) {
+  // D-14 first (highest priority): confirmed once-only.
+  if (hasBeenConfirmed(id, db)) {
+    return { eligible: false, reason: 'confirmed_once_only' };
+  }
+  // D-15 next: filed-as-decision never resurfaces.
+  if (hasBeenFiledAsDecision(id, db)) {
+    return { eligible: false, reason: 'filed_as_decision_never_resurfaces' };
+  }
+  // D-13 first half: cooldown must have expired.
+  if (!dismissalCooldownExpired(id, db)) {
+    return { eligible: false, reason: 'dismiss_cooldown_active' };
+  }
+  // D-13 second half: IF the breakthrough was previously dismissed (i.e., a baseline
+  // exists), new artifacts MUST have accumulated. The check is gated on existence of
+  // the dismiss event -- a never-dismissed breakthrough skips the artifacts check
+  // (it's vacuously eligible per priority 5).
+  const dismiss = findFirstEventForBreakthrough(id, 'breakthrough_dismissed', db);
+  if (dismiss) {
+    const baselineCount = (dismiss.properties && Array.isArray(dismiss.properties.artifact_ids_at_dismiss))
+      ? dismiss.properties.artifact_ids_at_dismiss.length : 0;
+    const currentCount = (opts && Number.isInteger(opts.current_artifact_count))
+      ? opts.current_artifact_count : 0;
+    if (currentCount <= baselineCount) {
+      return { eligible: false, reason: 'dismiss_no_new_artifacts' };
+    }
+  }
+  return { eligible: true };
+}
+
+module.exports = {
+  hasBeenConfirmed: hasBeenConfirmed,
+  hasBeenFiledAsDecision: hasBeenFiledAsDecision,
+  dismissalCooldownExpired: dismissalCooldownExpired,
+  newArtifactsAccumulated: newArtifactsAccumulated,
+  isEligibleForSurfacing: isEligibleForSurfacing,
+  SEVEN_DAY_COOLDOWN_MS: SEVEN_DAY_COOLDOWN_MS,
+};

package/lib/core/breakthrough/resurfacing.test.cjs

@@ -0,0 +1,233 @@
+'use strict';
+
+/*
+ * Phase 120-02 Wave 2 Task 1 -- D-13..D-15 resurfacing rules unit tests.
+ *
+ * Tests 1-14 cover:
+ *   - SEVEN_DAY_COOLDOWN_MS verbatim lock (D-13)
+ *   - hasBeenConfirmed (D-14 once-only marker)
+ *   - hasBeenFiledAsDecision (D-15 never-resurface marker)
+ *   - dismissalCooldownExpired (D-13 first half)
+ *   - newArtifactsAccumulated (D-13 second half; user verbatim:
+ *     "Time passing alone doesn't license resurfacing -- that's manipulation")
+ *   - isEligibleForSurfacing composite gate enforcing D-13 BOTH-condition rule
+ *
+ * Canon Part 8 source-grep + em-dash HARD RULE asserted in Tests 22 + 23
+ * (covered jointly with canary.test.cjs counterpart -- see canary.test.cjs).
+ */
+
+const test = require('node:test');
+const { strict: assert } = require('node:assert');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..', '..');
+const resurfacing = require(path.join(REPO_ROOT, 'lib', 'core', 'breakthrough', 'resurfacing.cjs'));
+const navigation = require(path.join(REPO_ROOT, 'lib', 'core', 'navigation.cjs'));
+const { openRoomDb } = require(path.join(REPO_ROOT, 'lib', 'core', 'room-db.cjs'));
+
+function makeTmpDb(prefix) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+  const db = openRoomDb(dir);
+  return { dir, db };
+}
+
+function seedNodeAsArtifact(db, id) {
+  const nowMs = Date.now();
+  db.prepare(
+    "INSERT INTO nodes (id, type, properties, source_path, created_by, review_status, created_at, last_seen_at) " +
+    "VALUES (?, 'artifact', '{}', 'test', 'system', 'confirmed', ?, ?)"
+  ).run(id, nowMs, nowMs);
+}
+
+// Helper: write a memory_event with a controlled created_at (for cooldown tests).
+function backdateLastEvent(db, eventId, backdatedMs) {
+  db.prepare("UPDATE nodes SET created_at = ? WHERE id = ?").run(backdatedMs, eventId);
+}
+
+test('120-02 Task 1 Test 1: SEVEN_DAY_COOLDOWN_MS verbatim = 604800000', () => {
+  assert.equal(resurfacing.SEVEN_DAY_COOLDOWN_MS, 7 * 24 * 3600 * 1000);
+  assert.equal(resurfacing.SEVEN_DAY_COOLDOWN_MS, 604800000);
+});
+
+test('120-02 Task 1 Test 2: hasBeenConfirmed returns true given a breakthrough_confirmed event', () => {
+  const { dir, db } = makeTmpDb('p120-02-t1-t2-');
+  const r = navigation.logMemoryEvent(db, 'breakthrough_confirmed', {
+    breakthrough_id: 'bk:1',
+    kind: 'convergence',
+    source_path: 'system:test',
+    created_by: 'system',
+  });
+  assert.equal(r.ok, true);
+  assert.equal(resurfacing.hasBeenConfirmed('bk:1', db), true);
+});
+
+test('120-02 Task 1 Test 3: hasBeenConfirmed returns false on empty event log', () => {
+  const { dir, db } = makeTmpDb('p120-02-t1-t3-');
+  assert.equal(resurfacing.hasBeenConfirmed('bk:never', db), false);
+});
+
+test('120-02 Task 1 Test 4: hasBeenFiledAsDecision returns true given a breakthrough_filed_as_decision event', () => {
+  const { dir, db } = makeTmpDb('p120-02-t1-t4-');
+  const r = navigation.logMemoryEvent(db, 'breakthrough_filed_as_decision', {
+    breakthrough_id: 'bk:2',
+    kind: 'convergence',
+    source_path: 'system:test',
+    created_by: 'system',
+  });
+  assert.equal(r.ok, true);
+  assert.equal(resurfacing.hasBeenFiledAsDecision('bk:2', db), true);
+});
+
+test('120-02 Task 1 Test 5: dismissalCooldownExpired returns false when dismissed 3 days ago', () => {
+  const { dir, db } = makeTmpDb('p120-02-t1-t5-');
+  const r = navigation.logMemoryEvent(db, 'breakthrough_dismissed', {
+    breakthrough_id: 'bk:3',
+    kind: 'convergence',
+    artifact_ids_at_dismiss: ['a1', 'a2', 'a3'],
+    source_path: 'system:test',
+    created_by: 'system',
+  });
+  assert.equal(r.ok, true);
+  // Backdate the event to 3 days ago.
+  backdateLastEvent(db, r.eventId, Date.now() - 3 * 24 * 3600 * 1000);
+  assert.equal(resurfacing.dismissalCooldownExpired('bk:3', db), false);
+});
+
+test('120-02 Task 1 Test 6: dismissalCooldownExpired returns true when dismissed 8 days ago', () => {
+  const { dir, db } = makeTmpDb('p120-02-t1-t6-');
+  const r = navigation.logMemoryEvent(db, 'breakthrough_dismissed', {
+    breakthrough_id: 'bk:4',
+    kind: 'convergence',
+    artifact_ids_at_dismiss: ['a1'],
+    source_path: 'system:test',
+    created_by: 'system',
+  });
+  assert.equal(r.ok, true);
+  backdateLastEvent(db, r.eventId, Date.now() - 8 * 24 * 3600 * 1000);
+  assert.equal(resurfacing.dismissalCooldownExpired('bk:4', db), true);
+});
+
+test('120-02 Task 1 Test 7: dismissalCooldownExpired returns true on never-dismissed breakthrough', () => {
+  const { dir, db } = makeTmpDb('p120-02-t1-t7-');
+  // Vacuously eligible: cooldown rule applies only IF the breakthrough was dismissed.
+  assert.equal(resurfacing.dismissalCooldownExpired('bk:fresh', db), true);
+});
+
+test('120-02 Task 1 Test 8: newArtifactsAccumulated returns true when current_artifact_count exceeds baseline', () => {
+  const { dir, db } = makeTmpDb('p120-02-t1-t8-');
+  const r = navigation.logMemoryEvent(db, 'breakthrough_dismissed', {
+    breakthrough_id: 'bk:5',
+    kind: 'convergence',
+    artifact_ids_at_dismiss: ['a1', 'a2', 'a3'],
+    source_path: 'system:test',
+    created_by: 'system',
+  });
+  assert.equal(r.ok, true);
+  backdateLastEvent(db, r.eventId, Date.now() - 8 * 24 * 3600 * 1000);
+  // Baseline = 3 at dismiss; current count = 4 -> accumulated.
+  const elig4 = resurfacing.isEligibleForSurfacing('bk:5', db, { current_artifact_count: 4 });
+  assert.equal(elig4.eligible, true);
+  // Baseline = 3 at dismiss; current count = 3 -> NOT accumulated.
+  const elig3 = resurfacing.isEligibleForSurfacing('bk:5', db, { current_artifact_count: 3 });
+  assert.equal(elig3.eligible, false);
+  assert.equal(elig3.reason, 'dismiss_no_new_artifacts');
+});
+
+test('120-02 Task 1 Test 9: isEligibleForSurfacing returns eligible:true on never-seen breakthrough', () => {
+  const { dir, db } = makeTmpDb('p120-02-t1-t9-');
+  const elig = resurfacing.isEligibleForSurfacing('bk:fresh', db, { current_artifact_count: 4 });
+  assert.equal(elig.eligible, true);
+});
+
+test('120-02 Task 1 Test 10: isEligibleForSurfacing D-14 confirmed once-only blocked', () => {
+  const { dir, db } = makeTmpDb('p120-02-t1-t10-');
+  navigation.logMemoryEvent(db, 'breakthrough_confirmed', {
+    breakthrough_id: 'bk:c',
+    source_path: 'system:test',
+    created_by: 'system',
+  });
+  const elig = resurfacing.isEligibleForSurfacing('bk:c', db, { current_artifact_count: 99 });
+  assert.equal(elig.eligible, false);
+  assert.equal(elig.reason, 'confirmed_once_only');
+});
+
+test('120-02 Task 1 Test 11: isEligibleForSurfacing D-15 filed-as-decision blocked', () => {
+  const { dir, db } = makeTmpDb('p120-02-t1-t11-');
+  navigation.logMemoryEvent(db, 'breakthrough_filed_as_decision', {
+    breakthrough_id: 'bk:f',
+    source_path: 'system:test',
+    created_by: 'system',
+  });
+  const elig = resurfacing.isEligibleForSurfacing('bk:f', db, { current_artifact_count: 99 });
+  assert.equal(elig.eligible, false);
+  assert.equal(elig.reason, 'filed_as_decision_never_resurfaces');
+});
+
+test('120-02 Task 1 Test 12: isEligibleForSurfacing D-13 dismissed in cooldown blocked', () => {
+  const { dir, db } = makeTmpDb('p120-02-t1-t12-');
+  const r = navigation.logMemoryEvent(db, 'breakthrough_dismissed', {
+    breakthrough_id: 'bk:d',
+    artifact_ids_at_dismiss: ['a1'],
+    source_path: 'system:test',
+    created_by: 'system',
+  });
+  backdateLastEvent(db, r.eventId, Date.now() - 3 * 24 * 3600 * 1000);
+  const elig = resurfacing.isEligibleForSurfacing('bk:d', db, { current_artifact_count: 99 });
+  assert.equal(elig.eligible, false);
+  assert.equal(elig.reason, 'dismiss_cooldown_active');
+});
+
+test('120-02 Task 1 Test 13: isEligibleForSurfacing D-13 cooldown expired BUT no new artifacts blocked (BOTH-condition lock)', () => {
+  // Per CONTEXT.md D-13 + user verbatim 2026-05-16: "Time passing alone doesn't
+  // license resurfacing -- that's manipulation". This test prevents OR drift
+  // (the BOTH-condition rule MUST stay AND, not OR).
+  const { dir, db } = makeTmpDb('p120-02-t1-t13-');
+  const r = navigation.logMemoryEvent(db, 'breakthrough_dismissed', {
+    breakthrough_id: 'bk:13',
+    artifact_ids_at_dismiss: ['a1', 'a2', 'a3'],
+    source_path: 'system:test',
+    created_by: 'system',
+  });
+  backdateLastEvent(db, r.eventId, Date.now() - 8 * 24 * 3600 * 1000);
+  // Cooldown expired (8 > 7) but artifact count unchanged (3 == 3 baseline).
+  const elig = resurfacing.isEligibleForSurfacing('bk:13', db, { current_artifact_count: 3 });
+  assert.equal(elig.eligible, false);
+  assert.equal(elig.reason, 'dismiss_no_new_artifacts');
+});
+
+test('120-02 Task 1 Test 14: isEligibleForSurfacing D-13 BOTH conditions met -> eligible', () => {
+  const { dir, db } = makeTmpDb('p120-02-t1-t14-');
+  const r = navigation.logMemoryEvent(db, 'breakthrough_dismissed', {
+    breakthrough_id: 'bk:14',
+    artifact_ids_at_dismiss: ['a1', 'a2'],
+    source_path: 'system:test',
+    created_by: 'system',
+  });
+  backdateLastEvent(db, r.eventId, Date.now() - 8 * 24 * 3600 * 1000);
+  // Cooldown expired AND new artifacts accumulated (5 > 2).
+  const elig = resurfacing.isEligibleForSurfacing('bk:14', db, { current_artifact_count: 5 });
+  assert.equal(elig.eligible, true);
+});
+
+test('120-02 Task 1 Test 22: Canon Part 8 source-grep -- zero Brain coupling in resurfacing.cjs', () => {
+  const src = fs.readFileSync(path.join(REPO_ROOT, 'lib', 'core', 'breakthrough', 'resurfacing.cjs'), 'utf8');
+  // Real API call patterns only -- not documentation prose (cf. 120-00 Deviation 2).
+  assert.equal(/require\s*\(\s*['"][^'"]*brain-client[^'"]*['"]\s*\)/.test(src), false,
+    'resurfacing.cjs must not require brain-client');
+  assert.equal(/fetch\s*\(\s*['"][^'"]*brain\.mindrian/.test(src), false,
+    'resurfacing.cjs must not fetch brain.mindrian.*');
+});
+
+test('120-02 Task 1 Test 23: em-dash HARD RULE -- zero U+2014 in resurfacing.cjs', () => {
+  const src = fs.readFileSync(path.join(REPO_ROOT, 'lib', 'core', 'breakthrough', 'resurfacing.cjs'), 'utf8');
+  // The U+2014 byte sequence in UTF-8 is 0xE2 0x80 0x94. Use codepoint check
+  // instead of including the literal character in the test source (which would
+  // make this test self-trip).
+  let count = 0;
+  for (const ch of src) {
+    if (ch.charCodeAt(0) === 0x2014) count++;
+  }
+  assert.equal(count, 0, 'resurfacing.cjs must contain zero U+2014 em-dash characters');
+});

package/lib/core/breakthrough/review-queue.cjs

@@ -0,0 +1,154 @@
+'use strict';
+// Phase 120-03 Wave 2 Task 2 -- SOFT_BAND breakthrough review queue.
+//
+// Per CONTEXT.md "Claude's Discretion" item 3: a separate
+// `.rooms/breakthrough-review-queue.db` SQLite database at the rooms-home level.
+// Mirrors the Phase 119-01 rooms-meta.db precedent (lib/core/room-discard-cascade.cjs::
+// _emitPartialFailure pattern). Sibling pattern; does NOT pollute per-room room.db
+// with cross-room review backlog.
+//
+// Per CONTEXT.md D-18 SOFT_BAND semantics:
+//   Confidence 0.35 <= conf <= 0.50 candidates queue here (NOT surfaced).
+//   Sample 20% manually each week to check for drift. These become retraining data.
+//
+// Canon Part 4: every choice is graph data. The review queue is the typed-row
+//   surface for SOFT_BAND breakthrough candidates; rows carry kind + confidence +
+//   theme + provenance ids (artifact_ids_json) for review.
+// Canon Part 8: queue stays LOCAL to the user's machine; no Brain coupling.
+// Canon Part 9: schema is queryable via standard SQLite; the sample-20% weekly
+//   audit is a manual SQL query against this db.
+//
+// Em-dash HARD RULE (CLAUDE.md feedback_no_emdashes): zero U+2014 in source.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+// Use Node's built-in node:sqlite DatabaseSync (Phase 109 SQL navigation spine
+// contract, mirrored from lib/core/room-db.cjs). Fall back to a no-op surface
+// only on require failure (env without sqlite, e.g. older Node versions; node:sqlite
+// is GA from Node 22.5+).
+let DatabaseSync;
+try {
+  ({ DatabaseSync } = require('node:sqlite'));
+} catch (_e) {
+  DatabaseSync = null;
+}
+
+// The 10-column DDL for the review_candidates table. Matches the test contract
+// in review-queue.test.cjs T11 (PRAGMA table_info returns these 10 column names).
+const TABLE_DDL = "CREATE TABLE IF NOT EXISTS review_candidates ( " +
+  "id TEXT PRIMARY KEY, " +
+  "room_slug TEXT, " +
+  "breakthrough_id TEXT NOT NULL, " +
+  "kind TEXT NOT NULL, " +
+  "confidence REAL NOT NULL, " +
+  "theme TEXT, " +
+  "artifact_ids_json TEXT, " +
+  "queued_at INTEGER NOT NULL, " +
+  "reviewed_at INTEGER, " +
+  "review_status TEXT NOT NULL DEFAULT 'pending'" +
+  ")";
+
+const REVIEW_QUEUE_DB_PATH = '.rooms/breakthrough-review-queue.db';
+
+// openReviewQueue(roomsHome) -> {db, dbPath?, fallback, reason?}
+//
+// Opens (creates if needed) the .rooms/breakthrough-review-queue.db at the given
+// rooms-home. Returns a handle with the db object, the resolved dbPath, and a
+// fallback flag. On EACCES / mkdir failure, falls back to an in-memory db so the
+// scanner can still insert (just not persistent across sessions).
+//
+// Graceful failure modes:
+//   - node:sqlite not available -> {db: null, fallback: true, reason: 'node_sqlite_not_available'}
+//   - mkdir fails -> in-memory db opened, fallback:true, reason: 'rooms_home_not_writable:<msg>'
+//   - in-memory open ALSO fails -> {db: null, fallback: true, reason: 'open_failed:<msg>'}
+function openReviewQueue(roomsHome) {
+  if (!DatabaseSync) {
+    return { db: null, fallback: true, reason: 'node_sqlite_not_available' };
+  }
+  try {
+    const metaDir = path.join(roomsHome, '.rooms');
+    fs.mkdirSync(metaDir, { recursive: true, mode: 0o755 });
+    const dbPath = path.join(metaDir, 'breakthrough-review-queue.db');
+    const db = new DatabaseSync(dbPath);
+    db.exec(TABLE_DDL);
+    return { db: db, dbPath: dbPath, fallback: false };
+  } catch (err) {
+    // Graceful fallback: in-memory db so the scanner can still insert; not persistent.
+    try {
+      const db = new DatabaseSync(':memory:');
+      db.exec(TABLE_DDL);
+      const errMsg = (err && err.message) ? err.message.slice(0, 80) : 'unknown';
+      return { db: db, fallback: true, reason: 'rooms_home_not_writable:' + errMsg };
+    } catch (err2) {
+      const errMsg2 = (err2 && err2.message) ? err2.message.slice(0, 80) : 'unknown';
+      return { db: null, fallback: true, reason: 'open_failed:' + errMsg2 };
+    }
+  }
+}
+
+// insertReviewCandidate(db, breakthrough, roomSlug) -> {ok, queue_id, queued_at} | {ok:false, reason}
+//
+// Inserts a SOFT_BAND candidate into the review queue. Generates a fresh queue_id
+// of the form "review:<8 hex bytes>" so callers do not need to coordinate IDs.
+// queued_at is Date.now() at insert time.
+//
+// review_status defaults to 'pending' per the DDL DEFAULT clause. reviewed_at
+// stays NULL until a manual reviewer updates it (manual SQL or future
+// /mos:doctor --review-queue-sweep command, deferred to v1.14.0).
+//
+// Theme is sliced to 200 chars to match the Phase 90-06 sanitizeDetailScalar
+// precedent (Canon Part 8 boundary -- bounded payload size).
+function insertReviewCandidate(db, breakthrough, roomSlug) {
+  if (!db || typeof db.prepare !== 'function') {
+    return { ok: false, reason: 'no_db' };
+  }
+  const bk = breakthrough || {};
+  const queueId = 'review:' + crypto.randomBytes(8).toString('hex');
+  const queued_at = Date.now();
+  try {
+    db.prepare(
+      "INSERT INTO review_candidates (id, room_slug, breakthrough_id, kind, confidence, theme, artifact_ids_json, queued_at, review_status) " +
+      "VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'pending')"
+    ).run(
+      queueId,
+      (typeof roomSlug === 'string' ? roomSlug : null),
+      bk.id || null,
+      (typeof bk.kind === 'string' ? bk.kind : 'unknown'),
+      (typeof bk.confidence === 'number' && Number.isFinite(bk.confidence) ? bk.confidence : 0),
+      (typeof bk.theme === 'string' ? bk.theme.slice(0, 200) : null),
+      JSON.stringify(Array.isArray(bk.artifact_ids) ? bk.artifact_ids : []),
+      queued_at
+    );
+    return { ok: true, queue_id: queueId, queued_at: queued_at };
+  } catch (err) {
+    return { ok: false, reason: (err && err.message) ? err.message : 'insert_failed' };
+  }
+}
+
+// listPendingReviews(db, limit) -> [{id, room_slug, breakthrough_id, kind, confidence, theme, queued_at}, ...]
+//
+// Returns rows where review_status = 'pending', ordered by queued_at DESC. Limit
+// defaults to 100; non-positive / non-integer limits use the default.
+function listPendingReviews(db, limit) {
+  if (!db || typeof db.prepare !== 'function') return [];
+  const lim = (Number.isInteger(limit) && limit > 0) ? limit : 100;
+  try {
+    return db.prepare(
+      "SELECT id, room_slug, breakthrough_id, kind, confidence, theme, queued_at " +
+      "FROM review_candidates WHERE review_status = 'pending' " +
+      "ORDER BY queued_at DESC LIMIT ?"
+    ).all(lim);
+  } catch (_e) {
+    return [];
+  }
+}
+
+module.exports = {
+  openReviewQueue,
+  insertReviewCandidate,
+  listPendingReviews,
+  REVIEW_QUEUE_DB_PATH,
+  TABLE_DDL,
+};