@shadowforge0/aquifer-memory 1.2.1 → 1.5.8

package/core/mcp-manifest.js

@@ -0,0 +1,131 @@
+'use strict';
+
+// MCP tool manifest — single source of truth for Aquifer's MCP surface.
+//
+// Spec: aquifer-completion §G1 (bi-directional registration). Gateway hosts
+// `require('@shadowforge0/aquifer-memory').MCP_TOOL_MANIFEST` in-process;
+// cross-process hosts (CC MCP server) consume the JSON file written by
+// `writeManifestFile()` / the `aquifer mcp-contract` CLI. Both paths read
+// from this module, so the two surfaces can never drift.
+//
+// Tool definitions are expressed as JSON Schema (standard, language-agnostic,
+// serialisable). consumers/mcp.js builds Zod schemas from these descriptors
+// at server start-up.
+
+const fs = require('fs');
+const path = require('path');
+
+const MCP_SERVER_NAME = 'aquifer-memory';
+
+const MCP_TOOL_MANIFEST = Object.freeze([
+  {
+    name: 'session_recall',
+    description: 'Search stored sessions by keyword or natural language. Use entities when the user names specific people, projects, files, tools, or concepts; entityMode="all" hard-filters to sessions containing every entity (default "any" boosts). Use mode to force fts/vector/hybrid (default hybrid). Use dateFrom/dateTo for time-bounded recall.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        query: { type: 'string', minLength: 1, description: 'Search query (keyword or natural language)' },
+        limit: { type: 'integer', minimum: 1, maximum: 20, description: 'Max results (default 5)' },
+        agentId: { type: 'string', description: 'Filter by agent ID' },
+        source: { type: 'string', description: 'Filter by source (e.g., gateway, cc)' },
+        dateFrom: { type: 'string', description: 'Start date YYYY-MM-DD' },
+        dateTo: { type: 'string', description: 'End date YYYY-MM-DD' },
+        entities: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Entity names to match',
+        },
+        entityMode: {
+          type: 'string',
+          enum: ['any', 'all'],
+          description: '"any" (default, boost) or "all" (only sessions with every entity)',
+        },
+        mode: {
+          type: 'string',
+          enum: ['fts', 'hybrid', 'vector'],
+          description: 'Recall mode: "fts" (keyword only, no embed needed), "hybrid" (default, FTS + vector), "vector" (vector only)',
+        },
+      },
+      required: ['query'],
+    },
+  },
+  {
+    name: 'session_feedback',
+    description: 'Record trust feedback on a recalled session. Helpful sessions rank higher in future recalls.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        sessionId: { type: 'string', minLength: 1, description: 'Session ID to give feedback on' },
+        verdict: { type: 'string', enum: ['helpful', 'unhelpful'], description: 'Was the recalled session useful?' },
+        note: { type: 'string', description: 'Optional reason' },
+        agentId: { type: 'string', description: 'Agent ID the session was stored under (e.g. "main"). Defaults to "agent" if omitted.' },
+      },
+      required: ['sessionId', 'verdict'],
+    },
+  },
+  {
+    name: 'memory_stats',
+    description: 'Return storage statistics for the Aquifer memory store (session counts by status, summaries, turn embeddings, entities, date range).',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {},
+    },
+  },
+  {
+    name: 'memory_pending',
+    description: 'List sessions with pending or failed processing status.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        limit: { type: 'integer', minimum: 1, maximum: 200, description: 'Max results (default 20)' },
+      },
+    },
+  },
+  {
+    name: 'session_bootstrap',
+    description: 'Load recent session context for a new conversation. Returns summaries, open items, and decisions from recent sessions. Call this at the start of a conversation for continuity; use session_recall for keyword search.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        agentId: { type: 'string', description: 'Filter by agent ID' },
+        limit: { type: 'integer', minimum: 1, maximum: 20, description: 'Max sessions (default 5)' },
+        lookbackDays: { type: 'integer', minimum: 1, maximum: 90, description: 'How far back in days (default 14)' },
+        maxChars: { type: 'integer', minimum: 500, maximum: 12000, description: 'Max output characters (default 4000)' },
+      },
+    },
+  },
+]);
+
+function getManifest() {
+  return {
+    manifestVersion: 1,
+    serverName: MCP_SERVER_NAME,
+    generatedAt: new Date().toISOString(),
+    tools: MCP_TOOL_MANIFEST.map(t => ({
+      name: t.name,
+      description: t.description,
+      inputSchema: JSON.parse(JSON.stringify(t.inputSchema)),
+    })),
+  };
+}
+
+function writeManifestFile(outPath) {
+  if (!outPath) throw new Error('outPath is required');
+  const resolved = path.resolve(outPath);
+  const dir = path.dirname(resolved);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(resolved, JSON.stringify(getManifest(), null, 2) + '\n', 'utf8');
+  return resolved;
+}
+
+module.exports = {
+  MCP_SERVER_NAME,
+  MCP_TOOL_MANIFEST,
+  getManifest,
+  writeManifestFile,
+};

