@rikalabs/akter 0.1.0-alpha.0

package/dist/runtime/database/neki/migrations.d.ts

@@ -0,0 +1,31 @@
+import { Context, Effect } from "effect";
+import { Migrator, SqlClient } from "effect/sql";
+import type { SqlConnection, SqlError } from "effect/sql";
+import type { Scope } from "effect";
+import { ShardingConfig } from "effect/cluster";
+/** Holds startup coordination before even the history table is created, on one leased session. */
+export declare const withMigrationCoordination: <A, E>(effect: Effect.Effect<A, E, SqlClient.SqlClient | Scope.Scope>) => Effect.Effect<A, E | SqlError.SqlError, SqlClient.SqlClient>;
+/** Propagation must finish before a later statement uses the changed schema. */
+export declare const MigrationBarrier: Context.Reference<(connection: SqlConnection.Connection) => Effect.Effect<unknown, SqlError.SqlError>>;
+/** A reserved session owns coordination across autocommit DDL and progress writes. */
+export declare const MigrationCoordination: Context.Reference<(connection: SqlConnection.Connection) => Effect.Effect<unknown, SqlError.SqlError, Scope.Scope>>;
+/** Failure injection runs after a durable boundary, never in place of the database operation. */
+export declare const MigrationBoundary: Context.Reference<(point: string) => Effect.Effect<void>>;
+/** A preflight is already satisfied when this migration has started changing its schema. */
+export declare const MigrationResuming: Context.Reference<boolean>;
+/**
+ * Cluster creates its tables outside migration history. Creating its default schema
+ * under startup coordination first prevents concurrent CREATE races without lending
+ * Cluster a migration-scoped SQL client or consuming a third off-turn connection.
+ */
+export declare const prepareRunnerStorage: Effect.Effect<void, SqlError.SqlError, ShardingConfig.ShardingConfig | SqlClient.SqlClient>;
+/**
+ * DDL and its propagation run without BEGIN. A durable statement journal closes the
+ * crash gap between applying DDL and recording it; replay touches only an unfinished
+ * step, so a later drop/recreate cannot make an earlier create run again. Existing
+ * data rewrites set fixed values and are replayable, never increments or external work.
+ */
+export declare const nekiMigrator: ({ record, refuseSkipped, }: {
+    readonly record: Record<string, Effect.Effect<void, never, SqlClient.SqlClient>>;
+    readonly refuseSkipped: Effect.Effect<void, Migrator.MigrationError | SqlError.SqlError, SqlClient.SqlClient>;
+}) => Effect.Effect<(readonly [number, string])[], Migrator.MigrationError | SqlError.SqlError, SqlClient.SqlClient>;

package/dist/runtime/database/neki/migrations.js

