@rikalabs/akter 0.1.0-alpha.0

package/dist/runtime/telemetry/sampler.js

@@ -0,0 +1,101 @@
+import { Context, Effect } from "effect";
+import { SqlClient } from "effect/sql";
+import { databaseTime } from "../turn/admission.js";
+import { Metrics, record } from "./metrics.js";
+/** Claims at or above this count mark a row as stuck, for intents and subscriptions alike. */
+const STUCK_ATTEMPTS = 8;
+/**
+ * Reports the gauges only the database knows. Each statement reads pending
+ * work or retained history past its horizon, never every stored actor: the
+ * outbox and due subscription rows are the relay's backlog, and events past
+ * `keepEvents` stay only while something pins them. A series that stops
+ * appearing is reported as 0 once, so a recovered subscription or an emptied
+ * kind does not keep its last value. Only due or backing-off subscription rows
+ * have undelivered events, which the partial due index covers, and pinned
+ * events past `keepEvents` are read from the pinned rows alone.
+ */
+export const databaseSampler = () => {
+    const reported = new Map();
+    return Effect.fnUntraced(function* (types) {
+        const sql = yield* SqlClient.SqlClient;
+        const now = yield* databaseTime;
+        const values = new Map();
+        const set = (metric, attributes, value) => {
+            values.set(`${metric.id}${JSON.stringify(attributes)}`, { metric, attributes, value });
+        };
+        const outbox = yield* sql `
+      SELECT kind, count(*)::int AS rows,
+        COALESCE(max(${now}::bigint - due_at_ms) FILTER (WHERE due_at_ms <= ${now}), 0)::text AS lag,
+        count(*) FILTER (WHERE attempts >= ${STUCK_ATTEMPTS})::int AS stuck
+      FROM actor_outbox GROUP BY kind`;
+        for (const kind of ["intent", "job", "feed", "control"]) {
+            const row = outbox.find((found) => found.kind === kind);
+            set(Metrics.outboxRows, { kind }, row?.rows ?? 0);
+            set(Metrics.relayLag, { kind }, Number(row?.lag ?? 0));
+        }
+        set(Metrics.stuckRows, { kind: "intent" }, outbox.find((row) => row.kind === "intent")?.stuck ?? 0);
+        const subscriptions = yield* sql `
+      SELECT s.subscriber_type, s.subscription,
+        max(g.event_sequence - s.delivered)::text AS events,
+        COALESCE(max(${now}::bigint - e.emitted_at_ms), 0)::text AS lag,
+        COALESCE(max(${now}::bigint - s.due_at_ms) FILTER (WHERE s.due_at_ms <= ${now}), 0)::text AS due,
+        count(*) FILTER (WHERE s.attempts >= ${STUCK_ATTEMPTS})::int AS stuck
+      FROM actor_subscriptions s
+      JOIN actor_generations g ON g.routing_key = s.routing_key AND g.tenant_id = s.tenant_id
+        AND g.actor_type = s.source_type AND g.actor_id = s.source_id
+      LEFT JOIN LATERAL (
+        SELECT e.emitted_at_ms FROM actor_events e
+        WHERE e.routing_key = s.routing_key AND e.tenant_id = s.tenant_id
+          AND e.actor_type = s.source_type AND e.actor_id = s.source_id
+          AND e.sequence > s.delivered AND e.event = ANY(s.events)
+        ORDER BY e.sequence LIMIT 1) e ON true
+      WHERE s.active AND s.due_at_ms IS NOT NULL
+      GROUP BY s.subscriber_type, s.subscription`;
+        let subscriptionLag = 0;
+        let subscriptionStuck = 0;
+        for (const row of subscriptions) {
+            const attributes = { subscriber_type: row.subscriber_type, subscription: row.subscription };
+            set(Metrics.subscriptionLagEvents, attributes, Number(row.events));
+            set(Metrics.subscriptionLag, attributes, Number(row.lag));
+            subscriptionLag = Math.max(subscriptionLag, Number(row.due));
+            subscriptionStuck += row.stuck;
+        }
+        set(Metrics.relayLag, { kind: "subscription" }, subscriptionLag);
+        set(Metrics.stuckRows, { kind: "subscription" }, subscriptionStuck);
+        for (const type of types) {
+            const cutoff = now - type.keepEventsMs;
+            const holdCutoff = cutoff - type.holdEventsMs;
+            const [pinned] = yield* sql `
+        SELECT
+          count(*) FILTER (WHERE e.emitted_at_ms > ${holdCutoff} AND e.sequence > s.held)::int AS subscriptions,
+          count(*) FILTER (WHERE e.sequence > w.held)::int AS workflows
+        FROM actor_events e
+        LEFT JOIN LATERAL (
+          SELECT min(s.delivered) AS held FROM actor_subscriptions s
+          WHERE s.routing_key = e.routing_key AND s.tenant_id = e.tenant_id
+            AND s.source_type = e.actor_type AND s.source_id = e.actor_id AND s.active) s ON true
+        LEFT JOIN LATERAL (
+          SELECT min(LEAST(x.event_cursor, COALESCE(w.wait_after, x.event_cursor))) AS held
+          FROM actor_workflow_executions x
+          LEFT JOIN actor_workflow_step w ON w.routing_key = x.routing_key
+            AND w.execution_id = x.execution_id AND w.kind = 'wait' AND w.exit IS NULL
+          WHERE x.routing_key = e.routing_key AND x.tenant_id = e.tenant_id
+            AND x.actor_type = e.actor_type AND x.actor_id = e.actor_id
+            AND x.status <> 'finished') w ON true
+        WHERE e.actor_type = ${type.actorType} AND e.emitted_at_ms <= ${cutoff}`;
+            set(Metrics.subscriptionPinned, { actor_type: type.actorType }, pinned?.subscriptions ?? 0);
+            set(Metrics.workflowPinned, { actor_type: type.actorType }, pinned?.workflows ?? 0);
+        }
+        for (const [key, series] of reported)
+            if (!values.has(key))
+                yield* record(series.metric, series.attributes, 0);
+        reported.clear();
+        for (const [key, { metric, attributes, value }] of values) {
+            yield* record(metric, attributes, value);
+            reported.set(key, { metric, attributes });
+        }
+    });
+};
+/** Samples the database gauges at once; the runtime also samples every `observability.sampleEvery`. */
+export class TelemetrySampler extends Context.Service()("@rikalabs/akter/runtime/telemetry/sampler/TelemetrySampler") {
+}