package/core/narratives.js

@@ -0,0 +1,212 @@
+'use strict';
+
+// aq.narratives.* — cross-session state snapshot capability.
+//
+// Spec: aquifer-completion §2 narrative. Strict core table is
+// ${schema}.narratives, with at-most-one 'active' row per
+// (tenant_id, agent_id, scope, scope_key) enforced by partial UNIQUE index
+// idx_narratives_active_scope.
+//
+// upsertSnapshot atomically supersedes the prior active row and inserts a
+// new active row. If the same idempotencyKey has already been recorded, the
+// existing narrative is returned unchanged (safe replay).
+
+const crypto = require('crypto');
+const { AqError, ok, err } = require('./errors');
+
+// Placeholder profile stamp — real stamps land via aq.schema registry
+// (capability 4, P2-2b). Until then consumers may pass a partial profile
+// or rely on this default so narratives/timeline can ship independently.
+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, scope, scopeKey, text }) {
+  return crypto.createHash('sha256')
+    .update(`${tenantId}:${agentId}:${scope}:${scopeKey}:${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 {
+    id: toNumber(row.id),
+    tenantId: row.tenant_id,
+    agentId: row.agent_id,
+    scope: row.scope,
+    scopeKey: row.scope_key,
+    sourceSessionId: row.source_session_id,
+    text: row.text,
+    status: row.status,
+    basedOnFactIds: (row.based_on_fact_ids || []).map(toNumber),
+    metadata: row.metadata || {},
+    supersededByNarrativeId: toNumber(row.superseded_by_narrative_id),
+    effectiveAt: row.effective_at,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+    consumerProfileId: row.consumer_profile_id,
+    consumerProfileVersion: row.consumer_profile_version,
+    consumerSchemaHash: row.consumer_schema_hash,
+  };
+}
+
+function createNarratives({ pool, schema, defaultTenantId }) {
+  async function upsertSnapshot(input) {
+    try {
+      if (!input || typeof input !== 'object') {
+        return err('AQ_INVALID_INPUT', 'upsertSnapshot requires an input object');
+      }
+      if (!input.agentId) {
+        return err('AQ_INVALID_INPUT', 'agentId 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 scope = input.scope || 'agent';
+      const scopeKey = input.scopeKey || agentId;
+      const text = input.text;
+      const basedOnFactIds = Array.isArray(input.basedOnFactIds) ? input.basedOnFactIds : [];
+      const metadata = input.metadata || {};
+      const profile = resolveProfile(input.profile);
+      const idempotencyKey = input.idempotencyKey
+        || defaultIdempotencyKey({ tenantId, agentId, scope, scopeKey, text });
+
+      const client = await pool.connect();
+      try {
+        await client.query('BEGIN');
+
+        // Idempotent replay: if this idempotency_key already exists, return it.
+        const existing = await client.query(
+          `SELECT * FROM ${schema}.narratives WHERE idempotency_key = $1`,
+          [idempotencyKey],
+        );
+        if (existing.rowCount > 0) {
+          await client.query('COMMIT');
+          return ok({
+            narrative: mapRow(existing.rows[0]),
+            supersededNarrativeId: null,
+          });
+        }
+
+        // Mark the prior active row (if any) as superseded; capture its id
+        // so the caller can link supersede chain for observability.
+        const prev = await client.query(
+          `UPDATE ${schema}.narratives
+             SET status = 'superseded'
+           WHERE tenant_id = $1 AND agent_id = $2 AND scope = $3
+             AND scope_key = $4 AND status = 'active'
+           RETURNING id`,
+          [tenantId, agentId, scope, scopeKey],
+        );
+        const supersededNarrativeId = prev.rowCount > 0 ? toNumber(prev.rows[0].id) : null;
+
+        const inserted = await client.query(
+          `INSERT INTO ${schema}.narratives (
+             tenant_id, agent_id, scope, scope_key, text, status,
+             based_on_fact_ids, metadata, source_session_id,
+             consumer_profile_id, consumer_profile_version, consumer_schema_hash,
+             idempotency_key
+           ) VALUES ($1, $2, $3, $4, $5, 'active', $6, $7, $8, $9, $10, $11, $12)
+           RETURNING *`,
+          [
+            tenantId, agentId, scope, scopeKey, text,
+            basedOnFactIds, metadata, input.sourceSessionId || null,
+            profile.id, profile.version, profile.schemaHash,
+            idempotencyKey,
+          ],
+        );
+
+        if (supersededNarrativeId) {
+          await client.query(
+            `UPDATE ${schema}.narratives
+               SET superseded_by_narrative_id = $1
+             WHERE id = $2`,
+            [inserted.rows[0].id, supersededNarrativeId],
+          );
+        }
+
+        await client.query('COMMIT');
+        return ok({
+          narrative: mapRow(inserted.rows[0]),
+          supersededNarrativeId,
+        });
+      } 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 scope = input.scope || 'agent';
+      const scopeKey = input.scopeKey || input.agentId;
+      const { rows } = await pool.query(
+        `SELECT * FROM ${schema}.narratives
+          WHERE tenant_id = $1 AND agent_id = $2
+            AND scope = $3 AND scope_key = $4
+            AND status = 'active'
+          LIMIT 1`,
+        [tenantId, input.agentId, scope, scopeKey],
+      );
+      return ok({ narrative: mapRow(rows[0]) });
+    } catch (e) {
+      return err('AQ_INTERNAL', e.message, { cause: e });
+    }
+  }
+
+  async function listHistory(input = {}) {
+    try {
+      if (!input.agentId) {
+        return err('AQ_INVALID_INPUT', 'agentId is required');
+      }
+      const tenantId = input.tenantId || defaultTenantId || 'default';
+      const scope = input.scope || 'agent';
+      const scopeKey = input.scopeKey || input.agentId;
+      const limit = Math.min(Math.max(input.limit || 20, 1), 200);
+      const { rows } = await pool.query(
+        `SELECT * FROM ${schema}.narratives
+          WHERE tenant_id = $1 AND agent_id = $2
+            AND scope = $3 AND scope_key = $4
+          ORDER BY effective_at DESC, id DESC
+          LIMIT $5`,
+        [tenantId, input.agentId, scope, scopeKey, limit],
+      );
+      return ok({ rows: rows.map(mapRow) });
+    } catch (e) {
+      return err('AQ_INTERNAL', e.message, { cause: e });
+    }
+  }
+
+  return { upsertSnapshot, getLatest, listHistory };
+}
+
+module.exports = { createNarratives };

package/core/profiles.js

@@ -0,0 +1,171 @@
+'use strict';
+
+// aq.profiles.* — consumer profile registry (capability #4 schemaRegistry).
+//
+// Spec: aquifer-completion §4 schemaRegistry, §D2 (consumer_profiles DDL).
+// The P2-2b surface only covers register/load; diff + resolveForWrite +
+// compiled template/schema generation land in P3 alongside prompt template
+// engine and output parser work.
+//
+// register(): insert (tenant_id, consumer_id, version, profile_hash,
+//   profile_json). If the same (consumer_id, version) with a different
+//   profile_hash is submitted, the UNIQUE (consumer_id, version,
+//   profile_hash) constraint makes this a conflict, returning
+//   AQ_CONFLICT so callers must bump version rather than silently drift.
+//
+// load(): fetch latest non-deprecated version (or a specific version).
+
+const crypto = require('crypto');
+const { AqError, ok, err } = require('./errors');
+
+function toNumber(v) {
+  if (v === null || v === undefined) return null;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : null;
+}
+
+function canonicaliseJson(value) {
+  if (value === null || typeof value !== 'object') return value;
+  if (Array.isArray(value)) return value.map(canonicaliseJson);
+  const sorted = {};
+  for (const key of Object.keys(value).sort()) {
+    sorted[key] = canonicaliseJson(value[key]);
+  }
+  return sorted;
+}
+
+function computeProfileHash(profileJson) {
+  // Stable hash over deeply-canonicalised JSON so semantically identical
+  // profiles always produce the same hash regardless of key ordering.
+  const canonical = JSON.stringify(canonicaliseJson(profileJson));
+  return crypto.createHash('sha256').update(canonical).digest('hex');
+}
+
+function mapRow(row) {
+  if (!row) return null;
+  return {
+    tenantId: row.tenant_id,
+    consumerId: row.consumer_id,
+    version: toNumber(row.version),
+    profileHash: row.profile_hash,
+    profile: row.profile_json,
+    loadedAt: row.loaded_at,
+    deprecatedAt: row.deprecated_at,
+  };
+}
+
+function createProfiles({ pool, schema, defaultTenantId }) {
+  async function register(input) {
+    try {
+      if (!input || typeof input !== 'object') {
+        return err('AQ_INVALID_INPUT', 'register requires an input object');
+      }
+      if (!input.consumerId) return err('AQ_INVALID_INPUT', 'consumerId is required');
+      if (!Number.isInteger(input.version) || input.version < 1) {
+        return err('AQ_INVALID_INPUT', 'version must be a positive integer');
+      }
+      if (!input.profile || typeof input.profile !== 'object') {
+        return err('AQ_INVALID_INPUT', 'profile (object) is required');
+      }
+
+      const tenantId = input.tenantId || defaultTenantId || 'default';
+      const profileHash = input.profileHash || computeProfileHash(input.profile);
+
+      // Try insert; if (tenant, consumer, version) already exists with a
+      // different hash, map to AQ_CONFLICT — the caller must bump version.
+      try {
+        const { rows } = await pool.query(
+          `INSERT INTO ${schema}.consumer_profiles
+             (tenant_id, consumer_id, version, profile_hash, profile_json)
+           VALUES ($1, $2, $3, $4, $5)
+           ON CONFLICT (tenant_id, consumer_id, version) DO NOTHING
+           RETURNING *`,
+          [tenantId, input.consumerId, input.version, profileHash, input.profile],
+        );
+        if (rows.length > 0) {
+          return ok({
+            consumerProfileId: input.consumerId,
+            version: input.version,
+            schemaHash: profileHash,
+            inserted: true,
+          });
+        }
+      } catch (e) {
+        // UNIQUE (consumer_id, version, profile_hash) may still violate if
+        // same version registered with different hash under a different
+        // tenant — surface as conflict.
+        if (e.code === '23505') {
+          return err('AQ_CONFLICT', 'profile hash collision on (consumer_id, version)');
+        }
+        throw e;
+      }
+
+      // Row already exists — verify hash matches for idempotent replay.
+      const existing = await pool.query(
+        `SELECT profile_hash FROM ${schema}.consumer_profiles
+          WHERE tenant_id = $1 AND consumer_id = $2 AND version = $3`,
+        [tenantId, input.consumerId, input.version],
+      );
+      if (existing.rows[0].profile_hash !== profileHash) {
+        return err('AQ_CONFLICT',
+          `profile (${input.consumerId} v${input.version}) already registered with a different hash — bump version`);
+      }
+      return ok({
+        consumerProfileId: input.consumerId,
+        version: input.version,
+        schemaHash: profileHash,
+        inserted: false,
+      });
+    } catch (e) {
+      if (e instanceof AqError) return err(e);
+      return err('AQ_INTERNAL', e.message, { cause: e });
+    }
+  }
+
+  async function load(input = {}) {
+    try {
+      if (!input.consumerId) return err('AQ_INVALID_INPUT', 'consumerId is required');
+      const tenantId = input.tenantId || defaultTenantId || 'default';
+
+      let rows;
+      if (input.version === 'latest' || input.version === undefined || input.version === null) {
+        const result = await pool.query(
+          `SELECT * FROM ${schema}.consumer_profiles
+            WHERE tenant_id = $1 AND consumer_id = $2 AND deprecated_at IS NULL
+            ORDER BY version DESC
+            LIMIT 1`,
+          [tenantId, input.consumerId],
+        );
+        rows = result.rows;
+      } else if (Number.isInteger(input.version) && input.version >= 1) {
+        const result = await pool.query(
+          `SELECT * FROM ${schema}.consumer_profiles
+            WHERE tenant_id = $1 AND consumer_id = $2 AND version = $3`,
+          [tenantId, input.consumerId, input.version],
+        );
+        rows = result.rows;
+      } else {
+        return err('AQ_INVALID_INPUT', 'version must be a positive integer or "latest"');
+      }
+
+      if (rows.length === 0) {
+        return err('AQ_PROFILE_NOT_FOUND',
+          `no profile for consumer=${input.consumerId} version=${input.version || 'latest'}`);
+      }
+      const mapped = mapRow(rows[0]);
+      return ok({
+        profile: mapped.profile,
+        consumerProfileId: mapped.consumerId,
+        version: mapped.version,
+        schemaHash: mapped.profileHash,
+        loadedAt: mapped.loadedAt,
+      });
+    } catch (e) {
+      return err('AQ_INTERNAL', e.message, { cause: e });
+    }
+  }
+
+  return { register, load };
+}
+
+module.exports = { createProfiles };

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 };