@shadowforge0/aquifer-memory 1.2.1 → 1.3.0

package/README.md

@@ -333,18 +333,17 @@ Built-in entity extraction and relationship tracking:
 
 ## Benchmark: LongMemEval
 
-We tested Aquifer's retrieval pipeline on [LongMemEval_S](https://github.com/xiaowu0162/LongMemEval) — 470 questions across 19,195 sessions (98,845 turn embeddings).
+We tested Aquifer's retrieval pipeline on [LongMemEval_S](https://github.com/xiaowu0162/LongMemEval) — 470 questions across 19,195 sessions with 98,795 turn embeddings. Per-question haystack scoping (matching the official protocol), bge-m3 embeddings via OpenRouter.
 
-**Setup:** Per-question haystack scoping (matching official methodology), bge-m3 embeddings via OpenRouter, turn-level user-only embedding.
+| Pipeline | R@1 | R@3 | R@5 | R@10 |
+|----------|-----|-----|-----|------|
+| Turn-only (cosine) | 89.5% | 96.6% | 98.1% | 98.9% |
+| Three-way hybrid (FTS + session_emb + turn_emb → RRF) | 79.2% | 94.0% | 97.7% | 98.9% |
+| **Hybrid + Cohere Rerank v3.5 (top-30)** | **96.0%** | **98.5%** | **99.3%** | **99.8%** |
 
-| Metric | Aquifer (bge-m3) |
-|--------|-----------------|
-| R@1 | 89.6% |
-| R@3 | 96.6% |
-| R@5 | 98.1% |
-| R@10 | 98.9% |
+Measured 2026-04-19 on Aquifer 1.2.1.
 
-**Key finding:** Turn-level embedding is the main driver — going from session-level (R@1=26.8%) to turn-level (R@1=89.6%) is a 3x improvement.
+**Key findings.** Turn-level embedding alone beats session-level (26.8% → 89.5% R@1, a 3× improvement). Hybrid fusion adds robustness at R@3-R@10 but trades R@1 because FTS + session-level signals spread the top candidate across adjacent sessions. Re-ranking the hybrid top-30 with a cross-encoder (Cohere Rerank v3.5) wins back the top-1 precision and then some — +16.9pt R@1 over hybrid baseline, and 6.5pt above pure turn-level cosine. That's the production pipeline Aquifer ships by default when a reranker is configured.
 
 ### Multi-Tenant
 

package/consumers/cli.js

