@shadowforge0/aquifer-memory 1.0.3 → 1.3.0

package/core/state.js

@@ -0,0 +1,163 @@
+'use strict';
+
+// aq.state.* — latest-snapshot-per-scope session state capability.
+//
+// Spec: aquifer-completion §7 sessionState. Strict core table is
+// ${schema}.session_states. Default shape
+// { goal, active_work, blockers, affect } is projected to explicit
+// columns for cheap filtering; full payload also stored as JSONB so
+// consumer-specific fields are lossless.
+//
+// write() supersedes the prior is_latest=true row for the same
+// (tenant, agent, scope_key) atomically. idempotencyKey replay returns
+// the existing row unchanged. Partial unique index enforces at-most-one
+// latest per scope.
+
+const crypto = require('crypto');
+const { AqError, ok, err } = require('./errors');
+
+const DEFAULT_PROFILE = Object.freeze({
+  id: 'anon',
+  version: 0,
+  schemaHash: 'pending',
+});
+
+function resolveProfile(profile) {
+  if (!profile) return DEFAULT_PROFILE;
+  return {
+    id: profile.id || DEFAULT_PROFILE.id,
+    version: Number.isInteger(profile.version) ? profile.version : DEFAULT_PROFILE.version,
+    schemaHash: profile.schemaHash || DEFAULT_PROFILE.schemaHash,
+  };
+}
+
+function toNumber(v) {
+  if (v === null || v === undefined) return null;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : null;
+}
+
+function defaultIdempotencyKey({ tenantId, agentId, scopeKey, payload }) {
+  return crypto.createHash('sha256')
+    .update(`${tenantId}:${agentId}:${scopeKey}:${JSON.stringify(payload)}`)
+    .digest('hex');
+}
+
+function mapRow(row) {
+  if (!row) return null;
+  return {
+    stateId: toNumber(row.id),
+    agentId: row.agent_id,
+    scopeKey: row.scope_key,
+    payload: row.payload || {},
+    isLatest: row.is_latest,
+    supersedesStateId: toNumber(row.supersedes_state_id),
+    createdAt: row.created_at,
+  };
+}
+
+function createState({ pool, schema, defaultTenantId }) {
+  async function write(input) {
+    try {
+      if (!input || typeof input !== 'object') {
+        return err('AQ_INVALID_INPUT', 'write requires an input object');
+      }
+      if (!input.agentId) return err('AQ_INVALID_INPUT', 'agentId is required');
+      if (!input.payload || typeof input.payload !== 'object') {
+        return err('AQ_INVALID_INPUT', 'payload is required');
+      }
+      const tenantId = input.tenantId || defaultTenantId || 'default';
+      const agentId = input.agentId;
+      const scopeKey = input.scopeKey || agentId;
+      const payload = input.payload;
+      const profile = resolveProfile(input.profile);
+      const idempotencyKey = input.idempotencyKey
+        || defaultIdempotencyKey({ tenantId, agentId, scopeKey, payload });
+
+      // Projected columns for cheap filtering/indexes. Fall back cleanly
+      // when payload uses consumer-specific shape.
+      const goal = typeof payload.goal === 'string' ? payload.goal : null;
+      const activeWork = Array.isArray(payload.active_work) ? payload.active_work : [];
+      const blockers = Array.isArray(payload.blockers) ? payload.blockers : [];
+      const affect = payload.affect && typeof payload.affect === 'object' ? payload.affect : {};
+
+      const client = await pool.connect();
+      try {
+        await client.query('BEGIN');
+
+        const existing = await client.query(
+          `SELECT * FROM ${schema}.session_states WHERE idempotency_key = $1`,
+          [idempotencyKey],
+        );
+        if (existing.rowCount > 0) {
+          await client.query('COMMIT');
+          return ok(mapRow(existing.rows[0]));
+        }
+
+        const prev = await client.query(
+          `UPDATE ${schema}.session_states
+             SET is_latest = false
+           WHERE tenant_id = $1 AND agent_id = $2 AND scope_key = $3
+             AND is_latest = true
+           RETURNING id`,
+          [tenantId, agentId, scopeKey],
+        );
+        const supersedesStateId = prev.rowCount > 0 ? toNumber(prev.rows[0].id) : null;
+
+        const inserted = await client.query(
+          `INSERT INTO ${schema}.session_states (
+             tenant_id, agent_id, scope_key, source_session_id,
+             consumer_profile_id, consumer_profile_version, consumer_schema_hash,
+             idempotency_key, goal, active_work, blockers, affect, payload,
+             is_latest, supersedes_state_id
+           ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, true, $14)
+           RETURNING *`,
+          [
+            tenantId, agentId, scopeKey, input.sessionId || null,
+            profile.id, profile.version, profile.schemaHash,
+            idempotencyKey, goal,
+            JSON.stringify(activeWork), JSON.stringify(blockers), JSON.stringify(affect),
+            JSON.stringify(payload), supersedesStateId,
+          ],
+        );
+
+        await client.query('COMMIT');
+        return ok(mapRow(inserted.rows[0]));
+      } catch (e) {
+        await client.query('ROLLBACK').catch(() => {});
+        throw e;
+      } finally {
+        client.release();
+      }
+    } catch (e) {
+      if (e instanceof AqError) return err(e);
+      return err('AQ_INTERNAL', e.message, { cause: e });
+    }
+  }
+
+  async function getLatest(input = {}) {
+    try {
+      if (!input.agentId) return err('AQ_INVALID_INPUT', 'agentId is required');
+      const tenantId = input.tenantId || defaultTenantId || 'default';
+      const scopeKey = input.scopeKey || input.agentId;
+      const { rows } = await pool.query(
+        `SELECT * FROM ${schema}.session_states
+          WHERE tenant_id = $1 AND agent_id = $2
+            AND scope_key = $3 AND is_latest = true
+          LIMIT 1`,
+        [tenantId, input.agentId, scopeKey],
+      );
+      const mapped = mapRow(rows[0]);
+      return ok({
+        state: mapped ? mapped.payload : null,
+        stateId: mapped ? mapped.stateId : null,
+      });
+    } catch (e) {
+      return err('AQ_INTERNAL', e.message, { cause: e });
+    }
+  }
+
+  return { write, getLatest };
+}
+
+module.exports = { createState };

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
   );
