@rikalabs/akter 0.1.0-alpha.0

package/dist/runtime/events/append.d.ts

@@ -0,0 +1,192 @@
+import { Effect } from "effect";
+import { SqlClient } from "effect/sql";
+import type { EmittedEvent } from "../members.ts";
+/**
+ * The statement that appends a turn's events inside its transaction, and the
+ * stamp it records once it replies. The caller already holds the actor's
+ * generation row lock, so reserving the next sequence numbers there gives one
+ * gap-free order per actor even when activations race; the counter lives on
+ * the generation row so pruning never lets a sequence be reused. The
+ * reservation and the insert share a statement, so nothing waits on the
+ * reserved numbers.
+ *
+ * The same statement probes the actor's subscription tag summary by key and,
+ * when some subscription follows an emitted class, upserts the actor's one
+ * feed row, due now. So the turn costs the same with no subscribers or ten
+ * thousand, and the relay fans the events out after commit; the stamp's `fed`
+ * says the relay should wake. The upsert resets `attempts`, so a relay
+ * expanding the feed while this commits keeps it due. Routed subscriptions
+ * registered here that name an emitted class get their missing source-side
+ * rows first, starting at this turn's first event. Those rows are widened,
+ * never narrowed, so an older runner cannot shrink one back, and their tag
+ * summary moves in the same statement by the tags the upsert added. The
+ * statement locks the routed rows it reads and builds each upserted row from
+ * the locked version, so the lock precedes the write whatever the plan: a
+ * settle that widened a row, or a cleanup that deleted one, after this
+ * statement's snapshot is read as committed, never counted twice or lost.
+ */
+export declare const eventsStatement: (request: {
+    readonly ref: {
+        readonly tenant: string;
+        readonly actor: string;
+        readonly id: string;
+    };
+    readonly caller: {
+        readonly _tag: "Anonymous";
+    } | {
+        readonly _tag: "System";
+        readonly source: "actor" | "cron" | "job" | "process" | "subscription" | "timer" | "workflow";
+        readonly ref?: {
+            readonly tenant: string;
+            readonly actor: string;
+            readonly id: string;
+        } | undefined;
+        readonly onBehalfOf?: {
+            readonly subject: string;
+        } | undefined;
+        readonly mint?: {
+            readonly commandId: string;
+            readonly ordinal: number;
+        } | undefined;
+    } | {
+        readonly _tag: "User";
+        readonly subject: string;
+    };
+    readonly command: string;
+    readonly commandId: string;
+    readonly payload: string;
+    readonly external?: boolean | undefined;
+    readonly clockOffset?: number | undefined;
+    readonly redelivered?: boolean | undefined;
+    readonly intent?: {
+        readonly tenant: string;
+        readonly actor: string;
+        readonly id: string;
+    } | undefined;
+    readonly delivery?: {
+        readonly subscription: string;
+        readonly sourceType: string;
+        readonly sourceId: string;
+        readonly epoch: string;
+        readonly kind: "event" | "gap" | "rejected";
+        readonly position: string;
+    } | undefined;
+    readonly queuedAtMs?: number | undefined;
+    readonly usageToken?: string | undefined;
+}, routingKey: bigint, events: readonly EmittedEvent[]) => Effect.Effect<{
+    statement: Effect.Effect<void, import("effect/sql/SqlError").SqlError, never>;
+    stamp: {
+        emittedAtMs: number;
+        fed: boolean;
+    };
+}, never, SqlClient.SqlClient>;
+/**
+ * Re-arms the timers of this actor's workflows that wait for one of the
+ * emitted classes; the result says whether the relay should wake.
+ */
+export declare const notifyEvents: (request: {
+    readonly ref: {
+        readonly tenant: string;
+        readonly actor: string;
+        readonly id: string;
+    };
+    readonly caller: {
+        readonly _tag: "Anonymous";
+    } | {
+        readonly _tag: "System";
+        readonly source: "actor" | "cron" | "job" | "process" | "subscription" | "timer" | "workflow";
+        readonly ref?: {
+            readonly tenant: string;
+            readonly actor: string;
+            readonly id: string;
+        } | undefined;
+        readonly onBehalfOf?: {
+            readonly subject: string;
+        } | undefined;
+        readonly mint?: {
+            readonly commandId: string;
+            readonly ordinal: number;
+        } | undefined;
+    } | {
+        readonly _tag: "User";
+        readonly subject: string;
+    };
+    readonly command: string;
+    readonly commandId: string;
+    readonly payload: string;
+    readonly external?: boolean | undefined;
+    readonly clockOffset?: number | undefined;
+    readonly redelivered?: boolean | undefined;
+    readonly intent?: {
+        readonly tenant: string;
+        readonly actor: string;
+        readonly id: string;
+    } | undefined;
+    readonly delivery?: {
+        readonly subscription: string;
+        readonly sourceType: string;
+        readonly sourceId: string;
+        readonly epoch: string;
+        readonly kind: "event" | "gap" | "rejected";
+        readonly position: string;
+    } | undefined;
+    readonly queuedAtMs?: number | undefined;
+    readonly usageToken?: string | undefined;
+}, routingKey: bigint, events: readonly EmittedEvent[], waited: ReadonlySet<string>) => Effect.Effect<boolean, import("effect/sql/SqlError").SqlError, import("effect/Crypto").Crypto | SqlClient.SqlClient>;
+/**
+ * Appends a turn's events and notifies their waiting workflows, one statement
+ * at a time; the result says whether the relay should wake, and when the
+ * events were stamped.
+ */
+export declare const appendEvents: (request: {
+    readonly ref: {
+        readonly tenant: string;
+        readonly actor: string;
+        readonly id: string;
+    };
+    readonly caller: {
+        readonly _tag: "Anonymous";
+    } | {
+        readonly _tag: "System";
+        readonly source: "actor" | "cron" | "job" | "process" | "subscription" | "timer" | "workflow";
+        readonly ref?: {
+            readonly tenant: string;
+            readonly actor: string;
+            readonly id: string;
+        } | undefined;
+        readonly onBehalfOf?: {
+            readonly subject: string;
+        } | undefined;
+        readonly mint?: {
+            readonly commandId: string;
+            readonly ordinal: number;
+        } | undefined;
+    } | {
+        readonly _tag: "User";
+        readonly subject: string;
+    };
+    readonly command: string;
+    readonly commandId: string;
+    readonly payload: string;
+    readonly external?: boolean | undefined;
+    readonly clockOffset?: number | undefined;
+    readonly redelivered?: boolean | undefined;
+    readonly intent?: {
+        readonly tenant: string;
+        readonly actor: string;
+        readonly id: string;
+    } | undefined;
+    readonly delivery?: {
+        readonly subscription: string;
+        readonly sourceType: string;
+        readonly sourceId: string;
+        readonly epoch: string;
+        readonly kind: "event" | "gap" | "rejected";
+        readonly position: string;
+    } | undefined;
+    readonly queuedAtMs?: number | undefined;
+    readonly usageToken?: string | undefined;
+}, routingKey: bigint, events: readonly EmittedEvent[], waited?: ReadonlySet<string> | undefined) => Effect.Effect<{
+    notified: boolean;
+    emittedAtMs: number;
+}, import("effect/sql/SqlError").SqlError, import("effect/Crypto").Crypto | SqlClient.SqlClient>;