@@ -0,0 +1,276 @@
+import { PgClient } from "@effect/sql-pg";
+import { Context, Effect } from "effect";
+import { Migrator, SqlClient } from "effect/sql";
+import { Reactivity } from "effect/reactivity";
+import { ShardingConfig } from "effect/cluster";
+import { NekiTurnSessions } from "./session.js";
+/** Holds startup coordination before even the history table is created, on one leased session. */
+export const withMigrationCoordination = (effect) => Effect.scoped(Effect.gen(function* () {
+    const source = yield* SqlClient.SqlClient;
+    const connection = yield* source.reserve;
+    yield* (yield* MigrationCoordination)(connection);
+    const reactivity = yield* Reactivity.make;
+    const client = yield* SqlClient.make({
+        acquirer: Effect.succeed(connection),
+        compiler: PgClient.makeCompiler(),
+        spanAttributes: [],
+    }).pipe(Effect.provideService(Reactivity.Reactivity, reactivity));
+    return yield* Effect.provideService(effect, SqlClient.SqlClient, client);
+}));
+/** Propagation must finish before a later statement uses the changed schema. */
+export const MigrationBarrier = Context.Reference("akter/MigrationBarrier", {
+    defaultValue: () => (connection) => connection.execute("SELECT __neki.wait_for_ddl()", [], undefined),
+});
+/** A reserved session owns coordination across autocommit DDL and progress writes. */
+export const MigrationCoordination = Context.Reference("akter/MigrationCoordination", {
+    defaultValue: () => (connection) => Effect.acquireRelease(connection.execute("SELECT pg_advisory_lock(1935764837, 487)", [], undefined), () => connection
+        .execute("SELECT pg_advisory_unlock(1935764837, 487)", [], undefined)
+        .pipe(Effect.orDie)),
+});
+/** Failure injection runs after a durable boundary, never in place of the database operation. */
+export const MigrationBoundary = Context.Reference("akter/MigrationBoundary", { defaultValue: () => () => Effect.void });
+/** A preflight is already satisfied when this migration has started changing its schema. */
+export const MigrationResuming = Context.Reference("akter/MigrationResuming", {
+    defaultValue: () => false,
+});
+/**
+ * Cluster creates its tables outside migration history. Creating its default schema
+ * under startup coordination first prevents concurrent CREATE races without lending
+ * Cluster a migration-scoped SQL client or consuming a third off-turn connection.
+ */
+export const prepareRunnerStorage = Effect.gen(function* () {
+    const config = yield* ShardingConfig.ShardingConfig;
+    const neki = yield* NekiTurnSessions;
+    return yield* withMigrationCoordination(Effect.gen(function* () {
+        const sql = yield* SqlClient.SqlClient;
+        const connection = yield* sql.reserve;
+        const boundary = yield* MigrationBoundary;
+        const barrier = yield* MigrationBarrier;
+        if (neki)
+            yield* barrier(connection);
+        yield* sql `CREATE TABLE IF NOT EXISTS cluster_runners (
+      machine_id SERIAL PRIMARY KEY,
+      address VARCHAR(255) NOT NULL,
+      runner TEXT NOT NULL,
+      healthy BOOLEAN NOT NULL DEFAULT TRUE,
+      last_heartbeat TIMESTAMP NOT NULL DEFAULT NOW(),
+      UNIQUE(address)
+    )`;
+        yield* boundary("cluster:runners:ddl");
+        if (neki)
+            yield* barrier(connection);
+        yield* boundary("cluster:runners:propagated");
+        if (config.shardLockDisableAdvisory) {
+            yield* sql `CREATE TABLE IF NOT EXISTS cluster_locks (
+        shard_id VARCHAR(50) PRIMARY KEY,
+        address VARCHAR(255) NOT NULL,
+        acquired_at TIMESTAMP NOT NULL
+      )`;
+            yield* boundary("cluster:locks:ddl");
+            if (neki)
+                yield* barrier(connection);
+            yield* boundary("cluster:locks:propagated");
+        }
+    }));
+});
+/** ALTER actions split only at commas outside quoted identifiers, literals and expressions. */
+const alterActions = (text) => {
+    const actions = [];
+    let start = 0;
+    let depth = 0;
+    let quote = "";
+    for (let i = 0; i < text.length; i++) {
+        const character = text[i];
+        if (quote !== "") {
+            if (character === quote) {
+                if (text[i + 1] === quote)
+                    i++;
+                else
+                    quote = "";
+            }
+        }
+        else if (character === "'" || character === '"')
+            quote = character;
+        else if (character === "(")
+            depth++;
+        else if (character === ")")
+            depth--;
+        else if (character === "," && depth === 0) {
+            actions.push(text.slice(start, i).trim());
+            start = i + 1;
+        }
+    }
+    actions.push(text.slice(start).trim());
+    return actions;
+};
+const identifier = '(?:"(?:[^"]|"")+"|[a-z_][a-z_0-9]*)(?:\\.(?:"(?:[^"]|"")+"|[a-z_][a-z_0-9]*))?';
+const alter = new RegExp(`^ALTER TABLE (${identifier})\\s+([\\s\\S]+)$`, "i");
+const unquote = (name) => name.replace(/^"|"$/g, "").replaceAll('""', '"');
+/**
+ * Resumption rewrites only the framework's audited DDL forms; an unknown form fails closed.
+ * A statement that already carries its own existence guard is replayed unchanged.
+ */
+const replayDdl = (sql, text) => Effect.gen(function* () {
+    if (/^CREATE (?:UNIQUE )?(?:TABLE|INDEX|SCHEMA) /i.test(text))
+        return text.replace(/^(CREATE (?:UNIQUE )?(?:TABLE|INDEX|SCHEMA)) (?!IF NOT EXISTS )/i, "$1 IF NOT EXISTS ");
+    if (/^DROP (?:TABLE|INDEX|VIEW) /i.test(text))
+        return text.replace(/^(DROP (?:TABLE|INDEX|VIEW)) (?!IF EXISTS )/i, "$1 IF EXISTS ");
+    if (/^CREATE (?:OR REPLACE )?(?:VIEW|FUNCTION) /i.test(text))
+        return text.replace(/^CREATE (?:OR REPLACE )?/i, "CREATE OR REPLACE ");
+    const policy = new RegExp(`^CREATE POLICY (${identifier}) ON (${identifier})`, "i").exec(text);
+    if (policy !== null) {
+        const [row] = yield* sql `SELECT EXISTS (
+        SELECT 1 FROM pg_policy WHERE polrelid = to_regclass(${policy[2]})
+          AND polname = ${unquote(policy[1])}) AS exists`;
+        return row?.exists === true ? undefined : text;
+    }
+    const match = alter.exec(text);
+    if (match !== null) {
+        const table = match[1];
+        const action = match[2];
+        if (/^ADD COLUMN /i.test(action))
+            return `ALTER TABLE ${table} ${action.replace(/^ADD COLUMN (?!IF NOT EXISTS )/i, "ADD COLUMN IF NOT EXISTS ")}`;
+        if (/^DROP CONSTRAINT /i.test(action))
+            return `ALTER TABLE ${table} ${action.replace(/^DROP CONSTRAINT (?!IF EXISTS )/i, "DROP CONSTRAINT IF EXISTS ")}`;
+        if (/^ENABLE ROW LEVEL SECURITY$/i.test(action))
+            return text;
+        const constraint = new RegExp(`^ADD CONSTRAINT (${identifier})\\s+`, "i").exec(action);
+        if (constraint !== null) {
+            const [row] = yield* sql `SELECT EXISTS (
+          SELECT 1 FROM pg_constraint WHERE conrelid = to_regclass(${table})
+            AND conname = ${unquote(constraint[1])}) AS exists`;
+            return row?.exists === true ? undefined : text;
+        }
+        const rename = new RegExp(`^RENAME COLUMN (${identifier}) TO (${identifier})$`, "i").exec(action);
+        if (rename !== null) {
+            const rows = yield* sql `SELECT attname AS name FROM pg_attribute
+          WHERE attrelid = to_regclass(${table}) AND NOT attisdropped
+            AND attname IN (${unquote(rename[1])}, ${unquote(rename[2])})`;
+            if (rows.some(({ name }) => name === unquote(rename[1])))
+                return text;
+            if (rows.some(({ name }) => name === unquote(rename[2])))
+                return undefined;
+        }
+    }
+    return yield* new Migrator.MigrationError({
+        kind: "BadState",
+        message: `No replay rule for migration DDL: ${text}`,
+    });
+});
+/**
+ * DDL and its propagation run without BEGIN. A durable statement journal closes the
+ * crash gap between applying DDL and recording it; replay touches only an unfinished
+ * step, so a later drop/recreate cannot make an earlier create run again. Existing
+ * data rewrites set fixed values and are replayable, never increments or external work.
+ */
+export const nekiMigrator = ({ record, refuseSkipped, }) => Effect.scoped(Effect.gen(function* () {
+    const source = yield* SqlClient.SqlClient;
+    const connection = yield* source.reserve;
+    const barrier = yield* MigrationBarrier;
+    const boundary = yield* MigrationBoundary;
+    const reactivity = yield* Reactivity.make;
+    const direct = yield* SqlClient.make({
+        acquirer: Effect.succeed(connection),
+        compiler: PgClient.makeCompiler(),
+        spanAttributes: [],
+    }).pipe(Effect.provideService(Reactivity.Reactivity, reactivity));
+    for (const [name, ddl] of [
+        [
+            "history",
+            "CREATE TABLE IF NOT EXISTS actor_migrations (migration_id integer PRIMARY KEY, created_at timestamptz NOT NULL DEFAULT now(), name text NOT NULL)",
+        ],
+        [
+            "journal",
+            "CREATE TABLE IF NOT EXISTS actor_migration_steps (migration_id integer NOT NULL, step integer NOT NULL, statement text NOT NULL, completed boolean NOT NULL DEFAULT false, PRIMARY KEY (migration_id, step))",
+        ],
+    ]) {
+        yield* barrier(connection);
+        yield* direct.unsafe(ddl);
+        yield* boundary(`bootstrap:${name}:ddl`);
+        yield* barrier(connection);
+        yield* boundary(`bootstrap:${name}:propagated`);
+    }
+    yield* Effect.provideService(refuseSkipped, SqlClient.SqlClient, direct);
+    const rows = yield* direct `SELECT migration_id::int AS id FROM actor_migrations`;
+    const latest = Math.max(0, ...rows.map(({ id }) => id));
+    const loaded = yield* Migrator.fromRecord(record);
+    if (new Set(loaded.map(([id]) => id)).size !== loaded.length)
+        return yield* new Migrator.MigrationError({
+            kind: "Duplicates",
+            message: "Found duplicate migration ids",
+        });
+    const applied = [];
+    for (const [id, name] of loaded) {
+        if (id <= latest)
+            continue;
+        const [progress] = yield* direct `SELECT EXISTS (
+      SELECT 1 FROM actor_migration_steps WHERE migration_id = ${id}) AS started`;
+        let step = 0;
+        const execute = (text, parameters, transform) => Effect.gen(function* () {
+            if (/^SELECT\b/i.test(text.trim()))
+                return yield* connection.execute(text, parameters, transform);
+            const mutation = text.trim();
+            const ddl = /^(CREATE|ALTER|DROP)\b/i.test(mutation);
+            if (!ddl && !(id === 26 && /^UPDATE\b/i.test(mutation)))
+                return yield* Effect.die(new Migrator.MigrationError({
+                    kind: "BadState",
+                    message: `Migration ${id} has no replayable data step: ${mutation}`,
+                }));
+            const alteration = alter.exec(mutation);
+            const statements = alteration !== null
+                ? alterActions(alteration[2]).map((action) => `ALTER TABLE ${alteration[1]} ${action}`)
+                : [mutation];
+            for (const statement of statements) {
+                const position = ++step;
+                const point = `${id}:${position}`;
+                const [saved] = yield* direct `SELECT statement, completed
+          FROM actor_migration_steps WHERE migration_id = ${id} AND step = ${position}`;
+                if (saved !== undefined && saved.statement !== statement)
+                    return yield* Effect.die(new Migrator.MigrationError({
+                        kind: "BadState",
+                        message: `Migration ${point} changed after it started`,
+                    }));
+                if (saved?.completed === true)
+                    continue;
+                if (saved === undefined) {
+                    yield* direct `INSERT INTO actor_migration_steps (migration_id, step, statement) VALUES (${id}, ${position}, ${statement})`;
+                    yield* boundary(`${point}:pending`);
+                }
+                if (ddl)
+                    yield* barrier(connection);
+                const replay = ddl
+                    ? yield* replayDdl(direct, statement).pipe(Effect.orDie)
+                    : statement;
+                if (replay !== undefined)
+                    yield* connection.execute(replay, parameters, transform);
+                yield* boundary(`${point}:applied`);
+                if (ddl) {
+                    yield* barrier(connection);
+                    yield* boundary(`${point}:propagated`);
+                }
+                yield* direct `UPDATE actor_migration_steps SET completed = true WHERE migration_id = ${id} AND step = ${position}`;
+                yield* boundary(`${point}:completed`);
+            }
+            return [];
+        });
+        const client = yield* SqlClient.make({
+            acquirer: Effect.succeed({ ...connection, execute }),
+            compiler: PgClient.makeCompiler(),
+            spanAttributes: [],
+        }).pipe(Effect.provideService(Reactivity.Reactivity, reactivity));
+        yield* record[Object.keys(record).find((key) => Number(key.split("_")[0]) === id)].pipe(Effect.provideService(SqlClient.SqlClient, client), Effect.provideService(MigrationResuming, progress?.started === true));
+        const [removed] = yield* direct `SELECT EXISTS (
+          SELECT 1 FROM actor_migration_steps WHERE migration_id = ${id} AND step > ${step}
+        ) AS exists`;
+        if (removed?.exists === true)
+            return yield* new Migrator.MigrationError({
+                kind: "BadState",
+                message: `Migration ${id} removed steps after it started`,
+            });
+        yield* direct `INSERT INTO actor_migrations (migration_id, name) VALUES (${id}, ${name})`;
+        yield* boundary(`${id}:recorded`);
+        applied.push([id, name]);
+    }
+    yield* Effect.provideService(refuseSkipped, SqlClient.SqlClient, direct);
+    return applied;
+}));

