@retinue/agentkit 0.1.0

package/dist/adapters/postgres/evaluation.js

@@ -0,0 +1,193 @@
+/**
+ * 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 { AgentPlatformError } from "../../core/errors.js";
+const iso = (v) => (v instanceof Date ? v.toISOString() : v);
+/** `jsonb` arrives parsed from node-postgres and as a string from some drivers. Both, or it works only in tests. */
+const json = (value, fallback) => value === null || value === undefined ? fallback : typeof value === "string" ? JSON.parse(value) : value;
+const toRun = (r) => ({
+    id: r.id,
+    release: r.release,
+    startedAt: iso(r.started_at),
+    ...(r.finished_at === null ? {} : { finishedAt: iso(r.finished_at) }),
+    total: Number(r.total),
+    passed: Number(r.passed),
+    meanScore: Number(r.mean_score),
+    byDimension: json(r.by_dimension, []),
+    costMinorUnits: Number(r.cost_minor_units),
+    graderVersions: json(r.grader_versions, {}),
+});
+const toCase = (r) => ({
+    caseId: r.case_id,
+    dimension: r.dimension,
+    expectKind: r.expect_kind,
+    verdict: { pass: r.passed, score: Number(r.score), reason: r.reason },
+    graderId: r.grader_id,
+    graderVersion: r.grader_version,
+    ...(r.model_id === null ? {} : { modelId: r.model_id }),
+    ...(r.prompt_version === null ? {} : { promptVersion: r.prompt_version }),
+    costMinorUnits: Number(r.cost_minor_units),
+});
+const RUN_COLUMNS = `id, release, started_at, finished_at, total, passed, mean_score, by_dimension,
+                     cost_minor_units, grader_versions`;
+const CASE_COLUMNS = `case_id, dimension, expect_kind, passed, score, reason, grader_id, grader_version,
+                       model_id, prompt_version, cost_minor_units`;
+export const createPostgresEvaluationStore = (sql) => ({
+    async startRun({ tenantId, id, release, startedAt }) {
+        const rows = await sql.query(`INSERT INTO evaluation_runs (tenant_id, id, release, started_at, total, passed, mean_score,
+                                    by_dimension, cost_minor_units, grader_versions)
+       VALUES ($1,$2,$3,$4,0,0,0,'[]'::jsonb,0,'{}'::jsonb)
+       -- Nothing updated: a duplicate run id is a caller bug, and silently reopening a completed run would
+       -- discard the numbers a release was gated on.
+       ON CONFLICT (tenant_id, id) DO NOTHING
+       RETURNING ${RUN_COLUMNS}`, [tenantId, id, release, startedAt]);
+        const created = rows[0];
+        if (created === undefined)
+            throw new AgentPlatformError({
+                code: "conflict",
+                message: `evaluation run ${id} already exists`,
+                retryable: false,
+            });
+        return toRun(created);
+    },
+    async recordCase({ tenantId, runId, result }) {
+        const rows = await sql.query(`INSERT INTO evaluation_case_results (tenant_id, run_id, case_id, dimension, expect_kind, passed, score,
+                                            reason, grader_id, grader_version, model_id, prompt_version,
+                                            cost_minor_units)
+       SELECT $1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13
+       -- Only when the run exists. Without this the foreign key would raise on a deleted run, and a harness
+       -- losing that race would abandon a whole scoring pass over an ordinary outcome.
+       WHERE EXISTS (SELECT 1 FROM evaluation_runs WHERE tenant_id = $1 AND id = $2)
+       -- The key is the idempotency: a resumed run re-recording a case replaces rather than double-counts it.
+       ON CONFLICT (tenant_id, run_id, case_id) DO UPDATE SET
+         dimension = EXCLUDED.dimension,
+         expect_kind = EXCLUDED.expect_kind,
+         passed = EXCLUDED.passed,
+         score = EXCLUDED.score,
+         reason = EXCLUDED.reason,
+         grader_id = EXCLUDED.grader_id,
+         grader_version = EXCLUDED.grader_version,
+         model_id = EXCLUDED.model_id,
+         prompt_version = EXCLUDED.prompt_version,
+         cost_minor_units = EXCLUDED.cost_minor_units
+       RETURNING case_id`, [
+            tenantId,
+            runId,
+            result.caseId,
+            result.dimension,
+            result.expectKind,
+            result.verdict.pass,
+            result.verdict.score,
+            result.verdict.reason,
+            result.graderId,
+            result.graderVersion,
+            result.modelId ?? null,
+            result.promptVersion ?? null,
+            result.costMinorUnits,
+        ]);
+        return { recorded: rows.length > 0 };
+    },
+    async completeRun({ tenantId, runId, finishedAt, graderVersions }) {
+        const rows = await sql.query(`WITH agg AS (
+         SELECT COUNT(*)                                    AS agg_total,
+                COUNT(*) FILTER (WHERE passed)              AS agg_passed,
+                COALESCE(AVG(score), 0)                     AS agg_mean_score,
+                COALESCE(SUM(cost_minor_units), 0)          AS agg_cost
+           FROM evaluation_case_results
+          WHERE tenant_id = $1 AND run_id = $2
+       ),
+       dims AS (
+         SELECT COALESCE(
+                  jsonb_agg(d ORDER BY d->>'dimension'),
+                  '[]'::jsonb
+                ) AS dim_json
+           FROM (
+             SELECT jsonb_build_object(
+                      'dimension', dimension,
+                      'total', COUNT(*),
+                      'passed', COUNT(*) FILTER (WHERE passed),
+                      'meanScore', COALESCE(AVG(score), 0)
+                    ) AS d
+               FROM evaluation_case_results
+              WHERE tenant_id = $1 AND run_id = $2
+              GROUP BY dimension
+           ) grouped
+       )
+       UPDATE evaluation_runs SET
+         finished_at = $3::timestamptz,
+         -- Every CTE column aliased: total, passed and cost_minor_units all exist on the target table
+         -- too, and an unqualified reference is ambiguous rather than defaulting to either.
+         total = agg.agg_total,
+         passed = agg.agg_passed,
+         mean_score = agg.agg_mean_score,
+         by_dimension = dims.dim_json,
+         cost_minor_units = agg.agg_cost,
+         grader_versions = $4::jsonb
+       FROM agg, dims
+       WHERE evaluation_runs.tenant_id = $1 AND evaluation_runs.id = $2
+       RETURNING ${RUN_COLUMNS}`, [tenantId, runId, finishedAt, JSON.stringify(graderVersions)]);
+        const run = rows[0];
+        if (run === undefined)
+            throw new AgentPlatformError({
+                code: "not_found",
+                message: `no such evaluation run ${runId}`,
+                retryable: false,
+            });
+        return toRun(run);
+    },
+    async get({ tenantId, runId }) {
+        const rows = await sql.query(`SELECT ${RUN_COLUMNS} FROM evaluation_runs WHERE tenant_id = $1 AND id = $2`, [tenantId, runId]);
+        // A foreign tenant's run yields no row: one tenant's quality gate is not another's business.
+        return rows[0] === undefined ? null : toRun(rows[0]);
+    },
+    async latest({ tenantId, release }) {
+        const rows = await sql.query(`SELECT ${RUN_COLUMNS} FROM evaluation_runs
+        WHERE tenant_id = $1
+          -- Completed only: an in-flight run's totals are partial, and comparing against one reports every case
+          -- it has not reached yet as a regression.
+          AND finished_at IS NOT NULL
+          AND ($2::text IS NULL OR release = $2::text)
+        -- Tie-broken by start then id: two runs can finish in the same instant, and "the latest run" must not
+        -- depend on physical row order. An unstable answer is a gate comparing against an arbitrary one of two.
+        ORDER BY finished_at DESC, started_at DESC, id DESC
+        LIMIT 1`, [tenantId, release ?? null]);
+        return rows[0] === undefined ? null : toRun(rows[0]);
+    },
+    async list({ tenantId, limit, cursor }) {
+        const rows = await sql.query(`SELECT ${RUN_COLUMNS} FROM evaluation_runs
+        WHERE tenant_id = $1
+          AND ($2::text IS NULL OR id > $2::text)
+        -- Newest first, the order a release history is read in.
+        ORDER BY started_at DESC, id
+        LIMIT $3`, [tenantId, cursor ?? null, limit + 1]);
+        const items = rows.slice(0, limit).map(toRun);
+        const last = items[items.length - 1];
+        return rows.length > limit && last !== undefined
+            ? { items, nextCursor: last.id }
+            : { items };
+    },
+    async listCaseResults({ tenantId, runId, limit, cursor }) {
+        const rows = await sql.query(`SELECT ${CASE_COLUMNS} FROM evaluation_case_results
+        WHERE tenant_id = $1 AND run_id = $2
+          AND ($3::text IS NULL OR case_id > $3::text)
+        -- By case id, so two runs' results zip together for a comparison without either side sorting.
+        ORDER BY case_id
+        LIMIT $4`, [tenantId, runId, cursor ?? null, limit + 1]);
+        const items = rows.slice(0, limit).map(toCase);
+        const last = items[items.length - 1];
+        return rows.length > limit && last !== undefined
+            ? { items, nextCursor: last.caseId }
+            : { items };
+    },
+});
+//# sourceMappingURL=evaluation.js.map