@@ -43,7 +43,7 @@ function parsePositiveInt(value, fallback) {
 function parseArgs(argv) {
   const args = { _: [], flags: {} };
   // Flags that take a value (not boolean)
-  const VALUE_FLAGS = new Set(['limit', 'agent-id', 'source', 'date-from', 'date-to', 'output', 'format', 'config', 'status', 'concurrency', 'entities', 'entity-mode', 'session-id', 'verdict', 'note', 'db', 'since', 'min-messages', 'lookback-days', 'max-chars']);
+  const VALUE_FLAGS = new Set(['limit', 'agent-id', 'source', 'date-from', 'date-to', 'output', 'format', 'config', 'status', 'concurrency', 'entities', 'entity-mode', 'session-id', 'verdict', 'note', 'db', 'since', 'min-messages', 'lookback-days', 'max-chars', 'out']);
   for (let i = 0; i < argv.length; i++) {
     if (argv[i] === '--') { args._.push(...argv.slice(i + 1)); break; }
     if (argv[i].startsWith('--')) {
@@ -360,6 +360,16 @@ Options:
     return;
   }
 
+  // mcp-contract: write canonical MCP tool manifest to disk. No Aquifer
+  // instance needed — manifest is static. Default path /tmp/aquifer-mcp-contract.json.
+  if (command === 'mcp-contract') {
+    const { writeMcpManifestFile } = require('../index');
+    const outPath = args.flags.out || '/tmp/aquifer-mcp-contract.json';
+    const written = writeMcpManifestFile(outPath);
+    console.log(`Wrote MCP manifest to ${written}`);
+    return;
+  }
+
   // All other commands need an Aquifer instance
   const configOverrides = {};
   if (args.flags.config) {

package/consumers/miranda/profile.json

@@ -0,0 +1,145 @@
+{
+  "$schema": "https://aquifer.dev/schema/consumer-profile.v1.json",
+  "consumer_profile_id": "miranda",
+  "version": 1,
+  "description": "Miranda persona consumer profile — canonical shape for session state, handoff, decision log, timeline categories, and default artifact producers. Reference implementation shipped inside Aquifer; production deployments may register additional versions with schema changes.",
+  "defaults": {
+    "tenant_id": "default",
+    "agent_id": "main",
+    "time_zone": "Asia/Taipei"
+  },
+  "schemas": {
+    "default.session_state.v1": {
+      "kind": "default",
+      "target": "sessionState",
+      "description": "What Miranda is currently focused on — goal + active threads + affect tag.",
+      "json_schema": {
+        "type": "object",
+        "additionalProperties": true,
+        "properties": {
+          "goal": { "type": ["string", "null"] },
+          "active_work": { "type": "array", "items": { "type": "string" } },
+          "blockers": { "type": "array", "items": { "type": "string" } },
+          "affect": {
+            "type": "object",
+            "additionalProperties": true,
+            "properties": {
+              "mood": { "type": ["string", "null"] },
+              "energy": { "enum": ["low", "medium", "high", null] },
+              "confidence": { "enum": ["low", "medium", "high", null] },
+              "notes": { "type": ["string", "null"] }
+            }
+          }
+        },
+        "required": ["goal", "active_work", "blockers", "affect"]
+      }
+    },
+    "default.session_handoff.v1": {
+      "kind": "default",
+      "target": "sessionHandoff",
+      "description": "Session-end baton: what was the last step, where to pick up, what still blocks.",
+      "json_schema": {
+        "type": "object",
+        "additionalProperties": true,
+        "properties": {
+          "last_step": { "type": "string" },
+          "status": { "enum": ["in_progress", "completed", "blocked"] },
+          "next": { "type": ["string", "null"] },
+          "blockers": { "type": "array", "items": { "type": "string" } },
+          "decided": { "type": "array", "items": { "type": "string" } },
+          "open_loops": { "type": "array", "items": { "type": "string" } }
+        },
+        "required": ["last_step", "status", "next", "blockers", "decided", "open_loops"]
+      }
+    },
+    "default.decision_log.v1": {
+      "kind": "default",
+      "target": "decisionLog",
+      "description": "Committed / proposed / reversed decisions with optional fact linkage.",
+      "json_schema": {
+        "type": "object",
+        "additionalProperties": true,
+        "properties": {
+          "decision": { "type": "string" },
+          "reason": { "type": ["string", "null"] },
+          "status": { "enum": ["proposed", "committed", "reversed"] },
+          "related_fact_ids": {
+            "type": "array",
+            "items": { "type": "integer" }
+          }
+        },
+        "required": ["decision", "reason", "status"]
+      }
+    },
+    "default.timeline.v1": {
+      "kind": "default",
+      "target": "timeline",
+      "description": "Miranda daily timeline category vocabulary. Categories map to existing daily-log sections (focus/todo/mood/handoff) plus organisational tags Miranda uses in weekly/monthly rollups.",
+      "category_vocabulary": [
+        "cli",
+        "focus",
+        "todo",
+        "handoff",
+        "narrative",
+        "organized",
+        "weekly",
+        "monthly",
+        "stats",
+        "health",
+        "garmin",
+        "note"
+      ],
+      "json_schema": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "occurred_at": { "type": "string", "format": "date-time" },
+          "source": { "type": "string" },
+          "session_ref": { "type": ["string", "null"] },
+          "category": { "type": "string" },
+          "text": { "type": "string" },
+          "metadata": { "type": "object" }
+        },
+        "required": ["occurred_at", "source", "session_ref", "category", "text", "metadata"]
+      }
+    }
+  },
+  "artifacts": {
+    "producers": [
+      {
+        "producer_id": "miranda.workspace.daily-log",
+        "type": "daily-log",
+        "trigger_phase": "timeline_write",
+        "format": "markdown",
+        "destination": "workspace://memory/{date}.md",
+        "description": "Renders the day's timeline events + state snapshot + handoff to a single markdown file under the Miranda workspace. Source of truth remains the DB; the .md is a rendered view."
+      },
+      {
+        "producer_id": "miranda.workspace.weekly-log",
+        "type": "weekly-log",
+        "trigger_phase": "artifact_dispatch",
+        "format": "markdown",
+        "destination": "workspace://memory/weekly/{week_start}.md",
+        "description": "Weekly rollup. Timeline events tagged [WEEKLY] plus cross-session narratives. Rendered from DB via rollupWeekly() helper."
+      },
+      {
+        "producer_id": "miranda.workspace.monthly-log",
+        "type": "monthly-log",
+        "trigger_phase": "artifact_dispatch",
+        "format": "markdown",
+        "destination": "workspace://memory/monthly/{month}.md",
+        "description": "Monthly rollup. Aggregates weekly entries + narrative supersede chain."
+      }
+    ]
+  },
+  "extraction_hints": {
+    "entities": {
+      "include_types": ["person", "project", "tool", "topic"],
+      "exclude_patterns": ["^/tmp/", "^/home/mingko/\\.", "^node_modules/"]
+    },
+    "facts": {
+      "prefer_subjects": ["MK", "Miranda", "Aquifer", "OpenClaw", "Jenny", "Evan", "Ivan"],
+      "avoid_ephemeral": true
+    }
+  }
+}

package/consumers/miranda/render-daily-md.js

@@ -0,0 +1,186 @@
+'use strict';
+
+// Miranda daily log renderer — reference implementation for the artifact
+// capability (spec §12).
+//
+// Pulls the canonical state for a date from Aquifer (timeline events + latest
+// state + active narrative + latest handoff) and renders it into a single
+// markdown file. Pure logic — does not write to disk; returns the rendered
+// string plus an artifact record declaration the caller can persist via
+// aq.artifacts.record().
+//
+// Shape deliberately mirrors the historical Miranda daily-log format so the
+// downstream consumers (CC, Discord pushes, weekly rollup) see no regression
+// during the cutover from render-daily-log.js to this reference impl.
+
+const crypto = require('crypto');
+
+function startOfDayIso(dateStr) {
+  return `${dateStr}T00:00:00Z`;
+}
+
+function endOfDayIso(dateStr) {
+  return `${dateStr}T23:59:59.999Z`;
+}
+
+function ensureDate(input) {
+  if (!input) throw new Error('date (YYYY-MM-DD) is required');
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(input)) {
+    throw new Error(`date must match YYYY-MM-DD, got: ${input}`);
+  }
+  return input;
+}
+
+function renderSection(title, lines) {
+  if (!lines || lines.length === 0) return null;
+  return `## ${title}\n\n${lines.join('\n')}\n`;
+}
+
+function formatTimelineLine(evt) {
+  const ts = new Date(evt.occurredAt).toISOString().slice(11, 16);
+  const src = evt.sessionRef ? ` (${evt.sessionRef})` : '';
+  return `- \`${ts}\`${src} ${evt.text}`;
+}
+
+function formatHandoff(payload) {
+  if (!payload) return null;
+  const lines = [];
+  if (payload.last_step) lines.push(`**Last step.** ${payload.last_step}`);
+  if (payload.status) lines.push(`**Status.** ${payload.status}`);
+  if (payload.next) lines.push(`**Next.** ${payload.next}`);
+  if (Array.isArray(payload.blockers) && payload.blockers.length > 0) {
+    lines.push(`**Blockers.**`);
+    for (const b of payload.blockers) lines.push(`- ${b}`);
+  }
+  if (Array.isArray(payload.open_loops) && payload.open_loops.length > 0) {
+    lines.push(`**Open loops.**`);
+    for (const l of payload.open_loops) lines.push(`- ${l}`);
+  }
+  return lines.length > 0 ? lines.join('\n') + '\n' : null;
+}
+
+function formatState(state) {
+  if (!state) return null;
+  const lines = [];
+  if (state.goal) lines.push(`**Goal.** ${state.goal}`);
+  if (Array.isArray(state.active_work) && state.active_work.length > 0) {
+    lines.push(`**Active work.**`);
+    for (const w of state.active_work) lines.push(`- ${w}`);
+  }
+  if (state.affect && typeof state.affect === 'object') {
+    const bits = [];
+    if (state.affect.mood) bits.push(`mood: ${state.affect.mood}`);
+    if (state.affect.energy) bits.push(`energy: ${state.affect.energy}`);
+    if (state.affect.confidence) bits.push(`confidence: ${state.affect.confidence}`);
+    if (bits.length > 0) lines.push(`**Affect.** ${bits.join(', ')}`);
+  }
+  return lines.length > 0 ? lines.join('\n') + '\n' : null;
+}
+
+// -------------------------------------------------------------------------
+// Public entry
+// -------------------------------------------------------------------------
+//
+// renderDailyMd({ aquifer, date, agentId, tenantId?, categories? }) returns:
+//   {
+//     markdown: string,
+//     artifact: { producerId, type, format, destination, payload,
+//                 idempotencyKey }  // ready for aq.artifacts.record()
+//   }
+//
+// The caller decides whether to persist the artifact record and where the
+// rendered file lands. Aquifer itself doesn't touch disk.
+
+async function renderDailyMd({
+  aquifer, date, agentId, tenantId, categories,
+  destinationTemplate = 'workspace://memory/{date}.md',
+  producerId = 'miranda.workspace.daily-log',
+}) {
+  if (!aquifer) throw new Error('aquifer instance is required');
+  if (!agentId) throw new Error('agentId is required');
+  const day = ensureDate(date);
+
+  const since = startOfDayIso(day);
+  const until = endOfDayIso(day);
+
+  const timelineResult = await aquifer.timeline.list({
+    tenantId, agentId, categories, since, until, limit: 500,
+  });
+  if (!timelineResult.ok) throw new Error(`timeline.list failed: ${timelineResult.error.message}`);
+
+  const stateResult = await aquifer.state.getLatest({ tenantId, agentId });
+  if (!stateResult.ok) throw new Error(`state.getLatest failed: ${stateResult.error.message}`);
+
+  const handoffResult = await aquifer.handoff.getLatest({ tenantId, agentId });
+  if (!handoffResult.ok) throw new Error(`handoff.getLatest failed: ${handoffResult.error.message}`);
+
+  const narrativeResult = await aquifer.narratives.getLatest({ tenantId, agentId });
+  if (!narrativeResult.ok) throw new Error(`narratives.getLatest failed: ${narrativeResult.error.message}`);
+
+  const events = (timelineResult.data.rows || []).slice().sort((a, b) =>
+    new Date(a.occurredAt).getTime() - new Date(b.occurredAt).getTime());
+
+  // Group timeline by category.
+  const grouped = new Map();
+  for (const evt of events) {
+    if (!grouped.has(evt.category)) grouped.set(evt.category, []);
+    grouped.get(evt.category).push(evt);
+  }
+
+  const sections = [];
+  sections.push(`# ${day}\n`);
+  const stateBlock = formatState(stateResult.data.state);
+  if (stateBlock) sections.push(`## State\n\n${stateBlock}`);
+
+  if (narrativeResult.data.narrative) {
+    sections.push(`## Narrative\n\n${narrativeResult.data.narrative.text}\n`);
+  }
+
+  const categoryOrder = ['focus', 'todo', 'mood', 'handoff', 'narrative',
+    'organized', 'note', 'stats', 'health', 'garmin', 'weekly', 'monthly', 'cli'];
+  const emitted = new Set();
+  for (const cat of categoryOrder) {
+    if (!grouped.has(cat)) continue;
+    const lines = grouped.get(cat).map(formatTimelineLine);
+    const sec = renderSection(cat.charAt(0).toUpperCase() + cat.slice(1), lines);
+    if (sec) sections.push(sec);
+    emitted.add(cat);
+  }
+  for (const [cat, evts] of grouped) {
+    if (emitted.has(cat)) continue;
+    const lines = evts.map(formatTimelineLine);
+    const sec = renderSection(cat, lines);
+    if (sec) sections.push(sec);
+  }
+
+  const handoffBlock = formatHandoff(handoffResult.data.handoff);
+  if (handoffBlock) sections.push(`## Handoff\n\n${handoffBlock}`);
+
+  const markdown = sections.join('\n').replace(/\n{3,}/g, '\n\n').trim() + '\n';
+
+  const destination = destinationTemplate.replace('{date}', day);
+  const idempotencyKey = crypto.createHash('sha256')
+    .update(`miranda:daily:${tenantId || 'default'}:${agentId}:${day}`)
+    .digest('hex');
+
+  return {
+    markdown,
+    artifact: {
+      producerId,
+      type: 'daily-log',
+      format: 'markdown',
+      destination,
+      triggerPhase: 'artifact_dispatch',
+      payload: {
+        date: day,
+        event_count: events.length,
+        has_state: !!stateResult.data.state,
+        has_handoff: !!handoffResult.data.handoff,
+        has_narrative: !!narrativeResult.data.narrative,
+      },
+      idempotencyKey,
+    },
+  };
+}
+
+module.exports = { renderDailyMd };

package/core/aquifer.js

@@ -270,6 +270,12 @@ function createAquifer(config = {}) {
           await pool.query(factsSql);
         }
 
+        // 5. Completion foundation (always, additive): narratives,
+        // consumer_profiles, sessions.consolidation_phases. Pure additive DDL
+        // with IF NOT EXISTS guards — safe on every migrate() call.
+        const completionSql = loadSql('004-completion.sql', schema);
+        await pool.query(completionSql);
+
         migrated = true;
       } finally {
         await pool.query('SELECT pg_advisory_unlock($1)', [lockKey]).catch((err) => {
@@ -1233,6 +1239,29 @@ function createAquifer(config = {}) {
     },
   };
 
+  // Completion-capability surfaces (P2). All methods return AqResult envelope;
+  // DDL materialised in schema/004-completion.sql (migrated unconditionally,
+  // additive only). See core/errors.js for envelope shape.
+  const { createNarratives } = require('./narratives');
+  const { createTimeline } = require('./timeline');
+  const { createState } = require('./state');
+  const { createHandoff } = require('./handoff');
+  const { createProfiles } = require('./profiles');
+  const { createDecisions } = require('./decisions');
+  const { createArtifacts } = require('./artifacts');
+  const { createConsolidation } = require('./consolidation');
+  const { createBundles } = require('./bundles');
+  const qSchema = qi(schema);
+  aquifer.narratives = createNarratives({ pool, schema: qSchema, defaultTenantId: tenantId });
+  aquifer.timeline = createTimeline({ pool, schema: qSchema, defaultTenantId: tenantId });
+  aquifer.state = createState({ pool, schema: qSchema, defaultTenantId: tenantId });
+  aquifer.handoff = createHandoff({ pool, schema: qSchema, defaultTenantId: tenantId });
+  aquifer.profiles = createProfiles({ pool, schema: qSchema, defaultTenantId: tenantId });
+  aquifer.decisions = createDecisions({ pool, schema: qSchema, defaultTenantId: tenantId });
+  aquifer.artifacts = createArtifacts({ pool, schema: qSchema, defaultTenantId: tenantId });
+  aquifer.consolidation = createConsolidation({ pool, schema: qSchema, defaultTenantId: tenantId });
+  aquifer.bundles = createBundles({ pool, schema: qSchema, defaultTenantId: tenantId });
+
   return aquifer;
 }
 

package/core/artifacts.js

@@ -0,0 +1,174 @@
+'use strict';
+
+// aq.artifacts.* — producer-declared output record capability.
+//
+// Spec: aquifer-completion §12 artifact. Aquifer stores the declaration +
+// lifecycle status but never interprets the payload. Producers own shape.
+// Typical flow: record with status='pending', produce content externally,
+// then upsert same idempotency_key with status='produced' + contentRef.
+
+const crypto = require('crypto');
+const { AqError, ok, err } = require('./errors');
+
+const DEFAULT_PROFILE = Object.freeze({
+  id: 'anon',
+  version: 0,
+  schemaHash: 'pending',
+});
+
+const VALID_STATUSES = new Set(['pending', 'produced', 'failed', 'discarded']);
+
+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, producerId, sessionId, artifactType, destination }) {
+  return crypto.createHash('sha256')
+    .update(`${tenantId}:${producerId}:${sessionId || ''}:${artifactType}:${destination}`)
+    .digest('hex');
+}
+
+function mapRow(row) {
+  if (!row) return null;
+  return {
+    artifactId: toNumber(row.id),
+    agentId: row.agent_id,
+    sessionId: row.source_session_id,
+    producerId: row.producer_id,
+    type: row.artifact_type,
+    triggerPhase: row.trigger_phase,
+    format: row.format,
+    destination: row.destination,
+    status: row.status,
+    contentRef: row.content_ref,
+    payload: row.payload || {},
+    metadata: row.metadata || {},
+    producedAt: row.produced_at,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+function createArtifacts({ pool, schema, defaultTenantId }) {
+  async function record(input) {
+    try {
+      if (!input || typeof input !== 'object') {
+        return err('AQ_INVALID_INPUT', 'record requires an input object');
+      }
+      if (!input.agentId) return err('AQ_INVALID_INPUT', 'agentId is required');
+      if (!input.producerId) return err('AQ_INVALID_INPUT', 'producerId is required');
+      if (!input.type) return err('AQ_INVALID_INPUT', 'type is required');
+      if (!input.format) return err('AQ_INVALID_INPUT', 'format is required');
+      if (!input.destination) return err('AQ_INVALID_INPUT', 'destination is required');
+
+      const status = input.status || 'pending';
+      if (!VALID_STATUSES.has(status)) {
+        return err('AQ_INVALID_INPUT',
+          `status must be one of ${Array.from(VALID_STATUSES).join(', ')}`);
+      }
+
+      const tenantId = input.tenantId || defaultTenantId || 'default';
+      const profile = resolveProfile(input.profile);
+      const idempotencyKey = input.idempotencyKey
+        || defaultIdempotencyKey({
+          tenantId,
+          producerId: input.producerId,
+          sessionId: input.sessionId,
+          artifactType: input.type,
+          destination: input.destination,
+        });
+
+      // Upsert semantics: producer may re-record the same artifact with
+      // updated status ('pending' → 'produced'), so DO UPDATE on matching
+      // idempotency_key, allowing lifecycle transitions.
+      const { rows } = await pool.query(
+        `INSERT INTO ${schema}.artifacts (
+           tenant_id, agent_id, source_session_id,
+           consumer_profile_id, consumer_profile_version, consumer_schema_hash,
+           idempotency_key, producer_id, artifact_type, trigger_phase,
+           format, destination, status, content_ref, payload, metadata,
+           produced_at
+         ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16,
+                   CASE WHEN $13 = 'produced' THEN COALESCE($17::timestamptz, now()) ELSE $17::timestamptz END)
+         ON CONFLICT (idempotency_key) DO UPDATE SET
+           status = EXCLUDED.status,
+           content_ref = COALESCE(EXCLUDED.content_ref, ${schema}.artifacts.content_ref),
+           payload = EXCLUDED.payload,
+           metadata = EXCLUDED.metadata,
+           produced_at = CASE
+             WHEN EXCLUDED.status = 'produced' AND ${schema}.artifacts.produced_at IS NULL
+               THEN now()
+             ELSE ${schema}.artifacts.produced_at
+           END
+         RETURNING *`,
+        [
+          tenantId, input.agentId, input.sessionId || null,
+          profile.id, profile.version, profile.schemaHash,
+          idempotencyKey, input.producerId, input.type,
+          input.triggerPhase || null, input.format, input.destination,
+          status, input.contentRef || null,
+          JSON.stringify(input.payload || {}),
+          JSON.stringify(input.metadata || {}),
+          input.producedAt || null,
+        ],
+      );
+      const mapped = mapRow(rows[0]);
+      return ok({ artifactId: mapped.artifactId });
+    } catch (e) {
+      if (e instanceof AqError) return err(e);
+      return err('AQ_INTERNAL', e.message, { cause: e });
+    }
+  }
+
+  async function list(input = {}) {
+    try {
+      const tenantId = input.tenantId || defaultTenantId || 'default';
+      const limit = Math.min(Math.max(input.limit || 50, 1), 500);
+      const params = [tenantId];
+      let where = 'tenant_id = $1';
+      if (input.agentId) {
+        params.push(input.agentId);
+        where += ` AND agent_id = $${params.length}`;
+      }
+      if (input.sessionId) {
+        params.push(input.sessionId);
+        where += ` AND source_session_id = $${params.length}`;
+      }
+      if (input.producerId) {
+        params.push(input.producerId);
+        where += ` AND producer_id = $${params.length}`;
+      }
+      if (Array.isArray(input.statuses) && input.statuses.length > 0) {
+        params.push(input.statuses);
+        where += ` AND status = ANY($${params.length})`;
+      }
+      params.push(limit);
+
+      const { rows } = await pool.query(
+        `SELECT * FROM ${schema}.artifacts
+          WHERE ${where}
+          ORDER BY created_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 { record, list };
+}
+
+module.exports = { createArtifacts };