@rikalabs/akter 0.1.0-alpha.0

package/dist/runtime/database/tenancy.d.ts

@@ -0,0 +1,69 @@
+import { Context, Effect } from "effect";
+import { SqlClient } from "effect/sql";
+/**
+ * The role tenant-scoped transactions run as when row-level security is on.
+ * Undefined, they run as the connecting role, which the policies exempt.
+ */
+export declare const TenantScope: Context.Reference<{
+    readonly role: string | undefined;
+    readonly adoption: AdoptionScope | undefined;
+}>;
+/**
+ * The writer role a runtime takes for turns of actor types that own an
+ * enforced adopted table, and the types that do. The turn binds the role and
+ * its tenant together, as row-level security does, because the framework
+ * tables' `durable_tenant` policies bind every role that does not bypass them. `enforced` fills as each
+ * type registers, before any turn runs.
+ */
+export interface AdoptionScope {
+    readonly role: string;
+    readonly enforced: Set<string>;
+}
+/**
+ * The settings that bind the rest of a transaction to `tenant`: its role and
+ * the `durable.tenant` setting every `durable_tenant` policy compares with.
+ * Both are local, so they end with the transaction and never leak to the
+ * next borrower of the connection.
+ */
+export declare const tenantSettings: ({ sql, role, tenant, }: {
+    readonly sql: SqlClient.SqlClient;
+    readonly role: string;
+    readonly tenant: string;
+}) => import("effect/sql/Statement").Statement<import("effect/sql/SqlConnection").Row>;
+/**
+ * Runs `effect` in a transaction bound to `tenant` as `role`, or unchanged
+ * when row-level security is off or `effect` already runs in a transaction,
+ * such as a query's, that its caller bound.
+ */
+export declare const inTenant: ({ sql, role, tenant, }: {
+    readonly sql: SqlClient.SqlClient;
+    readonly role: string | undefined;
+    readonly tenant: string;
+}) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E | import("effect/sql/SqlError").SqlError, R>;
+/** `inTenant` with this runtime's role. */
+export declare const withTenant: (tenant: string) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E | import("effect/sql/SqlError").SqlError, R | SqlClient.SqlClient>;
+/**
+ * Refuses to start unless `role` confines the runtime to one tenant per
+ * transaction: it must be settable by this login, must not bypass the
+ * policies, and must be able to write every framework table. Every
+ * framework table with a `tenant_id` must carry the policy, including tables
+ * later migrations add. Every inspection view must belong to a view-owner
+ * role the policies bind, so the views filter by the reader's tenant, and
+ * which `role` can't act as, so a turn can't alter or drop a view. Setting
+ * the role in a transaction is the one proof that works for every membership
+ * rule.
+ */
+export declare const checkRowLevelSecurity: (role: string) => Effect.Effect<undefined, import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;
+/**
+ * Refuses an owned table that would let a tenant-scoped transaction see other
+ * tenants' rows, or that `role` cannot use: row-level security must be on with
+ * the `durable_tenant` policy its drizzle-kit migration creates, and `role`
+ * must not own it, since Postgres exempts a table's owner from its policies.
+ */
+export declare const checkOwnedTable: (schema: string, table: string, role: string) => Effect.Effect<undefined, import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;
+/**
+ * Refuses an adopted table `role` cannot use. An adopted table carries no
+ * `durable_tenant` policy unless the application added one, so only the
+ * privileges are checked: `role` reads it, and writes it when the runtime does.
+ */
+export declare const checkAdoptedTable: (schema: string, table: string, role: string, writable: boolean) => Effect.Effect<undefined, import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;

package/dist/runtime/database/tenancy.js

