memorix 1.4.1 → 1.4.2

package/src/codegraph/external-provider.ts

@@ -302,6 +302,7 @@ function providerQuality(input: {
       capabilities: {
         declarations: true,
         importHints: true,
+        localRelativeImportTargets: true,
         resolvedRelations: false,
         exactLocations: false,
       },

package/src/codegraph/store.ts

@@ -1,9 +1,14 @@
 import { randomUUID } from 'node:crypto';
+import { posix as pathPosix } from 'node:path';
 import { getDatabase } from '../store/sqlite-db.js';
 import type {
   CodeEdge,
   CodeFile,
+  CodeGraphImpactSlice,
   CodeGraphStatus,
+  CodeStateDiff,
+  CodeStateFileChange,
+  CodeStateSnapshotFile,
   CodeStateScanCompleteness,
   CodeStateSnapshot,
   CodeStateSnapshotInput,
@@ -71,6 +76,41 @@ function rowToEdge(row: any): CodeEdge {
   } as CodeEdge;
 }
 
+function resolveRelativeImportTarget(
+  sourcePath: string,
+  evidence: string | undefined,
+  fileByPath: Map<string, CodeFile>,
+): CodeFile | undefined {
+  const target = evidence?.trim().replace(/\\/g, '/');
+  if (!target?.startsWith('.')) return undefined;
+  const base = normalizeCodePath(pathPosix.normalize(pathPosix.join(pathPosix.dirname(sourcePath), target)));
+  if (!base || base === '..' || base.startsWith('../')) return undefined;
+  const candidates = [base];
+  const extensionMatch = base.match(/(\.[A-Za-z0-9]+)$/);
+  const hasExtension = Boolean(extensionMatch);
+  if (!hasExtension) {
+    const extensions = [...new Set([...fileByPath.keys()]
+      .map(path => path.match(/(\.[A-Za-z0-9]+)$/)?.[1])
+      .filter((extension): extension is string => Boolean(extension)))];
+    for (const extension of extensions) {
+      candidates.push(`${base}${extension}`, `${base}/index${extension}`);
+    }
+  } else {
+    // Node ESM projects commonly import the emitted .js path from a .ts source.
+    // Keep an exact path first, then resolve only equivalent local source forms.
+    const sourceStem = base.slice(0, -extensionMatch![1].length);
+    const sourceExtensions = extensionMatch![1] === '.js'
+      ? ['.ts', '.tsx', '.js', '.jsx']
+      : extensionMatch![1] === '.mjs'
+        ? ['.mts', '.mjs']
+        : extensionMatch![1] === '.cjs'
+          ? ['.cts', '.cjs']
+          : [];
+    for (const extension of sourceExtensions) candidates.push(`${sourceStem}${extension}`);
+  }
+  return candidates.map(candidate => fileByPath.get(candidate)).find((file): file is CodeFile => Boolean(file));
+}
+
 function rowToRef(row: any): ObservationCodeRef {
   return {
     id: row.id,
@@ -134,6 +174,22 @@ function rowToSnapshot(row: any): CodeStateSnapshot {
   } as CodeStateSnapshot;
 }
 
+function rowToSnapshotFile(row: any): CodeStateSnapshotFile {
+  return {
+    snapshotId: row.snapshotId,
+    projectId: row.projectId,
+    fileId: row.fileId,
+    path: row.path,
+    contentHash: row.contentHash,
+  };
+}
+
+function snapshotIsIncomplete(snapshot: CodeStateSnapshot): boolean {
+  return snapshot.completeness.skippedOversizedFiles > 0
+    || (snapshot.completeness.unreadableFiles ?? 0) > 0
+    || snapshot.completeness.removalScanDeferred;
+}
+
 export class CodeGraphStore {
   private db: any = null;
   private dataDir: string | null = null;
@@ -312,6 +368,7 @@ export class CodeGraphStore {
     });
 
     tx();
+    this.reconcileLocalImportTargets(projectId);
   }
 
   /**
@@ -329,7 +386,10 @@ export class CodeGraphStore {
     const changed = input.changed.filter((delta) => delta.file.projectId === projectId);
     const metadataOnly = (input.metadataOnly ?? []).filter((file) => file.projectId === projectId);
     const removedFileIds = input.removedFileIds ?? [];
-    if (changed.length === 0 && metadataOnly.length === 0 && removedFileIds.length === 0) return;
+    if (changed.length === 0 && metadataOnly.length === 0 && removedFileIds.length === 0) {
+      this.reconcileLocalImportTargets(projectId);
+      return;
+    }
 
     const staleRefsForFile = this.db.prepare(`
       UPDATE observation_code_refs
@@ -340,9 +400,18 @@ export class CodeGraphStore {
         )
       )
     `);
-    const deleteEdgesForFile = this.db.prepare(`
+    const deleteEdgesFromFile = this.db.prepare(`
+      DELETE FROM code_edges
+      WHERE projectId = ? AND fromFileId = ?
+    `);
+    const clearImportTargetsForFile = this.db.prepare(`
+      UPDATE code_edges
+      SET toFileId = NULL
+      WHERE projectId = ? AND toFileId = ? AND type = 'imports'
+    `);
+    const deleteOtherIncomingEdgesForFile = this.db.prepare(`
       DELETE FROM code_edges
-      WHERE projectId = ? AND (fromFileId = ? OR toFileId = ?)
+      WHERE projectId = ? AND toFileId = ? AND type != 'imports'
     `);
     const deleteSymbolsForFile = this.db.prepare(`DELETE FROM code_symbols WHERE projectId = ? AND fileId = ?`);
     const deleteFile = this.db.prepare(`DELETE FROM code_files WHERE projectId = ? AND id = ?`);
@@ -380,7 +449,9 @@ export class CodeGraphStore {
       const staleAt = new Date().toISOString();
       for (const fileId of removedFileIds) {
         staleRefsForFile.run(staleAt, projectId, fileId, projectId, fileId);
-        deleteEdgesForFile.run(projectId, fileId, fileId);
+        deleteEdgesFromFile.run(projectId, fileId);
+        clearImportTargetsForFile.run(projectId, fileId);
+        deleteOtherIncomingEdgesForFile.run(projectId, fileId);
         deleteSymbolsForFile.run(projectId, fileId);
         deleteFile.run(projectId, fileId);
       }
@@ -388,7 +459,9 @@ export class CodeGraphStore {
       for (const delta of changed) {
         const fileId = delta.file.id;
         staleRefsForFile.run(staleAt, projectId, fileId, projectId, fileId);
-        deleteEdgesForFile.run(projectId, fileId, fileId);
+        deleteEdgesFromFile.run(projectId, fileId);
+        clearImportTargetsForFile.run(projectId, fileId);
+        deleteOtherIncomingEdgesForFile.run(projectId, fileId);
         deleteSymbolsForFile.run(projectId, fileId);
         writeFile(delta.file);
 
@@ -429,6 +502,7 @@ export class CodeGraphStore {
       for (const file of metadataOnly) writeFile(file);
     });
     tx();
+    this.reconcileLocalImportTargets(projectId);
   }
 
   upsertObservationRefs(refs: ObservationCodeRef[]): void {
@@ -493,6 +567,26 @@ export class CodeGraphStore {
     tx();
   }
 
+  /**
+   * Lite import extraction records the original import text first. Resolve only
+   * local relative imports against the current index after each refresh, so an
+   * added or removed target cannot leave a fabricated file-to-file relation.
+   */
+  reconcileLocalImportTargets(projectId: string): void {
+    const fileById = new Map(this.listFiles(projectId).map(file => [file.id, file]));
+    const fileByPath = new Map([...fileById.values()].map(file => [file.path, file]));
+    const update = this.db.prepare('UPDATE code_edges SET toFileId = ? WHERE id = ?');
+    const tx = this.db.transaction(() => {
+      for (const edge of this.listEdges(projectId)) {
+        if (edge.type !== 'imports' || !edge.fromFileId) continue;
+        const source = fileById.get(edge.fromFileId);
+        const target = source ? resolveRelativeImportTarget(source.path, edge.evidence, fileByPath) : undefined;
+        update.run(target?.id ?? null, edge.id);
+      }
+    });
+    tx();
+  }
+
   getFile(projectId: string, path: string): CodeFile | null {
     const row = this.db.prepare(`SELECT * FROM code_files WHERE projectId = ? AND path = ?`).get(projectId, normalizeCodePath(path));
     return row ? rowToFile(row) : null;
@@ -577,6 +671,19 @@ export class CodeGraphStore {
     `).all(projectId).map(rowToRef);
   }
 
+  /** Count distinct observations whose binding to these exact files is stale. */
+  countStaleObservationRefsForFiles(projectId: string, fileIds: string[]): number {
+    const ids = [...new Set(fileIds.filter(Boolean))];
+    if (ids.length === 0) return 0;
+    const placeholders = ids.map(() => '?').join(', ');
+    const row = this.db.prepare(`
+      SELECT COUNT(DISTINCT observationId) AS count
+      FROM observation_code_refs
+      WHERE projectId = ? AND status = 'stale' AND fileId IN (${placeholders})
+    `).get(projectId, ...ids);
+    return Number(row?.count ?? 0);
+  }
+
   listReferencedSymbols(projectId: string): CodeSymbol[] {
     return this.db.prepare(`
       SELECT DISTINCT symbols.*
@@ -601,6 +708,100 @@ export class CodeGraphStore {
     ).all(projectId, safeLimit).map(rowToSnapshot);
   }
 
+  listSnapshotFiles(snapshotId: string): CodeStateSnapshotFile[] {
+    return this.db.prepare(`
+      SELECT snapshotId, projectId, fileId, path, contentHash
+      FROM code_state_snapshot_files
+      WHERE snapshotId = ?
+      ORDER BY path
+    `).all(snapshotId).map(rowToSnapshotFile);
+  }
+
+  diffSnapshots(projectId: string, fromSnapshotId: string, toSnapshotId: string): CodeStateDiff {
+    const snapshots = this.db.prepare(`
+      SELECT * FROM code_state_snapshots WHERE id IN (?, ?)
+    `).all(fromSnapshotId, toSnapshotId).map(rowToSnapshot) as CodeStateSnapshot[];
+    if (snapshots.length !== 2) {
+      return { projectId, fromSnapshotId, toSnapshotId, available: false, reason: 'missing-snapshot', changes: [] };
+    }
+    if (snapshots.some(snapshot => snapshot.projectId !== projectId)) {
+      return { projectId, fromSnapshotId, toSnapshotId, available: false, reason: 'project-mismatch', changes: [] };
+    }
+    if (snapshots.some(snapshotIsIncomplete)) {
+      return { projectId, fromSnapshotId, toSnapshotId, available: false, reason: 'incomplete-snapshot', changes: [] };
+    }
+    const before = this.listSnapshotFiles(fromSnapshotId);
+    const after = this.listSnapshotFiles(toSnapshotId);
+    if (before.length === 0 || after.length === 0) {
+      return {
+        projectId,
+        fromSnapshotId,
+        toSnapshotId,
+        available: false,
+        reason: 'legacy-snapshot-without-manifest',
+        changes: [],
+      };
+    }
+    const beforeByPath = new Map(before.map(file => [file.path, file]));
+    const afterByPath = new Map(after.map(file => [file.path, file]));
+    const paths = [...new Set([...beforeByPath.keys(), ...afterByPath.keys()])].sort();
+    const changes: CodeStateFileChange[] = [];
+    for (const path of paths) {
+      const oldFile = beforeByPath.get(path);
+      const newFile = afterByPath.get(path);
+      if (!oldFile && newFile) {
+        changes.push({ path, kind: 'added', afterHash: newFile.contentHash });
+      } else if (oldFile && !newFile) {
+        changes.push({ path, kind: 'removed', beforeHash: oldFile.contentHash });
+      } else if (oldFile && newFile && oldFile.contentHash !== newFile.contentHash) {
+        changes.push({ path, kind: 'modified', beforeHash: oldFile.contentHash, afterHash: newFile.contentHash });
+      }
+    }
+    return { projectId, fromSnapshotId, toSnapshotId, available: true, changes };
+  }
+
+  impactSlice(projectId: string, changedPaths: string[], maxRelations = 24): CodeGraphImpactSlice {
+    const safeLimit = Number.isFinite(maxRelations) ? Math.max(1, Math.min(100, Math.floor(maxRelations))) : 24;
+    const normalizedPaths = [...new Set(changedPaths.map(normalizeCodePath).filter(Boolean))].sort();
+    const files = this.listFiles(projectId);
+    const fileById = new Map(files.map(file => [file.id, file.path]));
+    const fileIdBySymbolId = new Map(this.listSymbols(projectId).map(symbol => [symbol.id, symbol.fileId]));
+    const changedIds = new Set(files.filter(file => normalizedPaths.includes(file.path)).map(file => file.id));
+    const direct = new Set<string>();
+    let relationCount = 0;
+    let truncated = false;
+    for (const edge of this.listEdges(projectId)) {
+      const endpoints = [
+        edge.fromFileId,
+        edge.toFileId,
+        edge.fromSymbolId ? fileIdBySymbolId.get(edge.fromSymbolId) : undefined,
+        edge.toSymbolId ? fileIdBySymbolId.get(edge.toSymbolId) : undefined,
+      ].filter((id): id is string => Boolean(id));
+      if (!endpoints.some(id => changedIds.has(id))) continue;
+      const relatedPaths = endpoints
+        .filter(id => !changedIds.has(id))
+        .map(id => fileById.get(id))
+        .filter((path): path is string => Boolean(path));
+      if (relatedPaths.length === 0) continue;
+      if (relationCount >= safeLimit) {
+        truncated = true;
+        break;
+      }
+      relationCount += 1;
+      for (const path of relatedPaths) direct.add(path);
+    }
+    const snapshot = this.latestSnapshot(projectId);
+    return {
+      projectId,
+      ...(snapshot ? { snapshotId: snapshot.id } : {}),
+      changedPaths: normalizedPaths,
+      directlyConnectedPaths: [...direct].sort(),
+      relationCount,
+      truncated,
+      provider: snapshot?.provider ?? 'lite',
+    };
+  }
+
   /**
    * Record a completed scan and mark all current structural facts with its
    * epoch. The snapshot is written only after refresh reconciliation succeeds,
@@ -642,6 +843,16 @@ export class CodeGraphStore {
       this.db.prepare(
         "UPDATE observation_code_refs SET snapshotId = ? WHERE projectId = ? AND status = 'current'",
       ).run(id, input.projectId);
+      const snapshotFileRows = this.db.prepare(`
+        SELECT id, projectId, path, contentHash FROM code_files WHERE projectId = ? ORDER BY path
+      `).all(input.projectId) as Array<{ id: string; projectId: string; path: string; contentHash: string }>;
+      const insertSnapshotFile = this.db.prepare(`
+        INSERT INTO code_state_snapshot_files (snapshotId, projectId, fileId, path, contentHash)
+        VALUES (?, ?, ?, ?, ?)
+      `);
+      for (const file of snapshotFileRows) {
+        insertSnapshotFile.run(id, file.projectId, file.id, file.path, file.contentHash);
+      }
       snapshot = {
         ...input,
         id,

package/src/codegraph/types.ts

@@ -116,6 +116,46 @@ export interface CodeStateSnapshot extends CodeStateSnapshotInput {
   previousSnapshotId?: string;
 }
 
+/** Hash-only file state retained for an explicit Code State snapshot. */
+export interface CodeStateSnapshotFile {
+  snapshotId: string;
+  projectId: string;
+  fileId: string;
+  path: string;
+  contentHash: string;
+}
+
+export interface CodeStateFileChange {
+  path: string;
+  kind: 'added' | 'modified' | 'removed';
+  beforeHash?: string;
+  afterHash?: string;
+}
+
+/**
+ * An exact file-level comparison when both snapshots have hash manifests.
+ * It intentionally makes no claim about source-level semantic equivalence.
+ */
+export interface CodeStateDiff {
+  projectId: string;
+  fromSnapshotId: string;
+  toSnapshotId: string;
+  available: boolean;
+  reason?: 'missing-snapshot' | 'project-mismatch' | 'legacy-snapshot-without-manifest' | 'incomplete-snapshot';
+  changes: CodeStateFileChange[];
+}
+
+/** Bounded one-hop structural evidence around changed file paths. */
+export interface CodeGraphImpactSlice {
+  projectId: string;
+  snapshotId?: string;
+  changedPaths: string[];
+  directlyConnectedPaths: string[];
+  relationCount: number;
+  truncated: boolean;
+  provider: CodeGraphProviderKind;
+}
+
 export interface CodeGraphStatus {
   provider: CodeGraphProviderKind;
   files: number;
@@ -164,6 +204,8 @@ export interface CodeGraphProviderQuality {
     capabilities: {
       declarations: boolean;
       importHints: boolean;
+      /** Deterministic local-path mapping only; not semantic name resolution. */
+      localRelativeImportTargets: boolean;
       resolvedRelations: false;
       exactLocations: false;
     };

package/src/knowledge/context-assembly.ts

@@ -43,6 +43,22 @@ export interface ContextReceiptOmission {
   count: number;
 }
 
+export interface ContextReceiptGovernanceDecision {
+  kind: ContextCandidateKind;
+  id?: string;
+  disposition: 'include' | 'compact' | 'defer' | 'exclude';
+  reasons: string[];
+}
+
+/** Privacy-safe evidence qualification, never appended to the agent prompt. */
+export interface ContextReceiptGovernance {
+  /** Current implementation qualifies optional memory/knowledge, not caller task facts. */
+  scope: 'optional-evidence';
+  mode: 'abstain' | 'card' | 'workset';
+  decisions: ContextReceiptGovernanceDecision[];
+  cautions: string[];
+}
+
 export interface ContextReceipt {
   version: '1.3';
   target: ContextDeliveryTarget;
@@ -53,6 +69,7 @@ export interface ContextReceipt {
   };
   selected: ContextReceiptSelection[];
   omitted: ContextReceiptOmission[];
+  governance?: ContextReceiptGovernance;
   scheduledActions: string[];
 }
 
@@ -92,6 +109,14 @@ export function formatContextReceipt(receipt: ContextReceipt): string {
     }
   }
 
+  if (receipt.governance?.decisions.length) {
+    lines.push('', 'Optional evidence qualification');
+    for (const item of receipt.governance.decisions.slice(0, 20)) {
+      const id = item.id ? ` ${item.id}` : '';
+      lines.push(`- ${item.kind}${id}: ${item.disposition} (${item.reasons.join(', ')})`);
+    }
+  }
+
   if (receipt.scheduledActions.length > 0) {
     lines.push('', 'Scheduled follow-up');
     for (const action of receipt.scheduledActions) lines.push(`- ${action}`);

package/src/knowledge/governor.ts

@@ -0,0 +1,156 @@
+import type {
+  ContextCandidateFreshness,
+  ContextCandidateKind,
+  ContextCandidateTrust,
+} from './context-assembly.js';
+
+/**
+ * A small, serializable description of an item competing for agent context.
+ * This is intentionally independent from stores and prompt rendering so every
+ * delivery surface can apply the same evidence rules.
+ */
+export interface GovernanceCandidate {
+  kind: ContextCandidateKind;
+  id?: string;
+  estimatedTokens: number;
+  relevance: number;
+  scopeAllowed: boolean;
+  freshness?: ContextCandidateFreshness;
+  trust?: ContextCandidateTrust;
+  quality?: 'verified' | 'probationary' | 'degraded' | 'blocked';
+  conflict?: 'none' | 'possible' | 'confirmed';
+  evidenceCount?: number;
+}
+
+export type GovernanceDisposition = 'include' | 'compact' | 'defer' | 'exclude';
+
+export type GovernanceReason =
+  | 'scope-forbidden'
+  | 'confirmed-conflict'
+  | 'blocked-quality'
+  | 'degraded-quality'
+  | 'stale-evidence'
+  | 'unknown-freshness'
+  | 'possible-conflict'
+  | 'probationary-evidence'
+  | 'token-budget'
+  | 'current-source-backed-evidence'
+  | 'relevant-evidence'
+  | 'no-qualified-evidence';
+
+export interface GovernanceDecision {
+  candidate: GovernanceCandidate;
+  disposition: GovernanceDisposition;
+  reasons: GovernanceReason[];
+}
+
+export interface GovernancePlan {
+  mode: 'abstain' | 'card' | 'workset';
+  budget: { maxTokens: number; usedTokens: number };
+  decisions: GovernanceDecision[];
+  cautions: GovernanceReason[];
+}
+
+function clampRelevance(value: number): number {
+  if (!Number.isFinite(value)) return 0;
+  return Math.max(0, Math.min(1, value));
+}
+
+function classify(candidate: GovernanceCandidate): Omit<GovernanceDecision, 'candidate'> {
+  const freshness = candidate.freshness ?? 'unknown';
+  const trust = candidate.trust ?? 'historical';
+  const quality = candidate.quality ?? 'probationary';
+  const conflict = candidate.conflict ?? 'none';
+
+  if (!candidate.scopeAllowed) {
+    return { disposition: 'exclude', reasons: ['scope-forbidden'] };
+  }
+  if (conflict === 'confirmed') {
+    return { disposition: 'exclude', reasons: ['confirmed-conflict'] };
+  }
+  if (quality === 'blocked') {
+    return { disposition: 'exclude', reasons: ['blocked-quality'] };
+  }
+  if (quality === 'degraded') {
+    return { disposition: 'defer', reasons: ['degraded-quality'] };
+  }
+  if (freshness === 'stale') {
+    return { disposition: 'defer', reasons: ['stale-evidence'] };
+  }
+
+  const reasons: GovernanceReason[] = [];
+  let disposition: GovernanceDisposition = 'include';
+  if (freshness === 'unknown') {
+    disposition = 'compact';
+    reasons.push('unknown-freshness');
+  }
+  if (conflict === 'possible') {
+    disposition = 'compact';
+    reasons.push('possible-conflict');
+  }
+  if (quality === 'probationary') {
+    disposition = 'compact';
+    reasons.push('probationary-evidence');
+  }
+  if (disposition === 'include' && freshness === 'current' && trust === 'source-backed') {
+    reasons.push('current-source-backed-evidence');
+  } else if (reasons.length === 0) {
+    reasons.push('relevant-evidence');
+  }
+  return { disposition, reasons };
+}
+
+function priority(decision: GovernanceDecision): number {
+  const dispositionWeight: Record<GovernanceDisposition, number> = {
+    include: 3,
+    compact: 2,
+    defer: 1,
+    exclude: 0,
+  };
+  const evidence = Math.min(3, decision.candidate.evidenceCount ?? 0) / 10;
+  return dispositionWeight[decision.disposition] + clampRelevance(decision.candidate.relevance) + evidence;
+}
+
+/**
+ * Decide which evidence may enter a bounded context response. The result never
+ * mutates memory and deliberately prefers an explicit abstention to a generic
+ * history dump.
+ */
+export function governContextCandidates(
+  candidates: GovernanceCandidate[],
+  maxTokens: number,
+): GovernancePlan {
+  const safeBudget = Math.max(0, Math.floor(maxTokens));
+  const decisions = candidates.map(candidate => ({ candidate, ...classify(candidate) }));
+  const eligible = decisions
+    .filter(decision => decision.disposition === 'include' || decision.disposition === 'compact')
+    .sort((left, right) => priority(right) - priority(left));
+  let usedTokens = 0;
+
+  for (const decision of eligible) {
+    const tokens = Math.max(0, Math.ceil(decision.candidate.estimatedTokens));
+    if (usedTokens + tokens <= safeBudget) {
+      usedTokens += tokens;
+      continue;
+    }
+    decision.disposition = 'defer';
+    decision.reasons = [...decision.reasons, 'token-budget'];
+  }
+
+  const delivered = decisions.filter(decision => decision.disposition === 'include' || decision.disposition === 'compact');
+  const mode = delivered.length === 0
+    ? 'abstain'
+    : delivered.some(decision => decision.disposition === 'include')
+      ? 'workset'
+      : 'card';
+  const cautions = [...new Set(decisions
+    .filter(decision => decision.disposition !== 'include')
+    .flatMap(decision => decision.reasons))];
+
+  return {
+    mode,
+    budget: { maxTokens: safeBudget, usedTokens },
+    decisions,
+    cautions: cautions.length > 0 ? cautions : ['no-qualified-evidence'],
+  };
+}

package/src/knowledge/outcome-store.ts

@@ -0,0 +1,102 @@
+import { randomUUID } from 'node:crypto';
+import { sanitizeCredentials } from '../memory/secret-filter.js';
+import { getDatabase } from '../store/sqlite-db.js';
+import {
+  MEMORY_OUTCOME_CANDIDATE_KINDS,
+  MEMORY_OUTCOME_SIGNAL_KINDS,
+  type MemoryOutcomeCandidateKind,
+  type MemoryOutcomeSignal,
+  type MemoryOutcomeSignalKind,
+} from './outcome-types.js';
+
+function optionalText(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value : undefined;
+}
+
+function text(value: string, field: string, max = 1_000): string {
+  const safe = sanitizeCredentials(value).replace(/\s+/g, ' ').trim();
+  if (!safe) throw new Error('Outcome signal ' + field + ' is required.');
+  if (safe.length > max) throw new Error('Outcome signal ' + field + ' is too long.');
+  return safe;
+}
+
+function oneOf<T extends readonly string[]>(value: unknown, values: T, field: string): T[number] {
+  if (typeof value !== 'string' || !(values as readonly string[]).includes(value)) {
+    throw new Error('Outcome signal ' + field + ' is invalid.');
+  }
+  return value as T[number];
+}
+
+function rowToSignal(row: any): MemoryOutcomeSignal {
+  return {
+    id: row.id,
+    projectId: row.projectId,
+    candidateKind: row.candidateKind,
+    candidateId: row.candidateId,
+    kind: row.kind,
+    sourceRef: row.sourceRef,
+    ...(optionalText(row.snapshotId) ? { snapshotId: row.snapshotId } : {}),
+    ...(optionalText(row.detail) ? { detail: row.detail } : {}),
+    observedAt: row.observedAt,
+  } as MemoryOutcomeSignal;
+}
+
+/** Persistence only; callers decide which real-world event is worth recording. */
+export class OutcomeStore {
+  private db: any = null;
+
+  async init(dataDir: string): Promise<void> {
+    this.db = getDatabase(dataDir);
+  }
+
+  record(input: Omit<MemoryOutcomeSignal, 'id' | 'observedAt'> & { observedAt?: string }): MemoryOutcomeSignal {
+    const signal: MemoryOutcomeSignal = {
+      id: randomUUID(),
+      projectId: text(input.projectId, 'project id'),
+      candidateKind: oneOf(input.candidateKind, MEMORY_OUTCOME_CANDIDATE_KINDS, 'candidate kind'),
+      candidateId: text(input.candidateId, 'candidate id'),
+      kind: oneOf(input.kind, MEMORY_OUTCOME_SIGNAL_KINDS, 'kind'),
+      sourceRef: text(input.sourceRef, 'source reference'),
+      ...(input.snapshotId ? { snapshotId: text(input.snapshotId, 'snapshot id') } : {}),
+      ...(input.detail ? { detail: text(input.detail, 'detail') } : {}),
+      observedAt: input.observedAt ?? new Date().toISOString(),
+    };
+    this.db.prepare(`
+      INSERT INTO memory_outcome_signals (
+        id, projectId, candidateKind, candidateId, kind, sourceRef, snapshotId, detail, observedAt
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      signal.id,
+      signal.projectId,
+      signal.candidateKind,
+      signal.candidateId,
+      signal.kind,
+      signal.sourceRef,
+      signal.snapshotId ?? null,
+      signal.detail ?? null,
+      signal.observedAt,
+    );
+    return signal;
+  }
+
+  latestForCandidates(
+    projectId: string,
+    candidateKind: MemoryOutcomeCandidateKind,
+    candidateIds: string[],
+  ): Map<string, MemoryOutcomeSignal> {
+    const ids = [...new Set(candidateIds.filter(Boolean))];
+    if (ids.length === 0) return new Map();
+    const placeholders = ids.map(() => '?').join(', ');
+    const rows = this.db.prepare(`
+      SELECT * FROM memory_outcome_signals
+      WHERE projectId = ? AND candidateKind = ? AND candidateId IN (${placeholders})
+      ORDER BY observedAt DESC, id DESC
+    `).all(projectId, candidateKind, ...ids);
+    const latest = new Map<string, MemoryOutcomeSignal>();
+    for (const row of rows) {
+      const signal = rowToSignal(row);
+      if (!latest.has(signal.candidateId)) latest.set(signal.candidateId, signal);
+    }
+    return latest;
+  }
+}