@retinue/agentkit 0.1.0

package/dist/adapters/postgres/pg-executor.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Production `SqlExecutor` backed by node-postgres. `pg` is imported type-only here — the caller
+ * supplies the `Pool` — so the package has no runtime coupling to a specific driver instance.
+ */
+import type { Pool } from "pg";
+import type { SqlExecutor } from "./sql.js";
+import type { ConnectionOpener } from "./transaction.js";
+export declare const createPgExecutor: (pool: Pool) => SqlExecutor;
+/**
+ * Checks out one connection for the duration of `fn` — the primitive `createPgExecutor` cannot
+ * provide, because `pool.query` picks a different connection per call, so `BEGIN` / work / `COMMIT`
+ * through it would land on three connections and guarantee nothing (#98).
+ *
+ * `searchPath` exists for the conformance suite, which isolates each executor in its own schema. A
+ * pooled connection carries whatever `search_path` its last user left, so it has to be set per
+ * checkout rather than once at pool creation.
+ */
+export declare const createPoolOpener: (pool: Pool, searchPath?: string) => ConnectionOpener;
+//# sourceMappingURL=pg-executor.d.ts.map

package/dist/adapters/postgres/pg-executor.js

@@ -0,0 +1,32 @@
+export const createPgExecutor = (pool) => ({
+    query(text, params) {
+        return pool.query(text, params ? [...params] : undefined).then((r) => r.rows);
+    },
+});
+/**
+ * Checks out one connection for the duration of `fn` — the primitive `createPgExecutor` cannot
+ * provide, because `pool.query` picks a different connection per call, so `BEGIN` / work / `COMMIT`
+ * through it would land on three connections and guarantee nothing (#98).
+ *
+ * `searchPath` exists for the conformance suite, which isolates each executor in its own schema. A
+ * pooled connection carries whatever `search_path` its last user left, so it has to be set per
+ * checkout rather than once at pool creation.
+ */
+export const createPoolOpener = (pool, searchPath) => {
+    return async (fn) => {
+        const client = await pool.connect();
+        try {
+            if (searchPath)
+                await client.query(`SET search_path TO ${searchPath}`);
+            return await fn({
+                query(text, params) {
+                    return client.query(text, params ? [...params] : undefined).then((r) => r.rows);
+                },
+            });
+        }
+        finally {
+            client.release();
+        }
+    };
+};
+//# sourceMappingURL=pg-executor.js.map

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

@@ -0,0 +1,26 @@
+/**
+ * The Postgres `RunEventPruner` (#151).
+ *
+ * One statement, and every interesting decision is in it.
+ *
+ * **`ctid IN (SELECT … LIMIT n)`.** The bound has to be on the *rows selected*, not on the delete, and Postgres
+ * has no `DELETE … LIMIT`. Selecting `ctid` — the physical row locator — lets the subquery do a bounded,
+ * index-driven scan and the delete touch exactly those rows. The alternative shapes are worse: a correlated
+ * `IN (tenant_id, run_id, sequence)` tuple list is a much larger comparison per row, and a CTE with `RETURNING`
+ * still needs the same bounded selection to feed it.
+ *
+ * **The safety join is inside the subquery.** `run_events` has no status of its own, so "is this run terminal?"
+ * is a lookup on `runs` by `(tenant_id, run_id)` — which is `runs`' primary key, so it costs an index probe per
+ * candidate and no extra index. Putting the join in the subquery means a non-terminal run's rows are never
+ * *selected*, so they cannot be deleted by a later mistake in the outer statement.
+ *
+ * **`FOR UPDATE SKIP LOCKED` is deliberately absent.** Two concurrent prunes selecting overlapping `ctid`s is
+ * harmless: the second `DELETE` matches no row for the ones already gone and reports a smaller count. Adding row
+ * locks would serialise the sweeps and, worse, hold locks across the join — which is exactly the blocking this
+ * batching exists to avoid. Idempotency here comes from the delete being a no-op on an absent row, not from
+ * exclusion.
+ */
+import { type RunEventPruner } from "../../retention/index.js";
+import type { SqlExecutor } from "./sql.js";
+export declare const createPostgresRunEventPruner: (sql: SqlExecutor) => RunEventPruner;
+//# sourceMappingURL=retention.d.ts.map

package/dist/adapters/postgres/retention.js

