@ngockhoale/ukit 3.0.8 → 3.0.9

package/src/core/memory/retrieval.js

@@ -6,29 +6,14 @@ import {
   writePromptCacheEntry,
 } from '../token/index.js';
 import { listMemoryItems } from './store.js';
-import { isRecordUsable } from './records.js';
 import { loadV2Records } from './storeV2Loader.js';
+import { POLICY_VERSION, eligible, resolveEffectiveScope } from './policy.js';
 import { loadRuntimeConfig } from '../runtimeConfig.js';
-
-const STOPWORDS = new Set([
-  'the', 'a', 'an', 'and', 'or', 'to', 'for', 'of', 'with', 'in', 'on', 'is', 'are',
-  'this', 'that', 'it', 'as', 'by', 'be', 'use', 'using', 'implement', 'fix', 'task',
-  'cần', 'và', 'là', 'cho', 'một', 'những', 'dùng',
-]);
-
-function normalize(text) {
-  return String(text ?? '')
-    .toLowerCase()
-    .replace(/[^\p{L}\p{N}\s./:_-]/gu, ' ')
-    .replace(/\s+/g, ' ')
-    .trim();
-}
-
-function tokenize(text) {
-  return normalize(text)
-    .split(/\s+/)
-    .filter((token) => token && !STOPWORDS.has(token) && token.length > 1);
-}
+import { resolveMemoryStage, appendRolloutReceipt, latencyBandForMs } from './memoryFlags.js';
+import { createIndex, normalize, scoreRecordTokens, tokenize } from './recordIndex.js';
+import { buildMemoryHit, rankHits } from './memoryHit.js';
+import { resolveRecordFreshness } from './memoryFreshness.js';
+import { getHeadSha } from '../codeintel/freshness.js';
 
 function compactPhraseList(values, { limit = 1, fallback = 'n/a' } = {}) {
   const normalized = [...new Set(
@@ -131,21 +116,33 @@ function scoreItem(item, queryTokens) {
   return score + recencyBonus;
 }
 
-function withinScope(item, scope, projectId) {
+// projectId + registry-attested aliases (legacy display names recorded at
+// mint time) — migrated v1 records keep the name as project_id (M01-05).
+function boundProjectIds(projectId, projectAliases) {
+  const ids = new Set();
+  if (typeof projectId === 'string' && projectId) ids.add(projectId);
+  for (const alias of projectAliases ?? []) {
+    if (typeof alias === 'string' && alias) ids.add(alias);
+  }
+  return ids;
+}
+
+function withinScope(item, scope, projectId, projectAliases) {
   if (scope !== 'all' && item.type !== scope) {
     return false;
   }
 
-  if (!projectId) {
+  const boundIds = boundProjectIds(projectId, projectAliases);
+  if (boundIds.size === 0) {
     return true;
   }
 
   if (item.type === 'project') {
-    return item.content?.id === projectId;
+    return boundIds.has(item.content?.id);
   }
 
   if (item.type === 'session') {
-    return item.content?.projectId === projectId;
+    return boundIds.has(item.content?.projectId);
   }
 
   return true;
@@ -164,109 +161,205 @@ function buildSearchResult(item, relevanceScore) {
 
 // ---- Memory v2 records path (SPEC §2–§3) ----
 
-const RECORD_TYPE_WEIGHTS = Object.freeze({
+export const RECORD_TYPE_WEIGHTS = Object.freeze({
   project_rule: 7,
   derived_fact: 5,
   procedure: 5,
   episode: 3,
 });
 
-// Lazy import: storeV2.js is owned by TASK-002; missing module or a disabled
-// memoryV2 config falls back to the legacy items path. queryRecords itself
-// triggers ensureMigrated on the real store — no explicit migration here.
-async function queryV2Records(projectRoot) {
+// Lazy import: storeV2.js is owned by TASK-002; the loader reports a typed
+// {state, records} result. Legacy fallback is allowed ONLY on 'missing' or
+// 'empty' — 'corrupt'|'disabled'|'migrating' mean the v2 lane is authoritative
+// and empty (FR-008). queryRecords itself triggers ensureMigrated on the real
+// store — no explicit migration here.
+async function queryV2Records(projectRoot, { projectId } = {}) {
+  let policy = {};
+  let config = null;
   try {
-    const config = await loadRuntimeConfig(projectRoot);
+    config = await loadRuntimeConfig(projectRoot);
     if (config?.memoryV2?.enabled === false) {
-      return [];
+      return { state: 'disabled', records: [], policy, generation: 0 };
+    }
+    if (config?.memoryV2?.policy && typeof config.memoryV2.policy === 'object') {
+      policy = config.memoryV2.policy;
     }
   } catch {
-    // unreadable config → default enabled, keep going
-  }
-  return loadV2Records(projectRoot, {});
+    // unreadable config → default enabled, default policy, keep going
+  }
+  // M06 rollout flag (SPEC §5 FR-003): eligibility stage gates the v2 read
+  // lane. 'off' (incl. killSwitch / unlisted canary) → legacy lane output,
+  // byte-identical. 'shadow' runs the v2 load for measurement, discards it,
+  // emits a receipt, and still serves the legacy lane.
+  const eligibilityStage = config
+    ? resolveMemoryStage(config, 'eligibility', { projectId })
+    : 'default';
+  if (eligibilityStage === 'off') {
+    return { state: 'missing', records: [], policy, generation: 0 };
+  }
+  if (eligibilityStage === 'shadow') {
+    const startedAt = Date.now();
+    const probe = await loadV2Records(projectRoot, {});
+    await appendRolloutReceipt(projectRoot, {
+      plane: 'eligibility',
+      stage: 'shadow',
+      outcome: probe.state === 'ok' ? 'ok' : 'error',
+      code: probe.state,
+      latencyBand: latencyBandForMs(Date.now() - startedAt),
+    });
+    return { state: 'missing', records: [], policy, generation: 0 };
+  }
+  const { state, records, generation } = await loadV2Records(projectRoot, {}, { config, projectId });
+  // Index plane (FR-003): 'off' → linear scan; 'shadow' → indexed path runs
+  // for measurement only, linear result is served; live → indexed path.
+  const indexStage = config
+    ? resolveMemoryStage(config, 'index', { projectId })
+    : 'default';
+  return { state, records, policy, generation: generation ?? 0, indexStage };
 }
 
-function scoreRecord(record, queryTokens) {
-  const typeWeight = RECORD_TYPE_WEIGHTS[record.type] ?? 1;
-  if (queryTokens.length === 0) {
-    return typeWeight * Math.max(0.1, record.confidence ?? 1);
-  }
-
-  const recordTokens = new Set(tokenize(`${record.text ?? ''} ${record.provenance ?? ''}`));
-  let matched = 0;
-  for (const token of queryTokens) {
-    if (recordTokens.has(token)) {
-      matched += 1;
-    }
-  }
-  if (matched === 0) {
-    return 0;
-  }
-
-  const recencyBonus = record.created_at > 0
-    ? Math.min(1, record.created_at / Date.now())
-    : 0;
-  return typeWeight * matched * Math.max(0.1, record.confidence ?? 1) + recencyBonus;
+// 'missing'|'empty' → legacy compat lane; every other state keeps the v2 lane
+// authoritative (deny-by-default, no silent legacy injection).
+function v2AllowsLegacyFallback(state) {
+  return state === 'missing' || state === 'empty';
 }
 
 // Legacy scope names ('user'|'project'|'session') map onto v2 scope/type:
 // 'project' ↔ scope 'repo'/'task', 'session' ↔ type 'episode'.
-const LEGACY_SCOPE_MATCH = {
+export const LEGACY_SCOPE_MATCH = {
   user: (record) => record.scope === 'user',
   project: (record) => record.scope === 'repo' || record.scope === 'task',
   session: (record) => record.type === 'episode' || record.scope === 'session',
 };
 
-function recordWithinScope(record, scope, projectId) {
-  if (scope !== 'all') {
-    const matcher = LEGACY_SCOPE_MATCH[scope];
-    const matches = matcher ? matcher(record) : (record.scope === scope || record.type === scope);
-    if (!matches) return false;
-  }
-  if (projectId && record.project_id && record.project_id !== projectId) {
-    return false;
-  }
-  return true;
+// TASK-003 (FR-005): both v2 search paths delegate ranking to rankHits.
+// rankHits includes bonus-only (lexical=0) records; the index path can only
+// surface token-matching candidates, so the scan path pre-filters to the
+// same candidate pool (scoreRecordTokens > 0) — identical hits either way.
+function searchRecords(records, query, scope, limit, eligibleCtx, policy) {
+  const queryTokens = tokenize(query);
+  const candidates = records.filter((record) => scoreRecordTokens(record, queryTokens) > 0);
+  return rankHits(candidates, { queryTokens, eligibleCtx, policy, scope, limit });
 }
 
-function buildRecordSearchResult(record, relevanceScore) {
-  return {
-    id: record.id,
-    summary: record.text,
-    relevanceScore,
-    source: record.type,
-    timestamp: record.created_at ?? 0,
-    sourcePath: null,
-  };
+// Freshness is resolved post-limit only (≤ limit × MAX_EVIDENCE stats per
+// call). Watermarks are caller-supplied; when omitted and a hit carries
+// non-file evidence, `command` is filled lazily via getHeadSha (one bounded
+// git spawn per call, never per record). Resolver errors degrade to
+// 'unknown' and never break search.
+async function attachFreshness(hits, records, { projectRoot, watermarks } = {}) {
+  if (!Array.isArray(hits) || hits.length === 0) return hits;
+  const recordById = new Map((records ?? []).map((record) => [record.id, record]));
+  const needsCommand = watermarks?.command == null && hits.some((hit) => {
+    const record = recordById.get(hit.id);
+    return Array.isArray(record?.evidence)
+      && record.evidence.some((entry) => entry != null && entry.kind !== 'file');
+  });
+  const resolvedWatermarks = { ...(watermarks ?? {}) };
+  if (needsCommand) {
+    try {
+      resolvedWatermarks.command = getHeadSha(projectRoot);
+    } catch { /* absent → unknown */ }
+  }
+  await Promise.all(hits.map(async (hit) => {
+    const record = recordById.get(hit.id);
+    hit.freshness = await resolveRecordFreshness(record, {
+      projectRoot,
+      watermarks: resolvedWatermarks,
+    });
+  }));
+  return hits;
+}
+
+// Legacy requested scopes map onto policy scopes: 'project' is repo-bound.
+const REQUESTED_SCOPE_TO_POLICY = { project: 'repo' };
+
+// TASK-003 (FR-006/FR-007): module-scoped inverted index, in-process only,
+// never persisted. Cache key = projectRoot + project identity + POLICY_VERSION;
+// validity additionally requires index.generation === store generation. Any
+// mismatch, absence, or error falls back to the lexical scan — the index
+// narrows candidates, rankHits re-gates + scores (identical output either
+// path: the index candidate pool is exactly the score>0 set the scan uses).
+// Module-scoped index cache (in-process only, never persisted).
+const recordIndexes = new Map();
+
+export function resetRecordIndexForTests() {
+  recordIndexes.clear();
 }
 
-function searchRecords(records, query, scope, limit, projectId) {
+function searchRecordsIndexed(records, query, scope, limit, eligibleCtx, policy, indexKey, generation) {
   const queryTokens = tokenize(query);
-  return records
-    .filter((record) => isRecordUsable(record))
-    .filter((record) => recordWithinScope(record, scope, projectId))
-    .map((record) => ({ record, score: scoreRecord(record, queryTokens) }))
-    .filter((entry) => entry.score > 0)
-    .sort((left, right) => (
-      right.score - left.score
-      || (right.record.created_at ?? 0) - (left.record.created_at ?? 0)
-      || String(right.record.text ?? '').localeCompare(String(left.record.text ?? ''))
-    ))
-    .slice(0, limit)
-    .map((entry) => buildRecordSearchResult(entry.record, entry.score));
+  if (queryTokens.length === 0) {
+    return searchRecords(records, query, scope, limit, eligibleCtx, policy);
+  }
+  try {
+    let index = recordIndexes.get(indexKey);
+    if (!index) {
+      index = createIndex();
+      recordIndexes.set(indexKey, index);
+    }
+    if (index.stats().generation !== generation) {
+      index.build(records, { generation });
+    }
+    const candidates = index.query(queryTokens, { limit: records.length })
+      .map((hit) => hit.record);
+    return rankHits(candidates, { queryTokens, eligibleCtx, policy, scope, limit });
+  } catch {
+    return searchRecords(records, query, scope, limit, eligibleCtx, policy);
+  }
 }
 
-export async function search(query, scope = 'all', limit = 10, { projectRoot, projectId } = {}) {
-  const records = await queryV2Records(projectRoot);
-  if (records.length > 0) {
-    return searchRecords(records, query, scope, limit, projectId);
+export async function search(query, scope = 'all', limit = 10, { projectRoot, projectId, projectAliases, index = true, watermarks } = {}) {
+  const { state, records, policy, generation, indexStage } = await queryV2Records(projectRoot, { projectId });
+  const effective = resolveEffectiveScope(
+    { projectId: projectId ?? null },
+    REQUESTED_SCOPE_TO_POLICY[scope] ?? scope,
+  );
+  if (effective.denied) {
+    return [];
+  }
+  const eligibleCtx = {
+    projectId: effective.projectId,
+    projectAliases: projectAliases ?? [],
+    includeUser: effective.includeUser,
+  };
+
+  if (!v2AllowsLegacyFallback(state)) {
+    const indexKey = `${projectRoot ?? ''}::${effective.projectId ?? ''}::${POLICY_VERSION}`;
+    // Index plane (FR-003): 'off' forces the linear scan; 'shadow' runs the
+    // indexed path for measurement, discards it, and serves the scan result
+    // (zero output change) plus a bounded receipt.
+    if (index !== false && indexStage === 'shadow') {
+      const startedAt = Date.now();
+      try {
+        searchRecordsIndexed(records, query, scope, limit, eligibleCtx, policy, indexKey, generation);
+        await appendRolloutReceipt(projectRoot, {
+          plane: 'index', stage: 'shadow', outcome: 'ok', code: 'search',
+          latencyBand: latencyBandForMs(Date.now() - startedAt),
+        });
+      } catch {
+        await appendRolloutReceipt(projectRoot, {
+          plane: 'index', stage: 'shadow', outcome: 'error', code: 'search',
+          latencyBand: latencyBandForMs(Date.now() - startedAt),
+        });
+      }
+    }
+    const hits = index === false || indexStage === 'off' || indexStage === 'shadow'
+      ? searchRecords(records, query, scope, limit, eligibleCtx, policy)
+      : searchRecordsIndexed(
+          records, query, scope, limit, eligibleCtx, policy,
+          indexKey,
+          generation,
+        );
+    return attachFreshness(hits, records, { projectRoot, watermarks });
   }
 
   const items = await listMemoryItems(projectRoot);
   const queryTokens = tokenize(query);
 
+
   return items
-    .filter((item) => withinScope(item, scope, projectId))
+    .filter((item) => withinScope(item, scope, projectId, projectAliases))
     .map((item) => ({
       item,
       score: scoreItem(item, queryTokens),
@@ -309,9 +402,15 @@ function findRelatedItemIds(targetItem, allItems) {
     .slice(0, 5);
 }
 
-export async function expand(id, { projectRoot } = {}) {
-  const records = await queryV2Records(projectRoot);
-  if (records.length > 0) {
+export async function expand(id, { projectRoot, projectId, projectAliases } = {}) {
+  const { state, records, policy } = await queryV2Records(projectRoot, { projectId });
+  if (!v2AllowsLegacyFallback(state)) {
+    const effective = resolveEffectiveScope({ projectId: projectId ?? null }, 'all');
+    const eligibleCtx = {
+      projectId: effective.projectId,
+      projectAliases: projectAliases ?? [],
+      includeUser: effective.includeUser,
+    };
     // Resolve legacy item ids too: 'session:<legacyId>' → episode with
     // meta.legacyId, 'project:<projectId>' → records of that project.
     const colonIdx = String(id).indexOf(':');
@@ -326,12 +425,15 @@ export async function expand(id, { projectRoot } = {}) {
     if (!target) {
       return { id, fullContent: '', relatedItems: [] };
     }
+    const [hit] = await attachFreshness([buildMemoryHit(target)], [target], { projectRoot });
     return {
       id: target.id,
+      hit,
       fullContent: JSON.stringify(target, null, 2),
       relatedItems: records
         .filter((record) => record.id !== target.id)
         .filter((record) => record.type === target.type || record.project_id === target.project_id)
+        .filter((record) => eligible(record, eligibleCtx, policy).ok)
         .map((record) => record.id)
         .slice(0, 5),
     };
@@ -389,9 +491,6 @@ function buildInjectionSnippet(item) {
   return `user-rules=${(content.rules ?? []).slice(0, 3).join('; ') || 'n/a'}`;
 }
 
-function includeUserMemoryOrRecord(includeUserMemory, record) {
-  return includeUserMemory || record.scope !== 'user';
-}
 
 function buildRecordSnippet(record) {
   const text = String(record.text ?? '').trim();
@@ -418,14 +517,6 @@ function resolveRecallPressurePlan({
     };
   }
 
-  if (phase === 'soft') {
-    return {
-      phase,
-      maxTokens: Math.min(maxTokens, Math.max(112, Math.round(maxTokens * 0.88))),
-      limit: Math.max(1, Math.min(limit, 4)),
-      includeUserMemory: true,
-    };
-  }
 
   return {
     phase,
@@ -435,14 +526,17 @@ function resolveRecallPressurePlan({
   };
 }
 
-function isProjectAnchor(item, projectId) {
-  return Boolean(item && item.type === 'project' && (!projectId || item.content?.id === projectId));
+function isProjectAnchor(item, boundIds) {
+  return Boolean(item && item.type === 'project'
+    && (boundIds.size === 0 || boundIds.has(item.content?.id)));
 }
 
-function isSessionAnchor(item, projectId) {
-  return Boolean(item && item.type === 'session' && (!projectId || item.content?.projectId === projectId));
+function isSessionAnchor(item, boundIds) {
+  return Boolean(item && item.type === 'session'
+    && (boundIds.size === 0 || boundIds.has(item.content?.projectId)));
 }
 
+
 function dedupeItemsById(items) {
   const seen = new Set();
   const unique = [];
@@ -460,10 +554,12 @@ function selectContextItems({
   items = [],
   rankedItems = [],
   projectId,
+  projectAliases = [],
   limit = 5,
   includeUserMemory = true,
   allowProjectFallback = false,
 } = {}) {
+  const boundIds = boundProjectIds(projectId, projectAliases);
   const itemById = new Map(items.map((item) => [item.id, item]));
   const rankedSelection = rankedItems
     .map((entry) => itemById.get(entry.id))
@@ -472,13 +568,13 @@ function selectContextItems({
   if (rankedSelection.length === 0 && !allowProjectFallback) {
     return [];
   }
-  const projectAnchor = projectId
-    ? items.find((item) => item.type === 'project' && item.content?.id === projectId)
+  const projectAnchor = boundIds.size > 0
+    ? items.find((item) => item.type === 'project' && boundIds.has(item.content?.id))
     : rankedSelection.find((item) => item.type === 'project');
   const prioritized = dedupeItemsById([
     rankedSelection.length > 0 || allowProjectFallback ? projectAnchor : null,
-    ...rankedSelection.filter((item) => isSessionAnchor(item, projectId)),
-    ...rankedSelection.filter((item) => isProjectAnchor(item, projectId) && item.id !== projectAnchor?.id),
+    ...rankedSelection.filter((item) => isSessionAnchor(item, boundIds)),
+    ...rankedSelection.filter((item) => isProjectAnchor(item, boundIds) && item.id !== projectAnchor?.id),
     ...rankedSelection.filter((item) => item.type !== 'session' && item.type !== 'project'),
   ]);
 
@@ -493,6 +589,7 @@ function buildContextRequestKey({
   inputCompression,
   selectedItems,
   pressurePhase,
+  freshnessById,
 }) {
   return buildCompactMachineKey('memory-recall-v1', {
     currentTask: normalize(currentTask),
@@ -501,10 +598,17 @@ function buildContextRequestKey({
     limit,
     inputCompression,
     pressurePhase,
+    policyVersion: POLICY_VERSION,
     items: selectedItems.map((item) => ({
       id: item.id,
       timestamp: getTimestamp(item),
     })),
+    // FR-006: freshness signature — a stale transition changes the key so a
+    // cached "fresh" block is never served after evidence changed.
+    freshness: selectedItems.map((item) => ({
+      id: item.id,
+      state: freshnessById?.get(item.id)?.state ?? null,
+    })),
   });
 }
 
@@ -517,27 +621,31 @@ export async function getContextInjection(
     limit = 5,
     promptCache = false,
     inputCompression = true,
+    projectAliases = [],
   } = {},
 ) {
-  const records = await queryV2Records(projectRoot);
-  const items = records.length > 0 ? [] : await listMemoryItems(projectRoot);
+  const { state, records, policy } = await queryV2Records(projectRoot, { projectId });
+  const v2Active = !v2AllowsLegacyFallback(state);
+  const items = v2Active ? [] : await listMemoryItems(projectRoot);
   const pressureState = await readCompactPressureState(projectRoot);
   const recallPlan = resolveRecallPressurePlan({
     maxTokens,
     limit,
     pressureState,
   });
-  const rankedItems = await search(currentTask, 'all', Math.max(limit * 3, 8), { projectRoot, projectId });
-  const selectedItems = records.length > 0
+  const rankedItems = await search(currentTask, 'all', Math.max(limit * 3, 8), { projectRoot, projectId, projectAliases });
+  const eligibleCtx = { projectId: projectId ?? null, projectAliases, includeUser: recallPlan.includeUserMemory };
+  const selectedItems = v2Active
     ? dedupeItemsById(rankedItems
         .map((entry) => records.find((record) => record.id === entry.id))
         .filter(Boolean)
-        .filter((record) => includeUserMemoryOrRecord(recallPlan.includeUserMemory, record)))
+        .filter((record) => eligible(record, eligibleCtx, policy).ok))
         .slice(0, Math.max(1, recallPlan.limit))
     : selectContextItems({
         items,
         rankedItems,
         projectId,
+        projectAliases,
         limit: recallPlan.limit,
         includeUserMemory: recallPlan.includeUserMemory,
         allowProjectFallback: !String(currentTask ?? '').trim(),
@@ -547,6 +655,28 @@ export async function getContextInjection(
     return '';
   }
 
+  // FR-005/FR-006: freshness resolved post-selection only (≤ limit records),
+  // before the request key so a stale transition busts the prompt cache.
+  // Watermarks: command → getHeadSha once per call (bounded, never-throw);
+  // no cheap ledger-generation accessor exists → ledger omitted → unknown.
+  const freshnessById = new Map();
+  if (v2Active) {
+    const needsCommand = selectedItems.some((record) => Array.isArray(record?.evidence)
+      && record.evidence.some((entry) => entry != null && entry.kind !== 'file'));
+    const watermarks = {};
+    if (needsCommand) {
+      try {
+        watermarks.command = getHeadSha(projectRoot);
+      } catch { /* absent → unknown */ }
+    }
+    await Promise.all(selectedItems.map(async (record) => {
+      freshnessById.set(record.id, await resolveRecordFreshness(record, {
+        projectRoot,
+        watermarks,
+      }));
+    }));
+  }
+
   const requestKey = buildContextRequestKey({
     currentTask,
     projectId,
@@ -555,6 +685,7 @@ export async function getContextInjection(
     inputCompression,
     selectedItems,
     pressurePhase: recallPlan.phase,
+    freshnessById,
   });
 
   if (promptCache) {
@@ -564,11 +695,14 @@ export async function getContextInjection(
     }
   }
 
-  const rawBodyLines = records.length > 0
-    ? selectedItems.map((record) => `- [${record.type}] ${buildRecordSnippet(record)}`)
+  // FR-005: ' [stale]' appended only when freshness resolves stale; unknown
+  // adds no token.
+  const staleTag = (record) => (freshnessById.get(record.id)?.state === 'stale' ? ' [stale]' : '');
+  const rawBodyLines = v2Active
+    ? selectedItems.map((record) => `- [${record.type}] ${buildRecordSnippet(record)}${staleTag(record)}`)
     : selectedItems.map((item) => `- [${item.type}] ${buildDetailedInjectionSnippet(item)}`);
-  const bodyLines = records.length > 0
-    ? selectedItems.map((record) => `- ${buildRecordSnippet(record)}`)
+  const bodyLines = v2Active
+    ? selectedItems.map((record) => `- ${buildRecordSnippet(record)}${staleTag(record)}`)
     : selectedItems.map((item) => `- ${buildInjectionSnippet(item)}`);
   const rawLines = ['## Previous Context', ...rawBodyLines];
   const rawText = rawLines.join('\n');

package/src/core/memory/store.js

@@ -5,6 +5,7 @@ import { buildRuntimePaths } from '../runtimePaths.js';
 import { readJsonIfExists, writeJson } from '../fileOps.js';
 import { loadRuntimeConfig } from '../runtimeConfig.js';
 import { runHygiene } from './hygiene.js';
+import { redactWritePayload } from './writeGuard.js';
 
 // ---- Memory v2 facade (SPEC §3/§11) ----
 // Every exported signature and CLI output shape is preserved. When the v2
@@ -272,22 +273,26 @@ function createSearchableText(type, content) {
 
 export async function exportMemory(projectRoot) {
   const runtimePaths = buildRuntimePaths(projectRoot);
+  // FR-023/025: export is a bulk read lane — redact at the store boundary so
+  // every caller (CLI, future lanes) gets defense-in-depth, not just the CLI.
+  const config = await loadRuntimeConfig(projectRoot);
+  const redact = (data) => redactWritePayload({ meta: data }, { config }).payload.meta;
   if (await v2Active(projectRoot)) {
     const v2 = await storeV2();
     const items = recordsToMemoryItems(await v2.loadRecords(projectRoot), runtimePaths);
     const user = items.find((item) => item.type === 'user')?.content ?? defaultUserMemory();
-    return {
+    return redact({
       user,
       projects: items.filter((item) => item.type === 'project').map((item) => item.content),
       sessions: items.filter((item) => item.type === 'session').map((item) => item.content),
-    };
+    });
   }
 
   const user = (await readMemoryJson(runtimePaths.userMemoryPath)) ?? defaultUserMemory();
   const projects = (await readDirectoryJsonItems(runtimePaths.projectsDir)).map((item) => item.content);
   const sessions = (await readDirectoryJsonItems(runtimePaths.sessionsDir)).map((item) => item.content);
 
-  return { user, projects, sessions };
+  return redact({ user, projects, sessions });
 }
 
 // Read-compat: corrupt legacy files still surface the same warning the legacy
@@ -352,12 +357,16 @@ export async function listMemoryItems(projectRoot) {
 
 async function forgetMemoryItemV2(projectRoot, memoryId, runtimePaths) {
   const v2 = await storeV2();
+  const { mutateMemory } = await import('./mutateMemory.js');
   const archiveAll = async (records) => {
     let archived = 0;
     for (const record of records) {
       if (record.status !== 'archived') {
-        await v2.updateRecord(projectRoot, record.id, { status: 'archived' });
-        archived += 1;
+        const res = await mutateMemory(
+          { kind: 'project', projectRoot },
+          { op: 'forget', payload: { id: record.id } },
+        );
+        if (res.status === 'ok') archived += 1;
       }
     }
     return archived;
@@ -641,6 +650,8 @@ async function resolvePatternCandidateV2(projectRoot, projectId, candidateId, de
       scope: 'repo',
       confidence: 0.9,
       provenance: `${target.provenance ?? 'pattern-candidate'};promoted-from:${target.id}`,
+      // Approval is a trust transition — the promoted record is authoritative.
+      trust_tier: 'verified',
       meta: {
         ...target.meta,
         legacyStatus: 'approved',