package/dist/adapters/postgres/file-content.d.ts

@@ -0,0 +1,30 @@
+/**
+ * File bytes in Postgres — REQ-036 (#185).
+ *
+ * The platform had two content stores: in-memory, which loses everything on restart and is not shared between
+ * the API and the worker, and Supabase Storage, which needs a Supabase project. So a deployment running plain
+ * Postgres and Redis — the arrangement the example and the Nest service both use — could not accept an
+ * attachment at all. That is what made the multimodal path unreachable in practice rather than in principle.
+ *
+ * ## `bytea`, and when that is the wrong answer
+ *
+ * Bytes in a row are not how anyone should store a hundred megabytes: TOAST compresses and out-of-lines them, so
+ * a large object costs a second read and sits in the same backup, the same replication stream and the same
+ * connection memory as the data you actually query. This adapter exists because "no object storage" is a real
+ * deployment shape and "no attachments" is a worse answer, not because a database is a good filesystem.
+ *
+ * `signedUrl` therefore returns `null` — deliberately, and it is the honest answer rather than a gap. There is no
+ * URL that reaches a row without going through this process, so reads are proxied through `readFile` and the
+ * caller streams them. An adapter that returned a URL it could not actually sign would be worse than one that
+ * says it cannot.
+ *
+ * ## What the port demands and this respects
+ *
+ * `maxBytes` is enforced **while reading**, and nothing is written when it is passed. The declared size is a
+ * claim; the cap is the defence. Buffering to the cap and then refusing keeps the failure bounded, and inserting
+ * a partial row would leave an orphan on every oversized upload — precisely what reconciliation then has to hunt.
+ */
+import type { FileContentStore } from "../../persistence/index.js";
+import type { SqlExecutor } from "./sql.js";
+export declare const createPostgresFileContentStore: (sql: SqlExecutor) => FileContentStore;
+//# sourceMappingURL=file-content.d.ts.map

