@rikalabs/akter 0.1.0-alpha.0

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

@@ -0,0 +1,38 @@
+import { Context, Effect } from "effect";
+import { SqlClient } from "effect/sql";
+import type { AnyFleetView } from "../../tables/fleet.ts";
+/** The logical replication slot and publication every fleet view reads. */
+export declare const FLEET_SLOT = "durable_fleet";
+export declare const FLEET_PUBLICATION = "durable_fleet";
+/** How often a runner without the lock tries to take it. */
+export declare const LOCK_RETRY = "2 seconds";
+/**
+ * Test points of the fleet engine: `afterApply` runs after a batch's derived
+ * rows commit and before the slot advances, where a crash replays the batch;
+ * `poll` and `page` count a runner's subscription reads.
+ */
+export declare const FleetHooks: Context.Reference<{
+    readonly afterApply: Effect.Effect<void>;
+    /** Runs before each read of a view's state by a runner's subscription poller. */
+    readonly poll: (view: string) => Effect.Effect<void>;
+    /** Runs before each page query of a subscription. */
+    readonly page: (view: string) => Effect.Effect<void>;
+}>;
+/** A view with the schema names its tables resolve to on this database. */
+export interface ResolvedView {
+    readonly view: AnyFleetView;
+    readonly sourceSchema: string;
+    readonly derivedSchema: string;
+}
+/**
+ * Maintains every registered view while this runner holds the fleet lock:
+ * peeks a batch of committed changes, recomputes each touched group in one
+ * transaction, commits, and only then advances the slot, so a crash between
+ * the two replays a batch whose recompute is idempotent. When no change is
+ * waiting it rebuilds `building` and `stale` views a few tenants at a time.
+ * A view whose recompute fails is marked stale with its error and skipped
+ * until `durable fleet rebuild`, so it never stops the others. A slot that
+ * is missing, lost, or moved by anyone else marks every view stale. The
+ * runner that cannot take the lock retries every `LOCK_RETRY`.
+ */
+export declare const maintain: (views: readonly ResolvedView[]) => Effect.Effect<void, never, SqlClient.SqlClient>;

package/dist/runtime/fleet/maintainer.js

