@yemi33/minions 0.1.2424 → 0.1.2426

package/engine/memory-store.js

@@ -3,12 +3,21 @@
 const crypto = require('crypto');
 const { getDb, withTransaction, prepareCached } = require('./db');
 const { emitStateEvent } = require('./db-events');
+const reviewLearning = require('./review-learning');
 
 const MEMORY_TYPES = new Set(['semantic', 'episodic', 'procedural']);
 const SCOPE_TYPES = new Set(['global', 'project', 'agent']);
-const STATUSES = new Set(['active', 'superseded', 'retracted', 'expired']);
+const STATUSES = new Set(['active', 'candidate', 'superseded', 'retracted', 'expired']);
+const ACTIONS = new Set(['pin', 'retract', 'restore']);
 const TRUST_LEVELS = new Set(['human', 'system', 'agent', 'external']);
-const MAX_RETRIEVAL_RUNS = 5000;
+// Source-bound identity fields that a candidate transition must never allow a
+// caller to rewrite through `options` — they bind the stored candidate to its
+// finding/PR/author provenance and are reapplied from the stored row.
+const IMMUTABLE_CANDIDATE_METADATA = Object.freeze([
+  'kind', 'findingKey', 'prId', 'authorAgent', 'reviewerAgent', 'sourceHash',
+]);
+const MAX_RETRIEVAL_RUNS = reviewLearning.REVIEW_LEARNING_BOUNDS.retrievalRuns;
+const MAX_LIFECYCLE_EVENTS = reviewLearning.REVIEW_LEARNING_BOUNDS.lifecycleEvents;
 const QUERY_STOP_WORDS = new Set([
   'a', 'an', 'and', 'are', 'as', 'at', 'be', 'by', 'for', 'from', 'in', 'is',
   'it', 'of', 'on', 'or', 'that', 'the', 'this', 'to', 'with',
@@ -113,13 +122,24 @@ function upsertMemoryRecord(input) {
   const record = _normalize(input);
   const db = getDb();
   withTransaction(db, () => {
-    if (!record.supersedesId) {
+    if (record.status === 'active') {
       const prior = db.prepare(`
         SELECT id FROM memory_records
-        WHERE source_type=? AND source_ref=? AND status='active' AND content_hash<>?
-        ORDER BY updated_at DESC LIMIT 1
-      `).get(record.sourceType, record.sourceRef, record.contentHash);
-      if (prior) record.supersedesId = prior.id;
+        WHERE source_type=? AND source_ref=? AND status='active'
+          AND content_hash<>? AND id<>?
+        ORDER BY updated_at DESC, id LIMIT 1
+      `).get(record.sourceType, record.sourceRef, record.contentHash, record.id);
+      if (!record.supersedesId && prior) record.supersedesId = prior.id;
+      if (prior) {
+        db.prepare(`
+          UPDATE memory_records
+          SET status='superseded', valid_to=?, superseded_by=?, updated_at=?
+          WHERE source_type=? AND source_ref=? AND status='active' AND id<>?
+        `).run(
+          record.validFrom, record.id, record.updatedAt,
+          record.sourceType, record.sourceRef, record.id,
+        );
+      }
     }
     if (record.supersedesId) {
       db.prepare(`
@@ -174,37 +194,97 @@ function getMemoryRecord(id) {
 function updateMemoryRecordState(id, action) {
   const recordId = String(id || '').trim();
   if (!recordId) throw new TypeError('memory record id is required');
-  if (!['pin', 'retract', 'restore'].includes(action)) {
+  if (!ACTIONS.has(action)) {
     throw new TypeError(`unsupported memory action: ${action}`);
   }
-  if (!getMemoryRecord(recordId)) return null;
+  const existing = getMemoryRecord(recordId);
+  if (!existing) return null;
+  if (existing.status === 'candidate' && action !== 'retract') {
+    throw new TypeError(`memory candidate ${recordId} requires a verified disposition transition`);
+  }
 
   const db = getDb();
   const now = Date.now();
-  if (action === 'pin') {
-    db.prepare(`
-      UPDATE memory_records
-      SET trust='human', importance=1, confidence=MAX(confidence, 0.9),
-          status='active', valid_to=NULL, superseded_by=NULL, updated_at=?
-      WHERE id=?
-    `).run(now, recordId);
-  } else if (action === 'restore') {
-    db.prepare(`
-      UPDATE memory_records
-      SET status='active', valid_to=NULL, superseded_by=NULL, updated_at=?
-      WHERE id=?
-    `).run(now, recordId);
-  } else {
-    db.prepare(`
-      UPDATE memory_records
-      SET status='retracted', valid_to=?, updated_at=?
-      WHERE id=?
-    `).run(now, now, recordId);
-  }
+  // Detect whether the operator action is a real state transition. Idempotency
+  // of human actions (AC: "repeated operator actions do not duplicate lifecycle
+  // events") is provided by only emitting a lifecycle event when the record
+  // actually changed status/trust; re-applying the same action is a no-op event.
+  const changed = action === 'pin'
+    ? !(existing.trust === 'human' && existing.status === 'active'
+        && existing.validTo == null && existing.supersededBy == null)
+    : action === 'restore'
+      ? (existing.status !== 'active' || existing.validTo != null || existing.supersededBy != null)
+      : existing.status !== 'retracted';
+  withTransaction(db, () => {
+    if (action === 'pin') {
+      _supersedeOtherActiveVersions(db, existing, now);
+      db.prepare(`
+        UPDATE memory_records
+        SET trust='human', importance=1, confidence=MAX(confidence, 0.9),
+            status='active', valid_to=NULL, superseded_by=NULL, updated_at=?
+        WHERE id=?
+      `).run(now, recordId);
+    } else if (action === 'restore') {
+      _supersedeOtherActiveVersions(db, existing, now);
+      db.prepare(`
+        UPDATE memory_records
+        SET status='active', valid_to=NULL, superseded_by=NULL, updated_at=?
+        WHERE id=?
+      `).run(now, recordId);
+    } else {
+      db.prepare(`
+        UPDATE memory_records
+        SET status='retracted', valid_to=?, updated_at=?
+        WHERE id=?
+      `).run(now, now, recordId);
+    }
+  });
   emitStateEvent('memory_records', { id: recordId, action });
+  // Every operator pin/retract/restore of a review-learning record emits one
+  // compact lifecycle event (pinned/retracted/restored). The `changed` gate
+  // provides idempotency (repeated actions do not duplicate events); tagging
+  // project/area from the record (area || 'general') keeps the retracted/restored
+  // events in the same (project, area) group as the original `created` event so
+  // the diagnostics rollout aggregates and operator modal timeline (P-1ed2fb5f)
+  // report accurate counts.
+  if (changed && existing.sourceType === reviewLearning.REVIEW_LEARNING_SOURCE_TYPE) {
+    // Best-effort: an audit event must never break the operator control itself.
+    try {
+      recordMemoryLifecycleEvent({
+        eventType: reviewLearning.REVIEW_LEARNING_HUMAN_ACTION_EVENTS[action],
+        memoryId: recordId,
+        findingKey: existing.sourceRef,
+        project: existing.scopeKey,
+        agent: 'operator',
+        area: existing.metadata?.area || 'general',
+        disposition: existing.metadata?.disposition || null,
+        // A per-transition timestamp keeps a legitimate retract→restore→retract
+        // cycle as distinct events while pure replays are gated out above.
+        identity: `operator:${action}:${now}`,
+        metadata: { action, trigger: 'operator', priorStatus: existing.status },
+        createdAt: now,
+      });
+    } catch (err) {
+      emitStateEvent('memory_records', { id: recordId, action, lifecycleEventError: err.message });
+    }
+  }
   return getMemoryRecord(recordId);
 }
 
+// Reactivating a versioned record (pin/restore) must preserve the
+// single-active-version invariant that upsertMemoryRecord already enforces on
+// insert: supersede any OTHER active version sharing the same source lineage
+// (source_type + source_ref — e.g. a review-learning finding key) so restoring
+// or pinning an older version can never leave two active rows recallable.
+function _supersedeOtherActiveVersions(db, record, now) {
+  if (!record || record.sourceRef == null || String(record.sourceRef).trim() === '') return;
+  db.prepare(`
+    UPDATE memory_records
+    SET status='superseded', valid_to=?, superseded_by=?, updated_at=?
+    WHERE source_type=? AND source_ref=? AND status='active' AND id<>?
+  `).run(now, record.id, now, record.sourceType, record.sourceRef, record.id);
+}
+
 function listMemoryRecords(filters = {}) {
   const where = [];
   const args = [];
@@ -213,6 +293,8 @@ function listMemoryRecords(filters = {}) {
     ['memory_type', filters.memoryType],
     ['scope_type', filters.scopeType],
     ['scope_key', filters.scopeKey],
+    ['source_type', filters.sourceType],
+    ['source_ref', filters.sourceRef || filters.findingKey],
   ]) {
     if (value == null || value === '') continue;
     where.push(`${column}=?`);
@@ -242,6 +324,14 @@ function searchMemoryRecords(query, options = {}) {
     "(m.memory_type<>'procedural' OR m.trust IN ('human','system'))",
   ];
   const args = [match];
+  // Review-learning records are recalled exclusively through the dedicated
+  // deterministic project+audience path (retrieveApplicableReviewLearnings).
+  // They are unconditionally excluded from generic FTS-driven recall so a
+  // review lesson can never leak into the generic Relevant Memory pack. The
+  // operator inspection endpoint opts back in via includeReviewLearning.
+  if (!options.includeReviewLearning) {
+    where.push(`m.source_type<>'${reviewLearning.REVIEW_LEARNING_SOURCE_TYPE}'`);
+  }
   const statuses = Array.isArray(options.statuses)
     ? options.statuses.filter(status => STATUSES.has(status))
     : ['active'];
@@ -267,6 +357,24 @@ function searchMemoryRecords(query, options = {}) {
       args.push(...types);
     }
   }
+  // Diagnostics filters (P-1ed2fb5f). Applied inside the SQL WHERE so the LIMIT
+  // is honored after narrowing — post-filtering would silently drop matches.
+  if (options.sourceType) {
+    where.push('m.source_type=?');
+    args.push(String(options.sourceType));
+  }
+  if (options.findingKey) {
+    where.push('m.source_ref=?');
+    args.push(String(options.findingKey));
+  }
+  if (options.author) {
+    where.push("json_extract(m.metadata,'$.authorAgent')=?");
+    args.push(String(options.author));
+  }
+  if (options.audience) {
+    where.push("json_extract(m.metadata,'$.audience')=?");
+    args.push(String(options.audience));
+  }
   const limit = Math.max(1, Math.min(200, Number(options.limit) || 50));
   args.push(limit);
   // CROSS JOIN pins FTS as the outer loop; Node 22's SQLite otherwise prefers
@@ -320,25 +428,109 @@ function supersedeMatchingRecords(options = {}) {
   return changed;
 }
 
-function recordRetrievalRun(run) {
+function _boundedRetrievalText(value, maxBytes, label) {
+  if (value == null || String(value).trim() === '') return null;
+  return reviewLearning.redactBoundedText(value, maxBytes, label);
+}
+
+function _retrievalRow(row) {
+  if (!row) return null;
+  return {
+    id: row.id,
+    workItemId: row.work_item_id,
+    dispatchId: row.dispatch_id,
+    project: row.project,
+    agent: row.agent,
+    retrievalKind: row.retrieval_kind || 'general',
+    query: row.query,
+    candidateCount: row.candidate_count,
+    selectedCount: row.selected_count,
+    selectedBytes: row.selected_bytes,
+    durationMs: row.duration_ms,
+    shadow: row.shadow === 1,
+    selectedIds: _parseJson(row.selected_ids, []),
+    decisionTrace: _parseJson(row.decision_trace, []),
+    createdAt: row.created_at,
+  };
+}
+
+function recordRetrievalRun(run = {}) {
+  reviewLearning.assertNoProhibitedReviewPayload(run);
   const db = getDb();
+  const selectedIds = reviewLearning.normalizeSelectedIds(run.selectedIds);
+  const decisionTrace = reviewLearning.normalizeDecisionTrace(run.decisionTrace);
+  const retrievalKind = reviewLearning.normalizeRetrievalKind(run.retrievalKind);
+  const createdAt = Number.isFinite(Number(run.createdAt)) ? Number(run.createdAt) : Date.now();
+  let insertedId;
   withTransaction(db, () => {
-    db.prepare(`
+    const result = db.prepare(`
       INSERT INTO memory_retrieval_runs (
-        work_item_id, project, agent, query, candidate_count, selected_count,
-        selected_bytes, duration_ms, shadow, created_at
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        work_item_id, dispatch_id, project, agent, retrieval_kind, query,
+        candidate_count, selected_count, selected_bytes, duration_ms, shadow,
+        selected_ids, decision_trace, created_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `).run(
-      run.workItemId || null, run.project || null, run.agent || null,
-      String(run.query || ''), Number(run.candidateCount) || 0,
-      Number(run.selectedCount) || 0, Number(run.selectedBytes) || 0,
-      Number(run.durationMs) || 0, run.shadow ? 1 : 0, Date.now(),
+      _boundedRetrievalText(run.workItemId, 320, 'retrieval work item id'),
+      _boundedRetrievalText(run.dispatchId, 320, 'retrieval dispatch id'),
+      _boundedRetrievalText(run.project, 120, 'retrieval project'),
+      _boundedRetrievalText(run.agent, 96, 'retrieval agent'),
+      retrievalKind,
+      reviewLearning.redactBoundedText(
+        run.query || '',
+        reviewLearning.REVIEW_LEARNING_BOUNDS.queryBytes,
+        'retrieval query',
+      ),
+      Math.max(0, Math.min(1000000, Math.floor(Number(run.candidateCount) || 0))),
+      Math.max(0, Math.min(1000000, Math.floor(Number(run.selectedCount) || 0))),
+      Math.max(0, Math.min(100000000, Math.floor(Number(run.selectedBytes) || 0))),
+      Math.max(0, Math.min(3600000, Number(run.durationMs) || 0)),
+      run.shadow ? 1 : 0,
+      _json(selectedIds, []),
+      _json(decisionTrace, []),
+      createdAt,
     );
+    insertedId = result.lastInsertRowid;
     db.prepare(`
       DELETE FROM memory_retrieval_runs
       WHERE id NOT IN (SELECT id FROM memory_retrieval_runs ORDER BY id DESC LIMIT ?)
     `).run(MAX_RETRIEVAL_RUNS);
   });
+  return _retrievalRow(db.prepare('SELECT * FROM memory_retrieval_runs WHERE id=?').get(insertedId));
+}
+
+function getLatestRetrievalTrace(filters = {}) {
+  const where = [];
+  const args = [];
+  for (const [column, value] of [
+    ['dispatch_id', filters.dispatchId],
+    ['work_item_id', filters.workItemId],
+    ['retrieval_kind', filters.retrievalKind],
+    ['project', filters.project],
+  ]) {
+    if (value == null || String(value).trim() === '') continue;
+    where.push(`${column}=?`);
+    args.push(String(value));
+  }
+  const sql = `SELECT * FROM memory_retrieval_runs${where.length ? ` WHERE ${where.join(' AND ')}` : ''} ORDER BY id DESC LIMIT 1`;
+  return _retrievalRow(prepareCached(getDb(), sql).get(...args));
+}
+
+function listRetrievalTraces(filters = {}) {
+  const where = [];
+  const args = [];
+  for (const [column, value] of [
+    ['dispatch_id', filters.dispatchId],
+    ['work_item_id', filters.workItemId],
+    ['retrieval_kind', filters.retrievalKind],
+    ['project', filters.project],
+  ]) {
+    if (value == null || String(value).trim() === '') continue;
+    where.push(`${column}=?`);
+    args.push(String(value));
+  }
+  const limit = Math.max(1, Math.min(200, Number(filters.limit) || 50));
+  const sql = `SELECT * FROM memory_retrieval_runs${where.length ? ` WHERE ${where.join(' AND ')}` : ''} ORDER BY id DESC LIMIT ?`;
+  return prepareCached(getDb(), sql).all(...args, limit).map(_retrievalRow);
 }
 
 function getRetrievalStats() {
@@ -352,10 +544,585 @@ function getRetrievalStats() {
   `).get();
 }
 
+function upsertReviewLearningCandidate(input) {
+  const record = _normalize(reviewLearning.buildCandidateMemoryRecord(input));
+  const db = getDb();
+  let result;
+  withTransaction(db, () => {
+    const existing = _row(prepareCached(db, 'SELECT * FROM memory_records WHERE id=?').get(record.id));
+    if (existing && existing.status !== 'candidate') {
+      result = existing;
+      return;
+    }
+    if (existing) {
+      record.createdAt = existing.createdAt;
+      record.validFrom = existing.validFrom;
+      record.validTo = existing.validTo;
+      record.supersedesId = existing.supersedesId;
+      record.supersededBy = existing.supersededBy;
+      record.metadata = {
+        ...existing.metadata,
+        ...record.metadata,
+        candidateState: existing.metadata.candidateState || record.metadata.candidateState,
+        dispatchId: existing.metadata.dispatchId || record.metadata.dispatchId || null,
+        workItemId: existing.metadata.workItemId || record.metadata.workItemId || null,
+      };
+    }
+    result = upsertMemoryRecord(record);
+  });
+  return result;
+}
+
+function upsertReviewLearningLesson(input) {
+  const record = _normalize(reviewLearning.buildLessonMemoryRecord(input));
+  const existing = getMemoryRecord(record.id);
+  if (existing?.status === 'active') {
+    record.createdAt = existing.createdAt;
+    record.validFrom = existing.validFrom;
+    record.supersedesId = existing.supersedesId;
+    record.supersededBy = existing.supersededBy;
+  }
+  return upsertMemoryRecord(record);
+}
+
+function listReviewLearningCandidates(filters = {}) {
+  const records = listMemoryRecords({
+    status: 'candidate',
+    scopeType: filters.project ? 'project' : filters.scopeType,
+    scopeKey: filters.project || filters.scopeKey,
+    limit: Math.max(1, Math.min(500, Number(filters.limit) || 100)),
+  });
+  return records.filter(record => (
+    record.sourceType === reviewLearning.REVIEW_LEARNING_SOURCE_TYPE
+    || record.metadata.legacyUnverified === true
+  ) && (!filters.findingKey
+    || record.sourceRef === filters.findingKey
+    || record.metadata.findingKey === filters.findingKey));
+}
+
+function listActiveReviewLearnings(filters = {}) {
+  const where = [
+    "source_type='review-learning'",
+    "memory_type='procedural'",
+    "scope_type='project'",
+    "status='active'",
+  ];
+  const args = [];
+  if (filters.project) {
+    where.push('scope_key=?');
+    args.push(reviewLearning.normalizeProjectKey(filters.project));
+  }
+  if (filters.findingKey) {
+    where.push('source_ref=?');
+    args.push(reviewLearning.normalizeFindingKey(filters.findingKey));
+  }
+  const limit = Math.max(1, Math.min(500, Number(filters.limit) || 100));
+  const sql = `SELECT * FROM memory_records WHERE ${where.join(' AND ')} ORDER BY updated_at DESC, id LIMIT ?`;
+  const records = prepareCached(getDb(), sql).all(...args, limit).map(_row);
+  if (!filters.audience) return records;
+  return records.filter(record => record.metadata.audience === filters.audience);
+}
+
+function transitionReviewLearningCandidate(findingKey, disposition, options = {}) {
+  reviewLearning.assertNoProhibitedReviewPayload(options);
+  const normalizedFindingKey = reviewLearning.normalizeFindingKey(findingKey);
+  const transition = reviewLearning.candidateTransitionFor(disposition);
+  const lessonId = String(options.lessonId || '').trim();
+  if (transition.requiresLesson && !lessonId) {
+    throw new TypeError(`${transition.disposition} candidate transition requires a lesson id`);
+  }
+  const db = getDb();
+  const [findingProject] = normalizedFindingKey.split('|');
+  const now = Date.now();
+  const updated = [];
+  withTransaction(db, () => {
+    const rows = db.prepare(`
+      SELECT * FROM memory_records
+      WHERE source_type='review-learning' AND source_ref=? AND status='candidate'
+        AND scope_type='project' AND scope_key=?
+      ORDER BY updated_at DESC, id
+    `).all(normalizedFindingKey, findingProject);
+    if (!rows.length) return;
+    if (transition.requiresLesson) {
+      const lesson = db.prepare(`
+        SELECT * FROM memory_records
+        WHERE id=? AND source_type='review-learning' AND memory_type='procedural'
+          AND scope_type='project' AND scope_key=? AND source_ref=? AND status='active'
+      `).get(lessonId, findingProject, normalizedFindingKey);
+      const lessonMetadata = lesson ? _parseJson(lesson.metadata, {}) : {};
+      if (
+        !lesson
+        || lessonMetadata.kind !== 'review-learning-lesson'
+        || lessonMetadata.findingKey !== normalizedFindingKey
+      ) {
+        throw new TypeError(
+          `${transition.disposition} candidate transition requires an active review-learning lesson for the same finding and project`,
+        );
+      }
+    }
+    const statement = db.prepare(`
+      UPDATE memory_records
+      SET status=?, valid_to=?, superseded_by=?, metadata=?, updated_at=?
+      WHERE id=? AND status='candidate'
+    `);
+    for (const row of rows) {
+      const storedMetadata = _parseJson(row.metadata, {});
+      const provenance = {};
+      for (const key of IMMUTABLE_CANDIDATE_METADATA) {
+        if (storedMetadata[key] !== undefined) provenance[key] = storedMetadata[key];
+      }
+      const metadata = reviewLearning.normalizeReviewMetadata({
+        ...storedMetadata,
+        ...options,
+        ...(transition.requiresLesson ? { lessonId } : {}),
+        disposition: transition.disposition,
+        candidateState: transition.candidateState,
+        // Reapply source-bound identity last so caller `options` can never
+        // rewrite the candidate's immutable provenance during a transition.
+        ...provenance,
+      });
+      const result = statement.run(
+        transition.status,
+        transition.terminal ? now : row.valid_to,
+        transition.requiresLesson ? lessonId : row.superseded_by,
+        _json(metadata, {}),
+        now,
+        row.id,
+      );
+      if (result.changes) updated.push(row.id);
+    }
+  });
+  if (updated.length) {
+    emitStateEvent('memory_records', {
+      findingKey: normalizedFindingKey,
+      disposition: transition.disposition,
+      changed: updated.length,
+    });
+  }
+  return updated.map(getMemoryRecord);
+}
+
+// Quarantine an active review-learning lesson through the retracted lifecycle.
+// Used by evidence-backed contradictions (agent-driven) and distinct from the
+// generic operator control in updateMemoryRecordState. Provenance is retained:
+// only status/valid_to move and the contradiction detail is merged into
+// metadata without dropping existing keys. Idempotent — retracting an
+// already-retracted lesson is a no-op.
+function retractReviewLearningLesson(lessonId, options = {}) {
+  reviewLearning.assertNoProhibitedReviewPayload(options);
+  const recordId = String(lessonId || '').trim();
+  if (!recordId) throw new TypeError('review-learning lesson id is required');
+  const db = getDb();
+  const now = Date.now();
+  let changed = false;
+  let mergedMetadata = null;
+  withTransaction(db, () => {
+    const row = db.prepare(`
+      SELECT * FROM memory_records
+      WHERE id=? AND source_type='review-learning' AND memory_type='procedural'
+        AND status='active'
+    `).get(recordId);
+    if (!row) return;
+    const metadata = reviewLearning.normalizeReviewMetadata({
+      ..._parseJson(row.metadata, {}),
+      retractReason: options.reason || 'contradicted',
+      ...(options.contradictedBy ? { contradictedBy: options.contradictedBy } : {}),
+      ...(options.dispatchId ? { retractDispatchId: options.dispatchId } : {}),
+      ...(options.workItemId ? { retractWorkItemId: options.workItemId } : {}),
+      ...(Array.isArray(options.evidenceKinds) && options.evidenceKinds.length
+        ? { retractEvidenceKinds: options.evidenceKinds }
+        : {}),
+    });
+    const result = db.prepare(`
+      UPDATE memory_records
+      SET status='retracted', valid_to=?, metadata=?, updated_at=?
+      WHERE id=? AND status='active'
+    `).run(now, _json(metadata, {}), now, recordId);
+    changed = result.changes > 0;
+    if (changed) mergedMetadata = metadata;
+  });
+  if (changed) {
+    emitStateEvent('memory_records', {
+      id: recordId,
+      status: 'retracted',
+      reason: options.reason || 'contradicted',
+    });
+  }
+  return { record: getMemoryRecord(recordId), changed, metadata: mergedMetadata };
+}
+
+function _lifecycleRow(row) {
+  if (!row) return null;
+  return {
+    id: row.id,
+    eventKey: row.event_key,
+    eventType: row.event_type,
+    memoryId: row.memory_id,
+    findingKey: row.finding_key,
+    project: row.project,
+    agent: row.agent,
+    area: row.area,
+    disposition: row.disposition,
+    workItemId: row.work_item_id,
+    dispatchId: row.dispatch_id,
+    metadata: _parseJson(row.metadata, {}),
+    createdAt: row.created_at,
+  };
+}
+
+function recordMemoryLifecycleEvent(input) {
+  const event = reviewLearning.normalizeLifecycleEvent(input);
+  const db = getDb();
+  let inserted = false;
+  withTransaction(db, () => {
+    const result = db.prepare(`
+      INSERT OR IGNORE INTO memory_lifecycle_events (
+        event_key, event_type, memory_id, finding_key, project, agent, area,
+        disposition, work_item_id, dispatch_id, metadata, created_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      event.eventKey, event.eventType, event.memoryId, event.findingKey,
+      event.project, event.agent, event.area, event.disposition,
+      event.workItemId, event.dispatchId, _json(event.metadata, {}),
+      event.createdAt,
+    );
+    inserted = result.changes > 0;
+    db.prepare(`
+      DELETE FROM memory_lifecycle_events
+      WHERE id NOT IN (
+        SELECT id FROM memory_lifecycle_events ORDER BY id DESC LIMIT ?
+      )
+    `).run(MAX_LIFECYCLE_EVENTS);
+  });
+  const stored = _lifecycleRow(
+    db.prepare('SELECT * FROM memory_lifecycle_events WHERE event_key=?').get(event.eventKey),
+  );
+  if (inserted) emitStateEvent('memory_lifecycle_events', { eventKey: event.eventKey, eventType: event.eventType });
+  return stored;
+}
+
+function listMemoryLifecycleEvents(filters = {}) {
+  const where = [];
+  const args = [];
+  for (const [column, value] of [
+    ['event_type', filters.eventType],
+    ['memory_id', filters.memoryId],
+    ['finding_key', filters.findingKey],
+    ['project', filters.project],
+    ['agent', filters.agent],
+    ['area', filters.area],
+    ['disposition', filters.disposition],
+    ['work_item_id', filters.workItemId],
+    ['dispatch_id', filters.dispatchId],
+  ]) {
+    if (value == null || String(value).trim() === '') continue;
+    where.push(`${column}=?`);
+    args.push(String(value));
+  }
+  const limit = Math.max(1, Math.min(500, Number(filters.limit) || 100));
+  const sql = `SELECT * FROM memory_lifecycle_events${where.length ? ` WHERE ${where.join(' AND ')}` : ''} ORDER BY id DESC LIMIT ?`;
+  return prepareCached(getDb(), sql).all(...args, limit).map(_lifecycleRow);
+}
+
+function pruneMemoryLifecycleEvents(options = {}) {
+  const maxRows = Math.max(1, Math.min(
+    MAX_LIFECYCLE_EVENTS,
+    Math.floor(Number(options.maxRows) || MAX_LIFECYCLE_EVENTS),
+  ));
+  // Compact lifecycle events are retained for at most one year (in addition to
+  // the row cap) and are deliberately decoupled from KB file TTL (P-1ed2fb5f).
+  const maxAgeMs = Number.isFinite(Number(options.maxAgeMs))
+    ? Math.max(0, Number(options.maxAgeMs))
+    : reviewLearning.REVIEW_LEARNING_BOUNDS.lifecycleEventMaxAgeMs;
+  const now = Number.isFinite(Number(options.now)) ? Number(options.now) : Date.now();
+  const db = getDb();
+  let changed = 0;
+  withTransaction(db, () => {
+    changed += Number(db.prepare(`
+      DELETE FROM memory_lifecycle_events
+      WHERE id NOT IN (
+        SELECT id FROM memory_lifecycle_events ORDER BY id DESC LIMIT ?
+      )
+    `).run(maxRows).changes) || 0;
+    if (maxAgeMs > 0) {
+      changed += Number(db.prepare(`
+        DELETE FROM memory_lifecycle_events WHERE created_at < ?
+      `).run(now - maxAgeMs).changes) || 0;
+    }
+  });
+  if (changed) emitStateEvent('memory_lifecycle_events', { pruned: changed });
+  return changed;
+}
+
+// Unresolved review-learning candidates (still in the `candidate` state) expire
+// after 180 days so a never-promoted finding does not linger forever. Active
+// procedural lessons are untouched — they persist until superseded or retracted
+// (P-1ed2fb5f, acceptance criterion 5).
+function expireStaleReviewLearningCandidates(options = {}) {
+  const maxAgeMs = Number.isFinite(Number(options.maxAgeMs))
+    ? Math.max(0, Number(options.maxAgeMs))
+    : reviewLearning.REVIEW_LEARNING_BOUNDS.candidateExpiryMs;
+  const now = Number.isFinite(Number(options.now)) ? Number(options.now) : Date.now();
+  const cutoff = now - maxAgeMs;
+  const db = getDb();
+  let changed = 0;
+  withTransaction(db, () => {
+    changed = Number(db.prepare(`
+      UPDATE memory_records
+      SET status='expired', valid_to=?, updated_at=?
+      WHERE status='candidate'
+        AND source_type='review-learning'
+        AND updated_at < ?
+    `).run(now, now, cutoff).changes) || 0;
+  });
+  if (changed) emitStateEvent('memory_records', { expiredCandidates: changed });
+  return changed;
+}
+
+// Bounded per-finding / per-memory event-type counters for the operator modal.
+function getReviewLearningLifecycleSummary(filters = {}) {
+  const where = [];
+  const args = [];
+  for (const [column, value] of [
+    ['finding_key', filters.findingKey],
+    ['memory_id', filters.memoryId],
+    ['project', filters.project],
+    ['agent', filters.agent],
+    ['area', filters.area],
+  ]) {
+    if (value == null || String(value).trim() === '') continue;
+    where.push(`${column}=?`);
+    args.push(String(value));
+  }
+  const rows = prepareCached(getDb(), `
+    SELECT event_type, COUNT(*) AS count
+    FROM memory_lifecycle_events
+    ${where.length ? `WHERE ${where.join(' AND ')}` : ''}
+    GROUP BY event_type
+    ORDER BY event_type
+    LIMIT 64
+  `).all(...args);
+  const counters = {};
+  let total = 0;
+  for (const row of rows) {
+    counters[row.event_type] = Number(row.count) || 0;
+    total += Number(row.count) || 0;
+  }
+  return { counters, total };
+}
+
+function getReviewLearningRolloutAggregates(options = {}) {
+  const where = [];
+  const args = [];
+  if (options.project) {
+    where.push('project=?');
+    args.push(reviewLearning.normalizeProjectKey(options.project));
+  }
+  if (options.area) {
+    where.push('area=?');
+    args.push(reviewLearning.normalizeReviewArea(options.area));
+  }
+  if (Number.isFinite(Number(options.from))) {
+    where.push('created_at>=?');
+    args.push(Number(options.from));
+  }
+  if (Number.isFinite(Number(options.to))) {
+    where.push('created_at<?');
+    args.push(Number(options.to));
+  }
+  const positive = [...reviewLearning.POSITIVE_DISPOSITIONS];
+  const sql = `
+    SELECT project, area,
+      COUNT(DISTINCT CASE
+        WHEN event_type='created' AND disposition IN (${positive.map(() => '?').join(',')})
+        THEN finding_key END
+      ) AS created_findings,
+      COUNT(DISTINCT CASE
+        WHEN event_type='retrieved' THEN finding_key END
+      ) AS retrieved_findings,
+      COUNT(DISTINCT CASE
+        WHEN event_type='applied' THEN finding_key END
+      ) AS applied_findings,
+      COUNT(DISTINCT CASE
+        WHEN event_type='retracted' THEN finding_key END
+      ) AS retracted_findings,
+      COUNT(DISTINCT CASE
+        WHEN event_type='repeated-finding' THEN finding_key END
+      ) AS repeated_findings
+    FROM memory_lifecycle_events
+    ${where.length ? `WHERE ${where.join(' AND ')}` : ''}
+    GROUP BY project, area
+    ORDER BY project, area
+    LIMIT 500
+  `;
+  const minimumSample = Math.max(1, Math.min(10000, Math.floor(Number(options.minimumSample) || 20)));
+  return prepareCached(getDb(), sql).all(...positive, ...args).map(row => {
+    const createdFindings = Number(row.created_findings) || 0;
+    const retrievedFindings = Number(row.retrieved_findings) || 0;
+    const appliedFindings = Number(row.applied_findings) || 0;
+    const retractedFindings = Number(row.retracted_findings) || 0;
+    const repeatedFindings = Number(row.repeated_findings) || 0;
+    const sampleSufficient = createdFindings >= minimumSample;
+    return {
+      project: row.project,
+      area: row.area,
+      createdFindings,
+      retrievedFindings,
+      appliedFindings,
+      retractedFindings,
+      repeatedFindings,
+      // Plan's project-and-area rollout formula: recurrence rate is the share of
+      // distinct created findings that recurred as a repeated-finding event.
+      rate: createdFindings ? repeatedFindings / createdFindings : null,
+      minimumSample,
+      sampleSufficient,
+      status: sampleSufficient ? 'measured' : 'insufficient-sample',
+    };
+  });
+}
+
+// Staged-rollout success gate (P-507157f8). Compares a capture-only baseline
+// window against the first active-recall window per project and normalized area.
+// The rollout may only claim success for a (project, area) when BOTH windows have
+// at least `minimumSample` (default 20) resolved valid findings AND the repeated
+// valid-finding rate fell by at least `minReduction` (default 0.25 = 25%). Any
+// window short of the sample floor is reported `insufficient-sample`, never a
+// success. This is the measurement the docs' expansion criteria depend on: it is
+// deliberately conservative so a small or noisy sample can never green-light
+// broadening the recall canary.
+const ROLLOUT_DEFAULT_MIN_SAMPLE = 20;
+const ROLLOUT_DEFAULT_MIN_REDUCTION = 0.25;
+
+function _rolloutAggregateKey(row) {
+  return `${row.project}\u0000${row.area}`;
+}
+
+function getReviewLearningRolloutComparison(options = {}) {
+  const minimumSample = Math.max(
+    1,
+    Math.min(10000, Math.floor(Number(options.minimumSample) || ROLLOUT_DEFAULT_MIN_SAMPLE)),
+  );
+  const rawReduction = Number(options.minReduction);
+  const minReduction = Number.isFinite(rawReduction)
+    ? Math.max(0, Math.min(1, rawReduction))
+    : ROLLOUT_DEFAULT_MIN_REDUCTION;
+  const shared = { project: options.project, area: options.area, minimumSample };
+  const baselineRows = getReviewLearningRolloutAggregates({
+    ...shared,
+    from: options.baselineFrom,
+    to: options.baselineTo,
+  });
+  const activeRows = getReviewLearningRolloutAggregates({
+    ...shared,
+    from: options.activeFrom,
+    to: options.activeTo,
+  });
+  const baselineByKey = new Map(baselineRows.map(row => [_rolloutAggregateKey(row), row]));
+  const activeByKey = new Map(activeRows.map(row => [_rolloutAggregateKey(row), row]));
+  const keys = new Set([...baselineByKey.keys(), ...activeByKey.keys()]);
+  const results = [];
+  for (const key of keys) {
+    const baseline = baselineByKey.get(key) || null;
+    const active = activeByKey.get(key) || null;
+    const [project, area] = key.split('\u0000');
+    const baselineSufficient = !!(baseline && baseline.sampleSufficient);
+    const activeSufficient = !!(active && active.sampleSufficient);
+    const baselineRate = baseline ? baseline.rate : null;
+    const activeRate = active ? active.rate : null;
+    let reduction = null;
+    let success = false;
+    let status = 'insufficient-sample';
+    if (baselineSufficient && activeSufficient) {
+      // A zero baseline rate means there was nothing to improve on; that can
+      // never satisfy a "rate fell by >=25%" claim, so it is reported as a
+      // measured non-improvement rather than a divide-by-zero success.
+      if (baselineRate > 0) {
+        reduction = (baselineRate - activeRate) / baselineRate;
+      } else {
+        reduction = 0;
+      }
+      success = baselineRate > 0 && reduction >= minReduction;
+      status = success ? 'success' : 'no-improvement';
+    }
+    results.push({
+      project,
+      area,
+      minimumSample,
+      minReduction,
+      baseline: baseline
+        ? { createdFindings: baseline.createdFindings, repeatedFindings: baseline.repeatedFindings, rate: baselineRate, sampleSufficient: baselineSufficient }
+        : { createdFindings: 0, repeatedFindings: 0, rate: null, sampleSufficient: false },
+      active: active
+        ? { createdFindings: active.createdFindings, repeatedFindings: active.repeatedFindings, rate: activeRate, sampleSufficient: activeSufficient }
+        : { createdFindings: 0, repeatedFindings: 0, rate: null, sampleSufficient: false },
+      reduction,
+      success,
+      status,
+    });
+  }
+  results.sort((a, b) => (a.project === b.project ? a.area.localeCompare(b.area) : a.project.localeCompare(b.project)));
+  return results;
+}
+
+// Distinct valid findings backing a review-learning lesson (P-192d3660).
+// A single lesson record owns exactly one finding key (its source_ref), but the
+// same generalized rule can recur across multiple PRs/findings. Those
+// recurrences are captured as `repeated-finding` lifecycle events that reference
+// the original lesson through `metadata.priorLessonId`. Promotion eligibility
+// requires at least two distinct valid findings, so we union:
+//   1. the lesson's own source_ref finding key,
+//   2. finding keys of every lifecycle event stamped with this memory id, and
+//   3. finding keys of every `repeated-finding` event pointing back at it.
+// The related memory ids (prior + newer lessons in the same cluster) are
+// returned so the queued work item can cite stable originating memory ids.
+function getReviewLearningFindingSupport(memoryId) {
+  const id = String(memoryId || '').trim();
+  const empty = { memoryId: id, findingKeys: [], distinctFindings: 0, repeatedOccurrences: 0, memoryIds: id ? [id] : [] };
+  if (!id) return empty;
+  const db = getDb();
+  const lesson = db.prepare('SELECT source_ref, metadata FROM memory_records WHERE id=?').get(id);
+  if (!lesson) return empty;
+  const findingKeys = new Set();
+  const memoryIds = new Set([id]);
+  if (lesson.source_ref) findingKeys.add(lesson.source_ref);
+  const priorOfLesson = _parseJson(lesson.metadata, {})?.priorLessonId;
+  if (priorOfLesson) memoryIds.add(String(priorOfLesson));
+
+  const direct = db.prepare(`
+    SELECT finding_key, metadata FROM memory_lifecycle_events
+    WHERE memory_id=? AND finding_key IS NOT NULL AND finding_key<>''
+  `).all(id);
+  for (const row of direct) {
+    findingKeys.add(row.finding_key);
+    const prior = _parseJson(row.metadata, {})?.priorLessonId;
+    if (prior) memoryIds.add(String(prior));
+  }
+
+  const repeated = db.prepare(`
+    SELECT finding_key, memory_id FROM memory_lifecycle_events
+    WHERE event_type='repeated-finding'
+      AND json_extract(metadata,'$.priorLessonId')=?
+      AND finding_key IS NOT NULL AND finding_key<>''
+  `).all(id);
+  for (const row of repeated) {
+    findingKeys.add(row.finding_key);
+    if (row.memory_id) memoryIds.add(String(row.memory_id));
+  }
+
+  return {
+    memoryId: id,
+    findingKeys: [...findingKeys].sort(),
+    distinctFindings: findingKeys.size,
+    repeatedOccurrences: repeated.length,
+    memoryIds: [...memoryIds].sort(),
+  };
+}
+
 module.exports = {
   MEMORY_TYPES,
   SCOPE_TYPES,
   STATUSES,
+  ACTIONS,
   upsertMemoryRecord,
   getMemoryRecord,
   updateMemoryRecordState,
@@ -364,6 +1131,22 @@ module.exports = {
   transitionMemoryRecord,
   supersedeMatchingRecords,
   recordRetrievalRun,
+  getLatestRetrievalTrace,
+  listRetrievalTraces,
   getRetrievalStats,
+  upsertReviewLearningCandidate,
+  upsertReviewLearningLesson,
+  listReviewLearningCandidates,
+  listActiveReviewLearnings,
+  transitionReviewLearningCandidate,
+  retractReviewLearningLesson,
+  recordMemoryLifecycleEvent,
+  listMemoryLifecycleEvents,
+  pruneMemoryLifecycleEvents,
+  expireStaleReviewLearningCandidates,
+  getReviewLearningLifecycleSummary,
+  getReviewLearningRolloutAggregates,
+  getReviewLearningRolloutComparison,
+  getReviewLearningFindingSupport,
   _matchQuery,
 };