@rikalabs/akter 0.1.0-alpha.0

package/dist/runtime/content/store.d.ts

@@ -0,0 +1,63 @@
+import { Cause, Crypto, Effect, Option, Stream } from "effect";
+import { SqlClient } from "effect/sql";
+import { ContentTooLarge } from "../../errors/content.ts";
+import type { ContentPoint } from "../turn/hooks.ts";
+import { type Grants } from "./grant.ts";
+/** Bytes one content may hold. */
+export declare const MAX_CONTENT_BYTES: number;
+/**
+ * Bytes per stored chunk: well below the driver's 16 MiB message limit, so
+ * content of any size reads as one row per chunk.
+ */
+export declare const CHUNK_BYTES: number;
+/** The runtime's content configuration: grant keys, sweep timing, and connection limits. */
+interface ContentSettings {
+    readonly grants: Grants;
+    /** How long unreferenced content outlives its last grant, before the turn and skew margins. */
+    readonly graceMs: number;
+    /** The bound on clock skew between any two shards' databases. */
+    readonly skewMs: number;
+    /**
+     * PGlite has one connection, so no transaction may stay open across a
+     * client's upload or download; those buffer in memory instead.
+     */
+    readonly singleConnection: boolean;
+    /** The framework clock's offset from database time; only tests move it. */
+    readonly offset: () => number;
+    readonly hooks: {
+        readonly at: (point: ContentPoint) => Effect.Effect<void>;
+    };
+}
+/**
+ * Tenant-scoped content storage: uploads, grant-checked reads, and the sweep
+ * of unreferenced content. Times come from the database clock plus the
+ * framework offset, read inside the statement that uses them so the time and
+ * the write come from one shard. Every content has chunk 0, even an empty
+ * one, so a content with no rows has been swept. The sweep's reference scan is
+ * a scatter across every actor shard on a sharded backend, and it deletes a
+ * content row and its chunks in one statement so they go together.
+ */
+export declare const tenantContent: (settings: ContentSettings) => {
+    uploadBytes: (tenant: string, bytes: Uint8Array<ArrayBufferLike>) => Effect.Effect<{
+        readonly hash: string;
+        readonly size: number;
+        readonly grant: string;
+    }, ContentTooLarge | import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;
+    uploadStream: <E>(tenant: string, body: Stream.Stream<Uint8Array, E>, limit: number) => Effect.Effect<{
+        readonly hash: string;
+        readonly size: number;
+        readonly grant: string;
+    }, E | ContentTooLarge | import("effect/sql/SqlError").SqlError, Crypto.Crypto | SqlClient.SqlClient>;
+    grant: (tenant: string, hash: string, size: number) => Effect.Effect<Option.Option<{
+        readonly hash: string;
+        readonly size: number;
+        readonly grant: string;
+    }>, import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;
+    read: (tenant: string, hash: string, size: number) => Effect.Effect<Option.Option<Uint8Array<ArrayBuffer>>, import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;
+    stream: (tenant: string, hash: string, size: number, timeoutMs: number) => Stream.Stream<Uint8Array, Cause.NoSuchElementError, SqlClient.SqlClient>;
+    sweep: (force: boolean) => Effect.Effect<number, import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;
+    verify: (grant: string, bound: Omit<import("./grant.ts").Granted, "expiresAt">) => Effect.Effect<import("effect/Result").Result<number, import("../../index.ts").InvalidContentRef["reason"]>>;
+};
+/** The content store as the runtime consumes it. */
+export type ContentStoreImpl = ReturnType<typeof tenantContent>;
+export {};

package/dist/runtime/content/store.js

