@shadowforge0/aquifer-memory 1.8.1 → 1.9.1

package/core/memory-serving.js

@@ -1,12 +1,53 @@
 'use strict';
 
 function splitScopePath(value) {
-  if (Array.isArray(value)) return value.map(v => String(v).trim()).filter(Boolean);
+  if (Array.isArray(value)) {
+    const parts = value.map(v => String(v).trim()).filter(Boolean);
+    return parts.length > 0 ? parts : null;
+  }
   if (typeof value !== 'string') return null;
   const parts = value.split(',').map(v => v.trim()).filter(Boolean);
   return parts.length > 0 ? parts : null;
 }
 
+function uniqueList(values = []) {
+  const seen = new Set();
+  const out = [];
+  for (const value of values) {
+    const key = String(value || '').trim();
+    if (!key || seen.has(key)) continue;
+    seen.add(key);
+    out.push(key);
+  }
+  return out;
+}
+
+function normalizeScopeList(value) {
+  return uniqueList(splitScopePath(value) || []);
+}
+
+function requestedScopeKeys(opts = {}) {
+  const fromPath = normalizeScopeList(opts.activeScopePath);
+  const keys = [];
+  if (fromPath.length > 0) keys.push(...fromPath);
+  if (opts.activeScopeKey) keys.push(opts.activeScopeKey);
+  if (opts.scopeKey) keys.push(opts.scopeKey);
+  if (opts.resolvedScopeKey) keys.push(opts.resolvedScopeKey);
+  if (opts.scopeKeys) keys.push(...normalizeScopeList(opts.scopeKeys));
+  return uniqueList(keys);
+}
+
+function assertAllowedScopeRequest(opts = {}) {
+  const allowed = normalizeScopeList(opts.allowedScopeKeys);
+  if (allowed.length === 0) return;
+  const allowedSet = new Set(allowed);
+  const requested = requestedScopeKeys(opts);
+  const denied = requested.filter(key => !allowedSet.has(key));
+  if (denied.length > 0) {
+    throw new Error(`Requested memory scope is outside allowedScopeKeys: ${denied.join(', ')}`);
+  }
+}
+
 function hasEvidenceBoundary(opts = {}) {
   return Boolean(
     opts.agentId
@@ -89,7 +130,13 @@ function normalizeCuratedRecallRow(row = {}) {
 function createMemoryServingRuntime(memoryCfg = {}, env = process.env) {
   const servingMode = memoryCfg.servingMode || env.AQUIFER_MEMORY_SERVING_MODE || 'legacy';
   const defaultActiveScopeKey = memoryCfg.activeScopeKey || null;
-  const defaultActiveScopePath = splitScopePath(memoryCfg.activeScopePath || null);
+  const configuredActiveScopePath = splitScopePath(memoryCfg.activeScopePath || null);
+  const defaultActiveScopePath = configuredActiveScopePath
+    || uniqueList(['global', defaultActiveScopeKey].filter(Boolean));
+  const configuredAllowedScopeKeys = normalizeScopeList(memoryCfg.allowedScopeKeys || env.AQUIFER_MEMORY_ALLOWED_SCOPE_KEYS || null);
+  const defaultAllowedScopeKeys = configuredAllowedScopeKeys.length > 0
+    ? configuredAllowedScopeKeys
+    : defaultActiveScopePath;
 
   function resolveMode(opts = {}) {
     const mode = opts.memoryMode || opts.servingMode || servingMode;
@@ -100,12 +147,18 @@ function createMemoryServingRuntime(memoryCfg = {}, env = process.env) {
 
   function withDefaultScope(opts = {}) {
     const next = { ...opts };
-    if (!next.activeScopePath && defaultActiveScopePath) next.activeScopePath = defaultActiveScopePath;
+    const scopeIdOnly = next.scopeId && !next.activeScopePath && !next.activeScopeKey;
+    if (!next.allowedScopeKeys && defaultAllowedScopeKeys) {
+      next.allowedScopeKeys = defaultAllowedScopeKeys;
+    }
+    if (!scopeIdOnly && !next.activeScopePath && defaultActiveScopePath) next.activeScopePath = defaultActiveScopePath;
     if (Array.isArray(next.activeScopePath) && next.activeScopePath.length > 0) {
       if (!next.activeScopeKey) next.activeScopeKey = next.activeScopePath[next.activeScopePath.length - 1];
+      assertAllowedScopeRequest(next);
       return next;
     }
-    if (!next.activeScopeKey && defaultActiveScopeKey) next.activeScopeKey = defaultActiveScopeKey;
+    if (!scopeIdOnly && !next.activeScopeKey && defaultActiveScopeKey) next.activeScopeKey = defaultActiveScopeKey;
+    assertAllowedScopeRequest(next);
     return next;
   }
 
@@ -114,6 +167,7 @@ function createMemoryServingRuntime(memoryCfg = {}, env = process.env) {
     assertCuratedRecallOpts,
     defaultActiveScopeKey,
     defaultActiveScopePath,
+    defaultAllowedScopeKeys,
     hasEvidenceBoundary,
     normalizeCuratedRecallRow,
     resolveMode,
@@ -123,10 +177,13 @@ function createMemoryServingRuntime(memoryCfg = {}, env = process.env) {
 }
 
 module.exports = {
+  assertAllowedScopeRequest,
   assertCuratedBootstrapOpts,
   assertCuratedRecallOpts,
   createMemoryServingRuntime,
   hasEvidenceBoundary,
   normalizeCuratedRecallRow,
+  normalizeScopeList,
+  requestedScopeKeys,
   splitScopePath,
 };

package/core/memory-type-policy.js

@@ -0,0 +1,298 @@
+'use strict';
+
+const MEMORY_TYPE_POLICY = Object.freeze({
+  assistant_shaping: {
+    label: '回答塑形',
+    active: true,
+    defaultInheritance: 'defaultable',
+    defaultAspect: 'assistant_shaping',
+    bootstrapPriority: 0,
+    recallRank: 95,
+    runtimeContract: true,
+  },
+  constraint: {
+    label: '限制',
+    active: true,
+    defaultInheritance: 'additive',
+    defaultAspect: 'constraint',
+    bootstrapPriority: 1,
+    recallRank: 80,
+  },
+  state: {
+    label: '狀態',
+    active: true,
+    defaultInheritance: 'defaultable',
+    defaultAspect: 'state',
+    bootstrapPriority: 2,
+    recallRank: 60,
+  },
+  open_loop: {
+    label: '未完成',
+    active: true,
+    defaultInheritance: 'non_inheritable',
+    defaultAspect: 'open_loop',
+    bootstrapPriority: 3,
+    recallRank: 55,
+  },
+  decision: {
+    label: '決策',
+    active: true,
+    defaultInheritance: 'non_inheritable',
+    defaultAspect: 'decision',
+    bootstrapPriority: 4,
+    recallRank: 50,
+  },
+  preference: {
+    label: '偏好',
+    active: true,
+    defaultInheritance: 'defaultable',
+    defaultAspect: 'preference',
+    bootstrapPriority: 5,
+    recallRank: 70,
+  },
+  fact: {
+    label: '事實',
+    active: true,
+    defaultInheritance: 'defaultable',
+    defaultAspect: 'fact',
+    bootstrapPriority: 6,
+    recallRank: 40,
+  },
+  conclusion: {
+    label: '判斷',
+    active: true,
+    defaultInheritance: 'defaultable',
+    defaultAspect: 'conclusion',
+    bootstrapPriority: 7,
+    recallRank: 30,
+  },
+  entity_note: {
+    label: '註記',
+    active: true,
+    defaultInheritance: 'defaultable',
+    defaultAspect: 'entity_note',
+    bootstrapPriority: 8,
+    recallRank: 20,
+  },
+});
+
+const AUTHORITY_POLICY = Object.freeze({
+  raw_transcript: { strength: 0, sortPriority: 6 },
+  llm_inference: { strength: 1, sortPriority: 5 },
+  verified_summary: { strength: 2, sortPriority: 4 },
+  manual: { strength: 3, sortPriority: 2 },
+  system: { strength: 4, sortPriority: 3 },
+  executable_evidence: { strength: 5, sortPriority: 1 },
+  user_explicit: { strength: 6, sortPriority: 0 },
+});
+
+const FEEDBACK_WEIGHT = Object.freeze({
+  helpful: 0.15,
+  confirm: 0.10,
+  irrelevant: -0.20,
+  scope_mismatch: -0.25,
+  stale: -0.30,
+  incorrect: -0.50,
+});
+
+const ASSISTANT_SHAPING_KINDS = Object.freeze([
+  'response_style',
+  'interaction_boundary',
+  'retrieval_policy',
+  'tool_routing',
+  'memory_policy',
+  'user_preference',
+  'correction_pattern',
+  'decision_style',
+]);
+
+const ASSISTANT_SHAPING_SERVING_IMPACTS = Object.freeze([
+  'changes_future_responses',
+  'changes_retrieval_selection',
+  'changes_bootstrap_selection',
+  'changes_tool_routing',
+  'changes_memory_promotion',
+  'sets_user_boundary',
+  'sets_assistant_behavior',
+]);
+
+const ASSISTANT_SHAPING_PROMPT_LINES = Object.freeze([
+  'Use assistant_shaping only when a memory changes durable cross-consumer runtime behavior for the user: future response style, interaction boundary, retrieval selection, tool routing, or memory promotion policy.',
+  'Each assistant_shaping item must include guidance or policy text plus shapingKind, servingImpact, and userRelevance. For non-explicit-user-instruction summaries, include temporalSupport showing repeated observations, multiple sessions, or a consolidation window.',
+  'Treat shapingKind and servingImpact as extensible hints, not as a closed product taxonomy. If the item only reports current task state, implementation facts, or a single answer, keep it in the ordinary memory layer instead.',
+]);
+
+function normalizeToken(value) {
+  return String(value || '').trim().toLowerCase();
+}
+
+function memoryTypePolicy(type) {
+  return MEMORY_TYPE_POLICY[normalizeToken(type)] || null;
+}
+
+function activeMemoryTypes() {
+  return Object.keys(MEMORY_TYPE_POLICY).filter(type => MEMORY_TYPE_POLICY[type].active);
+}
+
+function isActiveMemoryType(type) {
+  const policy = memoryTypePolicy(type);
+  return Boolean(policy && policy.active);
+}
+
+function defaultInheritanceForMemoryType(type) {
+  return memoryTypePolicy(type)?.defaultInheritance || 'defaultable';
+}
+
+function defaultAspectForMemoryType(type) {
+  return memoryTypePolicy(type)?.defaultAspect || normalizeToken(type) || 'memory';
+}
+
+function memoryTypeLabel(type) {
+  return memoryTypePolicy(type)?.label || '記憶';
+}
+
+function memoryTypeBootstrapPriority(type) {
+  return memoryTypePolicy(type)?.bootstrapPriority ?? 99;
+}
+
+function memoryTypeRecallRank(type) {
+  return memoryTypePolicy(type)?.recallRank ?? 0;
+}
+
+function memoryTypeRuntimeContract(type) {
+  return memoryTypePolicy(type)?.runtimeContract === true;
+}
+
+function authorityPolicy(authority) {
+  return AUTHORITY_POLICY[normalizeToken(authority)] || null;
+}
+
+function authorityStrength(authority) {
+  return authorityPolicy(authority)?.strength ?? 0;
+}
+
+function authoritySortPriority(authority) {
+  return authorityPolicy(authority)?.sortPriority ?? 99;
+}
+
+function feedbackWeight(type) {
+  return FEEDBACK_WEIGHT[normalizeToken(type)] || 0;
+}
+
+function sqlLiteral(value) {
+  return `'${String(value).replace(/'/g, "''")}'`;
+}
+
+function caseSql(expr, entries, valueKey, fallback) {
+  const clauses = entries
+    .map(([key, policy]) => `WHEN ${sqlLiteral(key)} THEN ${policy[valueKey]}`)
+    .join('\n    ');
+  return `CASE ${expr}\n    ${clauses}\n    ELSE ${fallback}\n  END`;
+}
+
+function memoryTypeBootstrapPrioritySql(expr = 'm.memory_type') {
+  return caseSql(expr, Object.entries(MEMORY_TYPE_POLICY), 'bootstrapPriority', 99);
+}
+
+function memoryTypeRecallRankSql(expr = 'm.memory_type') {
+  const entries = Object.entries(MEMORY_TYPE_POLICY)
+    .map(([key, policy]) => [key, { recallWeight: (policy.recallRank || 0) / 100 }]);
+  return caseSql(expr, entries, 'recallWeight', 0);
+}
+
+function authoritySortPrioritySql(expr = 'm.authority') {
+  return caseSql(expr, Object.entries(AUTHORITY_POLICY), 'sortPriority', 99);
+}
+
+function feedbackWeightSql(expr = 'f.feedback_type') {
+  const entries = Object.entries(FEEDBACK_WEIGHT).map(([key, weight]) => [key, { weight }]);
+  return caseSql(expr, entries, 'weight', 0);
+}
+
+function memoryTypeOf(record = {}) {
+  return record.memoryType || record.memory_type || record.type || 'memory';
+}
+
+function memorySummaryText(record = {}) {
+  return String(record.summary || record.summaryText || record.title || '').replace(/\s+/g, ' ').trim();
+}
+
+function assistantShapingMetadata(record = {}) {
+  const payload = record.payload && typeof record.payload === 'object' ? record.payload : {};
+  const entries = [
+    ['policy', payload.policyKey || payload.policy_key || record.policyKey || record.policy_key],
+    ['kind', payload.shapingKind || payload.shaping_kind || payload.kind || payload.category || record.shapingKind || record.shaping_kind],
+    ['impact', payload.servingImpact || payload.serving_impact || payload.impact || record.servingImpact || record.serving_impact],
+  ];
+  return entries
+    .map(([key, value]) => [key, String(value || '').trim()])
+    .filter(([, value]) => value);
+}
+
+function formatRuntimeMemoryLine(record = {}, opts = {}) {
+  const type = memoryTypeOf(record);
+  const label = opts.localizedLabel === true ? memoryTypeLabel(type) : type;
+  const attrs = [];
+  const scope = record.scopeKey || record.scope_key;
+  const authority = record.authority;
+  const confidence = record.confidence || record.payload?.confidence || record.payload?.currentMemoryConfidence;
+  if (opts.includeScope === true && scope) attrs.push(`scope=${scope}`);
+  if (opts.includeAuthority === true && authority) attrs.push(`authority=${authority}`);
+  if (opts.includeConfidence === true && confidence) attrs.push(`confidence=${confidence}`);
+  const suffix = attrs.length > 0 ? ` ${attrs.join(' ')}` : '';
+  const metadata = type === 'assistant_shaping'
+    ? assistantShapingMetadata(record).map(([key, value]) => `${key}=${value}`).join(' ')
+    : '';
+  const metadataSuffix = metadata ? ` (${metadata})` : '';
+  return `- ${label}${suffix}: ${memorySummaryText(record)}${metadataSuffix}`;
+}
+
+function assistantShapingKindAllowed(value) {
+  return ASSISTANT_SHAPING_KINDS.includes(normalizeToken(value));
+}
+
+function assistantShapingServingImpactAllowed(value) {
+  const token = normalizeToken(value);
+  return assistantShapingServingImpactKnown(token)
+    || /^(changes|sets|routes|selects|filters|prioritizes|suppresses)_[a-z0-9_]+$/.test(token);
+}
+
+function assistantShapingServingImpactKnown(value) {
+  return ASSISTANT_SHAPING_SERVING_IMPACTS.includes(normalizeToken(value));
+}
+
+function assistantShapingPromptLines() {
+  return ASSISTANT_SHAPING_PROMPT_LINES.slice();
+}
+
+module.exports = {
+  ASSISTANT_SHAPING_KINDS,
+  ASSISTANT_SHAPING_SERVING_IMPACTS,
+  AUTHORITY_POLICY,
+  FEEDBACK_WEIGHT,
+  MEMORY_TYPE_POLICY,
+  activeMemoryTypes,
+  assistantShapingKindAllowed,
+  assistantShapingMetadata,
+  assistantShapingPromptLines,
+  assistantShapingServingImpactAllowed,
+  assistantShapingServingImpactKnown,
+  authoritySortPriority,
+  authoritySortPrioritySql,
+  authorityStrength,
+  defaultAspectForMemoryType,
+  defaultInheritanceForMemoryType,
+  feedbackWeight,
+  feedbackWeightSql,
+  formatRuntimeMemoryLine,
+  isActiveMemoryType,
+  memorySummaryText,
+  memoryTypeBootstrapPriority,
+  memoryTypeBootstrapPrioritySql,
+  memoryTypeLabel,
+  memoryTypeOf,
+  memoryTypePolicy,
+  memoryTypeRecallRank,
+  memoryTypeRecallRankSql,
+  memoryTypeRuntimeContract,
+};

package/core/operator-observability.js

@@ -0,0 +1,249 @@
+'use strict';
+
+function parseJsonObject(value, fallback = {}) {
+  if (value === null || value === undefined) return fallback;
+  if (typeof value === 'string') {
+    try {
+      const parsed = JSON.parse(value);
+      return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : fallback;
+    } catch {
+      return fallback;
+    }
+  }
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : fallback;
+}
+
+function rowTime(value) {
+  if (!value) return null;
+  const parsed = new Date(value);
+  return isNaN(parsed.getTime()) ? String(value) : parsed.toISOString();
+}
+
+function summarizeCompactionRun(row = {}) {
+  const output = parseJsonObject(row.output, {});
+  const plan = output.plan || output;
+  const candidates = Array.isArray(plan.candidates) ? plan.candidates : [];
+  const statusUpdates = Array.isArray(plan.statusUpdates || plan.status_updates)
+    ? (plan.statusUpdates || plan.status_updates)
+    : [];
+  return {
+    id: row.id,
+    kind: 'compaction',
+    status: row.status,
+    cadence: row.cadence,
+    periodStart: row.period_start,
+    periodEnd: row.period_end,
+    policyVersion: row.policy_version || null,
+    workerId: row.worker_id || null,
+    claimedAt: rowTime(row.claimed_at),
+    leaseExpiresAt: rowTime(row.lease_expires_at),
+    appliedAt: rowTime(row.applied_at),
+    reclaimedAt: rowTime(row.reclaimed_at),
+    error: row.error || null,
+    sourceCoverage: parseJsonObject(row.source_coverage, {}),
+    outputCoverage: parseJsonObject(row.output_coverage, {}),
+    candidateCount: candidates.length,
+    statusUpdateCount: statusUpdates.length,
+    createdAt: rowTime(row.created_at),
+    updatedAt: rowTime(row.updated_at),
+  };
+}
+
+function summarizeCheckpointRun(row = {}, sourceCount = 0) {
+  const payload = parseJsonObject(row.checkpoint_payload, {});
+  return {
+    id: row.id,
+    kind: 'checkpoint',
+    status: row.status,
+    scopeId: row.scope_id,
+    checkpointKey: row.checkpoint_key,
+    fromFinalizationIdExclusive: row.from_finalization_id_exclusive,
+    toFinalizationIdInclusive: row.to_finalization_id_inclusive,
+    windowStart: rowTime(row.window_start),
+    windowEnd: rowTime(row.window_end),
+    claimedAt: rowTime(row.claimed_at),
+    finalizedAt: rowTime(row.finalized_at),
+    error: row.error || null,
+    sourceCount,
+    checkpointPayloadKeys: Object.keys(payload).sort(),
+    createdAt: rowTime(row.created_at),
+    updatedAt: rowTime(row.updated_at),
+  };
+}
+
+function sourceValue(row = {}, key) {
+  const metadata = parseJsonObject(row.metadata, {});
+  return row[key] ?? metadata[key] ?? null;
+}
+
+function tableMissingError(error) {
+  return error && error.code === '42P01';
+}
+
+function createOperatorObservability({ pool, schema, defaultTenantId = 'default' }) {
+  async function compactionStatus(input = {}) {
+    const tenantId = input.tenantId || defaultTenantId;
+    const limit = Math.max(1, Math.min(50, input.limit || 10));
+    try {
+      const [latest, stale, counts] = await Promise.all([
+        pool.query(
+          `SELECT *
+             FROM ${schema}.compaction_runs
+            WHERE tenant_id = $1
+            ORDER BY COALESCE(applied_at, created_at) DESC, id DESC
+            LIMIT $2`,
+          [tenantId, limit],
+        ),
+        pool.query(
+          `SELECT *
+             FROM ${schema}.compaction_runs
+            WHERE tenant_id = $1
+              AND status = 'applying'
+              AND lease_expires_at IS NOT NULL
+              AND lease_expires_at < transaction_timestamp()
+            ORDER BY lease_expires_at ASC, id ASC
+            LIMIT $2`,
+          [tenantId, limit],
+        ),
+        pool.query(
+          `SELECT status, COUNT(*)::int AS count
+             FROM ${schema}.compaction_runs
+            WHERE tenant_id = $1
+            GROUP BY status`,
+          [tenantId],
+        ),
+      ]);
+      return {
+        available: true,
+        latest: latest.rows.map(summarizeCompactionRun),
+        staleClaims: stale.rows.map(summarizeCompactionRun),
+        statusCounts: Object.fromEntries(counts.rows.map(row => [row.status, row.count])),
+      };
+    } catch (error) {
+      if (tableMissingError(error)) {
+        return { available: false, latest: [], staleClaims: [], statusCounts: {}, error: 'compaction_runs table is missing' };
+      }
+      throw error;
+    }
+  }
+
+  async function checkpointStatus(input = {}) {
+    const tenantId = input.tenantId || defaultTenantId;
+    const limit = Math.max(1, Math.min(50, input.limit || 10));
+    try {
+      const [latest, counts] = await Promise.all([
+        pool.query(
+          `SELECT c.*, COUNT(s.id)::int AS source_count
+             FROM ${schema}.checkpoint_runs c
+             LEFT JOIN ${schema}.checkpoint_run_sources s
+               ON s.tenant_id = c.tenant_id
+              AND s.checkpoint_run_id = c.id
+            WHERE c.tenant_id = $1
+            GROUP BY c.id
+            ORDER BY c.updated_at DESC, c.id DESC
+            LIMIT $2`,
+          [tenantId, limit],
+        ),
+        pool.query(
+          `SELECT status, COUNT(*)::int AS count
+             FROM ${schema}.checkpoint_runs
+            WHERE tenant_id = $1
+            GROUP BY status`,
+          [tenantId],
+        ),
+      ]);
+      return {
+        available: true,
+        latest: latest.rows.map(row => summarizeCheckpointRun(row, row.source_count || 0)),
+        statusCounts: Object.fromEntries(counts.rows.map(row => [row.status, row.count])),
+      };
+    } catch (error) {
+      if (tableMissingError(error)) {
+        return { available: false, latest: [], statusCounts: {}, error: 'checkpoint_runs table is missing' };
+      }
+      throw error;
+    }
+  }
+
+  async function status(input = {}) {
+    const [compaction, checkpoint] = await Promise.all([
+      compactionStatus(input),
+      checkpointStatus(input),
+    ]);
+    return {
+      readOnly: true,
+      compaction,
+      checkpoint,
+    };
+  }
+
+  async function inspect(input = {}) {
+    const tenantId = input.tenantId || defaultTenantId;
+    const runId = input.runId || input.id;
+    if (!runId) throw new Error('runId is required');
+    const kind = input.kind || 'compaction';
+    if (kind === 'compaction') {
+      const result = await pool.query(
+        `SELECT *
+           FROM ${schema}.compaction_runs
+          WHERE tenant_id = $1
+            AND id = $2
+          LIMIT 1`,
+        [tenantId, runId],
+      );
+      if (!result.rows[0]) throw new Error('Compaction run not found');
+      return {
+        readOnly: true,
+        run: summarizeCompactionRun(result.rows[0]),
+      };
+    }
+    if (kind === 'checkpoint') {
+      const [run, sources] = await Promise.all([
+        pool.query(
+          `SELECT *
+             FROM ${schema}.checkpoint_runs
+            WHERE tenant_id = $1
+              AND id = $2
+            LIMIT 1`,
+          [tenantId, runId],
+        ),
+        pool.query(
+          `SELECT id, finalization_id, source_index, session_id, transcript_hash, finalized_at, metadata
+             FROM ${schema}.checkpoint_run_sources
+            WHERE tenant_id = $1
+              AND checkpoint_run_id = $2
+            ORDER BY source_index ASC, id ASC`,
+          [tenantId, runId],
+        ),
+      ]);
+      if (!run.rows[0]) throw new Error('Checkpoint run not found');
+      return {
+        readOnly: true,
+        run: summarizeCheckpointRun(run.rows[0], sources.rows.length),
+        sources: sources.rows.map(row => ({
+          id: row.id,
+          finalizationId: row.finalization_id,
+          sourceIndex: row.source_index,
+          sessionId: row.session_id,
+          agentId: sourceValue(row, 'agentId') || sourceValue(row, 'agent_id'),
+          source: sourceValue(row, 'source'),
+          status: sourceValue(row, 'status'),
+          transcriptHashPrefix: row.transcript_hash ? String(row.transcript_hash).slice(0, 12) : null,
+          finalizedAt: rowTime(row.finalized_at),
+        })),
+      };
+    }
+    throw new Error('kind must be compaction or checkpoint');
+  }
+
+  return {
+    status,
+    inspect,
+  };
+}
+
+module.exports = {
+  createOperatorObservability,
+  summarizeCompactionRun,
+  summarizeCheckpointRun,
+};

package/core/postgres-migrations.js

@@ -81,6 +81,26 @@ const MIGRATION_PLAN = [
       { table: 'finalization_candidates', column: 'candidate_hash' },
     ],
   },
+  {
+    id: '019-v1-memory-review-resolutions',
+    file: '019-v1-memory-review-resolutions.sql',
+    always: true,
+    signature: [
+      'memory_review_resolutions',
+      { index: 'idx_memory_review_resolutions_memory_latest' },
+      { index: 'idx_memory_review_resolutions_canonical_latest' },
+      { index: 'idx_memory_review_resolutions_defer_until' },
+      { index: 'idx_feedback_memory_review_latest' },
+    ],
+  },
+  {
+    id: '020-v1-assistant-shaping-memory',
+    file: '020-v1-assistant-shaping-memory.sql',
+    always: true,
+    signature: [
+      { index: 'idx_memory_records_assistant_shaping_bootstrap' },
+    ],
+  },
 ];
 
 function createPostgresMigrationRuntime(opts = {}) {
@@ -296,6 +316,8 @@ function createPostgresMigrationRuntime(opts = {}) {
           ['016-v1-evidence-ref-multi-item.sql', '016-v1-evidence-ref-multi-item'],
           ['017-v1-memory-record-embeddings.sql', '017-v1-memory-record-embeddings'],
           ['018-v1-finalization-candidate-envelope.sql', '018-v1-finalization-candidate-envelope'],
+          ['019-v1-memory-review-resolutions.sql', '019-v1-memory-review-resolutions'],
+          ['020-v1-assistant-shaping-memory.sql', '020-v1-assistant-shaping-memory'],
         ]) {
           await client.query(loadSql(migration[0], schema));
           ddlExecuted.push(migration[1]);