@rikalabs/akter 0.1.0-alpha.0

package/dist/runtime/registration.js

@@ -0,0 +1,186 @@
+import { Context, Crypto, Effect } from "effect";
+import { Sharding } from "effect/cluster";
+import { SqlClient, SqlError } from "effect/sql";
+import { isContent } from "../members/blob.js";
+import { retryPoolRefusal } from "./database/bounded.js";
+import { registerActor } from "./entity/register.js";
+import { findPayloadProblems, formatPayloadProblem, recordPayloadVersions, } from "./payloads/versions.js";
+import { checkPlacement } from "./storage/placements.js";
+import { DefectLog } from "./telemetry/defects.js";
+import { FrameworkClock } from "./turn/admission.js";
+import { OutboxRuntime, textArray } from "./turn/outbox.js";
+import { checkTables } from "./turn/rows.js";
+import { acceptWorkflows, formatIncompatibility } from "./workflows/compatibility.js";
+import { RECOVERY_MS } from "./workflows/engine.js";
+/** How long registering a source waits for the subscriber types routing from it to register. */
+const ROUTED_SUBSCRIBER_WAIT_MS = 5000;
+/**
+ * Registers actor, query, and job layers with the runtime. Each
+ * registration is refused unless its placement, tables, content, workflows,
+ * payload versions, and routed subscriptions agree with the database and the
+ * runtime's configuration; an accepted one is recorded for the relay, the
+ * connection holder, and the sweeps, and forgotten when its layer's scope
+ * closes.
+ */
+export const actorRegistration = ({ registrations, queryRegistrations, jobRegistrations, residency, diagnostics, owners, heldTypes, heldType, sweepsWorkflows, checked, services, frameworkClock, content, retryWindowMs, tableRole, adoptionRole, enforcedTypes, writerDeclarations, refreshPayloadWriters, subscriptions, transport, authorize, gate, writable, defectLog, outbox, }) => {
+    /** Concurrent layers can exceed checkout capacity; only a refused checkout is safe to retry here. */
+    const startupSql = (effect) => retryPoolRefusal(effect).pipe(Effect.orDie);
+    /**
+     * Refuses a layer that can't read every payload version the database
+     * may hold, as a placement or workflow mismatch is refused. `writes`
+     * names the actor type whose turns the layer runs, for the removed-class check.
+     */
+    const checkPayloadVersions = Effect.fnUntraced(function* (name, declarations, writes) {
+        const problems = yield* findPayloadProblems(declarations, writes === undefined ? [] : [writes]).pipe(Effect.provideContext(services), startupSql);
+        if (problems.length > 0)
+            return yield* Effect.die(new Error([
+                `Actor ${name} cannot read every stored payload version; deploy refused`,
+                ...problems.map(formatPayloadProblem),
+            ].join("\n")));
+    });
+    const recordRouted = Effect.fnUntraced(function* (registration) {
+        const sql = yield* SqlClient.SqlClient;
+        const routed = registration.subscriptions.filter((declared) => declared.routed !== undefined);
+        for (const declared of routed)
+            yield* sql `INSERT INTO actor_routed_subscriptions (source_type, subscriber_type, subscription)
+        VALUES (${declared.sourceType}, ${registration.name}, ${declared.tag})
+        ON CONFLICT DO NOTHING`;
+        yield* sql `DELETE FROM actor_routed_subscriptions
+      WHERE subscriber_type = ${registration.name}
+        AND NOT (source_type, subscription) IN (
+          SELECT * FROM unnest(${textArray({ sql, values: routed.map((declared) => declared.sourceType) })},
+            ${textArray({ sql, values: routed.map((declared) => declared.tag) })}))`;
+    });
+    /**
+     * A publishing turn creates a routed subscription's source-side rows
+     * only from the routed declarations its runner registers, so a runner
+     * that serves a source without a subscriber type routing from it would
+     * lose those events silently. Registering the source fails instead.
+     * Layers of one runtime register concurrently, so the subscriber gets
+     * a short window to register first.
+     */
+    const requireRoutedSubscribers = Effect.fnUntraced(function* (sourceType) {
+        const sql = yield* SqlClient.SqlClient;
+        const missing = Effect.map(sql `
+        SELECT subscriber_type, subscription FROM actor_routed_subscriptions
+        WHERE source_type = ${sourceType}`, (rows) => rows.filter((row) => row.subscriber_type !== sourceType && !registrations.has(row.subscriber_type)));
+        for (let waited = 0; waited < ROUTED_SUBSCRIBER_WAIT_MS; waited += 100) {
+            if ((yield* missing).length === 0)
+                return;
+            yield* Effect.sleep("100 millis");
+        }
+        const unregistered = yield* missing;
+        if (unregistered.length > 0)
+            return yield* Effect.die(new Error(`Actor ${sourceType} is registered without the subscriber types that route from it (${unregistered
+                .map((row) => `${row.subscriber_type}.${row.subscription}`)
+                .join(", ")}); register their layers on every runner that serves ${sourceType}`));
+    });
+    const declaresContent = (registration) => registration.blobs.some(isContent);
+    const requireContent = (name) => content === undefined
+        ? Effect.die(new Error(`Actor ${name} declares content; give the runtime content.keys`))
+        : Effect.void;
+    const recordContentTurn = Effect.fnUntraced(function* (registration) {
+        const sql = yield* SqlClient.SqlClient;
+        yield* sql `INSERT INTO actor_content_types (actor_type, turn_ms)
+      VALUES (${registration.name}, ${registration.policy.executionMs})
+      ON CONFLICT (actor_type) DO UPDATE
+      SET turn_ms = greatest(actor_content_types.turn_ms, EXCLUDED.turn_ms)`;
+    });
+    return {
+        register: Effect.fnUntraced(function* (registration) {
+            if (registrations.has(registration.name))
+                return yield* Effect.die(new Error(`Duplicate actor: ${registration.name}`));
+            yield* checkPlacement(registration).pipe(Effect.provideContext(services), startupSql);
+            if (declaresContent(registration)) {
+                yield* requireContent(registration.name);
+                yield* recordContentTurn(registration).pipe(Effect.provideContext(services), startupSql);
+            }
+            const enforces = yield* checkTables(registration.name, registration.tables, tableRole, {
+                role: adoptionRole,
+                writes: true,
+            }).pipe(Effect.provideContext(services), startupSql);
+            if (enforces)
+                enforcedTypes.add(registration.name);
+            for (const table of registration.tables)
+                checked.add(table);
+            if (registration.workflows.size > 0 && registration.policy.keepWorkflowsMs < retryWindowMs)
+                return yield* Effect.die(new Error(`Actor ${registration.name} keepWorkflows is shorter than the retry window`));
+            if (registration.workflows.size > 0 &&
+                retryWindowMs - registration.policy.deliveryMs <= RECOVERY_MS)
+                yield* Effect.logWarning(`Actor ${registration.name}: the retry window minus deliveryTimeout is at most the ${RECOVERY_MS / 1000}-second workflow recovery interval, so an activity whose runner dies fails with ActivityOutcomeUnknown instead of rerunning its actor calls`);
+            const { incompatibilities, retained } = yield* acceptWorkflows({
+                name: registration.name,
+                workflows: Array.from(registration.workflows.values(), ({ member }) => member),
+            }).pipe(Effect.provideContext(services), startupSql);
+            if (incompatibilities.length > 0)
+                return yield* Effect.die(new Error([
+                    `Actor ${registration.name} workflows are incompatible with open executions; deploy refused`,
+                    ...incompatibilities.map(formatIncompatibility),
+                ].join("\n")));
+            yield* checkPayloadVersions(registration.name, registration.payloads, {
+                actorType: registration.name,
+                events: registration.payloads
+                    .filter((declared) => declared.writes && declared.kind === "event")
+                    .map((declared) => declared.tag),
+            });
+            yield* recordPayloadVersions(registration.payloads).pipe(Effect.provideContext(services), Effect.provideService(FrameworkClock, frameworkClock), startupSql);
+            for (const declared of registration.payloads)
+                if (declared.writes)
+                    writerDeclarations.push(declared);
+            yield* refreshPayloadWriters.pipe(startupSql);
+            yield* recordRouted(registration).pipe(Effect.provideContext(services), startupSql);
+            yield* requireRoutedSubscribers(registration.name).pipe(Effect.provideContext(services), startupSql);
+            for (const declared of registration.subscriptions)
+                if (declared.routed === undefined)
+                    yield* subscriptions
+                        .widen(registration.name, declared)
+                        .pipe(Effect.provideContext(services), startupSql);
+            registrations.set(registration.name, registration);
+            if (registration.connections.size > 0 ||
+                registration.feeds.size > 0 ||
+                registration.watches.size > 0)
+                heldTypes.set(registration.name, heldType(registration));
+            if (retained)
+                sweepsWorkflows.add(registration.name);
+            yield* Effect.addFinalizer(() => Effect.sync(() => {
+                registrations.delete(registration.name);
+                residency.delete(registration.name);
+                diagnostics.delete(registration.name);
+                owners.delete(registration.name);
+                heldTypes.delete(registration.name);
+                sweepsWorkflows.delete(registration.name);
+            }));
+            const { isResident, owner, diagnose, restarting } = yield* registerActor(registration, transport, authorize, gate, writable).pipe(Effect.provideService(DefectLog, defectLog), Effect.provideContext(services), Effect.provideService(OutboxRuntime, outbox));
+            residency.set(registration.name, isResident);
+            diagnostics.set(registration.name, { diagnose, restarting });
+            owners.set(registration.name, owner);
+        }),
+        registerQueries: Effect.fnUntraced(function* (registration) {
+            if (queryRegistrations.has(registration.name))
+                return yield* Effect.die(new Error(`Duplicate query layer: ${registration.name}`));
+            yield* checkPlacement(registration).pipe(Effect.provideContext(services), startupSql);
+            if (declaresContent(registration))
+                yield* requireContent(registration.name);
+            yield* checkTables(registration.name, registration.tables, tableRole, {
+                role: adoptionRole,
+                writes: false,
+            }).pipe(Effect.provideContext(services), startupSql);
+            for (const table of registration.tables)
+                checked.add(table);
+            yield* checkPayloadVersions(registration.name, registration.payloads);
+            queryRegistrations.set(registration.name, registration);
+            yield* Effect.addFinalizer(() => Effect.sync(() => {
+                queryRegistrations.delete(registration.name);
+            }));
+        }),
+        registerJobs: Effect.fnUntraced(function* (registration) {
+            if (jobRegistrations.has(registration.name))
+                return yield* Effect.die(new Error(`Duplicate job layer: ${registration.name}`));
+            yield* checkPayloadVersions(registration.name, registration.payloads);
+            jobRegistrations.set(registration.name, registration);
+            yield* Effect.addFinalizer(() => Effect.sync(() => {
+                jobRegistrations.delete(registration.name);
+            }));
+        }),
+    };
+};