package/dist/runtime/telemetry/spans.d.ts

@@ -0,0 +1,38 @@
+import type { Request } from "../request.ts";
+/**
+ * Span names are public: dashboards, alerts, and `durable defects list` match
+ * on them, so a rename is a breaking change. Every name is bounded by the
+ * deployment's declarations, never by an actor id or command id; those are
+ * attributes.
+ */
+export declare const SpanNames: {
+    /** One command's admission on the runner that received it, from the receipt probe to the reply. */
+    readonly admission: "akter.admission";
+    /** One command turn on the actor's owner. */
+    readonly turn: (actor: string, command: string) => string;
+    /** One turn batch on the actor's owner: the commands that were waiting, run in one transaction. */
+    readonly batch: (actor: string) => string;
+    /** The turn's commit group, from the first staged write to the `COMMIT` reply. */
+    readonly commit: "akter.commit";
+    /** One relay delivery of an intent, timer, or cron tick. */
+    readonly relayIntent: "akter.relay.intent";
+    /** One relay delivery pass over a claimed subscription row. */
+    readonly relaySubscription: "akter.relay.subscription";
+    /** One executor attempt of a job. */
+    readonly job: (actor: string, job: string) => string;
+};
+/**
+ * What started a turn: `command` for an external caller, or the System
+ * source of a relay, workflow, or job route delivery.
+ */
+export declare const triggerOf: (request: Request) => "actor" | "command" | "cron" | "job" | "process" | "subscription" | "timer" | "workflow";
+/** Attributes every admission and turn span carries; none is a credential or payload. */
+export declare const requestAttributes: (request: Request) => {
+    "actor.type": string;
+    "actor.tenant": string;
+    "actor.id": string;
+    "command.name": string;
+    "command.id": string;
+    "caller.kind": "Anonymous" | "System" | "User";
+    "turn.trigger": string;
+};

package/dist/runtime/telemetry/spans.js

