@ngockhoale/ukit 3.0.8 → 3.0.9

package/src/core/memory/migrateMapping.js

@@ -0,0 +1,232 @@
+// Pure v1→v2 record mapping — SPEC §5 FR-001/FR-003 (M04-01).
+// mapLegacySources(sources, opts) → { records, plan[], skipped }
+//   sources: collectLegacySources shape
+//     { user, userFile?, projects:[{id,file?,content}], sessions:[{file?,session}|session],
+//       corruptFiles, corrupt?:[fileName] }
+//   opts: { projectId, now, episodeTtlMs?, tombstones?, resolveProjectId? }
+// Deterministic: record ids are `v1-<sha1(sourceKind:type:normalizedText)>` —
+// stable across runs and legacy file renames. No I/O; `now` is injected.
+// Rules (FR-003): tombstone precedence → plan 'tombstoned'; alias collision
+// (resolveProjectId returns a different verified identity) → plan 'conflict';
+// pending candidates → trust_tier 'candidate' + meta.legacyStatus 'pending',
+// never status 'active'; everything else → trust_tier 'legacy-unverified'.
+
+import crypto from 'node:crypto';
+import { createRecord } from './records.js';
+import { isTombstoned } from './recordStore.js';
+
+function normalizeText(text) {
+  return String(text).toLowerCase().replace(/\s+/g, ' ').trim();
+}
+
+function fingerprint(type, text) {
+  return crypto.createHash('sha1').update(`v1:${type}:${normalizeText(text)}`).digest('hex');
+}
+
+function recordId(sourceKind, type, text) {
+  return `v1-${crypto.createHash('sha1')
+    .update(`${sourceKind}:${type}:${normalizeText(text)}`)
+    .digest('hex')}`;
+}
+
+function sessionText(session) {
+  return [
+    session.taskDescription,
+    session.outcome ? `outcome: ${session.outcome}` : null,
+    ...(Array.isArray(session.keyActions) ? session.keyActions : []),
+  ].filter(Boolean).join(' — ');
+}
+
+/**
+ * mapLegacySources(sources, { projectId, now, episodeTtlMs, tombstones,
+ * resolveProjectId }) → { records, plan, skipped }
+ */
+export function mapLegacySources(sources, {
+  projectId = null,
+  now = null,
+  episodeTtlMs = 90 * 24 * 60 * 60 * 1000,
+  tombstones = [],
+  resolveProjectId = null,
+} = {}) {
+  const createdNow = Number.isFinite(now) ? now : Date.now();
+  const doc = { tombstones: Array.isArray(tombstones) ? tombstones : [] };
+  const records = [];
+  const plan = [];
+  let skipped = 0;
+
+  const emit = (spec, source, sourceKind) => {
+    const id = recordId(sourceKind, spec.type, spec.text);
+    const fp = fingerprint(spec.type, spec.text);
+    if (isTombstoned(doc, { id, fingerprint: fp })) {
+      plan.push({ id, source, action: 'tombstoned', reason: 'tombstone-precedence' });
+      skipped += 1;
+      return;
+    }
+    let record;
+    try {
+      record = createRecord({
+        id,
+        type: spec.type,
+        scope: spec.scope,
+        text: spec.text,
+        provenance: spec.provenance,
+        sourceFingerprint: fp,
+        confidence: spec.confidence,
+        createdBy: 'migration',
+        projectId: spec.projectId ?? null,
+        validUntil: spec.validUntil ?? null,
+        meta: spec.meta ?? {},
+        trustTier: spec.trustTier ?? 'legacy-unverified',
+        reason: 'migration',
+      });
+    } catch {
+      plan.push({ id, source, action: 'skip', reason: 'invalid-record' });
+      skipped += 1;
+      return;
+    }
+    if (Number.isFinite(spec.createdAt)) record.created_at = spec.createdAt;
+    else record.created_at = createdNow;
+    if (spec.status) record.status = spec.status;
+    records.push(record);
+    plan.push({ id, source, action: 'add', reason: 'mapped' });
+  };
+
+  // ── user memory ──
+  const user = sources?.user;
+  const userFile = sources?.userFile ?? 'user.json';
+  if (user && typeof user === 'object') {
+    for (const rule of Array.isArray(user.rules) ? user.rules : []) {
+      if (typeof rule !== 'string' || !rule) continue;
+      emit({
+        type: 'project_rule', scope: 'user', text: rule,
+        confidence: 1.0, provenance: 'legacy:user-rules', createdAt: user.updatedAt,
+      }, userFile, 'user-rules');
+    }
+    const prefs = user.preferences && typeof user.preferences === 'object' ? user.preferences : {};
+    for (const [key, value] of Object.entries(prefs)) {
+      const text = `${key} = ${typeof value === 'string' ? value : JSON.stringify(value)}`;
+      emit({
+        type: 'derived_fact', scope: 'user', text,
+        confidence: 1.0, provenance: 'legacy:user-preferences', createdAt: user.updatedAt,
+      }, userFile, 'user-preferences');
+    }
+  }
+
+  // ── project memory ──
+  for (const entry of Array.isArray(sources?.projects) ? sources.projects : []) {
+    const content = entry?.content ?? entry;
+    const legacyId = entry?.id ?? content?.id ?? null;
+    const file = entry?.file ?? `${legacyId ?? 'project'}.json`;
+    if (!content || typeof content !== 'object') continue;
+
+    // Alias collision: a legacy id that resolves to a DIFFERENT verified
+    // identity is a conflict — never silently rebound to this project.
+    if (typeof resolveProjectId === 'function' && legacyId) {
+      const resolved = resolveProjectId(legacyId);
+      if (resolved && resolved !== legacyId) {
+        plan.push({
+          id: `v1-${crypto.createHash('sha1').update(`project:${legacyId}`).digest('hex')}`,
+          source: file,
+          action: 'conflict',
+          reason: `alias-collision:${resolved}`,
+        });
+        skipped += 1;
+        continue;
+      }
+    }
+    const pid = legacyId ?? projectId;
+    const createdAt = content.updatedAt;
+
+    for (const text of Array.isArray(content.conventions) ? content.conventions : []) {
+      if (typeof text !== 'string' || !text) continue;
+      emit({
+        type: 'project_rule', scope: 'repo', text,
+        confidence: 0.9, provenance: 'legacy:conventions', projectId: pid, createdAt,
+      }, file, 'conventions');
+    }
+    for (const text of Array.isArray(content.activeRules) ? content.activeRules : []) {
+      if (typeof text !== 'string' || !text) continue;
+      emit({
+        type: 'project_rule', scope: 'repo', text,
+        confidence: 1.0, provenance: 'legacy:activeRules', projectId: pid, createdAt,
+      }, file, 'activeRules');
+    }
+    for (const decision of Array.isArray(content.decisions) ? content.decisions : []) {
+      if (!decision || typeof decision !== 'object') continue;
+      const text = decision.why ? `${decision.what} — ${decision.why}` : String(decision.what ?? '');
+      if (!text) continue;
+      emit({
+        type: 'derived_fact', scope: 'repo', text,
+        confidence: 0.9, provenance: 'legacy:decisions', projectId: pid,
+        createdAt: decision.when ?? createdAt,
+      }, file, 'decisions');
+    }
+    const profileEntries = [
+      ...(typeof content.architecture === 'string' && content.architecture ? [content.architecture] : []),
+      ...(Array.isArray(content.techStack)
+        ? content.techStack.filter((t) => typeof t === 'string' && t) : []),
+    ];
+    for (const text of profileEntries) {
+      emit({
+        type: 'derived_fact', scope: 'repo', text,
+        confidence: 0.8, provenance: 'legacy:project-profile', projectId: pid, createdAt,
+      }, file, 'project-profile');
+    }
+    for (const pc of Array.isArray(content.patternCandidates) ? content.patternCandidates : []) {
+      if (!pc || typeof pc !== 'object' || typeof pc.text !== 'string' || !pc.text) continue;
+      const legacyStatus = pc.status ?? 'pending';
+      const meta = { ...pc, legacyStatus };
+      const base = {
+        text: pc.text, provenance: 'legacy:pattern-candidate', projectId: pid,
+        createdAt: pc.detectedAt ?? createdAt, meta,
+      };
+      if (legacyStatus === 'approved') {
+        emit({ ...base, type: 'project_rule', scope: 'repo', confidence: 0.9 }, file, 'pattern-candidate');
+      } else if (legacyStatus === 'rejected') {
+        emit({ ...base, type: 'derived_fact', scope: 'task', confidence: 0.4, status: 'archived' },
+          file, 'pattern-candidate');
+      } else {
+        // Candidate isolation: pending candidates keep candidate trust and
+        // never land as active records.
+        emit({
+          ...base, type: 'derived_fact', scope: 'task', confidence: 0.4,
+          status: 'stale', trustTier: 'candidate',
+        }, file, 'pattern-candidate');
+      }
+    }
+  }
+
+  // ── sessions ──
+  for (const entry of Array.isArray(sources?.sessions) ? sources.sessions : []) {
+    const session = entry?.session ?? entry;
+    const file = entry?.file ?? 'sessions';
+    if (!session || typeof session !== 'object') continue;
+    const text = sessionText(session);
+    if (!text) continue;
+    const createdAt = session.startedAt ?? session.endedAt ?? null;
+    emit({
+      type: 'episode', scope: 'session', text,
+      confidence: 0.7, provenance: 'legacy:session',
+      projectId: typeof session.projectId === 'string' ? session.projectId : projectId,
+      createdAt,
+      validUntil: createdAt != null ? createdAt + episodeTtlMs : null,
+      meta: { legacyId: session.id ?? null },
+    }, file, 'session');
+  }
+
+  // ── corrupt legacy files: counted, never treated as empty ──
+  const corruptCount = Number.isFinite(sources?.corruptFiles) ? sources.corruptFiles : 0;
+  const corruptNames = Array.isArray(sources?.corrupt) ? sources.corrupt : [];
+  for (let i = 0; i < corruptCount; i += 1) {
+    const name = corruptNames[i] ?? `corrupt-file-${i + 1}`;
+    plan.push({
+      id: `v1-${crypto.createHash('sha1').update(`corrupt:${name}`).digest('hex')}`,
+      source: name,
+      action: 'skip',
+      reason: 'corrupt-legacy-file',
+    });
+    skipped += 1;
+  }
+
+  return { records, plan, skipped };
+}