package/dist/runtime/events/append.js

@@ -0,0 +1,128 @@
+import { Effect, Schema } from "effect";
+import { SqlClient } from "effect/sql";
+import { System } from "../../identity/caller.js";
+import { FrameworkClock } from "../turn/admission.js";
+import { bucketOf, CallerJson, OutboxRuntime, textArray } from "../turn/outbox.js";
+import { compress } from "../storage/codec.js";
+import { notifyWaits } from "../workflows/engine.js";
+import { summarize } from "../subscriptions/storage.js";
+/** The outbox key of an actor's feed row, which tells the relay to expand its subscriptions. */
+const FEED_KEY = "$feed";
+/**
+ * The statement that appends a turn's events inside its transaction, and the
+ * stamp it records once it replies. The caller already holds the actor's
+ * generation row lock, so reserving the next sequence numbers there gives one
+ * gap-free order per actor even when activations race; the counter lives on
+ * the generation row so pruning never lets a sequence be reused. The
+ * reservation and the insert share a statement, so nothing waits on the
+ * reserved numbers.
+ *
+ * The same statement probes the actor's subscription tag summary by key and,
+ * when some subscription follows an emitted class, upserts the actor's one
+ * feed row, due now. So the turn costs the same with no subscribers or ten
+ * thousand, and the relay fans the events out after commit; the stamp's `fed`
+ * says the relay should wake. The upsert resets `attempts`, so a relay
+ * expanding the feed while this commits keeps it due. Routed subscriptions
+ * registered here that name an emitted class get their missing source-side
+ * rows first, starting at this turn's first event. Those rows are widened,
+ * never narrowed, so an older runner cannot shrink one back, and their tag
+ * summary moves in the same statement by the tags the upsert added. The
+ * statement locks the routed rows it reads and builds each upserted row from
+ * the locked version, so the lock precedes the write whatever the plan: a
+ * settle that widened a row, or a cleanup that deleted one, after this
+ * statement's snapshot is read as committed, never counted twice or lost.
+ */
+export const eventsStatement = Effect.fnUntraced(function* (request, routingKey, events) {
+    const sql = yield* SqlClient.SqlClient;
+    const clock = yield* FrameworkClock;
+    const outbox = yield* OutboxRuntime;
+    const { tenant, actor, id } = request.ref;
+    const stamp = { emittedAtMs: 0, fed: false };
+    const emitted = [...new Set(events.map((event) => event.tag))];
+    const routed = outbox
+        .routed(actor)
+        .filter((sub) => sub.events.some((tag) => emitted.includes(tag)));
+    const values = sql.csv(events.map((event, index) => sql `(${index + 1}::bigint, ${event.tag}::text, ${compress(event.value)}::bytea, ${event.version}::int)`));
+    const source = (alias) => sql `${sql(alias)}.routing_key = ${routingKey} AND ${sql(alias)}.tenant_id = ${tenant}
+      AND ${sql(alias)}.source_type = ${actor} AND ${sql(alias)}.source_id = ${id}`;
+    const caller = yield* Schema.encodeEffect(CallerJson)(System.make({ source: "actor", ref: request.ref })).pipe(Effect.orDie);
+    const routedRows = routed.length === 0
+        ? sql.literal("")
+        : sql `, routed_want (subscriber_type, subscription, events) AS (
+            VALUES ${sql.csv(routed.map((sub) => sql `(${sub.subscriberType}::text, ${sub.tag}::text, ${textArray({ sql, values: sub.events })})`))}),
+          routed_old AS MATERIALIZED (
+            SELECT s.subscriber_type, s.subscription, s.events FROM actor_subscriptions s
+            JOIN routed_want w USING (subscriber_type, subscription)
+            WHERE ${source("s")} AND s.subscriber_id = ''
+            FOR UPDATE OF s),
+          routed_new AS (
+            INSERT INTO actor_subscriptions (routing_key, tenant_id, source_type, source_id,
+              subscriber_type, subscription, subscriber_id, events, epoch, active, delivered, bucket)
+            SELECT ${routingKey}, ${tenant}, ${actor}, ${id}, w.subscriber_type, w.subscription, '',
+              CASE WHEN o.events IS NULL THEN w.events
+                ELSE ARRAY(SELECT DISTINCT e FROM unnest(o.events || w.events) AS u(e) ORDER BY e) END,
+              0, true, reserved.base, ${bucketOf(routingKey)}
+            FROM routed_want w LEFT JOIN routed_old o USING (subscriber_type, subscription), reserved
+            ON CONFLICT (routing_key, tenant_id, source_type, source_id, subscriber_type, subscription, subscriber_id)
+            DO UPDATE SET events = EXCLUDED.events
+            WHERE NOT actor_subscriptions.events @> EXCLUDED.events
+            RETURNING subscriber_type, subscription, events),
+          routed_changed AS (
+            SELECT ${routingKey}::bigint AS routing_key, ${tenant}::text AS tenant_id,
+              ${actor}::text AS source_type, ${id}::text AS source_id,
+              coalesce(o.events, '{}'::text[]) AS was, n.events AS now
+            FROM routed_new n LEFT JOIN routed_old o USING (subscriber_type, subscription)),
+          ${summarize({ sql, changed: "routed_changed" })}`;
+    const statement = Effect.map(sql `WITH reserved AS (
+      UPDATE actor_generations SET event_sequence = event_sequence + ${events.length}
+      WHERE routing_key = ${routingKey} AND tenant_id = ${tenant} AND actor_type = ${actor} AND actor_id = ${id}
+      RETURNING event_sequence - ${events.length} AS base,
+        floor(extract(epoch FROM clock_timestamp()) * 1000)::bigint + ${clock.offsetMillis()} AS now
+    ),
+    appended AS (
+      INSERT INTO actor_events (routing_key, tenant_id, actor_type, actor_id, sequence, event, command_id, value, emitted_at_ms, payload_version)
+      SELECT ${routingKey}, ${tenant}, ${actor}, ${id}, reserved.base + staged.ordinal, staged.event,
+        ${request.commandId}, staged.value, reserved.now, staged.version
+      FROM reserved, (VALUES ${values}) AS staged (ordinal, event, value, version)
+      RETURNING 1)
+    ${routedRows},
+    feed AS (
+      INSERT INTO actor_outbox (routing_key, intent_id, kind, bucket, due_at_ms, scheduled_at_ms,
+        tenant_id, actor_type, actor_id, timer_key, target_type, target_id, command, payload, caller)
+      SELECT ${routingKey}, gen_random_uuid()::text, 'feed', ${bucketOf(routingKey)}, reserved.now,
+        reserved.now, ${tenant}, ${actor}, ${id}, ${FEED_KEY}, ${actor}, ${id}, ${FEED_KEY}, '', ${caller}
+      FROM reserved
+      WHERE EXISTS (SELECT 1 FROM actor_subscription_tags t
+          WHERE ${source("t")} AND t.event IN ${sql.in(emitted)})
+        ${routed.length === 0 ? sql.literal("") : sql.literal("OR EXISTS (SELECT 1 FROM routed_new)")}
+      ON CONFLICT (routing_key, tenant_id, actor_type, actor_id, timer_key) WHERE timer_key IS NOT NULL
+      DO UPDATE SET due_at_ms = least(actor_outbox.due_at_ms, EXCLUDED.due_at_ms), attempts = 0
+      RETURNING 1)
+    SELECT reserved.now::text AS emitted_at_ms, (SELECT count(*) FROM feed)::int AS fed
+    FROM reserved`, (rows) => {
+        stamp.emittedAtMs = Number(rows[0].emitted_at_ms);
+        stamp.fed = rows[0].fed > 0;
+    });
+    return { statement, stamp };
+});
+/**
+ * Re-arms the timers of this actor's workflows that wait for one of the
+ * emitted classes; the result says whether the relay should wake.
+ */
+export const notifyEvents = Effect.fnUntraced(function* (request, routingKey, events, waited) {
+    const tags = [...new Set(events.map((event) => event.tag))].filter((tag) => waited.has(tag));
+    return tags.length === 0 ? false : yield* notifyWaits(routingKey, request.ref, tags);
+});
+/**
+ * Appends a turn's events and notifies their waiting workflows, one statement
+ * at a time; the result says whether the relay should wake, and when the
+ * events were stamped.
+ */
+export const appendEvents = Effect.fnUntraced(function* (request, routingKey, events, waited = new Set()) {
+    if (events.length === 0)
+        return { notified: false, emittedAtMs: 0 };
+    const { statement, stamp } = yield* eventsStatement(request, routingKey, events);
+    yield* statement;
+    const notified = yield* notifyEvents(request, routingKey, events, waited);
+    return { notified: notified || stamp.fed, emittedAtMs: stamp.emittedAtMs };
+});