@@ -0,0 +1,44 @@
+import { Schema } from "effect";
+import { System } from "../../identity/caller.js";
+/**
+ * Span names are public: dashboards, alerts, and `durable defects list` match
+ * on them, so a rename is a breaking change. Every name is bounded by the
+ * deployment's declarations, never by an actor id or command id; those are
+ * attributes.
+ */
+export const SpanNames = {
+    /** One command's admission on the runner that received it, from the receipt probe to the reply. */
+    admission: "akter.admission",
+    /** One command turn on the actor's owner. */
+    turn: (actor, command) => `akter.${actor}/${command}`,
+    /** One turn batch on the actor's owner: the commands that were waiting, run in one transaction. */
+    batch: (actor) => `akter.${actor}/batch`,
+    /** The turn's commit group, from the first staged write to the `COMMIT` reply. */
+    commit: "akter.commit",
+    /** One relay delivery of an intent, timer, or cron tick. */
+    relayIntent: "akter.relay.intent",
+    /** One relay delivery pass over a claimed subscription row. */
+    relaySubscription: "akter.relay.subscription",
+    /** One executor attempt of a job. */
+    job: (actor, job) => `akter.job/${actor}/${job}`,
+};
+const isSystem = Schema.is(System);
+/**
+ * What started a turn: `command` for an external caller, or the System
+ * source of a relay, workflow, or job route delivery.
+ */
+export const triggerOf = (request) => request.external === true
+    ? "command"
+    : isSystem(request.caller)
+        ? request.caller.source
+        : "command";
+/** Attributes every admission and turn span carries; none is a credential or payload. */
+export const requestAttributes = (request) => ({
+    "actor.type": request.ref.actor,
+    "actor.tenant": request.ref.tenant,
+    "actor.id": request.ref.id,
+    "command.name": request.command,
+    "command.id": request.commandId,
+    "caller.kind": request.caller._tag,
+    "turn.trigger": triggerOf(request),
+});

package/dist/runtime/telemetry/usage.d.ts

@@ -0,0 +1,52 @@
+import { Context, Effect } from "effect";
+import type { SqlClient, SqlError } from "effect/sql";
+import type { ActorRef } from "../../identity/caller.ts";
+/** Commands whose receipts one turn commit newly inserted. */
+export interface UsageCommands {
+    readonly ref: ActorRef;
+    readonly commandIds: ReadonlyArray<string>;
+    /** The runtime's client for this turn: its statement reaches the turn's own transaction. */
+    readonly sql: SqlClient.SqlClient;
+}
+/** A query's answer the runtime is about to return. */
+export interface UsageRead {
+    readonly ref: ActorRef;
+    /**
+     * Identifies one read attempt across a watch's reruns. A watch without one
+     * is not recorded.
+     */
+    readonly requestToken?: string | undefined;
+    readonly watch: boolean;
+    /** The primary database's client. */
+    readonly sql: SqlClient.SqlClient;
+}
+/** The hooks of `UsageAccounting`. */
+export interface UsageAccountingService {
+    readonly commands: (input: UsageCommands) => Effect.Effect<void, SqlError.SqlError>;
+    readonly read: (input: UsageRead) => Effect.Effect<void, SqlError.SqlError>;
+}
+/**
+ * Whether `service` is a host's hook rather than the default. The runtime
+ * recognizes the default by identity and never invokes it, so a runtime
+ * without a host hook allocates, forks and awaits nothing for accounting.
+ */
+export declare const accountsUsage: (service: UsageAccountingService) => boolean;
+/**
+ * An optional hook that lets a host account for the work its actors do
+ * without the framework owning any accounting tables. The default is a
+ * single no-op value the runtime skips, so a self-hosted runtime pays no
+ * cost; a host that provides any other service, even one doing nothing, is
+ * invoked.
+ *
+ * `commands` is queued in the turn's commit group directly after the
+ * receipt insert, so its rows commit or roll back with the receipts. The
+ * group is pipelined: the returned effect must issue exactly one statement on
+ * the given `sql`, because a second one could be sent after the group's
+ * `COMMIT`. It sees only commands whose receipts are new; a replay never
+ * reaches it.
+ *
+ * `read` runs on the primary after the query's final access check and before
+ * a non-defect outcome is returned. A failure of either hook fails the work
+ * it accounts for.
+ */
+export declare const UsageAccounting: Context.Reference<UsageAccountingService>;

package/dist/runtime/telemetry/usage.js

