@rikalabs/akter 0.1.0-alpha.0

package/dist/runtime/turn/outbox.d.ts

@@ -0,0 +1,159 @@
+import { Context, Crypto, Effect, Schema } from "effect";
+import { SqlClient, type SqlError, type Statement } from "effect/sql";
+import type { RegisteredSubscription } from "../members.ts";
+import { type StagedOutbox } from "../../handles/intents.ts";
+import { type ActorRef } from "../../identity/caller.ts";
+/**
+ * The due-work bucket: the top eight bits of `routing_key`. Every runner's
+ * relay probes each bucket's `(bucket, kind, due_at_ms)` index range, so actors
+ * with nothing due are never read.
+ */
+export declare const bucketOf: (routingKey: bigint) => number;
+/** The inclusive range of values `bucketOf` returns. */
+export declare const BUCKETS: {
+    readonly first: -128;
+    readonly last: 127;
+};
+/**
+ * Runtime settings a turn needs to write intents: the deployment retry window,
+ * which becomes each intent's receipt horizon past its due time, and the
+ * relay's wake signal.
+ */
+export declare const OutboxRuntime: Context.Reference<{
+    readonly retryWindowMs: number;
+    /** Wakes this runner's relay to claim due rows now instead of at its next poll. */
+    readonly wake: Effect.Effect<void>;
+    /** Makes this runner's running attempts check for cancellation now. */
+    readonly cancelled: Effect.Effect<void>;
+    /**
+     * Routed subscriptions registered on this runner whose source is
+     * `sourceType`, with their subscriber type; a publishing turn inserts their
+     * missing source-side rows.
+     */
+    readonly routed: (sourceType: string) => ReadonlyArray<RegisteredSubscription & {
+        readonly subscriberType: string;
+    }>;
+}>;
+/** A `text[]` expression of `values`, each bound as its own text parameter so every driver binds it alike. */
+export declare const textArray: ({ sql, values, }: {
+    readonly sql: SqlClient.SqlClient;
+    readonly values: ReadonlyArray<string>;
+}) => Statement.Statement<import("effect/sql/SqlConnection").Row>;
+/** Codec between a string array and its JSON text. */
+export declare const StringsJson: Schema.fromJsonString<Schema.$Array<Schema.String>>;
+/** The payload of a `control` row: the registration change a subscribing turn stages for the relay to apply at the source. */
+export declare const ControlPayload: Schema.fromJsonString<Schema.Struct<{
+    readonly op: Schema.Literals<readonly ["subscribe", "remove"]>;
+    readonly epoch: Schema.String;
+    /** Where a subscribe starts: `"now"`, `"start"`, or an exclusive cursor. */
+    readonly start: Schema.String;
+    readonly events: Schema.$Array<Schema.String>;
+}>>;
+/** Codec between a `Caller` and the JSON text stored in an outbox row's `caller` column. */
+export declare const CallerJson: Schema.fromJsonString<Schema.toTaggedUnion<"_tag", readonly [Schema.TaggedStruct<"User", {
+    readonly subject: Schema.NonEmptyString;
+}>, Schema.TaggedStruct<"Anonymous", {}>, Schema.TaggedStruct<"System", {
+    readonly source: Schema.Literals<readonly ["process", "actor", "timer", "cron", "workflow", "job", "subscription"]>;
+    readonly ref: Schema.optional<Schema.Struct<{
+        readonly tenant: Schema.NonEmptyString;
+        readonly actor: Schema.NonEmptyString;
+        readonly id: Schema.NonEmptyString;
+    }>>;
+    readonly onBehalfOf: Schema.optional<Schema.Struct<{
+        readonly subject: Schema.NonEmptyString;
+    }>>;
+    readonly mint: Schema.optional<Schema.Struct<{
+        readonly commandId: Schema.String;
+        readonly ordinal: Schema.Int;
+    }>>;
+}>]>>;
+/** What the relay needs to hear once a turn's outbox writes commit; filled in as the statements reply. */
+export interface OutboxReplies {
+    /** Some row is due now, so the relay should wake. */
+    wake: boolean;
+    /** The turn cancelled a job attempt that is running. */
+    cancelled: boolean;
+    /** Started jobs the turn cancelled; their owner stops showing their progress. */
+    cancelledIds: Array<string>;
+}
+/**
+ * The statements that write one turn's intents, jobs, and subscription
+ * changes inside its transaction, and the job ids of the new job rows in
+ * `outbox.jobs` order. In order they: delete committed rows whose keys the
+ * turn replaced; cancel committed jobs whose keys it cancelled or enqueued
+ * again; insert the staged rows; upsert each subscription's cursor row and
+ * stage its control row; shift delayed rows; order capped jobs. No
+ * statement takes a parameter from another's reply, so they can be sent as one
+ * group; `replies` is complete once every statement has replied.
+ *
+ * `databaseNow` is the time due times are measured from; it is read only when
+ * there are rows to insert. When it was read before the handler ran, `commit`
+ * moves each relative delay to the commit statement's clock by one shift, read
+ * once because `clock_timestamp()` changes while a statement runs, and its
+ * `slackMs` extends the receipt horizon of those rows over the turn's longest
+ * possible run.
+ *
+ * A row's id is the receiver's command id, and its expiry keeps that receipt
+ * at least one retry window past the due time. A job row names its job
+ * in `command` and targets its own actor, where its routes deliver; the relay
+ * runs its executor when it is due.
+ *
+ * A never-claimed cancelled job is deleted; a claim that won the row lock
+ * first makes that delete skip it, and the later update statement then sees it
+ * running. A started job keeps its row as evidence and gives up its key:
+ * one not running is settled by the next claim, a running one by its attempt
+ * or, once its lease ends, by any runner.
+ *
+ * Each subscription change moves the subscriber's cursor row to a new epoch,
+ * kept forever so the epoch never goes back, and stages the control row that
+ * carries that epoch to the source, replacing a pending earlier change for the
+ * same subscription and source. A `"now"` start is set by the source when the registration
+ * reaches it; `"start"` is cursor 0.
+ */
+export declare const outboxStatements: <R>(routingKey: bigint, sender: {
+    readonly tenant: string;
+    readonly actor: string;
+    readonly id: string;
+}, outbox: StagedOutbox, databaseNow: Effect.Effect<number, SqlError.SqlError, R>, commit?: {
+    readonly slackMs: number;
+} | undefined) => Effect.Effect<{
+    statements: Effect.Effect<void, SqlError.SqlError, never>[];
+    replies: OutboxReplies;
+    jobIds: string[];
+}, SqlError.SqlError, R | Crypto.Crypto | SqlClient.SqlClient>;
+/**
+ * Orders a turn's capped jobs behind every earlier job of their type on
+ * this actor that became due no later. Claims take capped rows by
+ * `(ready_at_ms, intent_id)`, but the turn's clock has only millisecond
+ * resolution and is read before the actor's lock is taken, and job ids
+ * end in a random UUID: jobs enqueued in one turn, or in turns that read
+ * the same millisecond, would otherwise run in any order. The actor's lock
+ * serializes its turns, so the rows this statement reads are every earlier
+ * enqueue. It runs after any delay shift, so `scheduled_at_ms` is final.
+ *
+ * Within the turn, an earlier row of one job type that is due at the same
+ * time or no later always ends ahead of the rows after it. The latest
+ * `ready_at_ms` of earlier committed rows is probed twice, over rows not
+ * running and over running rows, each reading one partial index.
+ */
+export declare const orderCapped: ({ sql, routingKey, sender, capped, }: {
+    readonly sql: SqlClient.SqlClient;
+    readonly routingKey: bigint;
+    readonly sender: ActorRef;
+    readonly capped: ReadonlyArray<{
+        readonly id: string;
+        readonly job: string;
+        readonly dueAt: number;
+    }>;
+}) => Effect.Effect<void, SqlError.SqlError, never>;
+/**
+ * Writes one turn's intents and jobs now, reading the database time only
+ * when there are rows to insert. Returns the `OutboxReplies`, so the caller can
+ * wake the relay after commit when a row is due and tell it about cancelled
+ * attempts.
+ */
+export declare const writeOutbox: (routingKey: bigint, sender: {
+    readonly tenant: string;
+    readonly actor: string;
+    readonly id: string;
+}, outbox: StagedOutbox) => Effect.Effect<OutboxReplies, SqlError.SqlError, Crypto.Crypto | SqlClient.SqlClient>;