package/dist/runtime/events/cursor.d.ts

@@ -0,0 +1,2 @@
+/** True for a canonical cursor a stream could have issued. */
+export declare const isCursor: (cursor: string) => boolean;

package/dist/runtime/events/cursor.js

@@ -0,0 +1,5 @@
+/** A cursor is an event sequence: a non-negative 64-bit integer in canonical decimal. */
+const CURSOR = /^(0|[1-9][0-9]{0,18})$/;
+const MAX_SEQUENCE = 2n ** 63n - 1n;
+/** True for a canonical cursor a stream could have issued. */
+export const isCursor = (cursor) => CURSOR.test(cursor) && BigInt(cursor) <= MAX_SEQUENCE;

package/dist/runtime/events/replay.d.ts

@@ -0,0 +1,20 @@
+import { Effect } from "effect";
+import { SqlClient } from "effect/sql";
+import { RetentionGap, UnknownCursor } from "../../errors/events.ts";
+import type { StoredEvent } from "../members.ts";
+/**
+ * Replays committed events of the given tags after an exclusive cursor, up to `head`,
+ * the last sequence committed when the query read state. Every event up to
+ * `head` had committed by then, so a later read sees each of them unless it
+ * was pruned; the oldest retained event and the matching rows come from one
+ * statement, and because pruning only removes a prefix, an oldest event past
+ * the cursor's successor means history is missing. A page stops after
+ * `limit` matching events.
+ */
+export declare const replayEvents: (ref: {
+    readonly tenant: string;
+    readonly actor: string;
+    readonly id: string;
+}, routingKey: bigint, tags: readonly string[], after: string | undefined, head: bigint, limit: number) => Effect.Effect<(StoredEvent & {
+    readonly tag: string;
+})[], RetentionGap | import("effect/sql/SqlError").SqlError | UnknownCursor, SqlClient.SqlClient>;

