@rikalabs/akter 0.1.0-alpha.0

package/dist/testing/conformance/cron.d.ts

@@ -0,0 +1,5 @@
+import type { ConformanceCase } from "../conformance.ts";
+/** Cron cases: tick rows, firing as System, catch-up and skip rules, time zones, and stale ticks from earlier deployments. */
+export declare const cronConformance: ReadonlyArray<ConformanceCase>;
+/** Multi-runner cases: real Postgres only, each on a fresh database and cluster. */
+export declare const cronClusterConformance: ReadonlyArray<ConformanceCase>;

package/dist/testing/conformance/cron.js

@@ -0,0 +1,665 @@
+import { Cause, DateTime, Duration, Effect, Exit, Fiber, Layer, Schedule, Schema } from "effect";
+import { SqlClient } from "effect/sql";
+import { Actor, Intent, NotCreated, System } from "../../index.js";
+import { CallerJson } from "../../runtime/turn/outbox.js";
+import { claimIntents } from "../../runtime/turn/relay.js";
+import { ActorTest } from "../actor-test.js";
+import { ActorCluster } from "../cluster.js";
+import { CLAIM_LEASE } from "./outbox.js";
+const fired = [];
+const firedFor = (id) => fired.filter((run) => run.id === id);
+class Refused extends Schema.TaggedError()("Refused", {}) {
+}
+const Open = Actor.command("Open");
+const Refuse = Actor.command("Refuse", { error: Refused });
+const Stop = Actor.command("Stop");
+const Hijack = Actor.command("Hijack", { payload: Schema.Literals(["key", "cancel"]) });
+const Beat = Actor.command("Beat");
+const Yearly = Actor.command("Yearly");
+const EVERY_MINUTE = "$cron:UTC * * * * *";
+const YEARLY = "$cron:UTC 0 0 1 1 *";
+const SKIP = "10 minutes";
+const Heartbeat = Actor.make("CronHeartbeat", {
+    key: Schema.String,
+    state: Actor.state({
+        beats: Schema.Int.pipe(Schema.withDecodingDefault(Effect.succeed(0))),
+        ignored: Schema.Int.pipe(Schema.withDecodingDefault(Effect.succeed(0))),
+        stopped: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
+    }),
+    api: { Open, Refuse, Stop, Hijack },
+    internal: { Beat, Yearly },
+    policy: {
+        maxScheduleLag: SKIP,
+    },
+    schedules: { "*  * * * *": Beat, "0 0 1 1 *": Yearly },
+});
+const Peek = Actor.command("Peek");
+const Gated = Actor.make("CronGated", {
+    key: Schema.String,
+    api: { Open, Peek },
+    internal: { Beat },
+    createdBy: Open,
+    schedules: { "* * * * *": Beat },
+});
+const Secondly = Actor.make("CronSecondly", {
+    key: Schema.String,
+    api: { Open },
+    internal: { Beat },
+    schedules: { "* * * * * *": Beat },
+});
+const Pulse = Actor.command("Pulse");
+const Beacon = Actor.make("CronBeacon", {
+    key: Actor.singleton,
+    state: Actor.state({ pulses: Schema.Int.pipe(Schema.withDecodingDefault(Effect.succeed(0))) }),
+    api: {},
+    internal: { Pulse },
+    schedules: { "* * * * *": Pulse },
+});
+const Gap = Actor.command("Gap");
+const Fold = Actor.command("Fold");
+const FoldUtc = Actor.command("FoldUtc");
+const Interval = Actor.command("Interval");
+const GAP = "$cron:America/New_York 30 2 * * *";
+const FOLD = "$cron:America/New_York 30 1 * * *";
+const FOLD_UTC = "$cron:UTC 30 1 * * *";
+const INTERVAL = "$cron:@every 300000ms";
+/** Ticks in America/New_York across its real daylight-saving transitions, beside UTC and an interval. */
+const Zoned = Actor.make("CronZoned", {
+    key: Schema.String,
+    api: { Open },
+    internal: { Gap, Fold, FoldUtc, Interval },
+    policy: {
+        maxScheduleLag: "1 hour",
+    },
+    schedules: {
+        "CRON_TZ=America/New_York 30 2 * * *": Gap,
+        "CRON_TZ=America/New_York 30 1 * * *": Fold,
+        "30 1 * * *": FoldUtc,
+        "@every 5 minutes": Interval,
+    },
+});
+const record = (ref, commandId, caller) => Effect.sync(() => {
+    fired.push({
+        actor: ref.actor,
+        id: ref.id,
+        commandId,
+        source: Schema.is(System)(caller) ? caller.source : undefined,
+    });
+});
+const HeartbeatLive = Heartbeat.toLayer(Effect.succeed({
+    Open: () => Effect.void,
+    Refuse: () => Effect.fail(Refused.make()),
+    Stop: Effect.fnUntraced(function* () {
+        yield* (yield* Heartbeat.Turn).state.set({ stopped: true });
+    }),
+    Hijack: Effect.fnUntraced(function* (how) {
+        const turn = yield* Heartbeat.Turn;
+        if (how === "cancel")
+            return yield* Intent.cancel(EVERY_MINUTE);
+        yield* (yield* Heartbeat.intents(turn.ref.id)).Open().pipe(Intent.key(EVERY_MINUTE));
+    }),
+    Beat: Effect.fnUntraced(function* () {
+        const turn = yield* Heartbeat.Turn;
+        yield* record(turn.ref, turn.commandId, turn.caller);
+        if (turn.state.stopped)
+            yield* turn.state.set({ ignored: turn.state.ignored + 1 });
+        else
+            yield* turn.state.set({ beats: turn.state.beats + 1 });
+    }),
+    Yearly: () => Effect.void,
+}));
+const GatedLive = Gated.toLayer(Effect.succeed({
+    Open: () => Effect.void,
+    Peek: () => Effect.void,
+    Beat: Effect.fnUntraced(function* () {
+        const turn = yield* Gated.Turn;
+        yield* record(turn.ref, turn.commandId, turn.caller);
+    }),
+}));
+const SecondlyLive = Secondly.toLayer(Effect.succeed({
+    Open: () => Effect.void,
+    Beat: Effect.fnUntraced(function* () {
+        const turn = yield* Secondly.Turn;
+        yield* record(turn.ref, turn.commandId, turn.caller);
+    }),
+}));
+const BeaconLive = Beacon.toLayer(Effect.succeed({
+    Pulse: Effect.fnUntraced(function* () {
+        const turn = yield* Beacon.Turn;
+        yield* record(turn.ref, turn.commandId, turn.caller);
+        yield* turn.state.set({ pulses: turn.state.pulses + 1 });
+    }),
+}));
+const recordZoned = Effect.gen(function* () {
+    const turn = yield* Zoned.Turn;
+    yield* record(turn.ref, turn.commandId, turn.caller);
+});
+const ZonedLive = Zoned.toLayer(Effect.succeed({
+    Open: () => Effect.void,
+    Gap: () => recordZoned,
+    Fold: () => recordZoned,
+    FoldUtc: () => recordZoned,
+    Interval: () => recordZoned,
+}));
+const CronLive = Layer.mergeAll(HeartbeatLive, GatedLive, SecondlyLive, ZonedLive);
+/**
+ * One runtime of the cron actors for one case. The singleton's minutely tick
+ * joins only when asked, so it cannot take another case's fault injection, and
+ * the case's ticks are removed after it, since PGlite shares one database.
+ */
+const RETRY_WINDOW_MS = 60_000;
+const withRuntime = (environment, body, options = {}) => environment.run(Effect.gen(function* () {
+    const database = yield* environment.freshDatabase;
+    const context = yield* Layer.build(Layer.fresh((options.singleton === true ? Layer.merge(CronLive, BeaconLive) : CronLive).pipe(Layer.provideMerge(ActorTest.layer({
+        database,
+        retryWindowMs: RETRY_WINDOW_MS,
+    })), Layer.orDie)));
+    return yield* body.pipe(Effect.ensuring(Effect.gen(function* () {
+        const sql = yield* SqlClient.SqlClient;
+        const test = yield* ActorTest;
+        yield* sql `DELETE FROM actor_outbox WHERE timer_key LIKE '$cron:%'
+              AND (tenant_id = ${test.tenant} OR actor_type = 'CronBeacon')`;
+    }).pipe(Effect.orDie)), Effect.provideContext(context));
+}));
+const ticksOf = (ref) => Effect.gen(function* () {
+    const sql = yield* SqlClient.SqlClient;
+    return yield* sql `SELECT timer_key, intent_id, command, caller, attempts,
+        due_at_ms::text AS due, scheduled_at_ms::text AS scheduled
+      FROM actor_outbox WHERE tenant_id = ${ref.tenant} AND actor_type = ${ref.actor}
+        AND actor_id = ${ref.id} AND timer_key LIKE '$cron:%'
+      ORDER BY timer_key COLLATE "C" DESC`;
+}).pipe(Effect.orDie);
+const nowMs = ActorTest.use((test) => test.now).pipe(Effect.map((now) => now.epochMilliseconds));
+const MINUTE = 60_000;
+/** Holds when `row` is the first whole minute after `now`. */
+const nextMinuteAfter = (row, now) => row !== undefined &&
+    Number(row.scheduled) === Number(row.due) &&
+    Number(row.scheduled) === (Math.floor(now / MINUTE) + 1) * MINUTE;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+/** Midnight UTC of the `nth` Sunday of `month` (0-based) in `year`. */
+const nthSunday = (year, month, nth) => {
+    const weekday = DateTime.getPartUtc(DateTime.makeUnsafe(Date.UTC(year, month, 1)), "weekDay");
+    return Date.UTC(year, month, 1 + ((7 - weekday) % 7) + 7 * (nth - 1));
+};
+const springForward = (year) => nthSunday(year, 2, 2) + 7 * HOUR;
+const fallBack = (year) => nthSunday(year, 10, 1) + 6 * HOUR;
+/** The first transition at least two days after `now`, so a case can open its actor before it. */
+const upcoming = (transition, now) => {
+    let year = DateTime.getPartUtc(DateTime.makeUnsafe(now), "year");
+    while (transition(year) < now + 2 * DAY)
+        year++;
+    return transition(year);
+};
+const tickOf = (rows, key) => {
+    const row = rows.find((candidate) => candidate.timer_key === key);
+    return row === undefined ? undefined : { id: row.intent_id, scheduled: Number(row.scheduled) };
+};
+const advanceTo = (at) => Effect.gen(function* () {
+    const test = yield* ActorTest;
+    yield* test.advance(Math.max(0, at - (yield* nowMs)));
+});
+/**
+ * Moves the framework clock to one second past the next minute boundary, so a
+ * minutely tick written now is due about 59 seconds ahead. A case that later
+ * advances exactly to that tick then advances by a positive amount however
+ * slowly the database clock moves between its reads.
+ */
+const startOfMinute = Effect.gen(function* () {
+    const now = yield* nowMs;
+    yield* ActorTest.use((test) => test.advance((Math.floor(now / MINUTE) + 1) * MINUTE + 1000 - now));
+});
+const expiresAt = (row) => Number(row.intent_id.split(".")[2]);
+const receipts = (ref, command) => ActorTest.use((test) => test.receiptsFor(ref, command));
+const stateOf = (ref) => ActorTest.use((test) => test.inspect(ref)).pipe(Effect.map(({ state }) => state));
+/** Cron cases: tick rows, firing as System, catch-up and skip rules, time zones, and stale ticks from earlier deployments. */
+export const cronConformance = [
+    {
+        name: "writes one tick per cron entry on the first committed turn, including a declared failure",
+        run: ({ expect, environment }) => withRuntime(environment, Effect.gen(function* () {
+            const heartbeat = yield* Heartbeat.get("first-turn");
+            const before = yield* nowMs;
+            expect(Exit.isFailure(yield* heartbeat.Refuse().pipe(Effect.exit))).toBe(true);
+            const rows = yield* ticksOf(heartbeat.ref);
+            expect(rows.map((row) => [row.timer_key, row.command, row.attempts])).toEqual([
+                [YEARLY, "Yearly", 0],
+                [EVERY_MINUTE, "Beat", 0],
+            ]);
+            expect(nextMinuteAfter(rows[1], before) || nextMinuteAfter(rows[1], before + MINUTE)).toBe(true);
+            const caller = yield* Schema.decodeEffect(CallerJson)(rows[1].caller);
+            expect(Schema.is(System)(caller) ? [caller.source, caller.onBehalfOf] : caller).toEqual([
+                "cron",
+                undefined,
+            ]);
+            yield* heartbeat.Open();
+            yield* ActorTest.use((test) => test.invalidate(heartbeat.ref));
+            yield* heartbeat.Open();
+            expect(yield* ticksOf(heartbeat.ref)).toEqual(rows);
+        })),
+    },
+    {
+        name: "writes no tick for a turn rejected NotCreated",
+        run: ({ expect, environment }) => withRuntime(environment, Effect.gen(function* () {
+            const gated = yield* Gated.get("gated");
+            expect(yield* gated.Peek().pipe(Effect.flip)).toMatchObject({
+                reason: NotCreated.make({}),
+            });
+            expect(yield* ticksOf(gated.ref)).toEqual([]);
+            yield* gated.Open();
+            expect((yield* ticksOf(gated.ref)).map((row) => row.timer_key)).toEqual([EVERY_MINUTE]);
+        })),
+    },
+    {
+        name: "fires a due tick once as System cron and rewrites its row to the next scheduled time",
+        run: ({ expect, environment }) => withRuntime(environment, Effect.gen(function* () {
+            const test = yield* ActorTest;
+            const heartbeat = yield* Heartbeat.get("fires");
+            yield* heartbeat.Open();
+            const [, first] = yield* ticksOf(heartbeat.ref);
+            yield* test.advance("1 minute");
+            const runs = firedFor("fires");
+            expect(runs).toEqual([
+                { actor: "CronHeartbeat", id: "fires", commandId: first.intent_id, source: "cron" },
+            ]);
+            expect(yield* receipts(heartbeat.ref, "Beat")).toBe(1);
+            const [, next] = yield* ticksOf(heartbeat.ref);
+            expect(next.intent_id).not.toBe(first.intent_id);
+            expect(next.attempts).toBe(0);
+            expect(nextMinuteAfter(next, yield* nowMs)).toBe(true);
+            expect(expiresAt(first)).toBe(Number(first.scheduled) + RETRY_WINDOW_MS);
+            expect(expiresAt(next)).toBe(Number(next.scheduled) + RETRY_WINDOW_MS);
+            yield* test.advance("1 minute");
+            expect(yield* stateOf(heartbeat.ref)).toMatchObject({ beats: 2 });
+            expect(new Set(firedFor("fires").map((run) => run.commandId)).size).toBe(2);
+            expect((yield* ticksOf(heartbeat.ref)).length).toBe(2);
+        })),
+    },
+    {
+        name: "schedules a first tick from the time the first turn writes it, not from its admission",
+        run: ({ expect, environment }) => withRuntime(environment, Effect.gen(function* () {
+            const test = yield* ActorTest;
+            const secondly = yield* Secondly.get("slow-first-turn");
+            const admitted = yield* nowMs;
+            const handling = yield* test.pauseNext("beforeHandler");
+            const opening = yield* secondly.Open().pipe(Effect.forkChild);
+            yield* handling.reached;
+            yield* Effect.sleep("1200 millis");
+            const claimed = yield* test.pauseNext("afterClaim");
+            yield* handling.release;
+            yield* Fiber.join(opening);
+            const [tick] = yield* ticksOf(secondly.ref);
+            yield* claimed.release;
+            expect(Number(tick.scheduled) > admitted + 1200).toBe(true);
+        })),
+    },
+    {
+        name: "retargets a pending tick to the entry's current command and fires it once",
+        run: ({ expect, environment }) => withRuntime(environment, Effect.gen(function* () {
+            const sql = yield* SqlClient.SqlClient;
+            const test = yield* ActorTest;
+            const heartbeat = yield* Heartbeat.get("retarget");
+            yield* heartbeat.Open();
+            const [, first] = yield* ticksOf(heartbeat.ref);
+            yield* sql `UPDATE actor_outbox SET command = 'Retired'
+            WHERE intent_id = ${first.intent_id}`;
+            yield* test.advance("1 minute");
+            expect(firedFor("retarget").map((run) => run.commandId)).toEqual([first.intent_id]);
+            expect(yield* receipts(heartbeat.ref, "Beat")).toBe(1);
+            const [, next] = yield* ticksOf(heartbeat.ref);
+            expect(next.command).toBe("Beat");
+            expect(next.intent_id).not.toBe(first.intent_id);
+        })),
+    },
+    {
+        name: "advances a retargeted tick that already fired under its old command without firing it again",
+        run: ({ expect, environment }) => withRuntime(environment, Effect.gen(function* () {
+            const sql = yield* SqlClient.SqlClient;
+            const test = yield* ActorTest;
+            const heartbeat = yield* Heartbeat.get("retarget-fired");
+            yield* startOfMinute;
+            yield* heartbeat.Open();
+            const [, first] = yield* ticksOf(heartbeat.ref);
+            yield* test.crashNext("beforeOutboxDelete");
+            yield* test.advance(Number(first.scheduled) - (yield* nowMs));
+            expect(yield* receipts(heartbeat.ref, "Beat")).toBe(1);
+            yield* sql `UPDATE actor_outbox SET command = 'Retired'
+            WHERE intent_id = ${first.intent_id}`;
+            yield* test.advance(CLAIM_LEASE);
+            expect(firedFor("retarget-fired").map((run) => run.commandId)).toEqual([first.intent_id]);
+            expect(yield* receipts(heartbeat.ref, "Beat")).toBe(1);
+            const [, next] = yield* ticksOf(heartbeat.ref);
+            expect(next).toMatchObject({ command: "Beat", attempts: 0 });
+            expect(next.intent_id).not.toBe(first.intent_id);
+            expect(nextMinuteAfter(next, yield* nowMs)).toBe(true);
+        })),
+    },
+    {
+        name: "fires once after downtime inside the skip window and skips a tick older than it",
+        run: ({ expect, environment }) => withRuntime(environment, Effect.gen(function* () {
+            const test = yield* ActorTest;
+            const heartbeat = yield* Heartbeat.get("downtime");
+            yield* heartbeat.Open();
+            yield* test.advance("5 minutes");
+            expect(yield* stateOf(heartbeat.ref)).toMatchObject({ beats: 1 });
+            expect(nextMinuteAfter((yield* ticksOf(heartbeat.ref))[1], yield* nowMs)).toBe(true);
+            yield* test.advance("15 minutes");
+            expect(yield* stateOf(heartbeat.ref)).toMatchObject({ beats: 1 });
+            expect(yield* receipts(heartbeat.ref, "Beat")).toBe(1);
+            expect(nextMinuteAfter((yield* ticksOf(heartbeat.ref))[1], yield* nowMs)).toBe(true);
+            yield* test.advance("1 minute");
+            expect(yield* stateOf(heartbeat.ref)).toMatchObject({ beats: 2 });
+        })),
+    },
+    {
+        name: "rewrites a tick once after a crash between its receipt and the rewrite",
+        run: ({ expect, environment }) => withRuntime(environment, Effect.gen(function* () {
+            const test = yield* ActorTest;
+            const heartbeat = yield* Heartbeat.get("crash-rewrite");
+            yield* startOfMinute;
+            yield* heartbeat.Open();
+            const [, first] = yield* ticksOf(heartbeat.ref);
+            yield* test.crashNext("beforeOutboxDelete");
+            yield* test.advance(Number(first.scheduled) - (yield* nowMs));
+            expect(yield* receipts(heartbeat.ref, "Beat")).toBe(1);
+            const [, claimed] = yield* ticksOf(heartbeat.ref);
+            expect(claimed).toMatchObject({ intent_id: first.intent_id, attempts: 1 });
+            yield* test.advance(CLAIM_LEASE);
+            expect(yield* receipts(heartbeat.ref, "Beat")).toBe(1);
+            expect(yield* stateOf(heartbeat.ref)).toMatchObject({ beats: 1 });
+            const rows = yield* ticksOf(heartbeat.ref);
+            expect(rows.length).toBe(2);
+            expect(rows[1].intent_id).not.toBe(first.intent_id);
+            expect(nextMinuteAfter(rows[1], yield* nowMs)).toBe(true);
+        })),
+    },
+    {
+        name: "fires a claimed tick once even after the actor stopped, and its handler rechecks state",
+        run: ({ expect, environment }) => withRuntime(environment, Effect.gen(function* () {
+            const test = yield* ActorTest;
+            const heartbeat = yield* Heartbeat.get("claimed-then-stopped");
+            yield* heartbeat.Open();
+            const pause = yield* test.pauseNext("afterClaim");
+            const advancing = yield* test.advance("1 minute").pipe(Effect.forkChild);
+            yield* pause.reached;
+            yield* heartbeat.Stop();
+            yield* pause.release;
+            yield* Fiber.join(advancing);
+            expect(yield* stateOf(heartbeat.ref)).toEqual({ stopped: true, ignored: 1 });
+            expect(firedFor("claimed-then-stopped").length).toBe(1);
+        })),
+    },
+    {
+        name: "rejects application intents that stage or cancel a $cron: key",
+        run: ({ expect, environment }) => withRuntime(environment, Effect.gen(function* () {
+            const heartbeat = yield* Heartbeat.get("reserved");
+            yield* heartbeat.Open();
+            const rows = yield* ticksOf(heartbeat.ref);
+            for (const how of ["key", "cancel"]) {
+                const exit = yield* heartbeat.Hijack(how).pipe(Effect.exit);
+                expect(Exit.isFailure(exit) && Cause.pretty(exit.cause)).toContain("Intent.key values starting with $ are reserved");
+            }
+            expect(yield* ticksOf(heartbeat.ref)).toEqual(rows);
+        })),
+    },
+    {
+        name: "restores a missing entry's tick on the actor's next activation",
+        run: ({ expect, environment }) => withRuntime(environment, Effect.gen(function* () {
+            const test = yield* ActorTest;
+            const sql = yield* SqlClient.SqlClient;
+            const heartbeat = yield* Heartbeat.get("restored");
+            yield* heartbeat.Open();
+            const { ref } = heartbeat;
+            yield* sql `DELETE FROM actor_outbox WHERE tenant_id = ${ref.tenant}
+            AND actor_type = ${ref.actor} AND actor_id = ${ref.id} AND timer_key = ${YEARLY}`.pipe(Effect.orDie);
+            yield* heartbeat.Open();
+            expect((yield* ticksOf(ref)).map((row) => row.timer_key)).toEqual([EVERY_MINUTE]);
+            yield* test.invalidate(ref);
+            yield* heartbeat.Open();
+            expect((yield* ticksOf(ref)).map((row) => row.timer_key)).toEqual([YEARLY, EVERY_MINUTE]);
+        })),
+    },
+    {
+        name: "releases a tick whose entry left the policy and deletes it past the skip window",
+        run: ({ expect, environment }) => withRuntime(environment, Effect.gen(function* () {
+            const test = yield* ActorTest;
+            const sql = yield* SqlClient.SqlClient;
+            yield* startOfMinute;
+            const heartbeat = yield* Heartbeat.get("removed");
+            yield* heartbeat.Open();
+            const { ref } = heartbeat;
+            const removed = "$cron:UTC 5 4 * * *";
+            yield* sql `INSERT INTO actor_outbox (routing_key, intent_id, kind, bucket, due_at_ms,
+              scheduled_at_ms, tenant_id, actor_type, actor_id, timer_key, target_type, target_id,
+              command, payload, caller)
+            SELECT routing_key, intent_id || '-removed', kind, bucket, ${yield* nowMs},
+              ${yield* nowMs}, tenant_id, actor_type, actor_id, ${removed}, target_type,
+              target_id, command, payload, caller
+            FROM actor_outbox WHERE tenant_id = ${ref.tenant} AND actor_type = ${ref.actor}
+              AND actor_id = ${ref.id} AND timer_key = ${EVERY_MINUTE}`.pipe(Effect.orDie);
+            yield* test.advance(0);
+            const released = (yield* ticksOf(ref)).find((row) => row.timer_key === removed);
+            expect(released).toMatchObject({ attempts: 1 });
+            expect(yield* receipts(ref, "Beat")).toBe(0);
+            yield* test.advance("9 minutes");
+            expect((yield* ticksOf(ref)).map((row) => row.timer_key)).toEqual([
+                removed,
+                YEARLY,
+                EVERY_MINUTE,
+            ]);
+            expect(yield* receipts(ref, "Beat")).toBe(1);
+            yield* test.advance("2 minutes");
+            expect((yield* ticksOf(ref)).map((row) => row.timer_key)).toEqual([YEARLY, EVERY_MINUTE]);
+            expect(yield* receipts(ref, "Beat")).toBe(2);
+        })),
+    },
+    {
+        name: "writes a singleton's ticks in the default tenant at startup",
+        run: ({ expect, environment }) => withRuntime(environment, Effect.gen(function* () {
+            const test = yield* ActorTest;
+            const ref = (yield* Beacon.get()).ref;
+            expect(ref.tenant).toBe(test.tenant);
+            const [row] = yield* ticksOf(ref);
+            expect(row).toMatchObject({ timer_key: EVERY_MINUTE, command: "Pulse" });
+            expect(yield* test.inspect(ref)).toMatchObject({ receipts: 0 });
+            yield* test.advance("1 minute");
+            expect(yield* receipts(ref, "Pulse")).toBe(1);
+            expect(yield* stateOf(ref)).toMatchObject({ pulses: 1 });
+        }), { singleton: true }),
+    },
+    {
+        name: "claims $cron: ticks only for actor types registered on the claiming runner",
+        run: ({ expect, environment }) => withRuntime(environment, Effect.gen(function* () {
+            const sql = yield* SqlClient.SqlClient;
+            const heartbeat = yield* Heartbeat.get("claim-filter");
+            yield* heartbeat.Open();
+            const later = (yield* nowMs) + 400 * 24 * 60 * MINUTE;
+            const claim = (cronActors) => claimIntents({
+                sql,
+                now: later,
+                limit: 1000,
+                leaseMs: 1000,
+                maxBackoffMs: 1000,
+                cronActors,
+            }).pipe(Effect.orDie, Effect.map((rows) => rows.filter((row) => row.kind === "intent" && row.target_id === "claim-filter")));
+            expect(yield* claim(["CronGated"])).toEqual([]);
+            const claimed = yield* claim(["CronHeartbeat"]);
+            expect(claimed.map((row) => row.command).toSorted()).toEqual(["Beat", "Yearly"]);
+        })),
+    },
+    {
+        name: "fires a wall-clock time skipped by a spring-forward gap once, at the first instant after the gap",
+        run: ({ expect, environment }) => withRuntime(environment, Effect.gen(function* () {
+            const zoned = yield* Zoned.get("spring-gap");
+            yield* zoned.Open();
+            const { ref } = zoned;
+            const gapEnd = upcoming(springForward, yield* nowMs);
+            yield* advanceTo(gapEnd - MINUTE);
+            const pending = tickOf(yield* ticksOf(ref), GAP);
+            expect(pending?.scheduled).toBe(gapEnd);
+            expect(yield* receipts(ref, "Gap")).toBe(0);
+            yield* advanceTo(gapEnd);
+            expect(firedFor("spring-gap").filter((run) => run.commandId === pending.id)).toEqual([
+                { actor: "CronZoned", id: "spring-gap", commandId: pending.id, source: "cron" },
+            ]);
+            expect(tickOf(yield* ticksOf(ref), GAP)?.scheduled).toBe(gapEnd - 30 * MINUTE + DAY);
+            yield* advanceTo(gapEnd + HOUR + MINUTE);
+            expect(yield* receipts(ref, "Gap")).toBe(1);
+        })),
+    },
+    {
+        name: "fires a wall-clock time repeated by a fall-back transition once, at its first occurrence",
+        run: ({ expect, environment }) => withRuntime(environment, Effect.gen(function* () {
+            const zoned = yield* Zoned.get("fall-fold");
+            yield* zoned.Open();
+            const { ref } = zoned;
+            const transition = upcoming(fallBack, yield* nowMs);
+            const firstOccurrence = transition - 30 * MINUTE;
+            const secondOccurrence = transition + 30 * MINUTE;
+            yield* advanceTo(firstOccurrence - MINUTE);
+            const pending = tickOf(yield* ticksOf(ref), FOLD);
+            expect(pending?.scheduled).toBe(firstOccurrence);
+            yield* advanceTo(transition + 10 * MINUTE);
+            expect(yield* receipts(ref, "Fold")).toBe(1);
+            expect(firedFor("fall-fold").filter((run) => run.commandId === pending.id).length).toBe(1);
+            expect(tickOf(yield* ticksOf(ref), FOLD)?.scheduled).toBe(secondOccurrence + DAY);
+            yield* advanceTo(secondOccurrence + MINUTE);
+            expect(yield* receipts(ref, "Fold")).toBe(1);
+        })),
+    },
+    {
+        name: "keeps one expression in two zones as two entries that fire at their own times",
+        run: ({ expect, environment }) => withRuntime(environment, Effect.gen(function* () {
+            const zoned = yield* Zoned.get("two-zones");
+            yield* zoned.Open();
+            const { ref } = zoned;
+            const transition = upcoming(fallBack, yield* nowMs);
+            const nextUtc = transition - 6 * HOUR + DAY + 90 * MINUTE;
+            yield* advanceTo(transition - 31 * MINUTE);
+            const rows = yield* ticksOf(ref);
+            const newYork = tickOf(rows, FOLD);
+            const utc = tickOf(rows, FOLD_UTC);
+            expect(newYork?.scheduled).toBe(transition - 30 * MINUTE);
+            expect(utc?.scheduled).toBe(nextUtc);
+            expect(newYork?.id).not.toBe(utc?.id);
+            yield* advanceTo(transition - 30 * MINUTE);
+            expect([yield* receipts(ref, "Fold"), yield* receipts(ref, "FoldUtc")]).toEqual([1, 0]);
+            yield* advanceTo(nextUtc);
+            expect([yield* receipts(ref, "Fold"), yield* receipts(ref, "FoldUtc")]).toEqual([1, 1]);
+            expect(firedFor("two-zones")
+                .map((run) => run.commandId)
+                .filter((id) => id === newYork.id || id === utc.id)
+                .toSorted()).toEqual([newYork.id, utc.id].toSorted());
+        })),
+    },
+    {
+        name: "fires a fixed interval at multiples of its length and once after downtime",
+        run: ({ expect, environment }) => withRuntime(environment, Effect.gen(function* () {
+            const zoned = yield* Zoned.get("interval");
+            const opened = yield* nowMs;
+            yield* zoned.Open();
+            const { ref } = zoned;
+            const interval = 5 * MINUTE;
+            const first = tickOf(yield* ticksOf(ref), INTERVAL);
+            expect(first.scheduled % interval).toBe(0);
+            expect(first.scheduled > opened && first.scheduled <= opened + interval + 30_000).toBe(true);
+            yield* advanceTo(first.scheduled);
+            expect(yield* receipts(ref, "Interval")).toBe(1);
+            const second = tickOf(yield* ticksOf(ref), INTERVAL);
+            expect(second.scheduled).toBe(first.scheduled + interval);
+            yield* advanceTo(second.scheduled + 4 * interval + interval / 2);
+            expect(yield* receipts(ref, "Interval")).toBe(2);
+            expect(tickOf(yield* ticksOf(ref), INTERVAL)?.scheduled).toBe(second.scheduled + 5 * interval);
+        })),
+    },
+];
+const EXPIRATION_SECONDS = 3;
+/** A poll far longer than any case, so only a runner's own `advance` claims its rows. */
+const NO_POLL = { poll: "1 hour" };
+const withCluster = (environment, runners, body) => environment.run(Effect.gen(function* () {
+    const database = yield* environment.freshDatabase;
+    const context = yield* Layer.build(ActorTest.cluster({
+        database,
+        runners,
+        shardLockExpiration: `${EXPIRATION_SECONDS} seconds`,
+        actors: BeaconLive,
+        relay: NO_POLL,
+    }));
+    return yield* body.pipe(Effect.provideContext(context));
+}));
+const on = (runner, effect) => ActorCluster.use((cluster) => cluster.on(runner)(effect));
+const advanceOn = (runner, duration) => on(runner, ActorTest.use((test) => test.advance(duration)));
+const beaconRef = on(0, Beacon.get().pipe(Effect.map((beacon) => beacon.ref)));
+const pulsesOn = (runner, ref) => on(runner, receipts(ref, "Pulse"));
+const eventually = (check, what) => check.pipe(Effect.repeat({ schedule: Schedule.spaced("25 millis"), until: (held) => held }), Effect.timeoutOrElse({
+    duration: "30 seconds",
+    orElse: () => Effect.die(new Error(`Timed out waiting for ${what}`)),
+}), Effect.asVoid);
+const kill = (runner) => ActorCluster.use((cluster) => cluster.kill(runner).pipe(Effect.andThen(cluster.ready)));
+/** Multi-runner cases: real Postgres only, each on a fresh database and cluster. */
+export const cronClusterConformance = [
+    {
+        name: "keeps one singleton tick row and fires one logical tick per scheduled time on three runners",
+        requiresIndependentConnections: true,
+        timeoutMs: 90_000,
+        run: ({ expect, environment }) => withCluster(environment, 3, Effect.gen(function* () {
+            const cluster = yield* ActorCluster;
+            yield* cluster.ready;
+            const ref = yield* beaconRef;
+            const before = fired.length;
+            expect((yield* on(1, ticksOf(ref))).length).toBe(1);
+            for (const round of [1, 2, 3]) {
+                yield* Effect.forEach([0, 1, 2], (runner) => advanceOn(runner, "1 minute"), {
+                    concurrency: "unbounded",
+                    discard: true,
+                });
+                yield* eventually(pulsesOn(2, ref).pipe(Effect.map((count) => count === round)), `tick ${round}`);
+            }
+            const runs = fired.slice(before).filter((run) => run.id === ref.id);
+            expect(new Set(runs.map((run) => run.commandId)).size).toBe(3);
+            expect(yield* pulsesOn(0, ref)).toBe(3);
+            expect((yield* on(0, ticksOf(ref))).length).toBe(1);
+        })),
+    },
+    ...["afterClaim", "beforeOutboxDelete"].map((point) => ({
+        name: `fires a tick once when the runner delivering it is killed at ${point}`,
+        requiresIndependentConnections: true,
+        timeoutMs: 90_000,
+        run: ({ expect, environment }) => withCluster(environment, 3, Effect.gen(function* () {
+            const cluster = yield* ActorCluster;
+            yield* cluster.ready;
+            const ref = yield* beaconRef;
+            const [first] = yield* on(1, ticksOf(ref));
+            const pause = yield* on(0, ActorTest.use((test) => test.pauseNext(point)));
+            yield* advanceOn(0, "1 minute").pipe(Effect.forkChild);
+            yield* pause.reached;
+            yield* kill(0);
+            yield* advanceOn(1, "1 minute");
+            yield* advanceOn(2, "1 minute");
+            const held = yield* on(1, ticksOf(ref));
+            expect(held).toMatchObject([{ intent_id: first.intent_id, attempts: 1 }]);
+            expect(yield* pulsesOn(1, ref)).toBe(point === "afterClaim" ? 0 : 1);
+            yield* advanceOn(1, CLAIM_LEASE);
+            yield* advanceOn(2, CLAIM_LEASE);
+            yield* eventually(on(1, ticksOf(ref)).pipe(Effect.map((rows) => rows.length === 1 && rows[0].intent_id !== first.intent_id)), "the tick's rewrite");
+            expect(yield* pulsesOn(1, ref)).toBe(1);
+            expect(yield* on(2, stateOf(ref))).toMatchObject({ pulses: 1 });
+            expect((yield* on(1, ticksOf(ref)))[0]).toMatchObject({ attempts: 0 });
+        })),
+    })),
+    {
+        name: "keeps a singleton's ticks firing after its runner is killed",
+        requiresIndependentConnections: true,
+        timeoutMs: 90_000,
+        run: ({ expect, environment }) => withCluster(environment, 3, Effect.gen(function* () {
+            const cluster = yield* ActorCluster;
+            yield* cluster.ready;
+            const ref = yield* beaconRef;
+            const owner = (yield* cluster.owner(ref));
+            const survivor = (owner + 1) % 3;
+            yield* kill(owner);
+            yield* advanceOn(survivor, "1 minute");
+            yield* eventually(pulsesOn(survivor, ref).pipe(Effect.map((count) => count === 1)), "a tick on a survivor");
+            expect((yield* on(survivor, ticksOf(ref))).length).toBe(1);
+        })),
+    },
+];