wendkeep 0.72.1 → 0.74.0

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 || ''));
+}

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

@@ -14,6 +14,12 @@ import {
   sanitizeMemoryText,
   validateMemoryEvent,
 } from './memory-schema.mjs';
+import {
+  effectiveMemoryScope,
+  isRegisterMemoryKey,
+  memoryRecordKey,
+  sameMemoryScope,
+} from './memory-scope.mjs';
 import {
   assertVaultPathSafe, assertVaultPathsSafe, mkdirVaultPath, unlinkVaultFile,
   VAULT_LOCK_BUSY, withVaultPathLock, writeVaultFileAtomic,
@@ -376,6 +382,7 @@ function sameCompleteCausalLineage(left, right) {
 }
 
 function comparable(left, right) {
+  if (left?.project_id !== right?.project_id || !sameMemoryScope(left, right)) return false;
   if (sameCausalActivation(left, right)) return true;
   const leftSupersedes = left.supersedes_event_id || left.supersedes;
   const rightSupersedes = right.supersedes_event_id || right.supersedes;
@@ -387,7 +394,7 @@ function comparable(left, right) {
 function conflictGroupKey(event) {
   if (event.operation !== 'replace') return null;
   if (!Number.isInteger(event.base_revision) || typeof event.base_value_hash !== 'string') return null;
-  return `${event.memory_key}\u0000${event.base_revision}\u0000${event.base_value_hash}`;
+  return `${memoryRecordKey(event)}\u0000${event.base_revision}\u0000${event.base_value_hash}`;
 }
 
 function candidateId(reason, memoryKey, eventIds) {
@@ -421,6 +428,7 @@ function blockedByCoreCandidate(event, coreValue) {
     reason: 'blocked_by_core',
     status: 'blocked_by_core',
     memory_key: event.memory_key,
+    ...(event.scope ? { scope: effectiveMemoryScope(event), record_key: memoryRecordKey(event) } : {}),
     event_ids: [event.event_id],
     proposed_value: event.value,
     core_value: coreValue,
@@ -442,6 +450,10 @@ function conflictCandidate(memoryKey, events, currentEvent = null) {
     candidate_id: candidateId('conflict', memoryKey, eventIds),
     reason: 'conflict',
     memory_key: memoryKey,
+    ...((ordered[0] || currentEvent)?.scope ? {
+      scope: effectiveMemoryScope(ordered[0] || currentEvent || {}),
+      record_key: memoryRecordKey(ordered[0] || currentEvent || { memory_key: memoryKey }),
+    } : {}),
     event_ids: eventIds,
     values: eventIds.map((id) => byId.get(id).value),
     base_revision: ordered[0]?.base_revision ?? currentEvent?.revision ?? 0,
@@ -459,6 +471,7 @@ function conflictReviewEvent(candidate, candidateCount = 1) {
     event_id: `mem-review-${candidate.candidate_id}`,
     project_id: source.project_id || '',
     memory_key: candidate.memory_key,
+    scope: candidate.scope,
     operation: 'assert',
     value: `[revisão pendente: ${memoryKey}; candidates: ${candidateCount}; events: ${eventCount}]`,
     authority: 'candidate',
@@ -508,7 +521,9 @@ function isCausallyOlder(event, current) {
   if (sameCausalActivation(event, current)) {
     return Number(event.turn_sequence) < Number(current.turn_sequence);
   }
-  if (Number.isInteger(event.activation_epoch) && Number.isInteger(current.activation_epoch)
+  if (event.canonical_session_id && event.canonical_session_id === current.canonical_session_id
+      && sameMemoryScope(event, current)
+      && Number.isInteger(event.activation_epoch) && Number.isInteger(current.activation_epoch)
       && event.activation_epoch !== current.activation_epoch) {
     return event.activation_epoch < current.activation_epoch;
   }
@@ -518,6 +533,30 @@ function isCausallyOlder(event, current) {
     && eventEffective < currentEffective;
 }
 
+const AUTHORITY_RANK = Object.freeze({ candidate: 0, reported: 1, verified: 2 });
+
+function sameRegisterLineage(left, right) {
+  return Boolean(left?.canonical_session_id)
+    && left.canonical_session_id === right?.canonical_session_id
+    && left.project_id === right?.project_id
+    && sameMemoryScope(left, right);
+}
+
+/** Positive means `incoming` is a safe successor; null means human comparison is required. */
+function registerPrecedence(incoming, current) {
+  if (!incoming?.scope || !current?.scope
+      || !isRegisterMemoryKey(incoming?.memory_key) || !sameRegisterLineage(incoming, current)) return null;
+  const epoch = Number(incoming.activation_epoch ?? -1) - Number(current.activation_epoch ?? -1);
+  if (epoch) return epoch;
+  const turn = Number(incoming.turn_sequence ?? -1) - Number(current.turn_sequence ?? -1);
+  if (turn) return turn;
+  const authority = (AUTHORITY_RANK[incoming.authority] ?? -1) - (AUTHORITY_RANK[current.authority] ?? -1);
+  if (authority) return authority;
+  const observed = String(incoming.observed_at || '').localeCompare(String(current.observed_at || ''));
+  if (observed) return observed;
+  return String(incoming.event_id || '').localeCompare(String(current.event_id || ''));
+}
+
 /**
  * Pure deterministic reducer. It pre-detects incomparable scalar siblings so replay order
  * never turns one concurrent writer into an accidental winner.
@@ -537,7 +576,21 @@ export function reduceMemoryEvents(inputEvents = [], {
     }
     if (!existing) unique.set(event.event_id, event);
   }
-  const events = [...unique.values()].sort(eventOrder);
+  const rescopeTargets = new Set(
+    [...unique.values()].flatMap((item) => [
+      item.rescopes_event_id,
+      ...(Array.isArray(item.rescopes_event_ids) ? item.rescopes_event_ids : []),
+    ]).filter(Boolean),
+  );
+  const projectIds = new Set([...unique.values()].map((item) => item.project_id).filter(Boolean));
+  if (projectIds.size > 1) {
+    const error = new TypeError('Memory reducer cannot compare events from different projects.');
+    error.code = 'MEMORY_PROJECT_MIXED';
+    throw error;
+  }
+  const events = [...unique.values()]
+    .filter((item) => !rescopeTargets.has(item.event_id))
+    .sort(eventOrder);
   const candidateDecisions = new Map();
   for (const item of events) {
     const decision = item.candidate_decision;
@@ -604,7 +657,8 @@ export function reduceMemoryEvents(inputEvents = [], {
       continue;
     }
 
-    const current = records.get(item.memory_key);
+    const recordKey = memoryRecordKey(item);
+    const current = records.get(recordKey);
     const currentSource = current?.source;
     if (isCausallyOlder(item, currentSource)) {
       superseded.push({ event_id: item.event_id, by_event_id: currentSource.event_id });
@@ -613,10 +667,12 @@ export function reduceMemoryEvents(inputEvents = [], {
 
     if (item.operation === 'assert') {
       if (current && hashMemoryValue(current.value) !== hashMemoryValue(item.value)) {
-        if (sameCausalActivation(item, currentSource)
-            && Number(item.turn_sequence) > Number(currentSource.turn_sequence)) {
-          records.set(item.memory_key, { value: item.value, revision: current.revision + 1, source: item });
-          tombstones.delete(item.memory_key);
+        const precedence = registerPrecedence(item, currentSource);
+        if ((sameCausalActivation(item, currentSource)
+              && Number(item.turn_sequence) > Number(currentSource.turn_sequence))
+            || precedence > 0) {
+          records.set(recordKey, { value: item.value, revision: current.revision + 1, source: item });
+          tombstones.delete(recordKey);
           superseded.push({ event_id: currentSource.event_id, by_event_id: item.event_id });
           revision += 1;
           appliedEventIds.push(item.event_id);
@@ -628,8 +684,8 @@ export function reduceMemoryEvents(inputEvents = [], {
         continue;
       }
       if (!current) {
-        records.set(item.memory_key, { value: item.value, revision: 1, source: item });
-        tombstones.delete(item.memory_key);
+        records.set(recordKey, { value: item.value, revision: 1, source: item });
+        tombstones.delete(recordKey);
         revision += 1;
       }
       appliedEventIds.push(item.event_id);
@@ -642,8 +698,8 @@ export function reduceMemoryEvents(inputEvents = [], {
       const byHash = new Map(oldValues.map((value) => [hashMemoryValue(value), value]));
       additions.forEach((value) => byHash.set(hashMemoryValue(value), value));
       const value = [...byHash.entries()].sort(([left], [right]) => left.localeCompare(right)).map(([, entry]) => entry);
-      records.set(item.memory_key, { value, revision: (current?.revision || 0) + 1, source: item });
-      tombstones.delete(item.memory_key);
+      records.set(recordKey, { value, revision: (current?.revision || 0) + 1, source: item });
+      tombstones.delete(recordKey);
       revision += 1;
       appliedEventIds.push(item.event_id);
       continue;
@@ -664,13 +720,13 @@ export function reduceMemoryEvents(inputEvents = [], {
       if (item.value !== null && item.value !== undefined && Array.isArray(current.value)) {
         const removalHash = hashMemoryValue(item.value);
         const value = current.value.filter((entry) => hashMemoryValue(entry) !== removalHash);
-        records.set(item.memory_key, { value, revision: current.revision + 1, source: item });
-        tombstones.set(`${item.memory_key}:${removalHash}`, {
+        records.set(recordKey, { value, revision: current.revision + 1, source: item });
+        tombstones.set(`${recordKey}:${removalHash}`, {
           event_id: item.event_id, removed_event_id: current.source.event_id, value_hash: removalHash,
         });
       } else {
-        records.delete(item.memory_key);
-        tombstones.set(item.memory_key, {
+        records.delete(recordKey);
+        tombstones.set(recordKey, {
           event_id: item.event_id,
           removed_event_id: current.source.event_id,
           value_hash: hashMemoryValue(current.value),
@@ -691,8 +747,8 @@ export function reduceMemoryEvents(inputEvents = [], {
       candidates.push(conflictCandidate(item.memory_key, current ? [currentEventFromRecord(current), item] : [item]));
       continue;
     }
-    records.set(item.memory_key, { value: item.value, revision: current.revision + 1, source: item });
-    tombstones.delete(item.memory_key);
+    records.set(recordKey, { value: item.value, revision: current.revision + 1, source: item });
+    tombstones.delete(recordKey);
     const explicitlySupersededIds = new Set(
       Array.isArray(item.supersedes)
         ? item.supersedes
@@ -732,16 +788,16 @@ export function reduceMemoryEvents(inputEvents = [], {
       advanced = false;
       for (const pending of deferredAsserts) {
         if (resolvedCandidateIds.has(pending.candidate.candidate_id)) continue;
-        const current = records.get(pending.event.memory_key);
+        const current = records.get(memoryRecordKey(pending.event));
         const currentSource = current?.source;
         if (!sameCompleteCausalLineage(pending.event, currentSource)) continue;
         if (pending.event.turn_sequence > currentSource.turn_sequence) {
-          records.set(pending.event.memory_key, {
+          records.set(memoryRecordKey(pending.event), {
             value: pending.event.value,
             revision: current.revision + 1,
             source: pending.event,
           });
-          tombstones.delete(pending.event.memory_key);
+          tombstones.delete(memoryRecordKey(pending.event));
           superseded.push({ event_id: currentSource.event_id, by_event_id: pending.event.event_id });
           revision += 1;
           appliedEventIds.push(pending.event.event_id);
@@ -762,7 +818,7 @@ export function reduceMemoryEvents(inputEvents = [], {
     .map((candidate) => {
       const pending = pendingByCandidateId.get(candidate.candidate_id);
       if (!pending) return candidate;
-      const finalSource = currentEventFromRecord(records.get(candidate.memory_key));
+      const finalSource = currentEventFromRecord(records.get(candidate.record_key || candidate.memory_key));
       const previousSource = candidate.events?.find(
         (event) => event.event_id !== pending.event.event_id,
       );
@@ -791,10 +847,16 @@ export function reduceMemoryEvents(inputEvents = [], {
   superseded.sort((left, right) => left.event_id.localeCompare(right.event_id));
   const eventCursor = events.at(-1)?.event_id || 'none';
   const stateHash = hashMemoryValue({ state, tombstones: tombstoneObject });
+  const ambiguousRecordKeys = new Set(
+    unresolvedCandidates.map((candidate) => candidate.record_key || candidate.memory_key),
+  );
   const activeEvents = [
-    ...Object.entries(recordObject).map(([memoryKey, record]) => ({
+    ...Object.entries(recordObject)
+      .filter(([recordKey]) => !ambiguousRecordKeys.has(recordKey))
+      .map(([recordKey, record]) => ({
       ...record.source,
-      memory_key: memoryKey,
+      memory_key: record.source.memory_key,
+      projection_key: recordKey,
       operation: 'assert',
       value: record.value,
     })),

package/schema/observer/004-evidence-recall.sql

@@ -0,0 +1,25 @@
+CREATE TABLE IF NOT EXISTS document_chunks (
+  chunk_id TEXT PRIMARY KEY,
+  project_id TEXT NOT NULL REFERENCES projects(project_id) ON DELETE CASCADE,
+  logical_path TEXT NOT NULL,
+  title TEXT NOT NULL DEFAULT '',
+  heading TEXT NOT NULL DEFAULT '',
+  entity_type TEXT NOT NULL DEFAULT 'document',
+  change_slug TEXT NOT NULL DEFAULT '',
+  session_id TEXT NOT NULL DEFAULT '',
+  work_session_id TEXT NOT NULL DEFAULT '',
+  authority TEXT NOT NULL DEFAULT 'candidate',
+  observed_at TEXT NOT NULL,
+  validity TEXT NOT NULL DEFAULT 'active',
+  content_hash TEXT NOT NULL,
+  ordinal INTEGER NOT NULL DEFAULT 0,
+  content TEXT NOT NULL,
+  FOREIGN KEY(project_id, logical_path) REFERENCES documents(project_id, logical_path) ON DELETE CASCADE,
+  UNIQUE(project_id, logical_path, ordinal)
+);
+
+CREATE INDEX IF NOT EXISTS idx_document_chunks_project_path
+  ON document_chunks(project_id, logical_path, ordinal);
+
+CREATE INDEX IF NOT EXISTS idx_document_chunks_project_type
+  ON document_chunks(project_id, entity_type, validity, observed_at);

package/src/change.mjs

@@ -16,6 +16,7 @@ import {
   relinkChanges,
   backfillArtifactLinks,
   scaffoldPlaceholders,
+  isGuideCompactChange,
 } from '../hooks/change-core.mjs';
 import { evaluateGate, requiredSensors } from '../hooks/sensors-core.mjs';
 import { buildEffectiveRequirementPackage, evaluateVerdict, formatOrphanReqs, tasksHashOf, parseSpecsList, parseDelta, parseRequirements, applyDelta, validateSpecImpact } from '../hooks/spec-core.mjs';
@@ -61,7 +62,9 @@ export function runChange(argv) {
     // G2: link the active session into the proposta's source: (graph edge proposta->sessão).
     let sessionRel = '';
     try { sessionRel = readControl(vaultBase).session_file || ''; } catch { /* sem control */ }
-    const r = newChange(vaultBase, slug, { dateStr: today(), simple: rest.includes('--simple'), sessionRel });
+    const r = newChange(vaultBase, slug, {
+      dateStr: today(), simple: rest.includes('--simple'), guide: rest.includes('--guide'), sessionRel,
+    });
     process.stdout.write(`change ${r.created ? 'created' : 'exists'}: ${r.rel} (active)\n`);
     process.exit(0);
   }
@@ -97,7 +100,7 @@ export function runChange(argv) {
     let sessionRel = '';
     try { sessionRel = readControl(vaultBase).session_file || ''; } catch { /* no control */ }
     const r = continueChange(vaultBase, archivedSlug, newSlug, {
-      dateStr: today(), simple: rest.includes('--simple'), sessionRel,
+      dateStr: today(), simple: rest.includes('--simple'), guide: rest.includes('--guide'), sessionRel,
     });
     if (!r.ok) { process.stderr.write(`wendkeep change continue: ${r.error}\n`); process.exit(2); }
     process.stdout.write(`change created: ${r.rel} (continues ${r.archived}; active)\n`);
@@ -287,13 +290,16 @@ export function runChange(argv) {
     try { tasks = parseTasks(readFileSync(join(vaultBase, getLocale(vaultBase).folders.changes, slug, 'tarefas.md'), 'utf8')); } catch { /* sem tarefas */ }
     const forced = rest.includes('--force') && tasks.some((t) => !t.done);
     const trivial = !tasks.some((t) => t.req) && !tasks.some((t) => t.sensor);
-    if (trivial) process.stderr.write('aviso: change trivial (sem [req:]/[sensor:]) — ADR marcado trivial: true\n');
+    const compactGuide = isGuideCompactChange(join(vaultBase, getLocale(vaultBase).folders.changes, slug));
+    if (trivial) process.stderr.write(compactGuide
+      ? 'aviso: GUIDE compacta sem [req:]/[sensor:] — resultado permanece auditável no archive, sem ADR automático\n'
+      : 'aviso: change trivial (sem [req:]/[sensor:]) — ADR marcado trivial: true\n');
     const r = archiveChange(vaultBase, slug, { dateStr: today(), adrNum: getNextAdrNumber(vaultBase), gate, adrFlags: { forced, trivial } });
     if (!r.ok) {
       process.stderr.write(`change archive BLOCKED (gate): ${r.failing.join('; ')}\n`);
       process.exit(1);
     }
-    process.stdout.write(`archived: ${r.archivedRel}; ADR: ${r.adrRel}\n`);
+    process.stdout.write(`archived: ${r.archivedRel}${r.adrRel ? `; ADR: ${r.adrRel}` : '; GUIDE compacta: sem ADR'}\n`);
     if (r.promoted && r.promoted.length) process.stdout.write(`specs promovidas: ${r.promoted.join(', ')}\n`);
     if (r.specWarnings && r.specWarnings.length) for (const w of r.specWarnings) process.stderr.write(`  aviso spec: ${w}\n`);
     process.exit(0);