wendkeep 0.73.0 → 0.74.0

package/packages/vault/src/evidence-recall.mjs

@@ -0,0 +1,343 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { basename, join, relative } from 'node:path';
+
+export const EVIDENCE_INDEX_FILE = 'EVIDENCE_INDEX.jsonl';
+export const EVIDENCE_INDEX_VERSION = 1;
+
+const STOP_WORDS = new Set([
+  'a', 'an', 'and', 'as', 'at', 'da', 'das', 'de', 'do', 'dos', 'e', 'em', 'for', 'in',
+  'is', 'o', 'os', 'or', 'para', 'por', 'the', 'to', 'um', 'uma', 'with', 'com', 'que',
+]);
+
+function hash(value) {
+  return createHash('sha256').update(String(value ?? '')).digest('hex');
+}
+
+function cleanText(value) {
+  return String(value ?? '').replace(/\r\n/g, '\n').replace(/[\t ]+/g, ' ').trim();
+}
+
+export function normalizeRecallText(value) {
+  return cleanText(value).normalize('NFD').replace(/[\u0300-\u036f]/g, '').toLowerCase();
+}
+
+export function recallTerms(value) {
+  return normalizeRecallText(value).match(/[\p{L}\p{N}]+(?:[._-][\p{L}\p{N}]+)*/gu)
+    ?.filter((term) => term.length > 1 && !STOP_WORDS.has(term)) || [];
+}
+
+function parseFrontmatter(content) {
+  const match = String(content || '').match(/^---\n([\s\S]*?)\n---(?:\n|$)/);
+  if (!match) return { data: {}, body: String(content || '') };
+  const data = {};
+  for (const line of match[1].split('\n')) {
+    const item = line.match(/^([A-Za-z0-9_-]+):\s*(.*?)\s*$/);
+    if (!item) continue;
+    data[item[1]] = item[2].replace(/^['"]|['"]$/g, '');
+  }
+  return { data, body: String(content || '').slice(match[0].length) };
+}
+
+function inferredChangeSlug(logicalPath, metadata) {
+  const explicit = metadata.change_slug || metadata.change || '';
+  if (explicit) return String(explicit);
+  const segments = String(logicalPath || '').replaceAll('\\', '/').split('/');
+  const at = segments.findIndex((segment) => /^(?:08-Mudan[cç]as|08-Changes)$/i.test(segment));
+  return at >= 0 ? String(segments[at + 1] || '').replace(/^\d{4}-\d{2}-\d{2}-/, '') : '';
+}
+
+function entityType(logicalPath, heading, block, fallback = 'document') {
+  const signal = normalizeRecallText(`${logicalPath} ${heading}`);
+  const headingSignal = normalizeRecallText(heading);
+  if (/^\s*[-*]\s+\[[ xX]\]/m.test(block) || /\b(tasks?|tarefas?)\b/.test(headingSignal)) return 'task';
+  if (/\b(decisions?|decisoes?|adr)\b/.test(signal) || /(^|\/)04-/.test(logicalPath)) return 'decision';
+  if (/\b(requirements?|requisitos?|specs?|contratos?)\b/.test(signal) || /(^|\/)07-/.test(logicalPath)) return 'requirement';
+  if (/\b(evidence|evidencia|verdict|teste|test)\b/.test(signal)) return 'evidence';
+  if (/\b(session|sessao)\b/.test(signal) || /(^|\/)02-/.test(logicalPath)) return 'session';
+  return String(fallback || 'document');
+}
+
+function authorityFor(logicalPath, metadata, kind) {
+  if (['verified', 'reported', 'candidate'].includes(metadata.authority)) return metadata.authority;
+  if (kind === 'decision' || kind === 'requirement' || kind === 'evidence'
+      || /(^|\/)(?:04-|07-)/.test(logicalPath)) return 'verified';
+  return kind === 'session' ? 'reported' : 'candidate';
+}
+
+function validityFor(metadata, block) {
+  const explicit = normalizeRecallText(metadata.validity || metadata.status || '');
+  if (/superseded|superado|deprecated|obsoleto|rejected|abandon/.test(explicit)) return 'superseded';
+  if (/closed|done|archived|active|ativo|accepted|complete/.test(explicit)) return 'active';
+  if (/\b(?:superseded|superado|obsoleto)\b/i.test(block)) return 'superseded';
+  return 'active';
+}
+
+function observedAt(metadata) {
+  const raw = metadata.observed_at || metadata.updated_at || metadata.ended_at
+    || metadata.date || metadata.created_at || '';
+  if (!raw) return new Date(0).toISOString();
+  const parsed = Date.parse(raw);
+  return Number.isFinite(parsed) ? new Date(parsed).toISOString() : new Date(0).toISOString();
+}
+
+function splitLongBlock(block, maxChars = 1200) {
+  if (block.length <= maxChars) return [block];
+  const out = [];
+  let rest = block;
+  while (rest.length > maxChars) {
+    let cut = rest.lastIndexOf(' ', maxChars);
+    if (cut < Math.floor(maxChars * 0.6)) cut = maxChars;
+    out.push(rest.slice(0, cut).trim());
+    rest = rest.slice(cut).trim();
+  }
+  if (rest) out.push(rest);
+  return out;
+}
+
+function indexableBlockParts(block) {
+  const maxIndexedChars = 4 * 1024 * 1024;
+  if (block.length <= maxIndexedChars) return splitLongBlock(block);
+  const samples = 256;
+  const sampleChars = Math.floor(maxIndexedChars / samples);
+  const stride = block.length / samples;
+  return Array.from({ length: samples }, (_, index) => {
+    const start = Math.min(block.length - sampleChars, Math.floor(index * stride));
+    return cleanText(block.slice(Math.max(0, start), Math.max(0, start) + sampleChars));
+  }).filter(Boolean);
+}
+
+export function chunkMarkdownDocument({
+  projectId = '', logicalPath = '', content = '', metadata = {}, entityType: fallbackType = 'document',
+} = {}) {
+  const parsed = parseFrontmatter(content);
+  const meta = { ...parsed.data, ...(metadata || {}) };
+  const lines = parsed.body.replace(/\r\n/g, '\n').split('\n');
+  const title = cleanText(meta.title || lines.find((line) => /^#\s+/.test(line))?.replace(/^#\s+/, '')
+    || basename(logicalPath).replace(/\.md$/i, ''));
+  let heading = title;
+  let buffer = [];
+  const blocks = [];
+  let inFence = false;
+
+  const flush = () => {
+    const block = cleanText(buffer.join('\n'));
+    if (block) indexableBlockParts(block).forEach((part) => blocks.push({ heading, content: part }));
+    buffer = [];
+  };
+
+  for (const line of lines) {
+    if (/^```/.test(line.trim())) inFence = !inFence;
+    const headingMatch = !inFence && line.match(/^#{1,6}\s+(.+?)\s*$/);
+    if (headingMatch) {
+      flush();
+      heading = cleanText(headingMatch[1]);
+      continue;
+    }
+    if (!inFence && !line.trim()) flush();
+    else buffer.push(line);
+  }
+  flush();
+
+  const common = {
+    index_version: EVIDENCE_INDEX_VERSION,
+    project_id: String(projectId || ''),
+    logical_path: String(logicalPath || '').replaceAll('\\', '/'),
+    title,
+    change_slug: inferredChangeSlug(logicalPath, meta),
+    session_id: String(meta.session_id || ''),
+    work_session_id: String(meta.work_session_id || ''),
+    observed_at: observedAt(meta),
+  };
+  return blocks.map((block, ordinal) => {
+    const kind = entityType(common.logical_path, block.heading, block.content, meta.entity_type || fallbackType);
+    return {
+      ...common,
+      chunk_id: `chunk-${hash(`${projectId}\0${common.logical_path}\0${block.heading}\0${ordinal}\0${block.content}`).slice(0, 24)}`,
+      heading: block.heading,
+      entity_type: kind,
+      authority: authorityFor(common.logical_path, meta, kind),
+      validity: validityFor(meta, block.content),
+      ordinal,
+      content: block.content,
+      content_hash: hash(block.content),
+    };
+  });
+}
+
+function walkMarkdown(root, dir = root, found = []) {
+  let entries = [];
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return found; }
+  for (const entry of entries) {
+    if (entry.name === '.brain' || entry.name === '.obsidian' || entry.name === 'node_modules') continue;
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) walkMarkdown(root, path, found);
+    else if (entry.isFile() && entry.name.endsWith('.md')) found.push(path);
+  }
+  return found;
+}
+
+function projectIdForVault(vaultBase) {
+  try {
+    return String(JSON.parse(readFileSync(join(vaultBase, '.brain', 'PROJECT.json'), 'utf8')).projectId || '');
+  } catch {
+    return '';
+  }
+}
+
+export function buildEvidenceIndex(vaultBase) {
+  const projectId = projectIdForVault(vaultBase);
+  const chunks = [];
+  for (const path of walkMarkdown(vaultBase)) {
+    let content = '';
+    try { content = readFileSync(path, 'utf8'); } catch { continue; }
+    chunks.push(...chunkMarkdownDocument({
+      projectId,
+      logicalPath: relative(vaultBase, path).replaceAll('\\', '/'),
+      content,
+    }));
+  }
+  chunks.sort((left, right) => left.logical_path.localeCompare(right.logical_path)
+    || left.ordinal - right.ordinal || left.chunk_id.localeCompare(right.chunk_id));
+  const output = chunks.map((chunk) => JSON.stringify(chunk)).join('\n') + (chunks.length ? '\n' : '');
+  writeFileSync(join(vaultBase, '.brain', EVIDENCE_INDEX_FILE), output, 'utf8');
+  return chunks;
+}
+
+export function loadEvidenceIndex(vaultBase) {
+  const path = join(vaultBase, '.brain', EVIDENCE_INDEX_FILE);
+  if (!existsSync(path)) return [];
+  try {
+    return readFileSync(path, 'utf8').split('\n').filter(Boolean).map((line) => JSON.parse(line));
+  } catch {
+    return [];
+  }
+}
+
+function occurrences(terms, text) {
+  const tokens = recallTerms(text);
+  const counts = new Map();
+  for (const token of tokens) counts.set(token, (counts.get(token) || 0) + 1);
+  return terms.reduce((sum, term) => sum + (counts.get(term) || 0), 0);
+}
+
+function excerptFor(content, query, terms, max = 360) {
+  const raw = cleanText(content);
+  const normalized = normalizeRecallText(raw);
+  const phrase = normalizeRecallText(query);
+  let at = phrase ? normalized.indexOf(phrase) : -1;
+  if (at < 0) at = terms.map((term) => normalized.indexOf(term)).filter((index) => index >= 0).sort((a, b) => a - b)[0] ?? 0;
+  const start = Math.max(0, at - Math.floor(max * 0.3));
+  const end = Math.min(raw.length, start + max);
+  return `${start > 0 ? '…' : ''}${raw.slice(start, end).trim()}${end < raw.length ? '…' : ''}`;
+}
+
+function recencyScore(observed, now) {
+  const instant = Date.parse(observed || '');
+  if (!Number.isFinite(instant)) return 0;
+  const days = Math.max(0, (now - instant) / 86_400_000);
+  return Math.max(0, 1.5 * (1 - Math.min(days, 365) / 365));
+}
+
+export function recallEvidence(rows, query, { topK = 5, now = Date.now() } = {}) {
+  const terms = [...new Set(recallTerms(query))];
+  if (!terms.length || !Array.isArray(rows) || !rows.length) return [];
+  const docs = rows.map((row) => ({
+    row,
+    contentTerms: recallTerms(row.content),
+    allTerms: new Set(recallTerms(`${row.title} ${row.heading} ${row.logical_path} ${row.content}`)),
+  }));
+  const df = new Map(terms.map((term) => [term, docs.filter((doc) => doc.allTerms.has(term)).length]));
+  const averageLength = docs.reduce((sum, doc) => sum + doc.contentTerms.length, 0) / docs.length || 1;
+  const phrase = normalizeRecallText(query);
+  const scored = docs.map(({ row, contentTerms, allTerms }) => {
+    let score = 0;
+    for (const term of terms) {
+      const frequency = occurrences([term], row.content);
+      const idf = Math.log(1 + ((docs.length - (df.get(term) || 0) + 0.5) / ((df.get(term) || 0) + 0.5)));
+      if (frequency) score += idf * ((frequency * 2.2) / (frequency + 1.2 * (0.25 + 0.75 * contentTerms.length / averageLength)));
+      if (recallTerms(row.title).includes(term)) score += idf * 3;
+      if (recallTerms(row.heading).includes(term)) score += idf * 2.5;
+      if (recallTerms(row.logical_path).includes(term)) score += idf * 1.5;
+    }
+    if (phrase && normalizeRecallText(`${row.title} ${row.heading} ${row.content}`).includes(phrase)) score += 6;
+    if (row.authority === 'verified') score += 2;
+    else if (row.authority === 'reported') score += 1;
+    if (row.validity === 'superseded') score -= 8;
+    else if (row.validity === 'active') score += 1;
+    score += recencyScore(row.observed_at, now);
+    const matchedTerms = terms.filter((term) => allTerms.has(term));
+    return {
+      ...row,
+      score: Number(score.toFixed(6)),
+      matched_terms: matchedTerms,
+      excerpt: excerptFor(row.content, query, matchedTerms),
+    };
+  }).filter((row) => row.matched_terms.length && row.score > 0)
+    .sort((left, right) => right.score - left.score
+      || String(right.observed_at).localeCompare(String(left.observed_at))
+      || left.logical_path.localeCompare(right.logical_path));
+
+  const selected = [];
+  const perSource = new Map();
+  for (const row of scored) {
+    const count = perSource.get(row.logical_path) || 0;
+    if (count >= 1 && scored.some((candidate) => !perSource.has(candidate.logical_path))) continue;
+    selected.push(row);
+    perSource.set(row.logical_path, count + 1);
+    if (selected.length >= topK) break;
+  }
+  if (selected.length < topK) {
+    for (const row of scored) {
+      if (selected.some((item) => item.chunk_id === row.chunk_id)) continue;
+      selected.push(row);
+      if (selected.length >= topK) break;
+    }
+  }
+  return selected;
+}
+
+export function renderEvidenceContext(results, { maxBytes = 3072 } = {}) {
+  const lines = ['<wk_evidence_recall>'];
+  for (const [index, item] of results.entries()) {
+    const entry = [
+      `${index + 1}. ${item.title || item.logical_path} — ${item.heading || '(sem heading)'}`,
+      `   ${item.excerpt}`,
+      `   source:${item.logical_path} authority:${item.authority} validity:${item.validity} as_of:${item.observed_at}`,
+    ];
+    const candidate = [...lines, ...entry, '</wk_evidence_recall>'].join('\n');
+    if (Buffer.byteLength(candidate, 'utf8') > maxBytes) break;
+    lines.push(...entry);
+  }
+  lines.push('</wk_evidence_recall>');
+  return lines.length === 2 ? '' : lines.join('\n');
+}
+
+export function benchmarkEvidenceRecall(rows, cases, { topK = 5, now = Date.now() } = {}) {
+  let reciprocal = 0;
+  let recalled = 0;
+  let stale = 0;
+  let evidenceCorrect = 0;
+  let handoffs = 0;
+  let handoffsFound = 0;
+  for (const item of cases) {
+    const results = recallEvidence(rows, item.query, { topK, now });
+    const rank = results.findIndex((row) => row.chunk_id === item.expected_chunk_id
+      || row.logical_path === item.expected_path);
+    if (rank >= 0) { recalled += 1; reciprocal += 1 / (rank + 1); }
+    if (results[0]?.validity === 'superseded') stale += 1;
+    if (results.every((row) => row.logical_path && row.heading && row.authority && row.observed_at)) evidenceCorrect += 1;
+    if (item.handoff) {
+      handoffs += 1;
+      if (rank >= 0) handoffsFound += 1;
+    }
+  }
+  const count = Math.max(1, cases.length);
+  return {
+    recall_at_5: recalled / count,
+    mrr: reciprocal / count,
+    stale_answer_rate: stale / count,
+    evidence_accuracy: evidenceCorrect / count,
+    handoff_success: handoffs ? handoffsFound / handoffs : 1,
+  };
+}

package/packages/vault/src/index.mjs

@@ -5,5 +5,7 @@ export * from './memory-schema.mjs';
 export * from './memory-mode.mjs';
 export * from './memory-handoff.mjs';
 export * from './memory-store.mjs';
+export * from './memory-scope.mjs';
+export * from './evidence-recall.mjs';
 export * from './validate-core.mjs';
 export * from './validate-memory.mjs';

package/packages/vault/src/memory-handoff.mjs

@@ -1,8 +1,10 @@
 import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { basename, join, relative } from 'node:path';
 
 import { sanitizeMemoryText } from './memory-schema.mjs';
+import { scopeForMemoryKey } from './memory-scope.mjs';
 
 const SHARED_HANDOFF_FIELDS = Object.freeze([
   ['objective', 'objective.current'],
@@ -43,6 +45,10 @@ export function normalizeSharedHandoff(shared) {
   const normalized = {};
   const workSessionId = sanitizeMemoryText(shared.work_session_id ?? shared.workSessionId ?? '').trim();
   if (workSessionId) normalized.work_session_id = workSessionId;
+  for (const field of ['branch', 'worktree_id', 'repository_id', 'change_slug', 'tasks_hash', 'spec_hash']) {
+    const value = sanitizeMemoryText(shared[field] ?? '').trim();
+    if (value) normalized[field] = value;
+  }
 
   for (const [field] of SHARED_HANDOFF_FIELDS) {
     if (!Object.hasOwn(shared, field)) continue;
@@ -53,7 +59,7 @@ export function normalizeSharedHandoff(shared) {
   return Object.keys(normalized).length ? normalized : null;
 }
 
-function eventId(context, memoryKey, value) {
+function eventId(context, memoryKey, value, scope = null) {
   const digest = createHash('sha256')
     .update(JSON.stringify([
       context.projectId,
@@ -61,6 +67,7 @@ function eventId(context, memoryKey, value) {
       context.activation?.id,
       context.turn?.id,
       memoryKey,
+      scope,
       canonicalValue(value),
     ]))
     .digest('hex')
@@ -68,13 +75,15 @@ function eventId(context, memoryKey, value) {
   return `mem-${digest}`;
 }
 
-function makeEvent(context, { memoryKey, value, authority, evidence }) {
+function makeEvent(context, { memoryKey, value, authority, evidence, scopeContext = {} }) {
   const cleanValue = sanitizeValue(value);
+  const scope = scopeForMemoryKey(memoryKey, { ...context, ...scopeContext });
   const event = {
     v: 1,
-    event_id: eventId(context, memoryKey, cleanValue),
+    event_id: eventId(context, memoryKey, cleanValue, scope),
     project_id: String(context.projectId || ''),
     memory_key: memoryKey,
+    scope,
     operation: 'assert',
     value: cleanValue,
     authority,
@@ -118,6 +127,26 @@ function nextActionFrom(summary) {
   return id && text ? { id, summary: text } : null;
 }
 
+function gitScope(cwd = process.cwd(), spawn = spawnSync) {
+  const run = (args) => {
+    const result = spawn('git', args, { cwd, encoding: 'utf8', windowsHide: true });
+    return result.status === 0 ? String(result.stdout || '').trim() : '';
+  };
+  try {
+    const branch = run(['branch', '--show-current']) || `detached:${run(['rev-parse', '--short=12', 'HEAD'])}`;
+    const gitDir = run(['rev-parse', '--absolute-git-dir']);
+    const remote = run(['remote', 'get-url', 'origin']) || run(['rev-parse', '--show-toplevel']);
+    if (!branch || !gitDir || !remote) return null;
+    return {
+      branch,
+      worktree_id: createHash('sha256').update(gitDir).digest('hex').slice(0, 16),
+      repository_id: createHash('sha256').update(remote).digest('hex').slice(0, 16),
+    };
+  } catch {
+    return null;
+  }
+}
+
 export function collectLifecycleEvidence(vaultBase, { changeSlug = '', summary = '', noteRel = '' } = {}) {
   const evidence = {};
   const slug = String(changeSlug || '').trim();
@@ -159,11 +188,13 @@ export function collectLifecycleEvidence(vaultBase, { changeSlug = '', summary =
   if (nextAction) evidence.nextAction = nextAction;
   const commit = String(summary || '').match(/\b[0-9a-f]{40}\b/i)?.[0];
   if (commit) {
+    const scope = gitScope();
     evidence.git = {
       commit: commit.toLowerCase(),
       pushed: !/(?:nenhum|sem)\s+push/i.test(String(summary || '')),
       verified: false,
       path: noteRel,
+      ...(scope || {}),
     };
   }
   return evidence;
@@ -184,6 +215,14 @@ export function buildSessionMemoryEvents({
   const context = {
     projectId, identity, activation, turn, observedAt,
     workSessionId: normalizedShared?.work_session_id || '',
+    canonicalSessionId: identity?.canonicalConversationId || '',
+    activation_id: activation?.id || '',
+    branch: normalizedShared?.branch || '',
+    worktreeId: normalizedShared?.worktree_id || '',
+    repositoryId: normalizedShared?.repository_id || '',
+    changeSlug: normalizedShared?.change_slug || evidence.change?.slug || '',
+    tasksHash: normalizedShared?.tasks_hash || '',
+    specHash: normalizedShared?.spec_hash || '',
   };
   const events = [];
 
@@ -195,6 +234,7 @@ export function buildSessionMemoryEvents({
         value: normalizedShared[field],
         authority: 'reported',
         evidence: [noteRel],
+        scopeContext: { changeSlug: evidence.change?.slug || normalizedShared?.change_slug },
       }));
     }
   }
@@ -214,6 +254,7 @@ export function buildSessionMemoryEvents({
       value: { status: evidence.change.status, adr: evidence.change.adr },
       authority: 'verified',
       evidence: [evidence.change.path || evidence.change.adr],
+      scopeContext: { changeSlug: evidence.change.slug },
     }));
   }
 
@@ -227,6 +268,11 @@ export function buildSessionMemoryEvents({
       },
       authority: 'verified',
       evidence: [evidence.verdict.path],
+      scopeContext: {
+        changeSlug: evidence.change?.slug || normalizedShared?.change_slug,
+        tasksHash: evidence.verdict.tasks_hash || normalizedShared?.tasks_hash,
+        specHash: evidence.verdict.spec_hash || normalizedShared?.spec_hash,
+      },
     }));
   }
 
@@ -236,6 +282,10 @@ export function buildSessionMemoryEvents({
       value: [...new Set(evidence.sensors.map(String))].sort(),
       authority: 'verified',
       evidence: evidence.sensors,
+      scopeContext: {
+        changeSlug: evidence.change?.slug || normalizedShared?.change_slug,
+        tasksHash: evidence.sensors_tasks_hash || normalizedShared?.tasks_hash,
+      },
     }));
   }
 
@@ -249,6 +299,11 @@ export function buildSessionMemoryEvents({
       },
       authority: evidence.git.verified === false ? 'reported' : 'verified',
       evidence: [evidence.git.path || evidence.git.commit],
+      scopeContext: {
+        branch: evidence.git.branch || normalizedShared?.branch,
+        worktreeId: evidence.git.worktree_id || normalizedShared?.worktree_id,
+        repositoryId: evidence.git.repository_id || normalizedShared?.repository_id,
+      },
     }));
   }
 

package/packages/vault/src/memory-schema.mjs

@@ -1,4 +1,5 @@
 import { createHash } from 'node:crypto';
+import { MEMORY_SCOPE_TYPES, normalizeMemoryScope } from './memory-scope.mjs';
 
 export const SHARED_LIMITS = Object.freeze({ lines: 48, bytes: 6144, lineChars: 320 });
 
@@ -107,6 +108,11 @@ export function validateMemoryEvent(event, { projectId } = {}) {
   if (projectId !== undefined && !eventBelongsToVault(event, projectId)) {
     errors.push(`project_id não pertence ao vault esperado (${projectId}).`);
   }
+  if (event.scope !== undefined) {
+    if (!normalizeMemoryScope(event.scope, { projectId: event.project_id || projectId || '' })) {
+      errors.push(`scope deve conter type (${MEMORY_SCOPE_TYPES.join('|')}) e id não vazio compatível com o projeto.`);
+    }
+  }
 
   if (event.candidate_decision !== undefined) {
     const decision = event.candidate_decision;
@@ -133,7 +139,7 @@ export function validateMemoryEvent(event, { projectId } = {}) {
     }
   }
 
-  for (const field of ['value', 'evidence']) sanitizedField(event, field, errors);
+  for (const field of ['value', 'evidence', 'scope']) sanitizedField(event, field, errors);
   return { ok: errors.length === 0, errors, warnings };
 }
 
@@ -161,6 +167,7 @@ function hashProjection(events) {
     operation: event.operation,
     value: sanitizeMemoryText(event.value),
     authority: event.authority,
+    scope: event.scope,
     observed_at: event.observed_at,
     evidence: Array.isArray(event.evidence) ? event.evidence.map(sanitizeMemoryText) : [],
   }));
@@ -173,7 +180,10 @@ function eventLine(event) {
     ? event.evidence.map(sanitizeMemoryText).join(', ')
     : 'none';
   const source = sanitizeMemoryText(event.source_turn_id || event.canonical_session_id || event.activation_id || 'unknown');
-  const line = `- [${sanitizeMemoryText(event.event_id)}] ${value} · authority:${sanitizeMemoryText(event.authority)} · source:${source} · as_of:${sanitizeMemoryText(event.observed_at)} · evidence:${evidence}`;
+  const scope = event.scope?.type && event.scope?.id
+    ? ` · scope:${sanitizeMemoryText(event.scope.type)}:${sanitizeMemoryText(event.scope.id)}`
+    : '';
+  const line = `- [${sanitizeMemoryText(event.event_id)}] ${value} · authority:${sanitizeMemoryText(event.authority)}${scope} · source:${source} · as_of:${sanitizeMemoryText(event.observed_at)} · evidence:${evidence}`;
   return line.length <= SHARED_LIMITS.lineChars
     ? line
     : `${line.slice(0, SHARED_LIMITS.lineChars - 1).trimEnd()}…`;

package/packages/vault/src/memory-scope.mjs

@@ -0,0 +1,119 @@
+import { createHash } from 'node:crypto';
+
+export const MEMORY_SCOPE_TYPES = Object.freeze([
+  'project',
+  'work_session',
+  'change',
+  'branch',
+  'worktree',
+]);
+
+const SCOPE_TYPES = new Set(MEMORY_SCOPE_TYPES);
+const REGISTER_PATTERNS = [
+  /^git\.local-head$/,
+  /^handoff\.latest$/,
+  /^quality\.latest-(?:sensors|verdict)$/,
+  /^change\.[A-Za-z0-9._-]+\.status$/,
+];
+
+function clean(value) {
+  return String(value ?? '').trim().replace(/[\r\n\t]+/g, ' ').slice(0, 240);
+}
+
+function digest(value) {
+  return createHash('sha256').update(clean(value)).digest('hex').slice(0, 16);
+}
+
+export function normalizeMemoryScope(scope, { projectId = '' } = {}) {
+  if (!scope || typeof scope !== 'object' || Array.isArray(scope)) return null;
+  const type = clean(scope.type);
+  const id = clean(scope.id);
+  if (!SCOPE_TYPES.has(type) || !id) return null;
+  if (type === 'project' && projectId && id !== projectId) return null;
+  return { type, id };
+}
+
+function changeSlug(memoryKey, context) {
+  const fromKey = String(memoryKey || '').match(/^change\.([A-Za-z0-9._-]+)\.status$/)?.[1];
+  return clean(fromKey || context.changeSlug || context.change_slug);
+}
+
+function workSession(context) {
+  return clean(
+    context.workSessionId || context.work_session_id
+    || context.canonicalSessionId || context.canonical_session_id
+    || context.sessionId || context.session_id,
+  );
+}
+
+/** Deterministic scope policy for operational keys. It never uses an absolute local path. */
+export function scopeForMemoryKey(memoryKey, context = {}) {
+  const key = clean(memoryKey);
+  const projectId = clean(context.projectId || context.project_id) || 'unknown-project';
+  if (key === 'handoff.latest') {
+    return { type: 'work_session', id: workSession(context) || `legacy:${projectId}` };
+  }
+  if (key === 'git.local-head') {
+    const branch = clean(context.branch || context.branchName || context.branch_name);
+    const worktree = clean(context.worktreeId || context.worktree_id);
+    const repository = clean(context.repositoryId || context.repository_id);
+    if (branch) {
+      return {
+        type: 'branch',
+        id: [repository && `repo:${repository}`, worktree && `worktree:${worktree}`, `branch:${branch}`]
+          .filter(Boolean).join('|'),
+      };
+    }
+    const lineage = workSession(context) || clean(context.activation_id) || clean(context.event_id);
+    return { type: 'branch', id: `legacy:${projectId}:${digest(lineage || key)}` };
+  }
+  if (/^quality\.latest-(?:sensors|verdict)$/.test(key)) {
+    const slug = changeSlug(key, context) || `legacy:${digest(workSession(context) || key)}`;
+    const proof = clean(context.tasksHash || context.tasks_hash || context.specHash || context.spec_hash);
+    return { type: 'change', id: proof ? `${slug}|proof:${proof}` : slug };
+  }
+  if (/^change\.[A-Za-z0-9._-]+\.status$/.test(key)) {
+    return { type: 'change', id: changeSlug(key, context) };
+  }
+  if (/^(?:decision|adr)\b/.test(key)) {
+    const slug = changeSlug(key, context);
+    return slug ? { type: 'change', id: slug } : { type: 'project', id: projectId };
+  }
+  if (/^(?:constraint|restriction)\b/.test(key)) {
+    const session = workSession(context);
+    return session ? { type: 'work_session', id: session } : { type: 'project', id: projectId };
+  }
+  return { type: 'project', id: projectId };
+}
+
+export function effectiveMemoryScope(event = {}) {
+  // Ledger rows written before scoped registers existed remain project-scoped until an
+  // explicit append-only rescope migration supersedes them. This preserves historic replay.
+  return normalizeMemoryScope(event.scope, { projectId: event.project_id })
+    || { type: 'project', id: clean(event.project_id) || 'unknown-project' };
+}
+
+export function memoryScopeKey(scope) {
+  const normalized = normalizeMemoryScope(scope);
+  return normalized ? `${normalized.type}:${normalized.id}` : 'project:unknown-project';
+}
+
+export function sameMemoryScope(left, right) {
+  return memoryScopeKey(effectiveMemoryScope(left)) === memoryScopeKey(effectiveMemoryScope(right));
+}
+
+/** Project-scoped keys retain their historic public name; narrower registers are qualified. */
+export function memoryRecordKey(event) {
+  const scope = effectiveMemoryScope(event);
+  return scope.type === 'project'
+    ? String(event.memory_key)
+    : `${event.memory_key}@${memoryScopeKey(scope)}`;
+}
+
+export function isRegisterMemoryKey(memoryKey) {
+  return REGISTER_PATTERNS.some((pattern) => pattern.test(String(memoryKey || '')));
+}
+
+export function isHumanCuratedMemoryKey(memoryKey) {
+  return /^(?:decision|adr|constraint|restriction|block|blocker)\b/.test(String(memoryKey || ''));
+}