@shadowforge0/aquifer-memory 1.0.2 → 1.2.1

package/core/storage.js

@@ -281,7 +281,10 @@ async function searchSessions(pool, query, {
     FROM ${qi(schema)}.sessions s
     LEFT JOIN ${qi(schema)}.session_summaries ss ON ss.session_row_id = s.id
     WHERE ${where.join(' AND ')}
-    ORDER BY fts_rank DESC, s.last_message_at DESC NULLS LAST
+    ORDER BY
+      COALESCE(ss.search_text ILIKE '%' || $1 || '%', FALSE) DESC,
+      fts_rank DESC,
+      s.last_message_at DESC NULLS LAST
     LIMIT $${params.length}`,
     params
   );
@@ -360,32 +363,44 @@ async function upsertTurnEmbeddings(pool, sessionRowId, {
     throw new Error(`turns.length (${turns.length}) !== vectors.length (${vectors.length})`);
   }
 
+  // Batch insert: build multi-row VALUES clause
+  const valueClauses = [];
+  const params = [];
+
   for (let i = 0; i < turns.length; i++) {
     const t = turns[i];
     const vec = vectors[i];
     if (!vec) continue;
 
     const contentHash = crypto.createHash('sha256').update(t.text).digest('hex').slice(0, 16);
-    await pool.query(
-      `INSERT INTO ${qi(schema)}.turn_embeddings
-        (session_row_id, tenant_id, session_id, agent_id, source,
-         turn_index, message_index, role, content_text, content_hash, embedding)
-      VALUES ($1,$2,$3,$4,$5,$6,$7,'user',$8,$9,$10::vector)
-      ON CONFLICT (session_row_id, message_index) DO UPDATE SET
-        content_text = EXCLUDED.content_text,
-        content_hash = EXCLUDED.content_hash,
-        embedding = CASE
-          WHEN ${qi(schema)}.turn_embeddings.content_hash = EXCLUDED.content_hash
-          THEN ${qi(schema)}.turn_embeddings.embedding
-          ELSE EXCLUDED.embedding
-        END`,
-      [
-        sessionRowId, tenantId, sessionId, agentId, source || null,
-        t.turnIndex, t.messageIndex,
-        t.text, contentHash, vecToStr(vec),
-      ]
+    const off = params.length;
+    params.push(
+      sessionRowId, tenantId, sessionId, agentId, source || null,
+      t.turnIndex, t.messageIndex,
+      t.text, contentHash, vecToStr(vec),
+    );
+    valueClauses.push(
+      `($${off+1},$${off+2},$${off+3},$${off+4},$${off+5},$${off+6},$${off+7},'user',$${off+8},$${off+9},$${off+10}::vector)`
     );
   }
+
+  if (valueClauses.length === 0) return;
+
+  await pool.query(
+    `INSERT INTO ${qi(schema)}.turn_embeddings
+      (session_row_id, tenant_id, session_id, agent_id, source,
+       turn_index, message_index, role, content_text, content_hash, embedding)
+    VALUES ${valueClauses.join(',\n')}
+    ON CONFLICT (session_row_id, message_index) DO UPDATE SET
+      content_text = EXCLUDED.content_text,
+      content_hash = EXCLUDED.content_hash,
+      embedding = CASE
+        WHEN ${qi(schema)}.turn_embeddings.content_hash = EXCLUDED.content_hash
+        THEN ${qi(schema)}.turn_embeddings.embedding
+        ELSE EXCLUDED.embedding
+      END`,
+    params
+  );
 }
 
 // ---------------------------------------------------------------------------
@@ -403,6 +418,16 @@ async function searchTurnEmbeddings(pool, {
   source,
   limit = 15,
 }) {
+  // HNSW index fires only on `ORDER BY embedding <=> $vec LIMIT N` without
+  // additional predicates in the same query level. So the CTE does a plain
+  // nearest-neighbor scan (uses idx_turn_emb_embedding_hnsw at scale), then
+  // the outer SELECT applies tenant/agent/date/source filters and dedups.
+  //
+  // Filter narrowness may leave fewer than `limit` rows after post-filter;
+  // NN_OVERFETCH trades extra vector work for filter survival headroom.
+  const NN_OVERFETCH = 10;
+  const nnLimit = Math.max(50, limit * NN_OVERFETCH);
+
   const where = ['s.tenant_id = $1'];
   const params = [tenantId];
 
@@ -421,40 +446,70 @@ async function searchTurnEmbeddings(pool, {
   }
   if (agentIds) {
     params.push(agentIds);
-    where.push(`t.agent_id = ANY($${params.length})`);
+    where.push(`s.agent_id = ANY($${params.length})`);
   }
   if (source) {
     params.push(source);
-    where.push(`t.source = $${params.length}`);
+    where.push(`s.source = $${params.length}`);
   }
 
   params.push(`[${queryVec.join(',')}]`);
   const vecPos = params.length;
-
-  // m5: use subquery with LIMIT to avoid scanning all rows
-  params.push(limit * 3); // fetch more than needed for DISTINCT ON dedup
-  const innerLimitPos = params.length;
+  params.push(nnLimit);
+  const nnLimitPos = params.length;
 
   const result = await pool.query(
-    `SELECT * FROM (
-      SELECT DISTINCT ON (t.session_row_id)
+    `WITH nn AS (
+      SELECT t.session_row_id, t.content_text, t.turn_index,
+             (t.embedding <=> $${vecPos}::vector) AS turn_distance
+      FROM ${qi(schema)}.turn_embeddings t
+      ORDER BY t.embedding <=> $${vecPos}::vector ASC
+      LIMIT $${nnLimitPos}
+    )
+    SELECT * FROM (
+      SELECT DISTINCT ON (nn.session_row_id)
         s.session_id, s.id AS session_row_id, s.agent_id, s.source, s.started_at,
         ss.summary_text, ss.structured_summary, ss.access_count, ss.last_accessed_at,
         COALESCE(ss.trust_score, 0.5) AS trust_score,
-        t.content_text AS matched_turn_text, t.turn_index AS matched_turn_index,
-        (t.embedding <=> $${vecPos}::vector) AS turn_distance
-      FROM ${qi(schema)}.turn_embeddings t
-      JOIN ${qi(schema)}.sessions s ON s.id = t.session_row_id
+        nn.content_text AS matched_turn_text, nn.turn_index AS matched_turn_index,
+        nn.turn_distance
+      FROM nn
+      JOIN ${qi(schema)}.sessions s ON s.id = nn.session_row_id
       LEFT JOIN ${qi(schema)}.session_summaries ss ON ss.session_row_id = s.id
       WHERE ${where.join(' AND ')}
-      ORDER BY t.session_row_id, turn_distance ASC
-    ) sub
-    ORDER BY turn_distance ASC
-    LIMIT $${innerLimitPos}`,
+      ORDER BY nn.session_row_id, nn.turn_distance ASC
+    ) dedup
+    ORDER BY turn_distance ASC`,
     params
   );
 
-  return { rows: result.rows.slice(0, limit) };
+  if (result.rows.length > 0) {
+    return { rows: result.rows.slice(0, limit) };
+  }
+
+  // Fallback: HNSW-first path filtered out to nothing. This can happen when
+  // tenant/agent filters are narrow enough to eliminate every NN candidate.
+  // Pay the cost of a filter-first scan to guarantee we don't silently return
+  // empty when qualifying rows exist. No HNSW on this path — slower, correct.
+  const fallbackParams = params.slice(0, params.length - 1); // drop nnLimit
+  fallbackParams.push(limit);
+  const fallbackLimitPos = fallbackParams.length;
+  const fallback = await pool.query(
+    `SELECT DISTINCT ON (t.session_row_id)
+      s.session_id, s.id AS session_row_id, s.agent_id, s.source, s.started_at,
+      ss.summary_text, ss.structured_summary, ss.access_count, ss.last_accessed_at,
+      COALESCE(ss.trust_score, 0.5) AS trust_score,
+      t.content_text AS matched_turn_text, t.turn_index AS matched_turn_index,
+      (t.embedding <=> $${vecPos}::vector) AS turn_distance
+    FROM ${qi(schema)}.turn_embeddings t
+    JOIN ${qi(schema)}.sessions s ON s.id = t.session_row_id
+    LEFT JOIN ${qi(schema)}.session_summaries ss ON ss.session_row_id = s.id
+    WHERE ${where.join(' AND ')}
+    ORDER BY t.session_row_id, t.embedding <=> $${vecPos}::vector ASC
+    LIMIT $${fallbackLimitPos}`,
+    fallbackParams
+  );
+  return { rows: fallback.rows };
 }
 
 // ---------------------------------------------------------------------------
@@ -491,16 +546,32 @@ async function recordFeedback(pool, {
     }
 
     const trustBefore = parseFloat(current.rows[0].trust_score);
-    const trustAfter = verdict === 'helpful'
-      ? Math.min(1.0, trustBefore + TRUST_UP)
-      : Math.max(0.0, trustBefore - TRUST_DOWN);
 
-    await client.query(
-      `UPDATE ${qi(schema)}.session_summaries
-      SET trust_score = $1, updated_at = now()
-      WHERE session_row_id = $2`,
-      [trustAfter, sessionRowId]
+    // Dedupe: the same (agent, verdict) applied more than once must not stack.
+    // Audit row is still inserted so the sequence of feedback events is
+    // preserved; only the trust_score delta is skipped.
+    const prior = await client.query(
+      `SELECT 1 FROM ${qi(schema)}.session_feedback
+       WHERE session_row_id = $1 AND agent_id = $2 AND verdict = $3
+       LIMIT 1`,
+      [sessionRowId, agentId, verdict]
     );
+    const isDup = prior.rows.length > 0;
+
+    const trustAfter = isDup
+      ? trustBefore
+      : (verdict === 'helpful'
+          ? Math.min(1.0, trustBefore + TRUST_UP)
+          : Math.max(0.0, trustBefore - TRUST_DOWN));
+
+    if (!isDup) {
+      await client.query(
+        `UPDATE ${qi(schema)}.session_summaries
+        SET trust_score = $1, updated_at = now()
+        WHERE session_row_id = $2`,
+        [trustAfter, sessionRowId]
+      );
+    }
 
     await client.query(
       `INSERT INTO ${qi(schema)}.session_feedback
@@ -510,7 +581,7 @@ async function recordFeedback(pool, {
     );
 
     await client.query('COMMIT');
-    return { trustBefore, trustAfter, verdict };
+    return { trustBefore, trustAfter, verdict, duplicate: isDup };
   } catch (err) {
     await client.query('ROLLBACK').catch(() => {});
     throw err;

package/docs/postprocess-contract.md

@@ -0,0 +1,132 @@
+# `enrich({ postProcess })` Contract
+
+`aquifer.enrich(sessionId, opts)` runs commit → summarize → embed → entity-extract → mark-status inside a single DB transaction. After the transaction commits and the client is released, if `opts.postProcess` was supplied, Aquifer invokes it once with a context object. This is how consumers hook persona-specific side-effects (daily logs, workspace files, consolidation, narrative regen, metrics) without mutating core.
+
+**Stability**: stable in 1.x. Additive changes only (new ctx fields). No removals or breaking renames without a major bump.
+
+## Signature
+
+```ts
+postProcess?: (ctx: PostProcessContext) => Promise<void>
+```
+
+## When it runs
+
+- **After** transaction commit and client release. The session row is already at its final status (`succeeded` or `partial`); nothing in postProcess can affect that.
+- **At most once per enrich call**. No retry. If `postProcess` throws, the error is captured on the returned result as `postProcessError` (not re-thrown).
+- Best-effort. The enrich call's return value resolves regardless of postProcess outcome.
+
+## `ctx` shape
+
+```ts
+interface PostProcessContext {
+  session: {
+    id: number;              // DB primary key (miranda.sessions.id)
+    sessionId: string;       // caller-provided session key
+    agentId: string;
+    model: string | null;
+    source: string | null;
+    startedAt: string | null;  // ISO-8601
+    endedAt: string | null;    // ISO-8601
+  };
+
+  // opts.model override, falling back to session.model. Handy for consumers
+  // that want to pass the runtime model into downstream consolidation prompts.
+  effectiveModel: string | null;
+
+  // Summary result, if summarize ran. Null when skipSummary or summary failed.
+  summary: {
+    summaryText: string;
+    structuredSummary: object | null;  // custom summaryFn payload
+  } | null;
+
+  // Summary-level embedding vector (size = embed.dim). Null if embed skipped/failed.
+  embedding: number[] | null;
+
+  // Per-turn embedding vectors (one per user turn). Null if skipped/failed.
+  turnVectors: number[][] | null;
+
+  // Passthrough from customSummaryFn return { extra }. Consumers use this to
+  // smuggle intermediate results (recap/sections/workingFacts) from summaryFn
+  // into postProcess without recomputing.
+  extra: any;
+
+  // Messages used for embedding/entity extraction. Same array commit() saw.
+  normalized: Array<{ role: string; content: string; timestamp?: string }>;
+
+  // Parsed entities from entityParseFn (or built-in parser).
+  parsedEntities: Array<{ name: string; normalizedName: string; aliases: string[]; type: string }>;
+
+  // Which pipeline steps ran.
+  skipped: { summary: boolean; entities: boolean; turns: boolean };
+
+  // Counts from the tx.
+  turnsEmbedded: number;
+  entitiesFound: number;
+
+  // Non-fatal failures collected inside enrich. Defensive copy — mutating this
+  // array does NOT affect enrich's own warnings list.
+  warnings: string[];
+}
+```
+
+## Typical usage
+
+```js
+const result = await aquifer.enrich(sessionId, {
+  agentId: 'main',
+  summaryFn: async (msgs) => {
+    const output = await callLlm(buildPrompt({ msgs }));
+    const sections = parseSummaryOutput(output);
+    const recap = parseRecapLines(sections.recap);
+    return {
+      summaryText: recap.overview || '',
+      structuredSummary: recap,
+      entityRaw: sections.entities || null,
+      extra: { sections, recap, workingFacts: parseWorkingFacts(sections.working_facts) },
+    };
+  },
+  entityParseFn: (text) => parseEntitySection(text).entities,
+  postProcess: async (ctx) => {
+    const recap = ctx.extra?.recap;
+    const sections = ctx.extra?.sections;
+    const workingFacts = ctx.extra?.workingFacts || [];
+
+    // Daily log
+    if (recap || sections) {
+      await writeDailyEntries({ recap, sections, sessionId: ctx.session.sessionId, agentId: ctx.session.agentId });
+    }
+
+    // Write fact candidates (consumer-specific table, not in Aquifer schema)
+    if (workingFacts.length > 0) {
+      await writeFactCandidates({ facts: workingFacts, sessionId: ctx.session.sessionId });
+    }
+
+    // Consolidation (optional — requires enableFacts())
+    if (recap) {
+      const prompt = buildConsolidationPrompt({ recap, activeFacts, candidates, currentNarrative });
+      const output = await callLlm(prompt);
+      const { actions } = parseConsolidationOutput(output);
+      if (actions.length > 0) {
+        await aquifer.consolidate(ctx.session.sessionId, { actions, agentId: ctx.session.agentId });
+      }
+    }
+  },
+});
+
+if (result.postProcessError) {
+  logger.warn(`postProcess failed: ${result.postProcessError.message}`);
+}
+```
+
+## What NOT to do in postProcess
+
+- Don't throw as a signal of "enrich should have failed" — enrich is already committed. Use warnings or a separate audit table.
+- Don't mutate `ctx.normalized`, `ctx.parsedEntities`, or `ctx.warnings`. They're shared-reference with the enrich return; defensive copy if you need to modify.
+- Don't rely on postProcess running quickly — it's outside the tx. Long-running work should be fire-and-forget (see Miranda's `setImmediate` consolidation) or queued.
+
+## What Aquifer guarantees
+
+- `postProcess` receives the same `session` row the tx wrote. No stale reads.
+- If enrich's tx rolls back, postProcess is NOT called.
+- If postProcess throws, the error is on `result.postProcessError`. The session status is unaffected.

package/index.js

@@ -3,5 +3,13 @@
 const { createAquifer } = require('./core/aquifer');
 const { createEmbedder } = require('./pipeline/embed');
 const { createReranker } = require('./pipeline/rerank');
+const { normalizeEntityName } = require('./core/entity');
+const { parseEntitySection } = require('./consumers/shared/entity-parser');
 
-module.exports = { createAquifer, createEmbedder, createReranker };
+module.exports = {
+  createAquifer,
+  createEmbedder,
+  createReranker,
+  normalizeEntityName,
+  parseEntitySection,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shadowforge0/aquifer-memory",
-  "version": "1.0.2",
+  "version": "1.2.1",
   "description": "PG-native long-term memory for AI agents. Turn-level embedding, hybrid RRF ranking, optional knowledge graph. MCP server, CLI, and library API.",
   "main": "index.js",
   "files": [
@@ -9,6 +9,9 @@
     "pipeline/",
     "schema/",
     "consumers/",
+    "consumers/miranda/",
+    "consumers/default/",
+    "consumers/openclaw-ext/",
     "docs/",
     "scripts/"
   ],
@@ -20,8 +23,17 @@
     "./consumers/mcp": "./consumers/mcp.js",
     "./consumers/openclaw-plugin": "./consumers/openclaw-plugin.js",
     "./consumers/opencode": "./consumers/opencode.js",
+    "./consumers/claude-code": "./consumers/claude-code.js",
+    "./consumers/miranda": "./consumers/miranda/index.js",
+    "./consumers/default": "./consumers/default/index.js",
+    "./consumers/openclaw-ext": "./consumers/openclaw-ext/index.js",
     "./consumers/shared/config": "./consumers/shared/config.js",
-    "./consumers/shared/factory": "./consumers/shared/factory.js"
+    "./consumers/shared/factory": "./consumers/shared/factory.js",
+    "./consumers/shared/entity-parser": "./consumers/shared/entity-parser.js",
+    "./consumers/shared/normalize": "./consumers/shared/normalize.js",
+    "./consumers/shared/ingest": "./consumers/shared/ingest.js",
+    "./consumers/shared/recall-format": "./consumers/shared/recall-format.js",
+    "./consumers/shared/llm-autodetect": "./consumers/shared/llm-autodetect.js"
   },
   "repository": {
     "type": "git",
@@ -32,11 +44,20 @@
     "url": "https://github.com/shadowforge0/aquifer/issues"
   },
   "author": "shadowforge0",
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "test:integration": "node --test test/integration.test.js",
+    "lint": "eslint index.js core/*.js consumers/*.js consumers/shared/*.js consumers/miranda/*.js consumers/miranda/prompts/*.js consumers/default/*.js consumers/default/prompts/*.js consumers/openclaw-ext/*.js pipeline/*.js pipeline/consolidation/*.js scripts/*.js test/*.js",
+    "prepare": "git config core.hooksPath .githooks 2>/dev/null || true"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "pg": "^8.13.0",
     "zod": "^3.25.76"
   },
+  "devDependencies": {
+    "eslint": "^9.0.0"
+  },
   "engines": {
     "node": ">=18.0.0"
   },

package/pipeline/_http.js

@@ -28,7 +28,7 @@ function httpRequest(url, options, body) {
         }
         try {
           finish(resolve, JSON.parse(raw));
-        } catch (e) {
+        } catch {
           finish(reject, new Error(`Invalid JSON response: ${raw.slice(0, 200)}`));
         }
       });

package/pipeline/consolidation/apply.js

@@ -0,0 +1,176 @@
+'use strict';
+
+// ---------------------------------------------------------------------------
+// Consolidation apply — executes a batch of fact-lifecycle actions in one tx.
+//
+// Actions (each object in the array):
+//   { action: 'promote',   factId }                          candidate → active
+//   { action: 'create',    subject, statement, importance? } new active fact
+//   { action: 'update',    factId, statement }               refresh active statement
+//   { action: 'confirm',   factId }                          bump last_confirmed_at
+//   { action: 'stale',     factId }                          active → stale
+//   { action: 'discard',   factId }                          candidate → archived
+//   { action: 'merge',     factId, targetId }                candidate archived, target confirmed
+//   { action: 'supersede', factId, targetId }                active → superseded by target
+//
+// All mutations scoped to (tenantId, agentId). The caller is responsible for
+// providing a normalizer for subject_key (fall back to raw subject if absent).
+// ---------------------------------------------------------------------------
+
+function qi(identifier) { return `"${identifier}"`; }
+
+async function applyConsolidation(pool, {
+  actions,
+  agentId,
+  sessionId,
+  schema,
+  tenantId = 'default',
+  normalizeSubject = null,
+  recapOverview = '',
+} = {}) {
+  if (!pool) throw new Error('pool is required');
+  if (!schema) throw new Error('schema is required');
+  if (!agentId) throw new Error('agentId is required');
+  if (!Array.isArray(actions)) throw new Error('actions must be an array');
+
+  const tbl = `${qi(schema)}.facts`;
+  const summary = {
+    promote: 0, create: 0, update: 0, confirm: 0,
+    stale: 0, discard: 0, merge: 0, supersede: 0,
+    skipped: 0,
+  };
+
+  if (actions.length === 0) return summary;
+
+  const client = await pool.connect();
+  try {
+    await client.query('BEGIN');
+
+    for (const act of actions) {
+      switch (act.action) {
+        case 'promote': {
+          const r = await client.query(
+            `UPDATE ${tbl} SET status = 'active', last_confirmed_at = now()
+             WHERE id = $1 AND status = 'candidate' AND agent_id = $2 AND tenant_id = $3`,
+            [act.factId, agentId, tenantId],
+          );
+          summary.promote += r.rowCount;
+          if (r.rowCount === 0) summary.skipped++;
+          break;
+        }
+
+        case 'create': {
+          const subjectLabel = act.subject ? String(act.subject).slice(0, 200) : '';
+          const subjectKey = normalizeSubject ? normalizeSubject(subjectLabel) : subjectLabel.trim().toLowerCase();
+          if (!subjectKey) { summary.skipped++; break; }
+          const statement = act.statement ? String(act.statement).slice(0, 2000) : '';
+          if (!statement) { summary.skipped++; break; }
+          const importance = Number.isFinite(act.importance) ? act.importance : 7;
+          const evidence = JSON.stringify([{
+            type: 'session_ref',
+            session_id: sessionId || null,
+            excerpt: (recapOverview || '').slice(0, 200),
+          }]);
+          const r = await client.query(
+            `INSERT INTO ${tbl}
+             (tenant_id, subject_key, subject_label, statement, status, importance,
+              source_session_id, agent_id, evidence)
+             VALUES ($1, $2, $3, $4, 'active', $5, $6, $7, $8::jsonb)
+             ON CONFLICT DO NOTHING`,
+            [tenantId, subjectKey, subjectLabel, statement, importance, sessionId || null, agentId, evidence],
+          );
+          summary.create += r.rowCount;
+          if (r.rowCount === 0) summary.skipped++;
+          break;
+        }
+
+        case 'update': {
+          const statement = act.statement ? String(act.statement).slice(0, 2000) : '';
+          if (!statement) { summary.skipped++; break; }
+          const r = await client.query(
+            `UPDATE ${tbl} SET statement = $1, last_confirmed_at = now()
+             WHERE id = $2 AND status = 'active' AND agent_id = $3 AND tenant_id = $4`,
+            [statement, act.factId, agentId, tenantId],
+          );
+          summary.update += r.rowCount;
+          if (r.rowCount === 0) summary.skipped++;
+          break;
+        }
+
+        case 'confirm': {
+          const r = await client.query(
+            `UPDATE ${tbl} SET last_confirmed_at = now()
+             WHERE id = $1 AND status = 'active' AND agent_id = $2 AND tenant_id = $3`,
+            [act.factId, agentId, tenantId],
+          );
+          summary.confirm += r.rowCount;
+          if (r.rowCount === 0) summary.skipped++;
+          break;
+        }
+
+        case 'stale': {
+          const r = await client.query(
+            `UPDATE ${tbl} SET status = 'stale'
+             WHERE id = $1 AND status = 'active' AND agent_id = $2 AND tenant_id = $3`,
+            [act.factId, agentId, tenantId],
+          );
+          summary.stale += r.rowCount;
+          if (r.rowCount === 0) summary.skipped++;
+          break;
+        }
+
+        case 'discard': {
+          const r = await client.query(
+            `UPDATE ${tbl} SET status = 'archived'
+             WHERE id = $1 AND status = 'candidate' AND agent_id = $2 AND tenant_id = $3`,
+            [act.factId, agentId, tenantId],
+          );
+          summary.discard += r.rowCount;
+          if (r.rowCount === 0) summary.skipped++;
+          break;
+        }
+
+        case 'merge': {
+          const r1 = await client.query(
+            `UPDATE ${tbl} SET last_confirmed_at = now()
+             WHERE id = $1 AND status = 'active' AND tenant_id = $2`,
+            [act.targetId, tenantId],
+          );
+          const r2 = await client.query(
+            `UPDATE ${tbl} SET status = 'archived'
+             WHERE id = $1 AND status = 'candidate' AND tenant_id = $2`,
+            [act.factId, tenantId],
+          );
+          summary.merge += Math.min(r1.rowCount, r2.rowCount);
+          if (r1.rowCount === 0 || r2.rowCount === 0) summary.skipped++;
+          break;
+        }
+
+        case 'supersede': {
+          const r = await client.query(
+            `UPDATE ${tbl} SET status = 'superseded', superseded_by = $1
+             WHERE id = $2 AND status = 'active' AND tenant_id = $3`,
+            [act.targetId, act.factId, tenantId],
+          );
+          summary.supersede += r.rowCount;
+          if (r.rowCount === 0) summary.skipped++;
+          break;
+        }
+
+        default:
+          summary.skipped++;
+      }
+    }
+
+    await client.query('COMMIT');
+  } catch (err) {
+    await client.query('ROLLBACK').catch(() => {});
+    throw err;
+  } finally {
+    client.release();
+  }
+
+  return summary;
+}
+
+module.exports = { applyConsolidation };

package/pipeline/consolidation/index.js

@@ -0,0 +1,21 @@
+'use strict';
+
+// ---------------------------------------------------------------------------
+// Consolidation pipeline
+//
+// Mechanics only — Aquifer ships the 8-action apply + schema. The prompt and
+// output parser stay in consumers (they're persona-specific: different agents
+// want different wording, language, and action vocabulary extensions).
+//
+// Typical flow in a consumer:
+//
+//   const output = await llmFn(consumerBuildPrompt({...}));
+//   const { actions } = consumerParse(output);
+//   await aquifer.consolidate(sessionId, { actions, agentId });
+//
+// aquifer.consolidate() is defined in core/aquifer.js and delegates here.
+// ---------------------------------------------------------------------------
+
+const { applyConsolidation } = require('./apply');
+
+module.exports = { applyConsolidation };

package/pipeline/extract-entities.js

@@ -6,7 +6,7 @@ const { parseEntityOutput } = require('../core/entity');
 // defaultEntityPrompt
 // ---------------------------------------------------------------------------
 
-function defaultEntityPrompt(messages, opts = {}) {
+function defaultEntityPrompt(messages) {
   const conversation = messages
     .map(m => `[${m.role}] ${typeof m.content === 'string' ? m.content : JSON.stringify(m.content)}`)
     .join('\n');
@@ -60,7 +60,7 @@ async function extractEntities(messages, {
     const prompt = buildPrompt(messages, {});
     const response = await llmFn(prompt);
     return parseEntityOutput(response);
-  } catch (err) {
+  } catch {
     // LLM failure: return empty, never throw
     return [];
   }

package/pipeline/rerank.js

@@ -39,7 +39,7 @@ function createTEIReranker(config) {
   const initialBackoffMs = config.initialBackoffMs || 250;
 
   return {
-    async rerank(query, documents, opts = {}) {
+    async rerank(query, documents, _opts = {}) {
       if (!query || !documents || documents.length === 0) return [];
 
       const result = await withRetry(