package/dist/runtime/request.d.ts

@@ -0,0 +1,158 @@
+import { Schema } from "effect";
+import { ActorError } from "../errors/actor.ts";
+/**
+ * How a command or query ended, with its value or declared failure still
+ * JSON-encoded. A defect carries only its cause and is never a declared error.
+ */
+export declare const Outcome: Schema.TaggedUnion<{
+    readonly Acknowledged: Schema.TaggedStruct<"Acknowledged", {
+        readonly reason: Schema.Literals<readonly ["AlreadyApplied", "Stale", "Unsubscribed", "NotCreated"]>;
+    }>;
+    readonly Defect: Schema.TaggedStruct<"Defect", {
+        readonly cause: Schema.Defect;
+    }>;
+    readonly Failure: Schema.TaggedStruct<"Failure", {
+        readonly value: Schema.String;
+    }>;
+    readonly Success: Schema.TaggedStruct<"Success", {
+        readonly value: Schema.String;
+    }>;
+}>;
+/** How a command or query ended: an encoded success or declared failure, or a defect. */
+export type Outcome = typeof Outcome.Type;
+/**
+ * A command's outcome, with the commit version its caller's later queries
+ * wait for once the turn committed or replayed a receipt, and the database
+ * clock read on the turn's session after its transaction ended, which an
+ * external caller's expiry recheck uses before the reply. A defect carries
+ * neither.
+ */
+export declare const Executed: Schema.Struct<{
+    readonly outcome: Schema.TaggedUnion<{
+        readonly Acknowledged: Schema.TaggedStruct<"Acknowledged", {
+            readonly reason: Schema.Literals<readonly ["AlreadyApplied", "Stale", "Unsubscribed", "NotCreated"]>;
+        }>;
+        readonly Defect: Schema.TaggedStruct<"Defect", {
+            readonly cause: Schema.Defect;
+        }>;
+        readonly Failure: Schema.TaggedStruct<"Failure", {
+            readonly value: Schema.String;
+        }>;
+        readonly Success: Schema.TaggedStruct<"Success", {
+            readonly value: Schema.String;
+        }>;
+    }>;
+    readonly version: Schema.optionalKey<Schema.String>;
+    readonly endedAtMs: Schema.optionalKey<Schema.Finite>;
+    readonly replayed: Schema.optionalKey<Schema.Boolean>;
+}>;
+/** A command's outcome and the commit version its caller's later queries wait for. */
+export type Executed = typeof Executed.Type;
+declare const DeliveryFailed_base: Schema.Class<DeliveryFailed, Schema.TaggedStruct<"DeliveryFailed", {
+    readonly error: typeof ActorError;
+    readonly admitted: Schema.Boolean;
+}>, import("effect/Cause").YieldableError>;
+/** An owner's retryable delivery failure, with whether fenced admission validated the id. */
+export declare class DeliveryFailed extends DeliveryFailed_base {
+}
+/**
+ * What a subscription delivery carries beside its command id: the source-side
+ * row it came from, the subscription's epoch, and the source position it
+ * applies. Only the relay sets it; the subscriber's cursor row is checked and
+ * advanced against it in the delivery's own turn.
+ */
+export declare const SubscriptionEnvelope: Schema.Struct<{
+    readonly subscription: Schema.NonEmptyString;
+    readonly sourceType: Schema.NonEmptyString;
+    readonly sourceId: Schema.NonEmptyString;
+    readonly epoch: Schema.String;
+    readonly kind: Schema.Literals<readonly ["event", "gap", "rejected"]>;
+    /** An event's cursor, a gap's `resumeAfter`, or a rejected subscription's cursor. */
+    readonly position: Schema.String;
+}>;
+/** The relay's metadata for one subscription delivery. */
+export type SubscriptionEnvelope = typeof SubscriptionEnvelope.Type;
+/**
+ * One command or query addressed to an actor, with its encoded payload.
+ * `commandId` is the operation's identity: a retry with the same id replays
+ * the receipt instead of running again.
+ */
+export declare const Request: Schema.Struct<{
+    readonly ref: Schema.Struct<{
+        readonly tenant: Schema.NonEmptyString;
+        readonly actor: Schema.NonEmptyString;
+        readonly id: Schema.NonEmptyString;
+    }>;
+    readonly caller: 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;
+        }>>;
+    }>]>;
+    readonly command: Schema.NonEmptyString;
+    readonly commandId: Schema.String;
+    readonly payload: Schema.String;
+    /**
+     * Set only by the runtime on external admission. On its first delivery such
+     * a turn checks the id against its fenced read's database clock before it
+     * releases a receipt or runs the handler. Any turn of it rejects an expired
+     * id that has no receipt once retention may have pruned one, so pruning a
+     * receipt while its retry waits for the turn cannot run the command again.
+     */
+    readonly external: Schema.optionalKey<Schema.Boolean>;
+    /** Runtime-only framework-clock offset carried across a test/runner hop. */
+    readonly clockOffset: Schema.optionalKey<Schema.Finite>;
+    /**
+     * Set by the runtime only once an owner reported that an earlier attempt
+     * passed fenced admission. That attempt was admitted within the id's
+     * window, so expiry alone does not reject it before receipt resolution or
+     * the retention safety check. Invalid and future identities still fail.
+     */
+    readonly redelivered: Schema.optionalKey<Schema.Boolean>;
+    /**
+     * The sender of the committed outbox row the relay claimed. The rest of
+     * that row's delivery is this request's target, caller, command id,
+     * command, and payload. Only the relay supplies this provenance, and
+     * external admission rejects it rather than trusting a presented proof.
+     */
+    readonly intent: Schema.optionalKey<Schema.Struct<{
+        readonly tenant: Schema.NonEmptyString;
+        readonly actor: Schema.NonEmptyString;
+        readonly id: Schema.NonEmptyString;
+    }>>;
+    readonly delivery: Schema.optionalKey<Schema.Struct<{
+        readonly subscription: Schema.NonEmptyString;
+        readonly sourceType: Schema.NonEmptyString;
+        readonly sourceId: Schema.NonEmptyString;
+        readonly epoch: Schema.String;
+        readonly kind: Schema.Literals<readonly ["event", "gap", "rejected"]>;
+        /** An event's cursor, a gap's `resumeAfter`, or a rejected subscription's cursor. */
+        readonly position: Schema.String;
+    }>>;
+    /**
+     * When the admitting runner sent the command to its owner, by that
+     * runner's clock; the owner reports the wait as mailbox age. Not part of
+     * the command's identity.
+     */
+    readonly queuedAtMs: Schema.optionalKey<Schema.Finite>;
+    /**
+     * Names one read attempt for the host's usage accounting; a watch reuses it
+     * for every rerun. A host that supplies it must have bound it to an
+     * authenticated assertion. Not part of the request's identity.
+     */
+    readonly usageToken: Schema.optionalKey<Schema.NonEmptyString>;
+}>;
+/** One command or query addressed to an actor. */
+export type Request = typeof Request.Type;
+export {};