@@ -0,0 +1,30 @@
+import { Context, Effect } from "effect";
+const noUsageAccounting = {
+    commands: () => Effect.void,
+    read: () => Effect.void,
+};
+/**
+ * Whether `service` is a host's hook rather than the default. The runtime
+ * recognizes the default by identity and never invokes it, so a runtime
+ * without a host hook allocates, forks and awaits nothing for accounting.
+ */
+export const accountsUsage = (service) => service !== noUsageAccounting;
+/**
+ * An optional hook that lets a host account for the work its actors do
+ * without the framework owning any accounting tables. The default is a
+ * single no-op value the runtime skips, so a self-hosted runtime pays no
+ * cost; a host that provides any other service, even one doing nothing, is
+ * invoked.
+ *
+ * `commands` is queued in the turn's commit group directly after the
+ * receipt insert, so its rows commit or roll back with the receipts. The
+ * group is pipelined: the returned effect must issue exactly one statement on
+ * the given `sql`, because a second one could be sent after the group's
+ * `COMMIT`. It sees only commands whose receipts are new; a replay never
+ * reaches it.
+ *
+ * `read` runs on the primary after the query's final access check and before
+ * a non-defect outcome is returned. A failure of either hook fails the work
+ * it accounts for.
+ */
+export const UsageAccounting = Context.Reference("@rikalabs/akter/runtime/telemetry/usage/UsageAccounting", { defaultValue: () => noUsageAccounting });

package/dist/runtime/topology/admission.d.ts

@@ -0,0 +1,13 @@
+import { Context, Layer } from "effect";
+import { EntityAddress, Sharding } from "effect/cluster";
+import { ActorError } from "../../errors/actor.ts";
+declare const MailboxRefusals_base: Context.ServiceClass<MailboxRefusals, "@rikalabs/akter/runtime/topology/admission/MailboxRefusals", {
+    refuse: (address: EntityAddress.EntityAddress) => ActorError | undefined;
+}>;
+/** The owner classifies transient capacity errors using its own activation residency. */
+export declare class MailboxRefusals extends MailboxRefusals_base {
+}
+export declare const mailboxRefusals: Layer.Layer<MailboxRefusals, never, never>;
+/** Returns resident mailbox refusals through Execute's typed reply instead of a transport error. */
+export declare const admissionSharding: Layer.Layer<Sharding.Sharding, never, MailboxRefusals | import("effect/cluster/MessageStorage").MessageStorage | import("effect/cluster/RunnerHealth").RunnerHealth | import("effect/cluster/RunnerStorage").RunnerStorage | import("effect/cluster/Runners").Runners | import("effect/cluster/ShardingConfig").ShardingConfig>;
+export {};

package/dist/runtime/topology/admission.js

@@ -0,0 +1,36 @@
+import { Context, Effect, Exit, Layer, Predicate, Schema } from "effect";
+import { ClusterError, EntityAddress, Reply, Sharding } from "effect/cluster";
+import { ActorError } from "../../errors/actor.js";
+import { commandEntity } from "../entity/register.js";
+/** The owner classifies transient capacity errors using its own activation residency. */
+export class MailboxRefusals extends Context.Service()("@rikalabs/akter/runtime/topology/admission/MailboxRefusals") {
+}
+export const mailboxRefusals = Layer.sync(MailboxRefusals, () => ({ refuse: () => undefined }));
+/** Returns resident mailbox refusals through Execute's typed reply instead of a transport error. */
+export const admissionSharding = Layer.effect(Sharding.Sharding, Effect.gen(function* () {
+    const sharding = yield* Sharding.Sharding;
+    const refusals = yield* MailboxRefusals;
+    return Sharding.Sharding.of({
+        ...sharding,
+        send: (message) => sharding.send(message).pipe(Effect.catchIf(Schema.is(ClusterError.MailboxFull), (error) => Effect.gen(function* () {
+            if (!Predicate.isTagged(message, "IncomingRequest") ||
+                message.envelope.tag !== "Execute")
+                return yield* error;
+            const refusal = refusals.refuse(error.address);
+            if (refusal === undefined)
+                return yield* error;
+            const reply = new Reply.WithExit({
+                id: yield* sharding.getSnowflake,
+                requestId: message.envelope.requestId,
+                exit: Exit.fail(refusal),
+            });
+            yield* message
+                .respond(new Reply.ReplyWithContext({
+                reply,
+                rpc: commandEntity(error.address.entityType).protocol.requests.get("Execute"),
+                context: Context.empty(),
+            }))
+                .pipe(Effect.orDie);
+        }))),
+    });
+})).pipe(Layer.provide(Sharding.layer));