@@ -0,0 +1,294 @@
+import { Cause, Crypto, Effect, Option, Stream } from "effect";
+import { sha256Bytes, sha256Hasher } from "../../identity/digest.js";
+import { SqlClient } from "effect/sql";
+import { ContentTooLarge } from "../../errors/content.js";
+import { tenantRoutingKey } from "../storage/codec.js";
+import { textArray } from "../turn/outbox.js";
+import { GRANT_LIFETIME_MS } from "./grant.js";
+/** Bytes one content may hold. */
+export const MAX_CONTENT_BYTES = 64 * 1024 * 1024;
+/**
+ * Bytes per stored chunk: well below the driver's 16 MiB message limit, so
+ * content of any size reads as one row per chunk.
+ */
+export const CHUNK_BYTES = 1024 * 1024;
+/** A tenant's content is swept at most this often. */
+const SWEEP_INTERVAL_MS = 3_600_000;
+/** Candidates one sweep statement considers. */
+const SWEEP_BATCH = 500;
+/** Tenants one sweep pass claims. */
+const SWEEP_TENANTS = 100;
+const hex = (bytes) => Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+const concat = (parts, size) => {
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const part of parts) {
+        bytes.set(part, offset);
+        offset += part.byteLength;
+    }
+    return bytes;
+};
+/** Stored chunks, checked against the size its reference recorded; none when any is missing. */
+const complete = (rows, size) => {
+    let total = 0;
+    for (const [index, row] of rows.entries()) {
+        if (row.chunk !== index)
+            return Option.none();
+        total += row.bytes.byteLength;
+    }
+    return rows.length > 0 && total === size
+        ? Option.some(rows.map((row) => Uint8Array.from(row.bytes)))
+        : Option.none();
+};
+/**
+ * Tenant-scoped content storage: uploads, grant-checked reads, and the sweep
+ * of unreferenced content. Times come from the database clock plus the
+ * framework offset, read inside the statement that uses them so the time and
+ * the write come from one shard. Every content has chunk 0, even an empty
+ * one, so a content with no rows has been swept. The sweep's reference scan is
+ * a scatter across every actor shard on a sharded backend, and it deletes a
+ * content row and its chunks in one statement so they go together.
+ */
+export const tenantContent = (settings) => {
+    const { grants, hooks } = settings;
+    const clock = (sql) => sql `(floor(extract(epoch FROM clock_timestamp()) * 1000)::bigint + ${settings.offset()})`;
+    const now = Effect.gen(function* () {
+        const sql = yield* SqlClient.SqlClient;
+        const [row] = yield* sql `SELECT ${clock(sql)}::text AS now`;
+        return Number(row.now);
+    });
+    const refOf = (tenant, hash, size, expiresAt) => Effect.map(grants.sign({ tenant, hash, size, expiresAt }), (grant) => ({
+        hash,
+        size,
+        grant,
+    }));
+    /**
+     * Creates the content row or raises its grant horizon, and registers the
+     * tenant with the sweep. The returned horizon is at least the new grant's expiry.
+     */
+    const upsert = Effect.fnUntraced(function* (tenant, hash, size) {
+        const sql = yield* SqlClient.SqlClient;
+        const key = tenantRoutingKey(tenant);
+        const [row] = yield* sql `
+      WITH swept AS (
+        INSERT INTO tenant_content_sweeps (routing_key, tenant_id, swept_at_ms)
+        VALUES (${key}, ${tenant}, 0) ON CONFLICT DO NOTHING)
+      INSERT INTO tenant_contents (routing_key, tenant_id, hash, size, granted_until_ms)
+      VALUES (${key}, ${tenant}, ${hash}, ${size}, ${clock(sql)} + ${GRANT_LIFETIME_MS})
+      ON CONFLICT (routing_key, tenant_id, hash) DO UPDATE
+        SET granted_until_ms = greatest(tenant_contents.granted_until_ms, EXCLUDED.granted_until_ms)
+      RETURNING (xmax = 0) AS inserted, granted_until_ms::text AS granted_until_ms`;
+        return { inserted: row.inserted, expiresAt: Number(row.granted_until_ms) };
+    });
+    const writeChunk = Effect.fnUntraced(function* (tenant, hash, chunk, bytes) {
+        const sql = yield* SqlClient.SqlClient;
+        yield* sql `INSERT INTO tenant_content_chunks (routing_key, tenant_id, hash, chunk, bytes)
+      VALUES (${tenantRoutingKey(tenant)}, ${tenant}, ${hash}, ${chunk}, ${bytes}::bytea)`;
+    });
+    /** Stores bytes already in memory: hashed first, so existing content writes no bytes. */
+    const uploadBytes = Effect.fnUntraced(function* (tenant, bytes) {
+        const sql = yield* SqlClient.SqlClient;
+        if (bytes.byteLength > MAX_CONTENT_BYTES)
+            return yield* ContentTooLarge.make({ maxBytes: MAX_CONTENT_BYTES });
+        const hash = hex(sha256Bytes(bytes));
+        const size = bytes.byteLength;
+        const stored = yield* sql.withTransaction(Effect.gen(function* () {
+            const row = yield* upsert(tenant, hash, size);
+            if (row.inserted)
+                for (let chunk = 0; chunk === 0 || chunk * CHUNK_BYTES < size; chunk += 1)
+                    yield* writeChunk(tenant, hash, chunk, bytes.subarray(chunk * CHUNK_BYTES, (chunk + 1) * CHUNK_BYTES));
+            return row;
+        }));
+        return yield* refOf(tenant, hash, size, stored.expiresAt);
+    });
+    /**
+     * Stores a body as it arrives, in one transaction: 1 MiB chunks are written
+     * under a pending name while the body is hashed, then renamed to the hash,
+     * or dropped when the tenant already holds those bytes. Past `limit` the
+     * transaction rolls back, so no part of the body stays.
+     */
+    const uploadStream = (tenant, body, limit) => Effect.gen(function* () {
+        const sql = yield* SqlClient.SqlClient;
+        if (settings.singleConnection) {
+            const parts = [];
+            let size = 0;
+            yield* body.pipe(Stream.runForEach((part) => {
+                size += part.byteLength;
+                parts.push(part);
+                return size > limit ? ContentTooLarge.make({ maxBytes: limit }) : Effect.void;
+            }));
+            return yield* uploadBytes(tenant, concat(parts, size));
+        }
+        const pending = `pending:${yield* (yield* Crypto.Crypto).randomUUIDv4.pipe(Effect.orDie)}`;
+        const hasher = sha256Hasher();
+        const stored = yield* sql.withTransaction(Effect.gen(function* () {
+            let size = 0;
+            let chunk = 0;
+            let buffer = new Uint8Array(CHUNK_BYTES);
+            let filled = 0;
+            const flush = Effect.suspend(() => {
+                const bytes = buffer.slice(0, filled);
+                const index = chunk;
+                chunk += 1;
+                filled = 0;
+                return writeChunk(tenant, pending, index, bytes);
+            });
+            yield* body.pipe(Stream.runForEach((part) => Effect.gen(function* () {
+                size += part.byteLength;
+                if (size > limit)
+                    return yield* ContentTooLarge.make({ maxBytes: limit });
+                hasher.update(part);
+                let read = 0;
+                while (read < part.byteLength) {
+                    const taken = Math.min(CHUNK_BYTES - filled, part.byteLength - read);
+                    buffer.set(part.subarray(read, read + taken), filled);
+                    filled += taken;
+                    read += taken;
+                    if (filled === CHUNK_BYTES) {
+                        yield* flush;
+                        buffer = new Uint8Array(CHUNK_BYTES);
+                    }
+                }
+            })));
+            if (filled > 0 || chunk === 0)
+                yield* flush;
+            const hash = hex(hasher.digest());
+            const row = yield* upsert(tenant, hash, size);
+            const key = tenantRoutingKey(tenant);
+            yield* row.inserted
+                ? sql `UPDATE tenant_content_chunks SET hash = ${hash}
+                WHERE routing_key = ${key} AND tenant_id = ${tenant} AND hash = ${pending}`
+                : sql `DELETE FROM tenant_content_chunks
+                WHERE routing_key = ${key} AND tenant_id = ${tenant} AND hash = ${pending}`;
+            return { hash, size, expiresAt: row.expiresAt };
+        }));
+        return yield* refOf(tenant, stored.hash, stored.size, stored.expiresAt);
+    });
+    /**
+     * Raises the content's grant horizon and signs a grant for it; none when
+     * the content no longer exists. The row lock orders the raise with a
+     * sweep's delete: a raise first moves the horizon past the sweep's re-check.
+     */
+    const grant = Effect.fnUntraced(function* (tenant, hash, size) {
+        const sql = yield* SqlClient.SqlClient;
+        yield* hooks.at("beforeRaise");
+        const [row] = yield* sql `
+      UPDATE tenant_contents
+      SET granted_until_ms = greatest(granted_until_ms, ${clock(sql)} + ${GRANT_LIFETIME_MS})
+      WHERE routing_key = ${tenantRoutingKey(tenant)} AND tenant_id = ${tenant}
+        AND hash = ${hash} AND size = ${size}
+      RETURNING granted_until_ms::text AS granted_until_ms`;
+        if (row === undefined)
+            return Option.none();
+        return Option.some(yield* refOf(tenant, hash, size, Number(row.granted_until_ms)));
+    });
+    const chunksOf = (sql, tenant, hash) => sql `routing_key = ${tenantRoutingKey(tenant)} AND tenant_id = ${tenant} AND hash = ${hash}`;
+    /** Every chunk from one statement's snapshot, so a sweep deletes all of them or none. */
+    const readRows = Effect.fnUntraced(function* (tenant, hash, size) {
+        const sql = yield* SqlClient.SqlClient;
+        yield* hooks.at("afterResolve");
+        const rows = yield* sql `
+      SELECT chunk, bytes FROM tenant_content_chunks WHERE ${chunksOf(sql, tenant, hash)}
+      ORDER BY chunk`;
+        return complete(rows, size);
+    });
+    const read = (tenant, hash, size) => Effect.map(readRows(tenant, hash, size), Option.map((parts) => concat(parts, size)));
+    /**
+     * The content's chunks from one read-only REPEATABLE READ snapshot held for
+     * the whole stream, at most `timeoutMs`. The first statement checks every
+     * chunk is there before any is emitted.
+     */
+    const stream = (tenant, hash, size, timeoutMs) => {
+        const missing = new Cause.NoSuchElementError(`Content ${hash} is not stored`);
+        if (settings.singleConnection)
+            return Stream.unwrap(Effect.map(readRows(tenant, hash, size).pipe(Effect.orDie), Option.match({
+                onNone: () => Stream.fail(missing),
+                onSome: (parts) => Stream.fromArray(parts),
+            })));
+        return Stream.unwrap(Effect.gen(function* () {
+            const sql = yield* SqlClient.SqlClient;
+            const connection = yield* sql.reserve;
+            const onSnapshot = (effect) => Effect.provideService(effect, sql.transactionService, [connection, 0]);
+            yield* Effect.acquireRelease(onSnapshot(sql.unsafe("BEGIN ISOLATION LEVEL REPEATABLE READ READ ONLY")), () => onSnapshot(sql.unsafe("ROLLBACK")).pipe(Effect.ignore));
+            yield* hooks.at("afterResolve");
+            const [head] = yield* onSnapshot(sql `
+            SELECT count(*)::int AS chunks, max(chunk) AS last,
+              COALESCE(sum(octet_length(bytes)), 0)::float8 AS bytes
+            FROM tenant_content_chunks WHERE ${chunksOf(sql, tenant, hash)}`);
+            if (head.chunks === 0 || head.last !== head.chunks - 1 || head.bytes !== size)
+                return Stream.fail(missing);
+            return Stream.range(0, head.chunks - 1).pipe(Stream.mapEffect((chunk) => onSnapshot(sql `SELECT bytes FROM tenant_content_chunks
+                WHERE ${chunksOf(sql, tenant, hash)} AND chunk = ${chunk}`).pipe(Effect.map(([row]) => Uint8Array.from(row.bytes)), Effect.orDie)));
+        }).pipe(Effect.orDie)).pipe(Stream.interruptWhen(Effect.sleep(timeoutMs).pipe(Effect.andThen(Effect.die(new Error("A content stream outlived commandTimeout"))))));
+    };
+    /**
+     * Deletes content no actor references once its last grant is more than
+     * `grace + T` old, where `T` is the longest turn of any actor type that
+     * declares content. Candidates come from before a reference scan, and the
+     * delete re-checks the grant horizon against `sweep start − T − S`: a
+     * reference committed after its shard was scanned was attached under a
+     * grant that keeps the horizon past it. Each tenant goes at most once an
+     * hour, unless `force`.
+     */
+    const sweep = Effect.fnUntraced(function* (force) {
+        const sql = yield* SqlClient.SqlClient;
+        const started = yield* now;
+        const tenants = force
+            ? yield* sql `
+          SELECT routing_key::text AS routing_key, tenant_id FROM tenant_content_sweeps`
+            : yield* sql `
+          UPDATE tenant_content_sweeps SET swept_at_ms = ${started}
+          WHERE (routing_key, tenant_id) IN (
+            SELECT routing_key, tenant_id FROM tenant_content_sweeps
+            WHERE swept_at_ms <= ${started - SWEEP_INTERVAL_MS}
+            LIMIT ${SWEEP_TENANTS} FOR UPDATE SKIP LOCKED)
+          RETURNING routing_key::text AS routing_key, tenant_id`;
+        const [longest] = yield* sql `
+      SELECT COALESCE(max(turn_ms), 0)::float8 AS turn_ms FROM actor_content_types`;
+        const turnMs = longest.turn_ms;
+        let deleted = 0;
+        for (const { routing_key, tenant_id: tenant } of tenants) {
+            const key = BigInt(routing_key);
+            const sweepStart = yield* now;
+            const candidateBefore = sweepStart - settings.graceMs - turnMs - settings.skewMs;
+            const recheckBefore = sweepStart - turnMs - settings.skewMs;
+            let after = { granted: Number.MIN_SAFE_INTEGER, hash: "" };
+            for (;;) {
+                const candidates = yield* sql `
+          SELECT hash, granted_until_ms::text AS granted_until_ms FROM tenant_contents
+          WHERE routing_key = ${key} AND tenant_id = ${tenant}
+            AND granted_until_ms < ${candidateBefore}
+            AND (granted_until_ms, hash) > (${after.granted}, ${after.hash})
+          ORDER BY granted_until_ms, hash LIMIT ${SWEEP_BATCH}`;
+                if (candidates.length === 0)
+                    break;
+                const last = candidates.at(-1);
+                after = { granted: Number(last.granted_until_ms), hash: last.hash };
+                const referenced = new Set((yield* sql `
+            SELECT DISTINCT hash FROM actor_content_refs
+            WHERE tenant_id = ${tenant}
+              AND hash = ANY(${textArray({ sql, values: candidates.map((row) => row.hash) })})`).map((row) => row.hash));
+                yield* hooks.at("afterReferenceScan");
+                const unreferenced = candidates
+                    .map((row) => row.hash)
+                    .filter((hash) => !referenced.has(hash));
+                if (unreferenced.length === 0)
+                    continue;
+                const [gone] = yield* sql `
+          WITH gone AS (
+            DELETE FROM tenant_contents
+            WHERE routing_key = ${key} AND tenant_id = ${tenant}
+              AND hash = ANY(${textArray({ sql, values: unreferenced })})
+              AND granted_until_ms < ${recheckBefore}
+            RETURNING hash),
+          chunks AS (
+            DELETE FROM tenant_content_chunks c USING gone
+            WHERE c.routing_key = ${key} AND c.tenant_id = ${tenant} AND c.hash = gone.hash)
+          SELECT count(*)::int AS deleted FROM gone`;
+                deleted += gone.deleted;
+            }
+        }
+        return deleted;
+    });
+    return { uploadBytes, uploadStream, grant, read, stream, sweep, verify: grants.verify };
+};