package/dist/runtime/database/neki/session.d.ts

@@ -0,0 +1,23 @@
+import type { PgConnection, PgPool } from "@effect/sql-pg";
+import { Context, Effect } from "effect";
+import type { Scope } from "effect";
+import type { SqlError } from "effect/sql";
+/**
+ * Whether the database is a Neki router. Turn sessions then run
+ * `NEKI_SESSION_SETTINGS`; nothing sets this outside the Neki conformance
+ * backend until Neki is a supported database.
+ */
+export declare const NekiTurnSessions: Context.Reference<boolean>;
+/**
+ * Session settings a turn connection needs on Neki, in the order they are set.
+ * The router reads the transaction mode when `BEGIN` arrives, so both are set
+ * on the session before any turn opens a transaction, never inside one.
+ */
+export declare const NEKI_SESSION_SETTINGS: ReadonlyArray<string>;
+/**
+ * `pool.get` with `NEKI_SESSION_SETTINGS` run once on each session, on its
+ * first lease, so a turn that reaches a second shard fails instead of
+ * committing on one shard and not the other. A session whose settings fail is
+ * dropped from the pool: a turn must never run on one that lacks them.
+ */
+export declare const nekiLease: (pool: PgPool.PgPool) => Effect.Effect<PgConnection.PgConnection, SqlError.SqlError, Scope.Scope>;