@@ -0,0 +1,145 @@
+import { Context, Effect, Option } from "effect";
+import { SqlClient } from "effect/sql";
+/**
+ * The role tenant-scoped transactions run as when row-level security is on.
+ * Undefined, they run as the connecting role, which the policies exempt.
+ */
+export const TenantScope = Context.Reference("akter/TenantScope", {
+    defaultValue: () => ({ role: undefined, adoption: undefined }),
+});
+/**
+ * The settings that bind the rest of a transaction to `tenant`: its role and
+ * the `durable.tenant` setting every `durable_tenant` policy compares with.
+ * Both are local, so they end with the transaction and never leak to the
+ * next borrower of the connection.
+ */
+export const tenantSettings = ({ sql, role, tenant, }) => sql `set_config('role', ${role}, true), set_config('durable.tenant', ${tenant}, true)`;
+/**
+ * Runs `effect` in a transaction bound to `tenant` as `role`, or unchanged
+ * when row-level security is off or `effect` already runs in a transaction,
+ * such as a query's, that its caller bound.
+ */
+export const inTenant = ({ sql, role, tenant, }) => (effect) => Effect.gen(function* () {
+    if (role === undefined)
+        return yield* effect;
+    if (Option.isSome(yield* Effect.serviceOption(sql.transactionService)))
+        return yield* effect;
+    return yield* sql.withTransaction(sql `SELECT ${tenantSettings({ sql, role, tenant })}`.pipe(Effect.andThen(effect)));
+});
+/** `inTenant` with this runtime's role. */
+export const withTenant = (tenant) => (effect) => Effect.gen(function* () {
+    const { role } = yield* TenantScope;
+    const sql = yield* SqlClient.SqlClient;
+    return yield* inTenant({ sql, role, tenant })(effect);
+});
+const refuse = (message) => Effect.die(new Error(`Row-level security is misconfigured: ${message}`));
+/**
+ * Refuses to start unless `role` confines the runtime to one tenant per
+ * transaction: it must be settable by this login, must not bypass the
+ * policies, and must be able to write every framework table. Every
+ * framework table with a `tenant_id` must carry the policy, including tables
+ * later migrations add. Every inspection view must belong to a view-owner
+ * role the policies bind, so the views filter by the reader's tenant, and
+ * which `role` can't act as, so a turn can't alter or drop a view. Setting
+ * the role in a transaction is the one proof that works for every membership
+ * rule.
+ */
+export const checkRowLevelSecurity = Effect.fnUntraced(function* (role) {
+    const sql = yield* SqlClient.SqlClient;
+    const [found] = yield* sql `
+    SELECT rolsuper OR rolbypassrls AS exempt FROM pg_roles WHERE rolname = ${role}`;
+    if (found === undefined)
+        return yield* refuse(`role ${role} does not exist`);
+    if (found.exempt)
+        return yield* refuse(`role ${role} is a superuser or bypasses row-level security`);
+    yield* sql `SELECT set_config('role', ${role}, true)`.pipe(sql.withTransaction, Effect.catch(() => refuse(`this login cannot SET ROLE ${role}`)));
+    const tables = yield* sql `
+    SELECT c.relname AS table,
+      pg_has_role(${role}, c.relowner, 'USAGE') AS owned,
+      c.relrowsecurity AND EXISTS (
+        SELECT 1 FROM pg_policy p WHERE p.polrelid = c.oid AND p.polname = 'durable_tenant'
+      ) AS protected,
+      has_table_privilege(${role}, c.oid, 'SELECT, INSERT, UPDATE, DELETE') AS writable
+    FROM pg_class c
+    WHERE c.relnamespace = current_schema()::regnamespace AND c.relkind = 'r'
+      AND (c.relname LIKE 'actor\\_%' OR c.relname LIKE 'tenant\\_content%')
+      AND EXISTS (
+        SELECT 1 FROM pg_attribute a
+        WHERE a.attrelid = c.oid AND a.attname = 'tenant_id' AND NOT a.attisdropped
+      )
+    ORDER BY c.relname`;
+    for (const table of tables) {
+        if (table.owned)
+            return yield* refuse(`role ${role} owns ${table.table}, so no policy binds it`);
+        if (!table.protected)
+            return yield* refuse(`${table.table} has no durable_tenant policy; apply migration 0018_rls`);
+        if (!table.writable)
+            return yield* refuse(`role ${role} cannot read and write ${table.table}; grant it`);
+    }
+    const views = yield* sql `
+    SELECT v.relname AS view, o.rolname AS owner,
+      o.rolsuper OR o.rolbypassrls OR EXISTS (
+        SELECT 1 FROM pg_class t
+        WHERE t.relnamespace = current_schema()::regnamespace AND t.relkind = 'r'
+          AND t.relrowsecurity AND pg_has_role(o.oid, t.relowner, 'USAGE')
+      ) AS exempt,
+      pg_has_role(${role}, o.oid, 'MEMBER') AS shared,
+      NOT EXISTS (
+        SELECT 1 FROM pg_class t
+        WHERE t.relnamespace = current_schema()::regnamespace AND t.relkind = 'r'
+          AND t.relname LIKE 'actor\\_%'
+          AND NOT has_table_privilege(o.oid, t.oid, 'SELECT')
+      ) AS readable
+    FROM pg_class v JOIN pg_roles o ON o.oid = v.relowner
+    WHERE v.relnamespace = 'durable'::regnamespace AND v.relkind = 'v'
+    ORDER BY v.relname`;
+    for (const view of views) {
+        if (view.exempt)
+            return yield* refuse(`durable.${view.view} belongs to ${view.owner}, which the policies exempt, so it would show every tenant; give the views to a dedicated view-owner role`);
+        if (view.shared)
+            return yield* refuse(`durable.${view.view} belongs to ${view.owner}, which ${role} can act as, so a turn could alter or drop it; give the views to a role ${role} is not a member of`);
+        if (!view.readable)
+            return yield* refuse(`durable.${view.view} belongs to ${view.owner}, which cannot read every actor_* table; grant it SELECT`);
+    }
+});
+/**
+ * Refuses an owned table that would let a tenant-scoped transaction see other
+ * tenants' rows, or that `role` cannot use: row-level security must be on with
+ * the `durable_tenant` policy its drizzle-kit migration creates, and `role`
+ * must not own it, since Postgres exempts a table's owner from its policies.
+ */
+export const checkOwnedTable = Effect.fnUntraced(function* (schema, table, role) {
+    const sql = yield* SqlClient.SqlClient;
+    const [found] = yield* sql `
+    SELECT pg_has_role(${role}, c.relowner, 'USAGE') AS owned,
+      c.relrowsecurity AND EXISTS (
+        SELECT 1 FROM pg_policy p WHERE p.polrelid = c.oid AND p.polname = 'durable_tenant'
+      ) AS protected,
+      has_table_privilege(${role}, c.oid, 'SELECT, INSERT, UPDATE, DELETE') AS writable
+    FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+    WHERE n.nspname = ${schema} AND c.relname = ${table}`;
+    if (found?.protected !== true)
+        return yield* refuse(`owned table ${schema}.${table} has no durable_tenant policy; apply its drizzle-kit migration`);
+    if (found.owned)
+        return yield* refuse(`role ${role} owns ${schema}.${table}, so no policy binds it`);
+    if (!found.writable)
+        return yield* refuse(`role ${role} cannot read and write ${schema}.${table}; grant it`);
+});
+/**
+ * Refuses an adopted table `role` cannot use. An adopted table carries no
+ * `durable_tenant` policy unless the application added one, so only the
+ * privileges are checked: `role` reads it, and writes it when the runtime does.
+ */
+export const checkAdoptedTable = Effect.fnUntraced(function* (schema, table, role, writable) {
+    const sql = yield* SqlClient.SqlClient;
+    const [found] = yield* sql `
+    SELECT has_table_privilege(${role}, c.oid, 'SELECT') AS readable,
+      has_table_privilege(${role}, c.oid, 'INSERT') AND has_table_privilege(${role}, c.oid, 'UPDATE')
+        AND has_table_privilege(${role}, c.oid, 'DELETE') AS writable
+    FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+    WHERE n.nspname = ${schema} AND c.relname = ${table}`;
+    if (found?.readable !== true)
+        return yield* refuse(`role ${role} cannot read ${schema}.${table}; grant it`);
+    if (writable && !found.writable)
+        return yield* refuse(`role ${role} cannot read and write ${schema}.${table}; grant it`);
+});

