@shadowforge0/aquifer-memory 1.8.1 → 1.9.1

package/core/aquifer.js

@@ -14,11 +14,243 @@ const { createMemoryServingRuntime } = require('./memory-serving');
 const { createLegacyBootstrap } = require('./legacy-bootstrap');
 const { buildRerankDocument, resolveEmbedFn, shouldAutoRerank } = require('./recall-runtime');
 const { filterPublicPlaceholderSessionRows } = require('./public-session-filter');
+const { buildBacklogProductStatus, buildReadinessSurface } = require('./interface');
 
 // ---------------------------------------------------------------------------
 // createAquifer
 // ---------------------------------------------------------------------------
 
+const ACTIONABLE_PENDING_STATUSES = new Set(['pending', 'failed']);
+const TERMINAL_FINALIZATION_STATUSES = ['finalized', 'skipped', 'declined', 'deferred'];
+
+function normalizePendingWorkLimit(value, fallback = 100, max = 500) {
+  const parsed = parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) return fallback;
+  return Math.min(parsed, max);
+}
+
+function normalizePendingWorkStatuses(value) {
+  const input = Array.isArray(value)
+    ? value
+    : String(value || '').split(',');
+  const statuses = input.map(item => String(item || '').trim()).filter(Boolean);
+  const normalized = statuses.length > 0 ? statuses : Array.from(ACTIONABLE_PENDING_STATUSES);
+  for (const status of normalized) {
+    if (!ACTIONABLE_PENDING_STATUSES.has(status)) {
+      throw new Error(`pending work status must be one of: ${Array.from(ACTIONABLE_PENDING_STATUSES).join(', ')}`);
+    }
+  }
+  return [...new Set(normalized)];
+}
+
+function normalizePendingWorkAction(value) {
+  const action = String(value || 'inspect').trim();
+  if (!['inspect', 'backfill', 'skip'].includes(action)) {
+    throw new Error('pending work action must be inspect, backfill, or skip');
+  }
+  return action;
+}
+
+function pluralize(count, singular, plural = `${singular}s`) {
+  return count === 1 ? singular : plural;
+}
+
+function normalizePendingWorkRow(row = {}) {
+  return {
+    sessionId: row.session_id,
+    sessionKey: row.session_key || null,
+    source: row.source || 'api',
+    agentId: row.agent_id,
+    status: row.processing_status,
+    processingError: row.processing_error || null,
+    startedAt: row.started_at || null,
+    lastMessageAt: row.last_message_at || null,
+    msgCount: row.msg_count || 0,
+    userCount: row.user_count || 0,
+    model: row.model || null,
+  };
+}
+
+function normalizePendingWorkGroup(row = {}) {
+  return {
+    source: row.source || 'api',
+    agentId: row.agent_id,
+    status: row.processing_status,
+    count: row.count || 0,
+    earliest: row.earliest || null,
+    latest: row.latest || null,
+    msgCount: row.msg_count || 0,
+    userCount: row.user_count || 0,
+  };
+}
+
+function buildPendingWorkGuidance(groups = []) {
+  const statuses = new Set(groups.map(group => group.status));
+  const guidance = [];
+  if (statuses.has('pending')) {
+    guidance.push({
+      status: 'pending',
+      recommendedAction: 'backfill',
+      alternateAction: 'skip',
+      reason: 'Pending sessions can be enriched; skip is reserved for deterministic policy suppression.',
+    });
+  }
+  if (statuses.has('failed')) {
+    guidance.push({
+      status: 'failed',
+      recommendedAction: 'backfill',
+      alternateAction: 'inspect_error',
+      reason: 'Failed sessions are retryable work; session skip only mutates rows still in pending status.',
+    });
+  }
+  return guidance;
+}
+
+function buildPendingWorkPlan(samples = [], action = 'inspect', groups = []) {
+  const totalByStatus = {};
+  for (const group of groups || []) {
+    totalByStatus[group.status] = (totalByStatus[group.status] || 0) + (group.count || 0);
+  }
+  const plan = {
+    action,
+    dryRunOnly: true,
+    allowed: 0,
+    blocked: 0,
+    changes: [],
+    notes: [],
+  };
+  if (action === 'inspect') {
+    plan.notes.push('No lifecycle changes planned.');
+    return plan;
+  }
+  if (action === 'backfill') {
+    plan.allowed = Object.values(totalByStatus).reduce((sum, count) => sum + count, 0);
+  } else if (action === 'skip') {
+    plan.allowed = totalByStatus.pending || 0;
+    plan.blocked = totalByStatus.failed || 0;
+  }
+  for (const row of samples) {
+    if (action === 'backfill') {
+      plan.changes.push({
+        sessionId: row.sessionId,
+        source: row.source,
+        agentId: row.agentId,
+        status: row.status,
+        operation: 'enrich',
+        allowed: true,
+      });
+      continue;
+    }
+    if (action === 'skip' && row.status === 'pending') {
+      plan.changes.push({
+        sessionId: row.sessionId,
+        source: row.source,
+        agentId: row.agentId,
+        status: row.status,
+        operation: 'mark_session_skipped',
+        allowed: true,
+      });
+      continue;
+    }
+    plan.changes.push({
+      sessionId: row.sessionId,
+      source: row.source,
+      agentId: row.agentId,
+      status: row.status,
+      operation: action,
+      allowed: false,
+      reason: action === 'skip'
+        ? 'skip only applies to pending sessions; failed sessions should be retried or suppressed through an explicit terminal policy'
+        : 'unsupported action',
+    });
+  }
+  if (action === 'skip' && plan.blocked > 0) {
+    plan.notes.push(`${plan.blocked} failed row(s) are intentionally blocked from skip. Filter to --status pending before applying skip.`);
+  }
+  return plan;
+}
+
+function buildPendingWorkDecision(groups = []) {
+  const statusCounts = {};
+  for (const group of groups || []) {
+    statusCounts[group.status] = (statusCounts[group.status] || 0) + (group.count || 0);
+  }
+  const publicStatus = buildBacklogProductStatus({ statusCounts });
+  return {
+    status: publicStatus.code === 'clear'
+      ? 'clear'
+      : publicStatus.code === 'recoverable'
+        ? 'recoverable'
+        : 'attention',
+    summary: publicStatus.headline,
+    nextStep: publicStatus.action,
+    statusCounts,
+    publicStatus,
+  };
+}
+
+function buildReadiness(stats = {}) {
+  const servingMode = stats.serving?.mode || 'legacy';
+  const activeScopePath = Array.isArray(stats.serving?.activeScopePath)
+    ? stats.serving.activeScopePath
+    : [];
+  const memoryRecords = stats.memoryRecords || {};
+  const pendingTotal = stats.pendingSessions?.total || 0;
+  const hasHistoricalMemory = (stats.summaries || 0) > 0 || (stats.turnEmbeddings || 0) > 0;
+  const currentEnabled = servingMode === 'curated';
+  const activeCurrentRows = memoryRecords.available ? (memoryRecords.active || 0) : 0;
+  const currentReady = currentEnabled && activeCurrentRows > 0;
+  const currentEmpty = currentEnabled && activeCurrentRows === 0;
+  const activeScopeReady = currentEnabled && activeScopePath.length > 0 && !(activeScopePath.length === 1 && activeScopePath[0] === 'global');
+
+  const checks = [
+    {
+      key: 'backend',
+      status: 'ready',
+      label: 'Service',
+      message: 'Aquifer is online.',
+    },
+    {
+      key: 'historical_memory',
+      status: hasHistoricalMemory ? 'ready' : 'empty',
+      label: 'Saved content',
+      message: hasHistoricalMemory
+        ? 'Saved content is available.'
+        : 'No saved content is available yet.',
+    },
+    {
+      key: 'current_memory',
+      status: currentReady ? 'ready' : currentEmpty ? 'empty' : 'not_enabled',
+      label: 'Memory',
+      message: currentReady
+        ? `Memory has ${activeCurrentRows} active row(s).`
+        : currentEmpty
+          ? 'Memory is enabled, but no active rows are available yet.'
+          : 'Memory is still getting ready.',
+    },
+    {
+      key: 'active_scope',
+      status: activeScopeReady ? 'ready' : currentEnabled ? 'attention' : 'not_enabled',
+      label: 'App link',
+      message: activeScopeReady
+        ? `Memory is linked through ${activeScopePath.join(' > ')}.`
+        : currentEnabled
+          ? 'Memory is not linked to this app yet.'
+          : 'Memory link is not active yet.',
+    },
+    {
+      key: 'backlog',
+      status: pendingTotal > 0 ? 'attention' : 'ready',
+      label: 'Saved content',
+      message: pendingTotal > 0
+        ? `${pendingTotal} saved-content ${pluralize(pendingTotal, 'item')} still need attention.`
+        : 'Saved content is ready.',
+    },
+  ];
+
+  return buildReadinessSurface(stats, { checks });
+}
+
 function createAquifer(config = {}) {
   const backendKind = normalizeBackendKind(config.backend?.kind || config.storage?.backend || 'postgres');
   if (backendKind !== 'postgres') {
@@ -657,36 +889,34 @@ function createAquifer(config = {}) {
     // --- read path ---
 
     async memoryRecall(query, opts = {}) {
+      assertMemoryRecallQuery(query);
       memoryServing.assertCuratedRecallOpts(opts);
-      await ensureMigrated();
-      if (typeof query !== 'string' || query.trim().length === 0) {
-        throw new Error('memory.recall(query): query must be a non-empty string');
-      }
       const validModes = new Set(['fts', 'hybrid', 'vector']);
       const mode = opts.mode || 'hybrid';
       if (!validModes.has(mode)) {
         throw new Error(`Invalid curated recall mode: "${mode}". Must be one of: fts, hybrid, vector`);
       }
+      if (mode === 'vector' && !embedFn) {
+        throw new Error('curated memory_recall mode=vector requires config.embed.fn or EMBED_PROVIDER env');
+      }
+      const scopedOpts = memoryServing.withDefaultScope(opts);
+      await ensureMigrated();
       let queryVec = null;
-      if (mode === 'hybrid' || mode === 'vector') {
-        if (!embedFn) {
-          if (mode === 'vector') {
-            throw new Error('curated memory_recall mode=vector requires config.embed.fn or EMBED_PROVIDER env');
-          }
-        } else {
+      if ((mode === 'hybrid' || mode === 'vector') && embedFn) {
           const embedded = await embedFn([query]);
           queryVec = Array.isArray(embedded) && Array.isArray(embedded[0]) ? embedded[0] : null;
           if (!queryVec && mode === 'vector') throw new Error('embedFn returned empty vector for curated memory_recall');
-        }
       }
-      const scopedOpts = memoryServing.withDefaultScope(opts);
       const limit = Math.max(1, Math.min(50, scopedOpts.limit || 10));
       const runLexical = mode === 'fts' || mode === 'hybrid';
       const runVector = (mode === 'vector' || mode === 'hybrid') && queryVec;
       const [lexicalRows, embeddingRows] = await Promise.all([
         runLexical ? aquifer.memory.recall(query, {
           ...scopedOpts,
-          ftsConfig: migrationRuntime.getFtsConfig(),
+          // memory_records.search_tsv is generated with the stable simple config
+          // in schema/007, so curated memory_recall must query with the same
+          // config even when legacy session search selected a zh tokenizer.
+          ftsConfig: 'simple',
         }) : Promise.resolve([]),
         runVector ? aquifer.memory.recallViaMemoryEmbeddings(queryVec, scopedOpts) : Promise.resolve([]),
       ]);
@@ -1168,22 +1398,24 @@ function createAquifer(config = {}) {
     async skip(sessionId, opts = {}) {
       const agentId = opts.agentId || 'agent';
       const reason = opts.reason || null;
+      const source = opts.source || null;
       // Atomic CAS: only skip if still pending (avoids race with concurrent enrich)
       const result = await pool.query(
         `UPDATE ${qi(schema)}.sessions
         SET processing_status = 'skipped', processing_error = $1
         WHERE session_id = $2 AND agent_id = $3 AND tenant_id = $4
+          AND ($5::text IS NULL OR source = $5)
           AND processing_status = 'pending'
         RETURNING id`,
-        [reason, sessionId, agentId, tenantId]
+        [reason, sessionId, agentId, tenantId, source]
       );
       if (result.rows.length === 0) {
         // Check if session exists at all
-        const existing = await storage.getSession(pool, sessionId, agentId, {}, { schema, tenantId });
+        const existing = await storage.getSession(pool, sessionId, agentId, { source: source || undefined }, { schema, tenantId });
         if (!existing) throw new Error(`Session not found: ${sessionId} (agentId=${agentId})`);
         return null; // exists but not pending — no-op
       }
-      return { id: result.rows[0].id, sessionId, agentId, status: 'skipped' };
+      return { id: result.rows[0].id, sessionId, agentId, source, status: 'skipped' };
     },
 
     // --- public config accessor ---
@@ -1195,6 +1427,7 @@ function createAquifer(config = {}) {
         memoryServingMode: memoryServing.servingMode,
         memoryActiveScopeKey: memoryServing.defaultActiveScopeKey,
         memoryActiveScopePath: memoryServing.defaultActiveScopePath,
+        memoryAllowedScopeKeys: memoryServing.defaultAllowedScopeKeys,
         backendKind,
         backendProfile: backendInfo.profile,
         capabilities: backendInfo.capabilities,
@@ -1299,6 +1532,11 @@ function createAquifer(config = {}) {
         latestFinalizedAt: null,
         latestUpdatedAt: null,
       };
+      let pendingSessions = {
+        available: false,
+        total: null,
+        statuses: {},
+      };
       try {
         const finalizationResult = await pool.query(
           `SELECT
@@ -1327,15 +1565,47 @@ function createAquifer(config = {}) {
             .sort()
             .pop() || null,
         };
-      } catch { /* session_finalizations table may not exist on older installs */ }
+      } catch (err) {
+        if (err?.code !== '42P01') throw err;
+        /* session_finalizations table may not exist on older installs */
+      }
 
-      return {
+      try {
+        const actionablePending = await pool.query(
+          `SELECT s.processing_status, COUNT(*)::int AS count
+           FROM ${qi(schema)}.sessions s
+           WHERE s.tenant_id = $1
+             AND s.processing_status IN ('pending', 'failed')
+             AND NOT EXISTS (
+               SELECT 1
+               FROM ${qi(schema)}.session_finalizations f
+               WHERE f.tenant_id = s.tenant_id
+                 AND f.session_id = s.session_id
+                 AND f.agent_id = s.agent_id
+                 AND f.source = s.source
+                 AND f.status IN ('finalized', 'skipped', 'declined', 'deferred')
+             )
+           GROUP BY s.processing_status`,
+          [tenantId]
+        );
+        pendingSessions = {
+          available: true,
+          total: actionablePending.rows.reduce((sum, row) => sum + row.count, 0),
+          statuses: Object.fromEntries(actionablePending.rows.map(row => [row.processing_status, row.count])),
+        };
+      } catch (err) {
+        if (err?.code !== '42P01') throw err;
+        /* session_finalizations table may not exist on older installs */
+      }
+
+      const stats = {
         backendKind,
         backendProfile: backendInfo.profile,
         serving: {
           mode: memoryServing.servingMode,
           activeScopeKey: memoryServing.defaultActiveScopeKey,
           activeScopePath: memoryServing.defaultActiveScopePath,
+          allowedScopeKeys: memoryServing.defaultAllowedScopeKeys,
         },
         sessions: Object.fromEntries(sessions.rows.map(r => [r.processing_status, r.count])),
         sessionTotal: sessions.rows.reduce((s, r) => s + r.count, 0),
@@ -1344,22 +1614,175 @@ function createAquifer(config = {}) {
         entities: entityCount,
         memoryRecords,
         sessionFinalizations,
+        pendingSessions,
         earliest: timeRange.rows[0]?.earliest || null,
         latest: timeRange.rows[0]?.latest || null,
       };
+      return {
+        ...stats,
+        readiness: buildReadiness(stats),
+      };
+    },
+
+    async getPendingWork(opts = {}) {
+      const limit = normalizePendingWorkLimit(opts.limit, 100, 500);
+      const statuses = normalizePendingWorkStatuses(opts.statuses || opts.status);
+      const action = normalizePendingWorkAction(opts.action || opts.plan);
+      const filters = {
+        source: opts.source || null,
+        agentId: opts.agentId || null,
+        statuses,
+        limit,
+      };
+
+      const params = [tenantId, statuses];
+      const where = [
+        's.tenant_id = $1',
+        's.processing_status = ANY($2::text[])',
+      ];
+      if (filters.source) {
+        params.push(filters.source);
+        where.push(`s.source = $${params.length}`);
+      }
+      if (filters.agentId) {
+        params.push(filters.agentId);
+        where.push(`s.agent_id = $${params.length}`);
+      }
+
+      const terminalExclusion = `NOT EXISTS (
+        SELECT 1
+        FROM ${qi(schema)}.session_finalizations f
+        WHERE f.tenant_id = s.tenant_id
+          AND f.session_id = s.session_id
+          AND f.agent_id = s.agent_id
+          AND f.source = s.source
+          AND f.status = ANY($${params.length + 1}::text[])
+      )`;
+      const runQueries = async (excludeTerminal = true) => {
+        const queryParams = excludeTerminal ? [...params, TERMINAL_FINALIZATION_STATUSES] : params;
+        const whereSql = [...where, ...(excludeTerminal ? [terminalExclusion] : [])].join(' AND ');
+        const limitParam = queryParams.length + 1;
+        const [groupsResult, samplesResult] = await Promise.all([
+          pool.query(
+            `SELECT
+               COALESCE(s.source, 'api') AS source,
+               s.agent_id,
+               s.processing_status,
+               COUNT(*)::int AS count,
+               MIN(s.started_at) AS earliest,
+               MAX(s.started_at) AS latest,
+               COALESCE(SUM(s.msg_count), 0)::int AS msg_count,
+               COALESCE(SUM(s.user_count), 0)::int AS user_count
+             FROM ${qi(schema)}.sessions s
+             WHERE ${whereSql}
+             GROUP BY COALESCE(s.source, 'api'), s.agent_id, s.processing_status
+             ORDER BY COUNT(*) DESC, latest DESC`,
+            queryParams,
+          ),
+          pool.query(
+            `SELECT
+               s.session_id,
+               s.session_key,
+               COALESCE(s.source, 'api') AS source,
+               s.agent_id,
+               s.processing_status,
+               s.processing_error,
+               s.started_at,
+               s.last_message_at,
+               s.msg_count,
+               s.user_count,
+               s.model
+             FROM ${qi(schema)}.sessions s
+             WHERE ${whereSql}
+             ORDER BY s.started_at DESC
+             LIMIT $${limitParam}`,
+            [...queryParams, limit],
+          ),
+        ]);
+        return { groupsResult, samplesResult, terminalFiltering: excludeTerminal };
+      };
+
+      let result;
+      try {
+        result = await runQueries(true);
+      } catch (err) {
+        if (err?.code !== '42P01') throw err;
+        result = await runQueries(false);
+      }
+
+      const groups = result.groupsResult.rows.map(normalizePendingWorkGroup);
+      const samples = result.samplesResult.rows.map(normalizePendingWorkRow);
+      const total = groups.reduce((sum, group) => sum + group.count, 0);
+      const decision = buildPendingWorkDecision(groups);
+      return {
+        available: true,
+        generatedAt: new Date().toISOString(),
+        terminalFiltering: result.terminalFiltering,
+        filters,
+        total,
+        status: decision.status,
+        statusCounts: decision.statusCounts,
+        summary: decision.summary,
+        nextStep: decision.nextStep,
+        publicStatus: decision.publicStatus,
+        groups,
+        samples,
+        guidance: buildPendingWorkGuidance(groups),
+        plan: buildPendingWorkPlan(samples, action, groups),
+      };
     },
 
     async getPendingSessions(opts = {}) {
-      const limit = opts.limit !== undefined ? opts.limit : 100;
-      const result = await pool.query(
-        `SELECT session_id, agent_id, processing_status
-        FROM ${qi(schema)}.sessions
-        WHERE tenant_id = $1
-          AND processing_status IN ('pending', 'failed')
-        ORDER BY started_at DESC
-        LIMIT $2`,
-        [tenantId, limit]
-      );
+      const limit = normalizePendingWorkLimit(opts.limit, 100, 500);
+      const statuses = normalizePendingWorkStatuses(opts.statuses || opts.status);
+      const params = [tenantId, statuses];
+      const where = [
+        's.tenant_id = $1',
+        's.processing_status = ANY($2::text[])',
+      ];
+      if (opts.source) {
+        params.push(opts.source);
+        where.push(`s.source = $${params.length}`);
+      }
+      if (opts.agentId) {
+        params.push(opts.agentId);
+        where.push(`s.agent_id = $${params.length}`);
+      }
+      let result;
+      try {
+        const terminalParam = params.length + 1;
+        const limitParam = params.length + 2;
+        result = await pool.query(
+          `SELECT s.session_id, s.session_key, s.source, s.agent_id, s.processing_status,
+                  s.processing_error, s.started_at, s.last_message_at, s.msg_count, s.user_count, s.model
+           FROM ${qi(schema)}.sessions s
+           WHERE ${where.join(' AND ')}
+             AND NOT EXISTS (
+               SELECT 1
+               FROM ${qi(schema)}.session_finalizations f
+               WHERE f.tenant_id = s.tenant_id
+                 AND f.session_id = s.session_id
+                 AND f.agent_id = s.agent_id
+                 AND f.source = s.source
+                 AND f.status = ANY($${terminalParam}::text[])
+             )
+           ORDER BY s.started_at DESC
+           LIMIT $${limitParam}`,
+          [...params, TERMINAL_FINALIZATION_STATUSES, limit]
+        );
+      } catch (err) {
+        if (err?.code !== '42P01') throw err;
+        const limitParam = params.length + 1;
+        result = await pool.query(
+          `SELECT session_id, session_key, source, agent_id, processing_status,
+                  processing_error, started_at, last_message_at, msg_count, user_count, model
+          FROM ${qi(schema)}.sessions s
+          WHERE ${where.join(' AND ')}
+          ORDER BY started_at DESC
+          LIMIT $${limitParam}`,
+          [...params, limit]
+        );
+      }
       return result.rows;
     },
 
@@ -1386,9 +1809,10 @@ function createAquifer(config = {}) {
     },
 
     async memoryBootstrap(opts = {}) {
-      await ensureMigrated();
       memoryServing.assertCuratedBootstrapOpts(opts);
-      return aquifer.memory.bootstrap(memoryServing.withDefaultScope(opts));
+      const scopedOpts = memoryServing.withDefaultScope(opts);
+      await ensureMigrated();
+      return memoryBootstrap.bootstrap(scopedOpts);
     },
 
     async historicalBootstrap(opts = {}) {
@@ -1426,6 +1850,10 @@ function createAquifer(config = {}) {
   const { createMemoryConsolidation } = require('./memory-consolidation');
   const { createSessionFinalization } = require('./session-finalization');
   const { createSessionCheckpoints } = require('./session-checkpoints');
+  const { createOperatorObservability } = require('./operator-observability');
+  const { createDoctor } = require('./doctor');
+  const { createMemoryExplain } = require('./memory-explain');
+  const { createMemoryReview } = require('./memory-review');
   const qSchema = qi(schema);
   aquifer.narratives = createNarratives({ pool, schema: qSchema, defaultTenantId: tenantId });
   aquifer.timeline = createTimeline({ pool, schema: qSchema, defaultTenantId: tenantId });
@@ -1437,8 +1865,7 @@ function createAquifer(config = {}) {
   aquifer.consolidation = createConsolidation({ pool, schema: qSchema, defaultTenantId: tenantId });
   aquifer.bundles = createBundles({ pool, schema: qSchema, defaultTenantId: tenantId });
   // entityState materialises in schema/005-entity-state-history.sql, gated on
-  // entitiesEnabled (it FK-references entities). Drop-clean — see
-  // scripts/drop-entity-state-history.sql.
+  // entitiesEnabled because it FK-references entities.
   aquifer.entityState = createEntityState({ pool, schema: qSchema, defaultTenantId: tenantId });
   // insights materialises in schema/006-insights.sql. No FK from elsewhere
   // into this table; DROP CASCADE is clean. See scripts/drop-insights.sql.
@@ -1476,6 +1903,33 @@ function createAquifer(config = {}) {
     schema,
     defaultTenantId: tenantId,
   });
+  const operatorObservability = createOperatorObservability({
+    pool,
+    schema: qSchema,
+    defaultTenantId: tenantId,
+  });
+  const doctor = createDoctor({
+    pool,
+    schema,
+    recordsSchema: qSchema,
+    defaultTenantId: tenantId,
+    dbConfigured: Boolean(dbInput),
+    backendKind,
+    backendProfile: backendInfo.profile,
+    memoryServing,
+    listPendingMigrations: () => migrationRuntime.listPendingMigrations(),
+    operatorObservability,
+  });
+  const memoryExplain = createMemoryExplain({
+    pool,
+    schema: qSchema,
+    defaultTenantId: tenantId,
+  });
+  const memoryReview = createMemoryReview({
+    pool,
+    schema: qSchema,
+    defaultTenantId: tenantId,
+  });
 
   function currentMemoryScopeKeys(opts = {}) {
     if (Array.isArray(opts.activeScopePath) && opts.activeScopePath.length > 0) {
@@ -1485,6 +1939,12 @@ function createAquifer(config = {}) {
     return null;
   }
 
+  function assertMemoryRecallQuery(query) {
+    if (typeof query !== 'string' || query.trim().length === 0) {
+      throw new Error('memory.recall(query): query must be a non-empty string');
+    }
+  }
+
   // v1 curated-memory sidecar. Top-level recall/bootstrap can opt into this
   // plane through memory.servingMode while legacy/evidence mode remains
   // available for compatibility and debugging.
@@ -1520,21 +1980,25 @@ function createAquifer(config = {}) {
       return memoryPromotion.promote(candidates, opts);
     },
     bootstrap: async (opts = {}) => {
+      memoryServing.assertCuratedBootstrapOpts(opts);
+      const scopedOpts = memoryServing.withDefaultScope(opts);
       await ensureMigrated();
-      return memoryBootstrap.bootstrap(opts);
+      return memoryBootstrap.bootstrap(scopedOpts);
     },
     current: async (opts = {}) => {
+      const scopedOpts = memoryServing.withDefaultScope(opts);
       await ensureMigrated();
-      return memoryRecords.currentProjection(memoryServing.withDefaultScope(opts));
+      return memoryRecords.currentProjection(scopedOpts);
     },
     listCurrentMemory: async (opts = {}) => {
+      const scopedOpts = memoryServing.withDefaultScope(opts);
       await ensureMigrated();
-      return memoryRecords.currentProjection(memoryServing.withDefaultScope(opts));
+      return memoryRecords.currentProjection(scopedOpts);
     },
     backfillEmbeddings: async (opts = {}) => {
-      await ensureMigrated();
       requireEmbed('memory.backfillEmbeddings');
       const scopedOpts = memoryServing.withDefaultScope(opts);
+      await ensureMigrated();
       const listInput = {
         tenantId: scopedOpts.tenantId || tenantId,
         asOf: scopedOpts.asOf,
@@ -1611,20 +2075,39 @@ function createAquifer(config = {}) {
       };
     },
     recall: async (query, opts = {}) => {
+      assertMemoryRecallQuery(query);
+      memoryServing.assertCuratedRecallOpts(opts);
+      const scopedOpts = memoryServing.withDefaultScope(opts);
       await ensureMigrated();
-      return memoryRecall.recall(query, opts);
+      return memoryRecall.recall(query, scopedOpts);
     },
     recallViaEvidenceItems: async (query, opts = {}) => {
+      assertMemoryRecallQuery(query);
+      memoryServing.assertCuratedRecallOpts(opts);
+      const scopedOpts = memoryServing.withDefaultScope(opts);
       await ensureMigrated();
-      return memoryRecall.recallViaEvidenceItems(query, opts);
+      return memoryRecall.recallViaEvidenceItems(query, scopedOpts);
     },
     recallViaMemoryEmbeddings: async (queryVec, opts = {}) => {
+      memoryServing.assertCuratedRecallOpts(opts);
+      const scopedOpts = memoryServing.withDefaultScope(opts);
       await ensureMigrated();
-      return memoryRecall.recallViaMemoryEmbeddings(queryVec, opts);
+      return memoryRecall.recallViaMemoryEmbeddings(queryVec, scopedOpts);
     },
     recallViaLinkedSummaryEmbeddings: async (queryVec, opts = {}) => {
+      memoryServing.assertCuratedRecallOpts(opts);
+      const scopedOpts = memoryServing.withDefaultScope(opts);
       await ensureMigrated();
-      return memoryRecall.recallViaLinkedSummaryEmbeddings(queryVec, opts);
+      return memoryRecall.recallViaLinkedSummaryEmbeddings(queryVec, scopedOpts);
+    },
+    explainBootstrap: async (opts = {}) => {
+      return memoryExplain.explainBootstrap(memoryServing.withDefaultScope(opts));
+    },
+    explainCurrent: async (query, opts = {}) => {
+      return memoryExplain.explainCurrent(query, memoryServing.withDefaultScope(opts));
+    },
+    explainMemory: async (query, opts = {}) => {
+      return memoryExplain.explainMemory(query, memoryServing.withDefaultScope(opts));
     },
     rankHybridMemoryRows: (lexicalRows, embeddingRows, opts = {}) => {
       return memoryRecall.rankHybridMemoryRows(lexicalRows, embeddingRows, opts);
@@ -1665,9 +2148,11 @@ function createAquifer(config = {}) {
       return sessionFinalization.get(input);
     },
     list: async (input = {}) => {
-      await ensureMigrated();
       return sessionFinalization.list(input);
     },
+    inspect: async (input = {}) => {
+      return sessionFinalization.inspect(input);
+    },
     updateStatus: async (input = {}) => {
       await ensureMigrated();
       return sessionFinalization.updateStatus(input);
@@ -1722,6 +2207,33 @@ function createAquifer(config = {}) {
     },
   };
 
+  aquifer.operator = {
+    status: async (input = {}) => operatorObservability.status(input),
+    inspect: async (input = {}) => operatorObservability.inspect(input),
+  };
+
+  aquifer.doctor = {
+    run: async (input = {}) => doctor.run(input),
+  };
+
+  aquifer.review = {
+    queue: async (input = {}) => {
+      const scopedInput = memoryServing.withDefaultScope(input);
+      await ensureMigrated();
+      return memoryReview.queue(scopedInput);
+    },
+    inspect: async (input = {}) => {
+      const scopedInput = memoryServing.withDefaultScope(input);
+      await ensureMigrated();
+      return memoryReview.inspect(scopedInput);
+    },
+    resolve: async (input = {}) => {
+      const scopedInput = memoryServing.withDefaultScope(input);
+      await ensureMigrated();
+      return memoryReview.resolve(scopedInput);
+    },
+  };
+
   aquifer.finalizeSession = aquifer.finalization.finalizeSession;
 
   return aquifer;