@shadowforge0/aquifer-memory 1.6.0 → 1.8.0

package/core/scope-attribution.js

@@ -0,0 +1,279 @@
+'use strict';
+
+const path = require('node:path');
+
+const SLOT_ORDER = ['host', 'workspace', 'project', 'repo', 'session', 'task'];
+const PROMOTABLE_SLOT_IDS = new Set(['host', 'workspace', 'project', 'repo']);
+const GENERIC_KEYS = new Set([
+  '',
+  'default',
+  'global',
+  'main',
+  'na',
+  'n/a',
+  'none',
+  'null',
+  'unknown',
+  'unset',
+]);
+
+function normalizeText(value) {
+  if (value === undefined || value === null) return null;
+  const text = String(value).trim();
+  return text ? text : null;
+}
+
+function collapseWhitespace(value) {
+  const text = normalizeText(value);
+  return text ? text.replace(/\s+/g, ' ') : null;
+}
+
+function slugify(value) {
+  const text = normalizeText(value);
+  if (!text) return null;
+  const slug = text
+    .normalize('NFKD')
+    .replace(/[^\w\s:/.-]+/g, ' ')
+    .trim()
+    .replace(/\s+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '')
+    .toLowerCase();
+  return slug || null;
+}
+
+function isGenericKey(value) {
+  const key = slugify(value) || String(value || '').trim().toLowerCase();
+  return GENERIC_KEYS.has(key);
+}
+
+function toFactObject(value, aliases = []) {
+  if (value && typeof value === 'object' && !Array.isArray(value)) return value;
+  const text = normalizeText(value);
+  if (!text) return null;
+  const key = aliases[0] || 'value';
+  return { [key]: text };
+}
+
+function pickValue(fact, keys = []) {
+  if (!fact) return null;
+  for (const key of keys) {
+    const value = normalizeText(fact[key]);
+    if (value) return value;
+  }
+  return null;
+}
+
+function pickLabel(fact, fallback) {
+  return collapseWhitespace(pickValue(fact, ['label', 'title', 'name', 'displayName']) || fallback);
+}
+
+function normalizePrefixedScope(scopeKey, expectedPrefix) {
+  const raw = normalizeText(scopeKey);
+  if (!raw) return null;
+  const match = raw.match(/^([a-z_]+):(.*)$/i);
+  if (!match) return null;
+  const [, prefix, rest] = match;
+  if (prefix !== expectedPrefix) return null;
+  const body = normalizeText(rest);
+  if (!body) return null;
+  return `${expectedPrefix}:${body}`;
+}
+
+function normalizePathScope(prefix, rawPath) {
+  const value = normalizeText(rawPath);
+  if (!value) return null;
+  return `${prefix}:${path.resolve(value)}`;
+}
+
+function buildHostScope(rawFact) {
+  const fact = toFactObject(rawFact, ['host']);
+  if (!fact) return null;
+  const fromScopeKey = normalizePrefixedScope(pickValue(fact, ['scopeKey', 'scope_key']), 'host_runtime');
+  const key = fromScopeKey
+    || (() => {
+      const value = pickValue(fact, ['key', 'id', 'host', 'runtime', 'source', 'name', 'label']);
+      if (!value || isGenericKey(value)) return null;
+      const slug = slugify(value);
+      return slug ? `host_runtime:${slug}` : null;
+    })();
+  if (!key) return null;
+  return {
+    id: 'host',
+    slot: 'host',
+    scopeKind: 'host_runtime',
+    scopeKey: key,
+    label: pickLabel(fact, key.slice('host_runtime:'.length)),
+    raw: fact,
+  };
+}
+
+function buildWorkspaceScope(rawFact) {
+  const fact = toFactObject(rawFact, ['path']);
+  if (!fact) return null;
+  const fromScopeKey = normalizePrefixedScope(pickValue(fact, ['scopeKey', 'scope_key']), 'workspace');
+  const key = fromScopeKey || normalizePathScope('workspace', pickValue(fact, ['path', 'workspacePath', 'root', 'id']));
+  if (!key) return null;
+  const scopePath = key.slice('workspace:'.length);
+  return {
+    id: 'workspace',
+    slot: 'workspace',
+    scopeKind: 'workspace',
+    scopeKey: key,
+    label: pickLabel(fact, scopePath),
+    raw: fact,
+  };
+}
+
+function buildProjectScope(rawFact) {
+  const fact = toFactObject(rawFact, ['key']);
+  if (!fact) return null;
+  const fromScopeKey = normalizePrefixedScope(pickValue(fact, ['scopeKey', 'scope_key']), 'project');
+  const key = fromScopeKey
+    || (() => {
+      const value = pickValue(fact, ['key', 'slug', 'projectKey', 'projectSlug', 'id', 'name', 'label']);
+      if (!value || isGenericKey(value)) return null;
+      const slug = slugify(value);
+      return slug ? `project:${slug}` : null;
+    })();
+  if (!key) return null;
+  return {
+    id: 'project',
+    slot: 'project',
+    scopeKind: 'project',
+    scopeKey: key,
+    label: pickLabel(fact, key.slice('project:'.length)),
+    raw: fact,
+  };
+}
+
+function buildRepoScope(rawFact) {
+  const fact = toFactObject(rawFact, ['path']);
+  if (!fact) return null;
+  const fromScopeKey = normalizePrefixedScope(pickValue(fact, ['scopeKey', 'scope_key']), 'repo');
+  const key = fromScopeKey || normalizePathScope('repo', pickValue(fact, ['path', 'repoPath', 'root', 'repoRoot']));
+  if (!key) return null;
+  const repoPath = key.slice('repo:'.length);
+  return {
+    id: 'repo',
+    slot: 'repo',
+    scopeKind: 'repo',
+    scopeKey: key,
+    label: pickLabel(fact, path.basename(repoPath) || repoPath),
+    raw: fact,
+  };
+}
+
+function buildSessionScope(rawFact) {
+  const fact = toFactObject(rawFact, ['id']);
+  if (!fact) return null;
+  const fromScopeKey = normalizePrefixedScope(pickValue(fact, ['scopeKey', 'scope_key']), 'session');
+  const key = fromScopeKey
+    || (() => {
+      const value = pickValue(fact, ['id', 'key', 'sessionId', 'sessionKey']);
+      return value ? `session:${value}` : null;
+    })();
+  if (!key) return null;
+  return {
+    id: 'session',
+    slot: 'session',
+    scopeKind: 'session',
+    scopeKey: key,
+    label: pickLabel(fact, key.slice('session:'.length)),
+    raw: fact,
+  };
+}
+
+function buildTaskScope(rawFact) {
+  const fact = toFactObject(rawFact, ['id']);
+  if (!fact) return null;
+  const fromScopeKey = normalizePrefixedScope(pickValue(fact, ['scopeKey', 'scope_key']), 'task');
+  const key = fromScopeKey
+    || (() => {
+      const value = pickValue(fact, ['id', 'key', 'taskId', 'taskKey']);
+      return value ? `task:${value}` : null;
+    })();
+  if (!key) return null;
+  return {
+    id: 'task',
+    slot: 'task',
+    scopeKind: 'task',
+    scopeKey: key,
+    label: pickLabel(fact, key.slice('task:'.length)),
+    raw: fact,
+  };
+}
+
+function buildScopeForSlot(slotId, input) {
+  switch (slotId) {
+    case 'host':
+      return buildHostScope(input.host || input.hostRuntime || input.source);
+    case 'workspace':
+      return buildWorkspaceScope(input.workspace || input.workspacePath);
+    case 'project':
+      return buildProjectScope(input.project || input.projectKey || input.projectSlug);
+    case 'repo':
+      return buildRepoScope(input.repo || input.repoPath);
+    case 'session':
+      return buildSessionScope(input.session || input.sessionId || input.sessionKey);
+    case 'task':
+      return buildTaskScope(input.task || input.taskId || input.taskKey);
+    default:
+      return null;
+  }
+}
+
+function allowedScopeKeysForSlots(scopes) {
+  const seen = new Set(['global']);
+  const active = ['global'];
+  return scopes.map((scope) => {
+    if (PROMOTABLE_SLOT_IDS.has(scope.id) && !seen.has(scope.scopeKey)) {
+      seen.add(scope.scopeKey);
+      active.push(scope.scopeKey);
+    }
+    return active.slice();
+  });
+}
+
+function buildScopeEnvelope(input = {}) {
+  const scopes = [];
+  const seenIds = new Set();
+
+  for (const slotId of SLOT_ORDER) {
+    const scope = buildScopeForSlot(slotId, input);
+    if (!scope || seenIds.has(scope.id)) continue;
+    seenIds.add(scope.id);
+    scopes.push(scope);
+  }
+
+  const slotAllowedScopeKeys = allowedScopeKeysForSlots(scopes);
+  const allowedScopeKeys = slotAllowedScopeKeys[slotAllowedScopeKeys.length - 1] || ['global'];
+  const promotableScopes = scopes.filter(scope => PROMOTABLE_SLOT_IDS.has(scope.id));
+  const activeScope = promotableScopes[promotableScopes.length - 1] || null;
+  const slots = scopes.map((scope, index) => ({
+    ...scope,
+    promotable: PROMOTABLE_SLOT_IDS.has(scope.id),
+    allowedScopeKeys: slotAllowedScopeKeys[index],
+  }));
+  const scopeById = Object.fromEntries(slots.map(scope => [scope.id, scope]));
+
+  return {
+    policyVersion: 'scope_envelope_v1',
+    activeSlotId: activeScope ? activeScope.id : 'global',
+    activeScopeKey: activeScope ? activeScope.scopeKey : 'global',
+    allowedScopeKeys,
+    slots,
+    scopeById,
+  };
+}
+
+function getScopeByEnvelopeId(envelope, id) {
+  const scope = envelope && envelope.scopeById ? envelope.scopeById[id] : null;
+  if (!scope) throw new Error(`Unknown scope envelope id: ${id}`);
+  return scope;
+}
+
+module.exports = {
+  buildScopeEnvelope,
+  getScopeByEnvelopeId,
+};

