@shadowforge0/aquifer-memory 1.8.1 → 1.9.0

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/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,18 @@ 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' },
+    ],
+  },
 ];
 
 function createPostgresMigrationRuntime(opts = {}) {
@@ -296,6 +308,7 @@ 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'],
         ]) {
           await client.query(loadSql(migration[0], schema));
           ddlExecuted.push(migration[1]);

package/core/session-finalization.js

@@ -6,6 +6,7 @@ const { createMemoryRecords } = require('./memory-records');
 const { createMemoryPromotion } = require('./memory-promotion');
 const { sanitizeSummaryResult } = require('./memory-safety-gate');
 const { buildFinalizationReview, buildSessionStartContext } = require('./finalization-review');
+const { buildFinalizationInspection } = require('./finalization-inspector');
 
 function qi(identifier) { return `"${identifier}"`; }
 
@@ -15,6 +16,13 @@ function requireField(obj, field) {
   }
 }
 
+function finalizationReadError(error) {
+  if (error && error.code === '42P01') {
+    return new Error('Finalization observability tables are not available. Run `aquifer migrate`, then retry this read-only command.');
+  }
+  return error;
+}
+
 function hasStructuredContent(value) {
   return value && typeof value === 'object' && Object.keys(value).length > 0;
 }
@@ -190,7 +198,73 @@ function createSessionFinalization({
 
   async function list(input = {}) {
     const tenantId = input.tenantId || defaultTenantId || 'default';
-    return storage.listSessionFinalizations(pool, input, { schema, tenantId });
+    try {
+      return await storage.listSessionFinalizations(pool, input, { schema, tenantId });
+    } catch (error) {
+      throw finalizationReadError(error);
+    }
+  }
+
+  async function inspect(input = {}) {
+    const tenantId = input.tenantId || defaultTenantId || 'default';
+    let row = null;
+
+    try {
+      if (input.id) {
+        row = await storage.getSessionFinalizationById(pool, {
+          tenantId,
+          id: input.id,
+        }, { schema, tenantId });
+      } else {
+        requireField(input, 'sessionId');
+        requireField(input, 'agentId');
+        requireField(input, 'source');
+        const phase = input.phase || 'curated_memory_v1';
+        if (input.transcriptHash) {
+          row = await storage.getSessionFinalization(pool, {
+            tenantId,
+            sessionId: input.sessionId,
+            agentId: input.agentId,
+            source: input.source,
+            transcriptHash: input.transcriptHash,
+            phase,
+          }, { schema, tenantId });
+        } else {
+          const rows = await storage.listSessionFinalizations(pool, {
+            tenantId,
+            sessionId: input.sessionId,
+            agentId: input.agentId,
+            source: input.source,
+            phase,
+            limit: 2,
+          }, { schema, tenantId });
+          if (rows.length > 1) {
+            const matches = rows.map(match => {
+              const hash = match.transcript_hash ? String(match.transcript_hash).slice(0, 12) : '?';
+              const updatedAt = match.updated_at || '?';
+              return `#${match.id} status=${match.status} phase=${match.phase} hash=${hash} updated=${updatedAt}`;
+            }).join('; ');
+            throw new Error(`Multiple finalizations matched. Add --transcript-hash or --id to inspect one row. Matches: ${matches}`);
+          }
+          row = rows[0] || null;
+        }
+      }
+
+      if (!row) throw new Error('Finalization not found');
+      const [candidates, lineage] = await Promise.all([
+        storage.listFinalizationCandidates(pool, {
+          tenantId,
+          finalizationId: row.id,
+        }, { schema, tenantId }),
+        storage.getFinalizationLineageSummary(pool, {
+          tenantId,
+          finalizationId: row.id,
+        }, { schema, tenantId }),
+      ]);
+      return buildFinalizationInspection(row, candidates, lineage);
+    } catch (error) {
+      throw finalizationReadError(error);
+    }
   }
 
   async function updateStatus(input = {}) {
@@ -436,6 +510,7 @@ function createSessionFinalization({
     createTask,
     get,
     list,
+    inspect,
     updateStatus,
     finalizeSession,
   };

package/core/storage.js

@@ -614,6 +614,20 @@ async function getSessionFinalization(pool, input = {}, { schema, tenantId: defa
   return result.rows[0] || null;
 }
 
+async function getSessionFinalizationById(pool, input = {}, { schema, tenantId: defaultTenantId } = {}) {
+  requireField(input, 'id');
+  const tenantId = input.tenantId || defaultTenantId || 'default';
+  const result = await pool.query(
+    `SELECT *
+       FROM ${qi(schema)}.session_finalizations
+      WHERE tenant_id = $1
+        AND id = $2
+      LIMIT 1`,
+    [tenantId, input.id]
+  );
+  return result.rows[0] || null;
+}
+
 async function updateSessionFinalizationStatus(pool, input = {}, { schema, tenantId: defaultTenantId } = {}) {
   const status = normalizeFinalizationStatus(input.status);
   const tenantId = input.tenantId || defaultTenantId || 'default';
@@ -660,38 +674,137 @@ async function updateSessionFinalizationStatus(pool, input = {}, { schema, tenan
 
 async function listSessionFinalizations(pool, input = {}, { schema, tenantId: defaultTenantId } = {}) {
   const tenantId = input.tenantId || defaultTenantId || 'default';
+  const table = `${qi(schema)}.session_finalizations`;
   const params = [tenantId];
-  const where = [`tenant_id = $1`];
+  const where = [`${table}.tenant_id = $1`];
   if (input.host) {
     params.push(input.host);
-    where.push(`host = $${params.length}`);
+    where.push(`${table}.host = $${params.length}`);
   }
   if (input.status) {
     const statuses = Array.isArray(input.status) ? input.status : [input.status];
     for (const status of statuses) normalizeFinalizationStatus(status);
     params.push(statuses);
-    where.push(`status = ANY($${params.length}::text[])`);
+    where.push(`${table}.status = ANY($${params.length}::text[])`);
   }
   if (input.agentId) {
     params.push(input.agentId);
-    where.push(`agent_id = $${params.length}`);
+    where.push(`${table}.agent_id = $${params.length}`);
   }
   if (input.source) {
     params.push(input.source);
-    where.push(`source = $${params.length}`);
+    where.push(`${table}.source = $${params.length}`);
+  }
+  if (input.sessionId) {
+    params.push(input.sessionId);
+    where.push(`${table}.session_id = $${params.length}`);
+  }
+  if (input.transcriptHash) {
+    params.push(input.transcriptHash);
+    where.push(`${table}.transcript_hash = $${params.length}`);
+  }
+  if (input.phase) {
+    params.push(input.phase);
+    where.push(`${table}.phase = $${params.length}`);
+  }
+  if (input.mode) {
+    params.push(normalizeFinalizationMode(input.mode));
+    where.push(`${table}.mode = $${params.length}`);
   }
   params.push(Math.max(1, Math.min(200, input.limit || 50)));
   const result = await pool.query(
-    `SELECT *
-       FROM ${qi(schema)}.session_finalizations
+    `SELECT
+        ${table}.id,
+        ${table}.tenant_id,
+        ${table}.source,
+        ${table}.host,
+        ${table}.agent_id,
+        ${table}.session_id,
+        ${table}.transcript_hash,
+        ${table}.phase,
+        ${table}.mode,
+        ${table}.status,
+        ${table}.finalizer_model,
+        ${table}.scope_kind,
+        ${table}.scope_key,
+        ${table}.context_key,
+        ${table}.topic_key,
+        ${table}.candidate_envelope_hash,
+        ${table}.candidate_envelope_version,
+        ${table}.error,
+        ${table}.claimed_at,
+        ${table}.finalized_at,
+        ${table}.created_at,
+        ${table}.updated_at,
+        (
+          SELECT COUNT(*)::int
+            FROM ${qi(schema)}.finalization_candidates fc
+           WHERE fc.tenant_id = ${table}.tenant_id
+             AND fc.finalization_id = ${table}.id
+        ) AS candidate_count
+       FROM ${table}
       WHERE ${where.join(' AND ')}
-      ORDER BY updated_at DESC, id DESC
+      ORDER BY ${table}.updated_at DESC, ${table}.id DESC
       LIMIT $${params.length}`,
     params
   );
   return result.rows;
 }
 
+async function getFinalizationLineageSummary(pool, input = {}, { schema, tenantId: defaultTenantId } = {}) {
+  requireField(input, 'finalizationId');
+  const tenantId = input.tenantId || defaultTenantId || 'default';
+  const result = await pool.query(
+    `SELECT
+       COALESCE((
+         SELECT array_agg(id ORDER BY id)
+           FROM ${qi(schema)}.memory_records
+          WHERE tenant_id = $1
+            AND created_by_finalization_id = $2
+       ), ARRAY[]::bigint[]) AS memory_record_ids,
+       COALESCE((
+         SELECT array_agg(id ORDER BY id)
+           FROM ${qi(schema)}.fact_assertions_v1
+          WHERE tenant_id = $1
+            AND created_by_finalization_id = $2
+       ), ARRAY[]::bigint[]) AS fact_assertion_ids,
+       COALESCE((
+         SELECT COUNT(*)::int
+           FROM ${qi(schema)}.evidence_refs
+          WHERE tenant_id = $1
+            AND created_by_finalization_id = $2
+       ), 0) AS evidence_ref_count,
+       COALESCE((
+         SELECT COUNT(*)::int
+           FROM ${qi(schema)}.evidence_items
+          WHERE tenant_id = $1
+            AND created_by_finalization_id = $2
+       ), 0) AS evidence_item_count`,
+    [tenantId, input.finalizationId]
+  );
+  const row = result.rows[0] || {};
+  return {
+    memoryRecordIds: row.memory_record_ids || [],
+    factAssertionIds: row.fact_assertion_ids || [],
+    evidenceRefCount: row.evidence_ref_count || 0,
+    evidenceItemCount: row.evidence_item_count || 0,
+  };
+}
+
+async function listFinalizationCandidates(pool, input = {}, { schema, tenantId: defaultTenantId } = {}) {
+  requireField(input, 'finalizationId');
+  const tenantId = input.tenantId || defaultTenantId || 'default';
+  const result = await pool.query(
+    `SELECT *
+       FROM ${qi(schema)}.finalization_candidates
+      WHERE tenant_id = $1
+        AND finalization_id = $2
+      ORDER BY candidate_index ASC, id ASC`,
+    [tenantId, input.finalizationId]
+  );
+  return result.rows;
+}
+
 function candidateText(candidate = {}) {
   if (typeof candidate === 'string') return candidate.trim();
   const payload = candidate.payload && typeof candidate.payload === 'object' ? candidate.payload : null;
@@ -1236,8 +1349,11 @@ module.exports = {
   recordAccess,
   upsertSessionFinalization,
   getSessionFinalization,
+  getSessionFinalizationById,
   updateSessionFinalizationStatus,
   listSessionFinalizations,
+  getFinalizationLineageSummary,
+  listFinalizationCandidates,
   upsertCheckpointRun,
   updateCheckpointRunStatus,
   listCheckpointRuns,