@@ -0,0 +1,383 @@
+import { sql as fragment } from "drizzle-orm";
+import { PgDialect } from "drizzle-orm/pg-core";
+import { Cause, Clock, Context, Effect, Schedule } from "effect";
+import { SqlClient } from "effect/sql";
+import { Coordination } from "../database/coordination.js";
+import { tenantRoutingKey } from "../storage/codec.js";
+import { count, Metrics, record } from "../telemetry/metrics.js";
+import { filterSql } from "../turn/rows.js";
+import { decode } from "./pgoutput.js";
+/** The logical replication slot and publication every fleet view reads. */
+export const FLEET_SLOT = "durable_fleet";
+export const FLEET_PUBLICATION = "durable_fleet";
+/** The session-level advisory lock the one maintainer holds. */
+const LOCK = "akter/fleet";
+/** Changes asked for per peek; the peek still ends on a transaction boundary. */
+const PEEK_CHANGES = 500;
+/** How often an idle maintainer polls the slot. */
+const POLL_INTERVAL = "200 millis";
+/** How often a runner without the lock tries to take it. */
+export const LOCK_RETRY = "2 seconds";
+/** Groups a rebuild writes per poll: about 200 a second. */
+const REBUILD_GROUPS_PER_POLL = 40;
+/**
+ * Test points of the fleet engine: `afterApply` runs after a batch's derived
+ * rows commit and before the slot advances, where a crash replays the batch;
+ * `poll` and `page` count a runner's subscription reads.
+ */
+export const FleetHooks = Context.Reference("akter/FleetHooks", {
+    defaultValue: () => ({
+        afterApply: Effect.void,
+        poll: () => Effect.void,
+        page: () => Effect.void,
+    }),
+});
+const dialect = new PgDialect();
+const identifier = (name) => `"${name.replaceAll('"', '""')}"`;
+const qualified = (schema, table) => `${identifier(schema)}.${identifier(table)}`;
+/** The SQL of each aggregate over its quoted source column. */
+const AGGREGATE_SQL = {
+    count: () => "count(*)",
+    sum: (column) => `sum(${column})::bigint`,
+    avg: (column) => `avg(${column})::float8`,
+    min: (column) => `min(${column})`,
+    max: (column) => `max(${column})`,
+};
+/**
+ * The statement that recomputes one tenant's groups of `view` from the source
+ * and writes them: an upsert of every group the source still holds, and a
+ * delete of the groups among them it no longer does. `group` narrows it to
+ * one group, as a change batch does; without it the whole tenant is rebuilt.
+ */
+const recomputeStatement = (resolved, tenant, group, asOf) => {
+    const { view } = resolved;
+    const source = qualified(resolved.sourceSchema, view.source.table);
+    const derived = qualified(resolved.derivedSchema, view.tableName.split(".").at(-1));
+    const groupColumns = view.groupColumns.map(identifier);
+    const keys = ["tenant_id", ...groupColumns];
+    const tenantColumn = identifier(view.tenantColumn);
+    const sourceKeys = [`${tenantColumn}::text`, ...groupColumns];
+    const grouping = [tenantColumn, ...groupColumns];
+    const aggregates = view.aggregates.map(({ kind, column }) => AGGREGATE_SQL[kind](identifier(column ?? "")));
+    const columns = [...keys, ...view.aggregates.map(({ key }) => identifier(key)), "as_of"];
+    const filter = view.where === undefined
+        ? undefined
+        : filterSql({ table: view.from, filter: view.where });
+    const equal = (prefix) => group === undefined
+        ? fragment ``
+        : fragment.join(group.map((value, index) => fragment ` AND ${fragment.raw(`${prefix}${groupColumns[index]}`)} = ${value}`));
+    const statement = fragment `WITH fresh AS (
+      INSERT INTO ${fragment.raw(derived)} (${fragment.raw(columns.join(", "))})
+      SELECT ${fragment.raw(sourceKeys.join(", "))}, ${fragment.raw(aggregates.join(", "))}, ${asOf}::numeric
+      FROM ${fragment.raw(source)}
+      WHERE ${fragment.raw(identifier(view.routingColumn))} = ${String(tenantRoutingKey(tenant))}::bigint
+        AND ${fragment.raw(tenantColumn)} = ${tenant}${equal("")}${filter === undefined ? fragment `` : fragment ` AND (${filter})`}
+      GROUP BY ${fragment.raw(grouping.join(", "))}
+      ON CONFLICT (${fragment.raw(keys.join(", "))}) DO UPDATE SET ${fragment.raw([...view.aggregates.map(({ key }) => identifier(key)), "as_of"]
+        .map((column) => `${column} = EXCLUDED.${column}`)
+        .join(", "))}
+      RETURNING ${fragment.raw(groupColumns.join(", "))}),
+    gone AS (
+      DELETE FROM ${fragment.raw(derived)} d WHERE d.tenant_id = ${tenant}${equal("d.")}
+        AND NOT EXISTS (SELECT 1 FROM fresh f WHERE ${fragment.raw(groupColumns.map((column) => `f.${column} = d.${column}`).join(" AND "))})
+      RETURNING 1)
+    SELECT (SELECT count(*) FROM fresh)::int + (SELECT count(*) FROM gone)::int AS groups`;
+    return dialect.sqlToQuery(statement);
+};
+/** The innermost message of an error's cause chain: the database's own words. */
+const innermost = (error) => {
+    let message = error.message;
+    let current = error.cause;
+    while (current instanceof Error) {
+        message = current.message;
+        current = current.cause;
+    }
+    return message;
+};
+/**
+ * Maintains every registered view while this runner holds the fleet lock:
+ * peeks a batch of committed changes, recomputes each touched group in one
+ * transaction, commits, and only then advances the slot, so a crash between
+ * the two replays a batch whose recompute is idempotent. When no change is
+ * waiting it rebuilds `building` and `stale` views a few tenants at a time.
+ * A view whose recompute fails is marked stale with its error and skipped
+ * until `durable fleet rebuild`, so it never stops the others. A slot that
+ * is missing, lost, or moved by anyone else marks every view stale. The
+ * runner that cannot take the lock retries every `LOCK_RETRY`.
+ */
+export const maintain = Effect.fnUntraced(function* (views) {
+    const sql = yield* SqlClient.SqlClient;
+    const coordination = (yield* Coordination) ?? sql;
+    const hooks = yield* FleetHooks;
+    const holding = Effect.gen(function* () {
+        const connection = yield* coordination.reserve;
+        const lockOn = (effect) => Effect.provideService(effect, coordination.transactionService, [connection, 0]);
+        const [lock] = yield* Effect.acquireRelease(lockOn(coordination `SELECT pg_try_advisory_lock(hashtext(${LOCK})) AS locked`), (locks) => locks[0]?.locked === true
+            ? lockOn(coordination `SELECT pg_advisory_unlock(hashtext(${LOCK})) AS unlocked`).pipe(Effect.ignore)
+            : Effect.void);
+        if (lock?.locked !== true)
+            return false;
+        const dataConnection = coordination === sql ? connection : yield* sql.reserve;
+        const on = (effect) => Effect.provideService(effect, sql.transactionService, [dataConnection, 0]);
+        const alive = lockOn(coordination `SELECT 1`).pipe(Effect.andThen(Effect.sleep(POLL_INTERVAL)), Effect.forever);
+        return yield* coordination === sql
+            ? run(views, on, hooks.afterApply)
+            : Effect.raceFirst(run(views, on, hooks.afterApply), alive);
+    }).pipe(Effect.scoped);
+    yield* holding.pipe(Effect.catchCause((cause) => Cause.hasInterruptsOnly(cause)
+        ? Effect.interrupt
+        : Effect.logWarning("Fleet maintainer stopped", cause).pipe(Effect.as(false))), Effect.repeat(Schedule.spaced(LOCK_RETRY)));
+});
+const run = Effect.fnUntraced(function* (views, on, afterApply) {
+    const sql = yield* SqlClient.SqlClient;
+    const relations = new Map();
+    const names = views.map(({ view }) => view.name);
+    const cursors = new Map();
+    let position;
+    const now = Clock.currentTimeMillis;
+    const markAllStale = Effect.gen(function* () {
+        const at = yield* now;
+        yield* on(sql `UPDATE actor_fleet_views SET status = 'stale', updated_at_ms = ${at}
+      WHERE view_name IN ${sql.in(names)} AND status <> 'stale'`);
+        cursors.clear();
+    });
+    const statuses = on(sql `SELECT view_name, status, last_error FROM actor_fleet_views
+      WHERE view_name IN ${sql.in(names)}`).pipe(Effect.map((rows) => new Map(rows.map((row) => [row.view_name, row]))));
+    const recompute = (resolved, tenant, group, asOf) => {
+        const query = recomputeStatement(resolved, tenant, group, asOf);
+        return on(sql.unsafe(query.sql, query.params)).pipe(Effect.map((rows) => rows[0]?.groups ?? 0));
+    };
+    /** Runs `body` for one view inside a savepoint; a failure marks the view stale with its error. */
+    const isolated = (name, body) => on(sql `SAVEPOINT fleet_view`).pipe(Effect.andThen(body), Effect.andThen(on(sql `RELEASE SAVEPOINT fleet_view`)), Effect.as(true), Effect.catchTag("SqlError", (error) => Effect.gen(function* () {
+        yield* on(sql `ROLLBACK TO SAVEPOINT fleet_view`);
+        const at = yield* now;
+        yield* on(sql `UPDATE actor_fleet_views
+            SET status = 'stale', last_error = ${innermost(error)}, updated_at_ms = ${at}
+            WHERE view_name = ${name}`);
+        cursors.delete(name);
+        return false;
+    })));
+    const inTransaction = (body) => on(sql `BEGIN`).pipe(Effect.andThen(body), Effect.tap(() => on(sql `COMMIT`)), Effect.onError(() => on(sql `ROLLBACK`).pipe(Effect.ignore)));
+    const touchedBy = (change, touched, truncated) => {
+        if (change.kind === "relation")
+            relations.set(change.relation.id, change.relation);
+        if (change.kind === "truncate") {
+            for (const id of change.relations) {
+                const relation = relations.get(id);
+                for (const { view, sourceSchema } of views)
+                    if (relation?.schema === sourceSchema && relation.table === view.source.table)
+                        truncated.add(view.name);
+            }
+            return;
+        }
+        if (change.kind !== "insert" && change.kind !== "update" && change.kind !== "delete")
+            return;
+        const relation = relations.get(change.relation);
+        if (relation === undefined)
+            return;
+        const before = change.kind === "insert" ? undefined : change.before;
+        const after = change.kind === "delete" ? undefined : change.after;
+        for (const { view, sourceSchema } of views) {
+            if (relation.schema !== sourceSchema || relation.table !== view.source.table)
+                continue;
+            const indexes = [view.tenantColumn, ...view.groupColumns].map((column) => relation.columns.indexOf(column));
+            const keyOf = (tuple, fallback) => {
+                if (tuple === undefined)
+                    return undefined;
+                const values = [];
+                for (const index of indexes) {
+                    const value = tuple[index] ?? fallback?.[index];
+                    if (value === null || value === undefined)
+                        return undefined;
+                    values.push(value);
+                }
+                const [tenant, ...rest] = values;
+                if (tenant === undefined)
+                    return undefined;
+                const key = [tenant, ...rest];
+                return key;
+            };
+            const groups = touched.get(view.name) ?? new Map();
+            for (const key of [keyOf(before, undefined), keyOf(after, before)])
+                if (key !== undefined)
+                    groups.set(JSON.stringify(key), key);
+            touched.set(view.name, groups);
+        }
+    };
+    const slot = on(sql `
+      SELECT (pg_current_wal_flush_lsn() - '0/0')::text AS flush,
+        (s.confirmed_flush_lsn - '0/0')::text AS confirmed, s.wal_status
+      FROM (SELECT 1) one LEFT JOIN pg_replication_slots s
+        ON s.slot_name = ${FLEET_SLOT} AND s.database = current_database()`).pipe(Effect.map((rows) => rows[0]));
+    /**
+     * A new maintainer trusts the slot's position, unless a ready view has
+     * applied less than it: the slot then moved without this view seeing the
+     * changes between, as when it was dropped and recreated.
+     */
+    const start = Effect.gen(function* () {
+        const found = yield* slot;
+        if (found.confirmed === null || found.wal_status === "lost")
+            return yield* markAllStale;
+        position = found.confirmed;
+        const behind = yield* on(sql `SELECT view_name FROM actor_fleet_views
+        WHERE view_name IN ${sql.in(names)} AND status = 'ready'
+          AND (applied_lsn IS NULL OR applied_lsn < ${position}::numeric)`);
+        if (behind.length > 0)
+            yield* markAllStale;
+    });
+    let drained = yield* now;
+    /** Sets each view's lag gauges: WAL bytes past what was applied, and time since the feed was last drained. */
+    const reportLag = (flush) => Effect.gen(function* () {
+        const bytes = position === undefined ? 0 : Number(BigInt(flush) - BigInt(position));
+        const ms = (yield* now) - drained;
+        for (const name of names) {
+            yield* record(Metrics.fleetLagBytes, { view: name }, bytes);
+            yield* record(Metrics.fleetLag, { view: name }, ms);
+        }
+    });
+    const batch = Effect.gen(function* () {
+        const found = yield* slot;
+        if (found.confirmed === null || found.wal_status === "lost") {
+            if (position !== undefined)
+                yield* markAllStale;
+            position = undefined;
+            return false;
+        }
+        if (position === undefined || BigInt(found.confirmed) > BigInt(position)) {
+            if (position !== undefined)
+                yield* markAllStale;
+            position = found.confirmed;
+        }
+        const rows = yield* on(sql `
+        SELECT encode(data, 'base64') AS data FROM pg_logical_slot_peek_binary_changes(
+          ${FLEET_SLOT}, '0/0'::pg_lsn + ${found.flush}::numeric, ${PEEK_CHANGES},
+          'proto_version', '1', 'publication_names', ${FLEET_PUBLICATION})`);
+        const touched = new Map();
+        const truncated = new Set();
+        let lastEnd;
+        for (const row of rows) {
+            const change = decode(Buffer.from(row.data, "base64"));
+            if (change.kind === "commit")
+                lastEnd = change.end;
+            else
+                touchedBy(change, touched, truncated);
+        }
+        const target = rows.length >= PEEK_CHANGES && lastEnd !== undefined ? String(lastEnd) : found.flush;
+        if (BigInt(target) <= BigInt(position)) {
+            drained = yield* now;
+            yield* reportLag(found.flush);
+            return false;
+        }
+        const status = yield* statuses;
+        const recomputed = new Map();
+        yield* inTransaction(Effect.gen(function* () {
+            const advanced = [];
+            for (const resolved of views) {
+                const name = resolved.view.name;
+                const row = status.get(name);
+                if (row === undefined || row.last_error !== null)
+                    continue;
+                const derived = qualified(resolved.derivedSchema, resolved.view.tableName.split(".").at(-1));
+                const groups = [...(touched.get(name)?.values() ?? [])];
+                const ok = yield* isolated(name, Effect.gen(function* () {
+                    if (truncated.has(name)) {
+                        const tenants = yield* on(sql `SELECT DISTINCT tenant_id FROM ${sql.literal(derived)}`);
+                        for (const { tenant_id } of tenants)
+                            yield* recompute(resolved, tenant_id, undefined, target);
+                    }
+                    for (const [tenant, ...values] of groups)
+                        yield* recompute(resolved, tenant, values, target);
+                }));
+                if (ok)
+                    recomputed.set(name, groups.length);
+                if (ok && row.status === "ready")
+                    advanced.push(name);
+            }
+            const at = yield* now;
+            if (advanced.length > 0)
+                yield* on(sql `UPDATE actor_fleet_views SET applied_lsn = ${target}::numeric, updated_at_ms = ${at}
+            WHERE view_name IN ${sql.in(advanced)} AND status = 'ready'
+              AND (applied_lsn IS NULL OR applied_lsn < ${target}::numeric)`);
+        }));
+        yield* afterApply;
+        yield* on(sql `SELECT 1 FROM pg_replication_slot_advance(${FLEET_SLOT}, '0/0'::pg_lsn + ${target}::numeric)`);
+        position = target;
+        yield* count(Metrics.fleetBatches, {}, 1);
+        for (const [name, groups] of recomputed)
+            yield* count(Metrics.fleetGroupsRecomputed, { view: name }, groups);
+        if (target === found.flush)
+            drained = yield* now;
+        yield* reportLag(found.flush);
+        return rows.length > 0;
+    });
+    /**
+     * Rebuilds `building` and stale views without an error, a few tenants per
+     * poll, in keyset order over the tenants of the source and of the derived
+     * table, so groups that vanished are deleted. Each recompute reads current
+     * data and the maintainer is the only writer, so it converges while writes
+     * continue; the view is ready, as of the slot's position, after its last
+     * tenant.
+     */
+    const rebuild = Effect.gen(function* () {
+        if (position === undefined)
+            return;
+        const status = yield* statuses;
+        let budget = REBUILD_GROUPS_PER_POLL;
+        for (const resolved of views) {
+            const name = resolved.view.name;
+            const row = status.get(name);
+            if (row === undefined || row.status === "ready" || row.last_error !== null) {
+                cursors.delete(name);
+                continue;
+            }
+            const source = qualified(resolved.sourceSchema, resolved.view.source.table);
+            const derived = qualified(resolved.derivedSchema, resolved.view.tableName.split(".").at(-1));
+            while (budget > 0) {
+                const after = cursors.get(name);
+                const [next] = yield* on(sql `SELECT tenant_id FROM (
+              SELECT ${sql.literal(identifier(resolved.view.tenantColumn))}::text AS tenant_id
+              FROM ${sql.literal(source)}
+              UNION SELECT tenant_id FROM ${sql.literal(derived)}) t
+            WHERE ${after === undefined ? sql `true` : sql `tenant_id > ${after}`}
+            ORDER BY tenant_id LIMIT 1`);
+                if (next === undefined) {
+                    const at = yield* now;
+                    yield* on(sql `UPDATE actor_fleet_views
+            SET status = 'ready', applied_lsn = ${position}::numeric, updated_at_ms = ${at}
+            WHERE view_name = ${name} AND status <> 'ready' AND last_error IS NULL`);
+                    cursors.delete(name);
+                    break;
+                }
+                const asOf = position;
+                const written = yield* inTransaction(Effect.gen(function* () {
+                    let groups = 0;
+                    const ok = yield* isolated(name, recompute(resolved, next.tenant_id, undefined, asOf).pipe(Effect.map((count) => {
+                        groups = count;
+                    })));
+                    return ok ? groups : undefined;
+                }));
+                if (written === undefined)
+                    break;
+                cursors.set(name, next.tenant_id);
+                budget -= Math.max(1, written);
+            }
+            if (budget <= 0)
+                return;
+        }
+    });
+    yield* start;
+    return yield* Effect.gen(function* () {
+        const changed = yield* batch;
+        if (!changed) {
+            yield* rebuild;
+            yield* Effect.sleep(POLL_INTERVAL);
+        }
+    }).pipe(Effect.catchTag("SqlError", (error) => /replication slot|logical decoding/i.test(innermost(error))
+        ? Effect.gen(function* () {
+            if (position !== undefined)
+                yield* markAllStale;
+            position = undefined;
+            yield* Effect.sleep(POLL_INTERVAL);
+        })
+        : Effect.fail(error)), Effect.forever);
+});

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