package/dist/runtime/database/neki/session.js

@@ -0,0 +1,31 @@
+import { Context, Effect } from "effect";
+/**
+ * Whether the database is a Neki router. Turn sessions then run
+ * `NEKI_SESSION_SETTINGS`; nothing sets this outside the Neki conformance
+ * backend until Neki is a supported database.
+ */
+export const NekiTurnSessions = Context.Reference("akter/NekiTurnSessions", {
+    defaultValue: () => false,
+});
+/**
+ * Session settings a turn connection needs on Neki, in the order they are set.
+ * The router reads the transaction mode when `BEGIN` arrives, so both are set
+ * on the session before any turn opens a transaction, never inside one.
+ */
+export const NEKI_SESSION_SETTINGS = [
+    "SET __neki.tx_mode = 'single'",
+    "SET __neki.fanout = 'single'",
+];
+/**
+ * `pool.get` with `NEKI_SESSION_SETTINGS` run once on each session, on its
+ * first lease, so a turn that reaches a second shard fails instead of
+ * committing on one shard and not the other. A session whose settings fail is
+ * dropped from the pool: a turn must never run on one that lacks them.
+ */
+export const nekiLease = (pool) => {
+    const configured = new WeakSet();
+    const configure = (connection) => Effect.forEach(NEKI_SESSION_SETTINGS, (setting) => connection.query(setting, [], false), {
+        discard: true,
+    }).pipe(Effect.tap(() => Effect.sync(() => configured.add(connection))), Effect.tapCause(() => pool.invalidate(connection)));
+    return Effect.tap(pool.get, (connection) => configured.has(connection) ? Effect.void : configure(connection));
+};

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