package/src/core/memory/mutateMemory.js

@@ -0,0 +1,323 @@
+// mutateMemory — single guarded write entry for project + user stores
+// (SPEC §5 FR-011..FR-015). Every public write (add/update/archive/forget/
+// purge/restore) funnels through here so tombstone checks, optimistic
+// version checks, write-guard rejection, and the idempotency journal run
+// inside the same locked read-modify-write — no unguarded bypass remains.
+//
+// Domain failures are typed results, never throws. Lock-timeout and
+// unexpected I/O errors still propagate per the mutateRecordStore
+// fail-closed contract; StoreCorruptError is caught and mapped to
+// {status:'corrupt'} (quarantine already happened inside the lock).
+
+import crypto from 'node:crypto';
+import path from 'node:path';
+
+import { readJsonIfExists, writeJson } from '../fileOps.js';
+import { buildRuntimePaths } from '../runtimePaths.js';
+import { buildUserPaths } from '../userPaths.js';
+import { loadRuntimeConfig } from '../runtimeConfig.js';
+import {
+  mutateRecordStore,
+  isTombstoned,
+  applyRecordPatch,
+  isRawRecord,
+  StoreCorruptError,
+} from './recordStore.js';
+import { createRecord, normalizeRecord } from './records.js';
+import { guardWritePayload, redactWritePayload } from './writeGuard.js';
+import { classifyWrite, mergeEvidence, REVIEW_QUEUE_MAX } from './writeClassification.js';
+import { resolveMemoryStage, appendRolloutReceipt, latencyBandForMs } from './memoryFlags.js';
+import { resolveProjectIdentity } from './projectIdentity.js';
+
+const JOURNAL_MAX = 256;
+const OPS = new Set(['add', 'update', 'archive', 'forget', 'purge', 'restore']);
+
+function sha1(text) {
+  return crypto.createHash('sha1').update(String(text)).digest('hex');
+}
+
+function resolveTarget(target) {
+  if (target?.kind === 'project') {
+    const paths = buildRuntimePaths(target.projectRoot);
+    return { paths, recordsPath: paths.memoryV2RecordsPath };
+  }
+  if (target?.kind === 'user') {
+    const paths = buildUserPaths({ homeDir: target.homeDir });
+    return { paths, recordsPath: paths.memoryV2RecordsPath };
+  }
+  throw new Error(`mutateMemory: unknown target kind ${target?.kind}`);
+}
+
+async function readJournal(journalPath) {
+  const doc = await readJsonIfExists(journalPath);
+  const entries = doc && typeof doc.entries === 'object' && doc.entries ? doc.entries : {};
+  return { entries };
+}
+
+async function appendJournal(journalPath, key, entry) {
+  const journal = await readJournal(journalPath);
+  // FIFO cap: delete-then-set reorders the key to newest before trimming.
+  delete journal.entries[key];
+  journal.entries[key] = entry;
+  const keys = Object.keys(journal.entries);
+  while (keys.length > JOURNAL_MAX) {
+    delete journal.entries[keys.shift()];
+  }
+  await writeJson(journalPath, journal, { fsync: true });
+}
+
+function payloadFingerprint(payload) {
+  if (!payload || typeof payload !== 'object') return undefined;
+  return payload.source_fingerprint ?? payload.sourceFingerprint
+    ?? (typeof payload.text === 'string' ? sha1(payload.text) : undefined);
+}
+
+function buildRecord(payload, idempotencyKey) {
+  const record = isRawRecord(payload) ? normalizeRecord(payload) : createRecord(payload);
+  if (!record) return null;
+  if (idempotencyKey) record.meta = { ...record.meta, idem: idempotencyKey };
+  return record;
+}
+
+function findRecord(records, payload) {
+  const id = payload?.id ?? payload?.recordId;
+  return id ? records.find((r) => r.id === id) : undefined;
+}
+
+/**
+ * mutateMemory(target, envelope, {classifyAdd, guard} = {}) → Promise<result>
+ * target = {kind:'project', projectRoot} | {kind:'user', homeDir}
+ * envelope = {op, payload?, idempotencyKey?, expectedRevision?,
+ *             expectedGeneration?, actor?, confirmScope?}
+ * result = {status:'ok'|'conflict'|'rejected'|'duplicate'|'not-found'|
+ *           'corrupt'|'disabled'|'review-queue-full', record?, reason?, labels?}
+ */
+export async function mutateMemory(target, envelope = {}, { classifyAdd, guard } = {}) {
+  const { recordsPath, paths } = resolveTarget(target);
+  const journalPath = path.join(paths.memoryV2Dir, 'mutation-journal.json');
+  const { op, payload, idempotencyKey, expectedRevision, expectedGeneration,
+    confirmScope } = envelope;
+  if (!OPS.has(op)) {
+    return { status: 'rejected', reason: `unknown-op:${String(op)}` };
+  }
+  let config = null;
+  let receiptStage = null;
+  let projectId = null;
+  if (target.kind === 'project') {
+    try {
+      config = await loadRuntimeConfig(target.projectRoot);
+      if (config?.memoryV2?.enabled === false) return { status: 'disabled' };
+    } catch {
+      // unreadable config → default enabled, keep going
+    }
+    // M06 rollout flag (SPEC §5 FR-003): writer stage 'off' (incl. killSwitch
+    // or an unlisted canary project) disables the write lane entirely —
+    // flags only reduce capability. 'shadow' runs the same write and emits
+    // a bounded content-free receipt; 'canary'/'default' are live.
+    const identity = await resolveProjectIdentity(target.projectRoot, {
+      homeDir: target.homeDir, mint: false,
+    }).catch(() => null);
+    projectId = identity?.projectId ?? null;
+    const writerStage = resolveMemoryStage(config, 'writer', { projectId });
+    if (writerStage === 'off') {
+      return { status: 'disabled', reason: 'rollout-stage' };
+    }
+    receiptStage = writerStage === 'shadow' ? 'shadow' : null;
+  }
+  const guardFn = guard ?? ((p) => guardWritePayload(p, { config, projectId }));
+
+  try {
+    const startedAt = receiptStage ? Date.now() : 0;
+    const result = await mutateRecordStore(recordsPath, async (records, prior) => {
+      // 2. Idempotency — journal hit or a record already stamped meta.idem.
+      if (idempotencyKey) {
+        const journal = await readJournal(journalPath);
+        const hit = journal.entries[idempotencyKey];
+        if (hit) {
+          return { result: { status: 'duplicate', record: records.find((r) => r.id === hit.recordId) } };
+        }
+        const stamped = records.find((r) => r.meta?.idem === idempotencyKey);
+        if (stamped) return { result: { status: 'duplicate', record: stamped } };
+      }
+
+      // 3. Tombstone check — add/restore must never resurrect purged data.
+      if (op === 'add' && isTombstoned(prior, {
+        id: payload?.id, fingerprint: payloadFingerprint(payload),
+      })) {
+        return { result: { status: 'rejected', reason: 'tombstoned' } };
+      }
+
+      // 4. Optimistic checks.
+      if (expectedGeneration !== undefined && expectedGeneration !== prior.generation) {
+        return { result: { status: 'conflict', reason: 'generation-mismatch' } };
+      }
+      const existing = op === 'add' || op === 'restore' ? undefined : findRecord(records, payload);
+      if (op !== 'add' && op !== 'restore' && !existing) {
+        return { result: { status: 'not-found' } };
+      }
+      if (expectedRevision !== undefined) {
+        if (!existing || existing.revision !== expectedRevision) {
+          return { result: { status: 'conflict', reason: 'revision-mismatch' } };
+        }
+      }
+
+      const postWrite = idempotencyKey
+        ? async () => appendJournal(journalPath, idempotencyKey, {
+          op, recordId: appliedRecordId, at: Date.now(),
+        })
+        : null;
+      let appliedRecordId;
+
+      // 5-7. Per-op apply.
+      if (op === 'add') {
+        const classify = classifyAdd ?? ((p, recs) => classifyWrite(p, recs));
+        const decision = await classify(payload, records);
+        if (decision?.action === 'NOOP') {
+          const target = decision.targetId
+            ? records.find((r) => r.id === decision.targetId)
+            : findRecord(records, payload);
+          return { result: { status: 'duplicate', record: target } };
+        }
+        if (decision?.action === 'REVIEW') {
+          const pending = records.filter((r) => r.meta?.review_status === 'pending').length;
+          if (pending >= REVIEW_QUEUE_MAX) {
+            return { result: { status: 'review-queue-full' } };
+          }
+        }
+        const guarded = guardFn(payload);
+        if (guarded && guarded.ok === false) {
+          return { result: { status: 'rejected', reason: guarded.reason ?? 'secret-detected', labels: guarded.labels } };
+        }
+        // REVIEW records must persist even when the candidate itself is
+        // malformed (e.g. self-supersede) — strip the offending field so the
+        // quarantined record validates instead of crashing the write.
+        const recordPayload = decision?.action === 'REVIEW'
+          ? { ...payload, supersedes: [] }
+          : payload;
+        let record;
+        try {
+          record = buildRecord(recordPayload, idempotencyKey);
+        } catch {
+          record = null;
+        }
+        if (!record) return { result: { status: 'rejected', reason: 'invalid-record' } };
+        if (decision?.action === 'REVIEW') {
+          record.status = 'archived';
+          record.meta = { ...record.meta, review_status: 'pending', review_reason: decision.reason };
+          appliedRecordId = record.id;
+          return { result: { status: 'ok', record, reason: 'review' }, records: [...records, record], postWrite };
+        }
+        if (decision?.action === 'ENRICH' && decision.targetId) {
+          const targetRec = records.find((r) => r.id === decision.targetId);
+          if (targetRec) {
+            const patched = applyRecordPatch(records, targetRec.id, {
+              evidence: mergeEvidence(targetRec.evidence, record.evidence),
+              revision: (targetRec.revision ?? 1) + 1,
+            });
+            appliedRecordId = patched.record.id;
+            return {
+              result: { status: 'ok', record: patched.record, reason: 'enriched' },
+              records: patched.records,
+              postWrite,
+            };
+          }
+        }
+        if (decision?.action === 'SUPERSEDE') {
+          const targetIds = decision.targetIds
+            ?? (decision.targetId ? [decision.targetId] : []);
+          let next = records;
+          for (const id of targetIds) {
+            const patched = applyRecordPatch(next, id, {
+              status: 'archived', superseded_by: record.id, reason: 'superseded',
+            });
+            if (patched) next = patched.records;
+          }
+          appliedRecordId = record.id;
+          return { result: { status: 'ok', record }, records: [...next, record], postWrite };
+        }
+        appliedRecordId = record.id;
+        return { result: { status: 'ok', record }, records: [...records, record], postWrite };
+      }
+
+      if (op === 'update' || op === 'archive' || op === 'forget') {
+        const patch = op === 'update'
+          ? { ...(payload?.patch ?? payload) }
+          : { status: 'archived' };
+        delete patch.id;
+        const guarded = op === 'update' ? guardFn(patch) : { ok: true };
+        if (guarded && guarded.ok === false) {
+          return { result: { status: 'rejected', reason: guarded.reason ?? 'secret-detected', labels: guarded.labels } };
+        }
+        const patched = applyRecordPatch(records, existing.id, {
+          ...patch, revision: (existing.revision ?? 1) + 1,
+        });
+        appliedRecordId = patched.record.id;
+        return { result: { status: 'ok', record: patched.record }, records: patched.records, postWrite };
+      }
+
+      if (op === 'purge') {
+        if (target.kind === 'user' && confirmScope !== 'user') {
+          return { result: { status: 'rejected', reason: 'scope-confirm-required' } };
+        }
+        const tombstone = {
+          id: existing.id,
+          fingerprint: existing.source_fingerprint ?? sha1(existing.text),
+          purged_at: Date.now(),
+        };
+        appliedRecordId = existing.id;
+        return {
+          result: { status: 'ok', record: existing },
+          records: records.filter((r) => r.id !== existing.id),
+          tombstones: [...(prior.tombstones ?? []), tombstone],
+          postWrite,
+        };
+      }
+
+      // op === 'restore' — explicit migrate/restore path: fingerprint dedupe,
+      // tombstone precedence, guard in redact-mode.
+      const incoming = Array.isArray(payload?.records) ? payload.records : [];
+      const fingerprints = new Set(records.map((r) => r.source_fingerprint).filter(Boolean));
+      const ids = new Set(records.map((r) => r.id));
+      const additions = [];
+      for (const raw of incoming) {
+        const redacted = redactWritePayload(raw, { config }).payload;
+        const record = normalizeRecord(redacted);
+        if (!record) continue;
+        const fp = record.source_fingerprint ?? sha1(record.text);
+        if (ids.has(record.id) || fingerprints.has(fp)) continue;
+        if (isTombstoned(prior, { id: record.id, fingerprint: fp })) continue;
+        ids.add(record.id);
+        fingerprints.add(fp);
+        additions.push(record);
+      }
+      appliedRecordId = additions[0]?.id;
+      // No-op restore: nothing to add → skip the write entirely so a
+      // re-run leaves the doc byte-identical (no generation bump).
+      if (additions.length === 0) {
+        return { result: { status: 'ok', added: 0, records: [] } };
+      }
+      return {
+        result: { status: 'ok', added: additions.length, records: additions },
+        records: [...records, ...additions],
+        postWrite,
+      };
+    }, { onCorrupt: op === 'restore' ? 'quarantine-empty' : undefined });
+    if (receiptStage) {
+      // Shadow receipt (FR-004): outcome/code/latency band only — never the
+      // record body. Swallowed internally; cannot break the write.
+      await appendRolloutReceipt(target.projectRoot, {
+        plane: 'writer',
+        stage: receiptStage,
+        outcome: result.status === 'ok' ? 'ok' : result.status === 'rejected' ? 'deny' : 'error',
+        code: result.status,
+        latencyBand: latencyBandForMs(Date.now() - startedAt),
+      });
+    }
+    return result;
+  } catch (error) {
+    if (error instanceof StoreCorruptError || error?.name === 'StoreCorruptError') {
+      return { status: 'corrupt', reason: error.code };
+    }
+    throw error;
+  }
+}

