@rikalabs/akter 0.1.0-alpha.0

package/dist/testing/conformance/operator.js

@@ -0,0 +1,379 @@
+import { Effect, Layer, Option, Schema } from "effect";
+import { SqlClient } from "effect/sql";
+import { Actor, Actors } from "../../index.js";
+import { ActorTest } from "../actor-test.js";
+import { operatorHarness } from "./operator-harness.js";
+class Declined extends Schema.TaggedError()("OpDeclined", { reason: Schema.String }) {
+}
+class ProviderDown extends Schema.TaggedError()("OpProviderDown", {}) {
+}
+const Charge = Actor.job("OpCharge", {
+    payload: { amount: Schema.Finite },
+});
+const Ship = Actor.job("OpShip", { payload: { parcel: Schema.String } });
+const Pay = Actor.command("Pay", { payload: Schema.Finite, success: Schema.String });
+const Refuse = Actor.command("Refuse", { payload: Schema.String, error: Declined });
+const Send = Actor.command("Send", { payload: Schema.String });
+const Jam = Actor.command("Jam");
+const Till = Actor.make("OpTill", {
+    key: Schema.String,
+    jobs: {
+        OpCharge: { job: Charge, retry: { times: 0 } },
+        OpShip: { job: Ship, retry: { times: 0 } },
+    },
+    api: { Pay, Refuse, Send, Jam },
+});
+/** Counts handler runs and executor calls, and decides whether the provider is up. */
+const fixture = {
+    handlerRuns: 0,
+    charges: [],
+    ships: [],
+    up: false,
+};
+const live = Layer.mergeAll(Till.toLayer(Effect.succeed({
+    Pay: Effect.fnUntraced(function* (amount) {
+        fixture.handlerRuns += 1;
+        yield* (yield* Till.Turn).enqueue(Charge.make({ amount }));
+        return `paid ${amount}`;
+    }),
+    Refuse: (reason) => Effect.suspend(() => {
+        fixture.handlerRuns += 1;
+        return Effect.fail(Declined.make({ reason }));
+    }),
+    Jam: () => Effect.die(new Error("till jammed")),
+    Send: Effect.fnUntraced(function* (parcel) {
+        fixture.handlerRuns += 1;
+        yield* (yield* Till.Turn).enqueue(Ship.make({ parcel }));
+    }),
+})), Till.toJobLayer(Effect.succeed({
+    OpCharge: Effect.fnUntraced(function* () {
+        const executor = yield* Till.Executor;
+        fixture.charges.push(executor.jobId);
+        if (!fixture.up)
+            return yield* ProviderDown.make({});
+    }),
+    OpShip: Effect.fnUntraced(function* () {
+        const executor = yield* Till.Executor;
+        fixture.ships.push(executor.jobId);
+        if (!fixture.up)
+            return yield* Effect.die(new Error("carrier reply lost"));
+    }),
+})));
+/** One capability of `action` over `scope`. */
+const capability = (action, scope) => ({
+    action,
+    ...scope,
+});
+const encodeJson = Schema.encodeEffect(Schema.fromJsonString(Schema.Unknown));
+const withOperators = (environment, tokens, body) => operatorHarness({
+    environment,
+    live,
+    reset: () => {
+        Object.assign(fixture, { handlerRuns: 0, charges: [], ships: [], up: false });
+    },
+    tokens,
+    body,
+});
+const till = (tenant) => ({ tenant, actorType: "OpTill", actorId: "t1" });
+const paths = (tenant) => ({
+    inspect: `/operator/actors/OpTill/t1?tenant=${tenant}`,
+    receipt: (commandId) => `/operator/receipts/OpTill/t1/${commandId}?tenant=${tenant}`,
+    retry: (jobId) => `/operator/dead-letters/${jobId}/retry`,
+    discard: (jobId) => `/operator/dead-letters/${jobId}/discard`,
+    defects: `/operator/defects?tenant=${tenant}`,
+    audit: `/operator/audit?tenant=${tenant}`,
+});
+/** One dead letter of `OpCharge` (not ambiguous) on `OpTill/t1`, left by a failed charge. */
+const deadCharge = Effect.gen(function* () {
+    yield* (yield* Till.get("t1")).Pay(5);
+    yield* (yield* ActorTest).advance(0);
+});
+/** One dead letter of `OpShip`, ambiguous because the carrier's reply was lost. */
+const deadShipment = Effect.gen(function* () {
+    yield* (yield* Till.get("t1")).Send("box");
+    yield* (yield* ActorTest).advance(0);
+});
+const reasonOf = (answer) => Schema.decodeUnknownOption(Schema.Struct({ reason: Schema.Struct({ _tag: Schema.String, code: Schema.String }) }))(answer.body);
+/** Operator cases: application credentials are refused, grants are scoped by action and resource with audited denials, and inspection and repair follow their scopes. */
+export const operatorConformance = [
+    {
+        name: "refuses an application credential on every operator route and repairs nothing",
+        run: ({ expect, environment }) => withOperators(environment, { "operator-token": [capability("dead-letters.retry", { tenant: "*" })] }, ({ tenant, send, deadLetters, audit }) => Effect.gen(function* () {
+            yield* deadCharge;
+            const [letter] = yield* deadLetters;
+            const at = paths(tenant);
+            const body = { ...till(tenant), reason: "customer asked" };
+            for (const token of ["app-token", undefined])
+                for (const [method, path, payload] of [
+                    ["GET", at.inspect, undefined],
+                    ["GET", at.receipt("v1.0.0.x"), undefined],
+                    ["GET", at.defects, undefined],
+                    ["GET", at.audit, undefined],
+                    ["POST", at.retry(letter.job_id), body],
+                    ["POST", at.discard(letter.job_id), body],
+                ]) {
+                    const answer = yield* send(method, path, token, payload);
+                    expect(answer.status).toBe(401);
+                }
+            expect((yield* deadLetters).length).toBe(1);
+            expect(fixture.charges.length).toBe(1);
+            expect(yield* audit).toEqual([]);
+        })),
+    },
+    {
+        name: "refuses a grant outside its action or resource scope, audits the denial, and changes nothing",
+        run: ({ expect, environment }) => withOperators(environment, {
+            "narrow-token": [
+                capability("dead-letters.retry", { tenant: "*", actorType: "OpTill", actorId: "t2" }),
+                capability("inspect", { tenant: "*", actorType: "OpTill", actorId: "t1" }),
+            ],
+        }, ({ tenant, send, deadLetters, audit }) => Effect.gen(function* () {
+            yield* deadCharge;
+            const [letter] = yield* deadLetters;
+            const at = paths(tenant);
+            const refused = yield* send("POST", at.retry(letter.job_id), "narrow-token", {
+                ...till(tenant),
+                reason: "try again",
+            });
+            expect(refused.status).toBe(403);
+            expect(Option.getOrUndefined(reasonOf(refused))?.reason).toMatchObject({
+                code: "access_denied",
+            });
+            expect((yield* send("GET", at.audit, "narrow-token")).status).toBe(403);
+            expect((yield* deadLetters).length).toBe(1);
+            expect(fixture.charges.length).toBe(1);
+            expect(yield* audit).toMatchObject([
+                {
+                    operator: "op-narrow-token",
+                    action: "dead-letters.retry",
+                    actor_id: "t1",
+                    target: letter.job_id,
+                    capability: null,
+                    outcome: '"denied"',
+                },
+                { operator: "op-narrow-token", action: "audit.read", outcome: '"denied"' },
+            ]);
+        })),
+    },
+    {
+        name: "inspects an actor with receipt tags only, and outcomes only under receipts.read",
+        run: ({ expect, environment }) => withOperators(environment, {
+            "look-token": [capability("inspect", { tenant: "*" })],
+            "read-token": [
+                capability("inspect", { tenant: "*" }),
+                capability("receipts.read", { tenant: "*", actorType: "OpTill" }),
+            ],
+        }, ({ tenant, send, audit }) => Effect.gen(function* () {
+            fixture.up = true;
+            yield* (yield* Till.get("t1")).Pay(7);
+            const at = paths(tenant);
+            const looked = yield* send("GET", at.inspect, "look-token");
+            expect(looked.status).toBe(200);
+            expect(looked.body).toMatchObject({
+                actor: { actorType: "OpTill", actorId: "t1", generation: 1 },
+                receipts: [{ command: "Pay", outcomeTag: "Success" }],
+            });
+            expect(looked.body.receipts.every((receipt) => !("outcome" in receipt))).toBe(true);
+            const read = yield* send("GET", at.inspect, "read-token");
+            expect(read.body).toMatchObject({
+                receipts: [{ command: "Pay", outcome: { json: { value: '{"value":"paid 7"}' } } }],
+            });
+            expect((yield* send("GET", `/operator/actors/OpTill/missing?tenant=${tenant}`, "look-token"))
+                .status).toBe(404);
+            expect((yield* audit).map(({ action, outcome }) => [action, outcome])).toEqual([
+                ["inspect", '{"outcomes":false}'],
+                ["inspect", '{"outcomes":true}'],
+                ["inspect", '{"outcomes":false}'],
+            ]);
+        })),
+    },
+    {
+        name: "reads a success and a declared-failure outcome under a receipt-scoped grant without running the handler",
+        run: ({ expect, environment }) => withOperators(environment, {}, ({ tenant, send, audit, grant }) => Effect.gen(function* () {
+            const actors = yield* Actors;
+            const ids = {
+                paid: yield* actors.mintCommandId,
+                refused: yield* actors.mintCommandId,
+                other: yield* actors.mintCommandId,
+            };
+            const one = (commandId) => capability("receipts.read", {
+                tenant: "*",
+                actorType: "OpTill",
+                actorId: "t1",
+                commandId,
+            });
+            yield* grant("receipt-token", [one(ids.paid), one(ids.refused)]);
+            fixture.up = true;
+            const till1 = yield* Till.get("t1");
+            yield* till1.Pay(3).pipe(Actor.commandId(ids.paid));
+            yield* till1.Refuse("closed").pipe(Actor.commandId(ids.refused), Effect.ignore);
+            yield* till1.Pay(4).pipe(Actor.commandId(ids.other));
+            const runs = fixture.handlerRuns;
+            const at = paths(tenant);
+            expect(yield* send("GET", at.receipt(ids.paid), "receipt-token")).toMatchObject({
+                status: 200,
+                body: {
+                    commandId: ids.paid,
+                    command: "Pay",
+                    outcomeTag: "Success",
+                    outcome: { json: { value: '{"value":"paid 3"}' } },
+                },
+            });
+            const failure = yield* send("GET", at.receipt(ids.refused), "receipt-token");
+            expect(failure).toMatchObject({
+                status: 200,
+                body: { command: "Refuse", outcomeTag: "Failure" },
+            });
+            expect(yield* encodeJson(failure.body).pipe(Effect.orDie)).toContain("closed");
+            expect((yield* send("GET", at.receipt(ids.other), "receipt-token")).status).toBe(403);
+            expect(fixture.handlerRuns).toBe(runs);
+            expect((yield* audit).map(({ action, target, outcome }) => [action, target, outcome])).toEqual([
+                ["receipts.read", ids.paid, '"read"'],
+                ["receipts.read", ids.refused, '"read"'],
+                ["receipts.read", ids.other, '"denied"'],
+            ]);
+        })),
+    },
+    {
+        name: "retries a dead letter as a new effect and records operator, scope, reason, and the new effect id in the same transaction",
+        run: ({ expect, environment }) => withOperators(environment, {
+            "repair-token": [capability("dead-letters.retry", { tenant: "*", actorType: "OpTill" })],
+        }, ({ tenant, send, deadLetters, audit }) => Effect.gen(function* () {
+            yield* deadCharge;
+            const [letter] = yield* deadLetters;
+            fixture.up = true;
+            const retried = yield* send("POST", paths(tenant).retry(letter.job_id), "repair-token", {
+                ...till(tenant),
+                reason: "provider back up",
+            });
+            expect(retried.status).toBe(200);
+            const { jobId } = retried.body;
+            expect(jobId).not.toBe(letter.job_id);
+            yield* (yield* ActorTest).advance(0);
+            expect(fixture.charges).toEqual([letter.job_id, jobId]);
+            expect(yield* deadLetters).toEqual([]);
+            const [row] = yield* audit;
+            expect(row).toMatchObject({
+                operator: "op-repair-token",
+                action: "dead-letters.retry",
+                actor_id: "t1",
+                target: letter.job_id,
+                reason: "provider back up",
+                capability: '{"action":"dead-letters.retry","tenant":"*","actorType":"OpTill"}',
+            });
+            expect(row.outcome).toContain(`"jobId":"${jobId}"`);
+            expect(row.outcome).toContain('"providerChecked":false');
+            const again = yield* send("POST", paths(tenant).retry(letter.job_id), "repair-token", {
+                ...till(tenant),
+                reason: "again",
+            });
+            expect(again.status).toBe(404);
+            expect(fixture.charges.length).toBe(2);
+        })),
+    },
+    {
+        name: "lets one of two concurrent repairs of a dead letter through",
+        requiresIndependentConnections: true,
+        run: ({ expect, environment }) => withOperators(environment, { "repair-token": [capability("dead-letters.retry", { tenant: "*" })] }, ({ tenant, send, deadLetters, audit }) => Effect.gen(function* () {
+            yield* deadCharge;
+            const [letter] = yield* deadLetters;
+            fixture.up = true;
+            const body = { ...till(tenant), reason: "race" };
+            const answers = yield* Effect.forEach([1, 2], () => send("POST", paths(tenant).retry(letter.job_id), "repair-token", body), { concurrency: "unbounded" });
+            expect(answers.map(({ status }) => status).toSorted((a, b) => a - b)).toEqual([
+                200, 404,
+            ]);
+            yield* (yield* ActorTest).advance(0);
+            expect(fixture.charges.length).toBe(2);
+            expect((yield* audit).length).toBe(1);
+        })),
+    },
+    {
+        name: "refuses to retry an ambiguous dead letter until the operator states the provider was checked",
+        run: ({ expect, environment }) => withOperators(environment, { "repair-token": [capability("dead-letters.retry", { tenant: "*" })] }, ({ tenant, send, deadLetters, audit }) => Effect.gen(function* () {
+            yield* deadShipment;
+            const [letter] = yield* deadLetters;
+            expect(letter.ambiguous).toBe(true);
+            const body = { ...till(tenant), reason: "carrier says it never arrived" };
+            const refused = yield* send("POST", paths(tenant).retry(letter.job_id), "repair-token", body);
+            expect(refused).toMatchObject({
+                status: 409,
+                body: { jobId: letter.job_id },
+            });
+            expect((yield* deadLetters).length).toBe(1);
+            expect(yield* audit).toEqual([]);
+            fixture.up = true;
+            const checked = yield* send("POST", paths(tenant).retry(letter.job_id), "repair-token", {
+                ...body,
+                providerChecked: true,
+            });
+            expect(checked.status).toBe(200);
+            yield* (yield* ActorTest).advance(0);
+            expect(fixture.ships.length).toBe(2);
+            expect((yield* audit)[0].outcome).toContain('"providerChecked":true');
+        })),
+    },
+    {
+        name: "discards a dead letter with its audit row and never records its payload",
+        run: ({ expect, environment }) => withOperators(environment, { "repair-token": [capability("dead-letters.discard", { tenant: "*" })] }, ({ tenant, send, deadLetters, audit }) => Effect.gen(function* () {
+            yield* deadCharge;
+            const [letter] = yield* deadLetters;
+            const body = { ...till(tenant), reason: "refunded by hand" };
+            expect((yield* send("POST", paths(tenant).retry(letter.job_id), "repair-token", body))
+                .status).toBe(403);
+            const discarded = yield* send("POST", paths(tenant).discard(letter.job_id), "repair-token", body);
+            expect(discarded).toMatchObject({ status: 200, body: { discarded: letter.job_id } });
+            expect(yield* deadLetters).toEqual([]);
+            expect((yield* send("POST", paths(tenant).discard(letter.job_id), "repair-token", body))
+                .status).toBe(404);
+            const rows = yield* audit;
+            expect(rows.map(({ action, outcome }) => [action, outcome.includes("OpCharge")])).toEqual([
+                ["dead-letters.retry", false],
+                ["dead-letters.discard", true],
+            ]);
+            expect(rows[1].outcome).not.toContain("amount");
+            expect(rows[1].reason).toBe("refunded by hand");
+            expect(fixture.charges.length).toBe(1);
+        })),
+    },
+    {
+        name: "rolls the repair back when its audit row cannot be written",
+        run: ({ expect, environment }) => withOperators(environment, { "repair-token": [capability("dead-letters.retry", { tenant: "*" })] }, ({ tenant, send, deadLetters }) => Effect.gen(function* () {
+            const sql = yield* SqlClient.SqlClient;
+            yield* deadCharge;
+            const [letter] = yield* deadLetters;
+            fixture.up = true;
+            yield* sql `CREATE FUNCTION op_audit_refuse() RETURNS trigger LANGUAGE plpgsql AS $$
+                BEGIN RAISE EXCEPTION 'audit unavailable'; END $$`.pipe(Effect.orDie);
+            yield* sql `CREATE TRIGGER op_audit_refuse BEFORE INSERT ON actor_operator_audit
+                FOR EACH ROW EXECUTE FUNCTION op_audit_refuse()`.pipe(Effect.orDie);
+            const failed = yield* send("POST", paths(tenant).retry(letter.job_id), "repair-token", {
+                ...till(tenant),
+                reason: "try",
+            });
+            expect(failed.status).toBe(500);
+            expect((yield* deadLetters).map(({ job_id }) => job_id)).toEqual([letter.job_id]);
+            const [pending] = yield* sql `
+              SELECT count(*)::int AS count FROM actor_outbox WHERE kind = 'job'`.pipe(Effect.orDie);
+            expect(pending.count).toBe(0);
+            yield* (yield* ActorTest).advance(0);
+            expect(fixture.charges.length).toBe(1);
+        })),
+    },
+    {
+        name: "lists defects only under defects.read, for the grant's tenants",
+        run: ({ expect, environment }) => withOperators(environment, {
+            "defects-token": [capability("defects.read", { tenant: "*" })],
+            "look-token": [capability("inspect", { tenant: "*" })],
+        }, ({ tenant, send }) => Effect.gen(function* () {
+            yield* (yield* Till.get("t1")).Jam().pipe(Effect.exit);
+            expect((yield* send("GET", paths(tenant).defects, "look-token")).status).toBe(403);
+            const listed = yield* send("GET", paths(tenant).defects, "defects-token");
+            expect(listed).toMatchObject({
+                status: 200,
+                body: [{ span: "akter.OpTill/Jam", actorId: "t1", tenant }],
+            });
+            expect((yield* send("GET", paths("another-tenant").defects, "defects-token")).body).toEqual([]);
+        })),
+    },
+];