package/core/session-checkpoint-producer.js

@@ -0,0 +1,412 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const { sanitizeSummaryResult } = require('./memory-safety-gate');
+const { buildScopeEnvelope, getScopeByEnvelopeId } = require('./scope-attribution');
+
+const DEFAULT_POLICY_VERSION = 'session_checkpoint_producer_v1';
+const DEFAULT_COVERAGE_COORDINATE_SYSTEM = 'codex_sanitized_view_v1';
+const STRUCTURED_SUMMARY_SHAPE = '{"summaryText":"...","structuredSummary":{"facts":[],"decisions":[],"open_loops":[],"preferences":[],"constraints":[],"conclusions":[],"entity_notes":[],"states":[]},"coverage":{"coordinateSystem":"codex_sanitized_view_v1","coveredUntilMessageIndex":0,"coveredUntilChar":0}}';
+
+function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map(k => `${JSON.stringify(k)}:${stableJson(value[k])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function hashSnapshot(value) {
+  return crypto.createHash('sha256').update(stableJson(value)).digest('hex');
+}
+
+function optionalNonNegativeInteger(value) {
+  if (value === undefined || value === null || value === '') return null;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 0) return null;
+  return n;
+}
+
+function requiredPositiveInteger(value, field) {
+  const n = Number(value);
+  if (!Number.isSafeInteger(n) || n <= 0) {
+    throw new Error(`${field} must be a positive integer`);
+  }
+  return n;
+}
+
+function normalizeFinalizationRange(input = {}) {
+  const from = Number(input.fromFinalizationIdExclusive ?? input.from_finalization_id_exclusive ?? 0);
+  const to = Number(input.toFinalizationIdInclusive ?? input.to_finalization_id_inclusive);
+  if (!Number.isSafeInteger(from) || from < 0) {
+    throw new Error('fromFinalizationIdExclusive must be a non-negative integer');
+  }
+  if (!Number.isSafeInteger(to) || to <= from) {
+    throw new Error('toFinalizationIdInclusive must be greater than fromFinalizationIdExclusive');
+  }
+  return {
+    fromFinalizationIdExclusive: from,
+    toFinalizationIdInclusive: to,
+  };
+}
+
+function assertOkTranscriptView(view = {}) {
+  if (!view || view.status !== 'ok') {
+    throw new Error(`checkpoint synthesis requires an ok transcript view; got ${view && view.status ? view.status : 'missing'}`);
+  }
+  if (typeof view.text !== 'string') {
+    throw new Error('checkpoint synthesis requires view.text');
+  }
+}
+
+function normalizeCoverageNumber(...values) {
+  for (const value of values) {
+    const n = optionalNonNegativeInteger(value);
+    if (n !== null) return n;
+  }
+  return null;
+}
+
+function buildCheckpointCoverageFromView(view = {}, opts = {}) {
+  assertOkTranscriptView(view);
+  const explicit = opts.coverage && typeof opts.coverage === 'object'
+    ? opts.coverage
+    : (view.coverage && typeof view.coverage === 'object' ? view.coverage : {});
+  const transcript = explicit.transcript && typeof explicit.transcript === 'object' ? explicit.transcript : {};
+  const messageCount = Number.isFinite(Number(view.counts?.safeMessageCount))
+    ? Number(view.counts.safeMessageCount)
+    : (Array.isArray(view.messages) ? view.messages.length : 0);
+  const text = typeof view.text === 'string' ? view.text : '';
+  const fullCharCount = Number.isFinite(Number(view.fullCharCount ?? view.counts?.fullCharCount))
+    ? Number(view.fullCharCount ?? view.counts.fullCharCount)
+    : text.length;
+  const coveredUntilMessageIndex = normalizeCoverageNumber(
+    opts.coveredUntilMessageIndex,
+    explicit.coveredUntilMessageIndex,
+    explicit.covered_until_message_index,
+    explicit.messageIndex,
+    explicit.message_index,
+    transcript.coveredUntilMessageIndex,
+    transcript.covered_until_message_index
+  );
+  const coveredUntilChar = normalizeCoverageNumber(
+    opts.coveredUntilChar,
+    opts.coveredUntilCharIndex,
+    explicit.coveredUntilChar,
+    explicit.coveredUntilCharIndex,
+    explicit.covered_until_char,
+    explicit.covered_until_char_index,
+    transcript.coveredUntilChar,
+    transcript.covered_until_char
+  );
+  const coveredUntilLine = normalizeCoverageNumber(
+    opts.coveredUntilLine,
+    explicit.coveredUntilLine,
+    explicit.coveredUntilLineIndex,
+    explicit.covered_until_line,
+    explicit.covered_until_line_index,
+    transcript.coveredUntilLine,
+    transcript.covered_until_line
+  );
+  const coveredUntilLineChar = normalizeCoverageNumber(
+    opts.coveredUntilLineChar,
+    explicit.coveredUntilLineChar,
+    explicit.coveredUntilLineCharIndex,
+    explicit.covered_until_line_char,
+    explicit.covered_until_line_char_index,
+    transcript.coveredUntilLineChar,
+    transcript.covered_until_line_char
+  );
+  const coverage = {
+    coordinateSystem: explicit.coordinateSystem || explicit.coordinate_system || DEFAULT_COVERAGE_COORDINATE_SYSTEM,
+    messageIndexBase: 0,
+    charIndexBase: 0,
+    semantics: 'coveredUntilChar is the first uncovered zero-based char offset; messages up to coveredUntilMessageIndex are covered.',
+  };
+  if (coveredUntilMessageIndex !== null) coverage.coveredUntilMessageIndex = coveredUntilMessageIndex;
+  if (coveredUntilChar !== null) coverage.coveredUntilChar = coveredUntilChar;
+  if (coveredUntilLine !== null) coverage.coveredUntilLine = coveredUntilLine;
+  if (coveredUntilLineChar !== null) coverage.coveredUntilLineChar = coveredUntilLineChar;
+  if (coverage.coveredUntilMessageIndex === undefined && messageCount > 0) {
+    coverage.coveredUntilMessageIndex = messageCount - 1;
+  }
+  if (coverage.coveredUntilChar === undefined) coverage.coveredUntilChar = fullCharCount;
+  return coverage;
+}
+
+function compactText(value, maxChars = 360) {
+  const text = String(value || '').replace(/\s+/g, ' ').trim();
+  if (text.length <= maxChars) return text;
+  return `${text.slice(0, Math.max(0, maxChars - 1)).trim()}...`;
+}
+
+function compactCurrentMemoryRow(row = {}) {
+  const payload = row.payload && typeof row.payload === 'object' ? row.payload : {};
+  return {
+    memoryType: row.memoryType || row.memory_type || 'memory',
+    canonicalKey: row.canonicalKey || row.canonical_key || null,
+    scopeKey: row.scopeKey || row.scope_key || null,
+    summary: compactText(row.summary || row.title || '', 420),
+    authority: row.authority || null,
+    confidence: payload.confidence || payload.currentMemoryConfidence || null,
+  };
+}
+
+function compactCurrentMemory(currentMemory = null, opts = {}) {
+  const rows = Array.isArray(currentMemory?.memories)
+    ? currentMemory.memories
+    : (Array.isArray(currentMemory?.items) ? currentMemory.items : []);
+  const maxItems = Math.max(0, Math.min(20, opts.maxCurrentMemoryItems || opts.currentMemoryLimit || 12));
+  return rows
+    .map(compactCurrentMemoryRow)
+    .filter(row => row.summary)
+    .slice(0, maxItems);
+}
+
+function compactCheckpointRow(row = {}) {
+  const payload = row.payload && typeof row.payload === 'object' ? row.payload : {};
+  return {
+    checkpointKey: row.checkpointKey || row.checkpoint_key || null,
+    scopeKey: row.scopeKey || row.scope_key || null,
+    topicKey: row.topicKey || row.topic_key || payload.topicKey || null,
+    triggerKind: row.triggerKind || row.trigger_kind || payload.triggerKind || null,
+    summaryText: compactText(row.summaryText || row.summary_text || row.summary || payload.summaryText, 520),
+    coverage: row.coverage || payload.coverage || {},
+  };
+}
+
+function compactPreviousCheckpoints(checkpoints = [], opts = {}) {
+  const rows = Array.isArray(checkpoints?.checkpoints)
+    ? checkpoints.checkpoints
+    : (Array.isArray(checkpoints?.items) ? checkpoints.items : checkpoints);
+  const maxItems = Math.max(0, Math.min(12, opts.maxCheckpoints || opts.checkpointLimit || 6));
+  return (Array.isArray(rows) ? rows : [])
+    .map(compactCheckpointRow)
+    .filter(row => row.summaryText || Object.keys(row.coverage || {}).length > 0)
+    .slice(0, maxItems);
+}
+
+function normalizeScopeEnvelope(input = {}) {
+  const envelope = input.scopeEnvelope || input.scope_envelope || null;
+  if (envelope && typeof envelope === 'object') {
+    return {
+      ...envelope,
+      scopeById: envelope.scopeById || Object.fromEntries((envelope.slots || []).map(scope => [scope.id, scope])),
+    };
+  }
+  const scopeInput = input.scope && typeof input.scope === 'object' ? input.scope : input;
+  const built = buildScopeEnvelope(scopeInput);
+  if (built.activeScopeKey === 'global' && (!built.slots || built.slots.length === 0)) {
+    throw new Error('checkpoint synthesis requires a bounded scope envelope');
+  }
+  return built;
+}
+
+function normalizeTargetScope(envelope = {}, input = {}) {
+  const targetScopeEnvelopeId = input.targetScopeEnvelopeId
+    || input.target_scope_envelope_id
+    || input.targetScopeId
+    || input.target_scope_id
+    || envelope.activeSlotId;
+  const scope = getScopeByEnvelopeId(envelope, targetScopeEnvelopeId);
+  if (!scope.promotable) {
+    throw new Error(`checkpoint synthesis target scope is not promotable: ${targetScopeEnvelopeId}`);
+  }
+  if (!Array.isArray(envelope.allowedScopeKeys) || !envelope.allowedScopeKeys.includes(scope.scopeKey)) {
+    throw new Error(`checkpoint synthesis target scope is outside allowed envelope: ${scope.scopeKey}`);
+  }
+  return {
+    envelopeId: scope.id,
+    scopeKind: scope.scopeKind,
+    scopeKey: scope.scopeKey,
+    label: scope.label || null,
+  };
+}
+
+function buildCheckpointSynthesisInput(input = {}, opts = {}) {
+  const view = input.view || opts.view;
+  assertOkTranscriptView(view);
+  const range = normalizeFinalizationRange(input);
+  const scopeEnvelope = normalizeScopeEnvelope(input);
+  const targetScope = normalizeTargetScope(scopeEnvelope, input);
+  const coverage = buildCheckpointCoverageFromView(view, input);
+  const maxTranscriptChars = Math.max(1000, Math.min(120000, input.maxTranscriptChars || opts.maxTranscriptChars || 60000));
+  const transcriptText = view.text.length > maxTranscriptChars
+    ? view.text.slice(Math.max(0, view.text.length - maxTranscriptChars))
+    : view.text;
+  const base = {
+    kind: 'session_checkpoint_synthesis_input_v1',
+    policyVersion: input.policyVersion || opts.policyVersion || DEFAULT_POLICY_VERSION,
+    sourceOfTruth: input.sourceOfTruth || input.source_of_truth || opts.sourceOfTruth || 'sanitized_transcript_view',
+    triggerKind: input.triggerKind || input.trigger_kind || opts.triggerKind || 'manual',
+    promotion: {
+      default: 'checkpoint_proposal_only',
+      requires: 'operator_review_or_explicit_finalize',
+    },
+    guards: {
+      checkpointIsProcessMaterial: true,
+      rawToolOutputExcluded: true,
+      debugIdsExcluded: true,
+      activeMemoryCommitExcluded: true,
+    },
+    range,
+    coverage,
+    targetScope,
+    scopeEnvelope: {
+      policyVersion: scopeEnvelope.policyVersion || 'scope_envelope_v1',
+      activeSlotId: scopeEnvelope.activeSlotId,
+      activeScopeKey: scopeEnvelope.activeScopeKey,
+      allowedScopeKeys: scopeEnvelope.allowedScopeKeys || [],
+      slots: (scopeEnvelope.slots || []).map(scope => ({
+        id: scope.id,
+        slot: scope.slot,
+        scopeKind: scope.scopeKind,
+        scopeKey: scope.scopeKey,
+        label: scope.label || null,
+        promotable: Boolean(scope.promotable),
+        allowedScopeKeys: scope.allowedScopeKeys || [],
+      })),
+    },
+    transcript: {
+      sessionId: view.sessionId || null,
+      transcriptHash: view.transcriptHash || null,
+      charCount: view.charCount ?? view.text.length,
+      approxPromptTokens: view.approxPromptTokens || Math.ceil(view.text.length / 3),
+      truncated: transcriptText.length !== view.text.length,
+      text: transcriptText,
+    },
+    currentMemory: compactCurrentMemory(input.currentMemory || opts.currentMemory || null, input),
+    previousCheckpoints: compactPreviousCheckpoints(input.previousCheckpoints || input.checkpoints || opts.previousCheckpoints || [], input),
+    storage: {
+      scopeId: input.storageScopeId || input.storage_scope_id || input.scopeDbId || input.scope_db_id || null,
+    },
+  };
+  return {
+    ...base,
+    inputHash: hashSnapshot(base),
+  };
+}
+
+function promptSafeSynthesisInput(synthesisInput = {}) {
+  const transcript = synthesisInput.transcript && typeof synthesisInput.transcript === 'object'
+    ? {
+        ...synthesisInput.transcript,
+        transcriptHash: undefined,
+      }
+    : synthesisInput.transcript;
+  const out = {
+    ...synthesisInput,
+    inputHash: undefined,
+    storage: undefined,
+    transcript,
+  };
+  return JSON.parse(JSON.stringify(out));
+}
+
+function buildCheckpointSynthesisPrompt(synthesisInput = {}, opts = {}) {
+  if (!synthesisInput || synthesisInput.kind !== 'session_checkpoint_synthesis_input_v1') {
+    throw new Error('buildCheckpointSynthesisPrompt requires a checkpoint synthesis input');
+  }
+  const maxFacts = Math.max(1, Math.min(24, opts.maxFacts || 10));
+  const promptInput = promptSafeSynthesisInput(synthesisInput);
+  return [
+    'You are producing an Aquifer session checkpoint proposal.',
+    'Use only the <checkpoint_synthesis_input> block. Do not use hidden tool output, injected context, or debug material.',
+    'This checkpoint is producer process material, not active current memory and not final truth.',
+    'Choose scope only from scopeEnvelope.slots and keep every item inside targetScope unless the input proves a narrower allowed scope.',
+    'Do not include DB ids, raw hashes, secrets, raw tool output, or prompt/debug identifiers in memory candidates.',
+    'Return compact JSON with this shape:',
+    STRUCTURED_SUMMARY_SHAPE,
+    `Keep facts/decisions/open_loops concrete and scoped. Use at most ${maxFacts} facts.`,
+    'Preserve the coverage object so handoff can skip only the already-covered transcript range.',
+    '',
+    '<checkpoint_synthesis_input>',
+    stableJson(promptInput),
+    '</checkpoint_synthesis_input>',
+  ].join('\n');
+}
+
+function normalizeCheckpointSynthesisSummary(input = {}) {
+  const raw = input && typeof input === 'object'
+    ? {
+        summaryText: input.summaryText || input.summary || '',
+        structuredSummary: input.structuredSummary || input.structured_summary || {},
+      }
+    : {
+        summaryText: '',
+        structuredSummary: {},
+      };
+  const sanitized = sanitizeSummaryResult(raw);
+  const coverage = input && typeof input === 'object' && input.coverage && typeof input.coverage === 'object'
+    ? input.coverage
+    : null;
+  return {
+    summary: sanitized.summaryResult || raw,
+    coverage,
+    safetyGate: sanitized.meta || {},
+  };
+}
+
+function buildCheckpointRunInputFromSynthesis(synthesisInput = {}, synthesisSummary = {}, opts = {}) {
+  if (!synthesisInput || synthesisInput.kind !== 'session_checkpoint_synthesis_input_v1') {
+    throw new Error('checkpoint run input requires a checkpoint synthesis input');
+  }
+  const { summary, coverage, safetyGate } = normalizeCheckpointSynthesisSummary(synthesisSummary);
+  const summaryText = String(summary.summaryText || summary.summary || '').trim();
+  const structuredSummary = summary.structuredSummary || {};
+  if (!summaryText && Object.keys(structuredSummary).length === 0) {
+    throw new Error('checkpoint run input requires summaryText or structuredSummary');
+  }
+  const range = normalizeFinalizationRange(synthesisInput.range || {});
+  const scopeId = requiredPositiveInteger(
+    opts.storageScopeId || opts.scopeId || synthesisInput.storage?.scopeId,
+    'storageScopeId'
+  );
+  const status = opts.status || 'processing';
+  const targetScope = synthesisInput.targetScope || {};
+  const checkpointPayload = {
+    kind: 'session_checkpoint_proposal_v1',
+    policyVersion: synthesisInput.policyVersion || DEFAULT_POLICY_VERSION,
+    inputHash: synthesisInput.inputHash || hashSnapshot(synthesisInput),
+    promotionGate: 'operator_required',
+    checkpointRole: 'handoff_process_material',
+    triggerKind: synthesisInput.triggerKind || 'manual',
+    summaryText,
+    structuredSummary,
+    coverage: coverage || synthesisInput.coverage || {},
+    targetScope,
+    safetyGate,
+  };
+  return {
+    scopeId,
+    checkpointKey: opts.checkpointKey || undefined,
+    status,
+    fromFinalizationIdExclusive: range.fromFinalizationIdExclusive,
+    toFinalizationIdInclusive: range.toFinalizationIdInclusive,
+    scopeSnapshot: {
+      scopeKind: targetScope.scopeKind || null,
+      scopeKey: targetScope.scopeKey || null,
+      targetScopeEnvelopeId: targetScope.envelopeId || null,
+      policyVersion: synthesisInput.scopeEnvelope?.policyVersion || 'scope_envelope_v1',
+    },
+    checkpointText: summaryText || null,
+    checkpointPayload,
+    metadata: {
+      source: 'session_checkpoint_producer',
+      inputHash: checkpointPayload.inputHash,
+      triggerKind: checkpointPayload.triggerKind,
+      policyVersion: checkpointPayload.policyVersion,
+    },
+  };
+}
+
+module.exports = {
+  stableJson,
+  hashSnapshot,
+  buildCheckpointCoverageFromView,
+  buildCheckpointSynthesisInput,
+  buildCheckpointSynthesisPrompt,
+  promptSafeSynthesisInput,
+  normalizeCheckpointSynthesisSummary,
+  buildCheckpointRunInputFromSynthesis,
+};