package/src/core/memory/policy.js

@@ -0,0 +1,96 @@
+// Memory eligibility policy — single source of truth (M01-02).
+// Pure module: no I/O, no imports. Deny-by-default on every unbound or
+// ambiguous path; the only escape hatch is an explicit policy override.
+
+export const POLICY_VERSION = 'w1-2';
+
+const REPO_BOUND_SCOPES = Object.freeze(['repo', 'project', 'task', 'session']);
+const UNVERIFIED_PROVENANCE = Object.freeze([
+  'learning-observation',
+  'learning-candidate',
+  'delta-overlay',
+]);
+// Trust tiers that must never surface as a current authoritative fact
+// (TASK-005 / FR-010): candidates and observations are unreviewed input —
+// returning them as eligible is a false-authority breach. 'verified' and
+// 'legacy-unverified' (migrated records) remain admissible.
+const NON_AUTHORITY_TRUST_TIERS = Object.freeze(['candidate', 'observation']);
+const REQUESTED_SCOPES = Object.freeze(['repo', 'user', 'session', 'task', 'all']);
+
+function deny(reason) {
+  return { ok: false, reason };
+}
+
+// hostContext = {projectId: string|null, ambiguous?: boolean, sessionId?, taskId?, branch?}
+// requestedScope ∈ 'repo'|'user'|'session'|'task'|'all' (default 'all').
+// → {scope, projectId, includeUser, denied}
+export function resolveEffectiveScope(hostContext = {}, requestedScope = 'all') {
+  const scope = REQUESTED_SCOPES.includes(requestedScope) ? requestedScope : 'all';
+  const projectId = typeof hostContext.projectId === 'string' ? hostContext.projectId : null;
+  const ambiguous = hostContext.ambiguous === true;
+
+  if (scope === 'user') {
+    return { scope, projectId: null, includeUser: true, denied: false };
+  }
+
+  if (scope === 'all') {
+    // 'all' keeps projectId but does not opt into user records
+    // (user-repo-precedence: user records need explicit opt-in).
+    return { scope, projectId, includeUser: false, denied: false };
+  }
+
+  // repo / task / session require a non-null, non-ambiguous project binding.
+  if (projectId == null || ambiguous) {
+    return { scope, projectId, includeUser: false, denied: true };
+  }
+  return { scope, projectId, includeUser: false, denied: false };
+}
+
+// record per src/core/memory/records.js
+//   (scope, status, project_id, valid_until, provenance, type).
+// context = {projectId, projectAliases?: string[], includeUser, now?}
+// policy  = {legacyNullProjectId: 'deny'|'compat'} — default 'deny'.
+// → {ok: boolean, reason: string}
+export function eligible(record, context = {}, policy = {}) {
+  const now = typeof context.now === 'number' ? context.now : Date.now();
+  const legacyNull = policy.legacyNullProjectId === 'compat' ? 'compat' : 'deny';
+
+  if (record == null || typeof record !== 'object') {
+    return deny('status');
+  }
+  if (record.status !== 'active') {
+    return deny('status');
+  }
+  if (record.valid_until != null && record.valid_until <= now) {
+    return deny('expired');
+  }
+  if (UNVERIFIED_PROVENANCE.includes(record.provenance)) {
+    return deny('unverified-provenance');
+  }
+  if (NON_AUTHORITY_TRUST_TIERS.includes(record.trust_tier)) {
+    return deny('non-authority-trust-tier');
+  }
+
+  if (record.scope === 'user') {
+    if (context.includeUser !== true) {
+      return deny('user-scope-not-included');
+    }
+    return { ok: true, reason: 'ok' };
+  }
+
+  if (REPO_BOUND_SCOPES.includes(record.scope)) {
+    if (context.projectId == null) {
+      return deny('no-project-binding');
+    }
+    if (record.project_id != null && record.project_id !== context.projectId
+        && !(Array.isArray(context.projectAliases)
+          && context.projectAliases.includes(record.project_id))) {
+      return deny('project-mismatch');
+    }
+    if (record.project_id == null && legacyNull !== 'compat') {
+      return deny('null-project-id');
+    }
+  }
+
+  return { ok: true, reason: 'ok' };
+}