package/dist/runtime/cron/key.d.ts

@@ -0,0 +1,2 @@
+/** Timer keys the runtime keeps for `policy.cron`; application intents may not use them. */
+export declare const CRON_PREFIX = "$cron:";

package/dist/runtime/cron/key.js

@@ -0,0 +1,2 @@
+/** Timer keys the runtime keeps for `policy.cron`; application intents may not use them. */
+export const CRON_PREFIX = "$cron:";

package/dist/runtime/cron/schedule.d.ts

@@ -0,0 +1,69 @@
+import { Crypto, Effect } from "effect";
+import { SqlClient, type Statement } from "effect/sql";
+import type { CronEntry, CronSchedule } from "../../policies/schedules.ts";
+import { CRON_PREFIX } from "./key.ts";
+export { CRON_PREFIX };
+export type { CronEntry, CronSchedule };
+/**
+ * Writes the first tick of every entry `ref` has no pending tick for. The
+ * timer-key unique index makes concurrent writers, and entries that already
+ * tick, no-ops.
+ */
+export declare const writeTicks: (routingKey: bigint, ref: {
+    readonly tenant: string;
+    readonly actor: string;
+    readonly id: string;
+}, entries: readonly CronEntry[], now: number) => Effect.Effect<void, import("effect/sql/SqlError").SqlError, Crypto.Crypto | SqlClient.SqlClient>;
+/**
+ * Writes a singleton's missing ticks in its default tenant at startup. Every
+ * runner does this; the generation and timer-key unique indexes keep one row
+ * per entry however many start at once.
+ */
+export declare const bootstrapTicks: (routingKey: bigint, ref: {
+    readonly tenant: string;
+    readonly actor: string;
+    readonly id: string;
+}, entries: readonly CronEntry[]) => Effect.Effect<void, import("effect/sql/SqlError").SqlError, Crypto.Crypto | SqlClient.SqlClient>;
+/** The claimed tick row the relay settles. */
+interface ClaimedTick {
+    readonly tenant_id: string;
+    readonly actor_type: string;
+    readonly actor_id: string;
+    readonly routing_key: string;
+    readonly intent_id: string;
+    readonly command: string;
+    readonly payload: string;
+    readonly timer_key: string | null;
+    readonly scheduled_at: string;
+    readonly claimed_until: string;
+}
+/**
+ * Settles claimed `$cron:` rows for one relay. A tick is delivered like any
+ * intent unless it is older than its type's skip window, and after its
+ * receipt commits the row is rewritten, in place and under the same claim, to
+ * the first tick after now with a fresh id. A tick whose entry this runner
+ * does not declare is deleted once it is past the skip window and otherwise
+ * released with backoff, so a runner that still declares it can fire it. A
+ * tick whose stored target differs from its entry's delivers the entry's
+ * command on this claim, unless a receipt shows the tick already fired under
+ * its old command, in which case the row is rewritten instead.
+ */
+export declare const cronTicks: ({ sql, crypto, schedules, retryWindowMs, }: {
+    readonly sql: SqlClient.SqlClient;
+    readonly crypto: Crypto.Crypto;
+    readonly schedules: () => ReadonlyMap<string, CronSchedule>;
+    readonly retryWindowMs: number;
+}) => {
+    /** A tick is a `$cron:` row; application intents may not use the prefix. */
+    isTick: (row: ClaimedTick) => boolean;
+    /**
+     * Settles a tick that must not fire and returns undefined, or returns the
+     * command and payload the relay delivers on this claim.
+     */
+    settleUnfired: (row: ClaimedTick, claim: Statement.Fragment, backoffMs: number) => Effect.Effect<{
+        command: string;
+        payload: string;
+    } | undefined, import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;
+    /** Replaces a delivered tick's row with the entry's next tick. */
+    settleFired: (row: ClaimedTick, claim: Statement.Fragment) => Effect.Effect<void, import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;
+};