@@ -0,0 +1,21 @@
+import { PgliteClient } from "@effect/sql-pglite";
+import { DataDirLocked, DataDirVersion } from "../../errors/database.ts";
+/**
+ * The Postgres major the pinned PGlite embeds. Postgres cannot open a data
+ * directory another major wrote, so a PGlite upgrade across a major must
+ * change this, and a test checks it against what a fresh directory records.
+ */
+export declare const POSTGRES_MAJOR = "18";
+/** The lock file inside a data directory; the kernel drops its lock when the holder dies. */
+export declare const LOCK_FILE = ".akter.lock";
+/**
+ * A PGlite client layer that owns fresh instances; a borrowed `liveClient`
+ * keeps its original methods and lifetime. A file-backed instance holds its
+ * data directory's lock from before it opens until after it closes, refuses a
+ * directory another Postgres major wrote, and refuses `relaxedDurability`
+ * because it acknowledges a commit before its WAL is written, so a crash
+ * could lose a turn whose receipt the caller already has. Closing waits for
+ * in-flight queries: interrupted SQL fibers can leave protocol exchanges
+ * running, and closing PGlite during one deadlocks its single connection.
+ */
+export declare const pglite: (config?: PgliteClient.PgliteClientConfig) => import("effect/Layer").Layer<PgliteClient.PgliteClient | import("effect/sql/SqlClient").SqlClient, DataDirLocked | DataDirVersion | import("effect/sql/SqlError").SqlError, never>;

package/dist/runtime/database/pglite.js