package/dist/adapters/postgres/file-content.js

@@ -0,0 +1,111 @@
+/**
+ * File bytes in Postgres — REQ-036 (#185).
+ *
+ * The platform had two content stores: in-memory, which loses everything on restart and is not shared between
+ * the API and the worker, and Supabase Storage, which needs a Supabase project. So a deployment running plain
+ * Postgres and Redis — the arrangement the example and the Nest service both use — could not accept an
+ * attachment at all. That is what made the multimodal path unreachable in practice rather than in principle.
+ *
+ * ## `bytea`, and when that is the wrong answer
+ *
+ * Bytes in a row are not how anyone should store a hundred megabytes: TOAST compresses and out-of-lines them, so
+ * a large object costs a second read and sits in the same backup, the same replication stream and the same
+ * connection memory as the data you actually query. This adapter exists because "no object storage" is a real
+ * deployment shape and "no attachments" is a worse answer, not because a database is a good filesystem.
+ *
+ * `signedUrl` therefore returns `null` — deliberately, and it is the honest answer rather than a gap. There is no
+ * URL that reaches a row without going through this process, so reads are proxied through `readFile` and the
+ * caller streams them. An adapter that returned a URL it could not actually sign would be worse than one that
+ * says it cannot.
+ *
+ * ## What the port demands and this respects
+ *
+ * `maxBytes` is enforced **while reading**, and nothing is written when it is passed. The declared size is a
+ * claim; the cap is the defence. Buffering to the cap and then refusing keeps the failure bounded, and inserting
+ * a partial row would leave an orphan on every oversized upload — precisely what reconciliation then has to hunt.
+ */
+import { createHash } from "node:crypto";
+import { AgentPlatformError } from "../../core/errors.js";
+const int = (value) => (typeof value === "number" ? value : Number.parseInt(value, 10));
+export const createPostgresFileContentStore = (sql) => ({
+    async putFile({ tenantId, contentKey, mediaType, bytes, maxBytes }) {
+        const chunks = [];
+        let size = 0;
+        for await (const chunk of bytes) {
+            size += chunk.byteLength;
+            if (size > maxBytes) {
+                /**
+                 * Nothing has been written yet, and that is the point of buffering rather than streaming into the row.
+                 *
+                 * A streaming insert would have to either write and then delete — leaving the oversized object in the
+                 * WAL and briefly readable — or hold an open transaction for the duration of an upload. Buffering to the
+                 * cap bounds the memory at exactly `maxBytes`, which is the number the caller already agreed to.
+                 */
+                throw new AgentPlatformError({
+                    code: "invalid_input",
+                    message: `the file exceeds the ${maxBytes} byte limit`,
+                    retryable: false,
+                });
+            }
+            chunks.push(chunk);
+        }
+        const joined = Buffer.concat(chunks.map((c) => Buffer.from(c)));
+        const checksum = createHash("sha256").update(joined).digest("hex");
+        /**
+         * `ON CONFLICT … DO UPDATE`, not `DO NOTHING`.
+         *
+         * A content key is minted per upload, so a conflict means a retry of the *same* upload — and the bytes may
+         * differ from the first attempt if that attempt was truncated. Keeping the first write would leave a partial
+         * object that every later read returns, so the last complete write wins.
+         */
+        await sql.query(`INSERT INTO file_objects (tenant_id, content_key, media_type, byte_size, checksum, bytes)
+       VALUES ($1, $2, $3, $4, $5, $6)
+       ON CONFLICT (tenant_id, content_key)
+       DO UPDATE SET media_type = EXCLUDED.media_type, byte_size = EXCLUDED.byte_size,
+                     checksum = EXCLUDED.checksum, bytes = EXCLUDED.bytes`, [tenantId, contentKey, mediaType, joined.byteLength, checksum, joined]);
+        return { contentKey, byteSize: joined.byteLength, checksum };
+    },
+    async readFile({ tenantId, contentKey }) {
+        // Tenant in the predicate, always: a content key from one tenant must not resolve another's bytes, and the
+        // key is opaque precisely so that guessing one is useless.
+        const rows = await sql.query(`SELECT bytes FROM file_objects WHERE tenant_id = $1 AND content_key = $2`, [tenantId, contentKey]);
+        const row = rows[0];
+        if (row === undefined)
+            return null;
+        const bytes = Buffer.isBuffer(row.bytes) ? new Uint8Array(row.bytes) : row.bytes;
+        return (async function* () {
+            yield bytes;
+        })();
+    },
+    /**
+     * `null`, because there is no URL that reaches a database row.
+     *
+     * The port documents this as the answer for an adapter with no signing mechanism, and the caller streams
+     * through `readFile` instead. Returning a URL this process would have to serve itself would be a durable URL
+     * wearing a signed one's name — the thing #129's AC-6 made structurally impossible.
+     */
+    async signedUrl() {
+        return null;
+    },
+    async deleteFile({ tenantId, contentKey }) {
+        // Idempotent: deleting an absent row affects nothing, and a retried sweep depends on that.
+        await sql.query(`DELETE FROM file_objects WHERE tenant_id = $1 AND content_key = $2`, [tenantId, contentKey]);
+    },
+    async listObjects({ tenantId, prefix, limit, cursor }) {
+        const take = Math.max(1, Math.min(limit ?? 100, 1_000));
+        const rows = await sql.query(`SELECT content_key, byte_size FROM file_objects
+        WHERE tenant_id = $1
+          AND ($2::text IS NULL OR content_key LIKE $2 || '%')
+          AND ($3::text IS NULL OR content_key > $3)
+        ORDER BY content_key
+        LIMIT $4`, [tenantId, prefix ?? null, cursor ?? null, take + 1]);
+        // One more than asked for, so "there is another page" is a fact rather than an inference from a full page.
+        const page = rows.slice(0, take);
+        const items = page.map((r) => ({ contentKey: r.content_key, byteSize: int(r.byte_size) }));
+        return {
+            items,
+            ...(rows.length > take && page.length > 0 ? { nextCursor: page[page.length - 1].content_key } : {}),
+        };
+    },
+});
+//# sourceMappingURL=file-content.js.map

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