package/dist/runtime/topology/locks.d.ts

@@ -0,0 +1,56 @@
+import { Context, Duration, Effect } from "effect";
+import { type RunnerAddress, type RunnerStorage, type ShardId } from "effect/cluster";
+import { SqlClient } from "effect/sql";
+/** Builds Cluster registrations and lock storage on the deployment's authority, never on a runner's data shard. */
+export declare const coordinatedRunnerStorage: Effect.Effect<{
+    readonly register: (runner: import("effect/cluster/Runner").Runner, healthy: boolean) => Effect.Effect<import("effect/cluster/MachineId").MachineId, import("effect/cluster/ClusterError").PersistenceError>;
+    readonly unregister: (address: import("effect/cluster/RunnerAddress").RunnerAddress) => Effect.Effect<void, import("effect/cluster/ClusterError").PersistenceError>;
+    readonly getRunners: Effect.Effect<Array<readonly [runner: import("effect/cluster/Runner").Runner, healthy: boolean]>, import("effect/cluster/ClusterError").PersistenceError>;
+    readonly setRunnerHealth: (address: import("effect/cluster/RunnerAddress").RunnerAddress, healthy: boolean) => Effect.Effect<void, import("effect/cluster/ClusterError").PersistenceError>;
+    readonly acquire: (address: import("effect/cluster/RunnerAddress").RunnerAddress, shardIds: Iterable<ShardId.ShardId>) => Effect.Effect<Array<ShardId.ShardId>, import("effect/cluster/ClusterError").PersistenceError>;
+    readonly refresh: (address: import("effect/cluster/RunnerAddress").RunnerAddress, shardIds: Iterable<ShardId.ShardId>) => Effect.Effect<Array<ShardId.ShardId>, import("effect/cluster/ClusterError").PersistenceError>;
+    readonly release: (address: import("effect/cluster/RunnerAddress").RunnerAddress, shardId: ShardId.ShardId) => Effect.Effect<void, import("effect/cluster/ClusterError").PersistenceError>;
+    readonly releaseAll: (address: import("effect/cluster/RunnerAddress").RunnerAddress) => Effect.Effect<void, import("effect/cluster/ClusterError").PersistenceError>;
+}, import("effect/sql/SqlError").SqlError, import("effect/Scope").Scope | import("effect/cluster/ShardingConfig").ShardingConfig | SqlClient.SqlClient>;
+declare const ShardLease_base: Context.ServiceClass<ShardLease, "@rikalabs/akter/runtime/topology/locks/ShardLease", {
+    /** How often a resident singleton rechecks its lease. */
+    readonly interval: Duration.Duration;
+    readonly holds: (shardId: string) => Effect.Effect<boolean>;
+}>;
+/**
+ * Whether this runner still holds a shard's lock, read from the database. A
+ * runner whose lock refreshes stall keeps serving its shards in memory until
+ * it notices; singleton activations check this lease so their background work
+ * stops before another runner can take the shard.
+ */
+export declare class ShardLease extends ShardLease_base {
+}
+/**
+ * The lease of table-backed shard locks. A lock counts as held only while its
+ * last refresh is younger than half the expiration, so its holder stops
+ * before the lock expires and another runner may acquire it; a healthy runner
+ * refreshes at least every third of the expiration. A failed read counts as
+ * lost.
+ */
+export declare const tableShardLease: ({ sql, address, expiration, }: {
+    readonly sql: SqlClient.SqlClient;
+    readonly address: RunnerAddress.RunnerAddress;
+    readonly expiration: Duration.Duration;
+}) => {
+    /** How often a resident singleton rechecks its lease. */
+    readonly interval: Duration.Duration;
+    readonly holds: (shardId: string) => Effect.Effect<boolean>;
+};
+/**
+ * Keeps Cluster from dropping a shard it has just acquired.
+ *
+ * Cluster treats every held shard missing from a lock refresh's answer as
+ * lost, but it builds the refresh request from the shards it held when the
+ * refresh started. A shard whose acquire commits in between is missing from
+ * the answer without being lost, and Cluster reacquires it only on its next
+ * entity poll. Each acquired shard is reported as held by its runner's
+ * refreshes until one asks about it, which checks it for real, or until it is
+ * released.
+ */
+export declare const keepAcquiredShards: (storage: RunnerStorage.RunnerStorage["Service"]) => RunnerStorage.RunnerStorage["Service"];
+export {};