@@ -0,0 +1,59 @@
+/**
+ * The Postgres `RunEventPruner` (#151).
+ *
+ * One statement, and every interesting decision is in it.
+ *
+ * **`ctid IN (SELECT … LIMIT n)`.** The bound has to be on the *rows selected*, not on the delete, and Postgres
+ * has no `DELETE … LIMIT`. Selecting `ctid` — the physical row locator — lets the subquery do a bounded,
+ * index-driven scan and the delete touch exactly those rows. The alternative shapes are worse: a correlated
+ * `IN (tenant_id, run_id, sequence)` tuple list is a much larger comparison per row, and a CTE with `RETURNING`
+ * still needs the same bounded selection to feed it.
+ *
+ * **The safety join is inside the subquery.** `run_events` has no status of its own, so "is this run terminal?"
+ * is a lookup on `runs` by `(tenant_id, run_id)` — which is `runs`' primary key, so it costs an index probe per
+ * candidate and no extra index. Putting the join in the subquery means a non-terminal run's rows are never
+ * *selected*, so they cannot be deleted by a later mistake in the outer statement.
+ *
+ * **`FOR UPDATE SKIP LOCKED` is deliberately absent.** Two concurrent prunes selecting overlapping `ctid`s is
+ * harmless: the second `DELETE` matches no row for the ones already gone and reports a smaller count. Adding row
+ * locks would serialise the sweeps and, worse, hold locks across the join — which is exactly the blocking this
+ * batching exists to avoid. Idempotency here comes from the delete being a no-op on an absent row, not from
+ * exclusion.
+ */
+import { PRUNABLE_RUN_STATUSES } from "../../retention/index.js";
+/**
+ * The terminal statuses as a SQL list.
+ *
+ * Built from the exported constant so the SQL and the documented rule cannot drift. Quoted here rather than
+ * passed as a parameter because an array parameter would make the planner treat it as opaque and lose the
+ * index probe on `runs`; the values come from a closed list in our own source, never from input.
+ */
+const TERMINAL_LIST = PRUNABLE_RUN_STATUSES.map((s) => `'${s}'`).join(", ");
+export const createPostgresRunEventPruner = (sql) => ({
+    async prune({ olderThan, limit }) {
+        // A zero or negative limit would make `ctid IN (SELECT ... LIMIT 0)` delete nothing, which is correct but
+        // costs a scan. Answered without touching the database, because a maintenance loop with a misconfigured
+        // batch size should not generate load.
+        if (limit <= 0)
+            return { deleted: 0 };
+        const rows = await sql.query(`DELETE FROM run_events
+        WHERE ctid IN (
+          SELECT e.ctid
+            FROM run_events e
+            JOIN runs r ON r.tenant_id = e.tenant_id AND r.id = e.run_id
+           WHERE e.created_at < $1::timestamptz
+             -- AC-2. A non-terminal run can still be reconciled against its log, so its events are never
+             -- selected however old they are -- including a run that has waited months on a human approval.
+             AND r.status IN (${TERMINAL_LIST})
+           -- Oldest first, so a bounded sweep makes progress at the end of the table that will never come back
+           -- rather than nibbling at whatever the scan happened to reach.
+           ORDER BY e.created_at
+           LIMIT $2
+        )
+        RETURNING ctid`, [olderThan, limit]);
+        // The row count from `RETURNING`, not from a driver-specific `rowCount`: the executor port returns rows, and
+        // counting them is the one form that is identical across every adapter.
+        return { deleted: rows.length };
+    },
+});
+//# sourceMappingURL=retention.js.map

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

@@ -0,0 +1,17 @@
+/**
+ * Postgres `UsageRollupStore` (#139).
+ *
+ * Two properties are in the SQL rather than above it.
+ *
+ * **`rebuild` is one statement.** It aggregates the bucket's raw events and upserts the row, so the read and
+ * the write cannot see different data — a read-then-write would let an event land between them and be lost from
+ * the rollup while sitting in the ledger, which is the "no lost records" half of AC-4.
+ *
+ * **Idempotency is the primary key.** `ON CONFLICT (tenant_id, period, bucket_start) DO UPDATE` means a
+ * re-run replaces rather than accumulates, and two workers racing one bucket write the same value. No applied-
+ * event set, nothing to keep exactly right forever, and no way to double count.
+ */
+import type { UsageRollupStore } from "../../persistence/index.js";
+import type { SqlExecutor } from "./sql.js";
+export declare const createPostgresUsageRollupStore: (sql: SqlExecutor) => UsageRollupStore;
+//# sourceMappingURL=rollups.d.ts.map

