@shadowforge0/aquifer-memory 1.8.1 → 1.9.1

package/core/memory-consolidation.js

@@ -10,6 +10,49 @@ const OPERATOR_CADENCES = new Set(['manual', 'daily', 'weekly', 'monthly']);
 const DEFAULT_CLAIM_LEASE_SECONDS = 600;
 const DEFAULT_OPERATOR_SNAPSHOT_LIMIT = 1000;
 const MAX_OPERATOR_SNAPSHOT_LIMIT = 5000;
+const TEMPORAL_DISTILLATION_STANDARD_VERSION = 'temporal_distillation_standard_v1';
+const ASSISTANT_BEHAVIOR_LANGUAGE_LEVELS = new Set(['user_behavior', 'assistant_behavior']);
+const TEMPORAL_CADENCE_POLICY = {
+  daily: {
+    tier: 'daily',
+    windowKind: 'closed_utc_day',
+    outputSemantics: 'Carry forward still-current state, decisions, constraints, preferences, facts, conclusions, and open loops from a closed day.',
+    promotionRule: 'reviewed_synthesis_required',
+    aggregateCandidateRole: 'source_rollup_proposal',
+    promptGuidance: [
+      'Daily output may keep concrete same-day state and open loops only when they remain true after the day closes.',
+      'Do not promote transient test output, tool logs, progress narration, or resolved debugging paths.',
+      'Every returned item must include mergeKey, scopeClass, durability, and promotionTarget; temporal runtime state must include staleAfter or validTo.',
+    ],
+    preferredMemoryTypes: ['state', 'open_loop', 'decision', 'constraint', 'preference', 'fact', 'conclusion'],
+  },
+  weekly: {
+    tier: 'weekly',
+    windowKind: 'closed_utc_week',
+    outputSemantics: 'Promote only cross-day patterns, durable decisions, continuing risks, direction, and unresolved open loops from a closed week.',
+    promotionRule: 'reviewed_synthesis_required',
+    aggregateCandidateRole: 'source_rollup_proposal',
+    promptGuidance: [
+      'Weekly output must not preserve one-off daily details unless they still affect future work.',
+      'Prefer durable decisions, constraints, preferences, stable facts, conclusions, risks, and still-open loops.',
+      'Do not return temporary runtime state unless it has an explicit expiry and still affects future work.',
+    ],
+    preferredMemoryTypes: ['decision', 'constraint', 'preference', 'fact', 'conclusion', 'open_loop'],
+  },
+  monthly: {
+    tier: 'monthly',
+    windowKind: 'closed_utc_month',
+    outputSemantics: 'Keep only long-term principles, stable preferences, durable constraints, stable facts, architectural direction, and long-lived open loops from a closed month.',
+    promotionRule: 'reviewed_synthesis_required',
+    aggregateCandidateRole: 'source_rollup_proposal',
+    promptGuidance: [
+      'Monthly output must drop daily operational detail and stale project state.',
+      'Only durable principles, stable preferences, constraints, facts, direction, and long-lived open loops should remain.',
+      'Monthly output should not return workspace policy, process state, or one-off operator progress.',
+    ],
+    preferredMemoryTypes: ['constraint', 'preference', 'decision', 'fact', 'open_loop'],
+  },
+};
 
 function stableJson(value) {
   if (Array.isArray(value)) return `[${value.map(stableJson).join(',')}]`;
@@ -186,6 +229,27 @@ function aggregateCandidateCadence(cadence) {
   return cadence === 'daily' || cadence === 'weekly' || cadence === 'monthly';
 }
 
+function temporalPolicyForCadence(cadence) {
+  return TEMPORAL_CADENCE_POLICY[cadence] || null;
+}
+
+function isAggregateRollupCandidate(candidate = {}) {
+  const payload = candidate.payload && typeof candidate.payload === 'object' ? candidate.payload : {};
+  return payload.kind === 'compaction_rollup'
+    || payload.aggregateCandidateRole === 'source_rollup_proposal';
+}
+
+function assertPromotableTemporalCandidates(candidates = [], input = {}) {
+  if (input.promoteCandidates !== true) return;
+  const aggregateCandidates = candidates.filter(isAggregateRollupCandidate);
+  if (aggregateCandidates.length === 0) return;
+  if (input.unsafePromoteAggregateCandidates === true) return;
+  throw new Error(
+    'Temporal aggregate rollup candidates are ledger/prompt material only. '
+    + 'Attach a reviewed timer synthesis summary before promoting temporal candidates.'
+  );
+}
+
 function safeKeyPart(value, fallback) {
   const text = String(value || fallback || '').trim().toLowerCase();
   return text.replace(/\s+/g, '-').replace(/[^a-z0-9:._/-]/g, '-');
@@ -197,9 +261,272 @@ function compactSummary(record) {
   return summary.length > 240 ? `${summary.slice(0, 237)}...` : summary;
 }
 
+function normalizeClassifierValue(value) {
+  return String(value || '').trim().toLowerCase().replace(/\s+/g, '_').replace(/[^a-z0-9:_./-]/g, '');
+}
+
+function normalizeSummaryKey(value) {
+  return String(value || '').trim().toLowerCase().replace(/\s+/g, ' ');
+}
+
+function payloadValue(payload = {}, ...keys) {
+  for (const key of keys) {
+    if (payload[key] !== undefined && payload[key] !== null && payload[key] !== '') return payload[key];
+  }
+  return null;
+}
+
+function extractAbsolutePaths(text) {
+  return String(text || '').match(/\/(?:home|mnt|etc|var|tmp|opt|root|usr)\/[^\s"'<>),]+/g) || [];
+}
+
+function normalizePathPrefix(value) {
+  return String(value || '').trim().replace(/\/+$/, '');
+}
+
+function detectScopeClassFromContent(candidate = {}, opts = {}) {
+  const text = normalizeSummaryKey(`${candidate.title || ''} ${candidate.summary || ''}`);
+  const productRepoPaths = normalizeStringList(
+    opts.productRepoPaths || opts.productRepoPath || opts.repoPath || opts.allowedProductPath,
+  ).map(normalizePathPrefix).filter(Boolean);
+  const paths = extractAbsolutePaths(text);
+  if (paths.some(path => /(^|\/)(agents\.md|\.codex|\.openclaw)(\/|$)/.test(path.toLowerCase()))) {
+    return 'workspace_policy';
+  }
+  if (productRepoPaths.length > 0 && paths.some(path => (
+    !productRepoPaths.some(prefix => path === prefix || path.startsWith(`${prefix}/`))
+  ))) {
+    return 'workspace_policy';
+  }
+  if (/\bdirty worktree\b|\brevert\b.*\b(current task|user changes|outside the current task)\b/.test(text)) {
+    return 'workspace_policy';
+  }
+  if (/\b(restart|running process|mcp process|gateway|latest|published|release|tag|npm latest|github release|local install|runtime)\b/.test(text)) {
+    return 'runtime_state';
+  }
+  if (/\b(package surface|evidence_items|memory_records|postgresql|schema|query contract|release gate)\b/.test(text)) {
+    return 'product_memory';
+  }
+  return null;
+}
+
+function inferScopeClass(candidate = {}, opts = {}) {
+  const payload = candidate.payload && typeof candidate.payload === 'object' ? candidate.payload : {};
+  const explicit = normalizeClassifierValue(payloadValue(payload, 'scopeClass', 'scope_class'));
+  const detected = detectScopeClassFromContent(candidate, opts);
+  if (detected === 'workspace_policy') return detected;
+  if (explicit) return explicit;
+  return detected || 'product_memory';
+}
+
+function inferDurability(candidate = {}, scopeClass) {
+  const payload = candidate.payload && typeof candidate.payload === 'object' ? candidate.payload : {};
+  const explicit = normalizeClassifierValue(payloadValue(payload, 'durability'));
+  if (explicit) return explicit;
+  if (scopeClass === 'runtime_state') return 'temporal';
+  const memoryType = normalizeClassifierValue(candidate.memoryType || candidate.memory_type);
+  if (memoryType === 'open_loop') return 'bounded';
+  return 'durable';
+}
+
+function candidateExpiry(candidate = {}) {
+  const payload = candidate.payload && typeof candidate.payload === 'object' ? candidate.payload : {};
+  const staleness = payload.staleness && typeof payload.staleness === 'object' ? payload.staleness : {};
+  return payloadValue(candidate, 'staleAfter', 'stale_after', 'validTo', 'valid_to')
+    || payloadValue(payload, 'staleAfter', 'stale_after', 'validTo', 'valid_to', 'expiresAt', 'expires_at')
+    || payloadValue(staleness, 'staleAfter', 'stale_after', 'validTo', 'valid_to', 'expiresAt', 'expires_at');
+}
+
+function payloadObject(payload = {}, ...keys) {
+  for (const key of keys) {
+    const value = payload[key];
+    if (value && typeof value === 'object' && !Array.isArray(value)) return value;
+  }
+  return {};
+}
+
+function explicitBoolean(value) {
+  if (value === true || value === false) return value;
+  if (typeof value === 'string') {
+    const normalized = value.trim().toLowerCase();
+    if (normalized === 'true') return true;
+    if (normalized === 'false') return false;
+  }
+  return null;
+}
+
+function assistantBehaviorAbstraction(payload = {}) {
+  const abstraction = payloadObject(payload, 'abstraction', 'generalization', 'assistantBehaviorAbstraction');
+  const appliesBeyondSource = explicitBoolean(
+    abstraction.appliesBeyondSource
+    ?? abstraction.applies_beyond_source
+    ?? payload.appliesBeyondSource
+    ?? payload.applies_beyond_source,
+  );
+  const sourceBound = explicitBoolean(
+    abstraction.sourceBound
+    ?? abstraction.source_bound
+    ?? payload.sourceBound
+    ?? payload.source_bound,
+  );
+  const principle = String(
+    abstraction.principle
+    || abstraction.behaviorPrinciple
+    || abstraction.behavior_principle
+    || payload.behaviorPrinciple
+    || payload.behavior_principle
+    || '',
+  ).trim();
+  const languageLevel = normalizeClassifierValue(
+    abstraction.languageLevel
+    || abstraction.language_level
+    || payload.languageLevel
+    || payload.language_level,
+  );
+  const generalized = appliesBeyondSource === true && sourceBound === false && Boolean(principle);
+  const behaviorLanguage = ASSISTANT_BEHAVIOR_LANGUAGE_LEVELS.has(languageLevel);
+  return {
+    appliesBeyondSource,
+    sourceBound,
+    principle,
+    languageLevel,
+    declared: appliesBeyondSource !== null || sourceBound !== null || Boolean(principle) || Boolean(languageLevel),
+    generalized,
+    behaviorLanguage,
+    eligible: generalized && behaviorLanguage,
+  };
+}
+
+function evaluateTemporalDistillationCandidate(candidate = {}, opts = {}) {
+  const payload = candidate.payload && typeof candidate.payload === 'object' ? candidate.payload : {};
+  const cadence = normalizeClassifierValue(opts.cadence || candidate.payload?.cadence || 'manual');
+  const memoryType = normalizeClassifierValue(candidate.memoryType || candidate.memory_type);
+  const scopeClass = inferScopeClass(candidate, opts);
+  const promotionTarget = normalizeClassifierValue(payloadValue(payload, 'promotionTarget', 'promotion_target'))
+    || (memoryType === 'assistant_shaping'
+      ? 'assistant_behavior_memory'
+      : (scopeClass === 'product_memory' || scopeClass === 'runtime_state' ? 'project_current_memory' : scopeClass));
+  const durability = inferDurability(candidate, scopeClass);
+  const mergeKey = normalizeClassifierValue(payloadValue(payload, 'mergeKey', 'merge_key'));
+  const expiry = candidateExpiry(candidate);
+  const reasons = [];
+  const sourceCanonicalKeys = Array.isArray(candidate.sourceCanonicalKeys) ? candidate.sourceCanonicalKeys : [];
+  const sourceMemoryIds = Array.isArray(candidate.sourceMemoryIds) ? candidate.sourceMemoryIds : [];
+  const assistantBehaviorTarget = memoryType === 'assistant_shaping' && promotionTarget === 'assistant_behavior_memory';
+  const projectMemoryTarget = promotionTarget === 'project_current_memory';
+
+  if (!mergeKey) reasons.push('missing_merge_key');
+  if (candidate.sourceLineageError) reasons.push(candidate.sourceLineageError);
+  if (opts.requireSourceLineage === true && sourceCanonicalKeys.length === 0) reasons.push('missing_source_lineage');
+  if (sourceMemoryIds.length !== sourceCanonicalKeys.length) reasons.push('invalid_source_lineage');
+  if (scopeClass === 'workspace_policy' || promotionTarget === 'workspace_policy') reasons.push('workspace_policy_not_project_memory');
+  if (!assistantBehaviorTarget && !projectMemoryTarget) reasons.push('unsupported_promotion_target');
+  if (memoryType !== 'assistant_shaping' && promotionTarget === 'assistant_behavior_memory') {
+    reasons.push('assistant_behavior_target_requires_assistant_shaping');
+  }
+  if (assistantBehaviorTarget) {
+    const abstraction = assistantBehaviorAbstraction(payload);
+    if (!abstraction.generalized) reasons.push('assistant_behavior_requires_generalized_abstraction');
+    if (!abstraction.behaviorLanguage) reasons.push('assistant_behavior_requires_behavior_level_language');
+  }
+  if (durability === 'transient') reasons.push('transient_memory_not_promotable');
+  if (scopeClass === 'runtime_state' && !expiry) reasons.push('runtime_state_requires_expiry');
+  if ((cadence === 'weekly' || cadence === 'monthly') && scopeClass === 'runtime_state') reasons.push('runtime_state_not_promotable_for_cadence');
+  if (cadence === 'monthly' && memoryType === 'state') reasons.push('monthly_state_requires_long_lived_type');
+
+  return {
+    eligible: reasons.length === 0,
+    reasons,
+    standardVersion: TEMPORAL_DISTILLATION_STANDARD_VERSION,
+    mergeKey: mergeKey || `derived:${memoryType}:${hashSnapshot(candidate.summary || candidate.title || candidate.canonicalKey || '')}`,
+    scopeClass,
+    promotionTarget,
+    durability,
+    staleAfter: payloadValue(payload, 'staleAfter', 'stale_after') || payloadValue(candidate, 'staleAfter', 'stale_after') || null,
+    validTo: payloadValue(payload, 'validTo', 'valid_to') || payloadValue(candidate, 'validTo', 'valid_to') || null,
+  };
+}
+
+function temporalCandidatePriority(candidate = {}) {
+  const type = normalizeClassifierValue(candidate.memoryType || candidate.memory_type);
+  const priority = {
+    constraint: 80,
+    decision: 75,
+    fact: 70,
+    preference: 65,
+    open_loop: 60,
+    conclusion: 50,
+    state: 40,
+    entity_note: 30,
+  };
+  return priority[type] || 0;
+}
+
+function summarizeSafetyGate(safetyGate = {}) {
+  const stats = safetyGate.stats && typeof safetyGate.stats === 'object' ? safetyGate.stats : safetyGate;
+  return {
+    redacted: Number(stats.redacted || 0),
+    dropped: Number(stats.dropped || 0),
+  };
+}
+
+function applyTemporalDistillationStandard(candidates = [], opts = {}) {
+  const acceptedByMergeKey = new Map();
+  const rejected = [];
+  const acceptedOrder = [];
+
+  for (const candidate of candidates) {
+    const evaluation = evaluateTemporalDistillationCandidate(candidate, opts);
+    const payload = candidate.payload && typeof candidate.payload === 'object' ? candidate.payload : {};
+    const next = {
+      ...candidate,
+      staleAfter: candidate.staleAfter || candidate.stale_after || evaluation.staleAfter || null,
+      validTo: candidate.validTo || candidate.valid_to || evaluation.validTo || null,
+      payload: {
+        ...payload,
+        distillation: {
+          standardVersion: evaluation.standardVersion,
+          mergeKey: evaluation.mergeKey,
+          scopeClass: evaluation.scopeClass,
+          promotionTarget: evaluation.promotionTarget,
+          durability: evaluation.durability,
+          staleAfter: evaluation.staleAfter,
+          validTo: evaluation.validTo,
+        },
+      },
+    };
+    if (!evaluation.eligible) {
+      rejected.push({ candidate: next, reasons: evaluation.reasons });
+      continue;
+    }
+
+    const existing = acceptedByMergeKey.get(evaluation.mergeKey);
+    if (!existing) {
+      acceptedByMergeKey.set(evaluation.mergeKey, next);
+      acceptedOrder.push(evaluation.mergeKey);
+      continue;
+    }
+
+    const incomingPriority = temporalCandidatePriority(next);
+    const existingPriority = temporalCandidatePriority(existing);
+    if (incomingPriority > existingPriority) {
+      acceptedByMergeKey.set(evaluation.mergeKey, next);
+      rejected.push({ candidate: existing, reasons: ['duplicate_merge_key_superseded'] });
+    } else {
+      rejected.push({ candidate: next, reasons: ['duplicate_merge_key'] });
+    }
+  }
+
+  return {
+    candidates: acceptedOrder.map(key => acceptedByMergeKey.get(key)).filter(Boolean),
+    rejected,
+  };
+}
+
 function buildAggregateCandidates(normalized, statusUpdates, opts) {
   const { cadence, periodStart, periodEnd } = opts;
   if (!aggregateCandidateCadence(cadence)) return [];
+  const temporalPolicy = temporalPolicyForCadence(cadence);
 
   const staleIds = new Set(statusUpdates.map(update => String(update.memoryId)));
   const staleKeys = new Set(statusUpdates.map(update => String(update.canonicalKey || '')));
@@ -298,8 +625,11 @@ function buildAggregateCandidates(normalized, statusUpdates, opts) {
       payload: {
         kind: 'compaction_rollup',
         synthesisKind: 'timer_current_memory_synthesis_v1',
-        currentMemoryRole: `${cadence}_timer_synthesis_candidate`,
-        promotionGate: 'operator_required',
+        currentMemoryRole: `${cadence}_source_rollup_proposal`,
+        temporalTier: cadence,
+        temporalPolicy,
+        aggregateCandidateRole: 'source_rollup_proposal',
+        promotionGate: 'reviewed_synthesis_required',
         cadence,
         policyVersion,
         periodStart: windowStart,
@@ -324,8 +654,8 @@ function buildAggregateCandidates(normalized, statusUpdates, opts) {
           canonicalKey: record.canonicalKey,
         },
       })),
-      visibleInBootstrap: true,
-      visibleInRecall: true,
+      visibleInBootstrap: false,
+      visibleInRecall: false,
     });
   }
 
@@ -335,6 +665,7 @@ function buildAggregateCandidates(normalized, statusUpdates, opts) {
 function buildTimerSynthesisInput(normalized, statusUpdates, candidates, opts) {
   const { cadence, periodStart, periodEnd } = opts;
   if (!aggregateCandidateCadence(cadence)) return null;
+  const temporalPolicy = temporalPolicyForCadence(cadence);
 
   const staleIds = new Set(statusUpdates.map(update => String(update.memoryId)));
   const staleKeys = new Set(statusUpdates.map(update => String(update.canonicalKey || '')));
@@ -373,8 +704,10 @@ function buildTimerSynthesisInput(normalized, statusUpdates, candidates, opts) {
     periodEnd: windowEnd,
     promotion: {
       default: 'candidate_only',
-      requires: 'apply=true and promoteCandidates=true',
+      requires: 'apply=true, promoteCandidates=true, and reviewed synthesis summary',
+      aggregateCandidatePromotion: 'blocked_by_default',
     },
+    temporalPolicy,
     guards: {
       rawTranscriptExcluded: true,
       sessionSummariesExcluded: true,
@@ -419,14 +752,26 @@ function buildTimerSynthesisPrompt(plan = {}, opts = {}) {
     throw new Error('memory.consolidation.timer_synthesis_prompt requires a timer synthesisInput');
   }
   const maxFacts = opts.maxFacts || 12;
+  const temporalPolicy = synthesisInput.temporalPolicy || temporalPolicyForCadence(synthesisInput.cadence) || {};
+  const policyGuidance = Array.isArray(temporalPolicy.promptGuidance)
+    ? temporalPolicy.promptGuidance
+    : [];
   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":[]}}',
+    `Temporal tier: ${temporalPolicy.tier || synthesisInput.cadence || 'unknown'}.`,
+    `Temporal semantics: ${temporalPolicy.outputSemantics || 'Keep only memory that remains useful after the closed timer window.'}`,
+    ...policyGuidance.map(line => `Policy: ${line}`),
+    'Return compact JSON with this shape. Every item must include mergeKey, scopeClass, durability, promotionTarget, and sourceCanonicalKeys; temporal runtime state also needs staleAfter or validTo:',
+    '{"summaryText":"...","structuredSummary":{"assistant_shaping":[{"guidance":"...","shapingKind":"memory_policy","servingImpact":"changes_memory_promotion","userRelevance":"...","temporalSupport":{"observationCount":2},"abstraction":{"languageLevel":"user_behavior","appliesBeyondSource":true,"sourceBound":false,"principle":"..."},"mergeKey":"...","scopeClass":"assistant_behavior","durability":"durable","promotionTarget":"assistant_behavior_memory","sourceCanonicalKeys":["memory:canonical:key"]}],"facts":[{"statement":"...","subject":"...","aspect":"...","mergeKey":"...","scopeClass":"product_memory","durability":"durable","promotionTarget":"project_current_memory","sourceCanonicalKeys":["memory:canonical:key"]}],"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.',
+    'Use promotionTarget="project_current_memory" only for product-scoped memory that should be eligible for current-memory promotion.',
+    'Use assistant_shaping with promotionTarget="assistant_behavior_memory" only for durable assistant behavior that changes future responses, retrieval, tool routing, or memory promotion for the user.',
+    'For assistant_behavior_memory, put project-specific evidence only in sourceCanonicalKeys and abstraction context; guidance must state the generalized assistant behavior, and abstraction must set languageLevel="user_behavior", appliesBeyondSource=true, sourceBound=false, and principle.',
+    'Use scopeClass="workspace_policy" or promotionTarget="workspace_policy" for workspace/operator rules; those will stay out of project current memory.',
+    'Use the same mergeKey for duplicate claims across memory types so the deterministic gate can keep one candidate.',
     'Do not copy sourceCurrentMemory unchanged unless the timer window confirms it still carries forward.',
     '',
     '<timer_synthesis_input>',
@@ -504,6 +849,93 @@ function sourceLineageFromSynthesisInput(synthesisInput = {}) {
   };
 }
 
+function sourceLookupFromSynthesisInput(synthesisInput = {}) {
+  const rows = Array.isArray(synthesisInput.sourceCurrentMemory) ? synthesisInput.sourceCurrentMemory : [];
+  const byKey = new Map();
+  const byId = new Map();
+  for (const row of rows) {
+    const id = Number(row.memoryId);
+    const key = String(row.canonicalKey || '').trim();
+    if (!Number.isSafeInteger(id) || id <= 0 || !key) continue;
+    const pair = { id, key };
+    byKey.set(key, pair);
+    byId.set(id, pair);
+  }
+  return { byKey, byId };
+}
+
+function assistantBehaviorPromotionTarget(payload = {}) {
+  return normalizeClassifierValue(payloadValue(payload, 'promotionTarget', 'promotion_target'))
+    || normalizeClassifierValue(payloadObject(payload, 'distillation').promotionTarget || payloadObject(payload, 'distillation').promotion_target);
+}
+
+function normalizeAssistantBehaviorServingText(candidate = {}) {
+  if ((candidate.memoryType || candidate.memory_type) !== 'assistant_shaping') return candidate;
+  const payload = candidate.payload && typeof candidate.payload === 'object' ? candidate.payload : {};
+  if (assistantBehaviorPromotionTarget(payload) !== 'assistant_behavior_memory') return candidate;
+  const abstraction = assistantBehaviorAbstraction(payload);
+  if (!abstraction.eligible) return candidate;
+  const sourceGuidance = String(payload.guidance || '').trim();
+  const nextPayload = {
+    ...payload,
+    guidance: abstraction.principle,
+  };
+  if (sourceGuidance && sourceGuidance !== abstraction.principle) {
+    nextPayload.sourceGuidance = sourceGuidance;
+  }
+  return {
+    ...candidate,
+    title: abstraction.principle.slice(0, 120),
+    summary: abstraction.principle,
+    payload: nextPayload,
+  };
+}
+
+function candidatePayloadWithoutLineage(payload = {}) {
+  const rest = { ...payload };
+  delete rest.sourceMemoryIds;
+  delete rest.source_memory_ids;
+  delete rest.sourceCanonicalKeys;
+  delete rest.source_canonical_keys;
+  delete rest.sources;
+  delete rest.sourceKeys;
+  delete rest.source_keys;
+  return rest;
+}
+
+function resolveCandidateSourceLineage(payload = {}, lookup = {}) {
+  const keys = normalizeStringList(
+    payload.sourceCanonicalKeys || payload.source_canonical_keys || payload.sourceKeys || payload.source_keys,
+  );
+  const ids = normalizeStringList(payload.sourceMemoryIds || payload.source_memory_ids)
+    .map(value => Number(value))
+    .filter(value => Number.isSafeInteger(value) && value > 0);
+  const pairs = new Map();
+  for (const key of keys) {
+    const pair = lookup.byKey?.get(key);
+    if (!pair) {
+      return { sourceMemoryIds: [], sourceCanonicalKeys: [], error: 'invalid_source_lineage' };
+    }
+    pairs.set(pair.key, pair);
+  }
+  for (const id of ids) {
+    const pair = lookup.byId?.get(id);
+    if (!pair) {
+      return { sourceMemoryIds: [], sourceCanonicalKeys: [], error: 'invalid_source_lineage' };
+    }
+    pairs.set(pair.key, pair);
+  }
+  const sorted = [...pairs.values()].sort((a, b) => {
+    if (a.key !== b.key) return a.key.localeCompare(b.key);
+    return a.id - b.id;
+  });
+  return {
+    sourceMemoryIds: sorted.map(pair => pair.id),
+    sourceCanonicalKeys: sorted.map(pair => pair.key),
+    error: null,
+  };
+}
+
 function buildTimerSynthesisCandidates(plan = {}, synthesisSummary = {}, opts = {}) {
   const synthesisInput = plan.synthesisInput || plan.meta?.synthesisInput || null;
   if (!synthesisInput) {
@@ -513,6 +945,8 @@ function buildTimerSynthesisCandidates(plan = {}, synthesisSummary = {}, opts =
   const structuredSummary = summary.structuredSummary || {};
   const scope = inferTimerSynthesisScope(synthesisInput, opts);
   const lineage = sourceLineageFromSynthesisInput(synthesisInput);
+  const sourceLookup = sourceLookupFromSynthesisInput(synthesisInput);
+  const sourceRecordCount = lineage.sourceMemoryIds.length;
   const synthesisHash = hashSnapshot({
     summary,
     lineage,
@@ -530,7 +964,7 @@ function buildTimerSynthesisCandidates(plan = {}, synthesisSummary = {}, opts =
       periodStart: canonicalInstant(plan.periodStart),
       periodEnd: canonicalInstant(plan.periodEnd),
       policyVersion: plan.policyVersion || 'v1',
-      sourceCanonicalKeys: lineage.sourceCanonicalKeys,
+      sourceRecordCount,
     },
   }];
   const extracted = extractCandidatesFromStructuredSummary({
@@ -543,36 +977,54 @@ function buildTimerSynthesisCandidates(plan = {}, synthesisSummary = {}, opts =
     authority: opts.authority || 'verified_summary',
     evidenceRefs,
   });
-  const candidates = extracted.map((candidate, index) => ({
-    ...candidate,
-    candidateHash: hashSnapshot({
+  const prepared = extracted.map((candidate, index) => {
+    const normalizedCandidate = normalizeAssistantBehaviorServingText(candidate);
+    const itemPayload = normalizedCandidate.payload && typeof normalizedCandidate.payload === 'object'
+      ? normalizedCandidate.payload
+      : {};
+    const itemLineage = resolveCandidateSourceLineage(itemPayload, sourceLookup);
+    const 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,
-    },
-  }));
+      canonicalKey: normalizedCandidate.canonicalKey,
+      summary: normalizedCandidate.summary,
+    });
+    return {
+      ...normalizedCandidate,
+      candidateHash,
+      sourceMemoryIds: itemLineage.sourceMemoryIds,
+      sourceCanonicalKeys: itemLineage.sourceCanonicalKeys,
+      sourceLineageError: itemLineage.error,
+      payload: {
+        ...candidatePayloadWithoutLineage(itemPayload),
+        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,
+        sourceLineageRef: `timer_synthesis:${synthesisHash}:candidate:${candidateHash}`,
+        sourceRecordCount: itemLineage.sourceMemoryIds.length,
+        safetyGateSummary: summarizeSafetyGate(safetyGate),
+      },
+    };
+  });
+  const standardized = applyTemporalDistillationStandard(prepared, {
+    cadence: plan.cadence,
+    periodStart: plan.periodStart,
+    periodEnd: plan.periodEnd,
+    requireSourceLineage: true,
+  });
 
   return {
     summary,
     safetyGate,
     synthesisHash,
-    candidates,
+    candidates: standardized.candidates,
+    rejectedCandidates: standardized.rejected,
     sourceMemoryIds: lineage.sourceMemoryIds,
     sourceCanonicalKeys: lineage.sourceCanonicalKeys,
   };
@@ -603,6 +1055,23 @@ function attachTimerSynthesis(plan = {}, synthesisSummary = {}, opts = {}) {
       safetyGate: synthesis.safetyGate,
       synthesisHash: synthesis.synthesisHash,
       candidateCount: synthesis.candidates.length,
+      candidateTrace: synthesis.candidates.map(candidate => ({
+        candidateHash: candidate.candidateHash,
+        memoryType: candidate.memoryType,
+        canonicalKey: candidate.canonicalKey,
+        sourceMemoryIds: candidate.sourceMemoryIds || [],
+        sourceCanonicalKeys: candidate.sourceCanonicalKeys || [],
+      })),
+      rejectedCandidateCount: synthesis.rejectedCandidates.length,
+      rejectedCandidates: synthesis.rejectedCandidates.map(item => ({
+        memoryType: item.candidate.memoryType,
+        canonicalKey: item.candidate.canonicalKey,
+        summary: compactSummary(item.candidate),
+        reasons: item.reasons,
+        distillation: item.candidate.payload?.distillation || null,
+        sourceMemoryIds: item.candidate.sourceMemoryIds || [],
+        sourceCanonicalKeys: item.candidate.sourceCanonicalKeys || [],
+      })),
       sourceMemoryIds: synthesis.sourceMemoryIds,
       sourceCanonicalKeys: synthesis.sourceCanonicalKeys,
     },
@@ -613,6 +1082,7 @@ function attachTimerSynthesis(plan = {}, synthesisSummary = {}, opts = {}) {
       synthesisResult: {
         synthesisHash: synthesis.synthesisHash,
         candidateCount: synthesis.candidates.length,
+        rejectedCandidateCount: synthesis.rejectedCandidates.length,
         safetyGate: synthesis.safetyGate,
       },
     },
@@ -625,14 +1095,28 @@ function buildPromotionReview(input = {}, opts = {}) {
   const applyResult = input.applyResult || {};
   const candidates = Array.isArray(plan.candidates) ? plan.candidates : [];
   const statusUpdates = Array.isArray(plan.statusUpdates) ? plan.statusUpdates : [];
+  const aggregateCandidateCount = candidates.filter(isAggregateRollupCandidate).length;
+  const synthesisResult = plan.synthesisResult || plan.meta?.synthesisResult || null;
+  const rejectedCandidateCount = synthesisResult?.rejectedCandidateCount || 0;
+  const gate = input.promoteCandidates === true
+    ? (aggregateCandidateCount > 0
+        ? 'blocked unless unsafePromoteAggregateCandidates=true; attach reviewed synthesis summary for normal promotion'
+        : 'operator promotion requested for reviewed synthesis candidates')
+    : 'candidate-only unless promoteCandidates=true with reviewed synthesis summary';
   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(',')}`
+    const candidateSourceKeys = Array.isArray(candidate.sourceCanonicalKeys) && candidate.sourceCanonicalKeys.length > 0
+      ? candidate.sourceCanonicalKeys
+      : (Array.isArray(payload.sourceCanonicalKeys) ? payload.sourceCanonicalKeys : []);
+    const sourceKeys = candidateSourceKeys.length > 0
+      ? ` | sources=${candidateSourceKeys.join(',')}`
       : '';
-    return `- candidate ${type} ${scope}: ${compactSummary(candidate)}${sourceKeys}`;
+    const sourceLineage = !sourceKeys && payload.sourceLineageRef
+      ? ` | lineage=${payload.sourceLineageRef} sourceRecordCount=${payload.sourceRecordCount || 0}`
+      : '';
+    return `- candidate ${type} ${scope}: ${compactSummary(candidate)}${sourceKeys}${sourceLineage}`;
   });
   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})` : ''}`
@@ -642,9 +1126,10 @@ function buildPromotionReview(input = {}, opts = {}) {
     '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'}`,
+    `gate: ${gate}`,
+    `temporal synthesis: ${synthesisResult ? `reviewed summary attached (${synthesisResult.candidateCount || 0} candidates, ${rejectedCandidateCount} rejected)` : 'not attached'}`,
     `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}`,
+    `candidates: planned=${candidates.length} aggregate=${aggregateCandidateCount} promoted=${promotionResult.promoted || 0} quarantined=${promotionResult.quarantined || 0} errored=${promotionResult.errored || 0}`,
     'candidate proposals:',
     linesOrNone(candidateLines),
     'status update proposals:',
@@ -720,12 +1205,37 @@ function summarizePromotionResults(results = []) {
   return summary;
 }
 
-function normalizeCandidateLineage(candidate = {}) {
+function planLineageForCandidate(candidate = {}, plan = {}) {
   const payload = candidate.payload && typeof candidate.payload === 'object' ? candidate.payload : {};
-  const sourceCanonicalKeys = Array.isArray(payload.sourceCanonicalKeys)
-    ? payload.sourceCanonicalKeys.map(key => String(key || '')).filter(Boolean)
-    : [];
-  const rawSourceMemoryIds = Array.isArray(payload.sourceMemoryIds) ? payload.sourceMemoryIds : [];
+  const sourceLineageRef = String(payload.sourceLineageRef || '').trim();
+  if (!sourceLineageRef) return null;
+  const synthesisResult = plan.synthesisResult || plan.meta?.synthesisResult || null;
+  if (!synthesisResult || !synthesisResult.synthesisHash) return null;
+  const baseRef = `timer_synthesis:${synthesisResult.synthesisHash}`;
+  if (sourceLineageRef !== baseRef && !sourceLineageRef.startsWith(`${baseRef}:candidate:`)) return null;
+  return {
+    sourceMemoryIds: Array.isArray(synthesisResult.sourceMemoryIds) ? synthesisResult.sourceMemoryIds : [],
+    sourceCanonicalKeys: Array.isArray(synthesisResult.sourceCanonicalKeys) ? synthesisResult.sourceCanonicalKeys : [],
+  };
+}
+
+function normalizeCandidateLineage(candidate = {}, opts = {}) {
+  const payload = candidate.payload && typeof candidate.payload === 'object' ? candidate.payload : {};
+  const planLineage = planLineageForCandidate(candidate, opts.plan || {});
+  const candidateCanonicalKeys = Array.isArray(candidate.sourceCanonicalKeys)
+    ? candidate.sourceCanonicalKeys
+    : (Array.isArray(candidate.source_canonical_keys) ? candidate.source_canonical_keys : null);
+  const candidateMemoryIds = Array.isArray(candidate.sourceMemoryIds)
+    ? candidate.sourceMemoryIds
+    : (Array.isArray(candidate.source_memory_ids) ? candidate.source_memory_ids : null);
+  const sourceCanonicalKeys = Array.isArray(candidateCanonicalKeys)
+    ? candidateCanonicalKeys.map(key => String(key || '')).filter(Boolean)
+    : (Array.isArray(payload.sourceCanonicalKeys)
+        ? payload.sourceCanonicalKeys.map(key => String(key || '')).filter(Boolean)
+        : (planLineage?.sourceCanonicalKeys || []).map(key => String(key || '')).filter(Boolean));
+  const rawSourceMemoryIds = Array.isArray(candidateMemoryIds)
+    ? candidateMemoryIds
+    : (Array.isArray(payload.sourceMemoryIds) ? payload.sourceMemoryIds : (planLineage?.sourceMemoryIds || []));
   const sourceMemoryIds = rawSourceMemoryIds
     .filter(id => id !== null && id !== undefined)
     .map(id => Number(id));
@@ -1086,7 +1596,9 @@ function createMemoryConsolidation({ pool, schema, defaultTenantId, records = nu
     for (let i = 0; i < candidates.length; i++) {
       const candidate = candidates[i] || {};
       const result = results[i] || {};
-      const { payload, sourceMemoryIds, sourceCanonicalKeys } = normalizeCandidateLineage(candidate);
+      const { payload, sourceMemoryIds, sourceCanonicalKeys } = normalizeCandidateLineage(candidate, {
+        plan: input.plan,
+      });
       const candidateHash = candidate.candidateHash || payload.candidateHash || hashSnapshot(candidate);
       const inserted = await queryable.query(
         `INSERT INTO ${schema}.compaction_candidates (
@@ -1213,6 +1725,7 @@ function createMemoryConsolidation({ pool, schema, defaultTenantId, records = nu
               tenantId,
               run: claim,
               candidates,
+              plan,
               results: candidates.map(candidate => ({
                 candidate,
                 action: 'planned',
@@ -1258,6 +1771,8 @@ function createMemoryConsolidation({ pool, schema, defaultTenantId, records = nu
     const promoteCandidates = input.promoteCandidates === true;
     const summary = createApplySummary(statusUpdates);
 
+    assertPromotableTemporalCandidates(candidates, input);
+
     if (!records || typeof records.updateMemoryStatusIfCurrent !== 'function') {
       throw new Error('memory.consolidation.executePlan requires records.updateMemoryStatusIfCurrent');
     }
@@ -1344,6 +1859,7 @@ function createMemoryConsolidation({ pool, schema, defaultTenantId, records = nu
         tenantId,
         run: claim,
         candidates,
+        plan,
         results: promotionResults,
       });
       const promotionResult = summarizePromotionResults(promotionResults);
@@ -1525,6 +2041,7 @@ function createMemoryConsolidation({ pool, schema, defaultTenantId, records = nu
           applyToken: input.applyToken,
           appliedAt: input.appliedAt,
           promoteCandidates: true,
+          unsafePromoteAggregateCandidates: input.unsafePromoteAggregateCandidates,
           claimLeaseSeconds: input.claimLeaseSeconds,
           reclaimStaleClaims: input.reclaimStaleClaims,
         })
@@ -1579,6 +2096,11 @@ module.exports = {
   canonicalInstant,
   normalizeClaimLeaseSeconds,
   resolveOperatorWindow,
+  temporalPolicyForCadence,
+  evaluateTemporalDistillationCandidate,
+  applyTemporalDistillationStandard,
+  isAggregateRollupCandidate,
+  assertPromotableTemporalCandidates,
   planCompaction,
   buildTimerSynthesisInput,
   buildTimerSynthesisPrompt,