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

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

@@ -0,0 +1,256 @@
+'use strict';
+
+/*
+ * Phase 120-00 Wave 1 Task 3 -- the Breakthrough graph schema + the D-20 HARD FLOOR
+ * structural enforcement test surface.
+ *
+ * 12 tests covering:
+ *   1. validateProvenance happy path
+ *   2. validateProvenance rejects empty artifact_ids (D-20 HARD FLOOR)
+ *   3. validateProvenance rejects empty-string artifact ids
+ *   4. validateProvenance rejects missing breakthrough.id
+ *   5. writeBreakthrough happy path -- node + edges land via atomic transaction
+ *   6. writeBreakthrough rejects provenance-less input
+ *   7. D-20 CONSTITUTIONAL TEST: post-write SQL invariant
+ *      SELECT COUNT(*) FROM edges WHERE source=$bk AND type='DERIVED_FROM' >= 1
+ *   8. Atomic rollback on writeEdge failure (FK violation -- target missing)
+ *   9. Initial surfaced flag is false
+ *   10. D-20 BATCH INVARIANT: zero orphaned breakthroughs after all writes
+ *   11. Canon Part 8 source-grep (zero brain-client require)
+ *   12. writeBreakthrough does NOT emit breakthrough_surfaced (scanner does that)
+ */
+
+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 schema = require(path.join(REPO_ROOT, 'lib', 'core', 'breakthrough', 'schema.cjs'));
+const { openRoomDb, closeRoomDb } = require(path.join(REPO_ROOT, 'lib', 'core', 'room-db.cjs'));
+
+function makeTmpDb(prefix) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+  fs.mkdirSync(path.join(dir, '.mindrian'), { recursive: true });
+  const db = openRoomDb(dir);
+  return { dir, db };
+}
+
+function seedArtifact(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);
+}
+
+test('120-00 Task 3 Test 1: validateProvenance happy path', () => {
+  const r = schema.validateProvenance({ id: 'bk:1', artifact_ids: ['a1', 'a2'] });
+  assert.equal(r.ok, true);
+  assert.deepEqual(r.sanitized_artifact_ids, ['a1', 'a2']);
+});
+
+test('120-00 Task 3 Test 2: validateProvenance D-20 HARD FLOOR rejects empty artifact_ids', () => {
+  const r = schema.validateProvenance({ id: 'bk:1', artifact_ids: [] });
+  assert.equal(r.ok, false);
+  assert.equal(r.reason, 'provenance_required');
+});
+
+test('120-00 Task 3 Test 3: validateProvenance rejects empty-string artifact ids', () => {
+  const r = schema.validateProvenance({ id: 'bk:1', artifact_ids: ['', null, undefined] });
+  assert.equal(r.ok, false);
+  assert.equal(r.reason, 'provenance_required');
+});
+
+test('120-00 Task 3 Test 4: validateProvenance rejects missing breakthrough.id', () => {
+  const r = schema.validateProvenance({ artifact_ids: ['a1'] });
+  assert.equal(r.ok, false);
+  assert.equal(r.reason, 'breakthrough_id_required');
+});
+
+test('120-00 Task 3 Test 4b: validateProvenance rejects non-object input', () => {
+  assert.equal(schema.validateProvenance(null).ok, false);
+  assert.equal(schema.validateProvenance(undefined).ok, false);
+  assert.equal(schema.validateProvenance('string').ok, false);
+});
+
+test('120-00 Task 3 Test 5: writeBreakthrough happy path -- node + edges land atomically', () => {
+  const { dir, db } = makeTmpDb('p120-bk-happy-');
+  seedArtifact(db, 'a1');
+  seedArtifact(db, 'a2');
+  const nowMs = Date.now();
+  const candidate = {
+    id: 'bk:happy',
+    kind: 'convergence',
+    confidence: 0.55,
+    artifact_ids: ['a1', 'a2'],
+    theme: 'X',
+    differential: 0.6,
+    cross_section_linked: false,
+    detected_at: nowMs,
+    window_start: nowMs - 14 * 86400000,
+    window_end: nowMs,
+  };
+  const r = schema.writeBreakthrough(db, candidate);
+  assert.equal(r.ok, true, 'writeBreakthrough should succeed; got reason=' + (r.reason || ''));
+  assert.equal(r.breakthroughId, 'bk:happy');
+  assert.equal(r.edgeIds.length, 2);
+
+  // Verify the breakthrough node landed.
+  const bkRow = db.prepare("SELECT id, type, properties FROM nodes WHERE id = 'bk:happy'").get();
+  assert.equal(bkRow.type, 'breakthrough');
+  const bkProps = JSON.parse(bkRow.properties);
+  assert.equal(bkProps.kind, 'convergence');
+  assert.equal(bkProps.confidence, 0.55);
+
+  // Verify both DERIVED_FROM edges landed.
+  const edgeCount = db.prepare(
+    "SELECT COUNT(*) AS c FROM edges WHERE source = 'bk:happy' AND type = 'DERIVED_FROM'"
+  ).get().c;
+  assert.equal(edgeCount, 2, 'two DERIVED_FROM edges expected');
+
+  try { closeRoomDb(db); } catch (_e) { /* graceful */ }
+});
+
+test('120-00 Task 3 Test 6: writeBreakthrough rejects provenance-less input', () => {
+  const { dir, db } = makeTmpDb('p120-bk-bad-');
+  const r = schema.writeBreakthrough(db, { id: 'bk:bad', artifact_ids: [] });
+  assert.equal(r.ok, false);
+  assert.equal(r.reason, 'provenance_required');
+
+  // Verify NO breakthrough node landed.
+  const bkRow = db.prepare("SELECT id FROM nodes WHERE id = 'bk:bad'").get();
+  assert.equal(bkRow, undefined, 'no breakthrough node should land');
+
+  try { closeRoomDb(db); } catch (_e) { /* graceful */ }
+});
+
+test('120-00 Task 3 Test 7: D-20 CONSTITUTIONAL TEST -- Cypher invariant SQL query', () => {
+  const { dir, db } = makeTmpDb('p120-bk-d20-');
+  seedArtifact(db, 'a1');
+  seedArtifact(db, 'a2');
+  const r = schema.writeBreakthrough(db, {
+    id: 'bk:d20',
+    kind: 'convergence',
+    confidence: 0.55,
+    artifact_ids: ['a1', 'a2'],
+  });
+  assert.equal(r.ok, true);
+  // The SQL equivalent of:
+  //   MATCH (b:Breakthrough)-[:DERIVED_FROM]->(a:Artifact) WHERE b.id = 'bk:d20'
+  //   RETURN count(a)
+  // -- must return >= 1.
+  const count = db.prepare(
+    "SELECT COUNT(*) AS c FROM edges WHERE source = 'bk:d20' AND type = 'DERIVED_FROM'"
+  ).get().c;
+  assert.equal(count >= 1, true, 'D-20 invariant: count=' + count + ', expected >= 1');
+
+  try { closeRoomDb(db); } catch (_e) { /* graceful */ }
+});
+
+test('120-00 Task 3 Test 8: atomic rollback on writeEdge failure -- partial state cannot land', () => {
+  const { dir, db } = makeTmpDb('p120-bk-rb-');
+  seedArtifact(db, 'a-exists');
+  // a-missing intentionally NOT seeded -- FK constraint will fail on the second edge insert.
+  const r = schema.writeBreakthrough(db, {
+    id: 'bk:partial',
+    kind: 'convergence',
+    confidence: 0.55,
+    artifact_ids: ['a-exists', 'a-missing'],
+  });
+  assert.equal(r.ok, false, 'writeBreakthrough should fail when second edge target missing');
+  assert.match(r.reason, /writeEdge_failed|edge_write_failed/, 'reason should reference edge failure');
+
+  // Verify NO breakthrough node landed (ROLLBACK).
+  const bkRow = db.prepare("SELECT id FROM nodes WHERE id = 'bk:partial'").get();
+  assert.equal(bkRow, undefined, 'transaction rolled back -- no node landed');
+
+  // Verify NO DERIVED_FROM edges landed.
+  const edgeCount = db.prepare(
+    "SELECT COUNT(*) AS c FROM edges WHERE source = 'bk:partial'"
+  ).get().c;
+  assert.equal(edgeCount, 0, 'transaction rolled back -- zero edges landed');
+
+  try { closeRoomDb(db); } catch (_e) { /* graceful */ }
+});
+
+test('120-00 Task 3 Test 9: initial surfaced flag is false', () => {
+  const { dir, db } = makeTmpDb('p120-bk-sfc-');
+  seedArtifact(db, 'a1');
+  const r = schema.writeBreakthrough(db, {
+    id: 'bk:surf',
+    kind: 'convergence',
+    confidence: 0.55,
+    artifact_ids: ['a1'],
+  });
+  assert.equal(r.ok, true);
+  const row = db.prepare("SELECT properties FROM nodes WHERE id = 'bk:surf'").get();
+  const props = JSON.parse(row.properties);
+  assert.equal(props.surfaced, false, 'surfaced flag initially false; flipped by Plan 120-02 scanner');
+
+  try { closeRoomDb(db); } catch (_e) { /* graceful */ }
+});
+
+test('120-00 Task 3 Test 10: D-20 BATCH INVARIANT -- zero orphaned breakthroughs', () => {
+  const { dir, db } = makeTmpDb('p120-bk-batch-');
+  seedArtifact(db, 'a1');
+  seedArtifact(db, 'a2');
+  seedArtifact(db, 'a3');
+  // Two successful writes.
+  assert.equal(schema.writeBreakthrough(db, { id: 'bk:1', kind: 'convergence', confidence: 0.55, artifact_ids: ['a1', 'a2'] }).ok, true);
+  assert.equal(schema.writeBreakthrough(db, { id: 'bk:2', kind: 'convergence', confidence: 0.55, artifact_ids: ['a3'] }).ok, true);
+  // One failed write (provenance-less).
+  assert.equal(schema.writeBreakthrough(db, { id: 'bk:3', artifact_ids: [] }).ok, false);
+  // One failed write (FK violation).
+  assert.equal(schema.writeBreakthrough(db, { id: 'bk:4', kind: 'convergence', confidence: 0.55, artifact_ids: ['a-missing'] }).ok, false);
+
+  // The batch invariant: every breakthrough node has >= 1 DERIVED_FROM edge.
+  const orphans = db.prepare(
+    "SELECT b.id FROM nodes b WHERE b.type = 'breakthrough' " +
+    "AND NOT EXISTS (SELECT 1 FROM edges e WHERE e.source = b.id AND e.type = 'DERIVED_FROM')"
+  ).all();
+  assert.equal(orphans.length, 0, 'D-20 batch invariant: orphaned breakthroughs=' + JSON.stringify(orphans));
+
+  try { closeRoomDb(db); } catch (_e) { /* graceful */ }
+});
+
+test('120-00 Task 3 Test 11: Canon Part 8 invariant -- zero Brain client require', () => {
+  const src = fs.readFileSync(path.join(REPO_ROOT, 'lib', 'core', 'breakthrough', 'schema.cjs'), 'utf8');
+  assert.equal(/require\([^)]*brain-client/.test(src), false);
+  assert.equal(/fetch\([^)]*brain\.mindrian/.test(src), false);
+});
+
+test('120-00 Task 3 Test 12: writeBreakthrough does NOT emit breakthrough_surfaced', () => {
+  const { dir, db } = makeTmpDb('p120-bk-no-surf-');
+  seedArtifact(db, 'a1');
+  const r = schema.writeBreakthrough(db, {
+    id: 'bk:no-surf',
+    kind: 'convergence',
+    confidence: 0.55,
+    artifact_ids: ['a1'],
+  });
+  assert.equal(r.ok, true);
+  // Verify no memory_event with event_type='breakthrough_surfaced' landed.
+  const surfacedRows = db.prepare(
+    "SELECT id FROM nodes WHERE type = 'memory_event' " +
+    "AND json_extract(properties, '$.event_type') = 'breakthrough_surfaced'"
+  ).all();
+  assert.equal(surfacedRows.length, 0, 'writeBreakthrough must NOT emit breakthrough_surfaced; Plan 120-02 scanner does that');
+
+  try { closeRoomDb(db); } catch (_e) { /* graceful */ }
+});
+
+test('120-00 Task 3 Test 13 bonus: writeBreakthrough validates db handle', () => {
+  const r = schema.writeBreakthrough(null, { id: 'bk:x', artifact_ids: ['a1'] });
+  assert.equal(r.ok, false);
+  assert.equal(r.reason, 'invalid_db');
+});
+
+test('120-00 Task 3 Test 14 bonus: BREAKTHROUGH_KIND constants', () => {
+  assert.equal(schema.BREAKTHROUGH_KIND.CONVERGENCE, 'convergence');
+  assert.equal(schema.BREAKTHROUGH_KIND.CONTRADICTION_RESOLVED, 'contradiction_resolved');
+  assert.equal(schema.BREAKTHROUGH_KIND.CROSS_DOMAIN_ANALOGY, 'cross_domain_analogy');
+  assert.equal(schema.BREAKTHROUGH_KIND.REVERSE_SALIENT_CLOSED, 'reverse_salient_closed');
+  assert.equal(schema.BREAKTHROUGH_NODE_TYPE, 'breakthrough');
+});

