@rikalabs/akter 0.1.0-alpha.0

package/dist/tables/owned.js

@@ -0,0 +1,233 @@
+import { is, sql } from "drizzle-orm";
+import { bigint, ForeignKeyBuilder, IndexBuilder, pgPolicy, PgTable, PrimaryKeyBuilder, primaryKey, text, unique, UniqueConstraintBuilder, } from "drizzle-orm/pg-core";
+/** Ownership column keys, which are also their SQL names. */
+export const OWNERSHIP = ["routing_key", "tenant_id", "actor_id"];
+const ownershipColumns = () => ({
+    routing_key: bigint("routing_key", { mode: "bigint" }).notNull(),
+    tenant_id: text("tenant_id").notNull(),
+    actor_id: text("actor_id").notNull(),
+});
+const NameKey = Symbol.for("drizzle:Name");
+const SchemaKey = Symbol.for("drizzle:Schema");
+const ColumnsKey = Symbol.for("drizzle:Columns");
+const ExtraColumnsKey = Symbol.for("drizzle:ExtraConfigColumns");
+const ExtraConfigKey = Symbol.for("drizzle:ExtraConfigBuilder");
+const IsAliasKey = Symbol.for("drizzle:IsAlias");
+const ForeignKeysKey = Symbol.for("drizzle:PgInlineForeignKeys");
+/** Ownership lives beside the table, keyed by the table object itself, so no other object can claim it by copying a property or symbol. */
+const owned = new WeakMap();
+const routingColumn = () => ({ routing_key: bigint("routing_key", { mode: "bigint" }) });
+/** The ownership of `table`, or undefined when it is not an owned table. */
+export const ownership = (table) => owned.get(table);
+const isOwned = (table) => ownership(table) !== undefined;
+const flatten = (config, self) => (config?.(self) ?? []).flat();
+const mappedKindOf = (columnType) => {
+    if (columnType === "PgText" || columnType === "PgVarchar")
+        return "text";
+    return columnType === "PgUUID" ? "uuid" : undefined;
+};
+const declaredKey = (columns, extraColumns, extraConfig) => {
+    const keyOf = new Map(Object.entries(columns).map(([key, column]) => [column.name, key]));
+    let composite;
+    for (const builder of flatten(extraConfig, extraColumns))
+        if (is(builder, PrimaryKeyBuilder))
+            composite = builder.columns.map((column) => keyOf.get(column.name) ?? column.name);
+    return (composite ?? Object.entries(columns).flatMap(([key, column]) => (column.primary ? [key] : [])));
+};
+const adopt = (source, options) => {
+    const internals = source;
+    const name = internals[NameKey];
+    const columns = internals[ColumnsKey];
+    const access = options.access ?? "write";
+    if (access !== "write" && access !== "read")
+        throw new Error(`access of ${name} is "write" or "read"`);
+    const find = (column, role) => {
+        const found = Object.entries(columns).find(([, candidate]) => candidate === column);
+        if (found === undefined)
+            throw new Error(`owner.${role} is not a column of ${name}`);
+        const kind = mappedKindOf(found[1].columnType);
+        if (kind === undefined)
+            throw new Error(`owner.${role} of ${name} is a ${found[1].columnType} column; only text, varchar, and uuid columns can be mapped`);
+        return { key: found[0], column: found[1], kind };
+    };
+    const tenant = find(options.owner.tenant, "tenant");
+    const actor = find(options.owner.actor, "actor");
+    if (tenant.key === actor.key)
+        throw new Error(`owner.tenant and owner.actor of ${name} name the same column`);
+    for (const [key, column] of Object.entries(columns))
+        if (key === "routing_key" || column.name === "routing_key")
+            throw new Error(`Column ${key} of ${name} is reserved for ownership`);
+    const extraColumns = internals[ExtraColumnsKey];
+    const extraConfig = internals[ExtraConfigKey];
+    const primaryKey = declaredKey(columns, extraColumns, extraConfig);
+    if (access === "write" && primaryKey.length === 0)
+        throw new Error(`Owned table ${name} needs a primary key`);
+    let routingKey;
+    if (access === "write") {
+        const builder = routingColumn().routing_key;
+        const internal = builder;
+        internal.setName("routing_key");
+        const built = internal.build(source).postBuild();
+        Object.assign(source, { routing_key: built });
+        internals[ColumnsKey] = { ...columns, routing_key: built };
+        internals[ExtraColumnsKey] = {
+            ...extraColumns,
+            routing_key: internal.buildExtraConfigColumn(source),
+        };
+        routingKey = "routing_key";
+    }
+    const ownerKeys = [...(routingKey === undefined ? [] : [routingKey]), tenant.key, actor.key];
+    const schema = internals[SchemaKey];
+    owned.set(source, {
+        name: schema === undefined ? name : `${schema}.${name}`,
+        schema,
+        table: name,
+        columns: Object.keys(columns).filter((key) => key !== routingKey),
+        primaryKey,
+        owner: undefined,
+        placement: undefined,
+        adopted: true,
+        access,
+        ownerKeys,
+        ownerColumns: ownerKeys.map((key) => internals[ColumnsKey][key].name),
+        routingKey,
+        tenantKey: tenant.key,
+        actorKey: actor.key,
+        tenantKind: tenant.kind,
+        actorKind: actor.kind,
+    });
+    if (!isOwned(source))
+        throw new Error(`Table ${name} did not take ownership`);
+    return source;
+};
+/**
+ * Declares an actor-owned Drizzle table. The table gains `routing_key`,
+ * `tenant_id`, and `actor_id` columns; its primary key, unique constraints, and
+ * indexes are prefixed with them, so drizzle-kit generates keys that are
+ * unique per actor and scans that stay on one shard. Each table also carries
+ * the `durable_tenant` row-level-security policy: the table owner is exempt,
+ * and a runtime with row-level security sees only each transaction's tenant.
+ *
+ * Throws for anything but a `pgTable`, an alias, an already owned table, a
+ * table with a reserved ownership column, a table without a primary key, or a
+ * foreign key, which would cross actors and need ownership columns on both
+ * sides. Column-level `primaryKey` and `unique` would be global, so they move
+ * into the prefixed extra config. Only btree indexes are accepted: other
+ * methods cannot lead with the bigint and text ownership prefix.
+ *
+ * With `owner`, adopts a table that already exists and other code writes: its
+ * `tenant` and `actor` columns, which must be text, varchar, or uuid, hold the
+ * tenant and the actor's key, and nothing else about the table changes, so
+ * foreign keys stay. A writable adopted table gains a nullable `routing_key`
+ * and starts only after `durable adopt observe`; its primary key stays global,
+ * so a key another actor already holds fails the turn. `access: "read"` maps
+ * the two columns for reading and adds nothing.
+ *
+ * @example
+ * const Notes = Actor.table(pgTable("notes", { id: text("id").primaryKey(), body: text("body") }))
+ * const Invoices = Actor.table(invoices, { owner: { tenant: invoices.orgId, actor: invoices.accountId } })
+ */
+export const table = (source, ...adoption) => {
+    const options = adoption[0];
+    if (!is(source, PgTable))
+        throw new Error("Actor.table takes a pgTable");
+    const internals = source;
+    const name = internals[NameKey];
+    if (internals[IsAliasKey])
+        throw new Error(`Actor.table takes a table, not an alias: ${name}`);
+    if (ownership(source) !== undefined)
+        throw new Error(`Table ${name} is already owned`);
+    if (options !== undefined)
+        return adopt(source, options);
+    const columns = internals[ColumnsKey];
+    const reserved = OWNERSHIP;
+    for (const [key, column] of Object.entries(columns))
+        if (reserved.includes(key) || reserved.includes(column.name))
+            throw new Error(`Column ${key} of ${name} is reserved for ownership`);
+    if (internals[ForeignKeysKey].length > 0)
+        throw new Error(`Owned table ${name} cannot declare foreign keys`);
+    const extraColumns = internals[ExtraColumnsKey];
+    const extraConfig = internals[ExtraConfigKey];
+    const keyOf = new Map(Object.entries(columns).map(([key, column]) => [column.name, key]));
+    let composite;
+    for (const builder of flatten(extraConfig, extraColumns)) {
+        if (is(builder, ForeignKeyBuilder))
+            throw new Error(`Owned table ${name} cannot declare foreign keys`);
+        if (is(builder, PrimaryKeyBuilder))
+            composite = builder.columns.map((column) => keyOf.get(column.name) ?? column.name);
+    }
+    const columnKey = Object.entries(columns).filter(([, column]) => column.primary);
+    const key = composite ?? columnKey.map(([key]) => key);
+    if (key.length === 0)
+        throw new Error(`Owned table ${name} needs a primary key`);
+    const uniques = Object.entries(columns).filter(([, column]) => column.isUnique);
+    for (const [, column] of columnKey)
+        column.primary = false;
+    for (const [, column] of uniques)
+        column.isUnique = false;
+    const built = {};
+    const builtExtra = {};
+    for (const [key, builder] of Object.entries(ownershipColumns())) {
+        const internal = builder;
+        internal.setName(key);
+        built[key] = internal.build(source).postBuild();
+        builtExtra[key] = internal.buildExtraConfigColumn(source);
+    }
+    Object.assign(source, built);
+    internals[ColumnsKey] = { ...built, ...columns };
+    internals[ExtraColumnsKey] = { ...builtExtra, ...extraColumns };
+    internals[ExtraConfigKey] = (self) => {
+        const owner = OWNERSHIP.map((key) => self[key]);
+        const result = [];
+        let primaryName;
+        for (const builder of flatten(extraConfig, self)) {
+            if (is(builder, PrimaryKeyBuilder)) {
+                primaryName = builder.name;
+                continue;
+            }
+            if (is(builder, IndexBuilder)) {
+                const config = builder.config;
+                if (config.method !== undefined && config.method !== "btree")
+                    throw new Error(`Owned table ${name} supports btree indexes only; a ${config.method} index cannot lead with routing_key`);
+                config.columns = [...owner, ...config.columns];
+            }
+            else if (is(builder, UniqueConstraintBuilder)) {
+                const constraint = builder;
+                constraint.columns = [...owner, ...constraint.columns];
+            }
+            result.push(builder);
+        }
+        const [routing, tenant, actor] = owner;
+        for (const [key, column] of uniques) {
+            const constraint = unique(column.uniqueName).on(routing, tenant, actor, self[key]);
+            result.push(column.uniqueType === "not distinct" ? constraint.nullsNotDistinct() : constraint);
+        }
+        const [first, ...rest] = [...owner, ...key.map((column) => self[column])];
+        result.push(primaryKey({ name: primaryName, columns: [first, ...rest] }));
+        const scoped = sql `tenant_id = current_setting('durable.tenant', true)`;
+        result.push(pgPolicy("durable_tenant", { for: "all", using: scoped, withCheck: scoped }));
+        return result;
+    };
+    const schema = internals[SchemaKey];
+    owned.set(source, {
+        name: schema === undefined ? name : `${schema}.${name}`,
+        schema,
+        table: name,
+        columns: Object.keys(columns),
+        primaryKey: key,
+        owner: undefined,
+        adopted: false,
+        access: "write",
+        ownerKeys: OWNERSHIP,
+        ownerColumns: OWNERSHIP,
+        routingKey: "routing_key",
+        tenantKey: "tenant_id",
+        actorKey: "actor_id",
+        tenantKind: "text",
+        actorKind: "text",
+        placement: undefined,
+    });
+    if (!isOwned(source))
+        throw new Error(`Table ${name} did not take ownership`);
+    return source;
+};