package/dist/runtime/request.js

@@ -0,0 +1,102 @@
+import { Schema } from "effect";
+import { ActorRef, Caller } from "../identity/caller.js";
+import { ActorError } from "../errors/actor.js";
+/**
+ * How a command or query ended, with its value or declared failure still
+ * JSON-encoded. A defect carries only its cause and is never a declared error.
+ */
+export const Outcome = Schema.TaggedUnion({
+    Success: { value: Schema.String },
+    Failure: { value: Schema.String },
+    Defect: { cause: Schema.Defect() },
+    /**
+     * A subscription delivery the subscriber settled without running its
+     * handler; only the relay sees it, and it commits no receipt.
+     */
+    Acknowledged: {
+        reason: Schema.Literals(["AlreadyApplied", "Stale", "Unsubscribed", "NotCreated"]),
+    },
+});
+/**
+ * A command's outcome, with the commit version its caller's later queries
+ * wait for once the turn committed or replayed a receipt, and the database
+ * clock read on the turn's session after its transaction ended, which an
+ * external caller's expiry recheck uses before the reply. A defect carries
+ * neither.
+ */
+export const Executed = Schema.Struct({
+    outcome: Outcome,
+    version: Schema.optionalKey(Schema.String),
+    endedAtMs: Schema.optionalKey(Schema.Finite),
+    replayed: Schema.optionalKey(Schema.Boolean),
+});
+/** An owner's retryable delivery failure, with whether fenced admission validated the id. */
+export class DeliveryFailed extends Schema.TaggedError()("DeliveryFailed", {
+    error: ActorError,
+    admitted: Schema.Boolean,
+}) {
+}
+/**
+ * What a subscription delivery carries beside its command id: the source-side
+ * row it came from, the subscription's epoch, and the source position it
+ * applies. Only the relay sets it; the subscriber's cursor row is checked and
+ * advanced against it in the delivery's own turn.
+ */
+export const SubscriptionEnvelope = Schema.Struct({
+    subscription: Schema.NonEmptyString,
+    sourceType: Schema.NonEmptyString,
+    sourceId: Schema.NonEmptyString,
+    epoch: Schema.String,
+    kind: Schema.Literals(["event", "gap", "rejected"]),
+    /** An event's cursor, a gap's `resumeAfter`, or a rejected subscription's cursor. */
+    position: Schema.String,
+});
+/**
+ * One command or query addressed to an actor, with its encoded payload.
+ * `commandId` is the operation's identity: a retry with the same id replays
+ * the receipt instead of running again.
+ */
+export const Request = Schema.Struct({
+    ref: ActorRef,
+    caller: Caller,
+    command: Schema.NonEmptyString,
+    commandId: Schema.String,
+    payload: Schema.String,
+    /**
+     * Set only by the runtime on external admission. On its first delivery such
+     * a turn checks the id against its fenced read's database clock before it
+     * releases a receipt or runs the handler. Any turn of it rejects an expired
+     * id that has no receipt once retention may have pruned one, so pruning a
+     * receipt while its retry waits for the turn cannot run the command again.
+     */
+    external: Schema.optionalKey(Schema.Boolean),
+    /** Runtime-only framework-clock offset carried across a test/runner hop. */
+    clockOffset: Schema.optionalKey(Schema.Finite),
+    /**
+     * Set by the runtime only once an owner reported that an earlier attempt
+     * passed fenced admission. That attempt was admitted within the id's
+     * window, so expiry alone does not reject it before receipt resolution or
+     * the retention safety check. Invalid and future identities still fail.
+     */
+    redelivered: Schema.optionalKey(Schema.Boolean),
+    /**
+     * The sender of the committed outbox row the relay claimed. The rest of
+     * that row's delivery is this request's target, caller, command id,
+     * command, and payload. Only the relay supplies this provenance, and
+     * external admission rejects it rather than trusting a presented proof.
+     */
+    intent: Schema.optionalKey(ActorRef),
+    delivery: Schema.optionalKey(SubscriptionEnvelope),
+    /**
+     * When the admitting runner sent the command to its owner, by that
+     * runner's clock; the owner reports the wait as mailbox age. Not part of
+     * the command's identity.
+     */
+    queuedAtMs: Schema.optionalKey(Schema.Finite),
+    /**
+     * Names one read attempt for the host's usage accounting; a watch reuses it
+     * for every rerun. A host that supplies it must have bound it to an
+     * authenticated assertion. Not part of the request's identity.
+     */
+    usageToken: Schema.optionalKey(Schema.NonEmptyString),
+});

