@ngockhoale/ukit 3.0.8 → 3.0.9

package/src/core/fileOps.js

@@ -103,7 +103,7 @@ export async function ensureDir(dirPath) {
   await fs.mkdir(dirPath, { recursive: true });
 }
 
-export async function writeFileAtomic(filePath, content) {
+export async function writeFileAtomic(filePath, content, { fsync = false } = {}) {
   const dir = path.dirname(filePath);
   await ensureDir(dir);
 
@@ -119,6 +119,24 @@ export async function writeFileAtomic(filePath, content) {
     } else {
       await withTransientFsRetry(() => fs.writeFile(tempPath, content, 'utf8'));
     }
+    if (fsync) {
+      // Best-effort durability: flush the tmp file to stable storage before
+      // the rename publishes it. Filesystems without fsync support report
+      // ENOTSUP/EINVAL/EBADF — those are ignored so writes still land.
+      let handle;
+      try {
+        handle = await fs.open(tempPath, 'r');
+        await handle.sync();
+      } catch (syncError) {
+        if (!['ENOTSUP', 'EINVAL', 'EBADF'].includes(syncError?.code)) throw syncError;
+      } finally {
+        if (handle) await handle.close().catch(() => {});
+      }
+    }
+    // Test-only crash-injection hook (TASK-002): UKIT_TEST_CRASH_AT=
+    // 'pre-rename' kills the process after the tmp write but before the
+    // rename publishes it — proving a mid-write crash is all-or-nothing.
+    if (process.env.UKIT_TEST_CRASH_AT === 'pre-rename') process.exit(1);
     try {
       await withTransientFsRetry(() => fs.rename(tempPath, filePath));
     } catch (renameError) {
@@ -179,8 +197,8 @@ export async function copyFileRawExclusive(fromPath, toPath) {
   await fs.copyFile(fromPath, toPath, fs.constants.COPYFILE_EXCL);
 }
 
-export async function writeJson(filePath, data) {
-  await writeFileAtomic(filePath, `${JSON.stringify(data, null, 2)}\n`);
+export async function writeJson(filePath, data, opts) {
+  await writeFileAtomic(filePath, `${JSON.stringify(data, null, 2)}\n`, opts);
 }
 
 const LOCK_STALE_MS = 10_000;

package/src/core/memory/deltaOverlays.js

@@ -30,7 +30,8 @@
 
 import crypto from 'node:crypto';
 import { loadRuntimeConfig, resolveConfigStage } from '../runtimeConfig.js';
-import { addRecord, queryRecords, updateRecord } from './storeV2.js';
+import { queryRecords } from './storeV2.js';
+import { mutateMemory } from './mutateMemory.js';
 
 export const OVERLAY_PROVENANCE = 'delta-overlay';
 export const OVERLAY_OPS = Object.freeze(['insert', 'suppress', 'replace-field']);
@@ -261,13 +262,29 @@ async function findOverlayRecord(projectRoot, overlayId) {
   ) ?? null;
 }
 
-async function persistOverlayStatus(projectRoot, overlayId, status, extraMeta = {}) {
+export async function persistOverlayStatus(projectRoot, overlayId, status, extraMeta = {}, { expectedRevision } = {}) {
   try {
     const record = await findOverlayRecord(projectRoot, overlayId);
     if (!record) return null;
-    return await updateRecord(projectRoot, record.id, {
-      meta: { ...record.meta, status, ...extraMeta },
-    });
+    const res = await mutateMemory(
+      { kind: 'project', projectRoot },
+      {
+        op: 'update',
+        payload: {
+          id: record.id,
+          patch: {
+            meta: { ...record.meta, status, ...extraMeta },
+            // Approval is a trust transition — the overlay becomes
+            // authoritative (FR-018); other statuses keep the tier.
+            ...(status === 'approved' ? { trust_tier: 'verified' } : {}),
+          },
+        },
+        expectedRevision: expectedRevision ?? record.revision ?? 1,
+        actor: 'learning',
+      },
+    );
+    if (res.status === 'ok') return res.record;
+    return null;
   } catch {
     return null;
   }
@@ -357,22 +374,33 @@ export async function registerOverlay(projectRoot, overlay) {
   };
 
   const existing = await findOverlayRecord(projectRoot, overlay.id);
-  if (existing) {
-    return updateRecord(projectRoot, existing.id, {
-      meta: { ...existing.meta, ...meta, registeredAt: existing.meta?.registeredAt ?? meta.registeredAt },
-    });
-  }
+  if (existing) return existing;
 
-  return addRecord(projectRoot, {
-    type: 'derived_fact',
-    scope: OVERLAY_TO_RECORD_SCOPE[overlay.scope] ?? 'session',
-    text: `Delta overlay ${overlay.id} on ${overlay.baseContract}@${overlay.baseVersion} (${overlay.operations.length} op${overlay.operations.length === 1 ? '' : 's'})`,
-    provenance: OVERLAY_PROVENANCE,
-    confidence: 0.8,
-    createdBy: 'delta-overlay',
-    projectId: overlay.projectId ?? null,
-    meta,
-  });
+  try {
+    const res = await mutateMemory(
+      { kind: 'project', projectRoot },
+      {
+        op: 'add',
+        payload: {
+          type: 'derived_fact',
+          scope: OVERLAY_TO_RECORD_SCOPE[overlay.scope] ?? 'session',
+          text: `Delta overlay ${overlay.id} on ${overlay.baseContract}@${overlay.baseVersion} (${overlay.operations.length} op${overlay.operations.length === 1 ? '' : 's'})`,
+          provenance: OVERLAY_PROVENANCE,
+          confidence: 0.8,
+          createdBy: 'delta-overlay',
+          projectId: overlay.projectId ?? null,
+          trustTier: meta.status === 'approved' ? 'verified' : 'candidate',
+          meta,
+        },
+        idempotencyKey: `ov:${overlay.id}`,
+        actor: 'learning',
+      },
+    );
+    if (res.status === 'ok' || res.status === 'duplicate') return res.record ?? null;
+    return null;
+  } catch {
+    return null;
+  }
 }
 
 /**
@@ -382,16 +410,33 @@ export async function registerOverlay(projectRoot, overlay) {
  */
 export async function rollbackOverlay(projectRoot, overlayId) {
   if (!isNonEmptyString(overlayId)) return null;
-  const record = await findOverlayRecord(projectRoot, overlayId);
-  if (!record) return null;
-  return updateRecord(projectRoot, record.id, {
-    meta: {
-      ...record.meta,
-      status: 'expired',
-      enabled: false,
-      rolledBackAt: Date.now(),
-    },
-  });
+  try {
+    const record = await findOverlayRecord(projectRoot, overlayId);
+    if (!record) return null;
+    const res = await mutateMemory(
+      { kind: 'project', projectRoot },
+      {
+        op: 'update',
+        payload: {
+          id: record.id,
+          patch: {
+            meta: {
+              ...record.meta,
+              status: 'expired',
+              enabled: false,
+              rolledBackAt: Date.now(),
+            },
+          },
+        },
+        expectedRevision: record.revision ?? 1,
+        actor: 'learning',
+      },
+    );
+    if (res.status === 'ok') return res.record;
+    return null;
+  } catch {
+    return null;
+  }
 }
 
 /**

package/src/core/memory/learningCandidates.js

@@ -22,7 +22,8 @@
 
 import crypto from 'node:crypto';
 import { loadRuntimeConfig, resolveConfigStage } from '../runtimeConfig.js';
-import { addRecord, queryRecords } from './storeV2.js';
+import { queryRecords } from './storeV2.js';
+import { mutateMemory } from './mutateMemory.js';
 
 export const OBSERVATION_PROVENANCE = 'learning-observation';
 export const CANDIDATE_PROVENANCE = 'learning-candidate';
@@ -175,27 +176,52 @@ export async function observeLearningSignal(projectRoot, signal = {}) {
   const text = boundText(signal.text, MAX_SIGNAL_TEXT);
   const target = boundText(signal.target);
   const signature = `${signal.kind}:${normalizeText(target ?? text)}`.slice(0, MAX_META_FIELD);
-
-  return addRecord(projectRoot, {
-    type: 'derived_fact',
-    scope: CANDIDATE_TO_RECORD_SCOPE[signalScopeHint(signal)],
-    text: `learning-signal ${signal.kind}: ${String(text).trim()}`,
-    provenance: OBSERVATION_PROVENANCE,
-    confidence: 0.3,
-    createdBy: 'learning-observe',
-    projectId: boundText(signal.projectId),
-    meta: {
-      kind: signal.kind,
-      signature,
-      sessionId: boundText(signal.sessionId),
-      scopeHint: signalScopeHint(signal),
-      target,
-      condition: boundText(signal.condition),
-      proposedDelta: boundDelta(signal.proposedDelta),
-      evidenceRef: boundText(signal.evidenceRef),
-      observedAt: Date.now(),
-    },
-  });
+  // Idempotency is per (signature, session): the same signal re-observed in
+  // the same session is one record, while distinct sessions still count as
+  // separate occurrences for the minSessions promotion gate.
+  const signalHash = crypto.createHash('sha1')
+    .update(`${signature}|${boundText(signal.sessionId) ?? ''}`)
+    .digest('hex');
+
+  try {
+    const res = await mutateMemory(
+      { kind: 'project', projectRoot },
+      {
+        op: 'add',
+        payload: {
+          type: 'derived_fact',
+          scope: CANDIDATE_TO_RECORD_SCOPE[signalScopeHint(signal)],
+          text: `learning-signal ${signal.kind}: ${String(text).trim()}`,
+          provenance: OBSERVATION_PROVENANCE,
+          confidence: 0.3,
+          createdBy: 'learning-observe',
+          projectId: boundText(signal.projectId),
+          trustTier: 'observation',
+          meta: {
+            kind: signal.kind,
+            signature,
+            sessionId: boundText(signal.sessionId),
+            scopeHint: signalScopeHint(signal),
+            target,
+            condition: boundText(signal.condition),
+            proposedDelta: boundDelta(signal.proposedDelta),
+            evidenceRef: boundText(signal.evidenceRef),
+            observedAt: Date.now(),
+          },
+        },
+        idempotencyKey: `obs:${signalHash}`,
+        actor: 'learning',
+      },
+      // Recurring signals share meta.signature with different text — generic
+      // classification would REVIEW-archive them as 'contradiction'. Dedupe
+      // here is the idempotency journal, not text classification.
+      { classifyAdd: () => ({ action: 'ADD' }) },
+    );
+    if (res.status === 'ok' || res.status === 'duplicate') return res.record ?? null;
+    return null;
+  } catch {
+    return null;
+  }
 }
 
 function candidateText(kind, signalText, occurrences, sessions) {
@@ -270,32 +296,51 @@ export async function maybeCreateCandidate(projectRoot) {
     const conflicts = detectCandidateConflicts(draft, records);
 
     const candidateId = `lc_${crypto.randomBytes(6).toString('hex')}`;
-    return addRecord(projectRoot, {
-      type: 'derived_fact',
-      scope: CANDIDATE_TO_RECORD_SCOPE[scope],
-      text: candidateText(first.meta?.kind, first.text, group.length, sessions.size),
-      provenance: CANDIDATE_PROVENANCE,
-      confidence: Math.min(0.9, 0.4 + group.length * 0.1),
-      createdBy: 'learning-candidate',
-      projectId,
-      meta: {
-        id: candidateId,
-        candidateId,
-        schemaVersion: 1,
-        status: 'proposed',
-        signature,
-        kind: first.meta?.kind ?? null,
-        scope,
-        proposalType: PROPOSAL_TYPE_BY_KIND[first.meta?.kind] ?? 'knowledge',
-        condition: first.meta?.condition ?? `when ${first.meta?.kind ?? 'signal'} recurs`,
-        proposedDelta: draft.proposedDelta,
-        target: draft.target,
-        evidenceRefs,
-        occurrences: group.length,
-        sessions: sessions.size,
-        conflicts,
-      },
-    });
+    try {
+      const res = await mutateMemory(
+        { kind: 'project', projectRoot },
+        {
+          op: 'add',
+          payload: {
+            type: 'derived_fact',
+            scope: CANDIDATE_TO_RECORD_SCOPE[scope],
+            text: candidateText(first.meta?.kind, first.text, group.length, sessions.size),
+            provenance: CANDIDATE_PROVENANCE,
+            confidence: Math.min(0.9, 0.4 + group.length * 0.1),
+            createdBy: 'learning-candidate',
+            projectId,
+            trustTier: 'candidate',
+            meta: {
+              id: candidateId,
+              candidateId,
+              schemaVersion: 1,
+              status: 'proposed',
+              signature,
+              kind: first.meta?.kind ?? null,
+              scope,
+              proposalType: PROPOSAL_TYPE_BY_KIND[first.meta?.kind] ?? 'knowledge',
+              condition: first.meta?.condition ?? `when ${first.meta?.kind ?? 'signal'} recurs`,
+              proposedDelta: draft.proposedDelta,
+              target: draft.target,
+              evidenceRefs,
+              occurrences: group.length,
+              sessions: sessions.size,
+              conflicts,
+            },
+          },
+          idempotencyKey: `cand:${projectId ?? ''}|${signature}`,
+          actor: 'learning',
+        },
+        // Candidate text differs from its source observations under the same
+        // meta.signature — generic classification would REVIEW-archive it as
+        // 'contradiction'. Dedupe is the signature scan above + journal.
+        { classifyAdd: () => ({ action: 'ADD' }) },
+      );
+      if (res.status === 'ok' || res.status === 'duplicate') return res.record ?? null;
+      return null;
+    } catch {
+      return null;
+    }
   }
 
   return firstExisting;

package/src/core/memory/memoryFlags.js

@@ -0,0 +1,83 @@
+// memoryFlags — unified memoryV2 rollout control (SPEC §5 FR-002/FR-004).
+//
+// Four planes (eligibility/writer/index/decision) share the generic
+// resolveConfigStage machinery: off → shadow → canary → default. Flags only
+// ever REDUCE capability — malformed/missing resolves 'off', killSwitch is
+// absolute, and 'canary' without an opted-in projectId resolves 'off'.
+//
+// Shadow receipts are the only telemetry: bounded JSONL of counts/codes/
+// latency bands — never record text, prompt bodies, or secrets.
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { resolveConfigStage } from '../runtimeConfig.js';
+
+export const MEMORY_PLANES = Object.freeze(['eligibility', 'writer', 'index', 'decision']);
+
+const RECEIPT_MAX_BYTES = 64 * 1024;
+const RECEIPT_KEEP_LINES = 200;
+const RECEIPT_FIELDS = ['plane', 'stage', 'outcome', 'code', 'latencyBand'];
+
+/**
+ * resolveMemoryStage(config, plane, { projectId } = {})
+ *   → 'off'|'shadow'|'canary'|'default'
+ * Pure, no I/O. Resolution order: killSwitch → 'off'; malformed/missing →
+ * 'off'; 'canary' + projectId not in canaryProjects → 'off'.
+ */
+export function resolveMemoryStage(config, plane, { projectId } = {}) {
+  const memoryV2 = config?.memoryV2;
+  if (memoryV2 === null || typeof memoryV2 !== 'object' || Array.isArray(memoryV2)) {
+    return 'off';
+  }
+  if (memoryV2.killSwitch === true) {
+    return 'off';
+  }
+  const stage = resolveConfigStage(config, `memoryV2.${plane}.stage`);
+  if (stage === 'canary') {
+    const list = Array.isArray(memoryV2.canaryProjects) ? memoryV2.canaryProjects : [];
+    return projectId != null && list.includes(projectId) ? 'canary' : 'off';
+  }
+  return stage;
+}
+
+/** 'canary'|'default' → the new path is live for this project. */
+export function isMemoryPlaneLive(stage) {
+  return stage === 'canary' || stage === 'default';
+}
+
+/** Latency band for receipt telemetry — bands only, never raw timings. */
+export function latencyBandForMs(ms) {
+  if (!Number.isFinite(ms) || ms < 0) return 'over';
+  if (ms < 50) return 'p50';
+  if (ms < 200) return 'p95';
+  if (ms < 1000) return 'p99';
+  return 'over';
+}
+
+/**
+ * appendRolloutReceipt(root, receipt) → Promise<void>
+ * Bounded JSONL at .ukit/storage/memory/rollout-receipts.jsonl; rotates to
+ * the last 200 lines once the file exceeds 64KB. Only the whitelisted fields
+ * are written — content fields are stripped, never persisted. All failures
+ * are swallowed: telemetry must never break the operation it measures.
+ */
+export async function appendRolloutReceipt(root, receipt = {}) {
+  try {
+    const line = { ts: Date.now() };
+    for (const field of RECEIPT_FIELDS) {
+      if (receipt[field] !== undefined) line[field] = receipt[field];
+    }
+    const dir = path.join(root, '.ukit', 'storage', 'memory');
+    const file = path.join(dir, 'rollout-receipts.jsonl');
+    await fs.mkdir(dir, { recursive: true });
+    await fs.appendFile(file, `${JSON.stringify(line)}\n`, 'utf8');
+    const stat = await fs.stat(file);
+    if (stat.size > RECEIPT_MAX_BYTES) {
+      const lines = (await fs.readFile(file, 'utf8')).split('\n').filter(Boolean);
+      await fs.writeFile(file, `${lines.slice(-RECEIPT_KEEP_LINES).join('\n')}\n`, 'utf8');
+    }
+  } catch {
+    // EACCES / ENOSPC / vanished dir — swallowed by contract.
+  }
+}

package/src/core/memory/memoryFreshness.js

@@ -0,0 +1,190 @@
+// memoryFreshness.js — bounded freshness resolver for v2 memory records.
+//
+// Maps a record's evidence to { state: 'fresh'|'stale'|'unknown', detail }
+// using file fingerprints and caller-supplied watermarks. `unknown` is a
+// label, never an upgrade. I/O is capped at MAX_EVIDENCE (8) stat calls per
+// record — evidence locators only, no directory walks, no git spawns.
+//
+// Contract (SPEC §5 FR-003/FR-004, §8):
+//   resolveRecordFreshness(record, { projectRoot, watermarks?, now? })
+//     -> Promise<{ state, detail }>   // never rejects
+//   fileFingerprint(absPath)
+//     -> Promise<'fs:<mtimeMs>:<size>'|null>
+
+import crypto from 'node:crypto';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+
+import { MAX_EVIDENCE } from './records.js';
+
+const FRESH = 'fresh';
+const STALE = 'stale';
+const UNKNOWN = 'unknown';
+
+/**
+ * fileFingerprint(absPath) → 'fs:<mtimeMs>:<size>' or null on any fs error.
+ */
+export async function fileFingerprint(absPath) {
+  try {
+    const st = await fsp.stat(absPath);
+    if (!st.isFile()) return null;
+    return `fs:${st.mtimeMs}:${st.size}`;
+  } catch {
+    return null;
+  }
+}
+
+async function sha1Fingerprint(absPath) {
+  try {
+    const buf = await fsp.readFile(absPath);
+    return `sha1:${crypto.createHash('sha1').update(buf).digest('hex')}`;
+  } catch {
+    return null;
+  }
+}
+
+// Resolve a file-evidence locator against projectRoot. Returns the absolute
+// path when it stays inside projectRoot, else null (unverifiable — never
+// followed). Absolute locators are used as-is but must still land inside
+// projectRoot.
+function resolveLocator(projectRoot, locator) {
+  if (typeof locator !== 'string' || locator.length === 0) return null;
+  const root = path.resolve(projectRoot);
+  const abs = path.resolve(root, locator);
+  if (abs !== root && !abs.startsWith(root + path.sep)) return null;
+  return abs;
+}
+
+async function checkFileEvidence(projectRoot, entry) {
+  const abs = resolveLocator(projectRoot, entry.locator);
+  if (abs == null) return { state: UNKNOWN, detail: 'locator-unverifiable' };
+
+  // Symlink defense (SPEC §14): a locator that resolves inside projectRoot
+  // but lands on a symlink pointing outside must never be followed — the
+  // realpath containment check makes escapes unverifiable → 'unknown'.
+  try {
+    const lst = await fsp.lstat(abs);
+    if (lst.isSymbolicLink()) {
+      const root = path.resolve(projectRoot);
+      const real = await fsp.realpath(abs).catch(() => null);
+      if (real == null || (real !== root && !real.startsWith(root + path.sep))) {
+        return { state: UNKNOWN, detail: 'locator-unverifiable' };
+      }
+    }
+  } catch {
+    // lstat failure → fall through to the normal stat path, which maps
+    // ENOENT to 'file-missing' and other errors to 'file-unverified'.
+  }
+
+  const fp = entry.fingerprint;
+  if (typeof fp === 'string' && fp.startsWith('sha1:')) {
+    const actual = await sha1Fingerprint(abs);
+    if (actual == null) {
+      // Distinguish missing file from unreadable file.
+      const probe = await fileFingerprint(abs);
+      if (probe == null) {
+        try {
+          await fsp.stat(abs);
+          return { state: UNKNOWN, detail: 'file-unverified' }; // exists, unreadable
+        } catch {
+          return { state: STALE, detail: 'file-missing' };
+        }
+      }
+      return { state: UNKNOWN, detail: 'file-unverified' };
+    }
+    return actual === fp
+      ? { state: FRESH, detail: 'file-match' }
+      : { state: STALE, detail: 'file-changed' };
+  }
+
+  let st;
+  try {
+    st = await fsp.stat(abs);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return { state: STALE, detail: 'file-missing' };
+    return { state: UNKNOWN, detail: 'file-unverified' };
+  }
+  if (!st.isFile()) return { state: STALE, detail: 'file-missing' };
+
+  if (typeof fp !== 'string' || fp.length === 0) {
+    return { state: UNKNOWN, detail: 'file-unverified' };
+  }
+  if (fp.startsWith('fs:')) {
+    return `fs:${st.mtimeMs}:${st.size}` === fp
+      ? { state: FRESH, detail: 'file-match' }
+      : { state: STALE, detail: 'file-changed' };
+  }
+  // Unrecognized fingerprint scheme — cannot verify.
+  return { state: UNKNOWN, detail: 'file-unverified' };
+}
+
+// Non-file evidence (command|ledger|manual|import): compare the caller-
+// supplied watermarks[kind] against the observed watermark. String
+// watermarks (e.g. command → head sha) compare against entry.locator;
+// numeric watermarks (e.g. ledger → generation/epoch) compare against
+// entry.observed_at, falling back to record.revision.
+function checkWatermarkEvidence(entry, record, watermarks) {
+  const wm = watermarks != null ? watermarks[entry.kind] : undefined;
+  if (wm == null) return { state: UNKNOWN, detail: 'watermark-missing' };
+  if (typeof wm === 'string') {
+    return wm === entry.locator
+      ? { state: FRESH, detail: 'watermark-match' }
+      : { state: STALE, detail: 'watermark-stale' };
+  }
+  if (typeof wm === 'number' && Number.isFinite(wm)) {
+    const observed = Number.isFinite(entry.observed_at)
+      ? entry.observed_at
+      : record.revision;
+    return observed === wm
+      ? { state: FRESH, detail: 'watermark-match' }
+      : { state: STALE, detail: 'watermark-stale' };
+  }
+  return { state: UNKNOWN, detail: 'watermark-missing' };
+}
+
+/**
+ * resolveRecordFreshness(record, { projectRoot, watermarks = {}, now } = {})
+ *   → Promise<{ state: 'fresh'|'stale'|'unknown', detail: string }>
+ *
+ * Aggregate precedence: any stale → stale; else any unknown → unknown;
+ * else fresh. Never rejects — every per-entry error degrades to `unknown`.
+ */
+export async function resolveRecordFreshness(record, { projectRoot, watermarks = {}, now } = {}) {
+  void now;
+  try {
+    const evidence = Array.isArray(record?.evidence) ? record.evidence : [];
+    if (evidence.length === 0) return { state: UNKNOWN, detail: 'no-evidence' };
+
+    let sawStale = false;
+    let sawUnknown = false;
+    let firstDetail = 'no-evidence';
+
+    for (const entry of evidence.slice(0, MAX_EVIDENCE)) {
+      let verdict;
+      try {
+        if (entry != null && entry.kind === 'file') {
+          verdict = await checkFileEvidence(projectRoot, entry);
+        } else {
+          verdict = checkWatermarkEvidence(entry ?? {}, record ?? {}, watermarks);
+        }
+      } catch {
+        verdict = { state: UNKNOWN, detail: 'file-unverified' };
+      }
+      if (verdict.state === STALE) {
+        if (!sawStale) firstDetail = verdict.detail;
+        sawStale = true;
+      } else if (verdict.state === UNKNOWN) {
+        if (!sawStale && !sawUnknown) firstDetail = verdict.detail;
+        sawUnknown = true;
+      } else if (!sawStale && !sawUnknown) {
+        firstDetail = verdict.detail;
+      }
+    }
+
+    if (sawStale) return { state: STALE, detail: firstDetail };
+    if (sawUnknown) return { state: UNKNOWN, detail: firstDetail };
+    return { state: FRESH, detail: firstDetail };
+  } catch {
+    return { state: UNKNOWN, detail: 'resolver-error' };
+  }
+}