package/dist/testing/actor-test.d.ts

@@ -0,0 +1,360 @@
+import type { PgClient } from "@effect/sql-pg";
+import type { PgliteClient } from "@effect/sql-pglite";
+import { Context, Crypto, Data, DateTime, Duration, Effect, FileSystem, Layer, Redacted, Schema, Stream } from "effect";
+import { SqlClient } from "effect/sql";
+import { type ActorRef, type Caller } from "../identity/caller.ts";
+import type { DefinitionWithInternal } from "../actor/definition.ts";
+import type { ActorError } from "../errors/actor.ts";
+import type { AnyConnection } from "../members/connection.ts";
+import { ClientMessage } from "../runtime/connections/protocol.ts";
+import { type Actors } from "../handles/actors.ts";
+import { InternalActors } from "../runtime/actors.ts";
+import { type Outcome, type Request } from "../runtime/request.ts";
+import { type Options } from "../runtime/layer.ts";
+import { type TurnPoint } from "../runtime/turn/hooks.ts";
+import { type ProgressClosed, type ProgressMessage } from "../runtime/jobs/progress.ts";
+import type { Swept } from "../runtime/storage/retention.ts";
+import { ActorCluster, type ClusterOptions } from "./cluster.ts";
+import { type Simulation, type SimulationOptions } from "./simulate.ts";
+import { type ClusterSimulation, type ClusterSimulationOptions } from "./simulate-cluster.ts";
+declare const ClusterMember_base: Context.ServiceClass<ClusterMember, "@rikalabs/akter/testing/actor-test/ClusterMember", {
+    readonly tenant: string;
+    readonly connect: NonNullable<PgClient.PgPoolConfig["stream"]>;
+}>;
+/**
+ * Present while `ActorTest.cluster` builds one of its runners: the runner
+ * shares the cluster's tenant and opens its database connections through
+ * `connect`, so killing it can cut them.
+ */
+export declare class ClusterMember extends ClusterMember_base {
+}
+export interface TestOptions {
+    /**
+     * Postgres connection string or a PGlite client config. Omitted, a fresh
+     * in-memory PGlite database is created per layer build; `dataDir` retains
+     * a database across builds. PGlite is single-process and supplies no
+     * independent-connection behavior.
+     */
+    readonly database?: Redacted.Redacted<string> | PgliteClient.PgliteClientConfig;
+    /** A streaming replica of the Postgres `database`, which queries read once caught up. */
+    readonly replica?: Redacted.Redacted<string> | undefined;
+    /**
+     * Sessions each of the runtime's two pools may open; default 10. Many
+     * runtimes share one Postgres server in a test run, so a runtime that
+     * needs few sessions says so instead of sitting near `max_connections`.
+     */
+    readonly maxConnections?: number;
+    readonly as?: Caller;
+    readonly authorize?: Options["authorize"];
+    readonly retryWindowMs?: number;
+    readonly maxResidentActors?: number;
+    readonly admission?: Options["admission"];
+    readonly relay?: Options["relay"];
+    readonly executors?: Options["executors"];
+    readonly observability?: Options["observability"];
+    readonly rowLevelSecurity?: Options["rowLevelSecurity"];
+    readonly adoption?: Options["adoption"];
+    readonly payloadWriterWindow?: Options["payloadWriterWindow"];
+    /** Shared content settings; omitted, a fixed test grant key with the default grace and skew. */
+    readonly content?: Options["content"] | undefined;
+    /** Fleet views the runtime maintains; they need Postgres with `wal_level=logical`. */
+    readonly fleet?: Options["fleet"];
+}
+/** The grant key tests sign content grants with unless they configure their own. */
+export declare const TEST_CONTENT_KEY: {
+    id: string;
+    secret: Redacted.Redacted<string>;
+};
+export interface FaultOptions {
+    /** Only a turn running this command id takes the fault. */
+    readonly commandId?: string;
+}
+export interface Inspection {
+    readonly generation: string | undefined;
+    readonly state: Schema.JsonObject["Type"];
+    readonly receipts: number;
+    readonly events: number;
+    /** Pending intents and timers this actor sent, including job routes awaiting delivery. */
+    readonly outbox: number;
+    /** Jobs this actor enqueued whose executor has not yet settled them. */
+    readonly jobs: number;
+    /**
+     * The actor's row count per owned table, keyed by table name (schema-qualified
+     * outside the current schema); present when its type owns tables.
+     */
+    readonly rows?: Readonly<Record<string, number>>;
+    /** The actor's entry count per declared blob; present when its type declares blobs. */
+    readonly blobs?: Readonly<Record<string, number>>;
+}
+/** A test client's open connection, as a socket on this runner's transport would see it. */
+export interface TestConnection<C extends AnyConnection> {
+    readonly connectionId: string;
+    /** The flushed-through cursor after `open`: events after it were not replayed by `open`. */
+    readonly cursor: string;
+    /** Sends one client frame; it is encoded and numbered like a socket frame. */
+    readonly send: (frame: C["client"]["Type"]) => Effect.Effect<void, ActorError>;
+    /** Server frames in order; fails with the session's end. Control frames are skipped. */
+    readonly frames: Stream.Stream<C["server"]["Type"], ActorError>;
+    /** Every envelope in order, member frames with their cursors and control frames included. */
+    readonly messages: Stream.Stream<TestMessage<C["server"]["Type"]>, ActorError>;
+    /** Answers a `Resync` control frame once the client has caught up. */
+    readonly resyncDone: Effect.Effect<void>;
+    readonly close: Effect.Effect<void>;
+}
+export type TestMessage<Server> = {
+    readonly _tag: "Frame";
+    readonly frame: Server;
+    readonly cursor?: string | undefined;
+    readonly event?: string | undefined;
+} | {
+    /** Executor progress: display-only, lossy, and never replayed. */
+    readonly _tag: "Progress";
+    readonly job: string;
+    readonly jobId: string;
+    readonly attempt: number;
+    readonly seq: number;
+    /** The frame as the job's progress schema encodes it to JSON. */
+    readonly frame: unknown;
+} | Exclude<ClientMessage, {
+    readonly _tag: "Frame" | "Progress";
+}>;
+export interface TestDefinition {
+    readonly get: unknown;
+}
+type InternalHandleOf<D> = D extends DefinitionWithInternal<infer H> ? H : never;
+/** Package-internal escape hatch for deterministic runtime conformance cases. */
+export declare const executeForTest: (request: Request) => Effect.Effect<Outcome, ActorError, ActorTest>;
+/**
+ * Runs one retention sweep in the current runtime now, as its background loop
+ * does every minute; for benchmarks and tests that use the production layer.
+ */
+export declare const cleanup: Effect.Effect<Swept, never, InternalActors>;
+/**
+ * Sweeps every tenant's unreferenced content now, however recently each was
+ * swept, and returns how many contents it deleted; for benchmarks and tests.
+ */
+export declare const sweepContent: Effect.Effect<number, never, InternalActors>;
+/** A progress message an executor pool sent, and whether `dropProgress` dropped it. */
+export type ProgressRecord = Data.TaggedEnum<{
+    Progress: ProgressMessage & {
+        readonly dropped: boolean;
+    };
+    ProgressClosed: ProgressClosed & {
+        readonly dropped: boolean;
+    };
+}>;
+export declare const ProgressRecord: {
+    readonly $is: <Tag extends "Progress" | "ProgressClosed">(tag: Tag) => (u: unknown) => u is Extract<{
+        readonly _tag: "Progress";
+        readonly ref: ActorRef;
+        readonly jobId: string;
+        readonly job: string;
+        readonly attempt: number;
+        readonly seq: number;
+        readonly leaseUntil: number;
+        readonly frame: Uint8Array;
+        readonly dropped: boolean;
+    }, {
+        readonly _tag: Tag;
+    }> | Extract<{
+        readonly _tag: "ProgressClosed";
+        readonly ref: ActorRef;
+        readonly jobId: string;
+        readonly attempt: number;
+        readonly dropped: boolean;
+    }, {
+        readonly _tag: Tag;
+    }>;
+    readonly $match: {
+        <Cases extends { readonly [Tag in "Progress" | "ProgressClosed"]: (args: Extract<{
+            readonly _tag: "Progress";
+            readonly ref: ActorRef;
+            readonly jobId: string;
+            readonly job: string;
+            readonly attempt: number;
+            readonly seq: number;
+            readonly leaseUntil: number;
+            readonly frame: Uint8Array;
+            readonly dropped: boolean;
+        } | {
+            readonly _tag: "ProgressClosed";
+            readonly ref: ActorRef;
+            readonly jobId: string;
+            readonly attempt: number;
+            readonly dropped: boolean;
+        }, {
+            readonly _tag: Tag;
+        }>) => any; }>(cases: Cases): (value: {
+            readonly _tag: "Progress";
+            readonly ref: ActorRef;
+            readonly jobId: string;
+            readonly job: string;
+            readonly attempt: number;
+            readonly seq: number;
+            readonly leaseUntil: number;
+            readonly frame: Uint8Array;
+            readonly dropped: boolean;
+        } | {
+            readonly _tag: "ProgressClosed";
+            readonly ref: ActorRef;
+            readonly jobId: string;
+            readonly attempt: number;
+            readonly dropped: boolean;
+        }) => import("effect/Unify").Unify<ReturnType<Cases["Progress" | "ProgressClosed"]>>;
+        <Cases extends { readonly [Tag in "Progress" | "ProgressClosed"]: (args: Extract<{
+            readonly _tag: "Progress";
+            readonly ref: ActorRef;
+            readonly jobId: string;
+            readonly job: string;
+            readonly attempt: number;
+            readonly seq: number;
+            readonly leaseUntil: number;
+            readonly frame: Uint8Array;
+            readonly dropped: boolean;
+        } | {
+            readonly _tag: "ProgressClosed";
+            readonly ref: ActorRef;
+            readonly jobId: string;
+            readonly attempt: number;
+            readonly dropped: boolean;
+        }, {
+            readonly _tag: Tag;
+        }>) => any; }>(value: {
+            readonly _tag: "Progress";
+            readonly ref: ActorRef;
+            readonly jobId: string;
+            readonly job: string;
+            readonly attempt: number;
+            readonly seq: number;
+            readonly leaseUntil: number;
+            readonly frame: Uint8Array;
+            readonly dropped: boolean;
+        } | {
+            readonly _tag: "ProgressClosed";
+            readonly ref: ActorRef;
+            readonly jobId: string;
+            readonly attempt: number;
+            readonly dropped: boolean;
+        }, cases: Cases): import("effect/Unify").Unify<ReturnType<Cases["Progress" | "ProgressClosed"]>>;
+    };
+    readonly Progress: Data.TaggedEnum.ConstructorFrom<{
+        readonly _tag: "Progress";
+        readonly ref: ActorRef;
+        readonly jobId: string;
+        readonly job: string;
+        readonly attempt: number;
+        readonly seq: number;
+        readonly leaseUntil: number;
+        readonly frame: Uint8Array;
+        readonly dropped: boolean;
+    }, "_tag">;
+    readonly ProgressClosed: Data.TaggedEnum.ConstructorFrom<{
+        readonly _tag: "ProgressClosed";
+        readonly ref: ActorRef;
+        readonly jobId: string;
+        readonly attempt: number;
+        readonly dropped: boolean;
+    }, "_tag">;
+};
+/** Options of `ActorTest.actor`. */
+export interface TestActorOptions {
+    /**
+     * Path of a seed file `durable export` wrote. The actor starts from its
+     * state and pending work, staged as the caller the test runs as; the seed
+     * carries no tenant, caller, or credential. Reading it needs a `FileSystem`.
+     * An actor that already exists, a seed of another actor type, and a seed
+     * naming an effect the actor does not register each die.
+     */
+    readonly seed?: string;
+}
+declare const ActorTest_base: Context.ServiceClass<ActorTest, "@rikalabs/akter/testing/actor-test/ActorTest", {
+    readonly tenant: string;
+    readonly actor: <D extends TestDefinition, O extends TestActorOptions = {}>(definition: D, id?: string, options?: O) => Effect.Effect<{
+        readonly system: InternalHandleOf<D>;
+        readonly inspect: Effect.Effect<Inspection>;
+    }, never, Actors | (O extends {
+        readonly seed: string;
+    } ? FileSystem.FileSystem : never)>;
+    readonly inspect: (ref: ActorRef) => Effect.Effect<Inspection>;
+    /**
+     * Crashes the next turn to reach `point`, or with `commandId` the next
+     * turn of that command, which other commands' turns pass through.
+     */
+    readonly crashNext: (point: TurnPoint, options?: FaultOptions) => Effect.Effect<void>;
+    /** Pauses the next turn to reach `point`, or with `commandId` the next turn of that command. */
+    readonly pauseNext: (point: TurnPoint, options?: FaultOptions) => Effect.Effect<{
+        readonly reached: Effect.Effect<void>;
+        readonly release: Effect.Effect<void>;
+    }>;
+    /** Removes every queued `crashNext` and `pauseNext` fault and returns the points they were queued at. */
+    readonly clearFaults: Effect.Effect<ReadonlyArray<TurnPoint>>;
+    readonly invalidate: (ref: ActorRef) => Effect.Effect<void>;
+    /**
+     * Opens a connection to `ref` through this runner's in-process transport,
+     * which then holds it. A declared failure of `open` fails with that error.
+     */
+    readonly connect: <C extends AnyConnection>(ref: ActorRef, member: C, params: C["payload"]["Type"]) => Effect.Effect<TestConnection<C>, ActorError | C["error"]["Type"]>;
+    /** Ends the actor's activation on this runner as `hibernateAfter` would; its connections stay open. */
+    readonly hibernate: (ref: ActorRef) => Effect.Effect<void>;
+    /**
+     * Moves the framework clock forward by `duration`, then delivers every
+     * intent and timer that is due, including intents those deliveries stage.
+     * Command-id expiry, event timestamps, and retention follow the same clock.
+     */
+    readonly advance: (duration: Duration.Input) => Effect.Effect<void>;
+    /** The framework clock: database time plus every `advance` so far; `Intent.at` is due against it. */
+    readonly now: Effect.Effect<DateTime.Utc>;
+    /**
+     * Runs one retention sweep now, as the runtime does every minute, and
+     * returns how many receipts and events it deleted.
+     */
+    readonly cleanup: Effect.Effect<Swept>;
+    /** Committed receipts of `command` on the actor `ref`. */
+    readonly receiptsFor: (ref: ActorRef, command: string) => Effect.Effect<number>;
+    /**
+     * Writes raw stored state, as an older deployment would have, so tests can
+     * exercise state migrations. `version` is the number of migrations the
+     * stored shape has already passed through.
+     */
+    readonly seed: (ref: ActorRef, state: {
+        readonly [key: string]: Schema.Json;
+    }, version: number) => Effect.Effect<void>;
+    /** Every progress message this runner's executor pool sent, in order. */
+    readonly progress: Effect.Effect<ReadonlyArray<ProgressRecord>>;
+    /**
+     * Sends a progress message to its owner again, as a frame the network
+     * delayed would arrive; for cases about late progress.
+     */
+    readonly resendProgress: (message: ProgressMessage) => Effect.Effect<void>;
+    /**
+     * While `dropping` holds, this runner's owners send no `Committed` frame
+     * to query watches, as a lost broadcast would; a watch then shows a change
+     * only on its reconcile rerun.
+     */
+    readonly dropCommitted: (dropping: boolean) => Effect.Effect<void>;
+    /** Drops progress messages matching `predicate` between the pool and the owner. */
+    readonly dropProgress: (predicate: (message: ProgressMessage | ProgressClosed) => boolean) => Effect.Effect<void>;
+}>;
+export declare class ActorTest extends ActorTest_base {
+    /**
+     * Runs `runners` runtimes in this process against one Postgres database,
+     * each a distinct Cluster runner with its own address, connection pool, and
+     * expiring shard locks. Provides `ActorCluster`; see its controls.
+     */
+    static readonly cluster: <ROut, E, RIn>(options: ClusterOptions<ROut, E, RIn>) => Layer.Layer<ActorCluster, never, Crypto.Crypto | Exclude<Exclude<RIn, ActorTest | Actors | import("../index.ts").ContentStore | import("../runtime/index.ts").DefectLog | InternalActors | import("../runtime/operators/repair.ts").OperatorRuntime | PgliteClient.PgliteClient | import("../runtime/drain.ts").RuntimeControl | SqlClient.SqlClient | import("../runtime/index.ts").TelemetrySampler>, import("effect/Scope").Scope>>;
+    /**
+     * Runs `program` on the current test runtime under a fault schedule drawn
+     * from `seed`, then checks exactly-once receipts and outbox delivery; a
+     * failure dies with the seed that reproduces it.
+     */
+    static readonly simulate: <E, R>(options: SimulationOptions, program: (simulation: Simulation) => Effect.Effect<void, E, R>) => Effect.Effect<import("./simulate.ts").SimulationReport, never, R | ActorTest | Actors | SqlClient.SqlClient>;
+    /**
+     * Runs `program` on the current `ActorTest.cluster` under a fault schedule
+     * drawn from `seed`, with runner kills, lost heartbeats, and primary
+     * failovers as well as crashes, then checks exactly-once receipts and
+     * outbox delivery; a failure dies with the seed that reproduces it.
+     */
+    static readonly simulateCluster: <E, R>(options: ClusterSimulationOptions, program: (simulation: ClusterSimulation) => Effect.Effect<void, E, R>) => Effect.Effect<import("./simulate-cluster.ts").ClusterSimulationReport, never, R | ActorCluster>;
+    static readonly layer: (options?: TestOptions) => Layer.Layer<ActorTest | Actors | import("../index.ts").ContentStore | import("../runtime/index.ts").DefectLog | InternalActors | import("../runtime/operators/repair.ts").OperatorRuntime | PgliteClient.PgliteClient | import("../runtime/drain.ts").RuntimeControl | SqlClient.SqlClient | import("../runtime/index.ts").TelemetrySampler, import("../errors/database.ts").DataDirLocked | import("../errors/database.ts").DataDirVersion | import("effect/sql/Migrator").MigrationError | import("effect/sql/SqlError").SqlError, Crypto.Crypto>;
+}
+export {};