wendkeep 0.58.0 → 0.58.3

package/hooks/memory-schema.mjs

@@ -293,3 +293,18 @@ export function validateSharedMemory(content, { eventIds } = {}) {
     sections: parsed.sections,
   };
 }
+
+/**
+ * Classify SHARED from its own bytes without accepting malformed v2 as legacy.
+ * Empty v2 sidecar files are intentionally not part of this pure classification;
+ * vault-level operational evidence is handled by memory-mode.mjs.
+ */
+export function classifySharedMemory(content) {
+  const text = String(content ?? '').replace(/\r\n/g, '\n');
+  if (validateSharedMemory(text).ok) return { mode: 'v2', reason: 'valid-v2' };
+  const hasV2Signature = /^(?:schema_version|event_cursor|state_hash)\s*:/m.test(text)
+    || /^# SHARED_MEMORY\s+[—-]\s+proje[cç][aã]o operacional gerada\s*$/mi.test(text);
+  return hasV2Signature
+    ? { mode: 'v2', reason: 'v2-signature' }
+    : { mode: 'legacy', reason: text.trim() ? 'legacy-shared' : 'shared-absent' };
+}

package/hooks/obsidian-common.mjs

@@ -355,7 +355,7 @@ export function mutateSessionRegistry(vaultBase, mutator, { timeoutMs = 2000 } =
 function meaningfulPatch(patch = {}) {
   const protectedNonEmpty = new Set(['session_file', 'transcript_path', 'transcript_id', 'provider', 'started_at', 'change_slug', 'activation_id']);
   return Object.fromEntries(Object.entries(patch).filter(([key, value]) => {
-    if (key === 'advance_turn_sequence' || key === 'turn_sequence') return false;
+    if (['advance_turn_sequence', 'turn_sequence', 'turn_id', 'last_turn_sequence', 'recovery_activation_id', 'recovery_started_at'].includes(key)) return false;
     if (value === undefined || value === null) return false;
     if (value === '' && protectedNonEmpty.has(key)) return false;
     return true;
@@ -390,9 +390,13 @@ export function openActivation(registry, session = {}, explicitActivationId = ''
 
   const current = next.sessions[sessionId] || {};
   const activations = { ...(current.activations || {}) };
+  const openedAfterSequence = nonNegativeSequence(
+    session.opened_after_turn_sequence,
+    nonNegativeSequence(current.last_turn_sequence, 0),
+  );
   const requestedSequence = nonNegativeSequence(
     session.turn_sequence ?? session.last_turn_sequence,
-    0,
+    openedAfterSequence,
   );
 
   if (current.active_activation_id === activationId && activations[activationId]?.status === 'active') {
@@ -430,7 +434,9 @@ export function openActivation(registry, session = {}, explicitActivationId = ''
     epoch,
     status: 'active',
     started_at: session.activation_started_at || session.started_at || '',
-    last_turn_sequence: requestedSequence,
+    opened_after_turn_sequence: openedAfterSequence,
+    ...(current.last_turn_id ? { opened_after_turn_id: current.last_turn_id } : {}),
+    last_turn_sequence: Math.max(openedAfterSequence, requestedSequence),
     ...(session.transcript_id ? { transcript_id: session.transcript_id } : {}),
     ...(session.transcript_path ? { transcript_path: session.transcript_path } : {}),
     ...(session.provider ? { provider: session.provider } : {}),
@@ -441,19 +447,40 @@ export function openActivation(registry, session = {}, explicitActivationId = ''
     active_activation_id: activationId,
     activation_epoch: epoch,
     activation_started_at: session.activation_started_at || session.started_at || '',
-    last_turn_sequence: requestedSequence,
+    last_turn_sequence: Math.max(openedAfterSequence, requestedSequence),
     activations,
   };
   return next;
 }
 
 export function advanceActivationTurn(registry, turn = {}) {
-  const next = cloneRegistry(registry);
+  let next = cloneRegistry(registry);
   const sessionId = turn.session_id || turn.canonical_session_id || '';
-  const current = next.sessions[sessionId];
+  let current = next.sessions[sessionId];
   if (!current) return next;
 
-  const activeId = current.active_activation_id || '';
+  const turnId = String(turn.turn_id || '');
+  const knownTurn = Boolean(turnId && (
+    current.last_turn_id === turnId
+    || current.last_prompt_turn_id === turnId
+    || Object.prototype.hasOwnProperty.call(current.turn_sequences || {}, turnId)
+  ));
+  if (knownTurn) return next;
+
+  let activeId = current.active_activation_id || '';
+  if ((!activeId || current.activations?.[activeId]?.status !== 'active') && turn.recovery_activation_id) {
+    next = openActivation(next, {
+      session_id: sessionId,
+      activation_id: turn.recovery_activation_id,
+      activation_started_at: turn.recovery_started_at || turn.started_at || '',
+      turn_sequence: turn.turn_sequence ?? current.last_turn_sequence,
+      transcript_id: turn.transcript_id || current.transcript_id,
+      transcript_path: turn.transcript_path || current.transcript_path,
+      provider: turn.provider || current.provider,
+    });
+    current = next.sessions[sessionId];
+    activeId = current.active_activation_id || '';
+  }
   if (turn.activation_id && activeId && turn.activation_id !== activeId) return next;
   const previous = nonNegativeSequence(current.last_turn_sequence, 0);
   const explicit = nonNegativeSequence(turn.turn_sequence ?? turn.last_turn_sequence);
@@ -466,9 +493,18 @@ export function advanceActivationTurn(registry, turn = {}) {
         nonNegativeSequence(activations[activeId].last_turn_sequence, 0),
         sequence,
       ),
+      ...(turnId ? { last_prompt_turn_id: turnId } : {}),
     };
   }
-  next.sessions[sessionId] = { ...current, last_turn_sequence: sequence, activations };
+  next.sessions[sessionId] = {
+    ...current,
+    last_turn_sequence: sequence,
+    ...(turnId ? {
+      last_prompt_turn_id: turnId,
+      turn_sequences: { ...(current.turn_sequences || {}), [turnId]: sequence },
+    } : {}),
+    activations,
+  };
   return next;
 }
 
@@ -478,23 +514,22 @@ export function resolveStopActivation(registry, stop = {}) {
   if (!entry) return '';
   if (stop.activation_id) return String(stop.activation_id);
 
+  const activeId = entry.active_activation_id || '';
+  const active = entry.activations?.[activeId];
+  if (!activeId || active?.status !== 'active') return '';
   const transcriptId = String(stop.transcript_id || '');
   const transcriptPath = String(stop.transcript_path || '');
   if (!transcriptId && !transcriptPath) return '';
-  const matches = Object.entries(entry.activations || {}).filter(([, activation]) => {
-    if (!activation) return false;
-    if (transcriptId && activation.transcript_id && activation.transcript_id !== transcriptId) return false;
-    const paths = [
-      ...(Array.isArray(activation.transcript_paths) ? activation.transcript_paths : []),
-      activation.transcript_path,
-    ].filter(Boolean);
-    if (transcriptPath && paths.length && !paths.some((path) => transcriptsMatch(path, transcriptPath))) return false;
-    return Boolean(
-      (transcriptId && activation.transcript_id === transcriptId)
-      || (transcriptPath && paths.some((path) => transcriptsMatch(path, transcriptPath))),
-    );
-  });
-  return matches.length === 1 ? matches[0][0] : '';
+  if (transcriptId && active.transcript_id && active.transcript_id !== transcriptId) return '';
+  const paths = [
+    ...(Array.isArray(active.transcript_paths) ? active.transcript_paths : []),
+    active.transcript_path,
+  ].filter(Boolean);
+  if (transcriptPath && paths.length && !paths.some((path) => transcriptsMatch(path, transcriptPath))) return '';
+  return (
+    (transcriptId && active.transcript_id === transcriptId)
+    || (transcriptPath && paths.some((path) => transcriptsMatch(path, transcriptPath)))
+  ) ? activeId : '';
 }
 
 function stopResult(registry, stopDisposition, canPromoteMemory = false) {
@@ -531,21 +566,31 @@ export function applyStopActivation(registry, stop = {}) {
   const stopSequence = nonNegativeSequence(stop.turn_sequence ?? stop.last_turn_sequence);
   const lastSequence = nonNegativeSequence(current.last_turn_sequence, 0);
   if (stopSequence === null) return stopResult(next, 'ambiguous');
+  const active = current.activations?.[activeId] || {};
+  const openedAfterSequence = nonNegativeSequence(active.opened_after_turn_sequence, 0);
+  if (stopSequence <= openedAfterSequence && active.epoch > 1) {
+    return stopResult(next, 'superseded');
+  }
+  const stopTurnId = String(stop.turn_id || '');
+  if (stopTurnId && active.last_stop_turn_id === stopTurnId) {
+    return stopResult(next, 'duplicate');
+  }
   if (stopSequence < lastSequence) return stopResult(next, 'stale_turn');
 
   const activations = { ...(current.activations || {}) };
   activations[activeId] = {
     ...(activations[activeId] || { activation_id: activeId, epoch: current.activation_epoch }),
-    status: 'done',
-    ended_at: stop.ended_at || '',
+    status: 'active',
     last_turn_sequence: stopSequence,
+    last_stop_turn_sequence: stopSequence,
+    ...(stopTurnId ? { last_stop_turn_id: stopTurnId } : {}),
   };
   next.sessions[sessionId] = {
     ...current,
-    status: 'done',
-    ended_at: stop.ended_at || current.ended_at || '',
-    active_activation_id: '',
-    last_turn_sequence: stopSequence,
+    status: 'active',
+    active_activation_id: activeId,
+    last_turn_sequence: Math.max(lastSequence, stopSequence),
+    ...(stopTurnId ? { last_turn_id: stopTurnId } : {}),
     activations,
   };
   return stopResult(next, 'applied', true);
@@ -584,7 +629,7 @@ export function upsertSessionRegistry(vaultBase, sessionId, patch) {
           activation_id: clean.activation_id,
           activation_started_at: clean.activation_started_at,
           started_at: clean.activation_started_at || clean.started_at,
-          last_turn_sequence: clean.last_turn_sequence,
+          last_turn_sequence: patch.last_turn_sequence,
           transcript_id: clean.transcript_id || current.transcript_id,
           transcript_path: clean.transcript_path || current.transcript_path,
           provider: clean.provider || current.provider,
@@ -597,7 +642,13 @@ export function upsertSessionRegistry(vaultBase, sessionId, patch) {
         {
           session_id: sessionId,
           activation_id: causalCurrent.active_activation_id || '',
+          recovery_activation_id: patch.recovery_activation_id || '',
+          recovery_started_at: patch.recovery_started_at || '',
+          turn_id: patch.turn_id || '',
           turn_sequence: patch.turn_sequence,
+          transcript_id: clean.transcript_id || causalCurrent.transcript_id,
+          transcript_path: clean.transcript_path || causalCurrent.transcript_path,
+          provider: clean.provider || causalCurrent.provider,
         },
       ).sessions[sessionId];
     }

package/hooks/session-ensure.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { randomUUID } from 'crypto';
 import { existsSync, renameSync, statSync, writeFileSync } from 'fs';
 import { basename, dirname, join } from 'path';
 import {
@@ -43,6 +44,16 @@ function turnSequenceFromInput(input = {}) {
   return Number.isSafeInteger(parsed) && parsed >= 0 ? parsed : undefined;
 }
 
+function causalTurnPatch(input, now) {
+  return {
+    advance_turn_sequence: true,
+    turn_sequence: turnSequenceFromInput(input),
+    turn_id: input.turn_id || input.turnId || '',
+    recovery_activation_id: randomUUID(),
+    recovery_started_at: formatLocalIso(now),
+  };
+}
+
 function buildSessionContent({ relPath, now, summary = 'session', sessionId = '', reason = 'Sessão criada automaticamente pelo hook UserPromptSubmit.' }) {
   const date = formatDate(now);
   const startedAt = formatLocalIso(now);
@@ -268,8 +279,7 @@ function activateExistingSession({ vaultBase, relPath, startedAt, sessionId, inp
     transcript_path: identity.transcriptPath,
     transcript_id: identity.transcriptId,
     provider: identity.provider,
-    advance_turn_sequence: true,
-    turn_sequence: turnSequenceFromInput(input),
+    ...causalTurnPatch(input, now),
   });
   return true;
 }
@@ -296,8 +306,7 @@ function createSession({ vaultBase, sessionId, input, now, identity }) {
     transcript_path: identity.transcriptPath,
     transcript_id: identity.transcriptId,
     provider: identity.provider,
-    advance_turn_sequence: true,
-    turn_sequence: turnSequenceFromInput(input),
+    ...causalTurnPatch(input, now),
   });
   return { relPath, startedAt };
 }
@@ -348,8 +357,7 @@ function main() {
           transcript_path: identity.transcriptPath,
           transcript_id: identity.transcriptId,
           provider: identity.provider,
-          advance_turn_sequence: true,
-          turn_sequence: turnSequenceFromInput(input),
+          ...causalTurnPatch(input, now),
         });
         writeHookOutput({});
         return;
@@ -393,8 +401,7 @@ function main() {
         transcript_path: identity.transcriptPath,
         transcript_id: identity.transcriptId,
         provider: identity.provider,
-        advance_turn_sequence: true,
-        turn_sequence: turnSequenceFromInput(input),
+        ...causalTurnPatch(input, now),
       });
       writeHookOutput({});
       return;

package/hooks/session-memory-lifecycle.mjs

@@ -0,0 +1,330 @@
+// Durable SessionStop memory publication split into three explicit phases:
+// registry-guarded outbox staging -> independent projection -> registry CAS outcome.
+// Keeping the MEMORY lock out of the registry critical section avoids lock inversion,
+// while the immutable outbox is the durable hand-off between both locks.
+import { buildSessionMemoryEvents } from './memory-handoff.mjs';
+import { detectMemoryMode } from './memory-mode.mjs';
+import { sanitizeMemoryText } from './memory-schema.mjs';
+import { enqueueMemoryEvent, projectMemoryOutbox } from './memory-store.mjs';
+import { mutateSessionRegistry } from './obsidian-common.mjs';
+
+const DEFAULT_OBSERVED_AT = '1970-01-01T00:00:00.000Z';
+
+const DEFAULT_DEPS = Object.freeze({
+  buildSessionMemoryEvents,
+  detectMemoryMode,
+  enqueueMemoryEvent,
+  mutateSessionRegistry,
+  projectMemoryOutbox,
+  sanitizeMemoryText,
+});
+
+function dependencies(overrides = {}) {
+  return { ...DEFAULT_DEPS, ...(overrides || {}) };
+}
+
+function nonNegativeInteger(value, fallback = 0) {
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) && parsed >= 0 ? parsed : fallback;
+}
+
+function normalizeContext(context = {}) {
+  const handoff = context.handoff && typeof context.handoff === 'object'
+    ? context.handoff
+    : context;
+  const identity = handoff.identity || context.identity || {};
+  const activation = handoff.activation || context.activation || {};
+  const turn = handoff.turn || context.turn || {};
+  const sessionId = String(
+    context.sessionId
+    || context.canonicalSessionId
+    || identity.canonicalConversationId
+    || '',
+  );
+  const activationId = String(context.activationId || activation.id || '');
+  const activationEpoch = nonNegativeInteger(
+    context.activationEpoch ?? activation.epoch,
+    0,
+  );
+  const turnId = String(context.turnId || turn.id || '');
+  const turnSequence = nonNegativeInteger(context.turnSequence ?? turn.sequence, 0);
+  const observedAt = String(context.observedAt || handoff.observedAt || DEFAULT_OBSERVED_AT);
+  const disposition = String(
+    context.disposition
+    || context.stopDisposition
+    || 'applied',
+  );
+
+  return {
+    sessionId,
+    activationId,
+    activationEpoch,
+    turnId,
+    turnSequence,
+    observedAt,
+    disposition,
+    handoff: {
+      ...handoff,
+      identity: { ...identity, canonicalConversationId: sessionId },
+      activation: { ...activation, id: activationId, epoch: activationEpoch },
+      turn: { ...turn, id: turnId, sequence: turnSequence },
+      observedAt,
+    },
+  };
+}
+
+function attemptIdentity(context, memoryMode) {
+  return {
+    v: 1,
+    memory_mode: memoryMode,
+    canonical_session_id: context.sessionId,
+    activation_id: context.activationId,
+    activation_epoch: context.activationEpoch,
+    turn_id: context.turnId,
+    turn_sequence: context.turnSequence,
+    observed_at: context.observedAt,
+  };
+}
+
+function sameAttempt(left, right) {
+  if (!left || !right) return false;
+  return String(left.canonical_session_id || '') === String(right.canonical_session_id || '')
+    && String(left.activation_id || '') === String(right.activation_id || '')
+    && nonNegativeInteger(left.activation_epoch, -1) === nonNegativeInteger(right.activation_epoch, -1)
+    && String(left.turn_id || '') === String(right.turn_id || '')
+    && nonNegativeInteger(left.turn_sequence, -1) === nonNegativeInteger(right.turn_sequence, -1);
+}
+
+function skippedAttempt(context, memoryMode, disposition) {
+  return {
+    ...attemptIdentity(context, memoryMode),
+    disposition,
+    state: 'skipped',
+    event_ids: [],
+    checkpoint: null,
+  };
+}
+
+function causalDisposition(entry, context) {
+  if (!entry || !context.sessionId || !context.activationId || !context.turnId) return 'ambiguous';
+  if (['ambiguous', 'stale_turn', 'superseded'].includes(context.disposition)) {
+    return context.disposition;
+  }
+
+  const activeId = String(entry.active_activation_id || '');
+  const active = entry.activations?.[activeId];
+  if (!activeId || activeId !== context.activationId || active?.status !== 'active') {
+    return 'superseded';
+  }
+  if (nonNegativeInteger(active.epoch, -1) !== context.activationEpoch) return 'superseded';
+
+  const openedAfter = nonNegativeInteger(active.opened_after_turn_sequence, 0);
+  if (context.activationEpoch > 1 && context.turnSequence <= openedAfter) return 'superseded';
+
+  const lastStopSequence = nonNegativeInteger(
+    active.last_stop_turn_sequence,
+    nonNegativeInteger(entry.last_turn_sequence, 0),
+  );
+  const lastStopTurnId = String(active.last_stop_turn_id || entry.last_turn_id || '');
+  if (lastStopSequence > context.turnSequence) return 'stale_turn';
+  if (lastStopTurnId && lastStopTurnId !== context.turnId) return 'stale_turn';
+  return 'applied';
+}
+
+function retryAttempt(previous) {
+  if (previous.state === 'projected' || previous.state === 'duplicate') {
+    return { ...previous, disposition: 'duplicate', state: 'duplicate', retry: true };
+  }
+  if (previous.state === 'enqueued' || previous.state === 'degraded') {
+    return { ...previous, state: 'enqueued', retry: true };
+  }
+  return null;
+}
+
+function canPersistAmbiguousSkip(entry, candidate) {
+  if (candidate.disposition !== 'ambiguous') return false;
+  const entryEpoch = nonNegativeInteger(entry.activation_epoch, -1);
+  if (entryEpoch > candidate.activation_epoch) return false;
+  if (entryEpoch === candidate.activation_epoch
+      && nonNegativeInteger(entry.last_turn_sequence, -1) > candidate.turn_sequence) {
+    return false;
+  }
+
+  const previous = entry.last_memory_attempt;
+  if (!previous) return true;
+  const previousEpoch = nonNegativeInteger(previous.activation_epoch, -1);
+  if (previousEpoch !== candidate.activation_epoch) return previousEpoch < candidate.activation_epoch;
+  const previousTurn = nonNegativeInteger(previous.turn_sequence, -1);
+  if (previousTurn !== candidate.turn_sequence) return previousTurn < candidate.turn_sequence;
+  return sameAttempt(previous, candidate) && previous.state === 'skipped';
+}
+
+/**
+ * Revalidate the Stop under SESSION_REGISTRY.lock, durably enqueue every event, and only
+ * then acknowledge `last_memory_attempt.state = enqueued` in the same registry mutation.
+ */
+export function stageStopMemoryAttempt(vaultBase, rawContext, overrides = {}) {
+  const deps = dependencies(overrides);
+  const context = normalizeContext(rawContext);
+  const mode = deps.detectMemoryMode(vaultBase).mode;
+  if (mode === 'legacy') return skippedAttempt(context, 'legacy', 'legacy');
+
+  const identity = attemptIdentity(context, 'v2');
+  let staged = null;
+  deps.mutateSessionRegistry(vaultBase, (registry) => {
+    const entry = registry.sessions?.[context.sessionId];
+    const disposition = causalDisposition(entry, context);
+    if (disposition !== 'applied') {
+      staged = skippedAttempt(context, 'v2', disposition);
+      if (entry && canPersistAmbiguousSkip(entry, staged)) {
+        entry.last_memory_attempt = staged;
+        entry.memory_status = 'skipped';
+        if (context.activationId) entry.memory_activation_id = context.activationId;
+      }
+      return staged;
+    }
+
+    const previous = entry.last_memory_attempt;
+    if (sameAttempt(previous, identity)) {
+      const retry = retryAttempt(previous);
+      if (retry) {
+        staged = retry;
+        return staged;
+      }
+    }
+
+    const events = deps.buildSessionMemoryEvents(context.handoff);
+    if (!Array.isArray(events) || events.length === 0) {
+      throw new TypeError('Session memory staging requires at least one event.');
+    }
+    for (const event of events) deps.enqueueMemoryEvent(vaultBase, event);
+
+    staged = {
+      ...identity,
+      disposition: 'applied',
+      state: 'enqueued',
+      event_ids: events.map((event) => String(event.event_id || '')),
+      checkpoint: null,
+    };
+    entry.last_memory_attempt = staged;
+    entry.memory_status = 'enqueued';
+    entry.memory_activation_id = context.activationId;
+    return staged;
+  });
+
+  return staged || skippedAttempt(context, 'v2', 'ambiguous');
+}
+
+function outcome(attempt, state, extra = {}) {
+  const eventIds = Array.isArray(attempt?.event_ids) ? [...attempt.event_ids] : [];
+  return {
+    ...attempt,
+    ...extra,
+    state,
+    status: state,
+    event_ids: eventIds,
+    eventIds,
+    eventCount: eventIds.length,
+  };
+}
+
+/** Project outside the registry lock. The outbox remains the recovery authority on failure. */
+export function projectStopMemoryAttempt(vaultBase, attempt, overrides = {}) {
+  const deps = dependencies(overrides);
+  if (attempt?.memory_mode === 'legacy') {
+    return { ...outcome(attempt, 'skipped'), status: 'legacy' };
+  }
+  if (attempt?.state === 'duplicate') return outcome(attempt, 'duplicate');
+  if (attempt?.state === 'skipped') return outcome(attempt, 'skipped');
+
+  try {
+    const projection = deps.projectMemoryOutbox(vaultBase, overrides.projectOptions || {});
+    if (projection?.status === 'busy') {
+      return outcome(attempt, 'degraded', {
+        error: 'memory projector busy; outbox preserved for replay',
+        checkpoint: null,
+      });
+    }
+    return outcome(attempt, 'projected', {
+      checkpoint: {
+        revision: projection.revision,
+        event_cursor: projection.eventCursor,
+        state_hash: projection.stateHash,
+      },
+    });
+  } catch (error) {
+    return outcome(attempt, 'degraded', {
+      error: deps.sanitizeMemoryText(error?.message || String(error)),
+      checkpoint: null,
+    });
+  }
+}
+
+function activeContextMatches(entry, attempt) {
+  const activeId = String(entry?.active_activation_id || '');
+  const active = entry?.activations?.[activeId];
+  return activeId === String(attempt.activation_id || '')
+    && active?.status === 'active'
+    && nonNegativeInteger(active.epoch, -1) === nonNegativeInteger(attempt.activation_epoch, -1);
+}
+
+function storedAttempt(outcomeValue) {
+  const stored = {
+    v: 1,
+    memory_mode: 'v2',
+    canonical_session_id: String(outcomeValue.canonical_session_id || ''),
+    activation_id: String(outcomeValue.activation_id || ''),
+    activation_epoch: nonNegativeInteger(outcomeValue.activation_epoch, 0),
+    turn_id: String(outcomeValue.turn_id || ''),
+    turn_sequence: nonNegativeInteger(outcomeValue.turn_sequence, 0),
+    disposition: String(outcomeValue.disposition || 'applied'),
+    state: outcomeValue.state,
+    event_ids: Array.isArray(outcomeValue.event_ids) ? [...outcomeValue.event_ids] : [],
+    observed_at: String(outcomeValue.observed_at || DEFAULT_OBSERVED_AT),
+  };
+  if (outcomeValue.state === 'projected' && outcomeValue.checkpoint) {
+    stored.checkpoint = { ...outcomeValue.checkpoint };
+  }
+  if (outcomeValue.state === 'degraded' && outcomeValue.error) {
+    stored.error = String(outcomeValue.error);
+  }
+  return stored;
+}
+
+/** Persist a final outcome only while the exact staged activation/epoch/turn still owns it. */
+export function recordStopMemoryOutcome(vaultBase, attempt, outcomeValue, overrides = {}) {
+  if (attempt?.memory_mode === 'legacy' || outcomeValue?.status === 'legacy') {
+    return { ...outcomeValue, persisted: false, reason: 'legacy' };
+  }
+  if (outcomeValue?.state === 'duplicate' || outcomeValue?.state === 'skipped') {
+    return { ...outcomeValue, persisted: false, reason: outcomeValue.state };
+  }
+  if (!sameAttempt(attempt, outcomeValue)) {
+    return { ...outcomeValue, persisted: false, reason: 'stale-causal-context' };
+  }
+  if (!['projected', 'degraded'].includes(outcomeValue?.state)) {
+    return { ...outcomeValue, persisted: false, reason: 'non-final-outcome' };
+  }
+
+  const deps = dependencies(overrides);
+  let result = { ...outcomeValue, persisted: false, reason: 'stale-causal-context' };
+  deps.mutateSessionRegistry(vaultBase, (registry) => {
+    const entry = registry.sessions?.[attempt.canonical_session_id];
+    if (!entry || !activeContextMatches(entry, attempt)) return result;
+    if (!sameAttempt(entry.last_memory_attempt, attempt)) return result;
+
+    entry.last_memory_attempt = storedAttempt(outcomeValue);
+    entry.memory_status = outcomeValue.state;
+    entry.memory_activation_id = attempt.activation_id;
+    if (outcomeValue.state === 'projected') {
+      entry.memory_checkpoint = { ...outcomeValue.checkpoint };
+    } else {
+      // This branch is reachable only after the exact attempt CAS above. A stale outcome
+      // cannot clear a checkpoint owned by a newer activation/turn.
+      delete entry.memory_checkpoint;
+    }
+    result = { ...outcomeValue, persisted: true, reason: 'recorded' };
+    return result;
+  });
+  return result;
+}