@@ -0,0 +1,74 @@
+import { PGlite } from "@electric-sql/pglite";
+import { PgliteClient } from "@effect/sql-pglite";
+import { Effect } from "effect";
+import { DataDirLocked, DataDirVersion } from "../../errors/database.js";
+import { flockExclusive } from "./flock.js";
+/**
+ * The Postgres major the pinned PGlite embeds. Postgres cannot open a data
+ * directory another major wrote, so a PGlite upgrade across a major must
+ * change this, and a test checks it against what a fresh directory records.
+ */
+export const POSTGRES_MAJOR = "18";
+/** The lock file inside a data directory; the kernel drops its lock when the holder dies. */
+export const LOCK_FILE = ".akter.lock";
+/** A filesystem data directory, or undefined for an in-memory database. */
+const directoryOf = (dataDir) => {
+    if (dataDir === undefined || dataDir.startsWith("memory://"))
+        return undefined;
+    return dataDir.startsWith("file://") ? dataDir.slice("file://".length) : dataDir;
+};
+/** Holds an exclusive lock on the directory's lock file for the scope, so a second instance, in this process or another, never opens PGlite. */
+const lockDataDir = (directory) => Effect.gen(function* () {
+    if (!(yield* flockExclusive(`${directory}/${LOCK_FILE}`)))
+        return yield* DataDirLocked.make({ dataDir: directory });
+});
+/** Refuses a directory another Postgres major wrote before PGlite fails on it opaquely. */
+const checkVersion = (directory) => Effect.gen(function* () {
+    const found = yield* Effect.promise(() => import("node:fs/promises").then(({ readFile }) => readFile(`${directory}/PG_VERSION`, "utf8").then((text) => text.trim(), (error) => {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    })));
+    if (found !== undefined && found !== POSTGRES_MAJOR)
+        return yield* DataDirVersion.make({ dataDir: directory, found, expected: POSTGRES_MAJOR });
+});
+/**
+ * A PGlite client layer that owns fresh instances; a borrowed `liveClient`
+ * keeps its original methods and lifetime. A file-backed instance holds its
+ * data directory's lock from before it opens until after it closes, refuses a
+ * directory another Postgres major wrote, and refuses `relaxedDurability`
+ * because it acknowledges a commit before its WAL is written, so a crash
+ * could lose a turn whose receipt the caller already has. Closing waits for
+ * in-flight queries: interrupted SQL fibers can leave protocol exchanges
+ * running, and closing PGlite during one deadlocks its single connection.
+ */
+export const pglite = (config = {}) => {
+    if ("liveClient" in config)
+        return PgliteClient.layer(config);
+    const directory = directoryOf(config.dataDir);
+    return PgliteClient.layerFrom(Effect.gen(function* () {
+        if (directory !== undefined) {
+            if (config.relaxedDurability === true)
+                return yield* Effect.die(new Error("A file-backed PGlite database refuses relaxedDurability"));
+            yield* lockDataDir(directory);
+            yield* checkVersion(directory);
+        }
+        const pending = new Set();
+        const database = yield* Effect.acquireRelease(Effect.sync(() => {
+            const database = new PGlite(config);
+            const query = database.query.bind(database);
+            database.query = (...args) => {
+                const promise = query(...args);
+                pending.add(promise);
+                return promise.finally(() => pending.delete(promise));
+            };
+            return database;
+        }), (database) => Effect.gen(function* () {
+            while (pending.size > 0)
+                yield* Effect.promise(() => Promise.allSettled(pending));
+            yield* Effect.promise(() => database.close());
+        }));
+        yield* Effect.promise(() => database.waitReady);
+        return yield* PgliteClient.make({ ...config, liveClient: database });
+    }));
+};

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