package/dist/runtime/events/replay.js

@@ -0,0 +1,45 @@
+import { Effect } from "effect";
+import { SqlClient } from "effect/sql";
+import { RetentionGap, UnknownCursor } from "../../errors/events.js";
+import { decompress } from "../storage/codec.js";
+import { isCursor } from "./cursor.js";
+/**
+ * Replays committed events of the given tags after an exclusive cursor, up to `head`,
+ * the last sequence committed when the query read state. Every event up to
+ * `head` had committed by then, so a later read sees each of them unless it
+ * was pruned; the oldest retained event and the matching rows come from one
+ * statement, and because pruning only removes a prefix, an oldest event past
+ * the cursor's successor means history is missing. A page stops after
+ * `limit` matching events.
+ */
+export const replayEvents = Effect.fnUntraced(function* (ref, routingKey, tags, after, head, limit) {
+    const cursor = after ?? "0";
+    if (!isCursor(cursor) || BigInt(cursor) > head)
+        return yield* UnknownCursor.make({ cursor });
+    const position = BigInt(cursor);
+    const sql = yield* SqlClient.SqlClient;
+    const owner = (alias) => sql `${sql(alias)}.routing_key = ${routingKey} AND ${sql(alias)}.tenant_id = ${ref.tenant}
+      AND ${sql(alias)}.actor_type = ${ref.actor} AND ${sql(alias)}.actor_id = ${ref.id}`;
+    const rows = yield* sql `
+    SELECT (SELECT min(o.sequence)::text FROM actor_events o WHERE ${owner("o")}) AS oldest,
+      e.sequence::text AS sequence, e.event, e.command_id, e.value, e.payload_version,
+      e.emitted_at_ms::text AS emitted_at_ms
+    FROM (VALUES (1)) AS one (x)
+    LEFT JOIN actor_events e ON ${owner("e")} AND e.sequence > ${position}
+      AND e.sequence <= ${head} AND e.event IN ${sql.in(tags)}
+    ORDER BY e.sequence
+    LIMIT ${limit}`;
+    const oldest = rows[0]?.oldest;
+    if (position < head && (oldest == null || BigInt(oldest) > position + 1n))
+        return yield* RetentionGap.make({ cursor });
+    return rows
+        .filter((row) => row.sequence !== null)
+        .map((row) => ({
+        cursor: row.sequence,
+        tag: row.event,
+        commandId: row.command_id,
+        value: decompress(row.value),
+        version: row.payload_version,
+        timestampMs: Number(row.emitted_at_ms),
+    }));
+});

