wendkeep 0.66.4 → 0.66.5

package/hooks/session-observability-state.mjs

@@ -0,0 +1,241 @@
+import { createHash } from 'node:crypto';
+
+export const OBSERVABILITY_SCHEMA = 2;
+
+export const OBSERVABILITY_DIAGNOSTIC_CODES = Object.freeze([
+  'CACHE_INVALID',
+  'CHILD_META_INVALID',
+  'CHILD_MISSING',
+  'DUPLICATE_ROLLOUT_ID',
+  'FALLBACK_LIMIT_EXCEEDED',
+  'GRAPH_LIMIT_EXCEEDED',
+  'LEGACY_CHAIN_UNPROVEN',
+  'LIVE_BYTE_BUDGET_EXCEEDED',
+  'LIVE_DEADLINE_EXCEEDED',
+  'MAIN_TRANSCRIPT_UNRESOLVED',
+  'PARENT_META_INVALID',
+  'ROOT_MISMATCH',
+  'SOURCE_CHANGED_DURING_SCAN',
+  'STALE_FRONTIER',
+]);
+
+const DIAGNOSTIC_CODE_SET = new Set(OBSERVABILITY_DIAGNOSTIC_CODES);
+const OBSERVABILITY_STATES = new Set(['complete', 'none', 'degraded']);
+const FRONTIER_STRING_FIELDS = [
+  'canonical_session_id',
+  'activation_id',
+  'roots_stat_hash',
+  'graph_cursor',
+  'source_manifest_hash',
+];
+const FRONTIER_SEQUENCE_FIELDS = [
+  'activation_epoch',
+  'turn_sequence',
+  'signal_sequence',
+];
+const FRONTMATTER_TO_FRONTIER = Object.freeze({
+  canonical_session_id: 'observability_session_id',
+  activation_id: 'observability_activation_id',
+  activation_epoch: 'observability_activation_epoch',
+  turn_sequence: 'observability_turn_sequence',
+  signal_sequence: 'observability_signal_sequence',
+  roots_stat_hash: 'observability_roots_stat_hash',
+  graph_cursor: 'observability_graph_cursor',
+  source_manifest_hash: 'observability_source_manifest_hash',
+});
+
+function diagnosticError() {
+  const error = new TypeError('diagnostic de observabilidade inválido');
+  error.code = 'OBSERVABILITY_DIAGNOSTIC_INVALID';
+  return error;
+}
+
+function frontierError() {
+  const error = new TypeError('frontier de observabilidade inválido');
+  error.code = 'OBSERVABILITY_FRONTIER_INVALID';
+  return error;
+}
+
+function checkpointError() {
+  const error = new TypeError('checkpoint de observabilidade inválido');
+  error.code = 'OBSERVABILITY_CHECKPOINT_INVALID';
+  return error;
+}
+
+function safeNonEmptyString(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+function safeSequence(value) {
+  if (typeof value === 'string' && /^\d+$/.test(value.trim())) value = Number(value);
+  return Number.isSafeInteger(value) && value >= 0 ? value : null;
+}
+
+/**
+ * Reduce diagnostics to the only shape that may cross the local runtime boundary.
+ * Values are never interpolated in thrown errors so rejected private data is not echoed.
+ */
+export function sanitizeObservabilityDiagnostics(diagnostics = []) {
+  if (!Array.isArray(diagnostics)) throw diagnosticError();
+  const counts = new Map();
+  for (const diagnostic of diagnostics) {
+    if (!diagnostic || typeof diagnostic !== 'object' || Array.isArray(diagnostic)) {
+      throw diagnosticError();
+    }
+    const keys = Object.keys(diagnostic).sort();
+    if (keys.length !== 2 || keys[0] !== 'code' || keys[1] !== 'count') {
+      throw diagnosticError();
+    }
+    if (!DIAGNOSTIC_CODE_SET.has(diagnostic.code)
+      || !Number.isSafeInteger(diagnostic.count)
+      || diagnostic.count <= 0) {
+      throw diagnosticError();
+    }
+    counts.set(diagnostic.code, (counts.get(diagnostic.code) || 0) + diagnostic.count);
+  }
+  return [...counts.entries()]
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([code, count]) => ({ code, count }));
+}
+
+export function normalizeObservabilityFrontier(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw frontierError();
+  const frontier = {};
+  for (const field of FRONTIER_STRING_FIELDS) {
+    const value = safeNonEmptyString(input[field]);
+    if (value === null) throw frontierError();
+    frontier[field] = value;
+  }
+  for (const field of FRONTIER_SEQUENCE_FIELDS) {
+    const value = safeSequence(input[field]);
+    if (value === null) throw frontierError();
+    frontier[field] = value;
+  }
+  return {
+    canonical_session_id: frontier.canonical_session_id,
+    activation_id: frontier.activation_id,
+    activation_epoch: frontier.activation_epoch,
+    turn_sequence: frontier.turn_sequence,
+    signal_sequence: frontier.signal_sequence,
+    roots_stat_hash: frontier.roots_stat_hash,
+    graph_cursor: frontier.graph_cursor,
+    source_manifest_hash: frontier.source_manifest_hash,
+  };
+}
+
+export const buildObservabilityFrontier = normalizeObservabilityFrontier;
+
+export function hashObservabilityFrontier(input) {
+  const frontier = normalizeObservabilityFrontier(input);
+  return createHash('sha256').update(JSON.stringify(frontier)).digest('hex');
+}
+
+/**
+ * Compare a candidate frontier with the checkpoint already materialized.
+ * The argument order is deliberately (current, candidate), matching a CAS writer.
+ */
+export function compareObservabilityFrontiers(currentInput, candidateInput) {
+  if (!currentInput) {
+    normalizeObservabilityFrontier(candidateInput);
+    return 'newer';
+  }
+  const current = normalizeObservabilityFrontier(currentInput);
+  const candidate = normalizeObservabilityFrontier(candidateInput);
+  if (current.canonical_session_id !== candidate.canonical_session_id) return 'conflict';
+
+  for (const field of FRONTIER_SEQUENCE_FIELDS) {
+    if (candidate[field] < current[field]) return 'stale';
+    if (candidate[field] > current[field]) return 'newer';
+    if (field === 'activation_epoch' && candidate.activation_id !== current.activation_id) {
+      return 'conflict';
+    }
+  }
+
+  for (const field of ['roots_stat_hash', 'graph_cursor', 'source_manifest_hash']) {
+    if (candidate[field] !== current[field]) return 'conflict';
+  }
+  return 'same';
+}
+
+export const compareObservabilityFrontier = compareObservabilityFrontiers;
+
+function unquoteFrontmatterValue(raw) {
+  const value = String(raw ?? '').trim();
+  if (value.length >= 2 && value.startsWith("'") && value.endsWith("'")) {
+    return value.slice(1, -1).replaceAll("''", "'");
+  }
+  if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
+    try { return JSON.parse(value); } catch { return value.slice(1, -1); }
+  }
+  return value;
+}
+
+function checkpointFields(input) {
+  if (typeof input !== 'string') return input;
+  const normalized = input.replaceAll('\r\n', '\n');
+  const frontmatter = normalized.match(/^---\n([\s\S]*?)\n---(?:\n|$)/)?.[1] ?? normalized;
+  const fields = {};
+  for (const line of frontmatter.split('\n')) {
+    const match = line.match(/^([A-Za-z0-9_]+):\s*(.*)$/);
+    if (match) fields[match[1]] = unquoteFrontmatterValue(match[2]);
+  }
+  return fields;
+}
+
+export function renderObservabilityCheckpoint(frontierInput, {
+  state,
+  diagnostics = [],
+} = {}) {
+  const frontier = normalizeObservabilityFrontier(frontierInput);
+  if (!OBSERVABILITY_STATES.has(state)) throw checkpointError();
+  const safeDiagnostics = sanitizeObservabilityDiagnostics(diagnostics);
+  return {
+    observability_schema: OBSERVABILITY_SCHEMA,
+    subagents_observability_state: state,
+    observability_session_id: frontier.canonical_session_id,
+    observability_activation_id: frontier.activation_id,
+    observability_activation_epoch: frontier.activation_epoch,
+    observability_turn_sequence: frontier.turn_sequence,
+    observability_signal_sequence: frontier.signal_sequence,
+    observability_roots_stat_hash: frontier.roots_stat_hash,
+    observability_graph_cursor: frontier.graph_cursor,
+    observability_source_manifest_hash: frontier.source_manifest_hash,
+    subagents_diagnostics_json: JSON.stringify(safeDiagnostics),
+  };
+}
+
+function quoteFrontmatter(value) {
+  if (typeof value === 'number') return String(value);
+  return `'${String(value).replaceAll("'", "''")}'`;
+}
+
+export function renderObservabilityCheckpointLines(frontierInput, options = {}) {
+  const fields = renderObservabilityCheckpoint(frontierInput, options);
+  return Object.entries(fields).map(([key, value]) => `${key}: ${quoteFrontmatter(value)}`).join('\n');
+}
+
+export function parseObservabilityCheckpoint(input) {
+  const fields = checkpointFields(input);
+  if (!fields || typeof fields !== 'object') return null;
+  if (safeSequence(fields.observability_schema) !== OBSERVABILITY_SCHEMA) return null;
+  if (!OBSERVABILITY_STATES.has(fields.subagents_observability_state)) return null;
+  try {
+    const source = {};
+    for (const [field, frontmatterKey] of Object.entries(FRONTMATTER_TO_FRONTIER)) {
+      source[field] = unquoteFrontmatterValue(fields[frontmatterKey]);
+    }
+    const frontier = normalizeObservabilityFrontier(source);
+    const diagnosticsRaw = unquoteFrontmatterValue(fields.subagents_diagnostics_json ?? '[]');
+    const diagnostics = sanitizeObservabilityDiagnostics(JSON.parse(diagnosticsRaw));
+    return {
+      schema: OBSERVABILITY_SCHEMA,
+      state: fields.subagents_observability_state,
+      frontier,
+      diagnostics,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export const readObservabilityCheckpoint = parseObservabilityCheckpoint;

package/hooks/session-observability-store.mjs

@@ -0,0 +1,436 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  VAULT_LOCK_BUSY,
+  assertVaultPathSafe,
+  mkdirVaultPath,
+  withVaultPathLock,
+  writeVaultFileAtomic,
+} from './vault-path-safety.mjs';
+import { sanitizeObservabilityDiagnostics } from './session-observability-state.mjs';
+
+const STORE_SCHEMA_VERSION = 1;
+const STORE_DIR_PARTS = ['.brain', 'runtime', 'session-observability'];
+const STORE_PATH_CODE = 'OBSERVABILITY_STORE_PATH_UNSAFE';
+const DEFAULT_SIGNAL_LIMIT = 4_096;
+const SIGNAL_KINDS = new Set(['started', 'interacted', 'interrupted']);
+
+function storeError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function nonEmptyString(value, code = 'OBSERVABILITY_STORE_INVALID') {
+  if (typeof value !== 'string' || !value.trim()) {
+    throw storeError(code, 'identificador de observabilidade inválido');
+  }
+  return value.trim();
+}
+
+function sequence(value, fallback = null) {
+  if (typeof value === 'string' && /^\d+$/.test(value.trim())) value = Number(value);
+  return Number.isSafeInteger(value) && value >= 0 ? value : fallback;
+}
+
+function timeValue(value, fallback) {
+  return Number.isFinite(value) && value >= 0 ? value : fallback;
+}
+
+function jsonClone(value) {
+  if (value === undefined) return null;
+  try { return JSON.parse(JSON.stringify(value)); }
+  catch { throw storeError('OBSERVABILITY_STORE_INVALID', 'estado de observabilidade inválido'); }
+}
+
+function defaultState(sessionId, {
+  reconstructed = false,
+  dirty = false,
+  diagnostics = [],
+} = {}) {
+  return {
+    schema_version: STORE_SCHEMA_VERSION,
+    session_id: sessionId,
+    observability_signal_sequence: 0,
+    observability_checkpoint_sequence: 0,
+    observability_dirty: dirty,
+    signals: [],
+    lease: null,
+    checkpoint_frontier: null,
+    source_manifest: null,
+    graph_cache: null,
+    diagnostics: sanitizeObservabilityDiagnostics(diagnostics),
+    reconstructed,
+  };
+}
+
+function normalizeSignal(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw storeError('OBSERVABILITY_SIGNAL_INVALID', 'sinal de observabilidade inválido');
+  }
+  const rolloutId = nonEmptyString(
+    input.rollout_id ?? input.rolloutId ?? input.agent_thread_id ?? input.agentThreadId,
+    'OBSERVABILITY_SIGNAL_INVALID',
+  );
+  const signal = { rollout_id: rolloutId };
+  const transcriptPath = input.transcript_path ?? input.transcriptPath;
+  if (typeof transcriptPath === 'string' && transcriptPath.trim()) {
+    signal.transcript_path = transcriptPath.trim();
+  }
+  const parentThreadId = input.parent_thread_id
+    ?? input.parentThreadId
+    ?? input.parent_rollout_id
+    ?? input.parentRolloutId;
+  if (typeof parentThreadId === 'string' && parentThreadId.trim()) {
+    signal.parent_thread_id = parentThreadId.trim();
+  }
+  const rawKind = input.kind ?? input.event_kind ?? input.eventKind ?? 'started';
+  if (typeof rawKind !== 'string' || !SIGNAL_KINDS.has(rawKind.trim().toLowerCase())) {
+    throw storeError('OBSERVABILITY_SIGNAL_INVALID', 'sinal de observabilidade inválido');
+  }
+  signal.kind = rawKind.trim().toLowerCase();
+  const timestamp = input.timestamp ?? input.started_at ?? input.startedAt;
+  if (typeof timestamp === 'string' && timestamp.trim()) {
+    signal.timestamp = timestamp.trim();
+  }
+  const agentPath = input.agent_path ?? input.agentPath;
+  if (typeof agentPath === 'string' && agentPath.trim()) {
+    signal.agent_path = agentPath.trim();
+  }
+  const activationId = input.activation_id ?? input.activationId;
+  if (typeof activationId === 'string' && activationId.trim()) {
+    signal.activation_id = activationId.trim();
+  }
+  for (const [target, source] of [
+    ['activation_epoch', input.activation_epoch ?? input.activationEpoch],
+    ['turn_sequence', input.turn_sequence ?? input.turnSequence],
+    ['signal_sequence', input.signal_sequence ?? input.signalSequence],
+  ]) {
+    if (source !== undefined) {
+      const normalized = sequence(source);
+      if (normalized === null) {
+        throw storeError('OBSERVABILITY_SIGNAL_INVALID', 'sinal de observabilidade inválido');
+      }
+      signal[target] = normalized;
+    }
+  }
+  if (typeof input.observed_at === 'string' && input.observed_at.trim()) {
+    signal.observed_at = input.observed_at.trim();
+  }
+  return signal;
+}
+
+function normalizeLease(input) {
+  if (input == null) return null;
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw storeError('OBSERVABILITY_STORE_CORRUPT', 'lease de observabilidade corrompida');
+  }
+  const signalSequence = sequence(input.signal_sequence);
+  const expiresAt = timeValue(input.expires_at, null);
+  if (signalSequence === null || expiresAt === null) {
+    throw storeError('OBSERVABILITY_STORE_CORRUPT', 'lease de observabilidade corrompida');
+  }
+  return {
+    owner_token: nonEmptyString(input.owner_token, 'OBSERVABILITY_STORE_CORRUPT'),
+    signal_sequence: signalSequence,
+    acquired_at: timeValue(input.acquired_at, expiresAt),
+    expires_at: expiresAt,
+  };
+}
+
+function normalizeStoreState(input, sessionId) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)
+    || input.schema_version !== STORE_SCHEMA_VERSION
+    || input.session_id !== sessionId) {
+    throw storeError('OBSERVABILITY_STORE_CORRUPT', 'store de observabilidade corrompido');
+  }
+  const signalSequence = sequence(input.observability_signal_sequence);
+  const checkpointSequence = sequence(input.observability_checkpoint_sequence);
+  if (signalSequence === null || checkpointSequence === null
+    || checkpointSequence > signalSequence
+    || typeof input.observability_dirty !== 'boolean'
+    || !Array.isArray(input.signals)) {
+    throw storeError('OBSERVABILITY_STORE_CORRUPT', 'store de observabilidade corrompido');
+  }
+  const seen = new Set();
+  const signals = input.signals.map(normalizeSignal);
+  let previousSignalSequence = 0;
+  for (const signal of signals) {
+    if (seen.has(signal.rollout_id)
+      || !Number.isSafeInteger(signal.signal_sequence)
+      || signal.signal_sequence <= previousSignalSequence
+      || signal.signal_sequence > signalSequence) {
+      throw storeError('OBSERVABILITY_STORE_CORRUPT', 'store de observabilidade corrompido');
+    }
+    seen.add(signal.rollout_id);
+    previousSignalSequence = signal.signal_sequence;
+  }
+  return {
+    schema_version: STORE_SCHEMA_VERSION,
+    session_id: sessionId,
+    observability_signal_sequence: signalSequence,
+    observability_checkpoint_sequence: checkpointSequence,
+    observability_dirty: input.observability_dirty,
+    signals,
+    lease: normalizeLease(input.lease),
+    checkpoint_frontier: jsonClone(input.checkpoint_frontier),
+    source_manifest: jsonClone(input.source_manifest),
+    graph_cache: jsonClone(input.graph_cache),
+    diagnostics: sanitizeObservabilityDiagnostics(input.diagnostics ?? []),
+    reconstructed: Boolean(input.reconstructed),
+  };
+}
+
+function serializableState(input) {
+  return {
+    schema_version: input.schema_version,
+    session_id: input.session_id,
+    observability_signal_sequence: input.observability_signal_sequence,
+    observability_checkpoint_sequence: input.observability_checkpoint_sequence,
+    observability_dirty: input.observability_dirty,
+    signals: input.signals,
+    lease: input.lease,
+    checkpoint_frontier: input.checkpoint_frontier,
+    source_manifest: input.source_manifest,
+    graph_cache: input.graph_cache,
+    diagnostics: input.diagnostics,
+  };
+}
+
+function serialized(input) {
+  return `${JSON.stringify(serializableState(input), null, 2)}\n`;
+}
+
+function storeDirectory(vaultBase) {
+  return join(vaultBase, ...STORE_DIR_PARTS);
+}
+
+function ensureStoreDirectory(vaultBase) {
+  return mkdirVaultPath(vaultBase, storeDirectory(vaultBase), {
+    recursive: true,
+    label: 'runtime de observabilidade de sessão',
+    code: STORE_PATH_CODE,
+  });
+}
+
+export function observabilityStorePath(vaultBase, sessionId) {
+  const id = nonEmptyString(sessionId);
+  const digest = createHash('sha256').update(id).digest('hex');
+  return join(vaultBase, ...STORE_DIR_PARTS, `${digest}.json`);
+}
+
+function readStorePath(vaultBase, sessionId, path) {
+  const checked = assertVaultPathSafe(vaultBase, path, {
+    expectedType: 'file',
+    label: 'store de observabilidade de sessão',
+    code: STORE_PATH_CODE,
+  });
+  if (!checked.exists) return defaultState(sessionId);
+  try {
+    const raw = readFileSync(checked.target, 'utf8');
+    assertVaultPathSafe(vaultBase, checked.target, {
+      allowMissing: false,
+      expectedType: 'file',
+      label: 'store de observabilidade de sessão',
+      code: STORE_PATH_CODE,
+    });
+    return normalizeStoreState(JSON.parse(raw), sessionId);
+  } catch (error) {
+    if (error?.code === STORE_PATH_CODE) throw error;
+    return defaultState(sessionId, {
+      reconstructed: true,
+      dirty: true,
+      diagnostics: [{ code: 'CACHE_INVALID', count: 1 }],
+    });
+  }
+}
+
+export function readObservabilityStore(vaultBase, sessionId) {
+  const id = nonEmptyString(sessionId);
+  return readStorePath(vaultBase, id, observabilityStorePath(vaultBase, id));
+}
+
+/**
+ * Serialize a small store transition under the hardened Vault path lock.
+ * The mutator may return `{ state, value }`; its `value` is returned without persistence.
+ */
+export function mutateObservabilityStore(vaultBase, sessionId, mutator, {
+  lockTimeoutMs = 2_000,
+  lockStaleMs = 10_000,
+} = {}) {
+  const id = nonEmptyString(sessionId);
+  if (typeof mutator !== 'function') {
+    throw storeError('OBSERVABILITY_STORE_INVALID', 'mutator de observabilidade inválido');
+  }
+  ensureStoreDirectory(vaultBase);
+  const path = observabilityStorePath(vaultBase, id);
+  const outcome = withVaultPathLock(vaultBase, path, () => {
+    const current = readStorePath(vaultBase, id, path);
+    const transition = mutator(jsonClone(current));
+    if (transition == null) {
+      return { state: current, changed: false, value: null, reconstructed: current.reconstructed };
+    }
+    const nextInput = Object.hasOwn(transition, 'state') ? transition.state : transition;
+    const value = Object.hasOwn(transition, 'state') ? transition.value : null;
+    const next = normalizeStoreState({
+      ...nextInput,
+      schema_version: STORE_SCHEMA_VERSION,
+      session_id: id,
+    }, id);
+    next.reconstructed = false;
+    const before = serialized(current);
+    const after = serialized(next);
+    if (before !== after || current.reconstructed) {
+      writeVaultFileAtomic(vaultBase, path, after, 'utf8', {
+        label: 'store de observabilidade de sessão',
+        code: STORE_PATH_CODE,
+      });
+    }
+    return {
+      state: next,
+      changed: before !== after || current.reconstructed,
+      value,
+      reconstructed: current.reconstructed,
+    };
+  }, {
+    timeoutMs: lockTimeoutMs,
+    staleMs: lockStaleMs,
+    code: STORE_PATH_CODE,
+  });
+  if (outcome === VAULT_LOCK_BUSY) {
+    return { state: null, changed: false, value: null, busy: true, reconstructed: false };
+  }
+  return { ...outcome, busy: false };
+}
+
+export function recordObservabilitySignal(vaultBase, sessionId, signalInput, {
+  maxSignals = DEFAULT_SIGNAL_LIMIT,
+  ...storeOptions
+} = {}) {
+  const signal = normalizeSignal(signalInput);
+  if (!Number.isSafeInteger(maxSignals) || maxSignals <= 0) {
+    throw storeError('OBSERVABILITY_STORE_INVALID', 'limite de sinais inválido');
+  }
+  const outcome = mutateObservabilityStore(vaultBase, sessionId, (state) => {
+    const duplicate = state.signals.some((entry) => entry.rollout_id === signal.rollout_id);
+    if (duplicate) return { state, value: { duplicate: true } };
+    const nextSequence = state.observability_signal_sequence + 1;
+    state.observability_signal_sequence = nextSequence;
+    state.observability_dirty = true;
+    state.signals = [...state.signals, { ...signal, signal_sequence: nextSequence }]
+      .slice(-maxSignals);
+    return { state, value: { duplicate: false } };
+  }, storeOptions);
+  if (outcome.busy) {
+    return { recorded: false, duplicate: false, sequence: null, state: null, reason: 'store-busy' };
+  }
+  return {
+    recorded: !outcome.value.duplicate,
+    duplicate: outcome.value.duplicate,
+    sequence: outcome.state.observability_signal_sequence,
+    state: outcome.state,
+    reason: outcome.value.duplicate ? 'duplicate' : 'recorded',
+  };
+}
+
+export function tryAcquireObservabilityLease(vaultBase, sessionId, {
+  signalSequence,
+  ownerToken = randomUUID(),
+  now = Date.now(),
+  ttlMs = 20_000,
+  ...storeOptions
+} = {}) {
+  const requestedSequence = sequence(signalSequence);
+  const token = nonEmptyString(ownerToken, 'OBSERVABILITY_LEASE_INVALID');
+  const nowMs = timeValue(now, null);
+  if (requestedSequence === null || nowMs === null || !Number.isFinite(ttlMs) || ttlMs <= 0) {
+    throw storeError('OBSERVABILITY_LEASE_INVALID', 'lease de observabilidade inválida');
+  }
+  const outcome = mutateObservabilityStore(vaultBase, sessionId, (state) => {
+    const latest = state.observability_signal_sequence;
+    if (requestedSequence < latest) {
+      return { state, value: { acquired: false, reason: 'stale-signal' } };
+    }
+    if (requestedSequence > latest) {
+      return { state, value: { acquired: false, reason: 'future-signal' } };
+    }
+    const lease = state.lease;
+    if (lease && lease.expires_at > nowMs
+      && lease.signal_sequence === requestedSequence
+      && lease.owner_token !== token) {
+      return { state, value: { acquired: false, reason: 'lease-busy' } };
+    }
+    if (lease && lease.expires_at > nowMs
+      && lease.signal_sequence === requestedSequence
+      && lease.owner_token === token) {
+      return { state, value: { acquired: true, reason: 'already-owned' } };
+    }
+    state.lease = {
+      owner_token: token,
+      signal_sequence: requestedSequence,
+      acquired_at: nowMs,
+      expires_at: nowMs + ttlMs,
+    };
+    return { state, value: { acquired: true, reason: lease ? 'superseded' : 'acquired' } };
+  }, storeOptions);
+  if (outcome.busy) {
+    return { acquired: false, reason: 'store-busy', state: null, ownerToken: token };
+  }
+  return { ...outcome.value, state: outcome.state, ownerToken: token };
+}
+
+export function releaseObservabilityLease(vaultBase, sessionId, {
+  ownerToken,
+  signalSequence,
+  ...storeOptions
+} = {}) {
+  const token = nonEmptyString(ownerToken, 'OBSERVABILITY_LEASE_INVALID');
+  const expectedSequence = signalSequence === undefined ? null : sequence(signalSequence);
+  if (signalSequence !== undefined && expectedSequence === null) {
+    throw storeError('OBSERVABILITY_LEASE_INVALID', 'lease de observabilidade inválida');
+  }
+  const outcome = mutateObservabilityStore(vaultBase, sessionId, (state) => {
+    const owned = state.lease?.owner_token === token
+      && (expectedSequence === null || state.lease.signal_sequence === expectedSequence);
+    if (!owned) return { state, value: { released: false, reason: 'not-owner' } };
+    state.lease = null;
+    return { state, value: { released: true, reason: 'released' } };
+  }, storeOptions);
+  if (outcome.busy) return { released: false, reason: 'store-busy', state: null };
+  return { ...outcome.value, state: outcome.state };
+}
+
+export function markObservabilityCheckpoint(vaultBase, sessionId, {
+  checkpointSequence,
+  frontier = null,
+  sourceManifest,
+  graphCache,
+  diagnostics,
+  ...storeOptions
+} = {}) {
+  const nextCheckpoint = sequence(checkpointSequence);
+  if (nextCheckpoint === null) {
+    throw storeError('OBSERVABILITY_CHECKPOINT_INVALID', 'checkpoint de observabilidade inválido');
+  }
+  const outcome = mutateObservabilityStore(vaultBase, sessionId, (state) => {
+    if (nextCheckpoint > state.observability_signal_sequence) {
+      throw storeError('OBSERVABILITY_CHECKPOINT_INVALID', 'checkpoint de observabilidade inválido');
+    }
+    if (nextCheckpoint < state.observability_checkpoint_sequence) {
+      return { state, value: { accepted: false, reason: 'stale-checkpoint' } };
+    }
+    state.observability_checkpoint_sequence = nextCheckpoint;
+    state.observability_dirty = nextCheckpoint < state.observability_signal_sequence;
+    state.checkpoint_frontier = jsonClone(frontier);
+    if (sourceManifest !== undefined) state.source_manifest = jsonClone(sourceManifest);
+    if (graphCache !== undefined) state.graph_cache = jsonClone(graphCache);
+    if (diagnostics !== undefined) {
+      state.diagnostics = sanitizeObservabilityDiagnostics(diagnostics);
+    }
+    if (state.lease && state.lease.signal_sequence <= nextCheckpoint) state.lease = null;
+    return { state, value: { accepted: true, reason: 'checkpointed' } };
+  }, storeOptions);
+  if (outcome.busy) return null;
+  return outcome.state;
+}