@@ -0,0 +1,41 @@
+/** A tuple's column values in text form: null for SQL null, undefined for an unchanged TOAST value. */
+export type Tuple = ReadonlyArray<string | null | undefined>;
+/** A relation as the stream last described it. */
+export interface Relation {
+    readonly id: number;
+    readonly schema: string;
+    readonly table: string;
+    readonly columns: ReadonlyArray<string>;
+}
+/** One decoded pgoutput message the maintainer acts on. */
+export type Change = {
+    readonly kind: "relation";
+    readonly relation: Relation;
+} | {
+    readonly kind: "insert";
+    readonly relation: number;
+    readonly after: Tuple;
+} | {
+    readonly kind: "update";
+    readonly relation: number;
+    readonly before: Tuple | undefined;
+    readonly after: Tuple;
+} | {
+    readonly kind: "delete";
+    readonly relation: number;
+    readonly before: Tuple;
+} | {
+    readonly kind: "truncate";
+    readonly relations: ReadonlyArray<number>;
+} | {
+    readonly kind: "commit";
+    readonly end: bigint;
+} | {
+    readonly kind: "other";
+};
+/**
+ * Decodes one message of the pgoutput protocol, version 1, as
+ * `pg_logical_slot_peek_binary_changes` returns it. Messages the maintainer
+ * never needs (begin, origin, type, logical messages) decode as `other`.
+ */
+export declare const decode: (bytes: Uint8Array) => Change;

