@shadowforge0/aquifer-memory 1.8.0 → 1.9.0

package/core/aquifer.js

@@ -657,29 +657,24 @@ 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;
@@ -1195,6 +1190,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 +1295,11 @@ function createAquifer(config = {}) {
         latestFinalizedAt: null,
         latestUpdatedAt: null,
       };
+      let pendingSessions = {
+        available: false,
+        total: null,
+        statuses: {},
+      };
       try {
         const finalizationResult = await pool.query(
           `SELECT
@@ -1327,7 +1328,38 @@ 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 */
+      }
+
+      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 */
+      }
 
       return {
         backendKind,
@@ -1336,6 +1368,7 @@ function createAquifer(config = {}) {
           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,6 +1377,7 @@ function createAquifer(config = {}) {
         entities: entityCount,
         memoryRecords,
         sessionFinalizations,
+        pendingSessions,
         earliest: timeRange.rows[0]?.earliest || null,
         latest: timeRange.rows[0]?.latest || null,
       };
@@ -1351,15 +1385,38 @@ function createAquifer(config = {}) {
 
     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]
-      );
+      let result;
+      try {
+        result = await pool.query(
+          `SELECT s.session_id, s.agent_id, s.processing_status
+           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')
+             )
+           ORDER BY s.started_at DESC
+           LIMIT $2`,
+          [tenantId, limit]
+        );
+      } catch (err) {
+        if (err?.code !== '42P01') throw err;
+        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]
+        );
+      }
       return result.rows;
     },
 
@@ -1386,9 +1443,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 +1484,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 });
@@ -1476,6 +1538,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 +1574,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 +1615,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 +1710,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 +1783,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 +1842,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;

package/core/backends/local.js

@@ -299,6 +299,115 @@ function createLocalAquifer(config = {}) {
     async memoryBootstrap() {
       unsupported('memoryBootstrap', 'curatedBootstrap');
     },
+    doctor: {
+      async run() {
+        return {
+          ok: false,
+          status: 'warn',
+          checks: [
+            {
+              id: 'backend',
+              status: 'warn',
+              summary: 'Local starter backend is running with degraded governance coverage.',
+              details: {
+                backendKind: 'local',
+                backendProfile: capabilities.profile,
+                backendPath,
+                capabilities: capabilities.capabilities,
+              },
+              nextAction: capabilities.upgradeHint,
+            },
+            {
+              id: 'db',
+              status: 'warn',
+              summary: 'PostgreSQL governance ledgers are unavailable on the local starter backend.',
+              details: {
+                configured: false,
+                tenantId,
+              },
+              nextAction: 'Use the PostgreSQL backend for migrations, finalization ledgers, and operator workflows.',
+            },
+          ],
+        };
+      },
+    },
+    finalization: {
+      async list() {
+        unsupported('finalization list', 'finalizationLedger');
+      },
+      async inspect() {
+        unsupported('finalization inspect', 'finalizationLedger');
+      },
+    },
+    operator: {
+      async status() {
+        return {
+          readOnly: true,
+          compaction: {
+            available: false,
+            latest: [],
+            staleClaims: [],
+            statusCounts: {},
+            error: 'operator compaction ledger is unavailable on the local starter backend',
+          },
+          checkpoint: {
+            available: false,
+            latest: [],
+            statusCounts: {},
+            error: 'operator checkpoint ledger is unavailable on the local starter backend',
+          },
+        };
+      },
+      async inspect() {
+        unsupported('operator inspect', 'operatorCompaction');
+      },
+    },
+    memory: {
+      async explainBootstrap() {
+        unsupported('explain bootstrap', 'curatedBootstrap');
+      },
+      async explainCurrent() {
+        unsupported('explain memory', 'curatedRecall');
+      },
+      async explainMemory() {
+        unsupported('explain memory', 'curatedRecall');
+      },
+    },
+    review: {
+      async queue() {
+        return {
+          readOnly: true,
+          derived: true,
+          available: false,
+          items: [],
+          reviewQueue: [],
+          scope: {
+            activeScopeKey: null,
+            activeScopePath: [],
+          },
+          filters: {},
+          summary: {
+            scanned: 0,
+            queued: 0,
+            truncated: false,
+            severityCounts: {},
+            feedbackTypeCounts: {},
+          },
+          totals: {
+            items: 0,
+            issueFeedback: 0,
+            allFeedback: 0,
+          },
+          error: 'Memory review queue is unavailable on the local starter backend',
+        };
+      },
+      async inspect() {
+        unsupported('review inspect', 'curatedRecall');
+      },
+      async resolve() {
+        unsupported('review resolve', 'curatedRecall');
+      },
+    },
     async historicalBootstrap(opts = {}) {
       return this.bootstrap(opts);
     },