package/dist/runtime/turn/outbox.js

@@ -0,0 +1,269 @@
+import { Context, Crypto, Effect, Match, Schema } from "effect";
+import { SqlClient } from "effect/sql";
+import { Due, jobKey } from "../../handles/intents.js";
+import { Caller, System } from "../../identity/caller.js";
+import { databaseTime, FrameworkClock } from "./admission.js";
+/**
+ * The due-work bucket: the top eight bits of `routing_key`. Every runner's
+ * relay probes each bucket's `(bucket, kind, due_at_ms)` index range, so actors
+ * with nothing due are never read.
+ */
+export const bucketOf = (routingKey) => Number(routingKey >> 56n);
+/** The inclusive range of values `bucketOf` returns. */
+export const BUCKETS = { first: -128, last: 127 };
+/**
+ * Runtime settings a turn needs to write intents: the deployment retry window,
+ * which becomes each intent's receipt horizon past its due time, and the
+ * relay's wake signal.
+ */
+export const OutboxRuntime = Context.Reference("akter/OutboxRuntime", {
+    defaultValue: () => ({
+        retryWindowMs: 86_400_000,
+        wake: Effect.void,
+        cancelled: Effect.void,
+        routed: () => [],
+    }),
+});
+/** A `text[]` expression of `values`, each bound as its own text parameter so every driver binds it alike. */
+export const textArray = ({ sql, values, }) => sql `ARRAY[${sql.csv(values.map((value) => sql `${value}::text`))}]::text[]`;
+/** Codec between a string array and its JSON text. */
+export const StringsJson = Schema.fromJsonString(Schema.Array(Schema.String));
+/** The payload of a `control` row: the registration change a subscribing turn stages for the relay to apply at the source. */
+export const ControlPayload = Schema.fromJsonString(Schema.Struct({
+    op: Schema.Literals(["subscribe", "remove"]),
+    epoch: Schema.String,
+    /** Where a subscribe starts: `"now"`, `"start"`, or an exclusive cursor. */
+    start: Schema.String,
+    events: Schema.Array(Schema.String),
+}));
+/** The outbox key of a subscription's control row, so a later change replaces a pending one. */
+const controlKey = (change) => JSON.stringify(["$sub", change.subscription, change.source.actor, change.source.id]);
+/** Codec between a `Caller` and the JSON text stored in an outbox row's `caller` column. */
+export const CallerJson = Schema.fromJsonString(Caller);
+/**
+ * The statements that write one turn's intents, jobs, and subscription
+ * changes inside its transaction, and the job ids of the new job rows in
+ * `outbox.jobs` order. In order they: delete committed rows whose keys the
+ * turn replaced; cancel committed jobs whose keys it cancelled or enqueued
+ * again; insert the staged rows; upsert each subscription's cursor row and
+ * stage its control row; shift delayed rows; order capped jobs. No
+ * statement takes a parameter from another's reply, so they can be sent as one
+ * group; `replies` is complete once every statement has replied.
+ *
+ * `databaseNow` is the time due times are measured from; it is read only when
+ * there are rows to insert. When it was read before the handler ran, `commit`
+ * moves each relative delay to the commit statement's clock by one shift, read
+ * once because `clock_timestamp()` changes while a statement runs, and its
+ * `slackMs` extends the receipt horizon of those rows over the turn's longest
+ * possible run.
+ *
+ * A row's id is the receiver's command id, and its expiry keeps that receipt
+ * at least one retry window past the due time. A job row names its job
+ * in `command` and targets its own actor, where its routes deliver; the relay
+ * runs its executor when it is due.
+ *
+ * A never-claimed cancelled job is deleted; a claim that won the row lock
+ * first makes that delete skip it, and the later update statement then sees it
+ * running. A started job keeps its row as evidence and gives up its key:
+ * one not running is settled by the next claim, a running one by its attempt
+ * or, once its lease ends, by any runner.
+ *
+ * Each subscription change moves the subscriber's cursor row to a new epoch,
+ * kept forever so the epoch never goes back, and stages the control row that
+ * carries that epoch to the source, replacing a pending earlier change for the
+ * same subscription and source. A `"now"` start is set by the source when the registration
+ * reaches it; `"start"` is cursor 0.
+ */
+export const outboxStatements = Effect.fnUntraced(function* (routingKey, sender, outbox, databaseNow, commit) {
+    const sql = yield* SqlClient.SqlClient;
+    const clock = yield* FrameworkClock;
+    const { tenant, actor, id } = sender;
+    const statements = [];
+    const replies = { wake: false, cancelled: false, cancelledIds: [] };
+    const actorRow = sql `routing_key = ${routingKey} AND tenant_id = ${tenant}
+    AND actor_type = ${actor} AND actor_id = ${id}`;
+    const statementNow = sql `floor(extract(epoch FROM clock_timestamp()) * 1000)::bigint + ${clock.offsetMillis()}`;
+    if (outbox.replaced.length > 0)
+        statements.push(Effect.asVoid(sql `DELETE FROM actor_outbox WHERE ${actorRow} AND timer_key IN ${sql.in(outbox.replaced)}`));
+    if (outbox.cancelledJobs.length > 0) {
+        const keys = sql.in(outbox.cancelledJobs.map(jobKey));
+        statements.push(Effect.asVoid(sql `DELETE FROM actor_outbox WHERE ${actorRow} AND kind = 'job'
+        AND timer_key IN ${keys} AND attempts = 0 AND NOT running`));
+        statements.push(Effect.map(sql `UPDATE actor_outbox
+          SET cancelled_at_ms = stamp.at, timer_key = NULL, waiting = false,
+            due_at_ms = CASE WHEN running THEN due_at_ms ELSE least(due_at_ms, stamp.at) END
+          FROM (SELECT ${statementNow} AS at) AS stamp
+          WHERE ${actorRow} AND kind = 'job' AND timer_key IN ${keys}
+          RETURNING running, intent_id`, (marked) => {
+            replies.cancelledIds.push(...marked.map((row) => row.intent_id));
+            replies.cancelled ||= marked.some((row) => row.running);
+            replies.wake ||= marked.some((row) => !row.running);
+        }));
+    }
+    if (outbox.intents.length === 0 && outbox.jobs.length === 0 && outbox.subscriptions.length === 0)
+        return { statements, replies, jobIds: [] };
+    const crypto = yield* Crypto.Crypto;
+    const { retryWindowMs } = yield* OutboxRuntime;
+    const now = yield* databaseNow;
+    replies.wake ||= outbox.subscriptions.length > 0;
+    const rows = [];
+    const rowId = (dueAt, slackMs = 0) => crypto.randomUUIDv4.pipe(Effect.orDie, Effect.map((uuid) => `v1.${now}.${Math.max(dueAt, now) + slackMs + retryWindowMs}.${uuid}`));
+    const dueOf = (due) => due === undefined
+        ? now
+        : Due.match(due, {
+            After: ({ millis }) => now + millis,
+            At: ({ epochMillis }) => epochMillis,
+        });
+    const delayed = [];
+    const rowIdOf = Effect.fnUntraced(function* (due, dueAt) {
+        const relative = commit !== undefined && due?._tag === "After";
+        const rowIdentity = yield* rowId(dueAt, relative ? commit.slackMs : 0);
+        if (relative)
+            delayed.push(rowIdentity);
+        return rowIdentity;
+    });
+    for (const intent of outbox.intents) {
+        const dueAt = dueOf(intent.due);
+        replies.wake ||= dueAt <= now;
+        rows.push({
+            routing_key: routingKey,
+            intent_id: yield* rowIdOf(intent.due, dueAt),
+            kind: "intent",
+            bucket: bucketOf(routingKey),
+            due_at_ms: dueAt,
+            scheduled_at_ms: dueAt,
+            ready_at_ms: null,
+            tenant_id: tenant,
+            actor_type: actor,
+            actor_id: id,
+            timer_key: intent.key ?? null,
+            target_type: intent.target.actor,
+            target_id: intent.target.id,
+            command: intent.command,
+            payload: intent.payload,
+            payload_version: 0,
+            caller: yield* Schema.encodeEffect(CallerJson)(intent.caller).pipe(Effect.orDie),
+        });
+    }
+    const capped = [];
+    const jobIds = [];
+    for (const job of outbox.jobs) {
+        const dueAt = dueOf(job.due);
+        const intentId = yield* rowIdOf(job.due, dueAt);
+        replies.wake ||= dueAt <= now;
+        if (job.capped)
+            capped.push({ id: intentId, job: job.job, dueAt });
+        jobIds.push(intentId);
+        rows.push({
+            routing_key: routingKey,
+            intent_id: intentId,
+            kind: "job",
+            bucket: bucketOf(routingKey),
+            due_at_ms: dueAt,
+            scheduled_at_ms: dueAt,
+            ready_at_ms: dueAt,
+            tenant_id: tenant,
+            actor_type: actor,
+            actor_id: id,
+            timer_key: job.key === undefined ? null : jobKey(job.key),
+            target_type: actor,
+            target_id: id,
+            command: job.job,
+            payload: job.payload,
+            payload_version: job.version,
+            caller: yield* Schema.encodeEffect(CallerJson)(job.caller).pipe(Effect.orDie),
+        });
+    }
+    if (rows.length > 0)
+        statements.push(Effect.asVoid(sql `INSERT INTO actor_outbox ${sql.insert(rows)}`));
+    const caller = yield* Schema.encodeEffect(CallerJson)(System.make({ source: "actor", ref: sender })).pipe(Effect.orDie);
+    for (const change of outbox.subscriptions) {
+        const subscribe = change.op === "subscribe";
+        const applied = Match.value(change.from).pipe(Match.when("now", () => "-1"), Match.when("start", () => "0"), Match.orElse((cursor) => cursor));
+        statements.push(Effect.asVoid(sql `WITH cursor AS (
+          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}, ${change.subscription},
+            ${change.source.actor}, ${change.source.id}, 1, ${subscribe}, ${subscribe ? applied : "-1"})
+          ON CONFLICT (routing_key, tenant_id, actor_type, actor_id, subscription, source_type, source_id)
+          DO UPDATE SET epoch = actor_subscription_cursors.epoch + 1, active = EXCLUDED.active,
+            applied = CASE WHEN EXCLUDED.active THEN EXCLUDED.applied
+              ELSE actor_subscription_cursors.applied END
+          RETURNING epoch)
+        INSERT INTO actor_outbox (routing_key, intent_id, kind, bucket, due_at_ms, scheduled_at_ms,
+          tenant_id, actor_type, actor_id, timer_key, target_type, target_id, command, payload, caller)
+        SELECT ${routingKey}, ${yield* rowId(now)}, 'control', ${bucketOf(routingKey)}, ${now}, ${now},
+          ${tenant}, ${actor}, ${id}, ${controlKey(change)}, ${change.source.actor}, ${change.source.id},
+          ${change.subscription},
+          json_build_object('op', ${change.op}::text, 'epoch', cursor.epoch::text,
+            'start', ${change.from}::text, 'events', to_jsonb(${textArray({ sql, values: change.events })}))::text,
+          ${caller}
+        FROM cursor
+        ON CONFLICT (routing_key, tenant_id, actor_type, actor_id, timer_key) WHERE timer_key IS NOT NULL
+        DO UPDATE SET intent_id = EXCLUDED.intent_id, payload = EXCLUDED.payload,
+          due_at_ms = EXCLUDED.due_at_ms, scheduled_at_ms = EXCLUDED.scheduled_at_ms,
+          attempts = 0, last_error = NULL`));
+    }
+    if (delayed.length > 0)
+        statements.push(Effect.asVoid(sql `UPDATE actor_outbox
+        SET due_at_ms = due_at_ms + moved.shift, scheduled_at_ms = scheduled_at_ms + moved.shift,
+          ready_at_ms = ready_at_ms + moved.shift
+        FROM (SELECT ${statementNow} - ${now} AS shift) AS moved
+        WHERE routing_key = ${routingKey} AND intent_id IN ${sql.in(delayed)}`));
+    if (capped.length > 0)
+        statements.push(orderCapped({ sql, routingKey, sender, capped }));
+    return { statements, replies, jobIds };
+});
+/**
+ * Orders a turn's capped jobs behind every earlier job of their type on
+ * this actor that became due no later. Claims take capped rows by
+ * `(ready_at_ms, intent_id)`, but the turn's clock has only millisecond
+ * resolution and is read before the actor's lock is taken, and job ids
+ * end in a random UUID: jobs enqueued in one turn, or in turns that read
+ * the same millisecond, would otherwise run in any order. The actor's lock
+ * serializes its turns, so the rows this statement reads are every earlier
+ * enqueue. It runs after any delay shift, so `scheduled_at_ms` is final.
+ *
+ * Within the turn, an earlier row of one job type that is due at the same
+ * time or no later always ends ahead of the rows after it. The latest
+ * `ready_at_ms` of earlier committed rows is probed twice, over rows not
+ * running and over running rows, each reading one partial index.
+ */
+export const orderCapped = ({ sql, routingKey, sender, capped, }) => {
+    const ranked = capped.map((row, index) => {
+        const earlier = capped.slice(0, index).filter(({ job }) => job === row.job);
+        return {
+            id: row.id,
+            tied: earlier.filter(({ dueAt }) => dueAt === row.dueAt).length,
+            before: earlier.filter(({ dueAt }) => dueAt <= row.dueAt).length,
+        };
+    });
+    const ids = ranked.map(({ id }) => id);
+    const latestOf = (rows) => sql `(SELECT max(e.ready_at_ms)
+    FROM actor_outbox e
+    WHERE e.routing_key = o.routing_key AND e.tenant_id = o.tenant_id
+      AND e.actor_type = o.actor_type AND e.actor_id = o.actor_id AND e.command = o.command
+      AND e.kind = 'job' AND ${rows}
+      AND e.scheduled_at_ms <= o.scheduled_at_ms
+      AND e.intent_id NOT IN ${sql.in(ids)})`;
+    const latest = sql `greatest(${latestOf(sql `NOT e.running`)}, ${latestOf(sql `e.running`)})`;
+    return Effect.asVoid(sql `UPDATE actor_outbox o
+    SET ready_at_ms = greatest(o.scheduled_at_ms + v.tied,
+      coalesce(${latest}, o.scheduled_at_ms - 1) + 1 + v.before)
+    FROM (VALUES ${sql.csv(ranked.map(({ id, tied, before }) => sql `(${id}::text, ${tied}::int, ${before}::int)`))}) AS v(intent_id, tied, before)
+    WHERE o.routing_key = ${routingKey} AND o.tenant_id = ${sender.tenant}
+      AND o.actor_type = ${sender.actor} AND o.actor_id = ${sender.id}
+      AND o.intent_id = v.intent_id`);
+};
+/**
+ * Writes one turn's intents and jobs now, reading the database time only
+ * when there are rows to insert. Returns the `OutboxReplies`, so the caller can
+ * wake the relay after commit when a row is due and tell it about cancelled
+ * attempts.
+ */
+export const writeOutbox = Effect.fnUntraced(function* (routingKey, sender, outbox) {
+    const staged = yield* outboxStatements(routingKey, sender, outbox, databaseTime);
+    for (const statement of staged.statements)
+        yield* statement;
+    return staged.replies;
+});

