@rikalabs/akter 0.1.0-alpha.0

package/dist/runtime/turn/execute.js

@@ -0,0 +1,972 @@
+import { Cause, Clock, Crypto, Effect, Exit, Option, Predicate, Result, Schema, Scope, } from "effect";
+import { SqlClient, SqlError } from "effect/sql";
+import { ActorError, CommandExpired, NotCreated, Unauthorized } from "../../errors/actor.js";
+import {} from "../members.js";
+import { Outcome } from "../request.js";
+import { callerKey, System } from "../../identity/caller.js";
+import { commandTimes } from "../../identity/command.js";
+import { isMintedId, provesMint } from "../../identity/mint.js";
+import { parseChildId } from "../../identity/child.js";
+import { writeTicks } from "../cron/schedule.js";
+import { eventsStatement, notifyEvents } from "../events/append.js";
+import { COMMIT_VERSION } from "../database/replica.js";
+import { isPoolRefusal } from "../database/bounded.js";
+import { NekiTurnSessions } from "../database/neki/session.js";
+import { compress, decompress } from "../storage/codec.js";
+import { Metrics, record } from "../telemetry/metrics.js";
+import { SpanNames } from "../telemetry/spans.js";
+import { receiptMarginMs } from "../storage/retention.js";
+import { hashedPayload } from "../subscriptions/identity.js";
+import { tenantSettings, TenantScope } from "../database/tenancy.js";
+import { actorRow as rowOf, forget } from "../storage/generation.js";
+import { checkIdentity, databaseTime, FrameworkClock } from "./admission.js";
+import { abortedBefore, errorOf, Shared, TurnGroups, Unseated } from "./group.js";
+import { RetryTurn, TurnHooks } from "./hooks.js";
+import { OutboxRuntime, outboxStatements } from "./outbox.js";
+import { asSqlConnection, awaitReplies, queueStatements, sendPipelined, sendSequentially, TurnConnections, } from "./pipeline.js";
+import { MERGE_CAP, merges } from "../entity/mailbox.js";
+import { checkReceipt, encodeOutcome, hashCanonical } from "./receipt.js";
+const isSystem = Schema.is(System);
+/**
+ * The cursor row once `delivery` applied, as its commit writes it: a routed
+ * delivery creates the epoch-0 row or raises its position, a dynamic one moves
+ * the row of its own epoch, and a rejection deactivates that row.
+ */
+const applied = (delivery, cursor) => {
+    const epoch = cursor.sub_epoch ?? null;
+    if (delivery.kind === "rejected")
+        return epoch === delivery.epoch ? { ...cursor, sub_active: false } : cursor;
+    if (delivery.epoch === "0") {
+        if (epoch === null)
+            return { sub_epoch: "0", sub_active: true, sub_applied: delivery.position };
+        if (epoch !== "0")
+            return cursor;
+        const position = BigInt(cursor.sub_applied) >= BigInt(delivery.position)
+            ? cursor.sub_applied
+            : delivery.position;
+        return { ...cursor, sub_applied: position };
+    }
+    return epoch === delivery.epoch ? { ...cursor, sub_applied: delivery.position } : cursor;
+};
+/**
+ * How the subscriber's cursor row settles a subscription delivery before its
+ * handler runs: undefined runs the handler. A row of a newer epoch makes the
+ * delivery stale, an inactive row at its epoch means it was unsubscribed, and
+ * a position at or below `applied` was already applied. A dynamic
+ * subscription always has a row, so only a routed one (epoch 0) creates it.
+ */
+const acknowledgement = (delivery, admission) => {
+    const epoch = BigInt(delivery.epoch);
+    if (admission.sub_epoch == null)
+        return epoch > 0n ? "Stale" : undefined;
+    const stored = BigInt(admission.sub_epoch);
+    if (stored !== epoch)
+        return "Stale";
+    if (admission.sub_active !== true)
+        return "Unsubscribed";
+    if (delivery.kind === "rejected")
+        return undefined;
+    return BigInt(admission.sub_applied) >= BigInt(delivery.position) ? "AlreadyApplied" : undefined;
+};
+/** The first cron ticks a newly created actor stages, read against the database clock. */
+const cronTicks = Effect.fnUntraced(function* (routingKey, ref, cron) {
+    const now = yield* databaseTime;
+    const services = yield* Effect.context();
+    return [writeTicks(routingKey, ref, cron, now).pipe(Effect.provideContext(services))];
+});
+/**
+ * True when `request` is a minted actor's creating intent: its caller carries
+ * the parent's mint proof for the actor's id, and its delivery carries the
+ * sender of the committed outbox row the relay claimed. The trusted relay
+ * copies the request from that row, and external admission refuses this
+ * provenance. The child's transaction needs no read on the parent's shard.
+ */
+const committedMintIntent = Effect.fnUntraced(function* (request, parent) {
+    const { caller, ref, intent } = request;
+    if (request.external === true ||
+        intent === undefined ||
+        !isSystem(caller) ||
+        caller.ref === undefined ||
+        intent.tenant !== ref.tenant ||
+        intent.tenant !== caller.ref.tenant ||
+        intent.actor !== caller.ref.actor ||
+        intent.id !== caller.ref.id)
+        return false;
+    return yield* provesMint(caller, ref, parent);
+});
+const nothingWritten = { receipts: 0, events: 0, intents: 0, jobs: 0 };
+const nothingWrote = { state: false, events: [], tables: [], blobs: [] };
+class RolledBack {
+    plan;
+    constructor(plan) {
+        this.plan = plan;
+    }
+}
+const HANDLER_SAVEPOINT = "durable_handler";
+/**
+ * Commands already waiting for one actor, run in delivery order in one
+ * framework transaction sent as two groups. The admission group opens the
+ * transaction, takes the generation fence, resolves every command's receipt
+ * under it, and on a cold activation acquires the next generation and reads
+ * state. The handlers run in memory once those replies arrive, each on the
+ * state the previous one left. The commit group writes the dirty state, each
+ * command's events and outbox rows, the creation marker, and every receipt,
+ * then commits. A lone command is a batch of one.
+ *
+ * Each command keeps its own outcome: a declared failure discards only its
+ * own staged work, and an admission error (expiry, `NotCreated`, a receipt
+ * conflict) answers only that command. A stale fence or any defect fails the
+ * whole batch and writes nothing. A batch with nothing to commit rolls back.
+ * Every command id in a batch must be distinct.
+ *
+ * `statements` marks an actor whose handler can issue SQL; only its handlers
+ * run under a savepoint, so a declared failure discards the handler's rows.
+ * The first handler's savepoint goes out with admission and each later one's
+ * with that handler's first statement. A handler that issued no statement has
+ * nothing to roll back, so its unsent savepoint is dropped. Rolling back to a
+ * savepoint keeps it, so each failed handler leaves one open until commit; a
+ * batch never holds more savepoints than its command cap. `parent` is a
+ * parent-placed actor's parent type, whose turns alone mint it, and `waited`
+ * holds the event tags workflows wait on.
+ *
+ * Admission statements take no parameter from another's reply, so they share
+ * one flight. The generation insert precedes the fenced read, so a brand-new
+ * actor's receipts resolve under the generation row lock. The timeout
+ * `set_config` runs before that insert, so `lock_timeout` bounds the insert's
+ * row waits but not the table lock taken as the statement starts;
+ * `statement_timeout` applies from the next statement. With row-level
+ * security the same statement takes the tenant role, which binds every later
+ * statement of the turn, the handler's included, to the actor's tenant at no
+ * extra round trip. A subscription delivery's cursor row is read in the
+ * fenced statement, and the delivery's canonical payload, not the event's
+ * bytes, binds its identity. When another runner advanced the generation
+ * since this activation acquired it, its cached state may be stale, so
+ * nothing runs, the activation drops its cache, and the retry reloads under a
+ * new generation.
+ *
+ * Admission checks. The generation row is locked in a materialized input
+ * before the read evaluates its clock, so time spent waiting for the fence
+ * cannot admit an identity that expired meanwhile. External ids are validated
+ * against the fenced read's clock before their receipt is released or a handler
+ * runs. An owner reports
+ * that admission on a retryable failure, so only a previously admitted
+ * redelivery can run past expiry, and not once retention could have pruned
+ * its receipt. No pre-delivery receipt read is needed. Only the relay's subscription
+ * deliveries reach a handler, and only a handler takes one, so no caller
+ * reaches it around the cursor or route. A routed event for a subscriber its
+ * creating command has not created is skipped, and its cursor keeps a stale
+ * redelivery from running after another command creates the subscriber. A
+ * minted actor is created only by the relay delivering the creating intent
+ * its parent's turn staged and committed: the mint proof binds the id to the
+ * parent's command, and the relay's claimed-row provenance proves that
+ * command committed the intent without reading another actor's shard.
+ *
+ * Handlers and commit. Calls of a commutative reducer already waiting right
+ * behind a command merge into its turn: their inputs are combined and reduced
+ * once. A complete result lists every key it keeps, and any other key it was
+ * given is deleted. A delivery's cursor position is applied with its receipt,
+ * declared failures included. Re-arming waiting workflows reads their steps,
+ * so it runs before the commit group and only an actor with a workflow
+ * waiting on an emitted class pays for it. A cold activation that replays or
+ * acknowledges still commits and keeps the generation it acquired, so work
+ * the replay wakes runs under it. The first batch a generation commits
+ * schedules every cron entry not yet ticking from the database clock after
+ * its handlers ran, so a first tick is never due before the batch that
+ * writes it. A batch's work is bounded like a lone turn's: interruption and
+ * the command timeout roll it back, and SQL failures are defects. A failed or
+ * unknown commit leaves nothing the cached state can be trusted for, so it
+ * clears the cache.
+ *
+ * On Postgres a run uses one leased session. Each admission group opens with
+ * `BEGIN`, and each commit group ends with `COMMIT`, whose command tag must
+ * be `COMMIT`, since Postgres answers `COMMIT` in an aborted transaction with
+ * `ROLLBACK`. While batch N commits, the next batch already waiting sends its
+ * `BEGIN` and admission group in the same flight, right behind N's `COMMIT`:
+ * the server runs them strictly after it, as a new transaction on the same
+ * session. That admission is built as if N commits, which its fence proves. A
+ * batch that leaves the cache cold is committed alone, so the next one
+ * prepares, which may acquire the generation itself, before its admission
+ * locks the generation row. So is a batch whose publication may wait for that
+ * lock in another transaction: an admission already behind its `COMMIT` would
+ * hold the lock until the publication it waits on ends, and neither would
+ * ever finish. N's callers are answered once its `COMMIT` reply
+ * arrives, and the next batch's handlers run only once its own fence and
+ * receipt replies arrive. If N's commit fails, the next batch's transaction
+ * is rolled back unseen with it. The commit version is read on the same
+ * session after the transaction ends, in the same flight, so it covers the
+ * batch's commit record and any receipt it replayed. The same statement reads
+ * a fresh clock after the transaction ended for the external expiry recheck,
+ * never reusing admission time.
+ *
+ * The session is unsafe from the moment a `BEGIN` may be queued until a
+ * transaction-ending reply with nothing queued behind it. Any other exit
+ * rolls back, and a session whose transaction state is unknown never goes
+ * back to the pool: an interrupted batch cancels its backend's statement and
+ * discards the session, so an unsent `COMMIT` rolls back with it and one
+ * already sent resolves through the receipt on retry. Deferred statements go
+ * out in the same flight as the next statement a handler sends, or at the
+ * head of the commit group.
+ */
+export const executeBatches = Effect.fnUntraced(function* (run, cache, routingKey, policy, mintable, parent, statements, waited = new Set(), connections, cron = [], accounting) {
+    const sql = yield* SqlClient.SqlClient;
+    const hooks = yield* TurnHooks;
+    const clock = yield* FrameworkClock;
+    const scope = yield* TenantScope;
+    const { ref } = run.first[0].request;
+    const { tenant, actor, id } = ref;
+    const role = scope.role ?? (scope.adoption?.enforced.has(actor) === true ? scope.adoption.role : undefined);
+    const actorRow = rowOf({ sql, actor: { key: routingKey, ref } });
+    const canonicalsOf = (batch) => Effect.forEach(batch, ({ request }) => hashedPayload(request));
+    const cursorOf = (delivery) => sql `${actorRow} AND subscription = ${delivery.subscription}
+      AND source_type = ${delivery.sourceType} AND source_id = ${delivery.sourceId}`;
+    const applyCursor = (delivery) => Effect.asVoid(sql `INSERT INTO actor_subscription_cursors (routing_key, tenant_id, actor_type, actor_id,
+        subscription, source_type, source_id, epoch, active, applied)
+      VALUES (${routingKey}, ${tenant}, ${actor}, ${id}, ${delivery.subscription},
+        ${delivery.sourceType}, ${delivery.sourceId}, 0, true, ${delivery.position})
+      ON CONFLICT (routing_key, tenant_id, actor_type, actor_id, subscription, source_type, source_id)
+      DO UPDATE SET applied = greatest(actor_subscription_cursors.applied, EXCLUDED.applied)
+      WHERE actor_subscription_cursors.epoch = 0`);
+    const timeouts = sql `set_config('lock_timeout', ${`${policy.lockWaitMs}ms`}, true),
+      set_config('statement_timeout', ${`${policy.executionMs}ms`}, true),
+      set_config('durable.turn', 'on', true)
+      ${role === undefined ? sql.literal("") : sql `, ${tenantSettings({ sql, role, tenant })}`}`;
+    /**
+     * Turns that set the same transaction settings, which a group sets once for
+     * all of them. Each part is encoded so no two settings share a key.
+     */
+    const groupKey = [
+        policy.lockWaitMs,
+        policy.executionMs,
+        role === undefined ? "-" : `+${encodeURIComponent(role)}`,
+        role === undefined ? "-" : `+${encodeURIComponent(tenant)}`,
+    ].join(":");
+    const admit = (batch, canonicals, view, session, begin, grouped = false) => {
+        const cold = view.generation === undefined;
+        const readsState = cold || view.state === undefined;
+        let admissions = [];
+        let bumped;
+        let stored = [];
+        const subscribed = batch.some(({ request }) => request.delivery !== undefined);
+        const commands = sql.csv(batch.map(({ request: { commandId, delivery } }, index) => subscribed
+            ? sql `(${index}::integer, ${commandId}::text, ${canonicals[index]}::text,
+              ${delivery?.subscription ?? null}::text, ${delivery?.sourceType ?? null}::text,
+              ${delivery?.sourceId ?? null}::text)`
+            : sql `(${index}::integer, ${commandId}::text, ${canonicals[index]}::text)`));
+        const cursorColumns = subscribed
+            ? sql `, s.epoch::text AS sub_epoch, s.active AS sub_active, s.applied::text AS sub_applied`
+            : sql.literal("");
+        const values = subscribed
+            ? sql `(VALUES ${commands}) AS c (ordinal, command_id, payload, subscription, source_type, source_id)`
+            : sql `(VALUES ${commands}) AS c (ordinal, command_id, payload)`;
+        const cursorJoin = subscribed
+            ? sql `LEFT JOIN actor_subscription_cursors s ON s.routing_key = g.routing_key
+          AND s.tenant_id = g.tenant_id AND s.actor_type = g.actor_type AND s.actor_id = g.actor_id
+          AND s.subscription = c.subscription AND s.source_type = c.source_type
+          AND s.source_id = c.source_id`
+            : sql.literal("");
+        const group = [
+            ...begin,
+            ...(grouped
+                ? []
+                : [
+                    cold
+                        ? Effect.asVoid(sql `INSERT INTO actor_generations (routing_key, tenant_id, actor_type, actor_id)
+                  SELECT ${routingKey}, ${tenant}, ${actor}, ${id}
+                  FROM (SELECT ${timeouts}) AS timeouts
+                  ON CONFLICT DO NOTHING`)
+                        : Effect.asVoid(sql `SELECT ${timeouts}`),
+                ]),
+            Effect.map(sql `
+          WITH locked AS MATERIALIZED (
+            SELECT g.routing_key, g.tenant_id, g.actor_type, g.actor_id,
+              g.generation, g.created, g.event_sequence
+            FROM actor_generations g
+            WHERE ${rowOf({ sql, actor: { key: routingKey, ref }, alias: "g" })}
+            FOR UPDATE OF g ${grouped ? sql.literal("SKIP LOCKED") : sql.literal("")}
+          )
+          SELECT floor(extract(epoch FROM clock_timestamp()) * 1000)::text AS now,
+            g.generation::text AS generation, g.created,
+            c.payload::jsonb::text AS canonical,
+            r.caller_key, r.command, r.payload_hash, r.outcome, g.event_sequence::text AS head
+            ${cursorColumns}
+          FROM locked g
+          CROSS JOIN ${values}
+          LEFT JOIN actor_receipts r ON r.routing_key = g.routing_key AND r.tenant_id = g.tenant_id
+            AND r.actor_type = g.actor_type AND r.actor_id = g.actor_id AND r.command_id = c.command_id
+          ${cursorJoin}
+          ORDER BY c.ordinal`, (rows) => {
+                admissions = rows;
+            }),
+            ...(cold
+                ? [
+                    Effect.map(sql `
+                UPDATE actor_generations SET generation = generation + 1 WHERE ${actorRow}
+                RETURNING generation::text AS generation`, (rows) => {
+                        bumped = rows[0]?.generation;
+                    }),
+                ]
+                : []),
+            ...(readsState
+                ? [
+                    Effect.map(sql `
+                SELECT key, value FROM actor_state WHERE ${actorRow}`, (rows) => {
+                        stored = rows;
+                    }),
+                ]
+                : []),
+            ...(statements ? [session.control(`SAVEPOINT ${HANDLER_SAVEPOINT}`)] : []),
+        ];
+        const resume = Effect.fnUntraced(function* () {
+            const first = admissions[0];
+            if (first === undefined && grouped)
+                return yield* Effect.die(new Unseated());
+            if (first === undefined || (!cold && view.generation !== first.generation)) {
+                forget(cache);
+                return yield* Effect.die(RetryTurn.make({ message: "Stale actor generation" }));
+            }
+            const current = cold ? bumped : first.generation;
+            const now = Number(first.now) + clock.offsetMillis();
+            const { retryWindowMs } = yield* OutboxRuntime;
+            const expiryMarginMs = receiptMarginMs({
+                keepReceiptsMs: policy.keepReceiptsMs,
+                deliveryMs: policy.deliveryMs,
+                retryWindowMs,
+            });
+            const ticks = !cold || cron.length === 0 ? Effect.succeed([]) : cronTicks(routingKey, ref, cron);
+            const settled = Array.from({ length: batch.length });
+            let next;
+            const dirty = new Map();
+            const removed = new Set();
+            const staged = [];
+            const receipts = [];
+            let created = first.created;
+            let creates = false;
+            let replayed = false;
+            let wake = false;
+            const broadcasts = [];
+            let events = 0;
+            let intents = 0;
+            let jobs = 0;
+            const eventTags = new Set();
+            const tables = new Set();
+            const blobs = new Set();
+            const replays = new Set();
+            const committed = [];
+            const emitted = [];
+            const cursors = new Map();
+            const cursorKey = (delivery) => JSON.stringify([delivery.subscription, delivery.sourceType, delivery.sourceId]);
+            const cursorAt = (index, delivery) => cursors.get(cursorKey(delivery)) ?? admissions[index];
+            const apply = (index, delivery) => cursors.set(cursorKey(delivery), applied(delivery, cursorAt(index, delivery)));
+            const outboxes = [];
+            /**
+             * Admits one command of the batch once its payload hash is known: settles
+             * a replay, an expiry, or a refusal and yields nothing, or yields the
+             * hash its receipt records. A plain function rather than a generator,
+             * because a generator built for every turn is compiled again and again as
+             * the engine sees new copies of it.
+             */
+            const admitHashed = (index, hash) => {
+                const { request, command } = batch[index];
+                const admitted = admissions[index];
+                if (admitted.outcome !== null)
+                    return Effect.map(checkReceipt(request, hash, admitted).pipe(Effect.result), (replay) => {
+                        if (Result.isSuccess(replay)) {
+                            replayed = true;
+                            replays.add(index);
+                        }
+                        settled[index] = replay;
+                        return undefined;
+                    });
+                if (request.external === true &&
+                    Number(admitted.now) + (request.clockOffset ?? clock.offsetMillis()) >=
+                        commandTimes(request.commandId).expiresAt + expiryMarginMs) {
+                    settled[index] = Result.fail(ActorError.make({ reason: CommandExpired.make({ commandId: request.commandId }) }));
+                    return Effect.undefined;
+                }
+                if (command.internal && !isSystem(request.caller))
+                    return Effect.die(new Error("Internal commands require a System caller"));
+                const { delivery } = request;
+                const acknowledge = (reason) => {
+                    replayed = true;
+                    settled[index] = Result.succeed(Outcome.cases.Acknowledged.make({ reason }));
+                };
+                if (command.handler || delivery !== undefined) {
+                    const caller = request.caller;
+                    if (!command.handler ||
+                        delivery === undefined ||
+                        !isSystem(caller) ||
+                        caller.source !== "subscription" ||
+                        caller.ref?.actor !== delivery.sourceType ||
+                        caller.ref.id !== delivery.sourceId)
+                        return Effect.die(new Error("Subscription handlers accept only subscription deliveries"));
+                    if (caller.ref.tenant !== tenant)
+                        return Effect.die(new Error("A subscription delivery crosses tenants"));
+                    const reason = acknowledgement(delivery, cursorAt(index, delivery));
+                    if (reason !== undefined) {
+                        acknowledge(reason);
+                        return Effect.undefined;
+                    }
+                }
+                if (policy.createdBy !== undefined && !created && policy.createdBy !== request.command) {
+                    if (delivery !== undefined && delivery.epoch === "0" && delivery.kind === "event") {
+                        staged.push(applyCursor(delivery));
+                        apply(index, delivery);
+                        acknowledge("NotCreated");
+                        return Effect.undefined;
+                    }
+                    settled[index] = Result.fail(ActorError.make({ reason: NotCreated.make({}) }));
+                    return Effect.undefined;
+                }
+                if (!mintable ||
+                    policy.createdBy !== request.command ||
+                    created ||
+                    !isMintedId(parent === undefined ? id : (parseChildId(id)?.local ?? "")))
+                    return Effect.succeed(hash);
+                const refuse = () => {
+                    settled[index] = Result.fail(ActorError.make({ reason: Unauthorized.make({ code: "access_denied" }) }));
+                    return undefined;
+                };
+                return request.external === true
+                    ? Effect.sync(refuse)
+                    : Effect.map(committedMintIntent(request, parent), (committed) => committed ? hash : refuse());
+            };
+            const admitOne = (index) => {
+                const request = batch[index].request;
+                const identityNow = Number(admissions[index].now) + (request.clockOffset ?? clock.offsetMillis());
+                const hashed = Effect.flatMap(hashCanonical(admissions[index].canonical), (hash) => admitHashed(index, hash));
+                if (request.external !== true)
+                    return hashed;
+                return Effect.flatMap(checkIdentity(request.commandId, retryWindowMs, identityNow).pipe(Effect.result), (identity) => {
+                    if (Result.isFailure(identity) &&
+                        (request.redelivered !== true || !Schema.is(CommandExpired)(identity.failure.reason))) {
+                        settled[index] = Result.fail(identity.failure);
+                        return Effect.undefined;
+                    }
+                    batch[index].admitted = true;
+                    return hashed;
+                });
+            };
+            let index = 0;
+            while (index < batch.length) {
+                const { request, command } = batch[index];
+                const hash = yield* admitOne(index);
+                if (hash === undefined) {
+                    index += 1;
+                    continue;
+                }
+                const start = index;
+                const members = [{ index, request, hash }];
+                index += 1;
+                while (index < batch.length &&
+                    members.length < MERGE_CAP &&
+                    merges({ previous: batch[start], next: batch[index] })) {
+                    const joined = yield* admitOne(index);
+                    if (joined !== undefined)
+                        members.push({ index, request: batch[index].request, hash: joined });
+                    index += 1;
+                }
+                next ??= readsState
+                    ? new Map(stored.map(({ key, value }) => [key, decompress(value)]))
+                    : new Map(view.state);
+                const given = next;
+                const head = String(BigInt(first.head) + BigInt(events));
+                const savepoint = `SAVEPOINT ${HANDLER_SAVEPOINT}`;
+                if (statements && start > 0)
+                    yield* session.defer(savepoint);
+                const business = yield* hooks.at("beforeHandler", request).pipe(Effect.andThen(() => members.length === 1
+                    ? command.run(request, [...given], { head, connections })
+                    : command.merge(members.map((member) => member.request), [...given])), Effect.catchIf(SqlError.isSqlError, Effect.die), Effect.result);
+                const result = Result.isSuccess(business)
+                    ? business.success
+                    : business.failure;
+                if (statements && (start === 0 || !session.withdraw(savepoint)))
+                    yield* session.defer(Result.isSuccess(business)
+                        ? `RELEASE SAVEPOINT ${HANDLER_SAVEPOINT}`
+                        : `ROLLBACK TO SAVEPOINT ${HANDLER_SAVEPOINT}`);
+                const written = new Map(result.state);
+                if (result.complete)
+                    for (const key of given.keys())
+                        if (!written.has(key)) {
+                            given.delete(key);
+                            dirty.delete(key);
+                            removed.add(key);
+                        }
+                for (const [key, value] of written) {
+                    given.set(key, value);
+                    dirty.set(key, value);
+                    removed.delete(key);
+                }
+                if (result.events.length > 0) {
+                    const appended = yield* eventsStatement(request, routingKey, result.events);
+                    staged.push(appended.statement);
+                    committed.push({
+                        after: head,
+                        events: result.events,
+                        commandId: request.commandId,
+                    });
+                    emitted.push(appended.stamp);
+                }
+                events += result.events.length;
+                for (const event of result.events)
+                    eventTags.add(event.tag);
+                for (const table of result.writes?.tables ?? [])
+                    tables.add(table);
+                for (const blob of result.writes?.blobs ?? [])
+                    blobs.add(blob);
+                intents += result.outbox.intents.length;
+                jobs += result.outbox.jobs.length;
+                if (Outcome.guards.Success(result.outcome))
+                    broadcasts.push(...(result.broadcasts ?? []));
+                if (yield* notifyEvents(request, routingKey, result.events, waited))
+                    wake = true;
+                if (Outcome.guards.Success(result.outcome) &&
+                    policy.createdBy === request.command &&
+                    !created) {
+                    created = true;
+                    creates = true;
+                }
+                const outbox = yield* outboxStatements(routingKey, request.ref, result.outbox, Effect.succeed(now), { slackMs: policy.executionMs });
+                staged.push(...outbox.statements);
+                outboxes.push(outbox.replies);
+                const { delivery } = request;
+                if (delivery !== undefined) {
+                    apply(start, delivery);
+                    staged.push(delivery.kind === "rejected"
+                        ? Effect.asVoid(sql `UPDATE actor_subscription_cursors SET active = false
+                  WHERE ${cursorOf(delivery)} AND epoch = ${delivery.epoch}`)
+                        : delivery.epoch === "0"
+                            ? applyCursor(delivery)
+                            : Effect.asVoid(sql `UPDATE actor_subscription_cursors SET applied = ${delivery.position}
+                    WHERE ${cursorOf(delivery)} AND epoch = ${delivery.epoch}`));
+                }
+                const outcome = yield* encodeOutcome(result.outcome).pipe(Effect.orDie);
+                for (const member of members) {
+                    receipts.push({
+                        routing_key: routingKey,
+                        tenant_id: tenant,
+                        actor_type: actor,
+                        actor_id: id,
+                        command_id: member.request.commandId,
+                        command: member.request.command,
+                        payload_hash: member.hash,
+                        caller_key: callerKey(member.request.caller),
+                        outcome,
+                        expires_at_ms: commandTimes(member.request.commandId).expiresAt,
+                    });
+                    yield* hooks.at("beforeCommit", member.request);
+                    settled[member.index] = Result.succeed(result.outcome);
+                }
+            }
+            if (receipts.length === 0 && staged.length === 0 && !(cold && replayed))
+                return {
+                    writes: undefined,
+                    settled,
+                    generation: current,
+                    state: view.state,
+                    wake: false,
+                    broadcasts: [],
+                    head: first.head,
+                    committed: [],
+                    emitted: [],
+                    outbox: [],
+                    replays,
+                    written: nothingWritten,
+                    wrote: nothingWrote,
+                };
+            const writes = [];
+            if (dirty.size > 0)
+                writes.push(Effect.asVoid(sql `INSERT INTO actor_state ${sql.insert([...dirty].map(([key, value]) => ({
+                    routing_key: routingKey,
+                    tenant_id: tenant,
+                    actor_type: actor,
+                    actor_id: id,
+                    key,
+                    value: compress(value),
+                })))}
+        ON CONFLICT (routing_key, tenant_id, actor_type, actor_id, key) DO UPDATE SET value = EXCLUDED.value`));
+            if (removed.size > 0)
+                writes.push(Effect.asVoid(sql `DELETE FROM actor_state WHERE ${actorRow} AND key IN ${sql.in([...removed])}`));
+            writes.push(...staged);
+            if (creates)
+                writes.push(Effect.asVoid(sql `UPDATE actor_generations SET created = true WHERE ${actorRow}`));
+            if (receipts.length > 0) {
+                writes.push(Effect.asVoid(sql `INSERT INTO actor_receipts ${sql.insert(receipts)}`));
+                if (accounting !== undefined)
+                    writes.push(accounting.commands({
+                        ref,
+                        commandIds: receipts.map((receipt) => receipt.command_id),
+                        sql,
+                    }));
+            }
+            writes.push(...(yield* ticks));
+            return {
+                writes,
+                settled,
+                generation: current,
+                state: next,
+                wake,
+                broadcasts,
+                head: String(BigInt(first.head) + BigInt(events)),
+                committed,
+                emitted,
+                outbox: outboxes,
+                replays,
+                written: { receipts: receipts.length, events, intents, jobs },
+                wrote: {
+                    state: dirty.size > 0 || removed.size > 0,
+                    events: [...eventTags],
+                    tables: [...tables],
+                    blobs: [...blobs],
+                },
+            };
+        });
+        return { group, resume };
+    };
+    const bounded = (effect) => effect.pipe(Effect.interruptible, Effect.timeoutOrElse({
+        duration: policy.executionMs,
+        orElse: () => Effect.die(RetryTurn.make({ message: "Command execution timeout" })),
+    }), Effect.catchIf(SqlError.isSqlError, Effect.die));
+    const view = () => ({ generation: cache.generation, state: cache.state });
+    let current = run.first;
+    let orphan;
+    let answering = false;
+    let poolRefused = false;
+    const locate = (batch, following) => {
+        current = batch;
+        orphan = following;
+    };
+    /**
+     * Remembers what a commit proved and hands the ended batch to the
+     * activation, which publishes it. Only a commit replaces the cache.
+     */
+    const finish = (batch, plan, version, endedAtMs) => Effect.suspend(() => {
+        if (plan.writes !== undefined) {
+            cache.generation = plan.generation;
+            cache.state = plan.state;
+        }
+        answering = true;
+        return run.committed(batch, {
+            settled: plan.settled,
+            broadcasts: plan.broadcasts,
+            head: plan.head,
+            committed: plan.committed.map((entry, index) => ({
+                ...entry,
+                emittedAtMs: plan.emitted[index].emittedAtMs,
+            })),
+            cancelledJobs: plan.outbox.flatMap((replies) => replies.cancelledIds),
+            generation: plan.generation,
+            replays: plan.replays,
+            written: plan.writes === undefined ? nothingWritten : plan.written,
+            version,
+            endedAtMs,
+            wrote: plan.writes === undefined ? nothingWrote : plan.wrote,
+            wake: plan.wake ||
+                plan.outbox.some((replies) => replies.wake) ||
+                plan.emitted.some((stamp) => stamp.fed),
+            cancelled: plan.outbox.some((replies) => replies.cancelled),
+        });
+    }).pipe(Effect.andThen(Effect.sync(() => {
+        answering = false;
+    })));
+    /**
+     * The one batch lifecycle both backends share. Each batch is located, so a
+     * failure names it and any batch admitted behind it, and prepared before its
+     * handlers can run; one whose admission is not yet under way is opened;
+     * `transact` ends its transaction; and the ended batch is finished within its
+     * own span before the next is taken. The next batch is the one `transact`
+     * took while committing, whose admission may already ride behind this
+     * `COMMIT`, else whatever is waiting once this batch was answered.
+     * Opening stays lazy because preparation may acquire a generation and fill
+     * the cache whose view admission uses.
+     */
+    const drive = (open, transact) => {
+        const step = (admitting, pending) => {
+            locate(admitting, undefined);
+            return run.prepare.pipe(Effect.andThen(() => (pending === undefined ? open(admitting) : Effect.succeed(pending))), Effect.flatMap((admitted) => transact(admitting, admitted).pipe(Effect.tap((ended) => finish(admitting, ended.plan, ended.version, ended.endedAtMs)), run.observe(admitting))), Effect.flatMap((ended) => ended.following === undefined
+                ? Effect.flatMap(run.next, (next) => next === undefined ? Effect.void : step(next, ended.chained))
+                : step(ended.following, ended.chained)));
+        };
+        return Effect.suspend(() => step(run.first, undefined));
+    };
+    /**
+     * Postgres: a leased session per chain of batches. A batch is opened by
+     * queuing `BEGIN` and its admission group; `transact` waits for those
+     * replies, runs the handlers, takes the batch already waiting and, when this
+     * one leaves the cache warm, queues that batch's `BEGIN` and admission right
+     * behind this `COMMIT` in the same flight. The commit tag and version are read
+     * in that flight too.
+     *
+     * A batch that chains nothing ends with every reply in and no transaction
+     * open, so the session goes back to the pool before its callers are
+     * answered; publishing never holds a session another turn waits for. A batch
+     * that arrives later leases a session again.
+     */
+    const pipelined = (turns) => Effect.scoped(Effect.gen(function* () {
+        const scope = yield* Effect.scope;
+        let lease;
+        const leased = Effect.suspend(() => {
+            if (lease !== undefined)
+                return Effect.void;
+            return Effect.gen(function* () {
+                const held = yield* Scope.fork(scope);
+                const leasing = yield* Clock.currentTimeMillis;
+                const connection = yield* Scope.provide(turns.lease, held).pipe(Effect.tapError((error) => Effect.sync(() => {
+                    poolRefused = isPoolRefusal(error);
+                })), Effect.onError((cause) => Scope.close(held, Exit.failCause(cause))));
+                yield* record(Metrics.poolWait, {}, (yield* Clock.currentTimeMillis) - leasing);
+                lease = { connection, scope: held };
+            });
+        });
+        const release = Effect.suspend(() => {
+            const held = lease;
+            lease = undefined;
+            return held === undefined ? Effect.void : Scope.close(held.scope, Exit.void);
+        });
+        const session = () => lease.connection;
+        let open = false;
+        const deferred = [];
+        const control = (text) => session().query(text, [], true);
+        const flush = () => deferred.splice(0).map((text) => Effect.asVoid(control(text)));
+        const send = (statement) => Effect.suspend(() => {
+            if (deferred.length === 0)
+                return statement;
+            let reply;
+            return sendPipelined([
+                ...flush(),
+                Effect.map(statement, (value) => {
+                    reply = { value };
+                }),
+            ]).pipe(Effect.map(() => reply.value));
+        });
+        const pipeline = {
+            send: sendPipelined,
+            control: (text) => Effect.asVoid(control(text)),
+            defer: (text) => Effect.sync(() => {
+                deferred.push(text);
+            }),
+            withdraw: (text) => deferred.at(-1) === text && deferred.pop() !== undefined,
+        };
+        const begin = Effect.suspend(() => {
+            open = true;
+            return Effect.asVoid(control("BEGIN"));
+        });
+        const inTurn = (effect) => Effect.suspend(() => Effect.provideService(effect, sql.transactionService, [
+            asSqlConnection({ connection: session(), send }),
+            0,
+        ]));
+        const queue = (batch, view, ahead) => Effect.flatMap(canonicalsOf(batch), (canonicals) => {
+            const admission = admit(batch, canonicals, view, pipeline, [begin]);
+            return Effect.map(queueStatements({ scope, group: [...ahead, ...admission.group] }), (flight) => ({ admission, flight }));
+        });
+        /**
+         * Queues a batch's commit group, and the next batch's admission behind
+         * it when the cache stays warm, then waits for the commit replies.
+         */
+        const commitPlan = (batch, plan, following) => {
+            const ending = plan.writes === undefined ? "ROLLBACK" : "COMMIT";
+            const after = plan.writes === undefined ? view() : { generation: plan.generation, state: plan.state };
+            const chained = following !== undefined &&
+                after.generation !== undefined &&
+                after.state !== undefined &&
+                !run.publishesUnderLock(batch);
+            let tag;
+            let version = "";
+            let endedAtMs = 0;
+            const commit = [
+                ...(plan.writes === undefined ? [] : [...flush(), ...plan.writes]),
+                Effect.map(control(ending), (result) => {
+                    tag = result.command;
+                    if (!chained)
+                        open = false;
+                }),
+                Effect.map(session().query(COMMIT_VERSION, [], true), (result) => {
+                    const ended = result.rows[0];
+                    version = ended.version;
+                    endedAtMs = Number(ended.now);
+                }),
+            ];
+            locate(batch, following);
+            const upcoming = chained
+                ? queue(following, after, commit)
+                : Effect.map(queueStatements({ scope, group: commit }), (flight) => ({
+                    admission: undefined,
+                    flight,
+                }));
+            return Effect.flatMap(upcoming, ({ admission: next, flight }) => {
+                const answered = awaitReplies(flight.slice(0, commit.length));
+                return Effect.map(ending === "COMMIT" ? answered.pipe(Effect.withSpan(SpanNames.commit)) : answered, () => ({
+                    plan,
+                    version,
+                    endedAtMs,
+                    ending,
+                    tag,
+                    following,
+                    chained: next === undefined
+                        ? undefined
+                        : { admission: next, admitted: flight.slice(commit.length) },
+                }));
+            });
+        };
+        const alone = (batch, { admission, admitted }, taken) => awaitReplies(admitted).pipe(Effect.andThen(() => admission.resume()), Effect.flatMap((plan) => Effect.flatMap(taken === undefined ? run.next : Effect.succeed(taken), (following) => commitPlan(batch, plan, following))), inTurn, bounded, Effect.filterOrElse((stepped) => stepped.ending !== "COMMIT" || stepped.tag === "COMMIT", () => Effect.die(RetryTurn.make({ message: "Turn commit rolled back" }))), Effect.tap((stepped) => (stepped.chained === undefined ? release : Effect.void)));
+        const openAlone = (batch) => leased.pipe(Effect.andThen(queue(batch, view(), []).pipe(inTurn)), Effect.map(({ admission, flight }) => ({ admission, admitted: flight })));
+        const onMember = (member) => (effect) => Effect.suspend(() => Effect.provideService(effect, sql.transactionService, [
+            asSqlConnection({ connection: member.connection(), send: member.send }),
+            0,
+        ]));
+        /**
+         * Joins the forming group for this batch's settings with its fenced
+         * admission read alone; the group opens the transaction.
+         */
+        const openGrouped = (batch, joining) => Effect.flatMap(canonicalsOf(batch), (canonicals) => {
+            const admission = admit(batch, canonicals, view(), pipeline, [], true);
+            return joining
+                .join({
+                key: groupKey,
+                settings: (connection) => Effect.provideService(Effect.asVoid(sql `SELECT ${timeouts}`), sql.transactionService, [asSqlConnection({ connection, send: (statement) => statement }), 0]),
+                cancel: (connection) => Effect.ignore(sql `SELECT pg_cancel_backend(${connection.processId})`),
+                admission: (member) => admission.group.map(onMember(member)),
+            })
+                .pipe(Effect.tapError((error) => Effect.sync(() => {
+                poolRefused = isPoolRefusal(error);
+            })), Effect.map((member) => ({ admission, admitted: [], member })));
+        });
+        /**
+         * A grouped batch: its own admission replies, its handlers, and its
+         * writes handed to the group, answered once the group commits. When
+         * the actor's next batch is already waiting and this one leaves the
+         * cache warm, that batch's admission rides behind the group's
+         * `COMMIT` and the batch takes the group's session, as a batch on its
+         * own session would. `ended` is undefined when the batch must run again
+         * alone: the group ended without it, aborted on a neighbour's
+         * statement, skipped its locked generation row, or the batch tried to
+         * send another statement.
+         */
+        const grouped = (batch, admission, member) => {
+            let following;
+            return Effect.gen(function* () {
+                const replies = yield* Effect.exit(awaitReplies(member.replies()));
+                if (Exit.isFailure(replies)) {
+                    yield* member.leave(true);
+                    const error = errorOf(replies);
+                    if (error !== undefined && abortedBefore(error))
+                        return undefined;
+                    return yield* Effect.failCause(replies.cause);
+                }
+                if (!(yield* member.handling))
+                    return undefined;
+                const plan = yield* onMember(member)(admission.resume());
+                following = yield* run.next;
+                locate(batch, following);
+                const after = plan.writes === undefined
+                    ? view()
+                    : { generation: plan.generation, state: plan.state };
+                let next;
+                const handoff = following !== undefined &&
+                    after.generation !== undefined &&
+                    after.state !== undefined &&
+                    !run.publishesUnderLock(batch)
+                    ? yield* Effect.map(canonicalsOf(following), (canonicals) => ({
+                        chain: (connection) => {
+                            const on = (effect) => Effect.provideService(effect, sql.transactionService, [
+                                asSqlConnection({ connection, send }),
+                                0,
+                            ]);
+                            next = admit(following, canonicals, after, pipeline, [
+                                Effect.asVoid(connection.query("BEGIN", [], true)),
+                            ]);
+                            return next.group.map(on);
+                        },
+                        adopt: (connection, held) => Effect.suspend(() => {
+                            if (Predicate.isTagged(scope.state, "Closed"))
+                                return Effect.succeed(false);
+                            lease = { connection, scope: held };
+                            open = true;
+                            return Effect.as(Scope.addFinalizer(scope, Scope.close(held, Exit.void)), true);
+                        }),
+                    }))
+                    : undefined;
+                const writes = (plan.writes ?? []).map(onMember(member));
+                const waiting = member.commit(writes, handoff);
+                const shared = yield* writes.length > 0
+                    ? waiting.pipe(Effect.withSpan(SpanNames.commit))
+                    : waiting;
+                if (Shared.$is("Alone")(shared))
+                    return undefined;
+                return {
+                    plan,
+                    version: shared.version,
+                    endedAtMs: shared.endedAtMs,
+                    following,
+                    chained: shared.chained === undefined || next === undefined
+                        ? undefined
+                        : { admission: next, admitted: [...shared.chained] },
+                };
+            }).pipe(Effect.catchDefect((defect) => defect instanceof Unseated ? Effect.undefined : Effect.die(defect)), Effect.onExit(() => member.leave(false)), bounded, Effect.map((ended) => ({ ended, following })));
+        };
+        const transact = (batch, admitting) => admitting.member === undefined
+            ? alone(batch, admitting)
+            : Effect.flatMap(grouped(batch, admitting.admission, admitting.member), (outcome) => outcome.ended !== undefined
+                ? Effect.succeed(outcome.ended)
+                : Effect.flatMap(openAlone(batch), (opened) => alone(batch, opened, outcome.following)));
+        let first = true;
+        return yield* drive((batch) => {
+            const joining = first && view().generation !== undefined && view().state !== undefined
+                ? groups
+                : undefined;
+            first = false;
+            return joining === undefined ? openAlone(batch) : openGrouped(batch, joining);
+        }, transact).pipe(Effect.onExit((exit) => {
+            if (Exit.isSuccess(exit) || !open)
+                return Effect.void;
+            const connection = session();
+            if (Cause.hasInterrupts(exit.cause))
+                return sql `SELECT pg_cancel_backend(${connection.processId})`.pipe(Effect.ignore, Effect.andThen(turns.invalidate(connection)));
+            return control("ROLLBACK").pipe(Effect.flatMap((result) => result.command === "ROLLBACK" ? Effect.void : turns.invalidate(connection)), Effect.catch(() => turns.invalidate(connection)));
+        }));
+    }));
+    /**
+     * PGlite: one in-process session and nothing to pipeline, so each batch runs
+     * its groups one statement at a time inside `withTransaction`, which holds
+     * the session only for that transaction; a batch with nothing to commit rolls
+     * back. The commit version is read after the transaction ends.
+     */
+    const sequential = drive(() => Effect.void, (batch) => Effect.gen(function* () {
+        const control = (text) => Effect.asVoid(sql.unsafe(text));
+        const session = { send: sendSequentially, control, defer: control, withdraw: () => false };
+        const plan = yield* bounded(sql
+            .withTransaction(Effect.gen(function* () {
+            const admission = admit(batch, yield* canonicalsOf(batch), view(), session, []);
+            yield* sendSequentially(admission.group);
+            const decided = yield* admission.resume();
+            if (decided.writes === undefined)
+                return yield* Effect.fail(new RolledBack(decided));
+            yield* sendSequentially(decided.writes).pipe(Effect.withSpan(SpanNames.commit));
+            return decided;
+        }))
+            .pipe(Effect.catchIf((error) => error instanceof RolledBack, (rolled) => Effect.succeed(rolled.plan))));
+        const [ended] = yield* sql.unsafe(COMMIT_VERSION);
+        return {
+            plan,
+            version: ended.version,
+            endedAtMs: Number(ended.now),
+        };
+    }));
+    const turns = yield* Effect.serviceOption(TurnConnections);
+    const groups = statements || waited.size > 0 || (yield* NekiTurnSessions)
+        ? undefined
+        : Option.getOrUndefined(yield* Effect.serviceOption(TurnGroups));
+    const exit = yield* (Option.isSome(turns) ? pipelined(turns.value) : sequential).pipe(Effect.onError(() => Effect.sync(() => {
+        cache.state = undefined;
+    })), Effect.exit);
+    if (Exit.isSuccess(exit))
+        return undefined;
+    if (Cause.hasInterruptsOnly(exit.cause))
+        return yield* Effect.failCause(exit.cause);
+    return {
+        batch: current,
+        orphan,
+        cause: exit.cause,
+        committed: answering,
+        poolRefused,
+    };
+});