package/dist/runtime/feeds.d.ts

@@ -0,0 +1,26 @@
+import { Context, Crypto, Effect } from "effect";
+import { Sharding } from "effect/cluster";
+import { SqlClient } from "effect/sql";
+import { ActorError } from "../errors/actor.ts";
+import type { InternalActors } from "./actors.ts";
+import type { Registration } from "./members.ts";
+import type { Request } from "./request.ts";
+import type { ActorRef } from "../identity/caller.ts";
+import type { Transport } from "./connections/transport.ts";
+import type { FrameworkClock } from "./turn/admission.ts";
+/**
+ * The runtime's feeds to one subscriber: a page of an actor's committed
+ * events after a cursor, upcast to their current version, and a stream
+ * member's live items from the actor's connection entity. A stream whose
+ * owner lives on another runner is pinged and ends with `SessionEnded` once
+ * that owner is gone.
+ */
+export declare const eventFeeds: ({ registrations, services, allow, sharding, entityId, frameworkClock, transport, }: {
+    readonly registrations: ReadonlyMap<string, Registration>;
+    readonly services: Context.Context<SqlClient.SqlClient | Crypto.Crypto | Sharding.Sharding>;
+    readonly allow: (request: Request, kind?: "command" | "query" | "stream") => Effect.Effect<void, ActorError>;
+    readonly sharding: Sharding.Sharding["Service"];
+    readonly entityId: (ref: ActorRef) => Effect.Effect<string>;
+    readonly frameworkClock: (typeof FrameworkClock)["Service"];
+    readonly transport: Transport;
+}) => Pick<InternalActors["Service"], "readFeed" | "subscribe">;

package/dist/runtime/feeds.js