package/dist/adapters/postgres/rollups.js

@@ -0,0 +1,267 @@
+/**
+ * Postgres `UsageRollupStore` (#139).
+ *
+ * Two properties are in the SQL rather than above it.
+ *
+ * **`rebuild` is one statement.** It aggregates the bucket's raw events and upserts the row, so the read and
+ * the write cannot see different data — a read-then-write would let an event land between them and be lost from
+ * the rollup while sitting in the ledger, which is the "no lost records" half of AC-4.
+ *
+ * **Idempotency is the primary key.** `ON CONFLICT (tenant_id, period, bucket_start) DO UPDATE` means a
+ * re-run replaces rather than accumulates, and two workers racing one bucket write the same value. No applied-
+ * event set, nothing to keep exactly right forever, and no way to double count.
+ */
+const iso = (v) => (v instanceof Date ? v.toISOString() : v);
+/**
+ * `bigint` comes back as a string from node-postgres — correct past 2^53 and wrong for arithmetic.
+ *
+ * Narrowed here because every one of these is well inside the safe range: a tenant would need 9×10^15 tokens
+ * in one hour to overflow. Left as strings, a caller adding two rollups would concatenate them.
+ */
+const toRollup = (r) => ({
+    // #175: the grain, so a caller holding a mixed list can tell a tenant total from one person's.
+    ...(r.principal_id === null || r.principal_id === undefined
+        ? {}
+        : { principalId: r.principal_id }),
+    period: r.period,
+    bucketStart: iso(r.bucket_start),
+    inputTokens: Number(r.input_tokens),
+    outputTokens: Number(r.output_tokens),
+    cachedInputTokens: Number(r.cached_input_tokens),
+    reasoningTokens: Number(r.reasoning_tokens),
+    costMinorUnits: Number(r.cost_minor_units),
+    eventCount: Number(r.event_count),
+    currency: r.currency,
+    computedAt: iso(r.computed_at),
+});
+const COLUMNS = `principal_id, period, bucket_start, input_tokens, output_tokens, cached_input_tokens,
+                 reasoning_tokens, cost_minor_units, event_count, currency, computed_at`;
+/** The interval a period spans, as a SQL literal. Two values, both from a closed union — never user input. */
+/**
+ * The width of a bucket, as a SQL interval — total over `RollupPeriod`.
+ *
+ * A `Record` rather than a ternary chain, and that is the fix: it read
+ * `period === "hour" ? "1 hour" : "1 day"`, so adding `week` and `month` to `ROLLUP_PERIODS` silently gave both
+ * a **one-day** window. A month bucket starting on the 1st then aggregated only the 1st, and every monthly figure
+ * was whatever happened on the first of the month — zero for most of any month, and never obviously wrong.
+ *
+ * Nothing failed: the migration's CHECK accepted the period, the bucket arithmetic truncated correctly, the row
+ * was written. Only the number was wrong. A total map makes the next period a compile error instead.
+ */
+const BUCKET_INTERVAL = {
+    hour: "1 hour",
+    day: "1 day",
+    week: "7 days",
+    // Postgres resolves `1 month` against the bucket's own start, so February gets 28 days and March 31 — the
+    // calendar behaviour the bucket boundaries already assume.
+    month: "1 month",
+};
+const intervalFor = (period) => BUCKET_INTERVAL[period];
+export const createPostgresUsageRollupStore = (sql) => ({
+    /**
+     * Rebuild one bucket — the tenant's, or one principal's (#175).
+     *
+     * `principalId` absent aggregates every event in the bucket and writes the row where `principal_id IS NULL`;
+     * supplied aggregates that person's events and writes their row. The same statement either way, because the
+     * two are the same measurement at two grains and a second statement would be a second chance to disagree.
+     *
+     * `IS NOT DISTINCT FROM` in the conflict target rather than `=`, because the tenant row's `principal_id` is
+     * NULL and `NULL = NULL` is not true — an equality predicate would fail to match the existing row and try to
+     * insert a duplicate, which the partial unique index would then reject. The kind of bug that only appears on
+     * the *second* rebuild.
+     */
+    async rebuild({ tenantId, period, bucketStart, principalId }) {
+        const rows = await sql.query(`WITH agg AS (
+         SELECT COALESCE(SUM(input_tokens), 0)        AS input_tokens,
+                COALESCE(SUM(output_tokens), 0)       AS output_tokens,
+                COALESCE(SUM(cached_input_tokens), 0) AS cached_input_tokens,
+                -- reasoning_tokens is nullable in usage_records (not every provider reports it), so the
+                -- COALESCE is inside the SUM as well as outside: SUM ignores NULLs, but a bucket where *every*
+                -- row is NULL sums to NULL rather than 0.
+                COALESCE(SUM(COALESCE(reasoning_tokens, 0)), 0) AS reasoning_tokens,
+                COALESCE(SUM(cost_minor_units), 0)   AS cost_minor_units,
+                COUNT(*)                             AS event_count,
+                -- One currency per bucket. MIN rather than an arbitrary pick so the value is deterministic:
+                -- two rebuilds of the same bucket must agree, and a mixed-currency bucket is a configuration
+                -- problem the reconciliation report surfaces rather than something to paper over here.
+                COALESCE(MIN(currency), '')          AS currency,
+                -- The high-water mark this rollup covers. Recorded so staleness is an integer comparison
+                -- rather than a clock comparison -- see 0019.
+                COALESCE(MAX(record_seq), 0)         AS covers_seq
+           FROM usage_records
+          WHERE tenant_id = $1
+            AND occurred_at >= $3::timestamptz
+            AND occurred_at <  $3::timestamptz + INTERVAL '${intervalFor(period)}'
+            -- The whole tenant when $4 is NULL, one person otherwise. One predicate rather than two queries.
+            AND ($4::text IS NULL OR principal_id = $4::text)
+       )
+       INSERT INTO usage_rollups (tenant_id, principal_id, period, bucket_start, input_tokens, output_tokens,
+                                  cached_input_tokens, reasoning_tokens, cost_minor_units, event_count,
+                                  currency, computed_at, covers_seq)
+       SELECT $1, $4::text, $2, $3::timestamptz, input_tokens, output_tokens, cached_input_tokens, reasoning_tokens,
+              -- clock_timestamp(), not now(). now() is the *transaction* timestamp and therefore constant
+              -- within one -- so a rebuild and an append in the same transaction would stamp the identical
+              -- instant, the staleness comparison would always hold, and the bucket would be rebuilt forever.
+              -- Found by the conformance suite, whose executor is transaction-scoped.
+              cost_minor_units, event_count, currency, clock_timestamp(), covers_seq
+         FROM agg
+       -- The upsert *is* the idempotency: a re-run replaces rather than accumulates, and two workers racing
+       -- this bucket write the same value. DO UPDATE rather than DO NOTHING because a rebuild after new events
+       -- must actually change the row.
+       -- The arbiter has to name the index that actually covers this row's grain — #175.
+       --
+       -- Uniqueness is two *partial* indexes, one where principal_id IS NULL and one where it is not, because a
+       -- NULL cannot participate in a normal unique constraint. A single ON CONFLICT clause therefore cannot
+       -- serve both: naming the tenant index while inserting a principal row finds no arbiter, inserts, and
+       -- violates the principal index on the *second* rebuild. Which is exactly what happened — the first
+       -- rebuild of each per-person bucket succeeded and every one after it threw a duplicate-key violation on
+       -- usage_rollups_principal_bucket_idx.
+       ON CONFLICT ${principalId === undefined
+            ? "(tenant_id, period, bucket_start) WHERE principal_id IS NULL"
+            : "(tenant_id, principal_id, period, bucket_start) WHERE principal_id IS NOT NULL"} DO UPDATE SET
+         input_tokens = EXCLUDED.input_tokens,
+         output_tokens = EXCLUDED.output_tokens,
+         cached_input_tokens = EXCLUDED.cached_input_tokens,
+         reasoning_tokens = EXCLUDED.reasoning_tokens,
+         cost_minor_units = EXCLUDED.cost_minor_units,
+         event_count = EXCLUDED.event_count,
+         currency = EXCLUDED.currency,
+         computed_at = EXCLUDED.computed_at,
+         covers_seq = EXCLUDED.covers_seq
+       RETURNING ${COLUMNS}`, [tenantId, period, bucketStart, principalId ?? null]);
+        const row = rows[0];
+        if (row === undefined)
+            // Unreachable: the CTE always produces one row, even for an empty bucket. Returned rather than thrown so
+            // a caller never has to handle an impossible null.
+            return {
+                period,
+                bucketStart,
+                inputTokens: 0,
+                outputTokens: 0,
+                cachedInputTokens: 0,
+                reasoningTokens: 0,
+                costMinorUnits: 0,
+                eventCount: 0,
+                currency: "",
+                computedAt: new Date().toISOString(),
+            };
+        return toRollup(row);
+    },
+    async get({ tenantId, period, bucketStart, principalId }) {
+        const rows = await sql.query(`SELECT ${COLUMNS} FROM usage_rollups
+        WHERE tenant_id = $1 AND period = $2 AND bucket_start = $3::timestamptz
+          -- IS NOT DISTINCT FROM, so a NULL parameter matches the tenant row where = would match nothing.
+          AND principal_id IS NOT DISTINCT FROM $4::text`, [tenantId, period, bucketStart, principalId ?? null]);
+        // A foreign tenant's bucket yields no row, so no aggregate can span tenants and the answer is null without
+        // a comparison anyone could get wrong.
+        return rows[0] === undefined ? null : toRollup(rows[0]);
+    },
+    async list({ tenantId, period, from, to, limit, cursor, principalId }) {
+        const rows = await sql.query(`SELECT ${COLUMNS} FROM usage_rollups
+        WHERE tenant_id = $1 AND period = $2
+          -- The tenant's own buckets when $7 is NULL, one person's otherwise (#175). Without this predicate a
+          -- tenant chart would sum its own row *and* every principal's, double-counting everything.
+          AND principal_id IS NOT DISTINCT FROM $7::text
+          AND bucket_start >= $3::timestamptz
+          -- Exclusive upper bound, so adjacent ranges tile without a caller double-counting a boundary bucket.
+          AND bucket_start <  $4::timestamptz
+          AND ($5::text IS NULL OR bucket_start > $5::timestamptz)
+        ORDER BY bucket_start
+        LIMIT $6`, [tenantId, period, from, to, cursor ?? null, limit + 1, principalId ?? null]);
+        const items = rows.slice(0, limit).map(toRollup);
+        const last = items[items.length - 1];
+        return rows.length > limit && last !== undefined
+            ? { items, nextCursor: last.bucketStart }
+            : { items };
+    },
+    async sum({ tenantId, period, from, to, principalId }) {
+        const rows = await sql.query(
+        // Over the *rollups*, which is the point of AC-1: a spend query never scans raw records however much has
+        // been recorded.
+        `SELECT COALESCE(SUM(input_tokens), 0)        AS input_tokens,
+              COALESCE(SUM(output_tokens), 0)       AS output_tokens,
+              COALESCE(SUM(cached_input_tokens), 0) AS cached_input_tokens,
+              COALESCE(SUM(reasoning_tokens), 0)   AS reasoning_tokens,
+              COALESCE(SUM(cost_minor_units), 0)   AS cost_minor_units,
+              COALESCE(SUM(event_count), 0)        AS event_count
+         FROM usage_rollups
+        WHERE tenant_id = $1 AND period = $2
+          -- Same predicate as list, and load-bearing for the same reason: summing across the principal
+          -- dimension would add each person's total to the tenant's and double every figure.
+          AND principal_id IS NOT DISTINCT FROM $5::text
+          AND bucket_start >= $3::timestamptz AND bucket_start < $4::timestamptz`, [tenantId, period, from, to, principalId ?? null]);
+        const r = rows[0];
+        return {
+            inputTokens: Number(r?.input_tokens ?? 0),
+            outputTokens: Number(r?.output_tokens ?? 0),
+            cachedInputTokens: Number(r?.cached_input_tokens ?? 0),
+            reasoningTokens: Number(r?.reasoning_tokens ?? 0),
+            costMinorUnits: Number(r?.cost_minor_units ?? 0),
+            eventCount: Number(r?.event_count ?? 0),
+        };
+    },
+    async listStaleBuckets({ tenantId, period, since, limit, cursor }) {
+        const rows = await sql.query(
+        // Derived from the ledger: a bucket is stale when it holds an event at or after its last computation, or
+        // has never been computed. So the job's work list needs no persisted cursor -- an interrupted run resumes
+        // by asking again, and there is nothing to lose.
+        `WITH buckets AS (
+         /**
+          * GROUPING SETS, so one pass finds both grains — #175.
+          *
+          * A per-principal rollup is only useful if something rebuilds it, and the job cannot enumerate which
+          * principals were active in a bucket without reading the ledger — which is the scan a rollup exists to
+          * avoid. This query already reads the ledger to decide staleness, so it is the one place that knows
+          * cheaply, and GROUPING SETS ((bucket), (bucket, principal)) gets both for the price of the pass it
+          * was already making.
+          *
+          * The (bucket) set produces the tenant row with a NULL principal_id, which is exactly how the tenant
+          * row is stored — so the LEFT JOIN below matches without a special case.
+          */
+         SELECT date_trunc($2, occurred_at) AS bucket_start,
+                principal_id,
+                -- Which grouping set produced this row.
+                --
+                -- Necessary, not decoration: a NULL principal_id means "aggregated over every principal" in the
+                -- (bucket) set and "this event has no principal" in the (bucket, principal) set. Without
+                -- GROUPING they are indistinguishable, and a ledger of events with no principal produces the
+                -- same row twice — which is exactly what the conformance suite caught.
+                GROUPING(principal_id)      AS is_tenant_row,
+                -- The newest *sequence* in this bucket, not the newest time. An event recorded late with an
+                -- occurred_at in the past still has a higher sequence, so its bucket is correctly stale.
+                MAX(record_seq)             AS newest_seq
+           FROM usage_records
+          WHERE tenant_id = $1 AND occurred_at >= $3::timestamptz
+          GROUP BY GROUPING SETS ((1), (1, 2))
+       )
+       SELECT b.bucket_start, b.principal_id
+         FROM buckets b
+         LEFT JOIN usage_rollups r
+           ON r.tenant_id = $1 AND r.period = $2 AND r.bucket_start = b.bucket_start
+          AND r.principal_id IS NOT DISTINCT FROM b.principal_id
+        -- Parenthesised deliberately: AND binds tighter than OR, so without these the cursor filter would
+        -- apply only to the second branch and every never-computed bucket would come back on every page.
+        -- Strictly greater: an integer comparison with no ties, so a drained bucket is *not* listed.
+        WHERE (r.bucket_start IS NULL OR COALESCE(r.covers_seq, 0) < b.newest_seq)
+          AND ($4::text IS NULL OR b.bucket_start > $4::timestamptz)
+          -- Keep the tenant row, and a principal row only when there is an actual principal. Events with no
+          -- principal contribute to the tenant total and to no per-person total, which is what "unattributed"
+          -- honestly means.
+          AND (b.is_tenant_row = 1 OR b.principal_id IS NOT NULL)
+        -- The tenant row first within a bucket, so a job that stops mid-bucket has at least the total.
+        ORDER BY b.bucket_start, b.principal_id NULLS FIRST
+        LIMIT $5`, [tenantId, period, since, cursor ?? null, limit + 1]);
+        const items = rows.slice(0, limit).map((r) => ({
+            period,
+            bucketStart: iso(r.bucket_start),
+            ...(r.principal_id === null || r.principal_id === undefined
+                ? {}
+                : { principalId: r.principal_id }),
+        }));
+        const last = items[items.length - 1];
+        return rows.length > limit && last !== undefined
+            ? { items, nextCursor: last.bucketStart }
+            : { items };
+    },
+});
+//# sourceMappingURL=rollups.js.map