package/dist/runtime/fleet/pgoutput.js

@@ -0,0 +1,102 @@
+const text = new TextDecoder();
+/**
+ * Decodes one message of the pgoutput protocol, version 1, as
+ * `pg_logical_slot_peek_binary_changes` returns it. Messages the maintainer
+ * never needs (begin, origin, type, logical messages) decode as `other`.
+ */
+export const decode = (bytes) => {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    let at = 0;
+    const byte = () => String.fromCharCode(view.getUint8(at++));
+    const int8 = () => view.getInt8(at++);
+    const int16 = () => {
+        const value = view.getInt16(at);
+        at += 2;
+        return value;
+    };
+    const int32 = () => {
+        const value = view.getInt32(at);
+        at += 4;
+        return value;
+    };
+    const uint64 = () => {
+        const value = view.getBigUint64(at);
+        at += 8;
+        return value;
+    };
+    const string = () => {
+        const end = bytes.indexOf(0, at);
+        const value = text.decode(bytes.subarray(at, end));
+        at = end + 1;
+        return value;
+    };
+    const tuple = () => {
+        const count = int16();
+        const values = [];
+        for (let index = 0; index < count; index++) {
+            const kind = byte();
+            if (kind === "n")
+                values.push(null);
+            else if (kind === "u")
+                values.push(undefined);
+            else {
+                const length = int32();
+                values.push(text.decode(bytes.subarray(at, at + length)));
+                at += length;
+            }
+        }
+        return values;
+    };
+    const tag = byte();
+    switch (tag) {
+        case "R": {
+            const id = int32();
+            const schema = string();
+            const table = string();
+            int8();
+            const count = int16();
+            const columns = [];
+            for (let index = 0; index < count; index++) {
+                int8();
+                columns.push(string());
+                int32();
+                int32();
+            }
+            return { kind: "relation", relation: { id, schema, table, columns } };
+        }
+        case "I": {
+            const relation = int32();
+            byte();
+            return { kind: "insert", relation, after: tuple() };
+        }
+        case "U": {
+            const relation = int32();
+            const marker = byte();
+            if (marker === "N")
+                return { kind: "update", relation, before: undefined, after: tuple() };
+            const before = tuple();
+            byte();
+            return { kind: "update", relation, before, after: tuple() };
+        }
+        case "D": {
+            const relation = int32();
+            byte();
+            return { kind: "delete", relation, before: tuple() };
+        }
+        case "T": {
+            const count = int32();
+            int8();
+            const relations = [];
+            for (let index = 0; index < count; index++)
+                relations.push(int32());
+            return { kind: "truncate", relations };
+        }
+        case "C": {
+            int8();
+            uint64();
+            return { kind: "commit", end: uint64() };
+        }
+        default:
+            return { kind: "other" };
+    }
+};

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