package/dist/runtime/turn/pipeline.d.ts

@@ -0,0 +1,68 @@
+import { PgPool, type PgConnection } from "@effect/sql-pg";
+import { Context, Effect, Fiber, Layer } from "effect";
+import type { Scope } from "effect";
+import type { SqlError } from "effect/sql";
+declare const TurnConnections_base: Context.ServiceClass<TurnConnections, "@rikalabs/akter/runtime/turn/pipeline/TurnConnections", {
+    /** Leases one session for the enclosing scope; the session returns to the pool when the scope closes. */
+    readonly lease: Effect.Effect<PgConnection.PgConnection, SqlError.SqlError, Scope.Scope>;
+    /** Takes a connection out of the pool, so its session never serves another turn. */
+    readonly invalidate: (connection: PgConnection.PgConnection) => Effect.Effect<void>;
+    /** Sessions turns hold now, and turns still waiting for one. */
+    readonly sessions: () => {
+        readonly leased: number;
+        readonly waiting: number;
+    };
+}>;
+/**
+ * Connections a turn leases for itself alone. Each one is multiplexed and
+ * never pinned, so a turn can queue a group of statements without waiting for
+ * each reply; a pinned transaction would serialize them.
+ */
+export declare class TurnConnections extends TurnConnections_base {
+}
+/**
+ * Settings merged over the turn pool's own. Tests pass a socket factory here
+ * to count the flights one turn puts on the wire.
+ */
+export declare const TurnPoolSettings: Context.Reference<Partial<PgPool.Config>>;
+/**
+ * The turn pool: `maxConnections` sessions, each handed to one turn at a
+ * time. A concurrency of one keeps the lease exclusive while the session
+ * stays unpinned. A lease first takes a bounded admission slot, refused at
+ * once past `maxConnections` plus the waiter allowance, then waits for a
+ * session first come, first served, so a turn never waits behind turns that
+ * asked after it. Both slots stay with the lease's scope and return with the
+ * session.
+ *
+ * On Neki, each session first runs the Neki session settings.
+ */
+export declare const turnConnections: (options: PgPool.Config) => Layer.Layer<TurnConnections, SqlError.SqlError, never>;
+/**
+ * Puts one statement on the session. The runtime passes a sender that queues
+ * its deferred statements in the same flight, ahead of the statement.
+ */
+export type Send = <A>(statement: Effect.Effect<A, SqlError.SqlError>) => Effect.Effect<A, SqlError.SqlError>;
+export { asSqlConnection } from "../database/connection.ts";
+/**
+ * Queues a group of statements for one flight without waiting for replies.
+ *
+ * Each statement starts on its own fiber before the next is forked, so the
+ * driver queues them in submission order and flushes them together. Queuing
+ * is uninterruptible, so a group is queued whole or not at all. The fibers
+ * live in `scope`, so a group can be queued in one step and awaited in the
+ * next.
+ */
+export declare const queueStatements: ({ scope, group, }: {
+    readonly scope: Scope.Scope;
+    readonly group: ReadonlyArray<Effect.Effect<void, SqlError.SqlError>>;
+}) => Effect.Effect<Fiber.Fiber<void, SqlError.SqlError>[], never, never>;
+/**
+ * Waits for every reply of a queued group, in order. Every reply is awaited
+ * before the first failure is reported, so the session has nothing of the
+ * group in flight afterwards. Only the wait can be interrupted.
+ */
+export declare const awaitReplies: (fibers: ReadonlyArray<Fiber.Fiber<void, SqlError.SqlError>>) => Effect.Effect<void, SqlError.SqlError, never>;
+/** Sends a group of statements as one flight, on child fibers, and waits for every reply. */
+export declare const sendPipelined: (group: ReadonlyArray<Effect.Effect<void, SqlError.SqlError>>) => Effect.Effect<void, SqlError.SqlError, never>;
+/** Runs a group one statement at a time, for a database with nothing to pipeline. */
+export declare const sendSequentially: (group: ReadonlyArray<Effect.Effect<void, SqlError.SqlError>>) => Effect.Effect<void, SqlError.SqlError, never>;

