@rikalabs/akter 0.1.0-alpha.0

package/dist/testing/conformance/workflows/waits.js

@@ -0,0 +1,284 @@
+import { DateTime, Deferred, Effect, Fiber } from "effect";
+import { SqlClient } from "effect/sql";
+import { ActorTest } from "../../actor-test.js";
+import { Keeper, Shipper, Watch } from "./actors.js";
+import { eventually, reset, suspendedRow } from "./harness.js";
+/** Owner-event waits, clocks, and retention pins of workflows. */
+export const workflowWaitConformance = [
+    {
+        name: "workflows: resolves an event committed between start and registration",
+        run: ({ expect, environment, fixture }) => environment.run(Effect.gen(function* () {
+            yield* reset(fixture);
+            const gate = yield* Deferred.make();
+            fixture.gates.set("w2-between", gate);
+            const shipper = yield* Shipper.get("w2-between");
+            const run = yield* shipper.Watch({ mode: "gated", orderId: "w2-between" });
+            yield* eventually(Effect.sync(() => fixture.runs.get("hold:w2-between") === 1), "the activity before the wait");
+            yield* shipper.Pay({ orderId: "w2-between", amount: 4 });
+            yield* Deferred.succeed(gate, undefined);
+            expect(yield* run.result).toBe("paid-4");
+        }).pipe(Effect.ensuring(Effect.sync(() => fixture.gates.delete("w2-between"))))),
+    },
+    {
+        name: "workflows: resolves an event committed while the run is suspending",
+        run: ({ expect, environment, fixture }) => environment.run(Effect.gen(function* () {
+            yield* reset(fixture);
+            const test = yield* ActorTest;
+            const shipper = yield* Shipper.get("w2-suspending");
+            const pause = yield* test.pauseNext("beforeWorkflowSuspend");
+            const run = yield* shipper.Watch({ mode: "plain", orderId: "w2-suspending" });
+            yield* pause.reached;
+            yield* shipper.Pay({ orderId: "w2-suspending", amount: 5 });
+            yield* pause.release;
+            expect(yield* run.result).toBe("paid-5");
+        })),
+    },
+    {
+        name: "workflows: resolves an event delivered while the run is live",
+        run: ({ expect, environment, fixture }) => environment.run(Effect.gen(function* () {
+            yield* reset(fixture);
+            const sql = yield* SqlClient.SqlClient;
+            const gate = yield* Deferred.make();
+            fixture.gates.set("w2-live", gate);
+            const shipper = yield* Shipper.get("w2-live");
+            const run = yield* shipper.Watch({ mode: "race", orderId: "w2-live" });
+            yield* eventually(Effect.gen(function* () {
+                const rows = yield* sql `SELECT step FROM actor_workflow_step
+                WHERE execution_id = ${run.executionId} AND step = 'first'`;
+                return rows.length === 1 && fixture.runs.get("slow:w2-live") === 1;
+            }).pipe(Effect.orDie), "the wait to park beside the running activity");
+            yield* shipper.Pay({ orderId: "w2-live", amount: 6 });
+            const result = yield* run.result.pipe(Effect.timeoutOrElse({
+                duration: "15 seconds",
+                orElse: () => Effect.die(new Error("The live run was not preempted for its event")),
+            }));
+            expect(result).toBe("paid-6");
+        }).pipe(Effect.ensuring(Effect.gen(function* () {
+            const gate = fixture.gates.get("w2-live");
+            if (gate !== undefined)
+                yield* Deferred.succeed(gate, undefined);
+            fixture.gates.delete("w2-live");
+        })))),
+    },
+    {
+        name: "workflows: a parked wait resolves by the event its sibling activity emits as that sibling finishes",
+        timeoutMs: 120_000,
+        run: ({ expect, environment, fixture }) => environment.run(Effect.gen(function* () {
+            yield* reset(fixture);
+            const sql = yield* SqlClient.SqlClient;
+            const gate = yield* Deferred.make();
+            fixture.gates.set("sibling-gated", gate);
+            const ids = ["sibling-gated", "sibling-0", "sibling-1", "sibling-2", "sibling-3"];
+            const runs = yield* Effect.forEach(ids, (id) => Shipper.get(id).pipe(Effect.flatMap((shipper) => shipper.Watch({ mode: "sibling", orderId: id }))));
+            yield* eventually(Effect.gen(function* () {
+                const rows = yield* sql `SELECT step FROM actor_workflow_step
+                WHERE execution_id = ${runs[0].executionId} AND step = 'first' AND exit IS NULL`;
+                return rows.length === 1 && fixture.runs.get("emit:sibling-gated") === 1;
+            }).pipe(Effect.orDie), "the wait to park beside the gated sibling");
+            yield* Deferred.succeed(gate, undefined);
+            const results = yield* Effect.forEach(runs, (run) => run.result, {
+                concurrency: "unbounded",
+            }).pipe(Effect.timeoutOrElse({
+                duration: "60 seconds",
+                orElse: () => Effect.die(new Error("A run never resumed for its sibling's event")),
+            }));
+            expect(results).toEqual(ids.map(() => "paid-8|emitted"));
+            for (const [index, id] of ids.entries()) {
+                const [events] = yield* sql `SELECT count(*)::int AS count
+              FROM actor_events WHERE actor_type = 'Shipper' AND actor_id = ${id} AND event = 'Paid'`;
+                const [leftover] = yield* sql `SELECT
+              (SELECT count(*)::int FROM actor_workflow_step
+                WHERE execution_id = ${runs[index].executionId}) AS steps,
+              (SELECT count(*)::int FROM actor_outbox
+                WHERE timer_key = ${`wf:${runs[index].executionId}`}) AS timers`;
+                expect({ id, events: events.count, ...leftover }).toEqual({
+                    id,
+                    events: 1,
+                    steps: 0,
+                    timers: 0,
+                });
+            }
+        }).pipe(Effect.ensuring(Effect.sync(() => {
+            fixture.gates.delete("sibling-gated");
+        })))),
+    },
+    {
+        name: "workflows: a workflow command that kicks a running execution commits and answers while the owner call its activity makes waits behind it",
+        requiresIndependentConnections: true,
+        timeoutMs: 120_000,
+        run: ({ expect, environment, fixture }) => environment.run(Effect.gen(function* () {
+            yield* reset(fixture);
+            const sql = yield* SqlClient.SqlClient;
+            const test = yield* ActorTest;
+            const id = "kick-behind";
+            const gate = yield* Deferred.make();
+            fixture.gates.set(id, gate);
+            const shipper = yield* Shipper.get(id);
+            const run = yield* shipper.Watch({ mode: "sibling", orderId: id });
+            yield* eventually(Effect.sync(() => fixture.runs.get(`emit:${id}`) === 1), "the sibling activity to start");
+            const committing = yield* test.pauseNext("beforeCommit");
+            const reattach = yield* shipper
+                .Watch({ mode: "sibling", orderId: id })
+                .pipe(Effect.forkChild({ startImmediately: true }));
+            yield* committing.reached;
+            const arriving = yield* test.pauseNext("queued");
+            yield* Deferred.succeed(gate, undefined);
+            yield* arriving.reached;
+            yield* arriving.release;
+            yield* Effect.sleep("500 millis");
+            yield* committing.release;
+            const reattached = yield* Fiber.join(reattach).pipe(Effect.timeoutOrElse({
+                duration: "10 seconds",
+                orElse: () => Effect.die(new Error("The kicking turn never answered behind the owner call")),
+            }));
+            expect(reattached.executionId).toBe(run.executionId);
+            expect(yield* run.result).toBe("paid-8|emitted");
+            expect(fixture.runs.get(`emit:${id}`)).toBe(1);
+            expect(yield* test.receiptsFor(shipper.ref, "Pay")).toBe(1);
+            const [leftover] = yield* sql `SELECT
+            (SELECT count(*)::int FROM actor_workflow_step
+              WHERE execution_id = ${run.executionId}) AS steps,
+            (SELECT count(*)::int FROM actor_outbox
+              WHERE timer_key = ${`wf:${run.executionId}`}) AS timers`;
+            expect(leftover).toEqual({ steps: 0, timers: 0 });
+        }).pipe(Effect.ensuring(Effect.sync(() => {
+            fixture.gates.delete("kick-behind");
+        })))),
+    },
+    {
+        name: "workflows: resolves two sequential waits with two events",
+        run: ({ expect, environment, fixture }) => environment.run(Effect.gen(function* () {
+            yield* reset(fixture);
+            const shipper = yield* Shipper.get("w2-two");
+            const run = yield* shipper.Watch({ mode: "two", orderId: "w2-two" });
+            yield* shipper.Pay({ orderId: "w2-two", amount: 1 });
+            yield* shipper.Pay({ orderId: "w2-two", amount: 2 });
+            expect(yield* run.result).toBe("paid-1|paid-2");
+        })),
+    },
+    {
+        name: "workflows: resolves concurrent waits for one tag",
+        run: ({ expect, environment, fixture }) => environment.run(Effect.gen(function* () {
+            yield* reset(fixture);
+            const shipper = yield* Shipper.get("w2-concurrent");
+            const runs = yield* Effect.forEach(["c1", "c2", "c3"], (orderId) => shipper.Watch({ mode: "any", orderId }));
+            yield* Effect.forEach(runs, (run) => suspendedRow(run.executionId));
+            yield* shipper.Pay({ orderId: "anyone", amount: 9 });
+            expect(yield* Effect.forEach(runs, (run) => run.result, { concurrency: 3 })).toEqual([
+                "paid-9",
+                "paid-9",
+                "paid-9",
+            ]);
+        })),
+    },
+    {
+        name: "workflows: settles a wait exactly once when its event and timeout race",
+        timeoutMs: 120_000,
+        run: ({ expect, environment, fixture }) => environment.run(Effect.gen(function* () {
+            yield* reset(fixture);
+            const sql = yield* SqlClient.SqlClient;
+            const test = yield* ActorTest;
+            for (let round = 0; round < 6; round++) {
+                const orderId = `w2-timeout-${round}`;
+                const shipper = yield* Shipper.get(orderId);
+                const run = yield* shipper.Watch({ mode: "plain", orderId });
+                yield* suspendedRow(run.executionId);
+                const [wait] = yield* sql `SELECT due_at_ms::text AS due
+              FROM actor_workflow_step WHERE execution_id = ${run.executionId} AND step = 'first'`;
+                if (round === 0) {
+                    yield* test.advance("59 seconds");
+                    yield* shipper.Pay({ orderId, amount: round });
+                    yield* test.advance("2 seconds");
+                }
+                else
+                    yield* Effect.all([shipper.Pay({ orderId, amount: round }), test.advance("61 seconds")], {
+                        concurrency: 2,
+                    });
+                const result = yield* run.result;
+                const [event] = yield* sql `SELECT emitted_at_ms::text AS at
+              FROM actor_events WHERE actor_type = 'Shipper' AND actor_id = ${orderId}
+                AND tenant_id = ${shipper.ref.tenant}`;
+                if (Number(event.at) <= Number(wait.due))
+                    expect(result).toBe(`paid-${round}`);
+                else
+                    expect([`paid-${round}`, "unpaid"]).toContain(result);
+                expect(yield* (yield* Shipper.run(Watch, run.executionId)).result).toBe(result);
+            }
+        })),
+    },
+    {
+        name: "workflows: resumes two concurrent clocks at their own due times",
+        run: ({ expect, environment, fixture }) => environment.run(Effect.gen(function* () {
+            yield* reset(fixture);
+            const test = yield* ActorTest;
+            const shipper = yield* Shipper.get("clocks");
+            const run = yield* shipper.Watch({ mode: "clocks", orderId: "clocks" });
+            yield* suspendedRow(run.executionId);
+            const marks = () => ["mark-a", "mark-b"].map((label) => fixture.runs.get(`${label}:clocks`) ?? 0);
+            expect(marks()).toEqual([0, 0]);
+            yield* test.advance("6 seconds");
+            yield* eventually(Effect.sync(() => marks()[0] === 1), "the 5-second clock to resume");
+            yield* suspendedRow(run.executionId);
+            expect(marks()).toEqual([1, 0]);
+            yield* test.advance("5 seconds");
+            expect(yield* run.result).toBe("clocks");
+            expect(marks()).toEqual([1, 1]);
+        })),
+    },
+    {
+        name: "workflows: keeps a clock's due time across replays",
+        run: ({ expect, environment, fixture }) => environment.run(Effect.gen(function* () {
+            yield* reset(fixture);
+            const sql = yield* SqlClient.SqlClient;
+            const test = yield* ActorTest;
+            const shipper = yield* Shipper.get("long");
+            const run = yield* shipper.Watch({ mode: "long", orderId: "long" });
+            yield* suspendedRow(run.executionId);
+            const due = () => sql `SELECT due_at_ms::text AS due FROM actor_workflow_step
+              WHERE execution_id = ${run.executionId} AND step = 'long'`.pipe(Effect.map((rows) => rows[0]?.due));
+            const recorded = yield* due();
+            yield* test.advance("5 seconds");
+            yield* test.invalidate(shipper.ref);
+            const now = DateTime.toEpochMillis(yield* test.now);
+            yield* sql `UPDATE actor_outbox SET due_at_ms = ${now}
+            WHERE timer_key = ${`wf:${run.executionId}`}`;
+            yield* test.advance("1 second");
+            yield* eventually(test
+                .receiptsFor(shipper.ref, "$workflow/resume")
+                .pipe(Effect.map((count) => count > 0)), "the replay");
+            yield* suspendedRow(run.executionId);
+            expect(yield* due()).toBe(recorded);
+            yield* test.advance("2 seconds");
+            expect(fixture.runs.get("slept:long") ?? 0).toBe(0);
+            yield* test.advance("3 seconds");
+            expect(yield* run.result).toBe("slept");
+            expect(fixture.runs.get("slept:long")).toBe(1);
+        })),
+    },
+    {
+        name: "workflows: keeps events above an open cursor or pending wait from pruning",
+        run: ({ expect, environment }) => environment.run(Effect.gen(function* () {
+            const sql = yield* SqlClient.SqlClient;
+            const test = yield* ActorTest;
+            const keeper = yield* Keeper.get("pinned");
+            const sequences = () => sql `SELECT sequence::text AS sequence FROM actor_events
+              WHERE tenant_id = ${keeper.ref.tenant} AND actor_type = 'Keeper' AND actor_id = 'pinned'
+              ORDER BY sequence`.pipe(Effect.map((rows) => rows.map((row) => Number(row.sequence))));
+            for (const amount of [1, 2, 3])
+                yield* keeper.Emit({ orderId: "noise", amount });
+            const run = yield* keeper.Held({});
+            yield* suspendedRow(run.executionId);
+            for (const amount of [4, 5])
+                yield* keeper.Emit({ orderId: "noise", amount });
+            yield* Effect.sleep("200 millis");
+            yield* test.advance("2 hours");
+            yield* test.cleanup;
+            expect(yield* sequences()).toEqual([4, 5]);
+            yield* keeper.Emit({ orderId: "k", amount: 6 });
+            expect(yield* run.result).toBe("paid-6");
+            yield* test.advance("2 hours");
+            yield* test.cleanup;
+            expect(yield* sequences()).toEqual([]);
+        })),
+    },
+];

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