package/dist/testing/conformance/outbox-cross-shard.d.ts

@@ -0,0 +1,14 @@
+import { Layer } from "effect";
+import type { ConformanceCase, ConformanceSuite } from "../conformance.ts";
+export declare const crossShardLayer: Layer.Layer<never, never, import("../index.ts").InternalActors>;
+/**
+ * The cross-shard cases of the Outbox delivery gate. The sender's outbox row
+ * lives under the sender's routing key and the receiver's receipt under the
+ * receiver's, so each delivery is a write on one shard followed by a write on
+ * another, with the row deleted only after the second commits. On Postgres
+ * and PGlite these prove the protocol holds across routing keys; whether the
+ * keys are on different Neki shards is the topology of the run in #66.
+ */
+export declare const crossShardOutboxConformance: ReadonlyArray<ConformanceCase>;
+/** Cross-shard mailbox actors. */
+export declare const crossShardSuite: ConformanceSuite;

package/dist/testing/conformance/outbox-cross-shard.js

@@ -0,0 +1,160 @@
+import { Duration, Effect, Fiber, Layer, Schema } from "effect";
+import { SqlClient } from "effect/sql";
+import { Actor, Intent } from "../../index.js";
+import { routingKey } from "../../runtime/storage/codec.js";
+import { ActorTest } from "../actor-test.js";
+import { CLAIM_LEASE } from "./outbox.js";
+const Receive = Actor.command("Receive", { payload: Schema.String });
+const Touch = Actor.command("Touch");
+const Bodies = Actor.query("Bodies", { success: Schema.Array(Schema.String) });
+/** An actor placed by its own id, so a receiver can sit on another shard than its sender. */
+const Mailbox = Actor.make("ShardMailbox", {
+    key: Schema.String,
+    placement: "actor",
+    state: Actor.state({
+        bodies: Schema.Array(Schema.String).pipe(Schema.withDecodingDefault(Effect.succeed([]))),
+    }),
+    api: { Touch, Bodies },
+    internal: { Receive },
+});
+const Post = Actor.command("Post", {
+    payload: Schema.Struct({ to: Schema.String, body: Schema.String, afterMs: Schema.Int }),
+});
+const Poster = Actor.make("ShardPoster", {
+    key: Schema.String,
+    placement: "actor",
+    api: { Post },
+});
+/** Receiver handler runs by body, a rolled-back run included. */
+const taken = new Map();
+export const crossShardLayer = Layer.mergeAll(Mailbox.toLayer(Effect.succeed({
+    Touch: () => Effect.void,
+    Receive: Effect.fnUntraced(function* (body) {
+        const turn = yield* Mailbox.Turn;
+        taken.set(body, (taken.get(body) ?? 0) + 1);
+        yield* turn.state.set({ bodies: [...turn.state.bodies, body] });
+    }),
+})), Mailbox.toQueryLayer(Effect.succeed({
+    Bodies: Effect.fnUntraced(function* () {
+        return (yield* Mailbox.Read).state.bodies;
+    }),
+})), Poster.toLayer(Effect.succeed({
+    Post: Effect.fnUntraced(function* ({ to, body, afterMs }) {
+        yield* (yield* Mailbox.intents(to))
+            .Receive(body)
+            .pipe(Intent.after(Duration.millis(afterMs)));
+    }),
+})));
+/**
+ * A sender and a receiver whose routing keys sit in opposite halves of the
+ * 64-bit range: with two or more shards splitting that range, they are on
+ * different ones. The Neki run's topology has to split it; the pair only
+ * guarantees they are far apart. Ids carry the scenario, so cases sharing a
+ * tenant never share an actor.
+ */
+const across = Effect.fnUntraced(function* (scenario) {
+    const test = yield* ActorTest;
+    const keyOf = (actor, id) => routingKey({ ref: { tenant: test.tenant, actor, id }, placement: "actor" });
+    const sender = Array.from({ length: 256 }, (_, index) => `${scenario}-from-${index}`).find((id) => keyOf("ShardPoster", id) < 0n);
+    const receiver = Array.from({ length: 256 }, (_, index) => `${scenario}-to-${index}`).find((id) => keyOf("ShardMailbox", id) >= 0n);
+    if (sender === undefined || receiver === undefined)
+        return yield* Effect.die(new Error("No sender and receiver in opposite halves of the range"));
+    return {
+        sender: yield* Poster.get(sender),
+        receiver: yield* Mailbox.get(receiver),
+        senderKey: keyOf("ShardPoster", sender),
+        receiverKey: keyOf("ShardMailbox", receiver),
+    };
+});
+const keysOf = Effect.fnUntraced(function* (table, ref) {
+    const sql = yield* SqlClient.SqlClient;
+    const rows = yield* sql `
+    SELECT DISTINCT routing_key::text AS key FROM ${sql(table)}
+    WHERE tenant_id = ${ref.tenant} AND actor_type = ${ref.actor} AND actor_id = ${ref.id}`.pipe(Effect.orDie);
+    return rows.map(({ key }) => key);
+});
+/**
+ * The cross-shard cases of the Outbox delivery gate. The sender's outbox row
+ * lives under the sender's routing key and the receiver's receipt under the
+ * receiver's, so each delivery is a write on one shard followed by a write on
+ * another, with the row deleted only after the second commits. On Postgres
+ * and PGlite these prove the protocol holds across routing keys; whether the
+ * keys are on different Neki shards is the topology of the run in #66.
+ */
+export const crossShardOutboxConformance = [
+    {
+        name: "cross-shard outbox: delivers an intent from the sender's routing key to a receiver under another one",
+        run: ({ expect, environment }) => environment.run(Effect.gen(function* () {
+            const test = yield* ActorTest;
+            const { sender, receiver, senderKey, receiverKey } = yield* across("deliver");
+            yield* sender.Post({ to: receiver.ref.id, body: "hello", afterMs: 60_000 });
+            expect(yield* keysOf("actor_outbox", sender.ref)).toEqual([String(senderKey)]);
+            yield* test.advance("1 minute");
+            expect(yield* receiver.Bodies().pipe(Effect.orDie)).toEqual(["hello"]);
+            expect(yield* keysOf("actor_receipts", receiver.ref)).toEqual([String(receiverKey)]);
+            expect(String(senderKey) === String(receiverKey)).toBe(false);
+            expect(yield* test.receiptsFor(receiver.ref, "Receive")).toBe(1);
+            expect(yield* test.inspect(sender.ref)).toMatchObject({ receipts: 1, outbox: 0 });
+        })),
+    },
+    {
+        name: "cross-shard outbox: a crash before delivery leaves the row and the receiver untouched, and the redelivery lands once",
+        run: ({ expect, environment }) => environment.run(Effect.gen(function* () {
+            const test = yield* ActorTest;
+            const { sender, receiver } = yield* across("before-delivery");
+            yield* sender.Post({ to: receiver.ref.id, body: "before-delivery", afterMs: 60_000 });
+            yield* test.crashNext("beforeDelivery");
+            yield* test.advance("1 minute");
+            expect(yield* test.receiptsFor(receiver.ref, "Receive")).toBe(0);
+            expect(taken.get("before-delivery")).toBe(undefined);
+            expect(yield* test.inspect(sender.ref)).toMatchObject({ outbox: 1 });
+            yield* test.advance(CLAIM_LEASE);
+            expect(yield* receiver.Bodies().pipe(Effect.orDie)).toEqual(["before-delivery"]);
+            expect(taken.get("before-delivery")).toBe(1);
+            expect(yield* test.receiptsFor(receiver.ref, "Receive")).toBe(1);
+            expect(yield* test.inspect(sender.ref)).toMatchObject({ outbox: 0 });
+        })),
+    },
+    {
+        name: "cross-shard outbox: a crash after the receiver commits redelivers to a receipt replay, with one handler run",
+        run: ({ expect, environment }) => environment.run(Effect.gen(function* () {
+            const test = yield* ActorTest;
+            const { sender, receiver } = yield* across("after-commit");
+            yield* sender.Post({ to: receiver.ref.id, body: "after-commit", afterMs: 60_000 });
+            yield* test.crashNext("afterCommit");
+            yield* test.advance("1 minute");
+            yield* test.advance(CLAIM_LEASE);
+            expect(yield* receiver.Bodies().pipe(Effect.orDie)).toEqual(["after-commit"]);
+            expect(taken.get("after-commit")).toBe(1);
+            expect(yield* test.receiptsFor(receiver.ref, "Receive")).toBe(1);
+            expect(yield* test.inspect(sender.ref)).toMatchObject({ outbox: 0 });
+        })),
+    },
+    {
+        name: "cross-shard outbox: a crash between the receiver's commit and the row's deletion keeps the row until the redelivery replays the receipt",
+        run: ({ expect, environment }) => environment.run(Effect.gen(function* () {
+            const test = yield* ActorTest;
+            const { sender, receiver } = yield* across("before-delete");
+            yield* sender.Post({ to: receiver.ref.id, body: "before-delete", afterMs: 60_000 });
+            yield* test.crashNext("beforeOutboxDelete");
+            const pause = yield* test.pauseNext("beforeOutboxDelete");
+            yield* test.advance("1 minute");
+            expect(yield* test.inspect(sender.ref)).toMatchObject({ outbox: 1 });
+            const draining = yield* test.advance(CLAIM_LEASE).pipe(Effect.forkChild);
+            yield* pause.reached;
+            expect(taken.get("before-delete")).toBe(1);
+            expect(yield* test.receiptsFor(receiver.ref, "Receive")).toBe(1);
+            expect(yield* test.inspect(sender.ref)).toMatchObject({ outbox: 1 });
+            yield* pause.release;
+            yield* Fiber.join(draining);
+            expect(yield* receiver.Bodies().pipe(Effect.orDie)).toEqual(["before-delete"]);
+            expect(taken.get("before-delete")).toBe(1);
+            expect(yield* test.receiptsFor(receiver.ref, "Receive")).toBe(1);
+            expect(yield* test.inspect(sender.ref)).toMatchObject({ outbox: 0 });
+        })),
+    },
+];
+/** Cross-shard mailbox actors. */
+export const crossShardSuite = {
+    layer: () => crossShardLayer,
+};

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