@@ -0,0 +1,41 @@
+import { PgClient } from "@effect/sql-pg";
+import { Context, Effect, Layer } from "effect";
+import type { SqlClient } from "effect/sql";
+/**
+ * The primary's WAL insert position as a decimal string, and the database
+ * clock in epoch milliseconds. Read on a turn's session after its `COMMIT` or
+ * `ROLLBACK`, the position is at least the end of every commit record that
+ * session could have observed, so a replica that has replayed this far sees
+ * the turn's writes. An LSN cannot be known inside the transaction that
+ * writes it, which is why nothing stores it. The clock is read after the
+ * transaction ended, in the same flight, so an external caller's expiry
+ * recheck before its reply costs no round trip of its own.
+ */
+export declare const COMMIT_VERSION = "SELECT (pg_current_wal_insert_lsn() - '0/0')::text AS version,\n  floor(extract(epoch FROM clock_timestamp()) * 1000)::text AS now";
+/**
+ * This runner's streaming replica, if it has one. A query that carries a
+ * version reads there only once the replica has replayed past it, and
+ * otherwise reads the primary.
+ */
+export declare const ReadReplica: Context.Reference<SqlClient.SqlClient | undefined>;
+/** Provides `ReadReplica` as a client for `options`, or none when no replica is configured. */
+export declare const replicaLayer: (options: PgClient.PgPoolConfig | undefined) => Layer.Layer<never, import("effect/sql/SqlError").SqlError, never>;
+/**
+ * The primary's pool for queries, apart from the off-turn pool. Command
+ * admission and the receipt replay it serves then never queue behind a burst
+ * of readers, nor readers behind admission. Queries of types with owned
+ * tables or blobs stay on the off-turn pool, because the owned-rows binding
+ * is built on that client.
+ */
+export declare const QueryPool: Context.Reference<SqlClient.SqlClient | undefined>;
+/** Provides `QueryPool` as a bounded, first-come, first-served pool for `options`. */
+export declare const queryPoolLayer: (options: PgClient.PgPoolConfig) => Layer.Layer<never, import("effect/sql/SqlError").SqlError, never>;
+/**
+ * Whether the replica has replayed WAL through `version`. A server not in
+ * recovery reports no replay position, so it never counts as caught up.
+ *
+ * This runs as its own statement before the query's reads: a statement's
+ * snapshot is taken before its functions run, so a check in the same statement
+ * could pass after a snapshot that predates the replayed commit.
+ */
+export declare const caughtUp: (replica: SqlClient.SqlClient, version: string) => Effect.Effect<boolean, import("effect/sql/SqlError").SqlError, never>;

package/dist/runtime/database/replica.js

@@ -0,0 +1,51 @@
+import { PgClient } from "@effect/sql-pg";
+import { Context, Effect, Layer } from "effect";
+import { Reactivity } from "effect/reactivity";
+import { boundedPool } from "./bounded.js";
+/**
+ * The primary's WAL insert position as a decimal string, and the database
+ * clock in epoch milliseconds. Read on a turn's session after its `COMMIT` or
+ * `ROLLBACK`, the position is at least the end of every commit record that
+ * session could have observed, so a replica that has replayed this far sees
+ * the turn's writes. An LSN cannot be known inside the transaction that
+ * writes it, which is why nothing stores it. The clock is read after the
+ * transaction ended, in the same flight, so an external caller's expiry
+ * recheck before its reply costs no round trip of its own.
+ */
+export const COMMIT_VERSION = `SELECT (pg_current_wal_insert_lsn() - '0/0')::text AS version,
+  floor(extract(epoch FROM clock_timestamp()) * 1000)::text AS now`;
+/**
+ * This runner's streaming replica, if it has one. A query that carries a
+ * version reads there only once the replica has replayed past it, and
+ * otherwise reads the primary.
+ */
+export const ReadReplica = Context.Reference("@rikalabs/akter/runtime/database/replica/ReadReplica", { defaultValue: () => undefined });
+/** Provides `ReadReplica` as a client for `options`, or none when no replica is configured. */
+export const replicaLayer = (options) => Layer.effect(ReadReplica, Effect.gen(function* () {
+    if (options === undefined)
+        return undefined;
+    return yield* boundedPool(options);
+})).pipe(Layer.provide(Reactivity.layer));
+/**
+ * The primary's pool for queries, apart from the off-turn pool. Command
+ * admission and the receipt replay it serves then never queue behind a burst
+ * of readers, nor readers behind admission. Queries of types with owned
+ * tables or blobs stay on the off-turn pool, because the owned-rows binding
+ * is built on that client.
+ */
+export const QueryPool = Context.Reference("@rikalabs/akter/runtime/database/replica/QueryPool", { defaultValue: () => undefined });
+/** Provides `QueryPool` as a bounded, first-come, first-served pool for `options`. */
+export const queryPoolLayer = (options) => Layer.effect(QueryPool, boundedPool(options)).pipe(Layer.provide(Reactivity.layer));
+/**
+ * Whether the replica has replayed WAL through `version`. A server not in
+ * recovery reports no replay position, so it never counts as caught up.
+ *
+ * This runs as its own statement before the query's reads: a statement's
+ * snapshot is taken before its functions run, so a check in the same statement
+ * could pass after a snapshot that predates the replayed commit.
+ */
+export const caughtUp = Effect.fnUntraced(function* (replica, version) {
+    const rows = yield* replica `
+    SELECT coalesce(pg_last_wal_replay_lsn() - '0/0' >= ${version}::numeric, false) AS ready`;
+    return rows[0]?.ready === true;
+});

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