package/dist/runtime/database/transient.d.ts

@@ -0,0 +1,10 @@
+import type { SqlError } from "effect/sql";
+/**
+ * Whether a SQL failure is worth retrying unchanged: the driver says so, or
+ * the server refused the statement for its own state. SQLSTATE `57P01`–`57P03`
+ * mean an administrator or crash shutdown or a server still starting or in
+ * recovery; `53000`–`53300` cover exhausted resources, disk, memory or slots. The
+ * driver reports those as unknown, non-retryable errors, but the same
+ * statement succeeds once the server is back.
+ */
+export declare const transientSqlError: (error: SqlError.SqlError) => boolean;

package/dist/runtime/database/transient.js

@@ -0,0 +1,25 @@
+import { Schema } from "effect";
+/** The SQLSTATE a Postgres error response carries, as the driver keeps it on the error's cause. */
+const ServerResponse = Schema.Struct({ code: Schema.String });
+const isServerResponse = Schema.is(ServerResponse);
+/**
+ * Whether a SQL failure is worth retrying unchanged: the driver says so, or
+ * the server refused the statement for its own state. SQLSTATE `57P01`–`57P03`
+ * mean an administrator or crash shutdown or a server still starting or in
+ * recovery; `53000`–`53300` cover exhausted resources, disk, memory or slots. The
+ * driver reports those as unknown, non-retryable errors, but the same
+ * statement succeeds once the server is back.
+ */
+export const transientSqlError = (error) => {
+    if (error.isRetryable)
+        return true;
+    const cause = error.reason.cause;
+    return (isServerResponse(cause) &&
+        (cause.code === "57P01" ||
+            cause.code === "57P02" ||
+            cause.code === "57P03" ||
+            cause.code === "53000" ||
+            cause.code === "53100" ||
+            cause.code === "53200" ||
+            cause.code === "53300"));
+};