@@ -0,0 +1,4 @@
+import type { ConformanceCase } from "../conformance.ts";
+import type { WorkflowsFixture } from "./workflows/actors.ts";
+/** Workflow cases: stable execution ids, once-recorded activities, interrupts, and recovery. */
+export declare const workflowsConformance: ReadonlyArray<ConformanceCase<WorkflowsFixture>>;

package/dist/testing/conformance/workflows.js

@@ -0,0 +1,19 @@
+import { workflowAccessConformance } from "./workflows/access.js";
+import { workflowBasicConformance } from "./workflows/basics.js";
+import { engineConformance } from "./workflows/engine.js";
+import { workflowGuardConformance } from "./workflows/guards.js";
+import { workflowRecoveryConformance } from "./workflows/recovery.js";
+import { workflowStartConformance } from "./workflows/starts.js";
+import { workflowSuspensionConformance } from "./workflows/suspension.js";
+import { workflowWaitConformance } from "./workflows/waits.js";
+/** Workflow cases: stable execution ids, once-recorded activities, interrupts, and recovery. */
+export const workflowsConformance = [
+    ...engineConformance,
+    ...workflowBasicConformance,
+    ...workflowSuspensionConformance,
+    ...workflowRecoveryConformance,
+    ...workflowStartConformance,
+    ...workflowAccessConformance,
+    ...workflowGuardConformance,
+    ...workflowWaitConformance,
+];