@@ -0,0 +1,21 @@
+import { Context, Effect } from "effect";
+import { SqlClient } from "effect/sql";
+/** One inclusive bucket range on one database shard, independent of actor compute ownership. */
+export interface BucketRange {
+    readonly first: number;
+    readonly last: number;
+    /** Neki's shard UID; absent on an ordinary single database. */
+    readonly shard?: string | undefined;
+}
+/** The data ranges this runner may scan; ordinary databases have one range and no session setting. */
+export declare const ShardMap: Context.Reference<readonly BucketRange[]>;
+/**
+ * Gives each targeted range its own session for the lifetime of the caller's
+ * scope. A shard setting cannot leak into the shared off-turn pool, and a
+ * failed setup closes the session instead of returning it to another user.
+ * Untargeted ranges reuse the existing client without a setting or a lease.
+ */
+export declare const shardClients: Effect.Effect<{
+    range: BucketRange;
+    sql: SqlClient.SqlClient;
+}[], import("effect/sql/SqlError").SqlError, import("effect/Scope").Scope | SqlClient.SqlClient>;

package/dist/runtime/database/shards.js

@@ -0,0 +1,37 @@
+import { PgClient } from "@effect/sql-pg";
+import { Context, Effect, Layer } from "effect";
+import { SqlClient } from "effect/sql";
+import { BUCKETS } from "../turn/outbox.js";
+/** The data ranges this runner may scan; ordinary databases have one range and no session setting. */
+export const ShardMap = Context.Reference("akter/ShardMap", {
+    defaultValue: () => [BUCKETS],
+});
+/**
+ * Gives each targeted range its own session for the lifetime of the caller's
+ * scope. A shard setting cannot leak into the shared off-turn pool, and a
+ * failed setup closes the session instead of returning it to another user.
+ * Untargeted ranges reuse the existing client without a setting or a lease.
+ */
+export const shardClients = Effect.gen(function* () {
+    const sql = yield* SqlClient.SqlClient;
+    const ranges = yield* ShardMap;
+    const sorted = [...ranges].sort((a, b) => a.first - b.first);
+    for (const [index, range] of sorted.entries()) {
+        if (!Number.isInteger(range.first) ||
+            !Number.isInteger(range.last) ||
+            range.first < BUCKETS.first ||
+            range.last > BUCKETS.last ||
+            range.first > range.last ||
+            (index > 0 && sorted[index - 1].last >= range.first) ||
+            range.shard === "")
+            return yield* Effect.die(new Error("Invalid or overlapping shard bucket ranges"));
+    }
+    return yield* Effect.forEach(ranges, (range) => Effect.gen(function* () {
+        if (range.shard === undefined)
+            return { range, sql };
+        const postgres = yield* PgClient.PgClient;
+        const client = Context.get(yield* Layer.build(PgClient.layerFrom(PgClient.makeClient(postgres.config))), SqlClient.SqlClient);
+        yield* client `SET __neki.shard = ${client.literal(`'${range.shard.replaceAll("'", "''")}'`)}`;
+        return { range, sql: client };
+    }));
+});

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

@@ -0,0 +1,7 @@
+import { Effect } from "effect";
+import { SqlClient } from "effect/sql";
+/**
+ * Runs `effect` in a read-only, repeatable-read transaction, so every read in
+ * it sees one snapshot and Postgres refuses any write it could attempt.
+ */
+export declare const inReadOnlySnapshot: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E | import("effect/sql/SqlError").SqlError, R | SqlClient.SqlClient>;

package/dist/runtime/database/snapshot.js

@@ -0,0 +1,7 @@
+import { Effect } from "effect";
+import { SqlClient } from "effect/sql";
+/**
+ * Runs `effect` in a read-only, repeatable-read transaction, so every read in
+ * it sees one snapshot and Postgres refuses any write it could attempt.
+ */
+export const inReadOnlySnapshot = (effect) => Effect.flatMap(SqlClient.SqlClient, (sql) => sql.withTransaction(sql `SET TRANSACTION ISOLATION LEVEL REPEATABLE READ, READ ONLY`.pipe(Effect.andThen(effect))));