package/dist/runtime/topology/locks.js

@@ -0,0 +1,81 @@
+import { Context, Duration, Effect, PrimaryKey } from "effect";
+import { SqlRunnerStorage, } from "effect/cluster";
+import { SqlClient } from "effect/sql";
+import { Coordination } from "../database/coordination.js";
+import { prepareRunnerStorage } from "../database/neki/migrations.js";
+/** Builds Cluster registrations and lock storage on the deployment's authority, never on a runner's data shard. */
+export const coordinatedRunnerStorage = Effect.gen(function* () {
+    const sql = (yield* Coordination) ?? (yield* SqlClient.SqlClient);
+    return yield* prepareRunnerStorage.pipe(Effect.andThen(SqlRunnerStorage.make({})), Effect.provideService(SqlClient.SqlClient, sql));
+});
+/**
+ * Whether this runner still holds a shard's lock, read from the database. A
+ * runner whose lock refreshes stall keeps serving its shards in memory until
+ * it notices; singleton activations check this lease so their background work
+ * stops before another runner can take the shard.
+ */
+export class ShardLease extends Context.Service()("@rikalabs/akter/runtime/topology/locks/ShardLease") {
+}
+/**
+ * The lease of table-backed shard locks. A lock counts as held only while its
+ * last refresh is younger than half the expiration, so its holder stops
+ * before the lock expires and another runner may acquire it; a healthy runner
+ * refreshes at least every third of the expiration. A failed read counts as
+ * lost.
+ */
+export const tableShardLease = ({ sql, address, expiration, }) => {
+    const fresh = Duration.toMillis(expiration) / 2 / 1000;
+    const holder = PrimaryKey.value(address);
+    return ShardLease.of({
+        interval: Duration.divideUnsafe(expiration, 6),
+        holds: (shardId) => sql `SELECT 1 AS held FROM cluster_locks
+        WHERE shard_id = ${shardId} AND address = ${holder}
+          AND acquired_at >= NOW() - make_interval(secs => ${fresh})`.pipe(Effect.map((rows) => rows.length > 0), Effect.orElseSucceed(() => false)),
+    });
+};
+/**
+ * Keeps Cluster from dropping a shard it has just acquired.
+ *
+ * Cluster treats every held shard missing from a lock refresh's answer as
+ * lost, but it builds the refresh request from the shards it held when the
+ * refresh started. A shard whose acquire commits in between is missing from
+ * the answer without being lost, and Cluster reacquires it only on its next
+ * entity poll. Each acquired shard is reported as held by its runner's
+ * refreshes until one asks about it, which checks it for real, or until it is
+ * released.
+ */
+export const keepAcquiredShards = (storage) => {
+    const unchecked = new Map();
+    const of = (address) => {
+        const key = PrimaryKey.value(address);
+        const shards = unchecked.get(key) ?? new Set();
+        unchecked.set(key, shards);
+        return shards;
+    };
+    return {
+        ...storage,
+        acquire: (address, shardIds) => storage.acquire(address, shardIds).pipe(Effect.tap((acquired) => Effect.sync(() => {
+            const shards = of(address);
+            for (const shardId of acquired)
+                shards.add(shardId);
+        }))),
+        refresh: (address, shardIds) => Effect.suspend(() => {
+            const requested = Array.from(shardIds);
+            const shards = of(address);
+            for (const shardId of requested)
+                shards.delete(shardId);
+            return storage
+                .refresh(address, requested)
+                .pipe(Effect.map((held) => [
+                ...held,
+                ...Array.from(unchecked.get(PrimaryKey.value(address)) ?? []).filter((shardId) => !requested.includes(shardId)),
+            ]));
+        }),
+        release: (address, shardId) => Effect.sync(() => of(address).delete(shardId)).pipe(Effect.andThen(storage.release(address, shardId))),
+        releaseAll: (address) => Effect.sync(() => {
+            const key = PrimaryKey.value(address);
+            unchecked.get(key)?.clear();
+            unchecked.delete(key);
+        }).pipe(Effect.andThen(storage.releaseAll(address))),
+    };
+};

package/dist/runtime/topology/messages.d.ts