package/dist/testing/conformance.d.ts

@@ -0,0 +1,330 @@
+import { Effect, Layer, Logger, ManagedRuntime, type Crypto, type Scope } from "effect";
+import type { Redacted } from "effect";
+import type { HttpServer } from "effect/http";
+import { type SqlClient, Statement } from "effect/sql";
+import type { Actors } from "../index.ts";
+import type { InternalActors } from "../runtime/actors.ts";
+import type { RuntimeControl } from "../runtime/drain.ts";
+import type { OperatorRuntime } from "../runtime/operators/repair.ts";
+import type { Request } from "../runtime/request.ts";
+import { type ContentPoint, type TurnPoint } from "../runtime/turn/hooks.ts";
+import type { ContentStore } from "../handles/content.ts";
+import type { Options } from "../runtime/layer.ts";
+import { ActorTest } from "./actor-test.ts";
+import type { ConformanceEdge } from "./conformance/assertions.ts";
+/**
+ * Assertions injected by the test framework running the suite, e.g. Vitest's
+ * `expect`. The framework itself is never imported here.
+ */
+export interface ConformanceMatchers {
+    readonly not: ConformanceMatchers;
+    readonly toBe: <T>(expected: T) => void;
+    readonly toEqual: <T>(expected: T) => void;
+    readonly toContain: <T>(expected: T) => void;
+    readonly toMatchObject: <T extends object | ReadonlyArray<unknown>>(expected: T) => void;
+    readonly toBeInstanceOf: <T>(expected: T) => void;
+}
+export type ConformanceExpect = <T>(actual: T) => ConformanceMatchers;
+/**
+ * The subset of `describe`/`it`/lifecycle a registrar must supply. Vitest's
+ * exported functions satisfy this shape.
+ */
+export interface ConformanceRegistrar {
+    readonly describe: (name: string, body: () => void) => void;
+    /**
+     * Registers one case. A runner that aborts `signal` when the case times
+     * out or is cancelled, as Vitest does, interrupts the case's effects so
+     * their finalizers run before the next case starts.
+     */
+    readonly it: (name: string, body: (context: {
+        readonly signal?: AbortSignal | undefined;
+    }) => Promise<void>, timeout?: number) => void;
+    readonly beforeAll: (body: () => Promise<void> | void, timeout?: number) => void;
+    readonly afterAll: (body: () => Promise<void> | void) => void;
+    readonly expect: ConformanceExpect;
+    /** Registers an inapplicable case by name so it is reported, never silently dropped. */
+    readonly skip: (name: string) => void;
+}
+export type ConformanceDatabase = NonNullable<NonNullable<Parameters<typeof ActorTest.layer>[0]>["database"]>;
+export interface ConformanceConnection {
+    readonly query: (statement: string, parameters?: ReadonlyArray<unknown>) => Effect.Effect<ReadonlyArray<unknown>>;
+}
+/** Services every `environment.run` effect may require; Scope is provided. */
+export type ConformanceServices = Actors | InternalActors | RuntimeControl | ActorTest | SqlClient.SqlClient | Crypto.Crypto | ContentStore | OperatorRuntime;
+export type ConformanceRuntime = ManagedRuntime.ManagedRuntime<ConformanceServices, never>;
+export interface ConformanceEnvironment {
+    /** Runs an effect against the current runtime. */
+    readonly run: <A, E>(effect: Effect.Effect<A, E, ConformanceServices | Scope.Scope>) => Promise<A>;
+    /** Builds a new runtime without installing it; warm it explicitly. */
+    readonly build: (options?: {
+        readonly retryWindowMs?: number;
+        /** Deployment admission settings for cases that deliberately queue more than the defaults allow. */
+        readonly admission?: Options["admission"];
+        readonly database?: ConformanceDatabase;
+        /** Queries read this streaming replica of `database` once it has caught up. */
+        readonly replica?: Redacted.Redacted<string> | undefined;
+        readonly content?: Options["content"];
+        /**
+         * Sees every statement the runtime compiles, from any fiber. It replaces
+         * the current statement transformer of every fiber the runtime starts, so
+         * a case that installs its own on a caller cannot share the runtime.
+         */
+        readonly observe?: (statement: Statement.Statement<unknown>) => void;
+    }) => ConformanceRuntime;
+    /** Stops the current runtime; the retained database survives. */
+    readonly stop: Effect.Effect<void>;
+    /** Restarts the current runtime against the retained database. */
+    readonly restart: Effect.Effect<void>;
+    /**
+     * A second database untouched by the current runtime, for isolation cases.
+     * Only a case that declares `requiresFreshDatabase` may open one.
+     */
+    readonly freshDatabase: Effect.Effect<ConformanceDatabase>;
+    /**
+     * Copies the retained database whole, as a backup of a stopped deployment
+     * would, into a new database no runtime has opened. Requires `stop` first,
+     * and a case that declares `requiresFreshDatabase`.
+     */
+    readonly snapshot: Effect.Effect<ConformanceDatabase>;
+    /**
+     * Opens an independent SQL connection to the same database. Only present
+     * when the backend advertises `independentConnections`.
+     */
+    readonly connect?: Effect.Effect<ConformanceConnection, never, Scope.Scope>;
+    /** The retained database on a streaming replica; only present when the backend has one. */
+    readonly replica?: ConformanceReplica | undefined;
+    /** A fresh listening HTTP server that supports WebSocket upgrades; each build listens anew. */
+    readonly httpServer: Layer.Layer<HttpServer.HttpServer>;
+    /** The hosted edge under test, when the backend supplies one. */
+    readonly edge?: ConformanceEdge;
+}
+/** A physical streaming replica of the backend's Postgres primary. */
+export interface ConformanceReplica {
+    /** The retained database's connection string on the replica. */
+    readonly database: Redacted.Redacted<string>;
+    /** A superuser connection to the replica, e.g. to pause and resume WAL replay. */
+    readonly connect: Effect.Effect<ConformanceConnection, never, Scope.Scope>;
+}
+export interface ConformanceBackend {
+    /** True when the backend can open concurrent SQL connections (real Postgres). */
+    readonly independentConnections: boolean;
+    /** True when `open` returns a streaming replica of the primary. */
+    readonly hasReplica?: boolean;
+    /**
+     * True when the database is a Neki router. Turn sessions then run in
+     * single transaction mode and single fanout, and the cases flagged
+     * `requiresNeki` run; every other backend reports them through
+     * `registrar.skip`.
+     */
+    readonly neki?: boolean;
+    /** True when the server runs `wal_level=logical`, which fleet views need. */
+    readonly logicalDecoding?: boolean;
+    /**
+     * True when `open` can create further databases and snapshots; cases that
+     * declare `requiresFreshDatabase` are reported through `registrar.skip`
+     * otherwise.
+     */
+    readonly freshDatabases: boolean;
+    /** Extra services merged into every test runtime, e.g. BunCrypto.layer. */
+    readonly services: Layer.Layer<Crypto.Crypto, never, never>;
+    /**
+     * A listening HTTP server on an ephemeral loopback port that supports
+     * WebSocket upgrades, e.g. `BunHttpServer.layerServer({ port: 0 })`; the
+     * served-transport cases build one per case.
+     */
+    readonly httpServer: Layer.Layer<HttpServer.HttpServer>;
+    /**
+     * A hosted edge to run the edge half of the assertion cases against; a
+     * backend without one reports those cases through `registrar.skip`.
+     */
+    readonly edge?: ConformanceEdge;
+    readonly open: () => Promise<{
+        readonly database: ConformanceDatabase;
+        readonly freshDatabase: Effect.Effect<ConformanceDatabase>;
+        /** Copies a database that no runtime has open into a new one. */
+        readonly copy: (database: ConformanceDatabase) => Effect.Effect<ConformanceDatabase>;
+        readonly connect?: Effect.Effect<ConformanceConnection, never, Scope.Scope>;
+        readonly replica?: ConformanceReplica | undefined;
+        readonly close: Effect.Effect<void>;
+    }>;
+}
+/**
+ * The test authorization every conformance runtime applies. The harness
+ * resets it before each case, so a case that times out holding it closed
+ * does not deny the next one.
+ */
+export interface ConformanceAccess {
+    allowed: boolean;
+    /** Commands the test authorization refuses while `allowed` holds. */
+    readonly denied: Set<string>;
+    /** Principals that lost access: refused as callers and as `onBehalfOf`, as an application would. */
+    readonly revoked: Set<string>;
+}
+/**
+ * The actors and mutable fixture a group of cases owns. A registration builds
+ * each selected suite, and every suite it `uses`, once: its fixture when the
+ * registration starts and its layer into every runtime the registration
+ * builds. Suites without a fixture receive `undefined`.
+ */
+export interface ConformanceSuite<F = undefined> {
+    readonly fixture?: () => F;
+    /** Declared as a method so its parameter stays bivariant and any suite fits `ConformanceSuite<unknown>`. */
+    layer?(fixture: F): Layer.Layer<never, never, ConformanceSuiteServices>;
+    /** Other suites whose actors this suite's cases call. */
+    readonly uses?: ReadonlyArray<ConformanceSuite<unknown>>;
+    /** Runs at every turn fault point, as the process-level `TurnHooks`. */
+    turn?(fixture: F): (point: TurnPoint, request: Request) => Effect.Effect<void>;
+    /** Runs at every content-store fault point, as `ContentHooks`. */
+    content?(fixture: F): (point: ContentPoint) => Effect.Effect<void>;
+    /** Receives every log line the runtimes write; conformance runtimes print none. */
+    logger?(fixture: F): Logger.Logger<unknown, void>;
+}
+/** Services a suite's layer may require: what `ActorTest.layer` and the backend provide. */
+export type ConformanceSuiteServices = Layer.Success<ReturnType<typeof ActorTest.layer>> | Crypto.Crypto;
+export interface ConformanceContext<F = undefined> {
+    readonly expect: ConformanceExpect;
+    readonly environment: ConformanceEnvironment;
+    /** The fixture of the suite that owns the case. */
+    readonly fixture: F;
+    readonly access: ConformanceAccess;
+    /** The fixture of a suite the case's own suite `uses`. */
+    readonly fixtureOf: <G>(suite: ConformanceSuite<G>) => G;
+}
+export interface ConformanceCase<F = undefined> {
+    readonly name: string;
+    /**
+     * Requires `backend.independentConnections`; backends without it register
+     * the case through `registrar.skip` instead of running it.
+     */
+    readonly requiresIndependentConnections?: boolean;
+    /** Requires a streaming replica; backends without one skip the case. */
+    readonly requiresReplica?: boolean;
+    /** Requires `backend.edge`; backends without one register the case through `registrar.skip`. */
+    readonly requiresEdge?: boolean;
+    /** Requires `backend.neki`; every other backend registers the case through `registrar.skip`. */
+    readonly requiresNeki?: boolean;
+    /** Requires a server with `wal_level=logical`; backends without one skip the case. */
+    readonly requiresLogicalDecoding?: boolean;
+    /**
+     * Opens `environment.freshDatabase` or `environment.snapshot`. Only a case
+     * that declares it may, and backends without `freshDatabases` skip it.
+     */
+    readonly requiresFreshDatabase?: boolean;
+    /** Declared as a method so its parameter stays bivariant and any case fits `ConformanceCase<unknown>`. */
+    run(context: ConformanceContext<F>): Promise<void>;
+    readonly timeoutMs?: number;
+}
+/** A named group's cases and the suite that owns their actors and fixture. */
+export interface ConformanceGroupCases<F = unknown> {
+    readonly suite: ConformanceSuite<F>;
+    readonly cases: ReadonlyArray<ConformanceCase<F>>;
+}
+/**
+ * Every conformance case, grouped by the file that owns it, with the suite
+ * that owns its actors. `describeConformance` runs a subset through `groups`,
+ * so a group can run in its own Vitest file and worker; `conformance` is
+ * their union and the order within a group is kept.
+ */
+export declare const conformanceGroups: {
+    foundation: ConformanceGroupCases<unknown>;
+    access: ConformanceGroupCases<unknown>;
+    admission: ConformanceGroupCases<unknown>;
+    http: ConformanceGroupCases<unknown>;
+    protocols: ConformanceGroupCases<unknown>;
+    assertions: ConformanceGroupCases<unknown>;
+    edge: ConformanceGroupCases<unknown>;
+    coldServeEdge: ConformanceGroupCases<unknown>;
+    client: ConformanceGroupCases<unknown>;
+    offline: ConformanceGroupCases<unknown>;
+    capacity: ConformanceGroupCases<unknown>;
+    heap: ConformanceGroupCases<unknown>;
+    events: ConformanceGroupCases<unknown>;
+    reducer: ConformanceGroupCases<unknown>;
+    outbox: ConformanceGroupCases<unknown>;
+    tables: ConformanceGroupCases<unknown>;
+    effects: ConformanceGroupCases<unknown>;
+    progress: ConformanceGroupCases<unknown>;
+    multiRunner: ConformanceGroupCases<unknown>;
+    simulation: ConformanceGroupCases<unknown>;
+    drain: ConformanceGroupCases<unknown>;
+    pipeline: ConformanceGroupCases<unknown>;
+    batches: ConformanceGroupCases<unknown>;
+    groups: ConformanceGroupCases<unknown>;
+    relay: ConformanceGroupCases<unknown>;
+    relayCluster: ConformanceGroupCases<unknown>;
+    effectControl: ConformanceGroupCases<unknown>;
+    effectControlCluster: ConformanceGroupCases<unknown>;
+    singleton: ConformanceGroupCases<unknown>;
+    cron: ConformanceGroupCases<unknown>;
+    cronCluster: ConformanceGroupCases<unknown>;
+    blobs: ConformanceGroupCases<unknown>;
+    inspectionViews: ConformanceGroupCases<unknown>;
+    inspector: ConformanceGroupCases<unknown>;
+    rls: ConformanceGroupCases<unknown>;
+    retention: ConformanceGroupCases<unknown>;
+    restore: ConformanceGroupCases<unknown>;
+    workflows: ConformanceGroupCases<unknown>;
+    connections: ConformanceGroupCases<unknown>;
+    streams: ConformanceGroupCases<unknown>;
+    progressDelivery: ConformanceGroupCases<unknown>;
+    transports: ConformanceGroupCases<unknown>;
+    workflowVersions: ConformanceGroupCases<unknown>;
+    payloadMigrations: ConformanceGroupCases<unknown>;
+    subscriptions: ConformanceGroupCases<unknown>;
+    subscriptionsRetention: ConformanceGroupCases<unknown>;
+    subscriptionsCluster: ConformanceGroupCases<unknown>;
+    content: ConformanceGroupCases<unknown>;
+    counter: ConformanceGroupCases<unknown>;
+    properties: ConformanceGroupCases<unknown>;
+    mint: ConformanceGroupCases<unknown>;
+    readYourWrites: ConformanceGroupCases<unknown>;
+    observability: ConformanceGroupCases<unknown>;
+    operator: ConformanceGroupCases<unknown>;
+    export: ConformanceGroupCases<unknown>;
+    coldServe: ConformanceGroupCases<unknown>;
+    placement: ConformanceGroupCases<unknown>;
+    watch: ConformanceGroupCases<unknown>;
+    adoption: ConformanceGroupCases<unknown>;
+    singleShard: ConformanceGroupCases<unknown>;
+    crossShardOutbox: ConformanceGroupCases<unknown>;
+    fleet: ConformanceGroupCases<unknown>;
+};
+export type ConformanceGroup = keyof typeof conformanceGroups;
+/**
+ * The shared durable-turn conformance cases. Cases flagged
+ * `requiresIndependentConnections` need real Postgres: a second database
+ * connection to read committed state while a turn holds its transaction open
+ * or to take a competing row lock, or a database outside the JavaScript heap
+ * they measure. They never run on single-connection backends such as PGlite.
+ */
+export declare const conformance: ReadonlyArray<ConformanceCase<unknown>>;
+/** A backend capability a case can require, as `ConformanceCase` flags name it. */
+export type ConformanceRequirement = "independentConnections" | "replica" | "edge" | "neki" | "logicalDecoding" | "freshDatabase";
+/** The capabilities `conformanceCase` requires, in a fixed order. */
+export declare const requirementsOf: (conformanceCase: ConformanceCase<unknown>) => ReadonlyArray<ConformanceRequirement>;
+/** The capabilities `backend` provides. */
+export declare const capabilitiesOf: (backend: Pick<ConformanceBackend, "independentConnections" | "hasReplica" | "edge" | "neki" | "logicalDecoding" | "freshDatabases">) => ReadonlySet<ConformanceRequirement>;
+/**
+ * Registers the named groups' cases, or every group's, against `backend`.
+ * Only the selected groups' suites, and the suites they use, build their
+ * actors and fixtures. The same case names run on every backend; a case
+ * whose requirements the backend lacks is reported through `registrar.skip`.
+ *
+ * Each case runs under the registrar's abort signal: a timed-out or
+ * cancelled case is interrupted, its finalizers run, and the next case waits
+ * for them, then restarts a runtime the case left stopped and starts with
+ * open test authorization.
+ */
+export declare const describeConformance: (options: {
+    readonly name: string;
+    readonly backend: ConformanceBackend;
+    readonly registrar: ConformanceRegistrar;
+    readonly groups?: ReadonlyArray<ConformanceGroup>;
+}) => void;
+/** Registers `selected` groups; `describeConformance` passes registry groups, tests pass their own. */
+export declare const registerConformance: (options: {
+    readonly name: string;
+    readonly backend: ConformanceBackend;
+    readonly registrar: ConformanceRegistrar;
+    readonly selected: ReadonlyArray<ConformanceGroupCases>;
+}) => void;