package/dist/runtime/drain.d.ts

@@ -0,0 +1,132 @@
+import { Context, Duration, Effect, type Scope } from "effect";
+import { ActorError } from "../errors/actor.ts";
+/**
+ * Whether this runner should receive traffic. A runner is ready once its
+ * storage answers, its schemas are migrated and compatible (checked when the
+ * layer builds), it registers at least one actor, job, or query layer, its
+ * routing is up, a public runner has its currently assigned shards, and it
+ * is not draining. Readiness never waits for actors to
+ * wake or workflows to finish.
+ */
+export type Readiness = {
+    readonly ready: true;
+} | {
+    readonly ready: false;
+    /**
+     * `draining` or `drained` after `drain`; `storage` when the database does
+     * not answer; `routing` while acquiring shards or once sharding has
+     * shut down; `peering` when a mutual TLS runner's certificate has
+     * expired or its credentials have failed to load for too long;
+     * `unregistered` before any actor, job, or query layer registers.
+     */
+    readonly reason: "draining" | "drained" | "storage" | "routing" | "peering" | "unregistered";
+};
+/** What a drain did. */
+export interface DrainReport {
+    /**
+     * `clean` when claims and background work stopped and every in-flight turn
+     * and job attempt finished before the deadline; `deadline-expired`
+     * otherwise, when the deadline interrupted what was still in flight.
+     */
+    readonly outcome: "clean" | "deadline-expired";
+    /**
+     * Turns the deadline interrupted. Each rolled back, unless its commit had
+     * already been sent, in which case its receipt answers the caller's retry.
+     */
+    readonly interruptedTurns: number;
+    /**
+     * Job attempts the deadline interrupted. The provider may have applied
+     * each call, so each stays ambiguous, and another runner takes it over once
+     * its lease ends.
+     */
+    readonly interruptedJobs: number;
+}
+declare const RuntimeControl_base: Context.ServiceClass<RuntimeControl, "@rikalabs/akter/runtime/drain/RuntimeControl", {
+    readonly readiness: Effect.Effect<Readiness>;
+    /**
+     * Makes the runner unready, refuses new commands, and stops claiming
+     * intents, timers, jobs, and subscription deliveries, releasing claimed
+     * deliveries to other runners. In-flight turns and job attempts then
+     * get until `deadline` to finish before they are interrupted. Pending
+     * durable work stays in the database for other runners. The runner keeps
+     * its shards until its layer closes, which hands them to the other runners
+     * and ends workflow runs still live here, for another runner to replay; so
+     * close the layer once the drain returns. A second call waits for the
+     * first drain and returns its report.
+     */
+    readonly drain: (options: {
+        readonly deadline: Duration.Input;
+    }) => Effect.Effect<DrainReport>;
+}>;
+/**
+ * Readiness and bounded graceful drain of this runner. `Actors.layer`
+ * provides it.
+ */
+export declare class RuntimeControl extends RuntimeControl_base {
+}
+/**
+ * Admits turns until a drain closes it, counts the turns in flight, and
+ * interrupts them all once the drain's deadline passes.
+ */
+export declare const turnGate: () => {
+    /**
+     * Runs a turn unless the runner drains. A turn the deadline interrupts
+     * fails as unavailable once it has rolled back, so its caller retries on
+     * the actor's next owner.
+     */
+    run: <A, E, R>(turn: Effect.Effect<A, E, R>) => Effect.Effect<A, E | ActorError, R>;
+    readonly open: boolean;
+    /** Refuses new turns and waits until none is in flight. */
+    close: Effect.Effect<void, never, never>;
+    /**
+     * Refuses new turns, interrupts every turn in flight, and returns how many
+     * it interrupted, once they have ended.
+     */
+    expire: Effect.Effect<number, never, never>;
+};
+/** The turn gate a runtime creates once and shares with its drain. */
+export type TurnGate = ReturnType<typeof turnGate>;
+/** The runtime's side of a drain: its relay and background work. */
+interface Drainable {
+    readonly gate: TurnGate;
+    /** Stops claims and releases claimed deliveries. */
+    readonly stopClaims: Effect.Effect<void>;
+    readonly attemptsIdle: Effect.Effect<void>;
+    /** Interrupts running job attempts and returns how many. */
+    readonly interruptAttempts: Effect.Effect<number>;
+    /** Stops background maintenance such as retention sweeps. */
+    readonly stopBackground: Effect.Effect<void>;
+    /** Readiness apart from draining. */
+    readonly serving: Effect.Effect<Readiness>;
+}
+/**
+ * The drain runs in the runtime's scope, so a caller that stops waiting
+ * neither cancels it nor leaves a later caller without its report.
+ *
+ * The deadline counts from the call and covers stopping claims and background
+ * work too: releasing a claimed delivery or ending a sweep writes to the
+ * database, which a slow or contended database can hold for longer than the
+ * deadline. That stop runs on in the runtime's scope, so claims still end,
+ * while the deadline interrupts the turns and job attempts in flight and
+ * the report says it expired.
+ */
+export declare const runtimeControl: ({ scope, ...runtime }: Drainable & {
+    readonly scope: Scope.Scope;
+}) => {
+    readonly readiness: Effect.Effect<Readiness>;
+    /**
+     * Makes the runner unready, refuses new commands, and stops claiming
+     * intents, timers, jobs, and subscription deliveries, releasing claimed
+     * deliveries to other runners. In-flight turns and job attempts then
+     * get until `deadline` to finish before they are interrupted. Pending
+     * durable work stays in the database for other runners. The runner keeps
+     * its shards until its layer closes, which hands them to the other runners
+     * and ends workflow runs still live here, for another runner to replay; so
+     * close the layer once the drain returns. A second call waits for the
+     * first drain and returns its report.
+     */
+    readonly drain: (options: {
+        readonly deadline: Duration.Input;
+    }) => Effect.Effect<DrainReport>;
+};
+export {};

