@shadowforge0/aquifer-memory 1.6.0 → 1.8.0

package/core/mcp-manifest.js

@@ -18,9 +18,73 @@ const path = require('path');
 const MCP_SERVER_NAME = 'aquifer-memory';
 
 const MCP_TOOL_MANIFEST = Object.freeze([
+  {
+    name: 'memory_recall',
+    description: 'Explicit current-memory recall on the active curated memory corpus. Use this for current state and next-step lookup; use historical_recall for older session detail.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        query: { type: 'string', minLength: 1, description: 'Search query (keyword or natural language)' },
+        limit: { type: 'integer', minimum: 1, maximum: 20, description: 'Max results (default 5)' },
+        mode: {
+          type: 'string',
+          enum: ['fts', 'hybrid', 'vector'],
+          description: 'Recall mode: "fts" (keyword only), "hybrid" (default, FTS + vector), "vector" (vector only)',
+        },
+        explain: {
+          type: 'boolean',
+          description: 'Include per-result score breakdown (diagnostic use only).',
+        },
+        activeScopeKey: { type: 'string', description: 'Active curated memory scope key, e.g. project:aquifer' },
+        activeScopePath: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Ordered curated scope path from global to active scope',
+        },
+      },
+      required: ['query'],
+    },
+  },
+  {
+    name: 'historical_recall',
+    description: 'Explicit historical/session recall over stored sessions and summaries. Use this for timeline, detail, and session context lookup; use evidence_recall only for audit/debug/provenance.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        query: { type: 'string', minLength: 1, description: 'Search query (keyword or natural language)' },
+        limit: { type: 'integer', minimum: 1, maximum: 20, description: 'Max results (default 5)' },
+        agentId: { type: 'string', description: 'Filter by agent ID' },
+        source: { type: 'string', description: 'Filter by source (e.g., gateway, cc)' },
+        dateFrom: { type: 'string', description: 'Start date YYYY-MM-DD' },
+        dateTo: { type: 'string', description: 'End date YYYY-MM-DD' },
+        entities: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Entity names to match',
+        },
+        entityMode: {
+          type: 'string',
+          enum: ['any', 'all'],
+          description: '"any" (default, boost) or "all" (only sessions with every entity)',
+        },
+        mode: {
+          type: 'string',
+          enum: ['fts', 'hybrid', 'vector'],
+          description: 'Recall mode: "fts" (keyword only, no embed needed), "hybrid" (default, FTS + vector), "vector" (vector only)',
+        },
+        explain: {
+          type: 'boolean',
+          description: 'Include per-result score breakdown (rrf, timeDecay, entity, trust, rerank). Diagnostic use only.',
+        },
+      },
+      required: ['query'],
+    },
+  },
   {
     name: 'session_recall',
-    description: 'Search Aquifer memory. When memory serving mode is curated, this searches active curated memory only; use evidence_recall for legacy session/evidence lookup. Use entities/date filters where supported by the active serving mode.',
+    description: 'Compatibility recall surface. In curated serving mode this routes to current memory; in legacy serving mode it routes to historical/session recall. Prefer memory_recall for current state and historical_recall for timeline/detail lookup.',
     inputSchema: {
       type: 'object',
       additionalProperties: false,
@@ -115,7 +179,7 @@ const MCP_TOOL_MANIFEST = Object.freeze([
   },
   {
     name: 'memory_stats',
-    description: 'Return storage statistics for the Aquifer memory store (session counts by status, summaries, turn embeddings, entities, date range).',
+    description: 'Return storage statistics for the Aquifer memory store, serving mode, current-memory record coverage, and session date range.',
     inputSchema: {
       type: 'object',
       additionalProperties: false,

package/core/memory-bootstrap.js

@@ -2,10 +2,10 @@
 
 const TYPE_PRIORITY = {
   constraint: 0,
-  preference: 1,
-  state: 2,
-  open_loop: 3,
-  decision: 4,
+  state: 1,
+  open_loop: 2,
+  decision: 3,
+  preference: 4,
   fact: 5,
   conclusion: 6,
   entity_note: 7,
@@ -96,7 +96,13 @@ function resolveApplicableRecords(records = [], opts = {}) {
   return [...winners.values(), ...additive];
 }
 
-function sortForBootstrap(a, b) {
+function sortForBootstrap(a, b, opts = {}) {
+  const activeScopePath = opts.activeScopePath || (opts.activeScopeKey ? [opts.activeScopeKey] : ['global']);
+  const position = new Map(activeScopePath.map((key, idx) => [key, idx]));
+  const aScope = position.get(scopeKey(a)) ?? -1;
+  const bScope = position.get(scopeKey(b)) ?? -1;
+  if (bScope !== aScope) return bScope - aScope;
+
   const aType = TYPE_PRIORITY[a.memoryType || a.memory_type] ?? 99;
   const bType = TYPE_PRIORITY[b.memoryType || b.memory_type] ?? 99;
   if (aType !== bType) return aType - bType;
@@ -129,10 +135,11 @@ function buildText(records, meta) {
 
 function buildMemoryBootstrap(records = [], opts = {}) {
   const maxChars = Math.max(120, opts.maxChars || 4000);
+  const limit = Number.isFinite(opts.limit) ? Math.max(1, Math.min(100, Math.floor(opts.limit))) : null;
   const active = resolveApplicableRecords(
     records.filter(record => isActiveBootstrap(record, opts)),
     opts,
-  ).sort(sortForBootstrap);
+  ).sort((a, b) => sortForBootstrap(a, b, opts));
 
   const meta = {
     overflow: false,
@@ -141,7 +148,11 @@ function buildMemoryBootstrap(records = [], opts = {}) {
     count: active.length,
   };
 
-  let selected = active.slice();
+  let selected = limit ? active.slice(0, limit) : active.slice();
+  if (limit && active.length > limit) {
+    meta.overflow = true;
+    meta.degraded = true;
+  }
   let text = buildText(selected, meta);
   while (text.length > maxChars && selected.length > 1) {
     selected = selected.slice(0, -1);
@@ -167,13 +178,14 @@ function buildMemoryBootstrap(records = [], opts = {}) {
 
 function createMemoryBootstrap({ records }) {
   async function bootstrap(opts = {}) {
+    const requestedLimit = Number.isFinite(opts.limit) ? Math.max(1, Math.floor(opts.limit)) : 50;
     const rows = await records.listActive({
       tenantId: opts.tenantId,
       scopeId: opts.scopeId,
       scopeKeys: opts.activeScopePath || (opts.activeScopeKey ? [opts.activeScopeKey] : undefined),
       visibleInBootstrap: true,
       asOf: opts.asOf,
-      limit: opts.limit || 50,
+      limit: Math.max(50, Math.min(200, requestedLimit * 4)),
     });
     return buildMemoryBootstrap(rows, opts);
   }

package/core/memory-consolidation.js

@@ -3,6 +3,7 @@
 const crypto = require('crypto');
 const { extractCandidatesFromStructuredSummary, createMemoryPromotion } = require('./memory-promotion');
 const { createMemoryRecords } = require('./memory-records');
+const { sanitizeSummaryResult } = require('./memory-safety-gate');
 
 const ALLOWED_CADENCES = new Set(['session', 'daily', 'weekly', 'monthly', 'manual']);
 const OPERATOR_CADENCES = new Set(['manual', 'daily', 'weekly', 'monthly']);
@@ -296,6 +297,9 @@ function buildAggregateCandidates(normalized, statusUpdates, opts) {
       candidateHash,
       payload: {
         kind: 'compaction_rollup',
+        synthesisKind: 'timer_current_memory_synthesis_v1',
+        currentMemoryRole: `${cadence}_timer_synthesis_candidate`,
+        promotionGate: 'operator_required',
         cadence,
         policyVersion,
         periodStart: windowStart,
@@ -328,6 +332,326 @@ function buildAggregateCandidates(normalized, statusUpdates, opts) {
   return candidates;
 }
 
+function buildTimerSynthesisInput(normalized, statusUpdates, candidates, opts) {
+  const { cadence, periodStart, periodEnd } = opts;
+  if (!aggregateCandidateCadence(cadence)) return null;
+
+  const staleIds = new Set(statusUpdates.map(update => String(update.memoryId)));
+  const staleKeys = new Set(statusUpdates.map(update => String(update.canonicalKey || '')));
+  const sourceCurrentMemory = normalized
+    .filter(record => record.status === 'active')
+    .filter(record => record.id === null || !staleIds.has(String(record.id)))
+    .filter(record => !staleKeys.has(record.canonicalKey))
+    .filter(record => Boolean(record.canonicalKey))
+    .map(record => ({
+      memoryId: record.id,
+      memoryType: record.memoryType,
+      canonicalKey: record.canonicalKey,
+      scopeKind: record.scopeKind,
+      scopeKey: record.scopeKey,
+      contextKey: record.contextKey,
+      topicKey: record.topicKey,
+      summary: compactSummary(record),
+      acceptedAt: record.acceptedAt,
+      validFrom: record.validFrom,
+      validTo: record.validTo,
+      staleAfter: record.staleAfter,
+    }))
+    .sort((a, b) => {
+      if (a.canonicalKey !== b.canonicalKey) return a.canonicalKey.localeCompare(b.canonicalKey);
+      return String(a.memoryId).localeCompare(String(b.memoryId));
+    });
+
+  const windowStart = canonicalInstant(periodStart);
+  const windowEnd = canonicalInstant(periodEnd);
+  return {
+    kind: 'timer_current_memory_synthesis_v1',
+    sourceOfTruth: 'memory_records',
+    cadence,
+    policyVersion: opts.policyVersion || 'v1',
+    periodStart: windowStart,
+    periodEnd: windowEnd,
+    promotion: {
+      default: 'candidate_only',
+      requires: 'apply=true and promoteCandidates=true',
+    },
+    guards: {
+      rawTranscriptExcluded: true,
+      sessionSummariesExcluded: true,
+      nonActiveMemoryExcluded: true,
+      stalePlannedMemoryExcluded: true,
+    },
+    sourceCurrentMemory,
+    statusUpdates: statusUpdates
+      .map(update => ({
+        memoryId: update.memoryId,
+        canonicalKey: update.canonicalKey,
+        status: update.status,
+        reason: update.reason,
+      }))
+      .sort((a, b) => {
+        if (a.canonicalKey !== b.canonicalKey) return String(a.canonicalKey).localeCompare(String(b.canonicalKey));
+        return String(a.memoryId).localeCompare(String(b.memoryId));
+      }),
+    candidateProposals: candidates
+      .map(candidate => ({
+        candidateHash: candidate.candidateHash,
+        memoryType: candidate.memoryType,
+        canonicalKey: candidate.canonicalKey,
+        scopeKind: candidate.scopeKind,
+        scopeKey: candidate.scopeKey,
+        contextKey: candidate.contextKey,
+        topicKey: candidate.topicKey,
+        summary: compactSummary(candidate),
+        sourceMemoryIds: candidate.payload?.sourceMemoryIds || [],
+        sourceCanonicalKeys: candidate.payload?.sourceCanonicalKeys || [],
+      }))
+      .sort((a, b) => {
+        if (a.canonicalKey !== b.canonicalKey) return String(a.canonicalKey).localeCompare(String(b.canonicalKey));
+        return String(a.candidateHash).localeCompare(String(b.candidateHash));
+      }),
+  };
+}
+
+function buildTimerSynthesisPrompt(plan = {}, opts = {}) {
+  const synthesisInput = plan.synthesisInput || plan.meta?.synthesisInput || null;
+  if (!synthesisInput) {
+    throw new Error('memory.consolidation.timer_synthesis_prompt requires a timer synthesisInput');
+  }
+  const maxFacts = opts.maxFacts || 12;
+  return [
+    'You are producing an Aquifer timer current-memory synthesis proposal.',
+    'Use only the <timer_synthesis_input> block. Do not read raw transcripts, session summaries, tool output, or debug material.',
+    'This is a producer proposal, not an active memory commit. Promotion still requires the normal operator promotion gate.',
+    'Return compact JSON with this shape:',
+    '{"summaryText":"...","structuredSummary":{"facts":[],"decisions":[],"open_loops":[],"preferences":[],"constraints":[],"conclusions":[],"entity_notes":[],"states":[]}}',
+    `Keep facts/states/open_loops concrete and scoped. Use at most ${maxFacts} facts.`,
+    'Mark uncertain, resolved, superseded, revoked, or stale items explicitly in payload fields when applicable.',
+    'Do not copy sourceCurrentMemory unchanged unless the timer window confirms it still carries forward.',
+    '',
+    '<timer_synthesis_input>',
+    stableJson(synthesisInput),
+    '</timer_synthesis_input>',
+  ].join('\n');
+}
+
+function normalizeTimerSynthesisSummary(input = {}) {
+  const raw = input && typeof input === 'object'
+    ? {
+        summaryText: input.summaryText || input.summary || '',
+        structuredSummary: input.structuredSummary || input.structured_summary || {},
+      }
+    : {
+        summaryText: '',
+        structuredSummary: {},
+      };
+  const sanitized = sanitizeSummaryResult(raw);
+  return {
+    summary: sanitized.summaryResult || raw,
+    safetyGate: sanitized.meta || {},
+  };
+}
+
+function inferTimerSynthesisScope(synthesisInput = {}, opts = {}) {
+  if (opts.scopeKind && opts.scopeKey) {
+    return {
+      scopeKind: opts.scopeKind,
+      scopeKey: opts.scopeKey,
+      contextKey: opts.contextKey || null,
+      topicKey: opts.topicKey || null,
+    };
+  }
+  const scoped = new Map();
+  for (const row of synthesisInput.sourceCurrentMemory || []) {
+    const scopeKind = row.scopeKind || 'unspecified';
+    const scopeKey = row.scopeKey || 'unspecified';
+    const contextKey = row.contextKey || null;
+    const topicKey = row.topicKey || null;
+    scoped.set(stableJson({ scopeKind, scopeKey, contextKey, topicKey }), {
+      scopeKind,
+      scopeKey,
+      contextKey,
+      topicKey,
+    });
+  }
+  if (scoped.size === 1) return [...scoped.values()][0];
+  if (scoped.size === 0 && opts.activeScopeKey) {
+    return {
+      scopeKind: opts.activeScopeKind || 'project',
+      scopeKey: opts.activeScopeKey,
+      contextKey: opts.contextKey || null,
+      topicKey: opts.topicKey || null,
+    };
+  }
+  throw new Error('memory.consolidation.timer_synthesis requires scopeKind/scopeKey for multi-scope synthesis');
+}
+
+function sourceLineageFromSynthesisInput(synthesisInput = {}) {
+  const rows = Array.isArray(synthesisInput.sourceCurrentMemory) ? synthesisInput.sourceCurrentMemory : [];
+  const pairs = rows
+    .map(row => ({
+      id: Number(row.memoryId),
+      key: String(row.canonicalKey || '').trim(),
+    }))
+    .filter(row => Number.isSafeInteger(row.id) && row.id > 0 && row.key);
+  pairs.sort((a, b) => {
+    if (a.key !== b.key) return a.key.localeCompare(b.key);
+    return a.id - b.id;
+  });
+  return {
+    sourceMemoryIds: pairs.map(row => row.id),
+    sourceCanonicalKeys: pairs.map(row => row.key),
+  };
+}
+
+function buildTimerSynthesisCandidates(plan = {}, synthesisSummary = {}, opts = {}) {
+  const synthesisInput = plan.synthesisInput || plan.meta?.synthesisInput || null;
+  if (!synthesisInput) {
+    throw new Error('memory.consolidation.timer_synthesis requires a timer synthesisInput');
+  }
+  const { summary, safetyGate } = normalizeTimerSynthesisSummary(synthesisSummary);
+  const structuredSummary = summary.structuredSummary || {};
+  const scope = inferTimerSynthesisScope(synthesisInput, opts);
+  const lineage = sourceLineageFromSynthesisInput(synthesisInput);
+  const synthesisHash = hashSnapshot({
+    summary,
+    lineage,
+    cadence: plan.cadence,
+    periodStart: canonicalInstant(plan.periodStart),
+    periodEnd: canonicalInstant(plan.periodEnd),
+    policyVersion: plan.policyVersion || 'v1',
+  });
+  const evidenceRefs = [{
+    sourceKind: 'external',
+    sourceRef: `timer_synthesis:${synthesisHash}`,
+    relationKind: 'derived_from',
+    metadata: {
+      cadence: plan.cadence,
+      periodStart: canonicalInstant(plan.periodStart),
+      periodEnd: canonicalInstant(plan.periodEnd),
+      policyVersion: plan.policyVersion || 'v1',
+      sourceCanonicalKeys: lineage.sourceCanonicalKeys,
+    },
+  }];
+  const extracted = extractCandidatesFromStructuredSummary({
+    structuredSummary,
+    scopeKind: scope.scopeKind,
+    scopeKey: scope.scopeKey,
+    contextKey: scope.contextKey,
+    topicKey: scope.topicKey,
+    subject: opts.subject || `timer:${plan.cadence || 'manual'}`,
+    authority: opts.authority || 'verified_summary',
+    evidenceRefs,
+  });
+  const candidates = extracted.map((candidate, index) => ({
+    ...candidate,
+    candidateHash: hashSnapshot({
+      synthesisHash,
+      index,
+      canonicalKey: candidate.canonicalKey,
+      summary: candidate.summary,
+    }),
+    payload: {
+      ...(candidate.payload || {}),
+      kind: 'timer_synthesis',
+      synthesisKind: synthesisInput.kind || 'timer_current_memory_synthesis_v1',
+      currentMemoryRole: `${plan.cadence || 'manual'}_timer_synthesis_candidate`,
+      promotionGate: 'operator_required',
+      cadence: plan.cadence,
+      policyVersion: plan.policyVersion || 'v1',
+      periodStart: canonicalInstant(plan.periodStart),
+      periodEnd: canonicalInstant(plan.periodEnd),
+      synthesisHash,
+      sourceMemoryIds: lineage.sourceMemoryIds,
+      sourceCanonicalKeys: lineage.sourceCanonicalKeys,
+      safetyGate,
+    },
+  }));
+
+  return {
+    summary,
+    safetyGate,
+    synthesisHash,
+    candidates,
+    sourceMemoryIds: lineage.sourceMemoryIds,
+    sourceCanonicalKeys: lineage.sourceCanonicalKeys,
+  };
+}
+
+function attachTimerSynthesis(plan = {}, synthesisSummary = {}, opts = {}) {
+  const synthesis = buildTimerSynthesisCandidates(plan, synthesisSummary, opts);
+  const includeAggregateCandidates = opts.includeAggregateCandidates === true;
+  const candidates = includeAggregateCandidates
+    ? [...(Array.isArray(plan.candidates) ? plan.candidates : []), ...synthesis.candidates]
+    : synthesis.candidates;
+  const outputCoverage = {
+    ...(plan.outputCoverage || plan.meta?.outputCoverage || {}),
+    candidateCount: candidates.length,
+    synthesizedCandidateCount: synthesis.candidates.length,
+  };
+  const inputHash = hashSnapshot({
+    baseInputHash: plan.inputHash,
+    synthesisHash: synthesis.synthesisHash,
+    candidateHashes: candidates.map(candidate => candidate.candidateHash || hashSnapshot(candidate)),
+  });
+  return {
+    ...plan,
+    inputHash,
+    candidates,
+    synthesisResult: {
+      summary: synthesis.summary,
+      safetyGate: synthesis.safetyGate,
+      synthesisHash: synthesis.synthesisHash,
+      candidateCount: synthesis.candidates.length,
+      sourceMemoryIds: synthesis.sourceMemoryIds,
+      sourceCanonicalKeys: synthesis.sourceCanonicalKeys,
+    },
+    outputCoverage,
+    meta: {
+      ...(plan.meta || {}),
+      outputCoverage,
+      synthesisResult: {
+        synthesisHash: synthesis.synthesisHash,
+        candidateCount: synthesis.candidates.length,
+        safetyGate: synthesis.safetyGate,
+      },
+    },
+  };
+}
+
+function buildPromotionReview(input = {}, opts = {}) {
+  const plan = input.plan || input;
+  const promotionResult = input.promotionResult || {};
+  const applyResult = input.applyResult || {};
+  const candidates = Array.isArray(plan.candidates) ? plan.candidates : [];
+  const statusUpdates = Array.isArray(plan.statusUpdates) ? plan.statusUpdates : [];
+  const candidateLines = candidates.slice(0, Math.max(0, Math.min(20, opts.limit || 8))).map(candidate => {
+    const type = candidate.memoryType || candidate.memory_type || 'memory';
+    const scope = candidate.scopeKey || candidate.scope_key || 'unspecified';
+    const payload = candidate.payload && typeof candidate.payload === 'object' ? candidate.payload : {};
+    const sourceKeys = Array.isArray(payload.sourceCanonicalKeys) && payload.sourceCanonicalKeys.length > 0
+      ? ` | sources=${payload.sourceCanonicalKeys.join(',')}`
+      : '';
+    return `- candidate ${type} ${scope}: ${compactSummary(candidate)}${sourceKeys}`;
+  });
+  const staleLines = statusUpdates.slice(0, Math.max(0, Math.min(20, opts.limit || 8))).map(update => (
+    `- ${update.status}: ${update.canonicalKey || update.memoryId || 'memory'}${update.reason ? ` (${update.reason})` : ''}`
+  ));
+  const linesOrNone = lines => (lines.length > 0 ? lines.join('\n') : '- none');
+  return [
+    'Promotion review:',
+    `window: ${plan.cadence || 'manual'} ${canonicalInstant(plan.periodStart)} -> ${canonicalInstant(plan.periodEnd)}`,
+    `source: ${plan.synthesisInput?.sourceOfTruth || plan.meta?.synthesisInput?.sourceOfTruth || 'memory_records'}`,
+    `gate: ${input.promoteCandidates === true ? 'operator promotion requested' : 'candidate-only unless promoteCandidates=true'}`,
+    `status updates: planned=${statusUpdates.length} applied=${applyResult.applied || 0} skipped=${applyResult.skipped || 0}`,
+    `candidates: planned=${candidates.length} promoted=${promotionResult.promoted || 0} quarantined=${promotionResult.quarantined || 0} errored=${promotionResult.errored || 0}`,
+    'candidate proposals:',
+    linesOrNone(candidateLines),
+    'status update proposals:',
+    linesOrNone(staleLines),
+  ].join('\n');
+}
+
 function buildCoverage(normalized, statusUpdates, candidates) {
   const active = normalized.filter(record => record.status === 'active');
   const activeOpenLoops = active.filter(record => record.memoryType === 'open_loop');
@@ -460,6 +784,12 @@ function planCompaction(records = [], opts = {}) {
     periodStart,
     periodEnd,
   });
+  const synthesisInput = buildTimerSynthesisInput(normalized, statusUpdates, candidates, {
+    ...opts,
+    cadence,
+    periodStart,
+    periodEnd,
+  });
   const coverage = buildCoverage(normalized, statusUpdates, candidates);
 
   return {
@@ -469,6 +799,7 @@ function planCompaction(records = [], opts = {}) {
     policyVersion: opts.policyVersion || 'v1',
     inputHash,
     candidates,
+    synthesisInput,
     statusUpdates,
     sourceCoverage: coverage.sourceCoverage,
     outputCoverage: coverage.outputCoverage,
@@ -476,6 +807,7 @@ function planCompaction(records = [], opts = {}) {
       activeConflictRate: 0,
       deterministic: true,
       recordCount: normalized.length,
+      synthesisInput,
       sourceCoverage: coverage.sourceCoverage,
       outputCoverage: coverage.outputCoverage,
     },
@@ -1156,16 +1488,27 @@ function createMemoryConsolidation({ pool, schema, defaultTenantId, records = nu
       periodEnd: window.periodEnd,
       policyVersion: input.policyVersion || 'v1',
     });
+    const synthesisSummary = input.synthesisSummary || input.timerSynthesisSummary || null;
+    const effectivePlan = synthesisSummary
+      ? attachTimerSynthesis(plan, synthesisSummary, {
+          ...input,
+          tenantId,
+        })
+      : plan;
 
     if (input.apply !== true) {
       return {
         job,
         status: 'planned',
         dryRun: true,
-        plan,
-        cadence: plan.cadence,
-        periodStart: plan.periodStart,
-        periodEnd: plan.periodEnd,
+        plan: effectivePlan,
+        synthesisPrompt: input.includeSynthesisPrompt === true && effectivePlan.synthesisInput
+          ? buildTimerSynthesisPrompt(effectivePlan, input)
+          : undefined,
+        promotionReview: buildPromotionReview({ plan: effectivePlan }),
+        cadence: effectivePlan.cadence,
+        periodStart: effectivePlan.periodStart,
+        periodEnd: effectivePlan.periodEnd,
         snapshotCount: snapshot.rows.length,
         snapshotLimit: snapshot.snapshotLimit,
         snapshotTruncated: snapshot.snapshotTruncated,
@@ -1176,7 +1519,7 @@ function createMemoryConsolidation({ pool, schema, defaultTenantId, records = nu
 
     const result = input.promoteCandidates === true
       ? await executePlan({
-          plan,
+          plan: effectivePlan,
           tenantId,
           workerId: input.workerId,
           applyToken: input.applyToken,
@@ -1186,7 +1529,7 @@ function createMemoryConsolidation({ pool, schema, defaultTenantId, records = nu
           reclaimStaleClaims: input.reclaimStaleClaims,
         })
       : await applyPlan({
-          plan,
+          plan: effectivePlan,
           tenantId,
           workerId: input.workerId,
           applyToken: input.applyToken,
@@ -1194,21 +1537,27 @@ function createMemoryConsolidation({ pool, schema, defaultTenantId, records = nu
           claimLeaseSeconds: input.claimLeaseSeconds,
           reclaimStaleClaims: input.reclaimStaleClaims,
         });
-    const existingRun = result.run || await findExistingRun({ tenantId, plan });
+    const existingRun = result.run || await findExistingRun({ tenantId, plan: effectivePlan });
     return {
       ...result,
       job,
       dryRun: false,
-      cadence: plan.cadence,
-      periodStart: plan.periodStart,
-      periodEnd: plan.periodEnd,
+      promotionReview: buildPromotionReview({
+        plan: effectivePlan,
+        promotionResult: result.promotionResult,
+        applyResult: result.applyResult,
+        promoteCandidates: input.promoteCandidates === true,
+      }),
+      cadence: effectivePlan.cadence,
+      periodStart: effectivePlan.periodStart,
+      periodEnd: effectivePlan.periodEnd,
       snapshotCount: snapshot.rows.length,
       snapshotLimit: snapshot.snapshotLimit,
       snapshotTruncated: snapshot.snapshotTruncated,
       snapshotAsOf: snapshot.snapshotAsOf,
       scopeKeys: snapshot.scopeKeys,
       existingRun,
-      skipReason: result.run ? null : classifySkippedRun(existingRun, plan),
+      skipReason: result.run ? null : classifySkippedRun(existingRun, effectivePlan),
     };
   }
 
@@ -1231,6 +1580,11 @@ module.exports = {
   normalizeClaimLeaseSeconds,
   resolveOperatorWindow,
   planCompaction,
+  buildTimerSynthesisInput,
+  buildTimerSynthesisPrompt,
+  buildTimerSynthesisCandidates,
+  attachTimerSynthesis,
+  buildPromotionReview,
   distillArchiveSnapshot,
   createMemoryConsolidation,
 };