wendkeep 0.66.0 → 0.66.3

package/hooks/brain-reindex.mjs

@@ -1,13 +1,13 @@
-// .agent/hooks/brain-reindex.mjs
-// Backfill manual: reconstrói .brain/index.jsonl + .brain/DIGEST.md varrendo todo 02-Sessões.
-// Uso: node .agent/hooks/brain-reindex.mjs [caminho-do-vault]
-import { pathToFileURL } from 'node:url';
-import { getVaultBase } from './obsidian-common.mjs';
-import { buildBrainDigest, buildBrainIndex, brainDir } from './brain-core.mjs';
-
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
-  const vaultBase = getVaultBase({ obsidian_vault_path: process.argv[2] });
-  const rows = buildBrainIndex(vaultBase);
-  const digest = buildBrainDigest(vaultBase, rows);
-  process.stdout.write(`[brain] index: ${rows.length} sessões; digest: ${digest.length} linhas → ${brainDir(vaultBase)}\n`);
-}
+// .agent/hooks/brain-reindex.mjs
+// Backfill manual: reconstrói .brain/index.jsonl + .brain/DIGEST.md varrendo todo 02-Sessões.
+// Uso: node .agent/hooks/brain-reindex.mjs [caminho-do-vault]
+import { pathToFileURL } from 'node:url';
+import { getVaultBase } from './obsidian-common.mjs';
+import { buildBrainDigest, buildBrainIndex, brainDir } from './brain-core.mjs';
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const vaultBase = getVaultBase({ obsidian_vault_path: process.argv[2] });
+  const rows = buildBrainIndex(vaultBase);
+  const digest = buildBrainDigest(vaultBase, rows);
+  process.stdout.write(`[brain] index: ${rows.length} sessões; digest: ${digest.length} linhas → ${brainDir(vaultBase)}\n`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.66.0",
+  "version": "0.66.3",
   "description": "Vault-first persistent memory for AI coding agents, with an optional profile-aware governance runtime: OFF, FLOW, GUIDE, GOVERN, or ASSURE. Local-first and agent-agnostic (Claude Code, Codex, Cursor…).",
   "type": "module",
   "workspaces": [

package/packages/cli/src/index.mjs

@@ -101,7 +101,7 @@ Usage:
   wendkeep lesson add "t" "l"   Record a project-local lesson (injected at SessionStart).
   wendkeep memory <sub>          Shared memory v2: status | migrate [--apply] | repair |
                            reconcile <session> --by-session <session> --reason <text> [--apply] |
-                           promote <candidate> | reject <candidate>. --vault P.
+                           promote <candidate> [--event <event-id>] | reject <candidate>. --vault P.
                            Reconcile is dry-run by default; the original attempt remains audited.
   wendkeep validate-memory [path]  Validate .brain/CORE.md against the compaction
                            protocol (cap 25, 3 sections, no secrets/PII).

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

@@ -108,6 +108,31 @@ export function validateMemoryEvent(event, { projectId } = {}) {
     errors.push(`project_id não pertence ao vault esperado (${projectId}).`);
   }
 
+  if (event.candidate_decision !== undefined) {
+    const decision = event.candidate_decision;
+    if (!decision || typeof decision !== 'object' || Array.isArray(decision)) {
+      errors.push('candidate_decision deve ser objeto.');
+    } else {
+      if (typeof decision.candidate_id !== 'string' || !decision.candidate_id) {
+        errors.push('candidate_decision.candidate_id deve ser string não vazia.');
+      }
+      if (!['promote', 'reject'].includes(decision.action)) {
+        errors.push('candidate_decision.action deve ser promote ou reject.');
+      }
+      if (!Array.isArray(decision.event_ids)
+          || decision.event_ids.some((item) => typeof item !== 'string' || !item)) {
+        errors.push('candidate_decision.event_ids deve ser array de strings não vazias.');
+      }
+      if (decision.action === 'promote' && decision.selected_event_id !== undefined
+          && (typeof decision.selected_event_id !== 'string' || !decision.selected_event_id)) {
+        errors.push('candidate_decision.selected_event_id deve ser string não vazia.');
+      }
+      if (decision.action === 'reject' && decision.selected_event_id !== undefined) {
+        errors.push('candidate_decision.selected_event_id não é permitido em reject.');
+      }
+    }
+  }
+
   for (const field of ['value', 'evidence']) sanitizedField(event, field, errors);
   return { ok: errors.length === 0, errors, warnings };
 }

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

@@ -344,6 +344,22 @@ function sameCausalActivation(left, right) {
     && left.activation_id === right?.activation_id;
 }
 
+function hasCompleteCausalIdentity(event) {
+  return Boolean(event?.canonical_session_id)
+    && Boolean(event?.activation_id)
+    && Boolean(event?.source_turn_id)
+    && Number.isInteger(event?.activation_epoch)
+    && Number.isInteger(event?.turn_sequence);
+}
+
+function sameCompleteCausalLineage(left, right) {
+  return hasCompleteCausalIdentity(left)
+    && hasCompleteCausalIdentity(right)
+    && left.canonical_session_id === right.canonical_session_id
+    && left.activation_id === right.activation_id
+    && left.activation_epoch === right.activation_epoch;
+}
+
 function comparable(left, right) {
   if (sameCausalActivation(left, right)) return true;
   const leftSupersedes = left.supersedes_event_id || left.supersedes;
@@ -447,7 +463,9 @@ function isCausallyOlder(event, current) {
  * Pure deterministic reducer. It pre-detects incomparable scalar siblings so replay order
  * never turns one concurrent writer into an accidental winner.
  */
-export function reduceMemoryEvents(inputEvents = [], { coreInvariants = new Map() } = {}) {
+export function reduceMemoryEvents(inputEvents = [], {
+  coreInvariants = new Map(), resolveDeferredAsserts = true,
+} = {}) {
   const protectedValues = coreInvariants instanceof Map
     ? coreInvariants
     : new Map(Object.entries(coreInvariants || {}));
@@ -461,6 +479,19 @@ export function reduceMemoryEvents(inputEvents = [], { coreInvariants = new Map(
     if (!existing) unique.set(event.event_id, event);
   }
   const events = [...unique.values()].sort(eventOrder);
+  const candidateDecisions = new Map();
+  for (const item of events) {
+    const decision = item.candidate_decision;
+    if (!decision) continue;
+    const existing = candidateDecisions.get(decision.candidate_id);
+    if (existing && canonicalMemoryJson(existing.decision) !== canonicalMemoryJson(decision)) {
+      throw new MemoryEventCollision(
+        decision.candidate_id,
+        `Ledger contains incompatible decisions for candidate ${decision.candidate_id}`,
+      );
+    }
+    if (!existing) candidateDecisions.set(decision.candidate_id, { decision, event: item });
+  }
 
   const peerGroups = new Map();
   for (const item of events) {
@@ -482,12 +513,19 @@ export function reduceMemoryEvents(inputEvents = [], { coreInvariants = new Map(
   const records = new Map();
   const tombstones = new Map();
   const candidates = [];
+  const pendingAssertConflicts = [];
+  const resolvedCandidateIds = new Set();
   const emittedGroups = new Set();
   const appliedEventIds = [];
   const superseded = [];
   let revision = 0;
 
   for (const item of events) {
+    if (item.candidate_decision && item.candidate_decision.action === 'reject') {
+      appliedEventIds.push(item.event_id);
+      continue;
+    }
+
     if (protectedValues.has(item.memory_key)) {
       const coreValue = protectedValues.get(item.memory_key);
       const agreesWithCore = item.operation === 'assert'
@@ -525,7 +563,9 @@ export function reduceMemoryEvents(inputEvents = [], { coreInvariants = new Map(
           appliedEventIds.push(item.event_id);
           continue;
         }
-        candidates.push(conflictCandidate(item.memory_key, [currentEventFromRecord(current), item]));
+        const candidate = conflictCandidate(item.memory_key, [currentEventFromRecord(current), item]);
+        candidates.push(candidate);
+        pendingAssertConflicts.push({ candidate, event: item });
         continue;
       }
       if (!current) {
@@ -598,13 +638,56 @@ export function reduceMemoryEvents(inputEvents = [], { coreInvariants = new Map(
     appliedEventIds.push(item.event_id);
   }
 
+  if (resolveDeferredAsserts) {
+    // A physically late assert can sort before a corrective promotion because effective time
+    // precedes CLI decision time. Revisit only scalar assert conflicts left without an explicit
+    // decision, against the final complete causal source; the ledger and global ordering stay put.
+    const deferredAsserts = pendingAssertConflicts
+      .filter((pending) => !candidateDecisions.has(pending.candidate.candidate_id))
+      .sort((left, right) => String(left.event.memory_key).localeCompare(String(right.event.memory_key))
+        || String(left.event.canonical_session_id || '').localeCompare(String(right.event.canonical_session_id || ''))
+        || String(left.event.activation_id || '').localeCompare(String(right.event.activation_id || ''))
+        || Number(left.event.activation_epoch ?? -1) - Number(right.event.activation_epoch ?? -1)
+        || Number(left.event.turn_sequence ?? -1) - Number(right.event.turn_sequence ?? -1)
+        || eventOrder(left.event, right.event));
+    let advanced = true;
+    while (advanced) {
+      advanced = false;
+      for (const pending of deferredAsserts) {
+        if (resolvedCandidateIds.has(pending.candidate.candidate_id)) continue;
+        const current = records.get(pending.event.memory_key);
+        const currentSource = current?.source;
+        if (!sameCompleteCausalLineage(pending.event, currentSource)) continue;
+        if (pending.event.turn_sequence > currentSource.turn_sequence) {
+          records.set(pending.event.memory_key, {
+            value: pending.event.value,
+            revision: current.revision + 1,
+            source: pending.event,
+          });
+          tombstones.delete(pending.event.memory_key);
+          superseded.push({ event_id: currentSource.event_id, by_event_id: pending.event.event_id });
+          revision += 1;
+          appliedEventIds.push(pending.event.event_id);
+          resolvedCandidateIds.add(pending.candidate.candidate_id);
+          advanced = true;
+        } else if (pending.event.turn_sequence < currentSource.turn_sequence) {
+          superseded.push({ event_id: pending.event.event_id, by_event_id: currentSource.event_id });
+          resolvedCandidateIds.add(pending.candidate.candidate_id);
+        }
+      }
+    }
+  }
+
   const stateEntries = [...records].map(([key, record]) => [key, record.value]);
   const recordEntries = [...records].map(([key, record]) => [key, record]);
   const tombstoneEntries = [...tombstones];
   const state = sortedObject(stateEntries);
   const recordObject = sortedObject(recordEntries);
   const tombstoneObject = sortedObject(tombstoneEntries);
-  candidates.sort((left, right) => left.candidate_id.localeCompare(right.candidate_id));
+  const unresolvedCandidates = candidates
+    .filter((item) => !candidateDecisions.has(item.candidate_id)
+      && !resolvedCandidateIds.has(item.candidate_id));
+  unresolvedCandidates.sort((left, right) => left.candidate_id.localeCompare(right.candidate_id));
   superseded.sort((left, right) => left.event_id.localeCompare(right.event_id));
   const activeEvents = Object.entries(recordObject).map(([memoryKey, record]) => ({
     ...record.source,
@@ -618,7 +701,7 @@ export function reduceMemoryEvents(inputEvents = [], { coreInvariants = new Map(
   return {
     state,
     records: recordObject,
-    candidates,
+    candidates: unresolvedCandidates,
     tombstones: tombstoneObject,
     superseded,
     appliedEventIds,
@@ -635,8 +718,12 @@ export function reduceMemoryEvents(inputEvents = [], { coreInvariants = new Map(
  * `eventCursor` is the reducer's deterministic causal cursor; `ledgerCursor` is the
  * physical prefix boundary used by durable checkpoints.
  */
-export function deriveMemoryProjection(vaultBase, inputEvents = []) {
-  const reduced = reduceMemoryEvents(inputEvents, { coreInvariants: readCoreInvariants(vaultBase) });
+export function deriveMemoryProjection(vaultBase, inputEvents = [], {
+  resolveDeferredAsserts = true,
+} = {}) {
+  const reduced = reduceMemoryEvents(inputEvents, {
+    coreInvariants: readCoreInvariants(vaultBase), resolveDeferredAsserts,
+  });
   const ledgerCursor = inputEvents.at(-1)?.event_id || 'none';
   const checkpoint = {
     revision: reduced.revision,

package/src/memory.mjs

@@ -237,37 +237,272 @@ function readCandidates(vault) {
     .split('\n').filter(Boolean).map((line) => JSON.parse(line));
 }
 
-export function decideMemoryCandidate(vault, { action, candidateId, value } = {}) {
+function priorCandidateDecision(vault, candidateId) {
+  return readMemoryLedger(vault).events.find(
+    (event) => event.candidate_decision?.candidate_id === candidateId,
+  ) || null;
+}
+
+function candidateEvent(candidate, eventId) {
+  const events = Array.isArray(candidate.events) ? candidate.events : [];
+  if (candidate.reason === 'conflict' && !eventId) {
+    throw new Error('Candidate de conflito exige eventId (--event na CLI).');
+  }
+  if (!eventId) return events.length === 1 ? events[0] : null;
+  const selected = events.find((event) => event.event_id === eventId);
+  if (!selected) throw new Error(`event_id ${eventId} não pertence ao candidate ${candidate.candidate_id}.`);
+  return selected;
+}
+
+function assertCompatibleDecision(prior, { action, eventId }) {
+  const decision = prior.candidate_decision;
+  const sameSelection = action !== 'promote'
+    || (decision.selected_event_id || null) === (eventId || null);
+  if (decision.action !== action || !sameSelection) {
+    throw new Error(`Candidate ${decision.candidate_id} já possui decisão incompatível (${decision.action}).`);
+  }
+}
+
+function promotedMemoryValue(value) {
+  return typeof value === 'string' ? sanitizeMemoryText(value) : cloneJson(value);
+}
+
+function eventSupersedes(event) {
+  if (Array.isArray(event?.supersedes)) return event.supersedes;
+  return event?.supersedes_event_id ? [event.supersedes_event_id] : [];
+}
+
+function hasCompleteCausalIdentity(event) {
+  return Boolean(event?.canonical_session_id && event?.activation_id && event?.source_turn_id)
+    && Number.isInteger(event.activation_epoch)
+    && Number.isInteger(event.turn_sequence);
+}
+
+function sameCausalLineage(left, right) {
+  return hasCompleteCausalIdentity(left) && hasCompleteCausalIdentity(right)
+    && left.canonical_session_id === right.canonical_session_id
+    && left.activation_id === right.activation_id
+    && left.activation_epoch === right.activation_epoch;
+}
+
+function promotedSupersedes(vault, candidate, selected) {
+  const memberIds = new Set(Array.isArray(candidate.event_ids) ? candidate.event_ids : []);
+  const ledger = readMemoryLedger(vault);
+  if (ledger.status !== 'ok') throw new Error('Ledger de memória inválido durante a promoção.');
+  const current = deriveMemoryProjection(vault, ledger.events)
+    .records?.[candidate.memory_key]?.source;
+  if (!current?.event_id || memberIds.has(current.event_id)) return [...memberIds].sort();
+
+  const currentSelectedId = current.candidate_decision?.selected_event_id;
+  const currentSelected = currentSelectedId
+    ? ledger.events.find((event) => event.event_id === currentSelectedId)
+    : null;
+  const selectedLedger = ledger.events.find((event) => event.event_id === selected.event_id);
+  const currentAncestors = eventSupersedes(current);
+  const decisionMembers = Array.isArray(current.candidate_decision?.event_ids)
+    ? current.candidate_decision.event_ids
+    : [];
+  const canonicalAncestors = [...new Set(currentAncestors)].sort();
+  const canonicalDecisionMembers = [...new Set(decisionMembers)].sort();
+  const currentObserved = String(current.effective_at || current.observed_at || '');
+  const selectedObserved = String(selectedLedger?.effective_at || selectedLedger?.observed_at || '');
+  const currentPhysicalIndex = ledger.events.findIndex((event) => event.event_id === current.event_id);
+  const selectedPhysicalIndex = ledger.events.findIndex((event) => event.event_id === selected.event_id);
+  const bridgeChecks = {
+    legacyShape: current.operation === 'replace' && current.authority === 'verified'
+      && !current.canonical_session_id && !current.source_turn_id,
+    promotion: current.candidate_decision?.action === 'promote',
+    selectedPresent: Boolean(currentSelected),
+    selectedPersisted: Boolean(selectedLedger),
+    exactDecisionMembers: canonicalAncestors.length === currentAncestors.length
+      && canonicalDecisionMembers.length === decisionMembers.length
+      && canonicalAncestors.length === canonicalDecisionMembers.length
+      && canonicalAncestors.every((eventId, index) => eventId === canonicalDecisionMembers[index]),
+    selectedSuperseded: currentAncestors.includes(currentSelectedId)
+      && decisionMembers.includes(currentSelectedId),
+    candidateAncestor: currentAncestors.some((eventId) => memberIds.has(eventId)),
+    sameLineage: sameCausalLineage(currentSelected, selectedLedger),
+    laterTurn: selectedLedger?.turn_sequence > currentSelected?.turn_sequence,
+    appendedAfterCurrent: selectedPhysicalIndex > currentPhysicalIndex && currentPhysicalIndex >= 0,
+    observedBeforeCurrent: selectedObserved < currentObserved,
+  };
+  const bridgesObservedOrder = Object.values(bridgeChecks).every(Boolean);
+  if (!bridgesObservedOrder) {
+    throw new Error(
+      `Candidate ${candidate.candidate_id} não corresponde mais à projeção causal atual; `
+      + 'recarregue os candidates antes de promover.',
+    );
+  }
+  memberIds.add(current.event_id);
+  return [...memberIds].sort();
+}
+
+function matchesPromotedAttempt(attempt, selected) {
+  if (attempt?.memory_mode !== 'v2' || attempt.state !== 'projected'
+      || !Array.isArray(attempt.event_ids) || !attempt.event_ids.includes(selected.event_id)) return false;
+  if (attempt.activation_id && selected.activation_id
+      && attempt.activation_id !== selected.activation_id) return false;
+  if (Number.isInteger(attempt.activation_epoch) && Number.isInteger(selected.activation_epoch)
+      && attempt.activation_epoch !== selected.activation_epoch) return false;
+  if (Number.isInteger(attempt.turn_sequence) && Number.isInteger(selected.turn_sequence)
+      && attempt.turn_sequence !== selected.turn_sequence) return false;
+  if (attempt.canonical_session_id && selected.canonical_session_id
+      && attempt.canonical_session_id !== selected.canonical_session_id) return false;
+  return true;
+}
+
+function snapshotPromotedAttemptCheckpoints(vault, selected) {
+  if (!selected) return new Map();
+  const registry = readSessionRegistry(vault);
+  return new Map(Object.entries(registry.sessions || {})
+    .filter(([, entry]) => matchesPromotedAttempt(entry?.last_memory_attempt, selected))
+    .map(([sessionId, entry]) => [sessionId, {
+      attempt: attemptFingerprint(entry.last_memory_attempt),
+      checkpoint: memoryCheckpointFingerprint(entry),
+    }]));
+}
+
+function refreshPromotedAttemptCheckpoint(vault, {
+  candidateId, decisionEventId, selected, checkpoint, decidedAt, expectedAttempts,
+}) {
+  if (!selected || !checkpoint || !expectedAttempts?.size) return 0;
+  return mutateSessionRegistry(vault, (registry) => {
+    let refreshed = 0;
+    for (const [sessionId, entry] of Object.entries(registry.sessions || {})) {
+      const expected = expectedAttempts.get(sessionId);
+      if (!expected) continue;
+      const attempt = entry?.last_memory_attempt;
+      if (attemptFingerprint(attempt) !== expected.attempt
+          || memoryCheckpointFingerprint(entry) !== expected.checkpoint) continue;
+
+      const alreadyAudited = (entry.memory_candidate_decisions || [])
+        .some((audit) => audit.decision_event_id === decisionEventId);
+      if (alreadyAudited && sameCheckpoint(attempt.checkpoint, checkpoint)
+          && sameCheckpoint(entry.memory_checkpoint, checkpoint)) continue;
+      const originalCheckpoint = cloneJson(attempt.checkpoint || entry.memory_checkpoint || null);
+      attempt.checkpoint = cloneJson(checkpoint);
+      entry.memory_checkpoint = cloneJson(checkpoint);
+      entry.memory_status = 'projected';
+      if (!alreadyAudited) {
+        entry.memory_candidate_decisions = [
+          ...(Array.isArray(entry.memory_candidate_decisions) ? entry.memory_candidate_decisions : []),
+          {
+            v: 1,
+            type: 'candidate_checkpoint_refreshed',
+            candidate_id: candidateId,
+            decision_event_id: decisionEventId,
+            selected_event_id: selected.event_id,
+            decided_at: decidedAt,
+            original_checkpoint: originalCheckpoint,
+            checkpoint: cloneJson(checkpoint),
+          },
+        ];
+      }
+      refreshed += 1;
+    }
+    return refreshed;
+  });
+}
+
+export function decideMemoryCandidate(vault, {
+  action, candidateId, value, eventId, beforeCheckpointRefresh,
+} = {}) {
   if (!['promote', 'reject'].includes(action)) throw new TypeError('action deve ser promote ou reject.');
   if (!candidateId) throw new TypeError('candidateId é obrigatório.');
+  const preflight = projectMemoryOutbox(vault);
+  if (preflight.status === 'busy') return { status: 'busy', candidateId };
+  const prior = priorCandidateDecision(vault, candidateId);
+  if (prior) {
+    assertCompatibleDecision(prior, { action, eventId });
+    const selected = action === 'promote' && prior.candidate_decision.selected_event_id
+      ? readMemoryLedger(vault).events.find(
+        (event) => event.event_id === prior.candidate_decision.selected_event_id,
+      )
+      : null;
+    const expectedAttempts = snapshotPromotedAttemptCheckpoints(vault, selected);
+    beforeCheckpointRefresh?.();
+    const checkpointRefreshed = action === 'promote'
+      ? refreshPromotedAttemptCheckpoint(vault, {
+        candidateId,
+        decisionEventId: prior.event_id,
+        selected,
+        checkpoint: preflight.checkpoint,
+        decidedAt: prior.observed_at,
+        expectedAttempts,
+      })
+      : 0;
+    return {
+      status: action === 'promote' ? 'promoted' : 'rejected',
+      candidateId,
+      eventId: prior.event_id,
+      alreadyApplied: true,
+      checkpointRefreshed,
+      projection: preflight,
+    };
+  }
   const candidates = readCandidates(vault);
   const candidate = candidates.find((item) => item.candidate_id === candidateId);
   if (!candidate) throw new Error(`Candidate não encontrado: ${candidateId}`);
+  if (action === 'promote' && candidate.reason === 'blocked_by_core') {
+    throw new Error(`Candidate ${candidateId} está blocked_by_core; edite CORE ou rejeite o candidate.`);
+  }
+  const selected = action === 'promote' ? candidateEvent(candidate, eventId) : null;
+  const expectedAttempts = snapshotPromotedAttemptCheckpoints(vault, selected);
+  const selectedValue = selected?.value ?? value ?? candidate.value ?? candidate.proposed_value;
+  if (action === 'promote' && selectedValue === undefined) {
+    throw new Error(`Candidate ${candidateId} não contém valor promovível.`);
+  }
+  const supersedes = action === 'promote' && selected
+    ? promotedSupersedes(vault, candidate, selected)
+    : [];
   const now = new Date().toISOString();
+  const decision = {
+    candidate_id: candidateId,
+    action,
+    event_ids: Array.isArray(candidate.event_ids) ? [...candidate.event_ids].sort() : [],
+    ...(selected ? { selected_event_id: selected.event_id } : {}),
+  };
   const event = {
     v: 1,
-    event_id: `cli-${action}-${hash(candidateId).slice(0, 20)}`,
+    event_id: `cli-${action}-${hash(`${candidateId}\0${selected?.event_id || ''}`).slice(0, 20)}`,
     project_id: projectId(vault),
-    memory_key: action === 'promote' ? candidate.memory_key : `candidate.rejected.${candidateId}`,
-    operation: 'assert',
-    value: sanitizeMemoryText(action === 'promote' ? (value ?? candidate.value ?? candidate.values?.[0] ?? '') : 'rejected'),
+    memory_key: action === 'promote' ? candidate.memory_key : `candidate.decision.${candidateId}`,
+    operation: action === 'promote' && selected ? 'replace' : 'assert',
+    value: action === 'promote' ? promotedMemoryValue(selectedValue) : 'rejected',
     authority: 'verified',
-    activation_id: 'wendkeep-memory-cli',
-    turn_sequence: 0,
+    ...(selected?.canonical_session_id
+      ? { canonical_session_id: selected.canonical_session_id }
+      : {}),
+    activation_id: selected?.activation_id || 'wendkeep-memory-cli',
+    ...(Number.isInteger(selected?.activation_epoch) ? { activation_epoch: selected.activation_epoch } : {}),
+    turn_sequence: selected?.turn_sequence ?? 0,
+    ...(selected?.source_turn_id ? { source_turn_id: selected.source_turn_id } : {}),
     observed_at: now,
     evidence: [`candidate:${candidateId}`],
+    candidate_decision: decision,
+    ...(selected ? { supersedes } : {}),
   };
   enqueueMemoryEvent(vault, event);
   const projection = projectMemoryOutbox(vault);
   if (projection.status === 'busy') return { status: 'busy', candidateId };
-  const remaining = candidates.filter((item) => item.candidate_id !== candidateId);
-  const projected = readCandidates(vault);
-  const merged = new Map([...remaining, ...projected].map((item) => [item.candidate_id, item]));
-  writeVaultFileAtomic(
-    vault, brainPath(vault, CANDIDATES), candidateText([...merged.values()]), 'utf8',
-    { label: 'candidates após decisão humana' },
-  );
-  return { status: action === 'promote' ? 'promoted' : 'rejected', candidateId, eventId: event.event_id, projection };
+  beforeCheckpointRefresh?.();
+  const checkpointRefreshed = action === 'promote'
+    ? refreshPromotedAttemptCheckpoint(vault, {
+      candidateId,
+      decisionEventId: event.event_id,
+      selected,
+      checkpoint: projection.checkpoint,
+      decidedAt: now,
+      expectedAttempts,
+    })
+    : 0;
+  return {
+    status: action === 'promote' ? 'promoted' : 'rejected',
+    candidateId,
+    eventId: event.event_id,
+    checkpointRefreshed,
+    projection,
+  };
 }
 
 function cloneJson(value) {
@@ -778,6 +1013,67 @@ function historicalAssertOnlyCheckpoint(vault, attempt, authority, checkpoint) {
   return currentPrefix.checkpoint;
 }
 
+function deferredAssertReplayCheckpointMigration(
+  sessionId, entry, authority, legacyReplay, fullReplay,
+) {
+  const attempt = entry?.last_memory_attempt;
+  const checkpoint = attempt?.checkpoint;
+  if (attempt?.memory_mode !== 'v2' || attempt?.state !== 'projected'
+      || attempt?.disposition !== 'applied' || !checkpointShape(checkpoint)) return null;
+  if (!Object.prototype.hasOwnProperty.call(entry, 'memory_checkpoint')
+      || !sameCheckpoint(entry.memory_checkpoint, checkpoint)
+      || !sameCheckpoint(checkpoint, legacyReplay.checkpoint)
+      || sameCheckpoint(checkpoint, fullReplay.checkpoint)) return null;
+
+  const requiredEventIds = Array.isArray(attempt.event_ids) ? [...attempt.event_ids] : [];
+  if (!requiredEventIds.length || new Set(requiredEventIds).size !== requiredEventIds.length) return null;
+  const current = fullReplay.records?.['handoff.latest']?.source;
+  if (!current?.event_id || !requiredEventIds.includes(current.event_id)) return null;
+  const relevantLegacyCandidate = legacyReplay.candidates.some(
+    (candidate) => candidate.memory_key === 'handoff.latest'
+      && candidate.event_ids.includes(current.event_id),
+  );
+  const relevantCandidateStillReal = fullReplay.candidates.some(
+    (candidate) => candidate.memory_key === 'handoff.latest',
+  );
+  if (!relevantLegacyCandidate || relevantCandidateStillReal) return null;
+
+  const currentIdentity = {
+    canonical_session_id: current.canonical_session_id,
+    activation_id: current.activation_id,
+    activation_epoch: current.activation_epoch,
+    source_turn_id: current.source_turn_id,
+    turn_sequence: current.turn_sequence,
+  };
+  if (currentIdentity.canonical_session_id !== sessionId
+      || attempt.canonical_session_id !== currentIdentity.canonical_session_id
+      || attempt.activation_id !== currentIdentity.activation_id
+      || attempt.activation_epoch !== currentIdentity.activation_epoch
+      || attempt.turn_id !== currentIdentity.source_turn_id
+      || attempt.turn_sequence !== currentIdentity.turn_sequence) return null;
+
+  const newerAttemptEvent = authority.ledgerEvents.some((event) => (
+    event.canonical_session_id === currentIdentity.canonical_session_id
+      && event.activation_id === currentIdentity.activation_id
+      && event.activation_epoch === currentIdentity.activation_epoch
+      && Number.isInteger(event.turn_sequence)
+      && event.turn_sequence > currentIdentity.turn_sequence
+  ));
+  if (newerAttemptEvent) return null;
+
+  const proof = validateSuccessorProof({ bySessionId: sessionId }, attempt, authority);
+  return {
+    sessionId,
+    expectedFingerprint: attemptFingerprint(attempt),
+    expectedMemoryCheckpointFingerprint: memoryCheckpointFingerprint(entry),
+    originalCheckpoint: cloneJson(checkpoint),
+    checkpoint: cloneJson(fullReplay.checkpoint),
+    proof,
+    migrationType: 'deferred_assert_replay_migrated',
+    eventIds: requiredEventIds,
+  };
+}
+
 function legacyCheckpointMigration(vault, sessionId, entry, authority, fullReplay) {
   const attempt = entry?.last_memory_attempt;
   const checkpoint = attempt?.checkpoint;
@@ -807,6 +1103,8 @@ function legacyCheckpointMigration(vault, sessionId, entry, authority, fullRepla
     originalCheckpoint: cloneJson(checkpoint),
     checkpoint: cloneJson(nextCheckpoint),
     proof,
+    migrationType: 'legacy_causal_checkpoint_migrated',
+    eventIds: requiredEventIds,
   };
 }
 
@@ -818,11 +1116,14 @@ export function migrateLegacyMemoryCheckpoints(vault, {
     const authority = readMemoryAuthority(vault);
     assertAuthorityMatches(expectedAuthority, authority);
     const inspected = readSessionRegistry(vault);
+    const legacyReplay = deriveMemoryProjection(vault, authority.ledgerEvents, {
+      resolveDeferredAsserts: false,
+    });
     const fullReplay = deriveMemoryProjection(vault, authority.ledgerEvents);
     const plans = Object.entries(inspected.sessions || {})
-      .map(([sessionId, entry]) => legacyCheckpointMigration(
-        vault, sessionId, entry, authority, fullReplay,
-      ))
+      .map(([sessionId, entry]) => deferredAssertReplayCheckpointMigration(
+        sessionId, entry, authority, legacyReplay, fullReplay,
+      ) || legacyCheckpointMigration(vault, sessionId, entry, authority, fullReplay))
       .filter(Boolean);
     assertAuthorityMatches(expectedAuthority, readMemoryAuthority(vault));
     if (!plans.length) return {
@@ -861,14 +1162,20 @@ export function migrateLegacyMemoryCheckpoints(vault, {
 
         for (const plan of plans) {
           const entry = registry.sessions[plan.sessionId];
-          const reconciliationId = `memcp-${hash(`${plan.sessionId}\0${plan.expectedFingerprint}\0${plan.expectedMemoryCheckpointFingerprint}\0${canonicalMemoryJson(plan.checkpoint)}`).slice(0, 20)}`;
+          const reconciliationSeed = plan.migrationType === 'legacy_causal_checkpoint_migrated'
+            ? `${plan.sessionId}\0${plan.expectedFingerprint}\0${plan.expectedMemoryCheckpointFingerprint}\0${canonicalMemoryJson(plan.checkpoint)}`
+            : `${plan.migrationType}\0${plan.sessionId}\0${plan.expectedFingerprint}\0${plan.expectedMemoryCheckpointFingerprint}\0${canonicalMemoryJson(plan.checkpoint)}`;
+          const reconciliationId = `memcp-${hash(reconciliationSeed).slice(0, 20)}`;
           entry.memory_reconciliations = [
             ...(Array.isArray(entry.memory_reconciliations) ? entry.memory_reconciliations : []),
             {
               v: 1,
               reconciliation_id: reconciliationId,
-              type: 'legacy_causal_checkpoint_migrated',
+              type: plan.migrationType,
               reconciled_at: now,
+              ...(plan.migrationType === 'deferred_assert_replay_migrated'
+                ? { event_ids: [...plan.eventIds] }
+                : {}),
               causal_proof: cloneJson(plan.proof),
               original_checkpoint: cloneJson(plan.originalCheckpoint),
               checkpoint: cloneJson(plan.checkpoint),
@@ -1038,8 +1345,14 @@ export function runMemory(argv) {
         apply: reconcileArgs.apply,
       });
     }
-    else if (sub === 'promote' || sub === 'reject') result = decideMemoryCandidate(vault, { action: sub, candidateId: positional });
-    else { process.stderr.write('wendkeep memory: use status | migrate [--apply] | repair | reconcile <session> --by-session <session> --reason <text> [--apply] | promote <candidate> | reject <candidate>.\n'); process.exitCode = 2; return; }
+    else if (sub === 'promote' || sub === 'reject') {
+      const eventId = option(argv, '--event');
+      if (sub === 'reject' && eventId) throw memoryUsageError('--event é permitido somente em memory promote.');
+      result = decideMemoryCandidate(vault, {
+        action: sub, candidateId: positional, ...(eventId ? { eventId } : {}),
+      });
+    }
+    else { process.stderr.write('wendkeep memory: use status | migrate [--apply] | repair | reconcile <session> --by-session <session> --reason <text> [--apply] | promote <candidate> [--event <event-id>] | reject <candidate>.\n'); process.exitCode = 2; return; }
     process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
     if (sub === 'status' && argv.includes('--gate')) process.exitCode = result.status === 'blocked' ? 1 : 0;
     else if (sub === 'reconcile' && reconcileArgs.apply) process.exitCode = result.health?.status === 'blocked' ? 1 : 0;