package/dist/runtime/drain.js

@@ -0,0 +1,109 @@
+import { Context, Deferred, Duration, Effect, Exit, Fiber, Option } from "effect";
+import { ActorError, ActorUnavailable } from "../errors/actor.js";
+/**
+ * Readiness and bounded graceful drain of this runner. `Actors.layer`
+ * provides it.
+ */
+export class RuntimeControl extends Context.Service()("@rikalabs/akter/runtime/drain/RuntimeControl") {
+}
+const refused = () => ActorError.make({
+    reason: ActorUnavailable.make({ cause: new Error("Runner is draining") }),
+});
+/**
+ * Admits turns until a drain closes it, counts the turns in flight, and
+ * interrupts them all once the drain's deadline passes.
+ */
+export const turnGate = () => {
+    let open = true;
+    let inFlight = 0;
+    let interrupted = 0;
+    let idle;
+    const expired = Deferred.makeUnsafe();
+    const deadline = Deferred.await(expired).pipe(Effect.andThen(Effect.suspend(() => {
+        interrupted += 1;
+        return Effect.fail(refused());
+    })));
+    return {
+        /**
+         * Runs a turn unless the runner drains. A turn the deadline interrupts
+         * fails as unavailable once it has rolled back, so its caller retries on
+         * the actor's next owner.
+         */
+        run: (turn) => Effect.suspend(() => {
+            if (!open)
+                return Effect.fail(refused());
+            inFlight += 1;
+            return Effect.raceFirst(turn, deadline).pipe(Effect.ensuring(Effect.sync(() => {
+                inFlight -= 1;
+                if (inFlight === 0 && idle !== undefined)
+                    Deferred.doneUnsafe(idle, Exit.void);
+            })));
+        }),
+        get open() {
+            return open;
+        },
+        /** Refuses new turns and waits until none is in flight. */
+        close: Effect.suspend(() => {
+            open = false;
+            if (inFlight === 0)
+                return Effect.void;
+            idle ??= Deferred.makeUnsafe();
+            return Deferred.await(idle);
+        }),
+        /**
+         * Refuses new turns, interrupts every turn in flight, and returns how many
+         * it interrupted, once they have ended.
+         */
+        expire: Effect.suspend(() => {
+            open = false;
+            Deferred.doneUnsafe(expired, Exit.void);
+            if (inFlight > 0)
+                idle ??= Deferred.makeUnsafe();
+            return (idle === undefined ? Effect.void : Deferred.await(idle)).pipe(Effect.map(() => interrupted));
+        }),
+    };
+};
+/**
+ * The drain runs in the runtime's scope, so a caller that stops waiting
+ * neither cancels it nor leaves a later caller without its report.
+ *
+ * The deadline counts from the call and covers stopping claims and background
+ * work too: releasing a claimed delivery or ending a sweep writes to the
+ * database, which a slow or contended database can hold for longer than the
+ * deadline. That stop runs on in the runtime's scope, so claims still end,
+ * while the deadline interrupts the turns and job attempts in flight and
+ * the report says it expired.
+ */
+export const runtimeControl = ({ scope, ...runtime }) => {
+    let state = "serving";
+    const report = Deferred.makeUnsafe();
+    const run = (deadline) => Effect.gen(function* () {
+        const stopping = yield* runtime.stopClaims.pipe(Effect.andThen(runtime.stopBackground), Effect.forkIn(scope));
+        const finished = yield* Fiber.join(stopping).pipe(Effect.andThen(Effect.all([runtime.gate.close, runtime.attemptsIdle], {
+            concurrency: 2,
+            discard: true,
+        })), Effect.timeoutOption(deadline));
+        const done = Option.isSome(finished)
+            ? { outcome: "clean", interruptedTurns: 0, interruptedJobs: 0 }
+            : yield* Effect.all({
+                interruptedTurns: runtime.gate.expire,
+                interruptedJobs: runtime.interruptAttempts,
+            }, { concurrency: 2 }).pipe(Effect.map((counts) => ({ outcome: "deadline-expired", ...counts })));
+        if (done.outcome === "deadline-expired")
+            yield* Effect.logWarning("Drain deadline expired; interrupted in-flight work").pipe(Effect.annotateLogs({
+                interruptedTurns: done.interruptedTurns,
+                interruptedJobs: done.interruptedJobs,
+            }));
+        state = "drained";
+        yield* Deferred.succeed(report, done);
+    });
+    return RuntimeControl.of({
+        readiness: Effect.suspend(() => state === "serving" ? runtime.serving : Effect.succeed({ ready: false, reason: state })),
+        drain: (options) => Effect.suspend(() => {
+            if (state !== "serving")
+                return Deferred.await(report);
+            state = "draining";
+            return run(Duration.fromInputUnsafe(options.deadline)).pipe(Effect.forkIn(scope), Effect.andThen(Deferred.await(report)));
+        }),
+    });
+};