@@ -0,0 +1,36 @@
+import { Effect, Layer, Schema } from "effect";
+import type { InTurn } from "../../handles/intents.ts";
+import { ActorTest } from "../actor-test.ts";
+import type { ConformanceCase, ConformanceSuite } from "../conformance.ts";
+export interface OutboxFixture {
+    /** Receiver handler runs, including runs whose turn later rolled back. */
+    receives: number;
+    /** Makes the next `Receive` die once, as a receiver defect would. */
+    failNext: boolean;
+    escaped: Effect.Effect<void, never, InTurn>;
+}
+export declare const outboxFixture: () => OutboxFixture;
+export declare const outboxLayer: (fixture: OutboxFixture) => Layer.Layer<never, never, import("../index.ts").InternalActors>;
+export declare const receivedBodies: (to: string) => Effect.Effect<string[], never, ActorTest | import("../../index.ts").Actors>;
+interface PlanNode {
+    readonly "Node Type": string;
+    readonly "Relation Name"?: string | undefined;
+    readonly "Index Name"?: string | undefined;
+    readonly "Actual Rows": number;
+    readonly "Shared Hit Blocks": number;
+    readonly "Shared Read Blocks": number;
+    readonly "Rows Removed by Filter"?: number | undefined;
+    readonly Plans?: ReadonlyArray<PlanNode> | undefined;
+}
+export declare const PlanNode: Schema.Codec<PlanNode>;
+export declare const ExplainOutput: Schema.Tuple<readonly [Schema.Struct<{
+    readonly Plan: Schema.Codec<PlanNode, PlanNode, never, never>;
+}>]>;
+export declare const planNodes: (node: PlanNode) => ReadonlyArray<PlanNode>;
+/** The default claim lease for these actors: 30 s `commandTimeout` + 2 s `lockWait` + 5 s. */
+export declare const CLAIM_LEASE = "37 seconds";
+/** Outbox cases: committed intents deliver as System commands under the intent id, and staged intents from failed or rolled-back turns never deliver. */
+export declare const outboxConformance: ReadonlyArray<ConformanceCase<OutboxFixture>>;
+/** The outbox actors. */
+export declare const outboxSuite: ConformanceSuite<OutboxFixture>;
+export {};