@@ -0,0 +1,15 @@
+import { Layer } from "effect";
+import { MessageStorage } from "effect/cluster";
+/**
+ * Cluster message storage for direct commands: it keeps nothing, and the
+ * command's receipt is the only deduplication record.
+ *
+ * It is deliberately not `MessageStorage.noop`. Each entity manager records
+ * every request id it answers, and only Sharding's storage-read loop forgets
+ * them, once per poll; Sharding starts that loop for any storage except
+ * `noop`. Under `noop` the set grows by one id per command for the runner's
+ * lifetime. Here the loop runs, reads nothing, and forgets the ids, so a
+ * request id redelivered after a poll is admitted again and answered from
+ * its receipt. Persisting a message dies, as it does under `noop`.
+ */
+export declare const directMessages: Layer.Layer<MessageStorage.MessageStorage>;

package/dist/runtime/topology/messages.js

@@ -0,0 +1,32 @@
+import { Effect, Layer } from "effect";
+import { MessageStorage } from "effect/cluster";
+const persisted = (operation) => Effect.die(new Error(`${operation}: commands are direct, so no Cluster message is persisted`));
+/**
+ * Cluster message storage for direct commands: it keeps nothing, and the
+ * command's receipt is the only deduplication record.
+ *
+ * It is deliberately not `MessageStorage.noop`. Each entity manager records
+ * every request id it answers, and only Sharding's storage-read loop forgets
+ * them, once per poll; Sharding starts that loop for any storage except
+ * `noop`. Under `noop` the set grows by one id per command for the runner's
+ * lifetime. Here the loop runs, reads nothing, and forgets the ids, so a
+ * request id redelivered after a poll is admitted again and answered from
+ * its receipt. Persisting a message dies, as it does under `noop`.
+ */
+export const directMessages = Layer.effect(MessageStorage.MessageStorage, MessageStorage.make({
+    saveRequest: () => persisted("saveRequest"),
+    saveEnvelope: () => persisted("saveEnvelope"),
+    saveReply: (reply) => Effect.succeed(reply),
+    clearReplies: () => Effect.void,
+    repliesFor: () => Effect.succeed([]),
+    repliesForUnfiltered: () => Effect.succeed([]),
+    requestIdForPrimaryKey: () => Effect.succeedNone,
+    unprocessedMessages: () => Effect.succeed([]),
+    unprocessedMessagesById: () => Effect.succeed([]),
+    resetAddress: () => Effect.void,
+    resetRequests: () => Effect.void,
+    resetAddresses: () => Effect.void,
+    clearAddress: () => Effect.void,
+    resetShards: () => Effect.void,
+    withTransaction: (effect) => effect,
+}));

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

@@ -0,0 +1,22 @@
+import { Context, Effect } from "effect";
+import { SqlClient } from "effect/sql";
+import { ActorError } from "../../errors/actor.ts";
+/**
+ * Shifts the framework clock: command ids, their expiry, timers, event
+ * timestamps, and retention all read database time plus this offset. Only
+ * `ActorTest.advance` moves it, so every one of them moves together.
+ */
+export declare const FrameworkClock: Context.Reference<{
+    readonly offsetMillis: () => number;
+}>;
+/** The database clock as the framework sees it, in epoch milliseconds. */
+export declare const databaseTime: Effect.Effect<number, import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;
+/**
+ * Validates a command id against the admission clock. Fails with `ActorError`:
+ * `InvalidCommandId` when the id is not a version-1 id (`version` for another
+ * version, `malformed` otherwise), its window differs from `windowMs`
+ * (`window`), or it is issued after `now` (`future`); `CommandExpired` once
+ * `now` reaches its expiry. All times are epoch milliseconds. Without `now`
+ * only the id's form and window are checked, which needs no clock read.
+ */
+export declare const checkIdentity: (id: string, windowMs: number, now?: number | undefined) => Effect.Effect<undefined, ActorError, never>;

package/dist/runtime/turn/admission.js