@@ -361,7 +364,6 @@ async function upsertTurnEmbeddings(pool, sessionRowId, {
   }
 
   // Batch insert: build multi-row VALUES clause
-  const COLS_PER_ROW = 10;
   const valueClauses = [];
   const params = [];
 
@@ -416,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];
 
@@ -434,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 };
 }
 
 // ---------------------------------------------------------------------------
@@ -504,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
@@ -523,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/core/timeline.js

@@ -0,0 +1,152 @@
+'use strict';
+
+// aq.timeline.* — append-only event log capability.
+//
+// Spec: aquifer-completion §10 timeline. Fixed event shape
+// (occurred_at / source / session_ref / category / text / metadata),
+// consumer-owned category vocabulary. idempotency_key UNIQUE across the
+// table; appends with a duplicate key are a safe no-op and return the
+// existing row.
+
+const crypto = require('crypto');
+const { AqError, ok, err } = require('./errors');
+
+const DEFAULT_PROFILE = Object.freeze({
+  id: 'anon',
+  version: 0,
+  schemaHash: 'pending',
+});
+
+function resolveProfile(profile) {
+  if (!profile) return DEFAULT_PROFILE;
+  return {
+    id: profile.id || DEFAULT_PROFILE.id,
+    version: Number.isInteger(profile.version) ? profile.version : DEFAULT_PROFILE.version,
+    schemaHash: profile.schemaHash || DEFAULT_PROFILE.schemaHash,
+  };
+}
+
+function defaultIdempotencyKey({ tenantId, agentId, occurredAt, category, text }) {
+  return crypto.createHash('sha256')
+    .update(`${tenantId}:${agentId}:${occurredAt}:${category}:${text}`)
+    .digest('hex');
+}
+
+function toNumber(v) {
+  if (v === null || v === undefined) return null;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : null;
+}
+
+function mapRow(row) {
+  if (!row) return null;
+  return {
+    eventId: toNumber(row.id),
+    occurredAt: row.occurred_at,
+    source: row.source,
+    sessionRef: row.session_ref,
+    category: row.category,
+    text: row.text,
+    metadata: row.metadata || {},
+  };
+}
+
+function createTimeline({ pool, schema, defaultTenantId }) {
+  async function append(input) {
+    try {
+      if (!input || typeof input !== 'object') {
+        return err('AQ_INVALID_INPUT', 'append requires an input object');
+      }
+      if (!input.agentId) return err('AQ_INVALID_INPUT', 'agentId is required');
+      if (!input.occurredAt) return err('AQ_INVALID_INPUT', 'occurredAt is required');
+      if (!input.source) return err('AQ_INVALID_INPUT', 'source is required');
+      if (!input.category) return err('AQ_INVALID_INPUT', 'category is required');
+      if (!input.text || typeof input.text !== 'string') {
+        return err('AQ_INVALID_INPUT', 'text is required');
+      }
+
+      const tenantId = input.tenantId || defaultTenantId || 'default';
+      const agentId = input.agentId;
+      const profile = resolveProfile(input.profile);
+      const idempotencyKey = input.idempotencyKey
+        || defaultIdempotencyKey({
+          tenantId, agentId,
+          occurredAt: input.occurredAt,
+          category: input.category,
+          text: input.text,
+        });
+
+      // Idempotent append: on conflict, fall back to SELECT so the caller
+      // always gets the canonical row (the row that *won* the insert).
+      const insertResult = await pool.query(
+        `INSERT INTO ${schema}.timeline_events (
+           tenant_id, agent_id, occurred_at, source, session_ref,
+           category, text, metadata, source_session_id,
+           consumer_profile_id, consumer_profile_version, consumer_schema_hash,
+           idempotency_key
+         ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13)
+         ON CONFLICT (idempotency_key) DO NOTHING
+         RETURNING *`,
+        [
+          tenantId, agentId, input.occurredAt, input.source,
+          input.sessionRef || null, input.category, input.text,
+          input.metadata || {}, input.sessionId || null,
+          profile.id, profile.version, profile.schemaHash,
+          idempotencyKey,
+        ],
+      );
+      let row = insertResult.rows[0];
+      if (!row) {
+        const existing = await pool.query(
+          `SELECT * FROM ${schema}.timeline_events WHERE idempotency_key = $1`,
+          [idempotencyKey],
+        );
+        row = existing.rows[0];
+      }
+      const mapped = mapRow(row);
+      return ok({ eventId: mapped.eventId, event: mapped });
+    } catch (e) {
+      if (e instanceof AqError) return err(e);
+      return err('AQ_INTERNAL', e.message, { cause: e });
+    }
+  }
+
+  async function list(input = {}) {
+    try {
+      if (!input.agentId) return err('AQ_INVALID_INPUT', 'agentId is required');
+      const tenantId = input.tenantId || defaultTenantId || 'default';
+      const limit = Math.min(Math.max(input.limit || 50, 1), 500);
+
+      const params = [tenantId, input.agentId];
+      let where = 'tenant_id = $1 AND agent_id = $2';
+      if (Array.isArray(input.categories) && input.categories.length > 0) {
+        params.push(input.categories);
+        where += ` AND category = ANY($${params.length})`;
+      }
+      if (input.since) {
+        params.push(input.since);
+        where += ` AND occurred_at >= $${params.length}`;
+      }
+      if (input.until) {
+        params.push(input.until);
+        where += ` AND occurred_at <= $${params.length}`;
+      }
+      params.push(limit);
+
+      const { rows } = await pool.query(
+        `SELECT * FROM ${schema}.timeline_events
+          WHERE ${where}
+          ORDER BY occurred_at DESC, id DESC
+          LIMIT $${params.length}`,
+        params,
+      );
+      return ok({ rows: rows.map(mapRow) });
+    } catch (e) {
+      return err('AQ_INTERNAL', e.message, { cause: e });
+    }
+  }
+
+  return { append, list };
+}
+
+module.exports = { createTimeline };

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,27 @@
 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');
+const { AqError, ok, err, asResult, isKnownCode, KNOWN_CODES } = require('./core/errors');
+const { MCP_SERVER_NAME, MCP_TOOL_MANIFEST, getManifest, writeManifestFile } = require('./core/mcp-manifest');
 
-module.exports = { createAquifer, createEmbedder, createReranker };
+module.exports = {
+  createAquifer,
+  createEmbedder,
+  createReranker,
+  normalizeEntityName,
+  parseEntitySection,
+  // Completion-capability error envelope (P1 foundation).
+  AqError,
+  ok,
+  err,
+  asResult,
+  isKnownCode,
+  KNOWN_CODES,
+  // MCP tool manifest — canonical for gateway in-process + CC cross-process.
+  MCP_SERVER_NAME,
+  MCP_TOOL_MANIFEST,
+  getMcpManifest: getManifest,
+  writeMcpManifestFile: writeManifestFile,
+};