@@ -0,0 +1,36 @@
+import { Effect, Schema } from "effect";
+import { SqlClient } from "effect/sql";
+import type { AnyFleetView } from "../../tables/fleet.ts";
+declare const FleetSetupRefused_base: Schema.Class<FleetSetupRefused, Schema.TaggedStruct<"FleetSetupRefused", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** The server cannot hold fleet views; the message names the fix. */
+export declare class FleetSetupRefused extends FleetSetupRefused_base {
+}
+/** What `setupFleet` changed, for the operator's report. */
+export interface FleetSetup {
+    readonly sources: ReadonlyArray<string>;
+    readonly slot: "created" | "recreated" | "kept";
+}
+/**
+ * The operator step before fleet views run, as a role that may alter the
+ * source tables and create publications and slots: gives each source full
+ * replica identity, so an update tells the maintainer the group a row left;
+ * sets publication `durable_fleet` to exactly the sources; and creates the
+ * logical slot, recreating it when it was lost. Refuses a server whose
+ * `wal_level` is below logical.
+ */
+export declare const setupFleet: (views: readonly AnyFleetView[]) => Effect.Effect<{
+    sources: string[];
+    slot: "kept";
+} | {
+    sources: string[];
+    slot: "created" | "recreated";
+}, FleetSetupRefused | import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;
+/**
+ * Asks the maintainer to rebuild `view` from its source: the view goes back
+ * to `building` and its error is cleared, so a poisoned view runs again.
+ * Returns false when no runtime has registered the view.
+ */
+export declare const rebuildFleetView: (view: string) => Effect.Effect<boolean, import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;
+export {};