@@ -0,0 +1,41 @@
+import { Context, Effect, Schema } from "effect";
+import { SqlClient } from "effect/sql";
+import { ActorError, CommandExpired, InvalidCommandId } from "../../errors/actor.js";
+import { CommandId, commandTimes } from "../../identity/command.js";
+/**
+ * Shifts the framework clock: command ids, their expiry, timers, event
+ * timestamps, and retention all read database time plus this offset. Only
+ * `ActorTest.advance` moves it, so every one of them moves together.
+ */
+export const FrameworkClock = Context.Reference("akter/FrameworkClock", { defaultValue: () => ({ offsetMillis: () => 0 }) });
+/** The database clock as the framework sees it, in epoch milliseconds. */
+export const databaseTime = Effect.gen(function* () {
+    const sql = yield* SqlClient.SqlClient;
+    const clock = yield* FrameworkClock;
+    const rows = yield* sql `SELECT floor(extract(epoch FROM clock_timestamp()) * 1000)::text AS now`;
+    return Number(rows[0].now) + clock.offsetMillis();
+});
+const decodeCommandId = Schema.decodeEffect(CommandId);
+/** Matches a versioned command id this runner cannot read: `v<n>.` for any n other than 1. */
+const OTHER_VERSION = /^v(?!1\.)\d{1,9}\./;
+/**
+ * Validates a command id against the admission clock. Fails with `ActorError`:
+ * `InvalidCommandId` when the id is not a version-1 id (`version` for another
+ * version, `malformed` otherwise), its window differs from `windowMs`
+ * (`window`), or it is issued after `now` (`future`); `CommandExpired` once
+ * `now` reaches its expiry. All times are epoch milliseconds. Without `now`
+ * only the id's form and window are checked, which needs no clock read.
+ */
+export const checkIdentity = Effect.fnUntraced(function* (id, windowMs, now) {
+    const invalid = (code) => ActorError.make({ reason: InvalidCommandId.make({ commandId: id, code }) });
+    yield* decodeCommandId(id).pipe(Effect.mapError(() => invalid(OTHER_VERSION.test(id) ? "version" : "malformed")));
+    const { issuedAt, expiresAt } = commandTimes(id);
+    if (expiresAt - issuedAt !== windowMs)
+        return yield* invalid("window");
+    if (now === undefined)
+        return;
+    if (issuedAt > now)
+        return yield* invalid("future");
+    if (now >= expiresAt)
+        return yield* ActorError.make({ reason: CommandExpired.make({ commandId: id }) });
+});

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

@@ -0,0 +1,38 @@
+import { Effect } from "effect";
+import { SqlClient } from "effect/sql";
+import type { BlobAccess, BlobScope } from "../../state/blob.ts";
+import type { ContentStoreImpl } from "../content/store.ts";
+/**
+ * Bytes one entry may hold. `get` returns an entry as one row, and the Postgres
+ * driver closes a connection on any message over 16 MiB, so an entry stays well below it.
+ */
+export declare const MAX_ENTRY_BYTES: number;
+/** What content references need from the runtime: its store, the skew margin, and the clock offset. */
+export interface ContentBinding {
+    readonly store: ContentStoreImpl;
+    readonly skewMs: number;
+    readonly offset: () => number;
+}
+/**
+ * Binds blob capabilities to the calling fiber's turn or query. Every row is
+ * addressed by the trusted scope, so equal blob and entry names of two actors
+ * or tenants never meet; writes run on the turn's connection, inside its
+ * savepoint, and roll back with it. Off-turn contexts get read methods only,
+ * and turns get no content bytes.
+ *
+ * Declared blobs, names, and byte arrays are checked on every call, so misuse
+ * is a defect of the turn. Entry names reject lone surrogates, which Postgres
+ * would turn into U+FFFD and alias another name, and NUL. Byte arrays are
+ * copied on the way in and out, since the caller may reuse its buffer and a
+ * driver may decode into a pooled one. Content references count against the
+ * entry cap with the actor's own entries, and an existing entry stays
+ * writable at the cap; the quota is named only after a write changed nothing.
+ * A set overwrites chunk 0 and drops the rest in one statement that changes
+ * nothing past the quota, so a caught defect leaves the entry whole. Turns of
+ * one actor serialize on its generation lock, so an appended chunk index is
+ * free at insert. Attaching content verifies its grant by MAC without a read
+ * and requires the grant to outlive this shard's clock by the skew margin, so
+ * the tenant shard's sweep sees a horizon past this turn's commit. Content
+ * keys are required only when a content blob is used.
+ */
+export declare const bindBlobs: (scope: BlobScope, write: boolean, content: ContentBinding | undefined) => Effect.Effect<BlobAccess, never, SqlClient.SqlClient>;