@@ -0,0 +1,19 @@
+/**
+ * Postgres `FileMetadataStore` (#129).
+ *
+ * Metadata only. `FileContentStore` has no Postgres implementation and is classified `notApplicable` in the
+ * conformance matrix, because a relational adapter holding file bytes means base64 in a column — the
+ * antipattern #102 rejected when it declined to make `blobs` a pointer table.
+ *
+ * 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.
+ *
+ * - **`transition` is a compare-and-set in the statement**, `WHERE state = $from`, so two workers racing a
+ *   resumed upload and a conversation delete cannot both succeed. `rowCount` is the answer.
+ * - **Deletion is scheduled, not cascaded.** The foreign key is `ON DELETE RESTRICT`: a cascade would drop
+ *   the metadata and leave the bytes, which is exactly the orphan this design exists to avoid.
+ */
+import type { FileMetadataStore } from "../../persistence/index.js";
+import type { SqlExecutor } from "./sql.js";
+export declare const createPostgresFileMetadataStore: (sql: SqlExecutor) => FileMetadataStore;
+//# sourceMappingURL=files.d.ts.map

package/dist/adapters/postgres/files.js

@@ -0,0 +1,209 @@
+/**
+ * Postgres `FileMetadataStore` (#129).
+ *
+ * Metadata only. `FileContentStore` has no Postgres implementation and is classified `notApplicable` in the
+ * conformance matrix, because a relational adapter holding file bytes means base64 in a column — the
+ * antipattern #102 rejected when it declined to make `blobs` a pointer table.
+ *
+ * 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.
+ *
+ * - **`transition` is a compare-and-set in the statement**, `WHERE state = $from`, so two workers racing a
+ *   resumed upload and a conversation delete cannot both succeed. `rowCount` is the answer.
+ * - **Deletion is scheduled, not cascaded.** The foreign key is `ON DELETE RESTRICT`: a cascade would drop
+ *   the metadata and leave the bytes, which is exactly the orphan this design exists to avoid.
+ */
+import { AgentPlatformError } from "../../core/errors.js";
+import { asId } from "../../core/ids.js";
+const iso = (v) => (v instanceof Date ? v.toISOString() : v);
+const toFile = (r) => ({
+    id: asId(r.id),
+    conversationId: asId(r.conversation_id),
+    filename: r.filename,
+    mediaType: r.media_type,
+    // `bigint` comes back as a string from node-postgres, which is correct for values past 2^53 and wrong
+    // for arithmetic. A file size is well inside the safe range, so it is narrowed here rather than left as
+    // a string a caller would have to remember to convert.
+    byteSize: Number(r.byte_size),
+    contentKey: r.content_key,
+    ...(r.checksum === null ? {} : { checksum: r.checksum }),
+    state: r.state,
+    uploadedBy: asId(r.uploaded_by),
+    createdAt: iso(r.created_at),
+    ...(r.deleted_at === null ? {} : { deletedAt: iso(r.deleted_at) }),
+    // Absent rather than a record with a null state: "nothing has tried to extract this" and "extraction is
+    // pending" are different facts, and the column being null is how the first one is spelled.
+    ...(r.extraction_state === null
+        ? {}
+        : {
+            extraction: {
+                state: r.extraction_state,
+                ...(r.extraction_ref === null ? {} : { ref: asId(r.extraction_ref) }),
+                ...(r.extraction_failure_reason === null ? {} : { failureReason: r.extraction_failure_reason }),
+                ...(r.extraction_failure_message === null ? {} : { failureMessage: r.extraction_failure_message }),
+                ...(r.extraction_pages === null ? {} : { pageCount: Number(r.extraction_pages) }),
+                ...(r.extraction_blocks === null ? {} : { blockCount: Number(r.extraction_blocks) }),
+                ...(r.extraction_truncated === null ? {} : { truncated: r.extraction_truncated }),
+                ...(r.extraction_confidence === null ? {} : { confidence: Number(r.extraction_confidence) }),
+                ...(r.extracted_at === null ? {} : { at: iso(r.extracted_at) }),
+            },
+        }),
+});
+const COLUMNS = `id, conversation_id, filename, media_type, byte_size, content_key, checksum, state,
+                 uploaded_by, created_at, deleted_at, extraction_state, extraction_ref,
+                 extraction_failure_reason, extraction_failure_message, extraction_pages,
+                 extraction_blocks, extraction_truncated, extraction_confidence, extracted_at`;
+/**
+ * Keyset cursor on `(created_at, id)`.
+ *
+ * The same encoding the other Postgres stores use. An offset cursor shifts when a row is inserted, so a
+ * caller paging a conversation's files while one uploads either sees a file twice or misses one.
+ */
+const encodeCursor = (f) => Buffer.from(`${f.createdAt} ${f.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 };
+};
+const page = (rows, limit) => {
+    // One row over the limit is fetched, so "is there more" is answered by its presence rather than by a
+    // second COUNT that could disagree with the page it describes.
+    const items = rows.slice(0, limit).map(toFile);
+    const last = items[items.length - 1];
+    return rows.length > limit && last !== undefined
+        ? { items, nextCursor: encodeCursor(last) }
+        : { items };
+};
+export const createPostgresFileMetadataStore = (sql) => ({
+    async create({ tenantId, file }) {
+        const rows = await sql.query(`INSERT INTO files (tenant_id, id, conversation_id, filename, media_type, byte_size,
+                          content_key, checksum, state, uploaded_by, created_at, deleted_at)
+       VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12)
+       -- Nothing is updated on conflict: a duplicate id is a caller bug, and quietly overwriting the
+       -- existing row would repoint a file at different bytes.
+       ON CONFLICT (tenant_id, id) DO NOTHING
+       RETURNING id`, [
+            tenantId,
+            file.id,
+            file.conversationId,
+            file.filename,
+            file.mediaType,
+            file.byteSize,
+            file.contentKey,
+            file.checksum ?? null,
+            file.state,
+            file.uploadedBy,
+            file.createdAt,
+            file.deletedAt ?? null,
+        ]);
+        if (rows.length === 0)
+            throw new AgentPlatformError({
+                code: "conflict",
+                message: `file ${file.id} already exists`,
+                retryable: false,
+            });
+    },
+    async get({ tenantId, id }) {
+        const rows = await sql.query(`SELECT ${COLUMNS} FROM files 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 : toFile(rows[0]);
+    },
+    async listByConversation({ tenantId, conversationId, limit, cursor }) {
+        const after = cursor === undefined ? null : decodeCursor(cursor);
+        const rows = await sql.query(`SELECT ${COLUMNS} FROM files
+        WHERE tenant_id = $1 AND conversation_id = $2
+          -- Live rows only: this is what a user sees, and a soft-deleted row here would be a deleted
+          -- attachment coming back. 'deleting' is excluded as well as 'deleted', because deletion is
+          -- scheduled before the bytes go and a file listed in between is one a read would fail on.
+          AND deleted_at IS NULL AND state NOT IN ('deleting','deleted')
+          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]);
+        return page(rows, limit);
+    },
+    async transition({ tenantId, id, from, to, at, checksum }) {
+        const rows = await sql.query(`UPDATE files
+          SET state = $4,
+              checksum = COALESCE($5, checksum),
+              -- Soft delete is a property of reaching 'deleted', so a row can never be deleted without a
+              -- time. The schema's CHECK says the same thing, twice on purpose.
+              deleted_at = CASE WHEN $4 = 'deleted' THEN $6::timestamptz ELSE deleted_at END
+        WHERE tenant_id = $1 AND id = $2
+          -- The compare, in the statement. A read-then-write would let a conversation delete land between
+          -- the two and leave a 'stored' file whose bytes are scheduled for removal -- and nothing sweeps
+          -- a stored file's object.
+          AND state = $3
+        RETURNING id`, [tenantId, id, from, to, checksum ?? null, at]);
+        return { moved: rows.length > 0 };
+    },
+    async scheduleConversationDeletion({ tenantId, conversationId, at }) {
+        const rows = await sql.query(`UPDATE files
+          SET state = 'deleting', deleted_at = $3::timestamptz
+        WHERE tenant_id = $1 AND conversation_id = $2
+          -- 'pending' as well as 'stored': an upload in flight when the conversation is deleted must not
+          -- complete into a conversation that no longer exists, and moving it here is what makes its own
+          -- transition to 'stored' fail.
+          AND state IN ('stored','pending')
+        RETURNING id`, [tenantId, conversationId, at]);
+        // One statement rather than a list and a loop: a file uploaded between the two would be missed, and
+        // missed silently.
+        return { scheduled: rows.length };
+    },
+    async recordExtraction({ tenantId, id, extraction }) {
+        const rows = await sql.query(`UPDATE files
+          SET extraction_state = $3,
+              extraction_ref = $4,
+              extraction_failure_reason = $5,
+              extraction_failure_message = $6,
+              extraction_pages = $7,
+              extraction_blocks = $8,
+              extraction_truncated = $9,
+              extraction_confidence = $10,
+              extracted_at = $11::timestamptz
+        -- No compare on the previous extraction state, unlike transition(). A worker retrying after a crash
+        -- does not know what it wrote before the crash, and requiring it to would make recovery impossible.
+        WHERE tenant_id = $1 AND id = $2
+        RETURNING id`, [
+            tenantId,
+            id,
+            extraction.state,
+            extraction.ref ?? null,
+            extraction.failureReason ?? null,
+            extraction.failureMessage ?? null,
+            extraction.pageCount ?? null,
+            extraction.blockCount ?? null,
+            extraction.truncated ?? null,
+            extraction.confidence ?? null,
+            extraction.at ?? null,
+        ]);
+        // Zero rows means the file is gone -- a conversation deleted while extraction ran. An ordinary race, so
+        // it is reported rather than thrown; a worker that threw would retry it forever.
+        return { recorded: rows.length > 0 };
+    },
+    async listByExtractionState({ tenantId, state, olderThan, limit, cursor }) {
+        const after = cursor === undefined ? null : decodeCursor(cursor);
+        const rows = await sql.query(`SELECT ${COLUMNS} FROM files
+        WHERE tenant_id = $1
+          -- A file nothing has touched has a NULL state, and that is the same fact as 'pending': the row is
+          -- waiting. Coalescing here is what lets this query find the files a lost enqueue dropped, which is
+          -- the whole reason the method exists.
+          AND COALESCE(extraction_state, 'pending') = $2
+          AND created_at < $3::timestamptz
+          AND ($4::text IS NULL OR (created_at, id) > ($4::timestamptz, $5::text))
+        ORDER BY created_at, id
+        LIMIT $6`, [tenantId, state, olderThan, after?.createdAt ?? null, after?.id ?? null, limit + 1]);
+        return page(rows, limit);
+    },
+    async listByState({ tenantId, state, olderThan, limit, cursor }) {
+        const after = cursor === undefined ? null : decodeCursor(cursor);
+        const rows = await sql.query(`SELECT ${COLUMNS} FROM files
+        WHERE tenant_id = $1 AND state = $2
+          -- Strictly older, so a file that entered the state a second ago is an upload in progress rather
+          -- than an orphan. Without it the job reports every upload happening while it runs.
+          AND created_at < $3::timestamptz
+          AND ($4::text IS NULL OR (created_at, id) > ($4::timestamptz, $5::text))
+        ORDER BY created_at, id
+        LIMIT $6`, [tenantId, state, olderThan, after?.createdAt ?? null, after?.id ?? null, limit + 1]);
+        return page(rows, limit);
+    },
+});
+//# sourceMappingURL=files.js.map

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

@@ -0,0 +1,20 @@
+/**
+ * Flow definitions and executions in Postgres — #187, #186.
+ *
+ * Two things are enforced by the schema rather than by this file, because a rule in code is a rule one code path
+ * can miss:
+ *
+ * - **A version cannot be overwritten.** `(tenant_id, flow_id, version)` is the primary key and the insert has no
+ *   `ON CONFLICT`, so a second write of the same version is a constraint violation. An execution pins a version
+ *   and reads it for its whole life; a definition that could change under it would change an automation's shape
+ *   halfway through.
+ * - **A save cannot move an execution backwards.** The update carries `WHERE steps <= $n`, so a stale document
+ *   from a slower worker updates nothing. A flow that goes backwards re-performs external writes, which is the
+ *   failure the whole module exists to prevent — and doing it in the `WHERE` means two concurrent saves are
+ *   ordered by the database rather than by whichever read happened first.
+ */
+import type { FlowDefinitionStore, FlowExecutionStore } from "../../persistence/index.js";
+import type { SqlExecutor } from "./sql.js";
+export declare const createPostgresFlowDefinitionStore: (sql: SqlExecutor) => FlowDefinitionStore;
+export declare const createPostgresFlowExecutionStore: (sql: SqlExecutor) => FlowExecutionStore;
+//# sourceMappingURL=flows.d.ts.map