package/dist/runtime/turn/pipeline.js

@@ -0,0 +1,83 @@
+import { PgPool } from "@effect/sql-pg";
+import { Context, Duration, Effect, Exit, Fiber, Layer } from "effect";
+import { fairGate } from "../database/gate.js";
+import { nekiLease, NekiTurnSessions } from "../database/neki/session.js";
+import { admissionLimit } from "../admission.js";
+import { POOL_WAITERS, poolRefusal } from "../database/bounded.js";
+/**
+ * Connections a turn leases for itself alone. Each one is multiplexed and
+ * never pinned, so a turn can queue a group of statements without waiting for
+ * each reply; a pinned transaction would serialize them.
+ */
+export class TurnConnections extends Context.Service()("@rikalabs/akter/runtime/turn/pipeline/TurnConnections") {
+}
+/**
+ * Settings merged over the turn pool's own. Tests pass a socket factory here
+ * to count the flights one turn puts on the wire.
+ */
+export const TurnPoolSettings = Context.Reference("akter/TurnPoolSettings", { defaultValue: () => ({}) });
+/**
+ * The turn pool: `maxConnections` sessions, each handed to one turn at a
+ * time. A concurrency of one keeps the lease exclusive while the session
+ * stays unpinned. A lease first takes a bounded admission slot, refused at
+ * once past `maxConnections` plus the waiter allowance, then waits for a
+ * session first come, first served, so a turn never waits behind turns that
+ * asked after it. Both slots stay with the lease's scope and return with the
+ * session.
+ *
+ * On Neki, each session first runs the Neki session settings.
+ */
+export const turnConnections = (options) => Layer.effect(TurnConnections, Effect.gen(function* () {
+    const settings = yield* TurnPoolSettings;
+    const neki = yield* NekiTurnSessions;
+    const config = { ...options, ...settings };
+    const pool = yield* PgPool.make({
+        ...config,
+        multiplex: true,
+        multiplexConcurrency: 1,
+    });
+    const slots = config.maxConnections ?? 10;
+    const admission = admissionLimit({ limit: slots + POOL_WAITERS, wait: Duration.zero });
+    const gate = fairGate(slots);
+    const acquire = Effect.andThen(gate.take, neki ? nekiLease(pool) : pool.get);
+    let leased = 0;
+    let waiting = 0;
+    return TurnConnections.of({
+        lease: Effect.suspend(() => {
+            waiting += 1;
+            return Effect.andThen(admission.take.pipe(Effect.mapError(poolRefusal)), acquire).pipe(Effect.ensuring(Effect.sync(() => {
+                waiting -= 1;
+            })), Effect.tap(() => Effect.acquireRelease(Effect.sync(() => {
+                leased += 1;
+            }), () => Effect.sync(() => {
+                leased -= 1;
+            }))));
+        }),
+        invalidate: pool.invalidate,
+        sessions: () => ({ leased, waiting }),
+    });
+}));
+export { asSqlConnection } from "../database/connection.js";
+/**
+ * Queues a group of statements for one flight without waiting for replies.
+ *
+ * Each statement starts on its own fiber before the next is forked, so the
+ * driver queues them in submission order and flushes them together. Queuing
+ * is uninterruptible, so a group is queued whole or not at all. The fibers
+ * live in `scope`, so a group can be queued in one step and awaited in the
+ * next.
+ */
+export const queueStatements = ({ scope, group, }) => Effect.uninterruptible(Effect.forEach(group, (statement) => Effect.forkIn(statement, scope, { startImmediately: true, uninterruptible: false })));
+/**
+ * Waits for every reply of a queued group, in order. Every reply is awaited
+ * before the first failure is reported, so the session has nothing of the
+ * group in flight afterwards. Only the wait can be interrupted.
+ */
+export const awaitReplies = (fibers) => Effect.forEach(fibers, Fiber.await).pipe(Effect.flatMap((exits) => {
+    const failed = exits.find(Exit.isFailure);
+    return failed === undefined ? Effect.void : Effect.failCause(failed.cause);
+}));
+/** Sends a group of statements as one flight, on child fibers, and waits for every reply. */
+export const sendPipelined = (group) => Effect.uninterruptible(Effect.forEach(group, (statement) => Effect.forkChild(statement, { startImmediately: true, uninterruptible: false }))).pipe(Effect.flatMap(awaitReplies));
+/** Runs a group one statement at a time, for a database with nothing to pipeline. */
+export const sendSequentially = (group) => Effect.forEach(group, (statement) => statement, { discard: true });