@@ -0,0 +1,100 @@
+import { Cause, Clock, Context, Crypto, Deferred, Effect, Option, Schedule, Schema, Stream, } from "effect";
+import { Sharding } from "effect/cluster";
+import { SqlClient, SqlError } from "effect/sql";
+import { ActorError, ActorUnavailable, NotCreated, SessionEnded } from "../errors/actor.js";
+import { StreamFailed, StreamItem } from "./connections/protocol.js";
+import { connectionEntity } from "./entity/register.js";
+import { withTenant } from "./database/tenancy.js";
+import { replayEvents } from "./events/replay.js";
+import { routingKey } from "./storage/codec.js";
+/** How often a subscriber checks that a stream's owner on another runner is alive. */
+const OWNER_CHECK_INTERVAL = "1 second";
+const activationEnded = () => ActorError.make({ reason: SessionEnded.make({ cause: "ActivationEnded", resync: false }) });
+/**
+ * The runtime's feeds to one subscriber: a page of an actor's committed
+ * events after a cursor, upcast to their current version, and a stream
+ * member's live items from the actor's connection entity. A stream whose
+ * owner lives on another runner is pinged and ends with `SessionEnded` once
+ * that owner is gone.
+ */
+export const eventFeeds = ({ registrations, services, allow, sharding, entityId, frameworkClock, transport, }) => ({
+    readFeed: Effect.fnUntraced(function* (ref, tags, after, limit) {
+        const registration = registrations.get(ref.actor);
+        if (registration === undefined)
+            return yield* ActorError.make({
+                reason: ActorUnavailable.make({ cause: new Error("Actor not registered") }),
+            });
+        const key = routingKey({ ref, placement: registration.placement });
+        const sql = yield* SqlClient.SqlClient;
+        const events = yield* Effect.gen(function* () {
+            const [row] = yield* sql `
+          SELECT event_sequence::text AS head FROM actor_generations
+          WHERE routing_key = ${key} AND tenant_id = ${ref.tenant}
+            AND actor_type = ${ref.actor} AND actor_id = ${ref.id}`;
+            if (row === undefined)
+                return yield* ActorError.make({ reason: NotCreated.make({}) });
+            return yield* replayEvents(ref, key, tags, after, BigInt(row.head), limit);
+        }).pipe(withTenant(ref.tenant));
+        return yield* Effect.forEach(events, (event) => registration.upcastEvent(event.tag, event.version, event.value).pipe(Effect.map((value) => ({
+            cursor: event.cursor,
+            tag: event.tag,
+            commandId: event.commandId,
+            value,
+            timestampMs: event.timestampMs,
+        }))));
+    }, Effect.provideContext(services), Effect.catchIf(SqlError.isSqlError, (cause) => Effect.fail(ActorError.make({ reason: ActorUnavailable.make({ cause }) })))),
+    subscribe: (request) => Stream.unwrap(Effect.gen(function* () {
+        const registration = registrations.get(request.ref.actor);
+        if (registration === undefined || !registration.streams.has(request.command))
+            return yield* ActorError.make({
+                reason: ActorUnavailable.make({ cause: new Error("Stream not registered") }),
+            });
+        yield* allow(request, "stream");
+        const client = (yield* sharding.makeClient(connectionEntity(request.ref.actor)))(yield* entityId(request.ref));
+        const authorizedUntil = (yield* Clock.currentTimeMillis) +
+            frameworkClock.offsetMillis() +
+            registration.policy.reauthorizeMs;
+        const started = yield* Deferred.make();
+        const lost = yield* Deferred.make();
+        let owner;
+        yield* Deferred.await(started).pipe(Effect.flatMap(({ owner, ownerEpoch }) => owner === transport.holder
+            ? Effect.never
+            : transport.ping(owner, ownerEpoch).pipe(Effect.repeat({
+                schedule: Schedule.spaced(OWNER_CHECK_INTERVAL),
+                while: (alive) => alive,
+            }), Effect.andThen(Deferred.fail(lost, activationEnded())))), Effect.forkScoped);
+        let finished = false;
+        return client
+            .Subscribe({
+            member: request.command,
+            caller: request.caller,
+            input: request.payload,
+            authorizedUntil,
+        })
+            .pipe(Stream.tap((item) => Effect.gen(function* () {
+            if (StreamItem.guards.Done(item))
+                finished = true;
+            if (!StreamItem.guards.Started(item))
+                return;
+            if (owner !== undefined)
+                return yield* activationEnded();
+            owner = item;
+            yield* Deferred.succeed(started, item);
+        })), Stream.takeWhile((item) => !StreamItem.guards.Done(item)), Stream.filter(StreamItem.guards.Element), Stream.map((item) => item.value), Stream.concat(Stream.fromEffect(Effect.suspend(() => (finished ? Effect.void : activationEnded()))).pipe(Stream.drain)), Stream.interruptWhen(Deferred.await(lost)), Stream.catchCause((cause) => {
+            const failure = Cause.findErrorOption(cause);
+            if (Option.isSome(failure)) {
+                if (Schema.is(ActorError)(failure.value))
+                    return Stream.fail(failure.value);
+                if (Schema.is(StreamFailed)(failure.value))
+                    return Stream.fail({ failure: failure.value.value });
+            }
+            if (Cause.hasInterruptsOnly(cause))
+                return Stream.fromEffect(Effect.interrupt);
+            return Stream.fail(owner === undefined
+                ? ActorError.make({
+                    reason: ActorUnavailable.make({ cause: Cause.squash(cause) }),
+                })
+                : activationEnded());
+        }));
+    }).pipe(Effect.provideContext(services))),
+});