package/dist/adapters/postgres/run-coordinator.d.ts

@@ -0,0 +1,5 @@
+import type { ConversationRunCoordinator } from "../../persistence/index.js";
+import type { SqlExecutor } from "./sql.js";
+import type { TransactionRunner } from "./transaction.js";
+export declare const createPostgresConversationRunCoordinator: (sql: SqlExecutor, runner: TransactionRunner) => ConversationRunCoordinator;
+//# sourceMappingURL=run-coordinator.d.ts.map

package/dist/adapters/postgres/run-coordinator.js

@@ -0,0 +1,98 @@
+/** jsonb comes back parsed from PGlite and as text from some drivers; normalise both. */
+const toQueue = (value) => {
+    const parsed = typeof value === "string" ? JSON.parse(value) : value;
+    return Array.isArray(parsed) ? parsed.map(String) : [];
+};
+const SELECT_SLOT_FOR_UPDATE = `SELECT active_run_id, queued
+     FROM conversation_run_slots
+    WHERE tenant_id = $1 AND conversation_id = $2
+      FOR UPDATE`;
+const WRITE_SLOT = `UPDATE conversation_run_slots
+      SET active_run_id = $3, queued = $4::jsonb, updated_at = now()
+    WHERE tenant_id = $1 AND conversation_id = $2`;
+export const createPostgresConversationRunCoordinator = (sql, runner) => {
+    /**
+     * Whether the slot's current holder can be displaced.
+     *
+     * Liveness comes from the run's own lease (#93) rather than a second clock on the slot. Two leases
+     * for one fact drift, and when they disagree there is no principled tiebreak.
+     *
+     * The `rows[0]?.dead === true` shape carries the load-bearing half: **no run row means unknown, not
+     * dead.** `claimOrEnqueue` is legitimately called before the run row is committed, so treating a
+     * missing row as dead would let a fresh claim steal a live run's slot — a correctness bug much
+     * worse than recovering a crashed worker's slot slowly.
+     */
+    const holderIsDead = async (tx, tenantId, activeRunId) => {
+        const rows = await tx.query(`SELECT (
+                status IN ('completed', 'failed', 'cancelled')
+                OR (status = 'running' AND lease_expires_at IS NOT NULL AND lease_expires_at <= now())
+              ) AS dead
+         FROM runs
+        WHERE tenant_id = $1 AND id = $2`, [tenantId, activeRunId]);
+        return rows[0]?.dead === true;
+    };
+    return {
+        async claimOrEnqueue({ tenantId, conversationId, runId }) {
+            return runner.transaction(async (tx) => {
+                // An idle conversation still needs a row to lock. Separate from the lock because
+                // `INSERT … ON CONFLICT DO NOTHING` does not lock the conflicting row it declined to touch.
+                await tx.query(`INSERT INTO conversation_run_slots (tenant_id, conversation_id, queued, updated_at)
+           VALUES ($1, $2, '[]'::jsonb, now())
+           ON CONFLICT (tenant_id, conversation_id) DO NOTHING`, [tenantId, conversationId]);
+                const rows = await tx.query(SELECT_SLOT_FOR_UPDATE, [tenantId, conversationId]);
+                const row = rows[0];
+                // Unreachable in practice: the insert above guarantees a row, and the lock is held. Kept
+                // because returning a wrong "started" here would break single-flight silently.
+                if (!row)
+                    throw new Error(`conversation_run_slots row missing for ${conversationId}`);
+                const queue = toQueue(row.queued);
+                const active = row.active_run_id;
+                const free = active === null || active === runId || (await holderIsDead(tx, tenantId, active));
+                if (free) {
+                    // Claiming also drops the run from the backlog: a queued run that gets promoted by its own
+                    // retry must not remain listed behind itself.
+                    const remaining = queue.filter((r) => r !== runId);
+                    await tx.query(WRITE_SLOT, [tenantId, conversationId, runId, JSON.stringify(remaining)]);
+                    return { status: "started", position: 0 };
+                }
+                const next = queue.includes(runId) ? queue : [...queue, runId];
+                if (next !== queue) {
+                    await tx.query(WRITE_SLOT, [tenantId, conversationId, active, JSON.stringify(next)]);
+                }
+                return { status: "queued", position: next.indexOf(runId) + 1 };
+            });
+        },
+        async releaseAndPromote({ tenantId, conversationId, runId }) {
+            return runner.transaction(async (tx) => {
+                const rows = await tx.query(SELECT_SLOT_FOR_UPDATE, [tenantId, conversationId]);
+                const row = rows[0];
+                if (!row)
+                    return null;
+                // A release from a run that does not hold the slot changes nothing — it must not unseat the
+                // holder and must not promote anyone. Matches the reference adapter.
+                if (row.active_run_id !== runId)
+                    return null;
+                const queue = toQueue(row.queued);
+                const promoted = queue.shift() ?? null;
+                // Release and promote in the same statement, inside the same lock: the port's "no
+                // release→dequeue→claim gap" requirement is exactly the window this closes.
+                await tx.query(WRITE_SLOT, [tenantId, conversationId, promoted, JSON.stringify(queue)]);
+                return promoted;
+            });
+        },
+        async active({ tenantId, conversationId }) {
+            const rows = await sql.query(`SELECT active_run_id FROM conversation_run_slots
+          WHERE tenant_id = $1 AND conversation_id = $2`, [tenantId, conversationId]);
+            return (rows[0]?.active_run_id ?? null);
+        },
+        async depth({ tenantId, conversationId }) {
+            // Counted in the database rather than by fetching the array: depth is asked for far more often
+            // than the queue's contents are needed.
+            const rows = await sql.query(`SELECT jsonb_array_length(queued) AS depth FROM conversation_run_slots
+          WHERE tenant_id = $1 AND conversation_id = $2`, [tenantId, conversationId]);
+            const raw = rows[0]?.depth;
+            return raw === undefined ? 0 : Number(raw);
+        },
+    };
+};
+//# sourceMappingURL=run-coordinator.js.map