package/dist/runtime/retry.d.ts

@@ -0,0 +1,8 @@
+import { Duration } from "effect";
+import type { ActorError } from "../errors/actor.ts";
+/**
+ * The wait before retry `attempt` (0 for the first) of a delivery that failed
+ * with the given error: its own `retryAfter`, doubling on each attempt, capped at the
+ * greater of 500 ms and that first wait.
+ */
+export declare const retryDelay: (attempt: number) => (error: ActorError) => Duration.Duration;

package/dist/runtime/retry.js

@@ -0,0 +1,11 @@
+import { Duration, Option } from "effect";
+const CAP_MS = 500;
+/**
+ * The wait before retry `attempt` (0 for the first) of a delivery that failed
+ * with the given error: its own `retryAfter`, doubling on each attempt, capped at the
+ * greater of 500 ms and that first wait.
+ */
+export const retryDelay = (attempt) => (error) => {
+    const first = Option.getOrElse(error.retryAfter, () => 10);
+    return Duration.millis(Math.min(first * 2 ** attempt, Math.max(first, CAP_MS)));
+};

package/dist/runtime/runner.d.ts

@@ -0,0 +1,93 @@
+import { Context, Duration, Effect, Layer } from "effect";
+import { MessageStorage, RunnerHealth, Runners, RunnerStorage, Sharding, ShardingConfig } from "effect/cluster";
+import { RpcSerialization } from "effect/rpc";
+import { SocketServer } from "effect/socket";
+import { SqlClient } from "effect/sql";
+import { identity } from "./peering/credentials.ts";
+import { mtls } from "./peering/transport.ts";
+import { MailboxRefusals } from "./topology/admission.ts";
+/**
+ * Whether a command to an entity on this runner is encoded and decoded the
+ * way a remote delivery is. Off by default: a local hop hands the owner the
+ * request the runtime built and validated, and only a remote hop needs the
+ * bytes. Test runtimes turn it on so every delivery still checks the request
+ * schema.
+ */
+export declare const LocalRequestSerialization: Context.Reference<boolean>;
+declare const RunnerWiring_base: Context.ServiceClass<RunnerWiring, "@rikalabs/akter/runtime/runner/RunnerWiring", {
+    readonly config: Partial<ShardingConfig.ShardingConfig["Service"]>;
+    readonly sharding: Layer.Layer<Sharding.Sharding, never, ShardingConfig.ShardingConfig | MessageStorage.MessageStorage | RunnerStorage.RunnerStorage | RunnerHealth.RunnerHealth | MailboxRefusals>;
+    readonly storage: (storage: RunnerStorage.RunnerStorage["Service"]) => RunnerStorage.RunnerStorage["Service"];
+    readonly production?: boolean;
+}>;
+/** Package-internal wiring shared by production runners and fault-injecting test runners. */
+export declare class RunnerWiring extends RunnerWiring_base {
+}
+declare const RunnerReadiness_base: Context.ServiceClass<RunnerReadiness, "@rikalabs/akter/runtime/runner/RunnerReadiness", {
+    readonly acquired: (sharding: Pick<Sharding.Sharding["Service"], "hasShardId">) => Effect.Effect<boolean>;
+}>;
+/** The public runner's readiness checks acquired shards, not just a reachable database. */
+export declare class RunnerReadiness extends RunnerReadiness_base {
+}
+/** Builds assignment expectations independently of the runner's local acquisition state. */
+export declare const acquiredShards: Effect.Effect<{
+    readonly acquired: (sharding: Pick<Sharding.Sharding["Service"], "hasShardId">) => Effect.Effect<boolean>;
+}, never, RunnerStorage.RunnerStorage | ShardingConfig.ShardingConfig>;
+/** Production TCP runner configuration. All runners use the same shard count and lock expiration. */
+export interface SocketRunnerOptions<E> {
+    /** A unique, stable address reachable directly by every other runner; never a load-balancer address. */
+    readonly address: {
+        readonly host: string;
+        readonly port: number;
+    };
+    /** Bind address, defaulting to the advertised address. Use a private interface or an isolated network. */
+    readonly listenAddress?: {
+        readonly host: string;
+        readonly port: number;
+    };
+    /**
+     * Runner-to-runner TCP. `Runner.mtls` authenticates and encrypts it; the
+     * platform's plaintext layers, such as BunClusterSocket's layerSocketServer
+     * and layerClientProtocol, are for an isolated private network only.
+     */
+    readonly transport: Layer.Layer<SocketServer.SocketServer | Runners.RpcClientProtocol, E, ShardingConfig.ShardingConfig | RpcSerialization.RpcSerialization>;
+    /** Default 256; changing this requires stopping every runner. */
+    readonly shardsPerGroup?: number;
+    /** Default 35 seconds; finite and at least 3 seconds. Not an end-to-end recovery deadline. */
+    readonly shardLockExpiration?: Duration.Input;
+    /** Default 10 seconds, capped by Cluster at a third of the expiration. */
+    readonly shardLockRefreshInterval?: Duration.Input;
+    /** Default 1 second. */
+    readonly refreshAssignmentsInterval?: Duration.Input;
+    /** Default 15 seconds, bounding activation shutdown during a shard handoff. */
+    readonly entityTerminationTimeout?: Duration.Input;
+}
+/**
+ * Joins separate processes over TCP sockets. Provide this layer to
+ * `Actors.layer`; the framework keeps direct commands, SQL ownership, receipts,
+ * and outbox recovery, rather than enabling Cluster's persisted message store.
+ * A peer can deliver any runner message, so use `Runner.mtls` as the
+ * transport unless the network is isolated to this deployment's runners. The
+ * transport's own services stay in the runtime, so readiness sees whether a
+ * mutual TLS transport can still peer.
+ */
+export declare const socket: <E>(options: SocketRunnerOptions<E>) => Layer.Layer<RunnerWiring, never, never>;
+/**
+ * Runner-to-runner transport and ownership configuration, provided to
+ * `Actors.layer`: `socket` wires a runner, `mtls` is its authenticated
+ * transport, and `identity` is the URI subject alternative name a
+ * deployment's runner certificates carry.
+ */
+export declare const Runner: {
+    socket: typeof socket;
+    mtls: typeof mtls;
+    identity: typeof identity;
+};
+/** Refuses a routing layout mismatch before any runner registers or takes shards. */
+export declare const checkRunnerConfiguration: (wiring: {
+    readonly config: Partial<ShardingConfig.ShardingConfig["Service"]>;
+    readonly sharding: Layer.Layer<Sharding.Sharding, never, ShardingConfig.ShardingConfig | MessageStorage.MessageStorage | RunnerStorage.RunnerStorage | RunnerHealth.RunnerHealth | MailboxRefusals>;
+    readonly storage: (storage: RunnerStorage.RunnerStorage["Service"]) => RunnerStorage.RunnerStorage["Service"];
+    readonly production?: boolean;
+} | undefined) => Effect.Effect<undefined, import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;
+export {};