package/dist/runtime/fleet/setup.js

@@ -0,0 +1,58 @@
+import { Clock, Effect, Schema } from "effect";
+import { SqlClient } from "effect/sql";
+import { resolveViews } from "./checks.js";
+import { FLEET_PUBLICATION, FLEET_SLOT } from "./maintainer.js";
+/** The server cannot hold fleet views; the message names the fix. */
+export class FleetSetupRefused extends Schema.TaggedError()("FleetSetupRefused", { message: Schema.String }) {
+}
+const identifier = (name) => `"${name.replaceAll('"', '""')}"`;
+/**
+ * The operator step before fleet views run, as a role that may alter the
+ * source tables and create publications and slots: gives each source full
+ * replica identity, so an update tells the maintainer the group a row left;
+ * sets publication `durable_fleet` to exactly the sources; and creates the
+ * logical slot, recreating it when it was lost. Refuses a server whose
+ * `wal_level` is below logical.
+ */
+export const setupFleet = Effect.fnUntraced(function* (views) {
+    const sql = yield* SqlClient.SqlClient;
+    const [level] = yield* sql `SELECT current_setting('wal_level') AS wal_level`;
+    if (level?.wal_level !== "logical")
+        return yield* FleetSetupRefused.make({
+            message: `wal_level is ${level?.wal_level}; set wal_level = logical (ALTER SYSTEM SET wal_level = logical) and restart Postgres`,
+        });
+    const resolved = yield* resolveViews(views);
+    const sources = [
+        ...new Set(resolved.map(({ view, sourceSchema }) => `${identifier(sourceSchema)}.${identifier(view.source.table)}`)),
+    ];
+    for (const source of sources)
+        yield* sql.unsafe(`ALTER TABLE ${source} REPLICA IDENTITY FULL`);
+    const [publication] = yield* sql `
+    SELECT EXISTS (SELECT 1 FROM pg_publication WHERE pubname = ${FLEET_PUBLICATION}) AS found`;
+    yield* sql.unsafe(publication?.found === true
+        ? `ALTER PUBLICATION ${FLEET_PUBLICATION} SET TABLE ${sources.join(", ")}`
+        : `CREATE PUBLICATION ${FLEET_PUBLICATION} FOR TABLE ${sources.join(", ")}
+          WITH (publish = 'insert, update, delete, truncate')`);
+    const [slot] = yield* sql `
+    SELECT wal_status FROM pg_replication_slots
+    WHERE slot_name = ${FLEET_SLOT} AND database = current_database()`;
+    if (slot !== undefined && slot.wal_status !== "lost")
+        return { sources, slot: "kept" };
+    if (slot !== undefined)
+        yield* sql `SELECT 1 FROM (SELECT pg_drop_replication_slot(${FLEET_SLOT})) dropped`;
+    yield* sql `SELECT 1 FROM pg_create_logical_replication_slot(${FLEET_SLOT}, 'pgoutput')`;
+    return { sources, slot: slot === undefined ? "created" : "recreated" };
+});
+/**
+ * Asks the maintainer to rebuild `view` from its source: the view goes back
+ * to `building` and its error is cleared, so a poisoned view runs again.
+ * Returns false when no runtime has registered the view.
+ */
+export const rebuildFleetView = Effect.fnUntraced(function* (view) {
+    const sql = yield* SqlClient.SqlClient;
+    const at = yield* Clock.currentTimeMillis;
+    const rows = yield* sql `UPDATE actor_fleet_views
+    SET status = 'building', last_error = NULL, updated_at_ms = ${at}
+    WHERE view_name = ${view} RETURNING view_name`;
+    return rows.length > 0;
+});