@shadowforge0/aquifer-memory 1.0.2 → 1.2.1

package/consumers/openclaw-plugin.js

@@ -16,6 +16,8 @@
  */
 
 const { createAquiferFromConfig } = require('./shared/factory');
+const { runIngest } = require('./shared/ingest');
+const { formatRecallResults: sharedFormatRecallResults } = require('./shared/recall-format');
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -38,6 +40,7 @@ function normalizeEntries(rawEntries) {
   let startedAt = null, lastMessageAt = null;
 
   for (const entry of rawEntries) {
+    if (!entry) continue;
     const msg = entry.message || entry;
     if (!msg || !msg.role) continue;
     if (!['user', 'assistant', 'system'].includes(msg.role)) continue;
@@ -79,43 +82,63 @@ function normalizeEntries(rawEntries) {
   };
 }
 
-function formatDate(value) {
-  if (!value) return 'unknown';
-  const parsed = new Date(value);
-  return isNaN(parsed.getTime()) ? 'unknown' : parsed.toISOString().slice(0, 10);
-}
-
-function formatRecallResults(results) {
-  if (results.length === 0) return 'No matching sessions found.';
-
-  return results.map((r, i) => {
-    const ss = r.structuredSummary || {};
-    const title = ss.title || r.summaryText?.slice(0, 60) || '(untitled)';
-    const date = formatDate(r.startedAt);
-
-    const lines = [`### ${i + 1}. ${title} (${date}, ${r.agentId || 'default'})`];
-    if (ss.overview || r.summaryText) {
-      lines.push((ss.overview || r.summaryText).slice(0, 300));
-    }
-    if (r.matchedTurnText) {
-      lines.push(`Matched: ${r.matchedTurnText.slice(0, 200)}`);
-    }
-    return lines.join('\n');
-  }).join('\n\n');
-}
+// Thin adapter over the shared formatter. OpenClaw's tool output historically
+// used "Matched:" instead of "Matched turn:" and joined with blank lines, so
+// we supply a pair of renderer overrides to preserve that shape.
+const formatRecallResults = (function () {
+  const { createRecallFormatter } = require('./shared/recall-format');
+  const _fmt = createRecallFormatter({
+    header: () => null,
+    matched: (r) => r.matchedTurnText ? `Matched: ${String(r.matchedTurnText).slice(0, 200)}` : null,
+    separator: () => '',
+  });
+  return (results) => {
+    if (!results || results.length === 0) return 'No matching sessions found.';
+    return _fmt(results);
+  };
+})();
+// Re-export the shared formatter too for callers that want the default shape.
+formatRecallResults.shared = sharedFormatRecallResults;
 
 // ---------------------------------------------------------------------------
 // Plugin
 // ---------------------------------------------------------------------------
 
-module.exports = {
-  id: 'aquifer-memory',
-  name: 'Aquifer Memory',
+function buildPlugin() {
+  return {
+    id: 'aquifer-memory',
+    name: 'Aquifer Memory',
+    register,
+  };
+}
+
+module.exports = buildPlugin();
+// Expose helpers for unit testing. Not part of the plugin's OpenClaw-visible
+// contract; OpenClaw reads { id, name, register } only.
+module.exports.normalizeEntries = normalizeEntries;
+module.exports.coerceRawEntries = coerceRawEntries;
 
-  register(api) {
+function register(api) {
     const pluginConfig = api.pluginConfig || {};
-    let aquifer;
 
+    // v1.2.0: delegate to a persona layer if one is configured, otherwise
+    // run the generic default path (before_reset + session_recall + feedback).
+    const personaPath = pluginConfig.persona || process.env.AQUIFER_PERSONA;
+    if (personaPath) {
+      try {
+        const persona = require(personaPath);
+        if (persona && typeof persona.mountOnOpenClaw === 'function') {
+          persona.mountOnOpenClaw(api, pluginConfig);
+          api.logger.info(`[aquifer-memory] registered via persona: ${personaPath}`);
+          return;
+        }
+        api.logger.warn(`[aquifer-memory] persona at ${personaPath} lacks mountOnOpenClaw; falling back to default`);
+      } catch (err) {
+        api.logger.warn(`[aquifer-memory] failed to load persona ${personaPath}: ${err.message}; falling back to default`);
+      }
+    }
+
+    let aquifer;
     try {
       aquifer = createAquiferFromConfig(pluginConfig);
     } catch (err) {
@@ -138,65 +161,35 @@ module.exports = {
       if ((sessionKey || '').includes('subagent')) return;
       if ((sessionKey || '').includes(':cron:')) return;
 
-      const dedupKey = `${agentId}:${sessionId}`;
-      if (recentlyProcessed.has(dedupKey) || inFlight.has(dedupKey)) return;
-
       const rawEntries = coerceRawEntries(event?.messages || []);
       if (rawEntries.length < 3) {
         api.logger.info(`[aquifer-memory] skip: ${sessionId} only ${rawEntries.length} msgs`);
         return;
       }
 
-      inFlight.add(dedupKey);
       api.logger.info(`[aquifer-memory] capturing ${sessionId} (${rawEntries.length} entries)`);
 
       (async () => {
         try {
+          // OpenClaw hands us flat {role, content} entries; normalizeEntries
+          // produces the commit-ready shape, which we feed to shared runIngest
+          // as 'preNormalized' so commit+enrich+dedup stays host-agnostic.
           const norm = normalizeEntries(rawEntries);
-          if (norm.userCount === 0) {
-            api.logger.info(`[aquifer-memory] skip: no user messages in ${sessionId}`);
-            return;
-          }
-
-          // Commit
-          await aquifer.commit(sessionId, norm.messages, {
+          await runIngest({
+            aquifer,
+            sessionId,
             agentId,
             source: 'openclaw',
             sessionKey,
-            model: norm.model,
-            tokensIn: norm.tokensIn,
-            tokensOut: norm.tokensOut,
-            startedAt: norm.startedAt,
-            lastMessageAt: norm.lastMessageAt,
+            adapter: 'preNormalized',
+            preNormalized: norm,
+            minUserMessages,
+            dedupMap: recentlyProcessed,
+            inFlight,
+            logger: api.logger,
           });
-          api.logger.info(`[aquifer-memory] committed ${sessionId}`);
-
-          // Enrich (if enough messages)
-          if (norm.userCount >= minUserMessages) {
-            try {
-              const result = await aquifer.enrich(sessionId, { agentId });
-              api.logger.info(`[aquifer-memory] enriched ${sessionId} (${result.turnsEmbedded} turns, ${result.entitiesFound} entities)`);
-            } catch (enrichErr) {
-              api.logger.warn(`[aquifer-memory] enrich failed for ${sessionId}: ${enrichErr.message}`);
-            }
-          } else {
-            try {
-              await aquifer.skip(sessionId, { agentId, reason: `user_count=${norm.userCount} < min=${minUserMessages}` });
-            } catch (e) { api.logger.warn(`[aquifer-memory] skip failed for ${sessionId}: ${e.message}`); }
-          }
-
-          recentlyProcessed.set(dedupKey, Date.now());
         } catch (err) {
           api.logger.warn(`[aquifer-memory] capture failed for ${sessionId}: ${err.message}`);
-        } finally {
-          inFlight.delete(dedupKey);
-          // Evict old entries
-          if (recentlyProcessed.size > 200) {
-            const cutoff = Date.now() - 30 * 60 * 1000;
-            for (const [k, ts] of recentlyProcessed) {
-              if (ts < cutoff) recentlyProcessed.delete(k);
-            }
-          }
         }
       })();
     });
@@ -292,6 +285,5 @@ module.exports = {
       };
     }, { name: 'session_feedback' });
 
-    api.logger.info('[aquifer-memory] registered (before_reset + session_recall + session_feedback)');
-  },
-};
+  api.logger.info('[aquifer-memory] registered (before_reset + session_recall + session_feedback)');
+}

package/consumers/opencode.js

@@ -26,8 +26,7 @@
 
 const path = require('path');
 const os = require('os');
-const { createAquiferFromConfig } = require('./shared/factory');
-
+const { runIngest } = require('./shared/ingest');
 // ---------------------------------------------------------------------------
 // SQLite access — use Node 22+ built-in or fall back to better-sqlite3
 // ---------------------------------------------------------------------------
@@ -37,7 +36,7 @@ function openSqlite(dbPath) {
   try {
     const { DatabaseSync } = require('node:sqlite');
     return new DatabaseSync(dbPath, { open: true, readOnly: true });
-  } catch (_) {
+  } catch {
     // not available
   }
 
@@ -45,7 +44,7 @@ function openSqlite(dbPath) {
   try {
     const Database = require('better-sqlite3');
     return new Database(dbPath, { readonly: true });
-  } catch (_) {
+  } catch {
     // not available
   }
 
@@ -220,7 +219,7 @@ async function ingestOpenCode(aquifer, args) {
   try {
     const existing = await aquifer.exportSessions({ source: 'opencode', limit: 10000 });
     for (const row of existing) existingSet.add(row.session_id);
-  } catch (_) {
+  } catch {
     // exportSessions may not exist in all versions
   }
 
@@ -271,36 +270,34 @@ async function ingestOpenCode(aquifer, args) {
       continue;
     }
 
-    // Commit to Aquifer
+    // Commit + optional enrich via shared ingest pipeline
     try {
-      await aquifer.commit(sid, norm.messages, {
+      const ingestResult = await runIngest({
+        aquifer,
+        sessionId: sid,
         agentId,
         source: 'opencode',
-        model: norm.model,
-        tokensIn: norm.tokensIn,
-        tokensOut: norm.tokensOut,
-        startedAt: norm.startedAt,
-        lastMessageAt: norm.lastMessageAt,
+        adapter: 'preNormalized',
+        preNormalized: norm,
+        enrich: doEnrich,
+        minUserMessages,
+        logger: { info() {}, warn(m) { info.enrichError = m; } },
       });
+
       committed++;
       info.status = 'committed';
-
-      // Enrich if requested
-      if (doEnrich) {
-        try {
-          const enrichResult = await aquifer.enrich(sid, { agentId });
-          info.status = 'enriched';
-          info.turnsEmbedded = enrichResult.turnsEmbedded;
-          info.entitiesFound = enrichResult.entitiesFound;
-        } catch (enrichErr) {
-          info.enrichError = enrichErr.message;
-        }
+      if (ingestResult.enrichResult) {
+        info.status = 'enriched';
+        info.turnsEmbedded = ingestResult.enrichResult.turnsEmbedded;
+        info.entitiesFound = ingestResult.enrichResult.entitiesFound;
       }
 
       if (jsonOutput) {
         results.push(info);
       } else {
-        const enrichNote = info.turnsEmbedded != null ? ` (${info.turnsEmbedded} turns, ${info.entitiesFound} entities)` : '';
+        const enrichNote = info.turnsEmbedded !== null && info.turnsEmbedded !== undefined
+          ? ` (${info.turnsEmbedded} turns, ${info.entitiesFound} entities)`
+          : '';
         console.log(`  [${committed}] ${sid} "${session.title}"${enrichNote}`);
       }
     } catch (err) {

package/consumers/shared/autodetect.js

@@ -0,0 +1,64 @@
+'use strict';
+
+const { Pool } = require('pg');
+
+const DEFAULT_PG_URL = 'postgresql://aquifer:aquifer@localhost:5432/aquifer';
+const DEFAULT_OLLAMA_URL = 'http://localhost:11434';
+
+async function probePostgres(url, { timeoutMs = 1500 } = {}) {
+  const pool = new Pool({
+    connectionString: url,
+    connectionTimeoutMillis: timeoutMs,
+    max: 1,
+  });
+  try {
+    await pool.query('SELECT 1');
+    return true;
+  } catch {
+    return false;
+  } finally {
+    try { await pool.end(); } catch { /* ignore */ }
+  }
+}
+
+async function probeOllama(baseUrl, { timeoutMs = 1500 } = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(`${baseUrl.replace(/\/$/, '')}/api/tags`, {
+      signal: controller.signal,
+    });
+    return res.ok;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function autodetectForQuickstart(env, probes = {}) {
+  const probePg = probes.probePostgres || probePostgres;
+  const probeOll = probes.probeOllama || probeOllama;
+  const detected = {};
+
+  const hasDb = env.DATABASE_URL || env.AQUIFER_DB_URL;
+  if (!hasDb && await probePg(DEFAULT_PG_URL)) {
+    detected.DATABASE_URL = DEFAULT_PG_URL;
+  }
+
+  const hasEmbed = env.EMBED_PROVIDER
+    || (env.AQUIFER_EMBED_BASE_URL && env.AQUIFER_EMBED_MODEL);
+  if (!hasEmbed && await probeOll(DEFAULT_OLLAMA_URL)) {
+    detected.EMBED_PROVIDER = 'ollama';
+  }
+
+  return detected;
+}
+
+module.exports = {
+  autodetectForQuickstart,
+  probePostgres,
+  probeOllama,
+  DEFAULT_PG_URL,
+  DEFAULT_OLLAMA_URL,
+};

package/consumers/shared/entity-parser.js

@@ -0,0 +1,119 @@
+'use strict';
+
+// ---------------------------------------------------------------------------
+// Entity section parser — shared across consumers.
+//
+// Parses LLM output lines of the form:
+//   ENTITY: <name> | <type> | <alias1, alias2, ...>
+//   RELATION: <src> | <dst>
+//
+// Returns { entities, relations } ready for Aquifer entityParseFn.
+// Dedups, normalizes names via Aquifer's normalizeEntityName, and drops noise
+// entities (generic roles, pure-numeric, file paths, CLI flags, etc.).
+//
+// Consumers that use a different ENTITIES prompt format should write their own
+// parser — this one is for the ENTITY:/RELATION: line protocol.
+// ---------------------------------------------------------------------------
+
+// Import directly from core/entity to avoid a circular dep with top-level
+// index.js, which itself re-exports parseEntitySection from here.
+const { normalizeEntityName } = require('../../core/entity');
+
+const VALID_ENTITY_TYPES = new Set([
+  'person', 'project', 'concept', 'tool', 'metric',
+  'org', 'place', 'event', 'doc', 'task', 'topic', 'other',
+]);
+
+const ENTITY_STOPLIST = new Set([
+  // Role generics
+  '助理', '使用者', '用戶', 'assistant', 'user', 'agent', 'agents', '我',
+  // Too broad
+  'api', 'db', 'llm', 'cli', 'bash', 'diff', 'bug', 'config',
+  'extensions', 'hooks', 'cron', 'manifest', 'index.js', 'node.js',
+  // Common noise
+  'ok', 'timeout', 'error', 'test', 'cache', 'token',
+  '登入狀態', '授權提示', 'chat_id', 'promise.race',
+]);
+
+const CODE_EXT_RE = /\.(js|ts|jsx|tsx|mjs|cjs|sh|py|sql|md|json|yml|yaml|css|html|vue|svelte|go|rs|rb|php|java|kt|c|cpp|h|toml|ini|cfg|conf|lock|env|proto)$/i;
+const PATH_RE = /^[.\/~].*\//;
+const DOTFILE_RE = /^\.[a-z][a-z0-9._-]*$/i;
+
+function isNoiseEntity(normalizedName, rawName) {
+  if (ENTITY_STOPLIST.has(normalizedName)) return true;
+  if (/^\d+[秒分時天日月年kKgG%]/.test(rawName)) return true;
+  if (/^\d{2,}[mM]/.test(rawName)) return true;
+  if (/^\d+錯誤/.test(rawName)) return true;
+  if (/^\d{10,}$/.test(rawName)) return true;
+  if (normalizedName.length < 2) return true;
+  if (PATH_RE.test(rawName)) return true;
+  if (DOTFILE_RE.test(rawName)) return true;
+  if (CODE_EXT_RE.test(rawName)) return true;
+  if (/^--?\w/.test(rawName)) return true;
+  return false;
+}
+
+function splitFields(line) {
+  if (line.includes('|')) return line.split('|').map(s => s.trim());
+  if (line.includes('\t')) return line.split('\t').map(s => s.trim());
+  return [line.trim()];
+}
+
+function parseEntitySection(text, opts = {}) {
+  if (!text || typeof text !== 'string') return { entities: [], relations: [] };
+
+  const maxEntities = Number.isFinite(opts.maxEntities) ? opts.maxEntities : 10;
+  const maxRelations = Number.isFinite(opts.maxRelations) ? opts.maxRelations : 15;
+
+  const entityMap = new Map();
+  const relationSet = new Set();
+  const relations = [];
+
+  for (const rawLine of text.split('\n')) {
+    const line = rawLine.trim();
+    if (!line) continue;
+
+    if (/^ENTITY:/i.test(line)) {
+      if (entityMap.size >= maxEntities) continue;
+      const fields = splitFields(line.replace(/^ENTITY:\s*/i, ''));
+      const rawName = (fields[0] || '').trim().slice(0, 200);
+      if (!rawName) continue;
+      const normalizedName = normalizeEntityName(rawName);
+      if (!normalizedName || entityMap.has(normalizedName)) continue;
+      if (isNoiseEntity(normalizedName, rawName)) continue;
+      const rawType = (fields[1] || '').toLowerCase().trim();
+      const type = VALID_ENTITY_TYPES.has(rawType) ? rawType : 'other';
+      const rawAliases = fields[2] || '';
+      const aliases = (rawAliases && rawAliases !== '-')
+        ? rawAliases.split(',').map(a => a.trim().slice(0, 200)).filter(a => a && a !== '-')
+        : [];
+      entityMap.set(normalizedName, { name: rawName, normalizedName, type, aliases });
+    } else if (/^RELATION:/i.test(line)) {
+      if (relations.length >= maxRelations) continue;
+      const fields = splitFields(line.replace(/^RELATION:\s*/i, ''));
+      const src = (fields[0] || '').trim();
+      const dst = (fields[1] || '').trim();
+      if (!src || !dst) continue;
+      const ns = normalizeEntityName(src);
+      const nd = normalizeEntityName(dst);
+      if (!ns || !nd || ns === nd) continue;
+      const pairKey = ns < nd ? `${ns}|||${nd}` : `${nd}|||${ns}`;
+      if (relationSet.has(pairKey)) continue;
+      relationSet.add(pairKey);
+      relations.push({ src, dst });
+    }
+  }
+
+  const filteredRelations = relations.filter(r =>
+    entityMap.has(normalizeEntityName(r.src)) && entityMap.has(normalizeEntityName(r.dst))
+  );
+
+  return { entities: [...entityMap.values()], relations: filteredRelations };
+}
+
+module.exports = {
+  parseEntitySection,
+  isNoiseEntity,
+  VALID_ENTITY_TYPES,
+  ENTITY_STOPLIST,
+};

package/consumers/shared/ingest.js

@@ -0,0 +1,148 @@
+'use strict';
+
+// ---------------------------------------------------------------------------
+// Shared ingest flow — the standard "received session → Aquifer" pipeline.
+//
+// All three host adapters (OpenClaw before_reset, Claude Code afterburn,
+// OpenCode backfill) do the same three things:
+//   1. Normalize raw entries to commit-ready shape
+//   2. commit() the messages + metadata
+//   3. enrich() if enough user turns, else skip()
+// With dedup on (agentId, sessionId) so the same hook firing twice is safe.
+//
+// runIngest() centralizes this. Host adapters pass in their raw entries, the
+// adapter name, and an optional postProcess callback for persona side effects.
+// ---------------------------------------------------------------------------
+
+const { normalizeMessages } = require('./normalize');
+
+const RECENT_CAP = 200;
+const RECENT_TTL_MS = 30 * 60 * 1000;
+
+function evictStale(dedupMap, now = Date.now()) {
+    if (!dedupMap || dedupMap.size <= RECENT_CAP) return;
+    const cutoff = now - RECENT_TTL_MS;
+    for (const [k, ts] of dedupMap) {
+        if (ts < cutoff) dedupMap.delete(k);
+    }
+}
+
+/**
+ * Run the standard commit-then-enrich flow for a single session.
+ *
+ * @param {object} opts
+ * @param {object} opts.aquifer — Aquifer instance
+ * @param {string} opts.sessionId
+ * @param {string} opts.agentId
+ * @param {string} [opts.source] — caller-provided source tag (e.g. 'openclaw', 'cc', 'opencode')
+ * @param {string} [opts.sessionKey] — passed through to commit()
+ * @param {any[]} opts.rawEntries — host-native session entries
+ * @param {'gateway'|'cc'|'claude-code'|'preNormalized'} [opts.adapter]
+ *        'preNormalized' means rawEntries already matches normalizeMessages output
+ *        (used by OpenCode which reads SQLite directly).
+ * @param {object} [opts.preNormalized] — { messages, userCount, ... } ready to commit,
+ *        required when adapter === 'preNormalized'
+ * @param {number} [opts.minUserMessages=3] — enrich threshold
+ * @param {boolean} [opts.enrich=true] — when false, commit only; don't enrich or skip.
+ *        Useful for pull-style ingest (OpenCode) where enrichment runs later.
+ * @param {Map} [opts.dedupMap] — Map<key, timestamp>; same session won't process twice within TTL
+ * @param {Set} [opts.inFlight] — Set<key>; concurrent firings are guarded
+ * @param {function} [opts.postProcess] — forwarded to enrich()
+ * @param {function} [opts.summaryFn] — forwarded to enrich()
+ * @param {function} [opts.entityParseFn] — forwarded to enrich()
+ * @param {object} [opts.logger] — { info, warn }
+ * @returns {Promise<{status:string, normalized:any[]|null, counts:object|null, enrichResult:object|null, skipReason?:string}>}
+ */
+async function runIngest(opts = {}) {
+    const {
+        aquifer, sessionId, agentId, source, sessionKey,
+        rawEntries, adapter, preNormalized,
+        minUserMessages = 3,
+        enrich = true,
+        dedupMap = null, inFlight = null,
+        postProcess = null, summaryFn = null, entityParseFn = null,
+        logger = console,
+    } = opts;
+
+    if (!aquifer) throw new Error('aquifer is required');
+    if (!sessionId) throw new Error('sessionId is required');
+    if (!agentId) throw new Error('agentId is required');
+
+    const dedupKey = `${agentId}:${sessionId}`;
+    if (dedupMap && dedupMap.has(dedupKey)) {
+        return { status: 'dedup', normalized: null, counts: null, enrichResult: null, skipReason: 'recent' };
+    }
+    if (inFlight && inFlight.has(dedupKey)) {
+        return { status: 'dedup', normalized: null, counts: null, enrichResult: null, skipReason: 'in_flight' };
+    }
+    if (inFlight) inFlight.add(dedupKey);
+
+    try {
+        // 1. Normalize
+        let norm;
+        if (adapter === 'preNormalized') {
+            if (!preNormalized) throw new Error('preNormalized adapter requires opts.preNormalized');
+            norm = preNormalized;
+        } else {
+            norm = normalizeMessages(rawEntries, { adapter });
+        }
+
+        if (norm.userCount === 0) {
+            return { status: 'skipped_empty', normalized: norm.messages, counts: norm, enrichResult: null, skipReason: 'no_user_messages' };
+        }
+
+        // 2. Commit
+        await aquifer.commit(sessionId, norm.messages, {
+            agentId,
+            source: source || adapter || 'api',
+            sessionKey: sessionKey || null,
+            model: norm.model,
+            tokensIn: norm.tokensIn,
+            tokensOut: norm.tokensOut,
+            startedAt: norm.startedAt,
+            lastMessageAt: norm.lastMessageAt,
+        });
+        if (logger && logger.info) logger.info(`[aquifer-ingest] committed ${sessionId} (${norm.messages.length} msgs, user=${norm.userCount})`);
+
+        // 3. Enrich or skip (unless caller opts out — then commit only)
+        let enrichResult = null;
+        if (!enrich) {
+            if (dedupMap) { dedupMap.set(dedupKey, Date.now()); evictStale(dedupMap); }
+            return { status: 'committed_only', normalized: norm.messages, counts: norm, enrichResult: null };
+        }
+        if (norm.userCount >= minUserMessages) {
+            try {
+                enrichResult = await aquifer.enrich(sessionId, {
+                    agentId,
+                    summaryFn: summaryFn || undefined,
+                    entityParseFn: entityParseFn || undefined,
+                    postProcess: postProcess || undefined,
+                });
+                if (logger && logger.info) {
+                    logger.info(`[aquifer-ingest] enriched ${sessionId} (turns=${enrichResult.turnsEmbedded}, entities=${enrichResult.entitiesFound})`);
+                }
+            } catch (enrichErr) {
+                if (logger && logger.warn) logger.warn(`[aquifer-ingest] enrich failed for ${sessionId}: ${enrichErr.message}`);
+                // Commit already succeeded — don't rethrow
+            }
+        } else {
+            try {
+                await aquifer.skip(sessionId, { agentId, reason: `user_count=${norm.userCount} < min=${minUserMessages}` });
+            } catch (skipErr) {
+                if (logger && logger.warn) logger.warn(`[aquifer-ingest] skip failed for ${sessionId}: ${skipErr.message}`);
+            }
+            return { status: 'skipped_short', normalized: norm.messages, counts: norm, enrichResult: null, skipReason: `user_count=${norm.userCount}` };
+        }
+
+        if (dedupMap) {
+            dedupMap.set(dedupKey, Date.now());
+            evictStale(dedupMap);
+        }
+
+        return { status: 'ok', normalized: norm.messages, counts: norm, enrichResult };
+    } finally {
+        if (inFlight) inFlight.delete(dedupKey);
+    }
+}
+
+module.exports = { runIngest };