package/dist/runtime/turn/receipt.d.ts

@@ -0,0 +1,81 @@
+import { Crypto, Effect, Schema } from "effect";
+import { ActorError } from "../../errors/actor.ts";
+import { Outcome } from "../request.ts";
+/** Encodes an outcome to the JSON text a receipt stores. */
+export declare const encodeOutcome: (outcome: Outcome) => Effect.Effect<string, Schema.SchemaError, never>;
+/** SHA-256 over Postgres's JSONB text normalization of a payload, as stored in receipts. */
+export declare const hashCanonical: (canonical: string) => Effect.Effect<string, never, Crypto.Crypto>;
+/** A retained `actor_receipts` row as read back: the admission facts a replay checks and the encoded outcome it returns. */
+export interface StoredReceipt {
+    readonly caller_key: string;
+    readonly command: string;
+    readonly payload_hash: string;
+    readonly outcome: string;
+}
+/**
+ * Access and conflict rules for a retained receipt, shared by admission and
+ * replay. Fails with `ActorError` `Unauthorized` when the caller differs and
+ * `CommandConflict` when the command or payload hash differs; otherwise it
+ * returns the stored outcome. A stored outcome that cannot be decoded is a defect.
+ */
+export declare const checkReceipt: (request: {
+    readonly ref: {
+        readonly tenant: string;
+        readonly actor: string;
+        readonly id: string;
+    };
+    readonly caller: {
+        readonly _tag: "Anonymous";
+    } | {
+        readonly _tag: "System";
+        readonly source: "actor" | "cron" | "job" | "process" | "subscription" | "timer" | "workflow";
+        readonly ref?: {
+            readonly tenant: string;
+            readonly actor: string;
+            readonly id: string;
+        } | undefined;
+        readonly onBehalfOf?: {
+            readonly subject: string;
+        } | undefined;
+        readonly mint?: {
+            readonly commandId: string;
+            readonly ordinal: number;
+        } | undefined;
+    } | {
+        readonly _tag: "User";
+        readonly subject: string;
+    };
+    readonly command: string;
+    readonly commandId: string;
+    readonly payload: string;
+    readonly external?: boolean | undefined;
+    readonly clockOffset?: number | undefined;
+    readonly redelivered?: boolean | undefined;
+    readonly intent?: {
+        readonly tenant: string;
+        readonly actor: string;
+        readonly id: string;
+    } | undefined;
+    readonly delivery?: {
+        readonly subscription: string;
+        readonly sourceType: string;
+        readonly sourceId: string;
+        readonly epoch: string;
+        readonly kind: "event" | "gap" | "rejected";
+        readonly position: string;
+    } | undefined;
+    readonly queuedAtMs?: number | undefined;
+    readonly usageToken?: string | undefined;
+}, hash: string, receipt: StoredReceipt) => Effect.Effect<{
+    readonly _tag: "Acknowledged";
+    readonly reason: "AlreadyApplied" | "NotCreated" | "Stale" | "Unsubscribed";
+} | {
+    readonly _tag: "Defect";
+    readonly cause: unknown;
+} | {
+    readonly _tag: "Failure";
+    readonly value: string;
+} | {
+    readonly _tag: "Success";
+    readonly value: string;
+}, ActorError, never>;