@retinue/agentkit 0.1.0

package/dist/adapters/postgres/artifacts.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Postgres `ArtifactStore` (#133).
+ *
+ * Two properties are in the SQL rather than above it, for the reason every other adapter here puts them
+ * there: a check the caller performs is a check a second caller can skip.
+ *
+ * - **`addVersion` is a compare-and-set in the statement** — `WHERE latest_version = $expected` — so two
+ *   concurrent regenerations cannot both become version 2. The `UNIQUE (tenant_id, artifact_id, version)`
+ *   constraint says the same thing a second time, at the level where the application cannot be wrong about it.
+ * - **Content is a reference and there is no column it could be inlined into.** AC-5 is enforced by the
+ *   schema's shape, not by a rule someone follows.
+ */
+import type { ArtifactStore } from "../../persistence/index.js";
+import type { SqlExecutor } from "./sql.js";
+export declare const createPostgresArtifactStore: (sql: SqlExecutor) => ArtifactStore;
+//# sourceMappingURL=artifacts.d.ts.map

package/dist/adapters/postgres/artifacts.js

@@ -0,0 +1,172 @@
+/**
+ * Postgres `ArtifactStore` (#133).
+ *
+ * Two properties are in the SQL rather than above it, for the reason every other adapter here puts them
+ * there: a check the caller performs is a check a second caller can skip.
+ *
+ * - **`addVersion` is a compare-and-set in the statement** — `WHERE latest_version = $expected` — so two
+ *   concurrent regenerations cannot both become version 2. The `UNIQUE (tenant_id, artifact_id, version)`
+ *   constraint says the same thing a second time, at the level where the application cannot be wrong about it.
+ * - **Content is a reference and there is no column it could be inlined into.** AC-5 is enforced by the
+ *   schema's shape, not by a rule someone follows.
+ */
+import { AgentPlatformError } from "../../core/errors.js";
+import { asId } from "../../core/ids.js";
+const iso = (v) => (v instanceof Date ? v.toISOString() : v);
+const toArtifact = (r) => ({
+    id: asId(r.id),
+    conversationId: asId(r.conversation_id),
+    kind: r.kind,
+    name: r.name,
+    latestVersion: Number(r.latest_version),
+    createdAt: iso(r.created_at),
+    updatedAt: iso(r.updated_at),
+    ...(r.deleted_at === null ? {} : { deletedAt: iso(r.deleted_at) }),
+});
+const toVersion = (r) => ({
+    id: asId(r.id),
+    artifactId: asId(r.artifact_id),
+    version: Number(r.version),
+    contentRef: asId(r.content_ref),
+    // `bigint` comes back as a string from node-postgres, correct past 2^53 and wrong for arithmetic. An
+    // artifact's size is well inside the safe range, so it is narrowed here rather than left for a caller to
+    // remember.
+    byteSize: Number(r.byte_size),
+    ...(r.checksum === null ? {} : { checksum: r.checksum }),
+    // `jsonb` comes back parsed from node-postgres and as a string from some drivers, so both are handled —
+    // a store that assumed one would work in tests and fail on the other.
+    provenance: (typeof r.provenance === "string"
+        ? JSON.parse(r.provenance)
+        : r.provenance),
+    createdBy: asId(r.created_by),
+    createdAt: iso(r.created_at),
+});
+const ARTIFACT_COLUMNS = `id, conversation_id, kind, name, latest_version, created_at, updated_at, deleted_at`;
+const VERSION_COLUMNS = `id, artifact_id, version, content_ref, byte_size, checksum, provenance,
+                          created_by, created_at`;
+const encodeCursor = (createdAt, id) => Buffer.from(`${createdAt} ${id}`, "utf8").toString("base64url");
+const decodeCursor = (cursor) => {
+    const [createdAt, id] = Buffer.from(cursor, "base64url").toString("utf8").split(" ");
+    return createdAt === undefined || id === undefined ? null : { createdAt, id };
+};
+export const createPostgresArtifactStore = (sql) => ({
+    async create({ tenantId, artifact, version }) {
+        const rows = await sql.query(`INSERT INTO artifacts (tenant_id, id, conversation_id, kind, name, latest_version,
+                              created_at, updated_at, deleted_at)
+       VALUES ($1,$2,$3,$4,$5,1,$6,$6,NULL)
+       -- Nothing updated on conflict: a duplicate id is a caller bug, and overwriting would repoint a name
+       -- at different content while leaving the old versions attached to it.
+       ON CONFLICT (tenant_id, id) DO NOTHING
+       RETURNING ${ARTIFACT_COLUMNS}`, [tenantId, artifact.id, artifact.conversationId, artifact.kind, artifact.name, artifact.createdAt]);
+        const created = rows[0];
+        if (created === undefined)
+            throw new AgentPlatformError({
+                code: "conflict",
+                message: `artifact ${artifact.id} already exists`,
+                retryable: false,
+            });
+        // Version 1 in the same call. An artifact with no version is not something a reader can resolve, so the
+        // state is never observable -- and the FK means this insert cannot precede the row above.
+        await sql.query(`INSERT INTO artifact_versions (tenant_id, id, artifact_id, version, content_ref, byte_size,
+                                      checksum, provenance, created_by, created_at)
+       VALUES ($1,$2,$3,1,$4,$5,$6,$7::jsonb,$8,$9)`, [
+            tenantId,
+            version.id,
+            artifact.id,
+            version.contentRef,
+            version.byteSize,
+            version.checksum ?? null,
+            JSON.stringify(version.provenance),
+            version.createdBy,
+            version.createdAt,
+        ]);
+        return toArtifact(created);
+    },
+    async addVersion({ tenantId, id, expectedLatestVersion, version }) {
+        const bumped = await sql.query(`UPDATE artifacts
+          SET latest_version = latest_version + 1, updated_at = $4::timestamptz
+        WHERE tenant_id = $1 AND id = $2
+          -- The compare, in the statement. Two concurrent regenerations both hold expectedLatestVersion = 1;
+          -- exactly one UPDATE matches, and the loser is told so rather than overwriting the winner.
+          AND latest_version = $3
+          -- A deleted artifact gains no versions: a new version would resurrect it in every listing that
+          -- filters on deleted_at through the artifact row.
+          AND deleted_at IS NULL
+        RETURNING latest_version`, [tenantId, id, expectedLatestVersion, version.createdAt]);
+        const next = bumped[0];
+        if (next === undefined)
+            return { added: false };
+        const nextVersion = Number(next.latest_version);
+        await sql.query(`INSERT INTO artifact_versions (tenant_id, id, artifact_id, version, content_ref, byte_size,
+                                      checksum, provenance, created_by, created_at)
+       VALUES ($1,$2,$3,$4,$5,$6,$7,$8::jsonb,$9,$10)`, [
+            tenantId,
+            version.id,
+            id,
+            nextVersion,
+            version.contentRef,
+            version.byteSize,
+            version.checksum ?? null,
+            JSON.stringify(version.provenance),
+            version.createdBy,
+            version.createdAt,
+        ]);
+        return { added: true, version: nextVersion };
+    },
+    async get({ tenantId, id }) {
+        const rows = await sql.query(`SELECT ${ARTIFACT_COLUMNS} FROM artifacts WHERE tenant_id = $1 AND id = $2`, [tenantId, id]);
+        // A foreign id yields no row, so it is null without a comparison anyone could get wrong.
+        return rows[0] === undefined ? null : toArtifact(rows[0]);
+    },
+    async getVersion({ tenantId, id, version }) {
+        const rows = await sql.query(`SELECT ${VERSION_COLUMNS} FROM artifact_versions
+        WHERE tenant_id = $1 AND artifact_id = $2
+          -- The latest when none is asked for. Ordering and LIMIT rather than a join on latest_version, so
+          -- this answers correctly even if the denormalised counter were ever wrong.
+          AND ($3::integer IS NULL OR version = $3::integer)
+        ORDER BY version DESC
+        LIMIT 1`, [tenantId, id, version ?? null]);
+        return rows[0] === undefined ? null : toVersion(rows[0]);
+    },
+    async listByConversation({ tenantId, conversationId, limit, cursor }) {
+        const after = cursor === undefined ? null : decodeCursor(cursor);
+        const rows = await sql.query(`SELECT ${ARTIFACT_COLUMNS} FROM artifacts
+        WHERE tenant_id = $1 AND conversation_id = $2
+          -- Live only: a deleted artifact reappearing here is a deleted document coming back.
+          AND deleted_at IS NULL
+          AND ($3::text IS NULL OR (created_at, id) > ($3::timestamptz, $4::text))
+        ORDER BY created_at, id
+        LIMIT $5`, [tenantId, conversationId, after?.createdAt ?? null, after?.id ?? null, limit + 1]);
+        const items = rows.slice(0, limit).map(toArtifact);
+        const last = items[items.length - 1];
+        return rows.length > limit && last !== undefined
+            ? { items, nextCursor: encodeCursor(last.createdAt, last.id) }
+            : { items };
+    },
+    async listVersions({ tenantId, id, limit, cursor }) {
+        // Paged on the version number: it is 1-based and contiguous, so it is an exact cursor, and two versions
+        // created in the same millisecond would tie under a timestamp keyset -- which for a history is the one
+        // place order must not be approximate.
+        const after = cursor === undefined ? 0 : Number.parseInt(cursor, 10);
+        const from = Number.isSafeInteger(after) && after > 0 ? after : 0;
+        const rows = await sql.query(`SELECT ${VERSION_COLUMNS} FROM artifact_versions
+        WHERE tenant_id = $1 AND artifact_id = $2 AND version > $3
+        ORDER BY version
+        LIMIT $4`, [tenantId, id, from, limit + 1]);
+        const items = rows.slice(0, limit).map(toVersion);
+        const last = items[items.length - 1];
+        return rows.length > limit && last !== undefined
+            ? { items, nextCursor: String(last.version) }
+            : { items };
+    },
+    async softDelete({ tenantId, id, at }) {
+        const rows = await sql.query(`UPDATE artifacts
+          -- COALESCE, so a retried delete keeps the first timestamp: the answer to "when was this deleted"
+          -- must not move every time someone clicks again.
+          SET deleted_at = COALESCE(deleted_at, $3::timestamptz), updated_at = $3::timestamptz
+        WHERE tenant_id = $1 AND id = $2
+        RETURNING id`, [tenantId, id, at]);
+        return { deleted: rows.length > 0 };
+    },
+});
+//# sourceMappingURL=artifacts.js.map

package/dist/adapters/postgres/checkpoint-store.d.ts

@@ -0,0 +1,16 @@
+/**
+ * PostgreSQL `CheckpointStore` (#95). The durable resume point: a recovered worker reloads the
+ * latest checkpoint, finalises any tool calls that were mid-flight, and continues from there.
+ *
+ * The monotonic guarantee lives in the statement, not in the caller. `save` is a single upsert whose
+ * `DO UPDATE` carries `WHERE excluded.sequence >= checkpoints.sequence`, so a late write from a
+ * worker whose lease was already reaped cannot rewind the run. Read-then-write could not hold that
+ * across two processes — and "two workers, one run, briefly overlapping" is exactly what lease
+ * expiry produces.
+ */
+import type { RunId, TenantId } from "../../core/ids.js";
+import type { CheckpointStore } from "../../persistence/index.js";
+import type { SqlExecutor } from "./sql.js";
+export declare const createPostgresCheckpointStore: (sql: SqlExecutor) => CheckpointStore;
+export type { RunId, TenantId };
+//# sourceMappingURL=checkpoint-store.d.ts.map

package/dist/adapters/postgres/checkpoint-store.js

@@ -0,0 +1,34 @@
+/**
+ * The whole checkpoint round-trips through `state`; `sequence` and `step` are lifted into columns for
+ * the monotonic guard and the non-negative constraint. Reading from `state` rather than reassembling
+ * from columns keeps one source of truth, so a column and the payload cannot disagree.
+ */
+const toCheckpoint = (row) => (typeof row.state === "string" ? JSON.parse(row.state) : row.state);
+export const createPostgresCheckpointStore = (sql) => ({
+    async latest({ tenantId, runId }) {
+        const rows = await sql.query(`SELECT state FROM checkpoints WHERE tenant_id = $1 AND run_id = $2`, [tenantId, runId]);
+        const row = rows[0];
+        return row ? toCheckpoint(row) : null;
+    },
+    async save({ tenantId, checkpoint }) {
+        await sql.query(`INSERT INTO checkpoints (tenant_id, run_id, sequence, step, state, updated_at)
+       VALUES ($1, $2, $3, $4, $5::jsonb, $6::timestamptz)
+       ON CONFLICT (tenant_id, run_id) DO UPDATE
+          SET sequence   = excluded.sequence,
+              step       = excluded.step,
+              state      = excluded.state,
+              updated_at = excluded.updated_at
+        -- Monotonic: a save at a lower sequence is ignored, so a reaped worker's late write cannot
+        -- rewind a run that a newer claim has already advanced. Greater-or-equal rather than
+        -- strictly-greater, so an equal sequence is an idempotent refresh, not a rejected write.
+        WHERE excluded.sequence >= checkpoints.sequence`, [
+            tenantId,
+            checkpoint.runId,
+            checkpoint.sequence,
+            checkpoint.step,
+            JSON.stringify(checkpoint),
+            checkpoint.updatedAt,
+        ]);
+    },
+});
+//# sourceMappingURL=checkpoint-store.js.map

package/dist/adapters/postgres/config.d.ts

@@ -0,0 +1,15 @@
+import { type EgressPolicy } from "../../mcp/egress.js";
+import type { McpConnectionStore } from "../../mcp/provider.js";
+import type { SkillStore } from "../../persistence/index.js";
+import type { SkillVersion } from "../../skills/index.js";
+import type { SqlExecutor } from "./sql.js";
+export declare const createPostgresSkillStore: (sql: SqlExecutor) => SkillStore & {
+    add(tenantId: string, skill: SkillVersion): Promise<void>;
+};
+/**
+ * The egress policy is a constructor parameter, not a column — it is a deployment-level rule rather
+ * than per-connection data, which is why the SPEC's `egress_policy jsonb` had nothing to populate it.
+ * What survives a restart is the connection; the policy comes from whatever store is built at boot.
+ */
+export declare const createPostgresMcpConnectionStore: (sql: SqlExecutor, egress: EgressPolicy) => McpConnectionStore;
+//# sourceMappingURL=config.d.ts.map

package/dist/adapters/postgres/config.js

@@ -0,0 +1,187 @@
+/**
+ * PostgreSQL `SkillStore` and `McpConnectionStore` (#101) — tenant configuration.
+ *
+ * Two things worth stating up front, because both are places the SPEC and the code disagree.
+ *
+ * **`listCatalog` returns the latest *active* version per name.** That is what the reference adapter
+ * does, and the SPEC says nothing about it. The consequence is deliberate: a draft or archived
+ * version is invisible to discovery while remaining resolvable by `findVersion`, so a run pinned to
+ * an archived version keeps working and no new run picks it up.
+ *
+ * **A credential is a reference and nothing else.** `McpAuth` has no field capable of holding a
+ * secret value, and this table has no column that could either. That is the whole guarantee — and it
+ * is stronger than the pattern-matching constraint the SPEC proposed, which could not distinguish a
+ * reference from a secret in the general case.
+ */
+import { AgentPlatformError } from "../../core/errors.js";
+import { validateEndpoint } from "../../mcp/egress.js";
+import { validateSkillInput } from "../../skills/resolver.js";
+const iso = (v) => (v instanceof Date ? v.toISOString() : new Date(v).toISOString());
+const toSkill = (r) => ({
+    id: r.id,
+    name: r.name,
+    description: r.description,
+    source: r.source,
+    version: Number(r.version),
+    instructions: r.instructions,
+    status: r.status,
+    tenantId: r.tenant_id,
+    createdAt: iso(r.created_at),
+    ...(r.created_by === null ? {} : { createdBy: r.created_by }),
+});
+const SKILL_COLUMNS = `tenant_id, id, name, description, source, version, instructions, status,
+         created_at, created_by`;
+export const createPostgresSkillStore = (sql) => ({
+    /**
+     * Validated before the write, with the same function the reference adapter uses, so the two agree
+     * on what is storable rather than only on the happy path. The schema repeats the same bounds as
+     * CHECK constraints for the path that bypasses this method entirely.
+     */
+    async add(tenantId, skill) {
+        validateSkillInput(skill);
+        await sql.query(`INSERT INTO skills
+         (tenant_id, id, name, description, source, version, instructions, status, created_at, created_by)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9::timestamptz, $10)
+       ON CONFLICT (tenant_id, name, version) DO UPDATE
+          SET id = excluded.id,
+              description = excluded.description,
+              source = excluded.source,
+              instructions = excluded.instructions,
+              status = excluded.status,
+              created_at = excluded.created_at,
+              created_by = excluded.created_by`, [
+            tenantId,
+            skill.id,
+            skill.name,
+            skill.description,
+            skill.source,
+            skill.version,
+            skill.instructions,
+            skill.status,
+            skill.createdAt,
+            skill.createdBy ?? null,
+        ]);
+    },
+    async listCatalog({ tenantId }) {
+        // Latest active version per name. DISTINCT ON is the direct expression of that, and it reads off
+        // the partial index rather than sorting the tenant's whole skill history.
+        //
+        // Bodies are deliberately not selected: `SkillCatalogEntry` is documented as what discovery puts
+        // in context, and pulling 20k-character instructions into a catalog listing would defeat the
+        // lazy-loading the split exists for (AC-5).
+        const rows = await sql.query(`SELECT DISTINCT ON (name) id, name, description, source, version
+         FROM skills
+        WHERE tenant_id = $1 AND status = 'active'
+        ORDER BY name, version DESC`, [tenantId]);
+        return rows.map((r) => ({
+            id: r.id,
+            name: r.name,
+            description: r.description,
+            source: r.source,
+            version: Number(r.version),
+        }));
+    },
+    async findVersion({ tenantId, name, version }) {
+        // Exact version, never the nearest: a run records the version it used, and resolving to a
+        // neighbour would silently change behaviour on replay.
+        const rows = await sql.query(`SELECT ${SKILL_COLUMNS} FROM skills
+        WHERE tenant_id = $1 AND name = $2 AND version = $3`, [tenantId, name, version]);
+        const row = rows[0];
+        return row ? toSkill(row) : null;
+    },
+});
+/** Rebuilds the discriminated union from the two columns the pairing CHECK keeps consistent. */
+const toAuth = (kind, ref) => {
+    if (kind === "bearer" || kind === "oauth") {
+        // Unreachable while the pairing constraint holds; throwing rather than defaulting because a
+        // bearer connection with no reference would otherwise fail later, at handshake, far from here.
+        if (ref === null) {
+            throw new AgentPlatformError({
+                code: "invalid_input",
+                message: `MCP auth kind ${kind} is missing its credential reference`,
+                retryable: false,
+            });
+        }
+        return { kind, credentialRef: ref };
+    }
+    return { kind: "none" };
+};
+const toConnection = (r) => ({
+    id: r.id,
+    tenantId: r.tenant_id,
+    label: r.label,
+    transport: r.transport,
+    endpoint: r.endpoint,
+    auth: toAuth(r.auth_kind, r.auth_credential_ref),
+    enabled: r.enabled,
+    createdAt: iso(r.created_at),
+    ...(r.last_handshake_at === null ? {} : { lastHandshakeAt: iso(r.last_handshake_at) }),
+    ...(r.last_error === null ? {} : { lastError: r.last_error }),
+});
+const CONNECTION_COLUMNS = `id, tenant_id, label, transport, endpoint, auth_kind,
+         auth_credential_ref, enabled, created_at, last_handshake_at, last_error`;
+/**
+ * The egress policy is a constructor parameter, not a column — it is a deployment-level rule rather
+ * than per-connection data, which is why the SPEC's `egress_policy jsonb` had nothing to populate it.
+ * What survives a restart is the connection; the policy comes from whatever store is built at boot.
+ */
+export const createPostgresMcpConnectionStore = (sql, egress) => ({
+    async register({ tenantId, connection }) {
+        // Validated at registration and again at handshake by the client. Registration is the cheaper
+        // place to refuse, and it stops a policy-violating endpoint from ever being persisted.
+        validateEndpoint(egress, connection.transport, connection.endpoint);
+        if (connection.tenantId !== tenantId) {
+            throw new AgentPlatformError({
+                code: "forbidden",
+                message: "connection tenant mismatch",
+                retryable: false,
+            });
+        }
+        const ref = connection.auth.kind === "none" ? null : connection.auth.credentialRef;
+        await sql.query(`INSERT INTO mcp_connections
+         (tenant_id, id, label, transport, endpoint, auth_kind, auth_credential_ref,
+          enabled, created_at, last_handshake_at, last_error)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9::timestamptz, $10::timestamptz, $11)
+       ON CONFLICT (tenant_id, id) DO UPDATE
+          SET label = excluded.label,
+              transport = excluded.transport,
+              endpoint = excluded.endpoint,
+              auth_kind = excluded.auth_kind,
+              auth_credential_ref = excluded.auth_credential_ref,
+              enabled = excluded.enabled,
+              created_at = excluded.created_at,
+              last_handshake_at = excluded.last_handshake_at,
+              last_error = excluded.last_error`, [
+            tenantId,
+            connection.id,
+            connection.label,
+            connection.transport,
+            connection.endpoint,
+            connection.auth.kind,
+            ref,
+            connection.enabled,
+            connection.createdAt,
+            connection.lastHandshakeAt ?? null,
+            connection.lastError ?? null,
+        ]);
+    },
+    async get({ tenantId, id }) {
+        const rows = await sql.query(`SELECT ${CONNECTION_COLUMNS} FROM mcp_connections WHERE tenant_id = $1 AND id = $2`, [tenantId, id]);
+        const row = rows[0];
+        return row ? toConnection(row) : null;
+    },
+    async list({ tenantId }) {
+        const rows = await sql.query(`SELECT ${CONNECTION_COLUMNS} FROM mcp_connections WHERE tenant_id = $1 ORDER BY created_at, id`, [tenantId]);
+        return rows.map(toConnection);
+    },
+    async setEnabled({ tenantId, id, enabled }) {
+        // Silent on a missing connection, matching the reference adapter: disabling something absent has
+        // already achieved its purpose.
+        await sql.query(`UPDATE mcp_connections SET enabled = $3 WHERE tenant_id = $1 AND id = $2`, [
+            tenantId,
+            id,
+            enabled,
+        ]);
+    },
+});
+//# sourceMappingURL=config.js.map

package/dist/adapters/postgres/conversation-store.d.ts

@@ -0,0 +1,4 @@
+import type { ConversationStore } from "../../persistence/index.js";
+import type { SqlExecutor } from "./sql.js";
+export declare const createPostgresConversationStore: (sql: SqlExecutor, clock?: () => string) => ConversationStore;
+//# sourceMappingURL=conversation-store.d.ts.map

package/dist/adapters/postgres/conversation-store.js

@@ -0,0 +1,82 @@
+/**
+ * PostgreSQL `ConversationStore`. Pure SQL over a `SqlExecutor`; verified by the shared
+ * conformance harness (the same suite the in-memory adapter passes).
+ */
+import { AgentPlatformError } from "../../core/errors.js";
+const iso = (v) => (v instanceof Date ? v.toISOString() : new Date(v).toISOString());
+const toConversation = (r) => ({
+    id: r.id,
+    tenantId: r.tenant_id,
+    title: r.title,
+    version: r.version,
+    ...(r.archived_at === null ? {} : { archivedAt: iso(r.archived_at) }),
+    ...(r.deleted_at === null ? {} : { deletedAt: iso(r.deleted_at) }),
+    createdAt: iso(r.created_at),
+    updatedAt: iso(r.updated_at),
+});
+const conflict = (m) => new AgentPlatformError({ code: "conflict", message: m, retryable: false });
+const notFound = (id) => new AgentPlatformError({ code: "not_found", message: `Conversation ${id} not found`, retryable: false });
+const encodeCursor = (r) => Buffer.from(JSON.stringify({ c: iso(r.created_at), i: r.id })).toString("base64");
+const decodeCursor = (cursor) => JSON.parse(Buffer.from(cursor, "base64").toString("utf8"));
+/** Monotonic ISO clock, injectable for deterministic ordering in tests. */
+const defaultClock = () => {
+    let n = 0;
+    return () => new Date(Date.UTC(2020, 0, 1, 0, 0, 0, ++n)).toISOString();
+};
+export const createPostgresConversationStore = (sql, clock = defaultClock()) => ({
+    async create({ tenantId, id, title }) {
+        const now = clock();
+        const rows = await sql.query(`INSERT INTO conversations (tenant_id, id, title, version, created_at, updated_at)
+       VALUES ($1, $2, $3, 1, $4, $4)
+       ON CONFLICT (tenant_id, id) DO NOTHING
+       RETURNING *`, [tenantId, id, title, now]);
+        const row = rows[0];
+        if (!row)
+            throw conflict(`Conversation ${id} already exists`);
+        return toConversation(row);
+    },
+    async findById({ tenantId, id }) {
+        const rows = await sql.query(`SELECT * FROM conversations WHERE tenant_id = $1 AND id = $2 AND deleted_at IS NULL`, [tenantId, id]);
+        const row = rows[0];
+        return row ? toConversation(row) : null;
+    },
+    async list({ tenantId, limit, cursor }) {
+        const params = [tenantId, limit + 1];
+        let where = `tenant_id = $1 AND deleted_at IS NULL`;
+        if (cursor) {
+            const { c, i } = decodeCursor(cursor);
+            where += ` AND (created_at, id) > ($3, $4)`;
+            params.push(c, i);
+        }
+        const rows = await sql.query(`SELECT * FROM conversations WHERE ${where} ORDER BY created_at, id LIMIT $2`, params);
+        const hasMore = rows.length > limit;
+        const items = (hasMore ? rows.slice(0, limit) : rows).map(toConversation);
+        const last = hasMore ? rows[limit - 1] : undefined;
+        const page = last ? { items, nextCursor: encodeCursor(last) } : { items };
+        return page;
+    },
+    async update({ tenantId, id, expectedVersion, patch }) {
+        const changeArchived = patch.archivedAt !== undefined;
+        const rows = await sql.query(`UPDATE conversations
+         SET title = COALESCE($4, title),
+             archived_at = CASE WHEN $5 THEN $6 ELSE archived_at END,
+             version = version + 1,
+             updated_at = $7
+       WHERE tenant_id = $1 AND id = $2 AND version = $3 AND deleted_at IS NULL
+       RETURNING *`, [tenantId, id, expectedVersion, patch.title ?? null, changeArchived, patch.archivedAt ?? null, clock()]);
+        const row = rows[0];
+        if (row)
+            return toConversation(row);
+        // No row updated: distinguish a missing row from a stale version.
+        const exists = await this.findById({ tenantId, id });
+        throw exists ? conflict(`Conversation ${id} version ${expectedVersion} is stale`) : notFound(id);
+    },
+    async softDelete({ tenantId, id }) {
+        const now = clock();
+        const rows = await sql.query(`UPDATE conversations SET deleted_at = $3, version = version + 1, updated_at = $3
+       WHERE tenant_id = $1 AND id = $2 AND deleted_at IS NULL RETURNING id`, [tenantId, id, now]);
+        if (!rows[0])
+            throw notFound(id);
+    },
+});
+//# sourceMappingURL=conversation-store.js.map

package/dist/adapters/postgres/evaluation.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Postgres `EvaluationStore` (#141).
+ *
+ * Two properties are in the SQL.
+ *
+ * **`recordCase` upserts on the primary key**, so a resumed run re-recording a case it already scored replaces
+ * rather than double-counts it in the aggregate. The key is the idempotency; there is no applied-case set to
+ * keep right.
+ *
+ * **`completeRun` computes the aggregate from the case rows in one statement.** Accumulating as cases arrive
+ * would let a run's totals disagree with its own evidence after a re-record — and the number that gates a
+ * release must be derivable from what it was derived from.
+ */
+import type { EvaluationStore } from "../../persistence/index.js";
+import type { SqlExecutor } from "./sql.js";
+export declare const createPostgresEvaluationStore: (sql: SqlExecutor) => EvaluationStore;
+//# sourceMappingURL=evaluation.d.ts.map