package/dist/runtime/fleet/checks.d.ts

@@ -0,0 +1,17 @@
+import { Effect } from "effect";
+import { SqlClient } from "effect/sql";
+import type { AnyFleetView } from "../../tables/fleet.ts";
+import { type ResolvedView } from "./maintainer.ts";
+/** Resolves each view's source and derived table schemas on this database. */
+export declare const resolveViews: (views: readonly AnyFleetView[]) => Effect.Effect<ResolvedView[], import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;
+/**
+ * Refuses to start fleet views on a database that cannot maintain them, each
+ * time naming the fix: `wal_level` below logical, a login without
+ * `REPLICATION`, a source outside the publication or without full replica
+ * identity, a missing or lost slot, a source whose actor type is not placed
+ * by tenant, a source without an index leading with
+ * `(routing_key, tenant_id, …group columns)`, a missing derived table, and a
+ * derived table the tenant role owns, which would let a turn bypass its
+ * policy. Then records each view, marking one whose definition changed stale.
+ */
+export declare const checkFleet: (views: readonly AnyFleetView[], tenantRole: string | undefined) => Effect.Effect<ResolvedView[], import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;

package/dist/runtime/fleet/checks.js

@@ -0,0 +1,106 @@
+import { Clock, Effect } from "effect";
+import { SqlClient } from "effect/sql";
+import { FLEET_PUBLICATION, FLEET_SLOT } from "./maintainer.js";
+const refuse = (message) => Effect.die(new Error(`Fleet views cannot start: ${message}`));
+const currentSchema = Effect.gen(function* () {
+    const sql = yield* SqlClient.SqlClient;
+    return (yield* sql `SELECT current_schema() AS schema`)[0].schema;
+});
+/** Resolves each view's source and derived table schemas on this database. */
+export const resolveViews = Effect.fnUntraced(function* (views) {
+    const schema = yield* currentSchema;
+    return views.map((view) => ({
+        view,
+        sourceSchema: view.source.schema ?? schema,
+        derivedSchema: view.source.schema ?? schema,
+    }));
+});
+/**
+ * Refuses to start fleet views on a database that cannot maintain them, each
+ * time naming the fix: `wal_level` below logical, a login without
+ * `REPLICATION`, a source outside the publication or without full replica
+ * identity, a missing or lost slot, a source whose actor type is not placed
+ * by tenant, a source without an index leading with
+ * `(routing_key, tenant_id, …group columns)`, a missing derived table, and a
+ * derived table the tenant role owns, which would let a turn bypass its
+ * policy. Then records each view, marking one whose definition changed stale.
+ */
+export const checkFleet = Effect.fnUntraced(function* (views, tenantRole) {
+    const sql = yield* SqlClient.SqlClient;
+    const names = views.map(({ name }) => name);
+    if (new Set(names).size !== names.length)
+        return yield* refuse(`a view name is registered twice (${names.join(", ")})`);
+    const [level] = yield* sql `SELECT current_setting('wal_level') AS wal_level`;
+    if (level?.wal_level !== "logical")
+        return yield* refuse(`wal_level is ${level?.wal_level}; set wal_level = logical (ALTER SYSTEM SET wal_level = logical) and restart Postgres`);
+    const [login] = yield* sql `
+    SELECT rolname AS name, rolreplication OR rolsuper AS replication FROM pg_roles
+    WHERE rolname = session_user`;
+    if (login?.replication !== true)
+        return yield* refuse(`login ${login?.name} lacks REPLICATION, which the slot functions need; run ALTER ROLE ${login?.name} REPLICATION`);
+    const resolved = yield* resolveViews(views);
+    for (const { view, sourceSchema, derivedSchema } of resolved) {
+        const source = `${sourceSchema}.${view.source.table}`;
+        if (view.source.owner === undefined)
+            return yield* refuse(`${view.name} reads ${source}, which no Actor.make lists in tables`);
+        if (view.source.placement !== "tenant")
+            return yield* refuse(`${view.name} reads ${source} of actor ${view.source.owner}, which is not placed by tenant; a fleet view needs placement: "tenant"`);
+        const [table] = yield* sql `
+      SELECT c.relreplident AS identity,
+        EXISTS (SELECT 1 FROM pg_publication_tables p WHERE p.pubname = ${FLEET_PUBLICATION}
+          AND p.schemaname = n.nspname AND p.tablename = c.relname) AS published
+      FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+      WHERE n.nspname = ${sourceSchema} AND c.relname = ${view.source.table}`;
+        if (table === undefined)
+            return yield* refuse(`${view.name} reads ${source}, which does not exist; apply its drizzle-kit migration`);
+        if (!table.published)
+            return yield* refuse(`${source} is not in publication ${FLEET_PUBLICATION}; run durable fleet setup`);
+        if (table.identity !== "f")
+            return yield* refuse(`${source} does not have full replica identity; run durable fleet setup (ALTER TABLE ${source} REPLICA IDENTITY FULL)`);
+        const leading = [view.routingColumn, view.tenantColumn, ...view.groupColumns];
+        const indexes = yield* sql `
+      SELECT array(
+          SELECT a.attname FROM unnest(i.indkey::int2[]) WITH ORDINALITY k(attnum, position)
+          JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = k.attnum
+          ORDER BY k.position) AS columns
+      FROM pg_index i JOIN pg_class c ON c.oid = i.indrelid
+      JOIN pg_namespace n ON n.oid = c.relnamespace
+      WHERE n.nspname = ${sourceSchema} AND c.relname = ${view.source.table}
+        AND i.indisvalid AND i.indpred IS NULL`;
+        if (!indexes.some(({ columns }) => leading.every((column, index) => columns[index] === column)))
+            return yield* refuse(`${view.name} recomputes a group with one indexed read of ${source}; create its index: CREATE INDEX ${view.source.table}_${view.tableName.split(".").at(-1)} ON ${source} (${leading.join(", ")})`);
+        const derived = view.tableName.split(".").at(-1);
+        const [owner] = yield* sql `
+      SELECT ${tenantRole === undefined ? sql `false` : sql `pg_has_role(${tenantRole}, c.relowner, 'MEMBER')`}
+        AS owned_by_tenant,
+        ${tenantRole === undefined ? sql `true` : sql `has_table_privilege(${tenantRole}, c.oid, 'SELECT')`}
+        AS readable
+      FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+      WHERE n.nspname = ${derivedSchema} AND c.relname = ${derived}`;
+        if (owner === undefined)
+            return yield* refuse(`the derived table ${derivedSchema}.${derived} of ${view.name} does not exist; add ${view.name}.table to the drizzle-kit schema and apply its migration`);
+        if (!owner.readable)
+            return yield* refuse(`the tenant role ${tenantRole} cannot read ${derivedSchema}.${derived}, which subscriptions read as that role; GRANT SELECT ON ${derivedSchema}.${derived} TO ${tenantRole}`);
+        if (owner.owned_by_tenant)
+            return yield* refuse(`the tenant role ${tenantRole} owns ${derivedSchema}.${derived}, so its policy would not bind it; give the table to another role`);
+    }
+    const [slot] = yield* sql `
+    SELECT wal_status FROM pg_replication_slots
+    WHERE slot_name = ${FLEET_SLOT} AND database = current_database() AND slot_type = 'logical'`;
+    if (slot === undefined)
+        return yield* refuse(`replication slot ${FLEET_SLOT} does not exist; run durable fleet setup`);
+    if (slot.wal_status === "lost")
+        return yield* refuse(`replication slot ${FLEET_SLOT} is lost; run durable fleet setup to recreate it, and every view rebuilds`);
+    const at = yield* Clock.currentTimeMillis;
+    for (const { view, sourceSchema } of resolved) {
+        yield* sql `INSERT INTO actor_fleet_views (view_name, source_schema, source_table, definition_hash,
+        status, applied_lsn, updated_at_ms, last_error)
+      VALUES (${view.name}, ${sourceSchema}, ${view.source.table}, ${view.definitionHash},
+        'building', NULL, ${at}, NULL)
+      ON CONFLICT (view_name) DO UPDATE SET source_schema = EXCLUDED.source_schema,
+        source_table = EXCLUDED.source_table, definition_hash = EXCLUDED.definition_hash,
+        status = 'stale', last_error = NULL, updated_at_ms = EXCLUDED.updated_at_ms
+      WHERE actor_fleet_views.definition_hash <> EXCLUDED.definition_hash`;
+    }
+    return resolved;
+});