package/dist/adapters/postgres/run-event-log.d.ts

@@ -0,0 +1,26 @@
+/**
+ * PostgreSQL `RunEventLog` (#94). The durable half of streaming: catch-up after a reconnect reads
+ * this log, and worker crash-recovery reconciles against it (the C1 fix from the REQ-005 review).
+ *
+ * Two decisions carry the design:
+ *
+ *   1. **The caller's `sequence` is stored verbatim.** It is the worker's checkpoint cursor and the
+ *      client's reconnect cursor, so the store must never renumber. The SPEC originally called for
+ *      server-side allocation (`MAX(sequence)+1`), which would have overwritten both.
+ *   2. **`ON CONFLICT DO NOTHING`.** A duplicate sequence is a silent no-op, matching the reference
+ *      adapter — a recovered worker re-emits events, so a retried append is normal rather than
+ *      exceptional. The composite primary key makes the collision impossible; this turns it into the
+ *      idempotent no-op the port promises. The first write wins, so history never mutates under a
+ *      client that already read it.
+ *
+ * `append` takes whatever executor it is handed, so a transaction-scoped executor puts the write
+ * inside that transaction — which is what lets `emit()` keep writing the event *before* the
+ * checkpoint, atomically, without this store knowing about transactions at all.
+ */
+import type { RunEventLog } from "../../core/events.js";
+import type { RunId, TenantId } from "../../core/ids.js";
+import type { SqlExecutor } from "./sql.js";
+export declare const createPostgresRunEventLog: (sql: SqlExecutor) => RunEventLog;
+/** Re-exported for tests that need the row shape without importing the module's internals. */
+export type { RunId, TenantId };
+//# sourceMappingURL=run-event-log.d.ts.map