package/lib/core/breakthrough/scoring.cjs

@@ -0,0 +1,293 @@
+'use strict';
+/*
+ * Phase 120-01 Wave 2 Task 3 -- the 5-component breakthrough scoring formula +
+ * rankBreakthroughs + pickTopWithAffordance + getUserEngagementPrior +
+ * isThrottledKind. Per CONTEXT.md D-11..D-12 + D-19 verbatim:
+ *
+ *   score = (confidence x 0.4)
+ *         + (recency_decay x 0.2)        // half-life ~3 days
+ *         + (differential x 0.2)
+ *         + (artifact_count_log x 0.1)   // clamped [0, 1]
+ *         + (user_engagement_prior x 0.1) // per-detector-type Laplace-smoothed prior
+ *
+ * Tunable via config.json; the weights are the documented defaults (NOT magic
+ * numbers). Sum of weights MUST equal 1.0 (verified by SCORING_WEIGHTS unit test).
+ *
+ * Canon Part 8: ALL reads from breakthrough_confirmed / breakthrough_dismissed
+ *   / breakthrough_surfaced events stay LOCAL to the room.db. NO cross-room
+ *   aggregation. NO Brain coupling. NO require of brain-client. NO fetch to
+ *   brain.mindrian.* domain.
+ *
+ * Canon Part 9: ALL reads route through navigation.findRecentChanges chokepoint.
+ *   No direct sqlite reads in scoring.cjs (defense in depth on top of room-db.cjs
+ *   allow-list). Test 12 source-greps this invariant.
+ *
+ * Canon Part 10 sub-claim 5: variable reward fires automatically; the score IS
+ *   the math. The 5 components are deterministic functions of room state -- no
+ *   stochastic surfacing, no engagement-optimizer drift.
+ *
+ * Em-dash HARD RULE (CLAUDE.md feedback_no_emdashes): use "--" not the U+2014
+ *   character anywhere in this file (comments, log lines, strings).
+ *
+ * Pure CJS, node built-ins only, zero deps (Phase 87 invariant). Reads route
+ * through ../navigation.cjs::findRecentChanges (the only Canon Part 9-compliant
+ * door for memory_event queries).
+ */
+
+const navigation = require('../navigation.cjs');
+
+// CONTEXT.md D-12 verbatim lock. Object.freeze prevents accidental mutation of
+// the canonical weight map; if a downstream caller needs a mutable copy they
+// must clone explicitly. The 5 weights MUST sum to exactly 1.0 (Test 1 asserts
+// this within 1e-9 floating-point tolerance).
+const SCORING_WEIGHTS = Object.freeze({
+  confidence: 0.4,
+  recency: 0.2,
+  differential: 0.2,
+  artifact_count_log: 0.1,
+  user_engagement_prior: 0.1,
+});
+
+// CONTEXT.md D-12 verbatim: recency half-life ~3 days. The exponential-decay
+// kernel is exp(-ageDays / RECENCY_HALF_LIFE_DAYS); 3-day-old fires decay to
+// exp(-1) ~= 0.368, 6-day-old fires decay to exp(-2) ~= 0.135.
+const RECENCY_HALF_LIFE_DAYS = 3;
+
+// Neutral-prior return value when getUserEngagementPrior has no history to
+// learn from (or graceful degradation path on chokepoint failure). The +0.5
+// Laplace smoothing pivots around this midpoint.
+const ENGAGEMENT_NEUTRAL_PRIOR = 0.5;
+
+// CONTEXT.md D-19 verbatim: per-detector dismissal-rate canary. If a detector's
+// dismiss rate over the rolling D19_FIRE_WINDOW most-recent fires exceeds
+// D19_DISMISSAL_THRESHOLD, isThrottledKind returns true (Plan 120-02 scanner
+// then auto-throttles that detector to soft-fire-only until manually reviewed).
+//
+// D19_MIN_SAMPLE prevents premature throttling on small populations: a 1-of-2
+// dismiss = 50% would otherwise trip the canary on essentially noise. The
+// floor of 10 ensures statistical adequacy before throttling kicks in.
+const D19_DISMISSAL_THRESHOLD = 0.30;
+const D19_FIRE_WINDOW = 100;
+const D19_MIN_SAMPLE = 10;
+
+// Per-kind engagement-prior + canary window. Reads memory_event rows from the
+// trailing 90 days; older history is considered stale and excluded from the
+// learning signal.
+const PRIOR_WINDOW_DAYS = 90;
+const PRIOR_QUERY_LIMIT = 500;
+
+const DAY_MS = 24 * 3600 * 1000;
+
+// ---------------------------------------------------------------------------
+// recencyDecay -- exp(-ageDays / RECENCY_HALF_LIFE_DAYS). Clamped to [0, 1].
+// Future-dated candidates (ageMs < 0) clamp to age=0 (decay=1.0); they never
+// produce a decay > 1.0 even on clock skew.
+// ---------------------------------------------------------------------------
+function recencyDecay(detected_at, nowMs) {
+  const now = (typeof nowMs === 'number' && Number.isFinite(nowMs)) ? nowMs : Date.now();
+  const ts = (typeof detected_at === 'number' && Number.isFinite(detected_at)) ? detected_at : now;
+  const ageMs = Math.max(0, now - ts);
+  const ageDays = ageMs / DAY_MS;
+  const decay = Math.exp(-ageDays / RECENCY_HALF_LIFE_DAYS);
+  // Defense in depth: clamp to [0, 1] in case of floating-point edge cases.
+  return Math.min(1, Math.max(0, decay));
+}
+
+// ---------------------------------------------------------------------------
+// artifactCountLog -- log10(N) clamped to [0, 1]. CONTEXT.md D-12 specifies
+// the component is bounded so a 100-artifact convergence can't dominate the
+// score. log10(1)=0, log10(10)=1.0 (the ceiling), log10(100)=2.0 -> clamped 1.
+// ---------------------------------------------------------------------------
+function artifactCountLog(artifact_ids) {
+  if (!Array.isArray(artifact_ids)) return 0;
+  const n = artifact_ids.length;
+  if (n <= 0) return 0;
+  const raw = Math.log10(n);
+  return Math.min(1, Math.max(0, raw));
+}
+
+// ---------------------------------------------------------------------------
+// getUserEngagementPrior -- per-detector-kind Laplace-smoothed prior in [0, 1].
+//
+// Reads via navigation.findRecentChanges (Canon Part 9 chokepoint). Filters
+// the recent breakthrough_confirmed + breakthrough_dismissed events by kind
+// (extracted from properties.kind on each memory_event row).
+//
+// Smoothing formula: (confirmed + 0.5) / (confirmed + dismissed + 1)
+//   - empty history (0 confirmed + 0 dismissed): 0.5/1 = 0.5 (neutral)
+//   - 3 confirmed + 0 dismissed: 3.5/4 = 0.875 (pushed up)
+//   - 1 confirmed + 4 dismissed: 1.5/6 = 0.25  (pushed down)
+//
+// The +0.5 / +1 form pivots around the neutral midpoint and avoids the
+// division-by-zero failure mode of a naive ratio.
+//
+// Graceful degradation: missing/invalid roomState -> neutral 0.5. Chokepoint
+// throw (e.g., db handle closed) -> neutral 0.5. The prior must NEVER throw
+// from scoreBreakthrough's hot path.
+// ---------------------------------------------------------------------------
+function getUserEngagementPrior(kind, roomState) {
+  try {
+    if (!roomState || !roomState.db) return ENGAGEMENT_NEUTRAL_PRIOR;
+    const since = Date.now() - (PRIOR_WINDOW_DAYS * DAY_MS);
+    const confirmed = navigation.findRecentChanges(roomState.db, since, {
+      eventType: 'breakthrough_confirmed',
+      limit: PRIOR_QUERY_LIMIT,
+    }) || [];
+    const dismissed = navigation.findRecentChanges(roomState.db, since, {
+      eventType: 'breakthrough_dismissed',
+      limit: PRIOR_QUERY_LIMIT,
+    }) || [];
+    const cConfirmed = confirmed.filter((e) => e.properties && e.properties.kind === kind).length;
+    const cDismissed = dismissed.filter((e) => e.properties && e.properties.kind === kind).length;
+    return (cConfirmed + 0.5) / (cConfirmed + cDismissed + 1);
+  } catch (_e) {
+    return ENGAGEMENT_NEUTRAL_PRIOR;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// isThrottledKind -- CONTEXT.md D-19 dismissal-rate canary.
+//
+// Returns true if the per-kind dismissal rate over the rolling D19_FIRE_WINDOW
+// most-recent fires exceeds D19_DISMISSAL_THRESHOLD (with D19_MIN_SAMPLE floor
+// to avoid throttling on small populations).
+//
+// Implementation:
+//   1. Read breakthrough_surfaced + breakthrough_dismissed events for the kind
+//      via navigation.findRecentChanges (Canon Part 9 chokepoint).
+//   2. Take the most-recent D19_FIRE_WINDOW surfaces for the kind.
+//   3. Match dismisses against the surfaced breakthrough_ids (only dismisses
+//      that targeted a fire in the window count).
+//   4. If fired.length < D19_MIN_SAMPLE, return false (statistical floor).
+//   5. Compute rate = dismissed_in_window / fired.length. Return rate > D19_DISMISSAL_THRESHOLD.
+//
+// Graceful degradation: missing/invalid roomState -> false (not throttled).
+// Chokepoint throw -> false (fail-open; never lock out a detector on infra hiccup).
+// ---------------------------------------------------------------------------
+function isThrottledKind(kind, roomState) {
+  try {
+    if (!roomState || !roomState.db) return false;
+    const since = Date.now() - (PRIOR_WINDOW_DAYS * DAY_MS);
+    const surfaced = navigation.findRecentChanges(roomState.db, since, {
+      eventType: 'breakthrough_surfaced',
+      limit: PRIOR_QUERY_LIMIT,
+    }) || [];
+    const dismissed = navigation.findRecentChanges(roomState.db, since, {
+      eventType: 'breakthrough_dismissed',
+      limit: PRIOR_QUERY_LIMIT,
+    }) || [];
+    // Filter by kind and take most-recent D19_FIRE_WINDOW fires (findRecentChanges
+    // already returns rows ORDER BY created_at DESC).
+    const fired = surfaced
+      .filter((e) => e.properties && e.properties.kind === kind)
+      .slice(0, D19_FIRE_WINDOW);
+    if (fired.length < D19_MIN_SAMPLE) return false;
+    // Match dismisses against the in-window fire ids. Only dismisses that target
+    // a fire in the window count; a dismiss for an out-of-window fire is noise.
+    const fireIds = new Set(
+      fired
+        .map((e) => e.properties && e.properties.breakthrough_id)
+        .filter((id) => typeof id === 'string' && id.length > 0)
+    );
+    const dismissedInWindow = dismissed.filter(
+      (e) => e.properties && e.properties.kind === kind &&
+             typeof e.properties.breakthrough_id === 'string' &&
+             fireIds.has(e.properties.breakthrough_id)
+    ).length;
+    const rate = dismissedInWindow / fired.length;
+    return rate > D19_DISMISSAL_THRESHOLD;
+  } catch (_e) {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// scoreBreakthrough -- the 5-component formula (CONTEXT.md D-12 verbatim).
+//
+// score = W.confidence * candidate.confidence
+//       + W.recency * recencyDecay(candidate.detected_at, nowMs)
+//       + W.differential * candidate.differential
+//       + W.artifact_count_log * artifactCountLog(candidate.artifact_ids)
+//       + W.user_engagement_prior * getUserEngagementPrior(candidate.kind, roomState)
+//
+// Each component is independently bounded; the weighted sum is bounded in [0, 1]
+// (assuming candidate.confidence and candidate.differential are themselves in
+// [0, 1] -- the detectors enforce this via the buildCandidate clip in Plan 120-00).
+//
+// Graceful degradation: null/non-object candidate -> 0. Missing fields default
+// to 0 (or to nowMs for detected_at -> decay=1.0). The function must NEVER throw.
+// ---------------------------------------------------------------------------
+function scoreBreakthrough(candidate, roomState, nowMs) {
+  if (!candidate || typeof candidate !== 'object') return 0;
+  const conf = (typeof candidate.confidence === 'number') ? candidate.confidence : 0;
+  const diff = (typeof candidate.differential === 'number') ? candidate.differential : 0;
+  const now = (typeof nowMs === 'number' && Number.isFinite(nowMs)) ? nowMs : Date.now();
+  const recency = recencyDecay(
+    (typeof candidate.detected_at === 'number') ? candidate.detected_at : now,
+    now
+  );
+  const acLog = artifactCountLog(candidate.artifact_ids);
+  const engagement = getUserEngagementPrior(candidate.kind, roomState);
+  const W = SCORING_WEIGHTS;
+  return (W.confidence * conf)
+    + (W.recency * recency)
+    + (W.differential * diff)
+    + (W.artifact_count_log * acLog)
+    + (W.user_engagement_prior * engagement);
+}
+
+// ---------------------------------------------------------------------------
+// rankBreakthroughs -- stable sort by score descending; ties broken by
+// detected_at descending (newer wins). Each ranked item is shallow-cloned with
+// a numeric `score` property attached.
+// ---------------------------------------------------------------------------
+function rankBreakthroughs(candidates, roomState, nowMs) {
+  if (!Array.isArray(candidates)) return [];
+  const now = (typeof nowMs === 'number' && Number.isFinite(nowMs)) ? nowMs : Date.now();
+  const scored = candidates.map(function (c) {
+    return { candidate: c, score: scoreBreakthrough(c, roomState, now) };
+  });
+  scored.sort(function (a, b) {
+    if (b.score !== a.score) return b.score - a.score;
+    // Tie-break: newer detected_at wins (descending). Missing detected_at sorts
+    // last (treat as 0).
+    const aTs = (a.candidate && typeof a.candidate.detected_at === 'number') ? a.candidate.detected_at : 0;
+    const bTs = (b.candidate && typeof b.candidate.detected_at === 'number') ? b.candidate.detected_at : 0;
+    return bTs - aTs;
+  });
+  return scored.map(function (s) {
+    return Object.assign({}, s.candidate, { score: s.score });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// pickTopWithAffordance -- CONTEXT.md D-11 verbatim: surface the top-1; expose
+// the rest as a "More breakthroughs (N)" affordance count + the queued list.
+//
+// Returns { top: <highest-scoring | null>, more_count: <N | 0>, queued: <[]> }.
+// ---------------------------------------------------------------------------
+function pickTopWithAffordance(candidates, roomState, nowMs) {
+  const ranked = rankBreakthroughs(candidates, roomState, nowMs);
+  if (ranked.length === 0) return { top: null, more_count: 0, queued: [] };
+  return {
+    top: ranked[0],
+    more_count: ranked.length - 1,
+    queued: ranked.slice(1),
+  };
+}
+
+module.exports = {
+  scoreBreakthrough: scoreBreakthrough,
+  rankBreakthroughs: rankBreakthroughs,
+  pickTopWithAffordance: pickTopWithAffordance,
+  getUserEngagementPrior: getUserEngagementPrior,
+  isThrottledKind: isThrottledKind,
+  recencyDecay: recencyDecay,
+  artifactCountLog: artifactCountLog,
+  SCORING_WEIGHTS: SCORING_WEIGHTS,
+  RECENCY_HALF_LIFE_DAYS: RECENCY_HALF_LIFE_DAYS,
+  ENGAGEMENT_NEUTRAL_PRIOR: ENGAGEMENT_NEUTRAL_PRIOR,
+  D19_DISMISSAL_THRESHOLD: D19_DISMISSAL_THRESHOLD,
+  D19_FIRE_WINDOW: D19_FIRE_WINDOW,
+  D19_MIN_SAMPLE: D19_MIN_SAMPLE,
+};