package/dist/runtime/entity/mailbox.d.ts

@@ -0,0 +1,86 @@
+import type { Request } from "../request.ts";
+/**
+ * The most commands one turn batch runs. It stays below the 64 open
+ * subtransactions past which Postgres overflows its per-backend subtransaction
+ * cache, since a batch of an actor whose handlers issue statements can hold a
+ * savepoint per command.
+ */
+export declare const BATCH_CAP = 32;
+/**
+ * The most calls of one commutative reducer that one merged turn combines.
+ * Merging never waits for calls: it takes only those already waiting.
+ */
+export declare const MERGE_CAP = 1024;
+/**
+ * The most command ids an activation keeps to run alone after a failed batch.
+ * An id leaves the set when its retry is taken, and a caller that never
+ * retries would otherwise leave it for the activation's lifetime. Past the
+ * cap the oldest go first: an evicted id's late retry may join a batch again,
+ * which a retryable failure makes safe.
+ */
+export declare const ALONE_CAP: number;
+/** Adds `ids` to `alone` as its newest entries, then drops the oldest past `ALONE_CAP`. */
+export declare const markAlone: ({ alone, ids, }: {
+    readonly alone: Set<string>;
+    readonly ids: Iterable<string>;
+}) => void;
+/** A waiting command, and whether its reducer merges with its neighbours. */
+interface Mergeable {
+    readonly request: Request;
+    readonly command: {
+        readonly merge?: unknown;
+    };
+}
+/** True when `next` joins a merged turn of `previous`'s commutative reducer. */
+export declare const merges: ({ previous, next, }: {
+    readonly previous: Mergeable;
+    readonly next: Mergeable;
+}) => boolean;
+/**
+ * Removes the next batch from the front of `waiting`, in delivery order: the
+ * first command, then each command behind it that is already waiting, up to
+ * `BATCH_CAP` turns. Consecutive calls of one commutative reducer are one
+ * merged turn of up to `MERGE_CAP` calls. Nothing waits for more to arrive. A
+ * command joins a batch only once its own `queued` hook has finished, so the
+ * batch stops at the first command that is still in it, and takes nothing when
+ * that is the first.
+ *
+ * A batch stops before a command id it already holds, so a retry queued
+ * behind its original resolves through the receipt the original commits. It
+ * also stops before a command listed in `alone`, and such a command runs in a
+ * batch of its own, once: these are the commands of a batch that failed, run
+ * one per transaction until each has been processed.
+ */
+export declare const takeBatch: <W extends Mergeable & {
+    /** Set once the request's `queued` hook has finished. */
+    readonly queued: boolean;
+}>({ waiting, alone, }: {
+    readonly waiting: Array<W>;
+    readonly alone: Set<string>;
+}) => Array<W>;
+/**
+ * One activation handler's waiting commands in arrival order, and its
+ * worker's wake-up. A command is offered as Cluster delivers it and becomes
+ * takeable once its `queued` hook finished; the wake-up stays open while the
+ * front command is takeable, so the worker never sleeps past ready work and a
+ * command whose hook is still running holds back every command behind it.
+ * `alone` outlives the handler: it holds the ids of a failed batch, each run
+ * in a transaction of its own once.
+ */
+export declare const activationMailbox: <W extends Mergeable & {
+    queued: boolean;
+}>(alone: Set<string>) => {
+    offer: (entry: W) => void;
+    /** Marks `entry`'s `queued` hook finished, so a batch may take it. */
+    queued: (entry: W) => void;
+    /** Waits until the front command may be takeable. */
+    await: import("effect/Effect").Effect<void, never, never>;
+    /** The next batch, possibly empty; the wake-up closes once the front command is not takeable. */
+    take: () => W[];
+    /** Puts taken commands back in front of everything that arrived since. */
+    requeue: (entries: ReadonlyArray<W>) => void;
+    /** Runs each of `ids` alone once, the next time it is taken. */
+    isolate: (ids: Iterable<string>) => void;
+    size: () => number;
+};
+export {};