package/dist/runtime/cron/schedule.js

@@ -0,0 +1,144 @@
+import { Crypto, Effect, Schema } from "effect";
+import { SqlClient } from "effect/sql";
+import { System } from "../../identity/caller.js";
+import { CRON_PREFIX } from "./key.js";
+import { databaseTime } from "../turn/admission.js";
+import { bucketOf, CallerJson, OutboxRuntime } from "../turn/outbox.js";
+export { CRON_PREFIX };
+const tickId = (now, dueAt, retryWindowMs) => Effect.gen(function* () {
+    const crypto = yield* Crypto.Crypto;
+    const uuid = yield* crypto.randomUUIDv4.pipe(Effect.orDie);
+    return `v1.${now}.${Math.max(dueAt, now) + retryWindowMs}.${uuid}`;
+});
+/**
+ * Writes the first tick of every entry `ref` has no pending tick for. The
+ * timer-key unique index makes concurrent writers, and entries that already
+ * tick, no-ops.
+ */
+export const writeTicks = Effect.fnUntraced(function* (routingKey, ref, entries, now) {
+    if (entries.length === 0)
+        return;
+    const sql = yield* SqlClient.SqlClient;
+    const { retryWindowMs } = yield* OutboxRuntime;
+    const caller = yield* Schema.encodeEffect(CallerJson)(System.make({ source: "cron", ref })).pipe(Effect.orDie);
+    const rows = [];
+    for (const entry of entries) {
+        const dueAt = entry.next(now);
+        rows.push({
+            routing_key: routingKey,
+            intent_id: yield* tickId(now, dueAt, retryWindowMs),
+            kind: "intent",
+            bucket: bucketOf(routingKey),
+            due_at_ms: dueAt,
+            scheduled_at_ms: dueAt,
+            tenant_id: ref.tenant,
+            actor_type: ref.actor,
+            actor_id: ref.id,
+            timer_key: entry.key,
+            target_type: ref.actor,
+            target_id: ref.id,
+            command: entry.command,
+            payload: yield* entry.payload,
+            caller,
+        });
+    }
+    yield* sql `INSERT INTO actor_outbox ${sql.insert(rows)}
+    ON CONFLICT (routing_key, tenant_id, actor_type, actor_id, timer_key)
+      WHERE timer_key IS NOT NULL
+    DO NOTHING`;
+});
+/**
+ * Writes a singleton's missing ticks in its default tenant at startup. Every
+ * runner does this; the generation and timer-key unique indexes keep one row
+ * per entry however many start at once.
+ */
+export const bootstrapTicks = Effect.fnUntraced(function* (routingKey, ref, entries) {
+    if (entries.length === 0)
+        return;
+    const sql = yield* SqlClient.SqlClient;
+    yield* sql.withTransaction(Effect.gen(function* () {
+        yield* sql `INSERT INTO actor_generations (routing_key, tenant_id, actor_type, actor_id)
+        VALUES (${routingKey}, ${ref.tenant}, ${ref.actor}, ${ref.id}) ON CONFLICT DO NOTHING`;
+        yield* writeTicks(routingKey, ref, entries, yield* databaseTime);
+    }));
+});
+/**
+ * Settles claimed `$cron:` rows for one relay. A tick is delivered like any
+ * intent unless it is older than its type's skip window, and after its
+ * receipt commits the row is rewritten, in place and under the same claim, to
+ * the first tick after now with a fresh id. A tick whose entry this runner
+ * does not declare is deleted once it is past the skip window and otherwise
+ * released with backoff, so a runner that still declares it can fire it. A
+ * tick whose stored target differs from its entry's delivers the entry's
+ * command on this claim, unless a receipt shows the tick already fired under
+ * its old command, in which case the row is rewritten instead.
+ */
+export const cronTicks = ({ sql, crypto, schedules, retryWindowMs, }) => {
+    const entryOf = (row) => schedules()
+        .get(row.actor_type)
+        ?.entries.find((entry) => entry.key === row.timer_key);
+    const rewrite = Effect.fnUntraced(function* (row, entry, claim) {
+        const now = yield* databaseTime;
+        const dueAt = entry.next(now);
+        const id = yield* tickId(now, dueAt, retryWindowMs).pipe(Effect.provideService(Crypto.Crypto, crypto));
+        const payload = yield* entry.payload;
+        yield* sql `UPDATE actor_outbox SET intent_id = ${id},
+        command = ${entry.command}, payload = ${payload}, due_at_ms = ${dueAt},
+        scheduled_at_ms = ${dueAt}, attempts = 0, last_error = NULL, ambiguous = false
+      WHERE ${claim}`;
+    });
+    return {
+        /** A tick is a `$cron:` row; application intents may not use the prefix. */
+        isTick: (row) => row.timer_key?.startsWith(CRON_PREFIX) === true,
+        /**
+         * Settles a tick that must not fire and returns undefined, or returns the
+         * command and payload the relay delivers on this claim.
+         */
+        settleUnfired: Effect.fnUntraced(function* (row, claim, backoffMs) {
+            const schedule = schedules().get(row.actor_type);
+            const entry = entryOf(row);
+            const now = yield* databaseTime;
+            const scheduledAt = Number(row.scheduled_at);
+            const stale = schedule !== undefined && now - scheduledAt > schedule.skipMs;
+            const annotations = {
+                actor: row.actor_type,
+                id: row.actor_id,
+                tenant: row.tenant_id,
+                timerKey: row.timer_key,
+                commandId: row.intent_id,
+            };
+            if (entry === undefined) {
+                if (stale) {
+                    yield* Effect.logInfo("Cron tick removed").pipe(Effect.annotateLogs(annotations));
+                    yield* sql `DELETE FROM actor_outbox WHERE ${claim}`;
+                }
+                else
+                    yield* sql `UPDATE actor_outbox SET due_at_ms = ${now + backoffMs} WHERE ${claim}`;
+                return undefined;
+            }
+            if (stale) {
+                yield* Effect.logInfo("Cron tick skipped").pipe(Effect.annotateLogs({ ...annotations, lateMs: now - scheduledAt }));
+                yield* rewrite(row, entry, claim);
+                return undefined;
+            }
+            if (row.command === entry.command)
+                return { command: row.command, payload: row.payload };
+            const fired = yield* sql `SELECT 1 FROM actor_receipts
+        WHERE routing_key = ${BigInt(row.routing_key)} AND tenant_id = ${row.tenant_id}
+          AND actor_type = ${row.actor_type} AND actor_id = ${row.actor_id}
+          AND command_id = ${row.intent_id}`;
+            if (fired.length > 0) {
+                yield* rewrite(row, entry, claim);
+                return undefined;
+            }
+            return { command: entry.command, payload: yield* entry.payload };
+        }),
+        /** Replaces a delivered tick's row with the entry's next tick. */
+        settleFired: (row, claim) => Effect.suspend(() => {
+            const entry = entryOf(row);
+            return entry === undefined
+                ? sql `DELETE FROM actor_outbox WHERE ${claim}`.pipe(Effect.asVoid)
+                : rewrite(row, entry, claim);
+        }),
+    };
+};

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

