@shadowforge0/aquifer-memory 1.5.12 → 1.7.0

package/core/aquifer.js

@@ -10,6 +10,7 @@ const { hybridRank } = require('./hybrid-rank');
 const { summarize } = require('../pipeline/summarize');
 const { extractEntities } = require('../pipeline/extract-entities');
 const { createEmbedder } = require('../pipeline/embed');
+const { applyEnrichSafetyGate, sanitizeSummaryResult } = require('./memory-safety-gate');
 
 // ---------------------------------------------------------------------------
 // Schema name validation
@@ -278,6 +279,102 @@ function createAquifer(config = {}) {
   // Override via config.ftsConfig if you need to force one or the other.
   let ftsConfig = config.ftsConfig || null;
 
+  const memoryCfg = config.memory || {};
+  const memoryServingMode = memoryCfg.servingMode || process.env.AQUIFER_MEMORY_SERVING_MODE || 'legacy';
+  function splitScopePath(value) {
+    if (Array.isArray(value)) return value.map(v => String(v).trim()).filter(Boolean);
+    if (typeof value !== 'string') return null;
+    const parts = value.split(',').map(v => v.trim()).filter(Boolean);
+    return parts.length > 0 ? parts : null;
+  }
+  const defaultActiveScopeKey = memoryCfg.activeScopeKey || process.env.AQUIFER_MEMORY_ACTIVE_SCOPE_KEY || null;
+  const defaultActiveScopePath = splitScopePath(
+    memoryCfg.activeScopePath || process.env.AQUIFER_MEMORY_ACTIVE_SCOPE_PATH || null,
+  );
+  function resolveMemoryServingMode(opts = {}) {
+    const mode = opts.memoryMode || opts.servingMode || memoryServingMode;
+    if (mode === 'legacy' || mode === 'evidence') return 'legacy';
+    if (mode === 'curated') return 'curated';
+    throw new Error(`Invalid memory serving mode: "${mode}". Must be one of: legacy, curated`);
+  }
+  function withDefaultMemoryScope(opts = {}) {
+    const next = { ...opts };
+    if (!next.activeScopePath && defaultActiveScopePath) next.activeScopePath = defaultActiveScopePath;
+    if (!next.activeScopeKey && defaultActiveScopeKey) next.activeScopeKey = defaultActiveScopeKey;
+    return next;
+  }
+  function assertCuratedRecallOpts(opts = {}) {
+    const unsupported = [];
+    for (const key of ['agentId', 'agentIds', 'source', 'dateFrom', 'dateTo', 'entities', 'entityMode', 'mode', 'weights', 'rerank', 'allowUnsafeDebug', 'unsafeDebug']) {
+      if (opts[key] !== undefined && opts[key] !== null) unsupported.push(key);
+    }
+    if (unsupported.length > 0) {
+      throw new Error(`curated session_recall does not support legacy filters: ${unsupported.join(', ')}. Use activeScopeKey/activeScopePath or evidence_recall.`);
+    }
+  }
+  function assertCuratedBootstrapOpts(opts = {}) {
+    const unsupported = [];
+    for (const key of ['agentId', 'source', 'lookbackDays', 'dateFrom', 'dateTo']) {
+      if (opts[key] !== undefined && opts[key] !== null) unsupported.push(key);
+    }
+    if (unsupported.length > 0) {
+      throw new Error(`curated session_bootstrap does not support legacy filters: ${unsupported.join(', ')}. Use activeScopeKey/activeScopePath.`);
+    }
+  }
+  function hasEvidenceBoundary(opts = {}) {
+    return Boolean(
+      opts.agentId
+      || (Array.isArray(opts.agentIds) && opts.agentIds.length > 0)
+      || opts.source
+      || opts.dateFrom
+      || opts.dateTo
+      || opts.host
+      || opts.sessionId
+      || opts.allowUnsafeDebug === true
+      || opts.unsafeDebug === true
+    );
+  }
+  function curatedRecallTitle(row = {}) {
+    const title = row.title || row.summary || row.canonical_key || row.canonicalKey || row.memory_type || row.memoryType || 'memory';
+    return String(title).trim();
+  }
+  function curatedRecallSummary(row = {}) {
+    const summary = row.summary || row.title || row.canonical_key || row.canonicalKey || '';
+    return String(summary).trim();
+  }
+  function normalizeCuratedRecallRow(row = {}) {
+    const memoryId = row.memoryId || row.memory_id || row.id || null;
+    const canonicalKey = row.canonicalKey || row.canonical_key || null;
+    const memoryType = row.memoryType || row.memory_type || null;
+    const scopeKey = row.scopeKey || row.scope_key || null;
+    const scopeKind = row.scopeKind || row.scope_kind || null;
+    const summaryText = curatedRecallSummary(row) || null;
+    const title = curatedRecallTitle(row) || null;
+    const scoreValue = row.recall_score ?? row.score ?? row.lexical_rank ?? null;
+    const score = scoreValue === null ? null : Number(scoreValue);
+    return {
+      ...row,
+      memoryId: memoryId === null ? null : String(memoryId),
+      canonicalKey,
+      memoryType,
+      scopeKey,
+      scopeKind,
+      title,
+      summaryText,
+      structuredSummary: {
+        title,
+        overview: summaryText,
+      },
+      startedAt: row.acceptedAt || row.accepted_at || row.observedAt || row.observed_at || null,
+      score: Number.isFinite(score) ? score : null,
+      feedbackTarget: {
+        kind: 'memory_feedback',
+        memoryId: memoryId === null ? null : String(memoryId),
+        canonicalKey,
+      },
+    };
+  }
+
   // State-change extraction (Q3): off by default. When enabled, enrich() runs
   // an extra LLM call to capture temporal state transitions on whitelisted
   // entities. See pipeline/extract-state-changes.js + core/entity-state.js.
@@ -326,6 +423,13 @@ function createAquifer(config = {}) {
     { id: '004-completion',          file: '004-completion.sql',          always: true, signature: 'narratives' },
     { id: '005-entity-state-history',file: '005-entity-state-history.sql',gate: 'entities', signature: 'entity_state_history' },
     { id: '006-insights',            file: '006-insights.sql',            always: true, signature: 'insights' },
+    { id: '007-v1-foundation',       file: '007-v1-foundation.sql',       always: true, signature: 'memory_records' },
+    { id: '008-session-finalizations',file: '008-session-finalizations.sql',always: true, signature: 'session_finalizations' },
+    { id: '009-v1-assertion-plane',  file: '009-v1-assertion-plane.sql',  always: true, signature: 'fact_assertions_v1' },
+    { id: '010-v1-finalization-review',file: '010-v1-finalization-review.sql',always: true, signature: 'finalization_candidates' },
+    { id: '011-v1-compaction-claim', file: '011-v1-compaction-claim.sql', always: true, signature: { table: 'compaction_runs', column: 'apply_token' } },
+    { id: '012-v1-compaction-lease', file: '012-v1-compaction-lease.sql', always: true, signature: { table: 'compaction_runs', column: 'lease_expires_at' } },
+    { id: '013-v1-compaction-lineage', file: '013-v1-compaction-lineage.sql', always: true, signature: 'compaction_candidates' },
   ];
 
   function requiredMigrations() {
@@ -340,15 +444,38 @@ function createAquifer(config = {}) {
     const required = MIGRATION_PLAN.filter(m => m.always
       || (m.gate === 'entities' && entitiesEnabled)
       || (m.gate === 'facts' && factsEnabled));
-    const signatures = required.map(m => m.signature);
-    if (signatures.length === 0) return [];
-    const r = await queryRunner.query(
-      `SELECT tablename FROM pg_tables
-         WHERE schemaname = $1 AND tablename = ANY($2::text[])`,
-      [schema, signatures]
-    );
-    const present = new Set(r.rows.map(row => row.tablename));
-    return required.filter(m => present.has(m.signature)).map(m => m.id);
+    const tableSignatures = required
+      .map(m => m.signature)
+      .filter(signature => typeof signature === 'string');
+    const columnSignatures = required
+      .map(m => m.signature)
+      .filter(signature => signature && typeof signature === 'object');
+    const presentTables = new Set();
+    const presentColumns = new Set();
+    if (tableSignatures.length > 0) {
+      const r = await queryRunner.query(
+        `SELECT tablename FROM pg_tables
+           WHERE schemaname = $1 AND tablename = ANY($2::text[])`,
+        [schema, tableSignatures]
+      );
+      for (const row of r.rows) presentTables.add(row.tablename);
+    }
+    if (columnSignatures.length > 0) {
+      const tables = [...new Set(columnSignatures.map(signature => signature.table))];
+      const r = await queryRunner.query(
+        `SELECT table_name, column_name
+           FROM information_schema.columns
+          WHERE table_schema = $1 AND table_name = ANY($2::text[])`,
+        [schema, tables]
+      );
+      for (const row of r.rows) presentColumns.add(`${row.table_name}.${row.column_name}`);
+    }
+    return required
+      .filter(m => {
+        if (typeof m.signature === 'string') return presentTables.has(m.signature);
+        return presentColumns.has(`${m.signature.table}.${m.signature.column}`);
+      })
+      .map(m => m.id);
   }
 
   async function buildMigrationPlan(queryRunner) {
@@ -492,6 +619,49 @@ function createAquifer(config = {}) {
           const insightsSql = loadSql('006-insights.sql', schema);
           await client.query(insightsSql); ddlExecuted.push('006-insights');
 
+          // 8. v1 curated-memory foundation (always, additive). This creates
+          // a sidecar curated plane without changing the legacy session recall
+          // or bootstrap serving path.
+          const memoryV1Sql = loadSql('007-v1-foundation.sql', schema);
+          await client.query(memoryV1Sql); ddlExecuted.push('007-v1-foundation');
+
+          // 9. v1 session finalization ledger (always, additive). Finalization
+          // is the source-of-truth lifecycle for handoff/session-end/recovery
+          // triggers; local consumer markers are cache hints only.
+          const finalizationSql = loadSql('008-session-finalizations.sql', schema);
+          await client.query(finalizationSql); ddlExecuted.push('008-session-finalizations');
+
+          // 10. v1 structured assertion plane (always, additive). This keeps
+          // legacy 004-facts untouched and adds the minimal DB contract for
+          // backing structured assertions, tenant-safe scope ancestry guards,
+          // and compaction coverage fields.
+          const assertionPlaneSql = loadSql('009-v1-assertion-plane.sql', schema);
+          await client.query(assertionPlaneSql); ddlExecuted.push('009-v1-assertion-plane');
+
+          // 11. v1 finalization review and lineage (always, additive). This
+          // stores human review text, minimal SessionStart text, finalization
+          // candidate rows, and row-level created_by_finalization_id lineage.
+          const finalizationReviewSql = loadSql('010-v1-finalization-review.sql', schema);
+          await client.query(finalizationReviewSql); ddlExecuted.push('010-v1-finalization-review');
+
+          // 12. v1 compaction claim/apply guard (always, additive). This adds
+          // a minimal claim token and one-live-apply guard for compaction_runs;
+          // it does not create or promote aggregate memory.
+          const compactionClaimSql = loadSql('011-v1-compaction-claim.sql', schema);
+          await client.query(compactionClaimSql); ddlExecuted.push('011-v1-compaction-claim');
+
+          // 13. v1 compaction claim lease (always, additive). This persists
+          // row-level lease expiry so stale applying claims can be reclaimed
+          // without relying on caller clocks or changing runtime defaults.
+          const compactionLeaseSql = loadSql('012-v1-compaction-lease.sql', schema);
+          await client.query(compactionLeaseSql); ddlExecuted.push('012-v1-compaction-lease');
+
+          // 14. v1 compaction lineage and candidate ledger (always,
+          // additive). This records aggregate candidate outcomes and links
+          // promoted rows back to the compaction run that created them.
+          const compactionLineageSql = loadSql('013-v1-compaction-lineage.sql', schema);
+          await client.query(compactionLineageSql); ddlExecuted.push('013-v1-compaction-lineage');
+
           migrated = true;
         } finally {
           await client.query('SELECT pg_advisory_unlock($1)', [lockKey]).catch((err) => {
@@ -850,9 +1020,12 @@ function createAquifer(config = {}) {
         ? (typeof rawMessages === 'string' ? JSON.parse(rawMessages) : rawMessages)
         : null;
       const normalized = messages ? (messages.normalized || messages) : [];
+      const safety = applyEnrichSafetyGate(normalized);
+      const safeNormalized = safety.messages;
+      const safetyGate = safety.meta;
 
       // 2. Extract user turns
-      const turns = storage.extractUserTurns(normalized);
+      const turns = storage.extractUserTurns(safeNormalized);
 
       // Collected across pre-tx and tx phases; any non-empty warnings demote
       // the final status from 'succeeded' to 'partial' (see step 8 below).
@@ -863,7 +1036,7 @@ function createAquifer(config = {}) {
       let entityRaw = null;
       let extra = null;
 
-      if (!skipSummary && normalized.length > 0) {
+      if (!skipSummary && safeNormalized.length > 0) {
         // Pre-transaction failures (customSummaryFn / summarize throws) would
         // otherwise bubble out and leave the session stuck in 'processing'
         // until stale reclaim. Capture as a warning so status ends 'partial',
@@ -871,13 +1044,13 @@ function createAquifer(config = {}) {
         try {
           if (customSummaryFn) {
             // Custom pipeline: caller handles LLM call and parsing
-            summaryResult = await customSummaryFn(normalized);
+            summaryResult = await customSummaryFn(safeNormalized);
             if (summaryResult && summaryResult.entityRaw) entityRaw = summaryResult.entityRaw;
             if (summaryResult && summaryResult.extra) extra = summaryResult.extra;
           } else {
             // Built-in pipeline
             const doMergeEntities = entitiesEnabled && mergeCall && !skipEntities;
-            summaryResult = await summarize(normalized, {
+            summaryResult = await summarize(safeNormalized, {
               llmFn,
               promptFn: summarizePromptFn,
               mergeEntities: doMergeEntities,
@@ -890,6 +1063,11 @@ function createAquifer(config = {}) {
           warnings.push(`summary step failed: ${e.message}`);
           summaryResult = null;
         }
+        if (summaryResult) {
+          const sanitizedSummary = sanitizeSummaryResult(summaryResult);
+          summaryResult = sanitizedSummary.summaryResult;
+          safetyGate.summary = sanitizedSummary.meta;
+        }
       }
 
       // 4. Pre-compute all LLM/embed results BEFORE opening transaction
@@ -921,7 +1099,7 @@ function createAquifer(config = {}) {
           } else if (entityRaw) {
             parsedEntities = entity.parseEntityOutput(entityRaw);
           } else if (llmFn && !customSummaryFn) {
-            parsedEntities = await extractEntities(normalized, { llmFn, promptFn: entityPromptFn });
+            parsedEntities = await extractEntities(safeNormalized, { llmFn, promptFn: entityPromptFn });
           }
         } catch (e) { warnings.push(`entity extraction failed: ${e.message}`); }
       }
@@ -937,7 +1115,7 @@ function createAquifer(config = {}) {
         if (scopedEntities.length > 0) {
           try {
             const { extractStateChanges } = require('../pipeline/extract-state-changes');
-            const result = await extractStateChanges(normalized, {
+            const result = await extractStateChanges(safeNormalized, {
               llmFn,
               promptFn: stateChangesPromptFn,
               entities: scopedEntities.map(e => ({ name: e.name, aliases: e.aliases || [] })),
@@ -969,9 +1147,9 @@ function createAquifer(config = {}) {
             summaryText: summaryResult.summaryText,
             structuredSummary: summaryResult.structuredSummary,
             model: (optModel !== undefined ? optModel : session.model) || null, sourceHash: null,
-            msgCount: normalized.length,
+            msgCount: safeNormalized.length,
             userCount: turns.length,
-            assistantCount: normalized.filter(m => m.role === 'assistant').length,
+            assistantCount: safeNormalized.filter(m => m.role === 'assistant').length,
             startedAt: session.started_at, endedAt: session.ended_at,
             embedding: summaryEmbedding,
           });
@@ -1132,8 +1310,10 @@ function createAquifer(config = {}) {
             turnVectors,
             extra,
             normalized,
+            sanitized: safeNormalized,
             parsedEntities,
             skipped: { summary: skipSummary, entities: skipEntities, turns: skipTurnEmbed },
+            safetyGate,
             turnsEmbedded,
             entitiesFound,
             warnings: [...warnings],  // defensive copy — caller cannot mutate enrich warnings
@@ -1150,6 +1330,7 @@ function createAquifer(config = {}) {
         entitiesFound,
         warnings,
         extra,
+        safetyGate,
         session: {
           id: session.id,
           sessionId,
@@ -1165,6 +1346,16 @@ function createAquifer(config = {}) {
     // --- read path ---
 
     async recall(query, opts = {}) {
+      if (resolveMemoryServingMode(opts) === 'curated') {
+        assertCuratedRecallOpts(opts);
+        await ensureMigrated();
+        const rows = await aquifer.memory.recall(query, withDefaultMemoryScope(opts));
+        return rows.map(normalizeCuratedRecallRow);
+      }
+      return aquifer.evidenceRecall(query, { ...opts, allowBroadEvidence: true });
+    },
+
+    async evidenceRecall(query, opts = {}) {
       // Contract (aligned across core / manifest / consumer tools): query must
       // be a non-empty string. Empty strings previously short-circuited to []
       // silently — that masks caller bugs. Callers wanting "recent sessions"
@@ -1172,6 +1363,9 @@ function createAquifer(config = {}) {
       if (typeof query !== 'string' || query.trim().length === 0) {
         throw new Error('aquifer.recall(query): query must be a non-empty string');
       }
+      if (opts.allowBroadEvidence !== true && !hasEvidenceBoundary(opts)) {
+        throw new Error('evidence_recall requires an audit boundary filter (agentId, source, dateFrom/dateTo, host, sessionId) or allowUnsafeDebug=true');
+      }
 
       const VALID_MODES = ['fts', 'hybrid', 'vector'];
       const mode = opts.mode !== undefined ? opts.mode : 'hybrid';
@@ -1558,6 +1752,50 @@ function createAquifer(config = {}) {
       });
     },
 
+    async memoryFeedback(memoryId, opts = {}) {
+      let targetMemoryId = memoryId;
+      let canonicalKey = opts.canonicalKey || null;
+      if (memoryId && typeof memoryId === 'object') {
+        targetMemoryId = memoryId.memoryId || memoryId.id || null;
+        canonicalKey = memoryId.canonicalKey || memoryId.canonical_key || canonicalKey;
+      }
+      if (!targetMemoryId && !canonicalKey) {
+        throw new Error('memoryFeedback(memoryId): memoryId or canonicalKey is required');
+      }
+      const feedbackType = opts.feedbackType || opts.verdict;
+      if (!feedbackType) throw new Error('opts.feedbackType is required');
+      await ensureMigrated();
+      if (!targetMemoryId && canonicalKey) {
+        const rows = await memoryRecords.findActiveByCanonicalKey({
+          tenantId: opts.tenantId || tenantId,
+          canonicalKey,
+        });
+        if (!rows[0]) throw new Error(`Active memory not found: ${canonicalKey}`);
+        targetMemoryId = rows[0].id;
+        canonicalKey = rows[0].canonical_key || rows[0].canonicalKey || canonicalKey;
+      }
+      const result = await aquifer.memory.recordFeedback({
+        tenantId: opts.tenantId || tenantId,
+        targetKind: 'memory_record',
+        targetId: targetMemoryId,
+        feedbackType,
+        actorKind: opts.actorKind || 'user',
+        actorId: opts.actorId || opts.agentId || null,
+        queryFingerprint: opts.queryFingerprint || null,
+        note: opts.note || null,
+        metadata: {
+          ...(opts.metadata || {}),
+          publicSurface: 'memoryFeedback',
+        },
+      });
+      return {
+        ...result,
+        memoryId: targetMemoryId === null ? null : String(targetMemoryId),
+        canonicalKey,
+        feedbackType,
+      };
+    },
+
     async feedbackStats(opts = {}) {
       await ensureMigrated();
       return storage.getFeedbackStats(pool, {
@@ -1600,7 +1838,7 @@ function createAquifer(config = {}) {
     // --- public config accessor ---
 
     getConfig() {
-      return { schema, tenantId };
+      return { schema, tenantId, memoryServingMode };
     },
 
     // v1.2.0: expose the internal pool so host persona layers can reuse it
@@ -1705,6 +1943,10 @@ function createAquifer(config = {}) {
 
     async bootstrap(opts = {}) {
       await ensureMigrated();
+      if (resolveMemoryServingMode(opts) === 'curated') {
+        assertCuratedBootstrapOpts(opts);
+        return aquifer.memory.bootstrap(withDefaultMemoryScope(opts));
+      }
 
       const agentId = opts.agentId || null;
       const source = opts.source || null;
@@ -1823,6 +2065,12 @@ function createAquifer(config = {}) {
   const { createBundles } = require('./bundles');
   const { createEntityState } = require('./entity-state');
   const { createInsights } = require('./insights');
+  const { createMemoryRecords } = require('./memory-records');
+  const { createMemoryPromotion } = require('./memory-promotion');
+  const { createMemoryBootstrap } = require('./memory-bootstrap');
+  const { createMemoryRecall } = require('./memory-recall');
+  const { createMemoryConsolidation } = require('./memory-consolidation');
+  const { createSessionFinalization } = require('./session-finalization');
   const qSchema = qi(schema);
   aquifer.narratives = createNarratives({ pool, schema: qSchema, defaultTenantId: tenantId });
   aquifer.timeline = createTimeline({ pool, schema: qSchema, defaultTenantId: tenantId });
@@ -1851,6 +2099,120 @@ function createAquifer(config = {}) {
     dedup: config.insights && config.insights.dedup ? config.insights.dedup : undefined,
   });
 
+  const memoryRecords = createMemoryRecords({ pool, schema: qSchema, defaultTenantId: tenantId });
+  const memoryPromotion = createMemoryPromotion({ records: memoryRecords });
+  const memoryBootstrap = createMemoryBootstrap({ records: memoryRecords });
+  const memoryRecall = createMemoryRecall({ pool, schema: qSchema, defaultTenantId: tenantId });
+  const memoryConsolidation = createMemoryConsolidation({
+    pool,
+    schema: qSchema,
+    defaultTenantId: tenantId,
+    records: memoryRecords,
+  });
+  const sessionFinalization = createSessionFinalization({
+    pool,
+    schema,
+    recordsSchema: qSchema,
+    defaultTenantId: tenantId,
+  });
+
+  // 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.
+  aquifer.memory = {
+    upsertScope: async (input = {}) => {
+      await ensureMigrated();
+      return memoryRecords.upsertScope(input);
+    },
+    createVersion: async (input = {}) => {
+      await ensureMigrated();
+      return memoryRecords.createVersion(input);
+    },
+    upsertMemory: async (input = {}) => {
+      await ensureMigrated();
+      return memoryRecords.upsertMemory(input);
+    },
+    linkEvidence: async (input = {}) => {
+      await ensureMigrated();
+      return memoryRecords.linkEvidence(input);
+    },
+    recordFeedback: async (input = {}) => {
+      await ensureMigrated();
+      return memoryRecords.recordFeedback(input);
+    },
+    extractCandidates: (input = {}) => memoryPromotion.extractCandidates(input),
+    assessCandidate: (candidate = {}) => memoryPromotion.assessCandidate(candidate),
+    promote: async (candidates = [], opts = {}) => {
+      await ensureMigrated();
+      return memoryPromotion.promote(candidates, opts);
+    },
+    bootstrap: async (opts = {}) => {
+      await ensureMigrated();
+      return memoryBootstrap.bootstrap(opts);
+    },
+    current: async (opts = {}) => {
+      await ensureMigrated();
+      return memoryRecords.currentProjection(withDefaultMemoryScope(opts));
+    },
+    listCurrentMemory: async (opts = {}) => {
+      await ensureMigrated();
+      return memoryRecords.currentProjection(withDefaultMemoryScope(opts));
+    },
+    recall: async (query, opts = {}) => {
+      await ensureMigrated();
+      return memoryRecall.recall(query, opts);
+    },
+    consolidation: {
+      plan: memoryConsolidation.plan,
+      distillArchiveSnapshot: memoryConsolidation.distillArchiveSnapshot,
+      runJob: async (input = {}) => {
+        await ensureMigrated();
+        return memoryConsolidation.runJob(input);
+      },
+      recordRun: async (input = {}) => {
+        await ensureMigrated();
+        return memoryConsolidation.recordRun(input);
+      },
+      claimRun: async (input = {}) => {
+        await ensureMigrated();
+        return memoryConsolidation.claimRun(input);
+      },
+      applyPlan: async (input = {}) => {
+        await ensureMigrated();
+        return memoryConsolidation.applyPlan(input);
+      },
+      executePlan: async (input = {}) => {
+        await ensureMigrated();
+        return memoryConsolidation.executePlan(input);
+      },
+    },
+  };
+
+  aquifer.finalization = {
+    createTask: async (input = {}) => {
+      await ensureMigrated();
+      return sessionFinalization.createTask(input);
+    },
+    get: async (input = {}) => {
+      await ensureMigrated();
+      return sessionFinalization.get(input);
+    },
+    list: async (input = {}) => {
+      await ensureMigrated();
+      return sessionFinalization.list(input);
+    },
+    updateStatus: async (input = {}) => {
+      await ensureMigrated();
+      return sessionFinalization.updateStatus(input);
+    },
+    finalizeSession: async (input = {}) => {
+      await ensureMigrated();
+      return sessionFinalization.finalizeSession(input);
+    },
+  };
+
+  aquifer.finalizeSession = aquifer.finalization.finalizeSession;
+
   return aquifer;
 }