package/dist/adapters/postgres/run-event-log.js

@@ -0,0 +1,30 @@
+import { parseRunEvent } from "../../core/validation.js";
+/**
+ * Validate on read rather than trusting the column. A corrupt or hand-edited row otherwise flows
+ * straight into a client's event stream, where the failure surfaces far from its cause.
+ */
+const toEvent = (row) => parseRunEvent(typeof row.event === "string" ? JSON.parse(row.event) : row.event);
+export const createPostgresRunEventLog = (sql) => ({
+    async append({ tenantId, event }) {
+        await sql.query(`INSERT INTO run_events (tenant_id, run_id, sequence, type, event)
+       VALUES ($1, $2, $3, $4, $5::jsonb)
+       ON CONFLICT (tenant_id, run_id, sequence) DO NOTHING`, [tenantId, event.runId, event.sequence, event.type, JSON.stringify(event)]);
+    },
+    async listAfter({ tenantId, runId, after, limit }) {
+        // `sequence > $3 ORDER BY sequence` is a forward range scan on the primary key — the whole point
+        // of keying on (tenant_id, run_id, sequence) rather than a surrogate id.
+        const rows = await sql.query(`SELECT event FROM run_events
+        WHERE tenant_id = $1 AND run_id = $2 AND sequence > $3
+        ORDER BY sequence
+        ${limit === undefined ? "" : "LIMIT $4"}`, limit === undefined ? [tenantId, runId, after] : [tenantId, runId, after, limit]);
+        return rows.map(toEvent);
+    },
+    async latestSequence({ tenantId, runId }) {
+        // COALESCE, not an empty-result branch: a run with no events has head 0, which is the cursor a
+        // fresh client sends. Recovery compares against this to decide what the checkpoint missed.
+        const rows = await sql.query(`SELECT COALESCE(MAX(sequence), 0) AS head FROM run_events WHERE tenant_id = $1 AND run_id = $2`, [tenantId, runId]);
+        const head = rows[0]?.head ?? 0;
+        return typeof head === "number" ? head : Number(head);
+    },
+});
+//# sourceMappingURL=run-event-log.js.map

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

@@ -0,0 +1,4 @@
+import type { RunStore } from "../../persistence/index.js";
+import type { SqlExecutor } from "./sql.js";
+export declare const createPostgresRunStore: (sql: SqlExecutor) => RunStore;
+//# sourceMappingURL=run-store.d.ts.map