@@ -0,0 +1,43 @@
+import { PgClient } from "@effect/sql-pg";
+import { Effect } from "effect";
+import { SqlClient, SqlError, Statement } from "effect/sql";
+/** Extra checkouts each pool holds beyond its connections before refusing further work. */
+export declare const POOL_WAITERS = 64;
+/** SQL-compatible overload keeps caller-facing reads retryable without exposing the internal cause. */
+export declare const poolRefusal: (cause: unknown) => SqlError.SqlError;
+/** Recognizes only our pre-statement checkout refusal, never a failed statement or unknown commit. */
+export declare const isPoolRefusal: (cause: unknown) => boolean;
+/** Retries a pre-statement checkout refusal for scoped startup and background work. */
+export declare const retryPoolRefusal: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+/**
+ * The native Postgres client with at most 64 queued checkouts beyond its
+ * connection capacity, handing its connections out first come, first served.
+ * All SQL entry points share admission, including reservations,
+ * transactions, streams and listeners; bounding only command dispatch would
+ * leave queries and background callers able to grow the pool's waiter list.
+ * A refused checkout sent no statement.
+ *
+ * A checkout passes three stages in order: the bounded admission slot,
+ * refused at once past the limit; a first-come, first-served gate with one
+ * slot per connection, so a caller never waits behind one that asked after
+ * it, which Effect's pool allows because it hands a freed connection to
+ * whichever fiber asks next; then the pool, which therefore never has a
+ * waiter of its own. Both slots belong to the checkout's scope, or to the
+ * borrowed statement, and return with the connection, so cancellation never
+ * leaks either. A statement inside a transaction reuses its connection and
+ * takes neither.
+ *
+ * Apart from the gates it is `PgClient.make`: the same compiler, transforms,
+ * span attributes, commit check, savepoint release, JSON fragments, and
+ * notifications, which use a checkout of their own rather than the caller's
+ * transaction.
+ */
+export declare const boundedPool: (options: PgClient.PgPoolConfig) => Effect.Effect<SqlClient.SqlClient & {
+    "~@effect/sql-pg/PgClient": "~@effect/sql-pg/PgClient";
+    config: PgClient.PgPoolConfig;
+    json: (value: unknown) => Statement.Fragment;
+    listen: (channel: string) => Effect.Effect<import("effect/Queue").Dequeue<import("@effect/sql-pg/PgConnection").Notification, SqlError.SqlError>, SqlError.SqlError, import("effect/Scope").Scope>;
+    notify: (channel: string, payload: string) => Effect.Effect<void, SqlError.SqlError, never>;
+}, SqlError.SqlError, import("effect/reactivity/Reactivity").Reactivity | import("effect/Scope").Scope>;
+/** Provides the bounded primary/off-turn client without changing its connection configuration. */
+export declare const boundedLayer: (options: PgClient.PgPoolConfig) => import("effect/Layer").Layer<PgClient.PgClient | SqlClient.SqlClient, SqlError.SqlError, never>;