@rikalabs/akter 0.1.0-alpha.0

package/dist/runtime/operators/routes.d.ts

@@ -0,0 +1,35 @@
+import { HttpRouter } from "effect/http";
+import { DefectLog } from "../telemetry/defects.ts";
+import type { OperatorAuth } from "./auth.ts";
+import { OperatorRuntime } from "./repair.ts";
+/** Options for serving the operator routes. */
+export interface OperatorsOptions<R> {
+    /** Authenticates every operator request to a grant; an `Actor.auth` provider is not accepted. */
+    readonly auth: OperatorAuth<R>;
+    /** Prefix for every route. Default `"/operator"`. */
+    readonly basePath?: `/${string}`;
+}
+/**
+ * Serves the operator routes on the application's `HttpRouter`. Every
+ * request is authenticated to an operator grant, checked against the one
+ * capability its action and resource need, and recorded in the operator
+ * audit log: a repair in its own transaction, a read before it is answered,
+ * and a refusal by scope as `"denied"`. A browser page on another origin is
+ * refused before its credentials are read.
+ *
+ * - `GET /actors/:type/:id?tenant&limit`: `inspect`; receipt outcomes only under `receipts.read`.
+ * - `GET /actors/:type/:id/export?tenant`: `export`; the actor's seed, read-only. Answers 409 `ExportRefused` when a stored value does not decode or the actor holds too much pending work.
+ * - `GET /receipts/:type/:id/:commandId?tenant`: `receipts.read`; never runs the command.
+ * - `GET /defects?tenant&actor&sinceMs&limit`: `defects.read`; `tenant` may be `*`.
+ * - `POST /dead-letters/:jobId/retry` `{ tenant, actorType, actorId, reason, providerChecked? }`: `dead-letters.retry`.
+ * - `POST /dead-letters/:jobId/discard` `{ tenant, actorType, actorId, reason }`: `dead-letters.discard`.
+ * - `POST /subscriptions/skip` `{ tenant, sourceType, sourceId, subscriberType, subscription, subscriberId, through, reason }`: `subscriptions.skip`, scoped to the source actor.
+ * - `GET /subscriptions/lagging?tenant&minAttempts&limit`: `inspect`, tenant-wide; failing subscription rows with their lag and last error.
+ * - `GET /audit?tenant&limit`: `audit.read`; `tenant` may be `*`.
+ */
+declare const serve: <R = never>(options: OperatorsOptions<R>) => import("effect/Layer").Layer<never, never, DefectLog | HttpRouter.HttpRouter | OperatorRuntime | Exclude<R, import("effect/Scope").Scope> | Exclude<HttpRouter.Request.From<"Requires", Exclude<Exclude<R, R>, HttpRouter.Provided>>, import("effect/Scope").Scope>>;
+/** Operator route constructors; `serve` mounts the routes. */
+export declare const Operators: {
+    serve: typeof serve;
+};
+export {};

package/dist/runtime/operators/routes.js

@@ -0,0 +1,190 @@
+import { Effect, Match, Option, Schema } from "effect";
+import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/http";
+import { ActorError, Unauthorized } from "../../errors/actor.js";
+import { invalidInput, undecodable } from "../../serve/wire.js";
+import { foundOrNotFound, notFoundResponse, operatorResponse, refuseCrossOrigin, } from "../inspector/http.js";
+import { DefectLog } from "../telemetry/defects.js";
+import { authorizing } from "./grants.js";
+import { OperatorRuntime } from "./repair.js";
+/** The most rows one list returns. */
+const MAX_ROWS = 1000;
+const Tenant = Schema.NonEmptyString;
+const Limit = Schema.FiniteFromString.check(Schema.isInt(), Schema.isBetween({ minimum: 1, maximum: MAX_ROWS }));
+const ActorParams = Schema.Struct({ type: Schema.NonEmptyString, id: Schema.NonEmptyString });
+const ReceiptParams = Schema.Struct({
+    type: Schema.NonEmptyString,
+    id: Schema.NonEmptyString,
+    commandId: Schema.NonEmptyString,
+});
+const JobParams = Schema.Struct({ jobId: Schema.NonEmptyString });
+const PageQuery = Schema.Struct({ tenant: Tenant, limit: Schema.optional(Limit) });
+const TenantQuery = Schema.Struct({ tenant: Tenant });
+const DefectsQuery = Schema.Struct({
+    tenant: Tenant,
+    actor: Schema.optional(Schema.NonEmptyString),
+    sinceMs: Schema.optional(Schema.FiniteFromString.check(Schema.isInt())),
+    limit: Schema.optional(Limit),
+});
+/** Rows that failed this many deliveries in a row count as lagging. */
+const LAGGING_ATTEMPTS = 8;
+const LaggingQuery = Schema.Struct({
+    tenant: Tenant,
+    minAttempts: Schema.optional(Schema.FiniteFromString.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(1))),
+    limit: Schema.optional(Limit),
+});
+const Reason = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(500));
+const DiscardBody = Schema.Struct({
+    tenant: Tenant,
+    actorType: Schema.NonEmptyString,
+    actorId: Schema.NonEmptyString,
+    reason: Reason,
+});
+const SkipBody = Schema.Struct({
+    tenant: Tenant,
+    sourceType: Schema.NonEmptyString,
+    sourceId: Schema.NonEmptyString,
+    subscriberType: Schema.NonEmptyString,
+    subscription: Schema.NonEmptyString,
+    subscriberId: Schema.NonEmptyString,
+    through: Schema.String.check(Schema.isPattern(/^[1-9][0-9]{0,17}$/u)),
+    reason: Reason,
+});
+const RetryBody = Schema.Struct({
+    ...DiscardBody.fields,
+    providerChecked: Schema.optional(Schema.Boolean),
+});
+/** Answers a repair's result as JSON and each refusal with its own status. */
+const repairResponse = (repair) => repair.pipe(Effect.map((result) => HttpServerResponse.jsonUnsafe(result)), Effect.catch((error) => Effect.succeed(Match.value(error).pipe(Match.tagsExhaustive({
+    OperatorNotFound: notFoundResponse,
+    ProviderOutcomeUnknown: (refused) => HttpServerResponse.jsonUnsafe(refused, { status: 409 }),
+    JobNotServed: (refused) => HttpServerResponse.jsonUnsafe(refused, { status: 503 }),
+})))));
+/** Decodes a JSON request body; a body that is not JSON is refused as `decode`. */
+const decodeBody = (schema) => HttpServerRequest.schemaBodyJson(schema).pipe(Effect.catchTag("HttpServerError", () => Effect.fail(invalidInput("decode"))));
+/**
+ * Serves the operator routes on the application's `HttpRouter`. Every
+ * request is authenticated to an operator grant, checked against the one
+ * capability its action and resource need, and recorded in the operator
+ * audit log: a repair in its own transaction, a read before it is answered,
+ * and a refusal by scope as `"denied"`. A browser page on another origin is
+ * refused before its credentials are read.
+ *
+ * - `GET /actors/:type/:id?tenant&limit`: `inspect`; receipt outcomes only under `receipts.read`.
+ * - `GET /actors/:type/:id/export?tenant`: `export`; the actor's seed, read-only. Answers 409 `ExportRefused` when a stored value does not decode or the actor holds too much pending work.
+ * - `GET /receipts/:type/:id/:commandId?tenant`: `receipts.read`; never runs the command.
+ * - `GET /defects?tenant&actor&sinceMs&limit`: `defects.read`; `tenant` may be `*`.
+ * - `POST /dead-letters/:jobId/retry` `{ tenant, actorType, actorId, reason, providerChecked? }`: `dead-letters.retry`.
+ * - `POST /dead-letters/:jobId/discard` `{ tenant, actorType, actorId, reason }`: `dead-letters.discard`.
+ * - `POST /subscriptions/skip` `{ tenant, sourceType, sourceId, subscriberType, subscription, subscriberId, through, reason }`: `subscriptions.skip`, scoped to the source actor.
+ * - `GET /subscriptions/lagging?tenant&minAttempts&limit`: `inspect`, tenant-wide; failing subscription rows with their lag and last error.
+ * - `GET /audit?tenant&limit`: `audit.read`; `tenant` may be `*`.
+ */
+const serve = (options) => HttpRouter.use(Effect.fnUntraced(function* (router) {
+    const basePath = (options.basePath ?? "/operator").replace(/\/+$/, "");
+    const context = yield* Effect.context();
+    const runtime = yield* OperatorRuntime;
+    const defects = yield* DefectLog;
+    const authenticate = (request) => Effect.gen(function* () {
+        yield* refuseCrossOrigin(request);
+        return yield* options.auth
+            .authenticate({
+            headers: request.headers,
+            cookies: {},
+        })
+            .pipe(Effect.provideContext(context), Effect.mapError((reason) => ActorError.make({ reason })), Effect.tapError(() => Effect.logWarning("Operator request not authenticated")));
+    });
+    const authorize = (grant, action, resource, target) => Effect.gen(function* () {
+        const entry = {
+            operator: grant.operator,
+            action,
+            tenant: resource.tenant,
+            actorType: resource.actorType,
+            actorId: resource.actorId,
+            target,
+            capability: authorizing({ grant, action, resource }),
+        };
+        if (Option.isNone(entry.capability)) {
+            yield* runtime.record(entry, "denied");
+            return yield* ActorError.make({ reason: Unauthorized.make({ code: "access_denied" }) });
+        }
+        return entry;
+    });
+    /** Authorizes a read and records it in the audit log before it is answered. */
+    const authorizeRead = (grant, action, resource, target) => authorize(grant, action, resource, target).pipe(Effect.flatMap((entry) => runtime.record(entry, "read")));
+    const route = (method, path, handle) => router.add(method, `${basePath}${path}`, (request) => authenticate(request).pipe(Effect.flatMap(handle), Effect.catchTag("SchemaError", (error) => Effect.fail(undecodable(error))), operatorResponse("Operator request failed")));
+    yield* route("GET", "/actors/:type/:id", (grant) => Effect.gen(function* () {
+        const { type, id } = yield* HttpRouter.schemaPathParams(ActorParams);
+        const { tenant, limit } = yield* HttpRouter.schemaParams(PageQuery);
+        const resource = { tenant, actorType: type, actorId: id };
+        const entry = yield* authorize(grant, "inspect", resource);
+        const outcomes = Option.isSome(authorizing({ grant, action: "receipts.read", resource }));
+        yield* runtime.record(entry, { outcomes });
+        return foundOrNotFound(yield* runtime.inspect({ ...resource, limit: limit ?? 20, outcomes }));
+    }));
+    yield* route("GET", "/actors/:type/:id/export", (grant) => Effect.gen(function* () {
+        const { type, id } = yield* HttpRouter.schemaPathParams(ActorParams);
+        const { tenant } = yield* HttpRouter.schemaParams(TenantQuery);
+        const resource = { tenant, actorType: type, actorId: id };
+        yield* authorizeRead(grant, "export", resource);
+        return yield* runtime.exportSeed(resource).pipe(Effect.map(foundOrNotFound), Effect.catchTag("ExportRefused", (refused) => Effect.succeed(HttpServerResponse.jsonUnsafe(refused, { status: 409 }))));
+    }));
+    yield* route("GET", "/receipts/:type/:id/:commandId", (grant) => Effect.gen(function* () {
+        const { type, id, commandId } = yield* HttpRouter.schemaPathParams(ReceiptParams);
+        const { tenant } = yield* HttpRouter.schemaParams(TenantQuery);
+        const resource = { tenant, actorType: type, actorId: id, commandId };
+        yield* authorizeRead(grant, "receipts.read", resource, commandId);
+        return foundOrNotFound(yield* runtime.receipt(resource));
+    }));
+    yield* route("GET", "/defects", (grant) => Effect.gen(function* () {
+        const { tenant, actor, sinceMs, limit } = yield* HttpRouter.schemaParams(DefectsQuery);
+        yield* authorizeRead(grant, "defects.read", { tenant, actorType: actor });
+        const listed = yield* defects.list({ actorType: actor, sinceMs });
+        const own = tenant === "*" ? listed : listed.filter((defect) => defect.tenant === tenant);
+        return HttpServerResponse.jsonUnsafe(own.slice(-(limit ?? MAX_ROWS)));
+    }));
+    const repair = (path, run) => route("POST", `/dead-letters/:jobId/${path}`, (grant) => Effect.gen(function* () {
+        const { jobId } = yield* HttpRouter.schemaPathParams(JobParams);
+        const body = yield* decodeBody(RetryBody);
+        const entry = yield* authorize(grant, path === "retry" ? "dead-letters.retry" : "dead-letters.discard", target(body), jobId);
+        return yield* repairResponse(run(body, jobId, { ...entry, reason: body.reason }));
+    }));
+    yield* repair("retry", (body, jobId, audit) => runtime.retry({
+        target: target(body),
+        jobId,
+        providerChecked: body.providerChecked === true,
+        audit,
+    }));
+    yield* repair("discard", (body, jobId, audit) => runtime
+        .discard({ target: target(body), jobId, audit })
+        .pipe(Effect.as({ discarded: jobId })));
+    yield* route("POST", "/subscriptions/skip", (grant) => Effect.gen(function* () {
+        const body = yield* decodeBody(SkipBody);
+        const source = { tenant: body.tenant, actorType: body.sourceType, actorId: body.sourceId };
+        const entry = yield* authorize(grant, "subscriptions.skip", source, `${body.subscriberType}.${body.subscription}/${body.subscriberId}`);
+        return yield* repairResponse(runtime.skip({
+            target: source,
+            subscriberType: body.subscriberType,
+            subscription: body.subscription,
+            subscriberId: body.subscriberId,
+            through: body.through,
+            audit: { ...entry, reason: body.reason },
+        }));
+    }));
+    yield* route("GET", "/subscriptions/lagging", (grant) => Effect.gen(function* () {
+        const { tenant, minAttempts, limit } = yield* HttpRouter.schemaParams(LaggingQuery);
+        yield* authorizeRead(grant, "inspect", { tenant });
+        return HttpServerResponse.jsonUnsafe(yield* runtime.lagging({
+            tenant,
+            minAttempts: minAttempts ?? LAGGING_ATTEMPTS,
+            limit: limit ?? 100,
+        }));
+    }));
+    yield* route("GET", "/audit", (grant) => Effect.gen(function* () {
+        const { tenant, limit } = yield* HttpRouter.schemaParams(PageQuery);
+        yield* authorizeRead(grant, "audit.read", { tenant });
+        return HttpServerResponse.jsonUnsafe(yield* runtime.audit({ tenant, limit: limit ?? 100 }));
+    }));
+}));
+const target = (resource) => ({ tenant: resource.tenant, actorType: resource.actorType, actorId: resource.actorId });
+/** Operator route constructors; `serve` mounts the routes. */
+export const Operators = { serve };

package/dist/runtime/operators/seed.d.ts

@@ -0,0 +1,123 @@
+import { type Context, type Crypto, Effect, Schema } from "effect";
+import { SqlClient } from "effect/sql";
+import type { RegisteredJob } from "../members.ts";
+import { ActorRef, type Caller } from "../../identity/caller.ts";
+import { TenantScope } from "../database/tenancy.ts";
+import { FrameworkClock } from "../turn/admission.ts";
+import { OutboxRuntime } from "../turn/outbox.ts";
+/** The only seed format this build writes and reads. */
+export declare const SEED_FORMAT = 1;
+/**
+ * One actor's exported state and pending obligations, with nothing that
+ * identifies its tenant, caller, or credentials: a seed is replayed under the
+ * tenant and caller of the test that reads it. `dueInMs` is measured from the
+ * moment of export, so a replay follows the test's own clock. `omitted` counts
+ * what the seed does not carry: receipts, events, workflow executions, dead
+ * letters, rows of the actor's owned tables, and its blob entries, so a reader
+ * can see what a replay starts without.
+ */
+export declare const Seed: Schema.Struct<{
+    readonly format: Schema.Literal<1>;
+    readonly actor: Schema.Struct<{
+        readonly type: Schema.NonEmptyString;
+        readonly id: Schema.NonEmptyString;
+    }>;
+    readonly created: Schema.Boolean;
+    readonly stateVersion: Schema.Int;
+    readonly state: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    readonly intents: Schema.$Array<Schema.Struct<{
+        readonly target: Schema.Struct<{
+            readonly actor: Schema.NonEmptyString;
+            readonly id: Schema.NonEmptyString;
+        }>;
+        readonly command: Schema.NonEmptyString;
+        readonly payload: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+        readonly key: Schema.optional<Schema.NonEmptyString>;
+        readonly dueInMs: Schema.Int;
+    }>>;
+    readonly jobs: Schema.$Array<Schema.Struct<{
+        readonly job: Schema.NonEmptyString;
+        readonly payload: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+        readonly payloadVersion: Schema.Int;
+        readonly key: Schema.optional<Schema.NonEmptyString>;
+        readonly dueInMs: Schema.Int;
+    }>>;
+    readonly omitted: Schema.Struct<{
+        readonly receipts: Schema.Int;
+        readonly events: Schema.Int;
+        readonly workflows: Schema.Int;
+        readonly deadLetters: Schema.Int;
+        readonly tableRows: Schema.Int;
+        readonly blobs: Schema.Int;
+    }>;
+}>;
+/** A decoded `Seed`. */
+export type Seed = typeof Seed.Type;
+/** Codec between a `Seed` and the JSON text a seed file holds. */
+export declare const SeedJson: Schema.fromJsonString<Schema.Struct<{
+    readonly format: Schema.Literal<1>;
+    readonly actor: Schema.Struct<{
+        readonly type: Schema.NonEmptyString;
+        readonly id: Schema.NonEmptyString;
+    }>;
+    readonly created: Schema.Boolean;
+    readonly stateVersion: Schema.Int;
+    readonly state: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    readonly intents: Schema.$Array<Schema.Struct<{
+        readonly target: Schema.Struct<{
+            readonly actor: Schema.NonEmptyString;
+            readonly id: Schema.NonEmptyString;
+        }>;
+        readonly command: Schema.NonEmptyString;
+        readonly payload: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+        readonly key: Schema.optional<Schema.NonEmptyString>;
+        readonly dueInMs: Schema.Int;
+    }>>;
+    readonly jobs: Schema.$Array<Schema.Struct<{
+        readonly job: Schema.NonEmptyString;
+        readonly payload: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+        readonly payloadVersion: Schema.Int;
+        readonly key: Schema.optional<Schema.NonEmptyString>;
+        readonly dueInMs: Schema.Int;
+    }>>;
+    readonly omitted: Schema.Struct<{
+        readonly receipts: Schema.Int;
+        readonly events: Schema.Int;
+        readonly workflows: Schema.Int;
+        readonly deadLetters: Schema.Int;
+        readonly tableRows: Schema.Int;
+        readonly blobs: Schema.Int;
+    }>;
+}>>;
+/** What the runtime's clock and outbox references hold on this runner. */
+type ReferenceOf<T> = T extends Context.Reference<infer S> ? S : never;
+/**
+ * Builds the operation that starts an actor from a seed, over the runtime's
+ * SQL, crypto, clock, and outbox, and its job registrations.
+ *
+ * The actor's row, state, and obligations are written in one transaction, so
+ * a refused seed leaves nothing behind. It never overwrites: an actor that
+ * already has a generation row refuses the seed. Obligations are staged
+ * through the turn's own outbox statements under the caller the test runs as,
+ * never a caller from the file, so a seed cannot carry authority. A job
+ * this runner has no executor for is refused, because it could never run.
+ * A seed marking created an actor type that declares no `createdBy` is
+ * refused: that marker stays false for such a type, or declaring the policy
+ * later would treat the seeded actor as already created.
+ */
+export declare const seedRuntime: (deps: {
+    readonly services: Context.Context<SqlClient.SqlClient | Crypto.Crypto>;
+    readonly clock: ReferenceOf<typeof FrameworkClock>;
+    readonly outbox: ReferenceOf<typeof OutboxRuntime>;
+    readonly jobOf: (actorType: string, job: string) => RegisteredJob | undefined;
+    /** Whether the actor type declares `createdBy`. */
+    readonly createdBy: (actorType: string) => boolean;
+    readonly wake: Effect.Effect<void>;
+    /** The tenant and adoption writer roles the operator's turns take, as the runtime's own turns do. */
+    readonly tenantScope: ReferenceOf<typeof TenantScope>;
+}) => (args_0: {
+    readonly ref: ActorRef;
+    readonly caller: Caller;
+    readonly seed: Seed;
+}) => Effect.Effect<undefined, never, never>;
+export {};

package/dist/runtime/operators/seed.js

@@ -0,0 +1,123 @@
+import { Effect, Schema } from "effect";
+import { SqlClient, SqlError } from "effect/sql";
+import { Due, emptyOutbox } from "../../handles/intents.js";
+import { ActorRef } from "../../identity/caller.js";
+import { VERSION_KEY } from "../../state/migration.js";
+import { TenantScope, withTenant } from "../database/tenancy.js";
+import { compress, routingKey } from "../storage/codec.js";
+import { recordedPlacement } from "../storage/placements.js";
+import { databaseTime, FrameworkClock } from "../turn/admission.js";
+import { OutboxRuntime, outboxStatements } from "../turn/outbox.js";
+/** The only seed format this build writes and reads. */
+export const SEED_FORMAT = 1;
+const Count = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
+/**
+ * One actor's exported state and pending obligations, with nothing that
+ * identifies its tenant, caller, or credentials: a seed is replayed under the
+ * tenant and caller of the test that reads it. `dueInMs` is measured from the
+ * moment of export, so a replay follows the test's own clock. `omitted` counts
+ * what the seed does not carry: receipts, events, workflow executions, dead
+ * letters, rows of the actor's owned tables, and its blob entries, so a reader
+ * can see what a replay starts without.
+ */
+export const Seed = Schema.Struct({
+    format: Schema.Literal(SEED_FORMAT),
+    actor: Schema.Struct({ type: Schema.NonEmptyString, id: Schema.NonEmptyString }),
+    created: Schema.Boolean,
+    stateVersion: Count,
+    state: Schema.Record(Schema.String, Schema.Json),
+    intents: Schema.Array(Schema.Struct({
+        target: Schema.Struct({ actor: Schema.NonEmptyString, id: Schema.NonEmptyString }),
+        command: Schema.NonEmptyString,
+        payload: Schema.Json,
+        key: Schema.optional(Schema.NonEmptyString),
+        dueInMs: Count,
+    })),
+    jobs: Schema.Array(Schema.Struct({
+        job: Schema.NonEmptyString,
+        payload: Schema.Json,
+        payloadVersion: Count,
+        key: Schema.optional(Schema.NonEmptyString),
+        dueInMs: Count,
+    })),
+    omitted: Schema.Struct({
+        receipts: Count,
+        events: Count,
+        workflows: Count,
+        deadLetters: Count,
+        tableRows: Count,
+        blobs: Count,
+    }),
+});
+/** Codec between a `Seed` and the JSON text a seed file holds. */
+export const SeedJson = Schema.fromJsonString(Seed);
+/**
+ * Builds the operation that starts an actor from a seed, over the runtime's
+ * SQL, crypto, clock, and outbox, and its job registrations.
+ *
+ * The actor's row, state, and obligations are written in one transaction, so
+ * a refused seed leaves nothing behind. It never overwrites: an actor that
+ * already has a generation row refuses the seed. Obligations are staged
+ * through the turn's own outbox statements under the caller the test runs as,
+ * never a caller from the file, so a seed cannot carry authority. A job
+ * this runner has no executor for is refused, because it could never run.
+ * A seed marking created an actor type that declares no `createdBy` is
+ * refused: that marker stays false for such a type, or declaring the policy
+ * later would treat the seeded actor as already created.
+ */
+export const seedRuntime = (deps) => Effect.fnUntraced(function* ({ ref, caller, seed, }) {
+    if (seed.actor.type !== ref.actor)
+        return yield* Effect.die(new Error(`The seed is of ${seed.actor.type}, not ${ref.actor}: refusing to seed it`));
+    if (seed.created && !deps.createdBy(ref.actor))
+        return yield* Effect.die(new Error(`The seed marks ${ref.actor} created, but ${ref.actor} declares no createdBy: refusing to seed it`));
+    for (const { job } of seed.jobs)
+        if (deps.jobOf(ref.actor, job) === undefined)
+            return yield* Effect.die(new Error(`The seed has job ${job}, which ${ref.actor} does not register`));
+    const sql = yield* SqlClient.SqlClient;
+    const placement = yield* recordedPlacement(ref.actor);
+    if (placement === undefined)
+        return yield* Effect.die(new Error(`Actor ${ref.actor} is not registered`));
+    const key = routingKey({ ref, placement });
+    yield* withTenant(ref.tenant)(sql.withTransaction(Effect.gen(function* () {
+        const [inserted] = yield* sql `
+            INSERT INTO actor_generations (routing_key, tenant_id, actor_type, actor_id, created)
+            VALUES (${key}, ${ref.tenant}, ${ref.actor}, ${ref.id}, ${seed.created})
+            ON CONFLICT DO NOTHING
+            RETURNING created`;
+        if (inserted === undefined)
+            return yield* Effect.die(new Error(`${ref.actor}/${ref.id} already exists: a seed starts an actor, never overwrites one`));
+        const rows = Object.entries(seed.state).map(([name, value]) => [name, JSON.stringify(value)]);
+        if (seed.stateVersion > 0)
+            rows.push([VERSION_KEY, String(seed.stateVersion)]);
+        for (const [name, value] of rows)
+            yield* sql `INSERT INTO actor_state (routing_key, tenant_id, actor_type, actor_id, key, value)
+              VALUES (${key}, ${ref.tenant}, ${ref.actor}, ${ref.id}, ${name}, ${compress(value)})`;
+        const staged = yield* outboxStatements(key, ref, {
+            ...emptyOutbox,
+            intents: seed.intents.map((intent) => ({
+                target: ActorRef.make({
+                    tenant: ref.tenant,
+                    actor: intent.target.actor,
+                    id: intent.target.id,
+                }),
+                command: intent.command,
+                payload: JSON.stringify(intent.payload),
+                caller,
+                due: Due.cases.After.make({ millis: intent.dueInMs }),
+                key: intent.key,
+            })),
+            jobs: seed.jobs.map((job) => ({
+                job: job.job,
+                payload: JSON.stringify(job.payload),
+                version: job.payloadVersion,
+                caller,
+                due: Due.cases.After.make({ millis: job.dueInMs }),
+                key: job.key,
+                capped: deps.jobOf(ref.actor, job.job)?.perActor !== undefined,
+            })),
+        }, databaseTime);
+        for (const statement of staged.statements)
+            yield* statement;
+    })));
+    yield* deps.wake;
+}, (effect) => effect.pipe(Effect.catchIf(SqlError.isSqlError, Effect.die), Effect.provideService(FrameworkClock, deps.clock), Effect.provideService(OutboxRuntime, deps.outbox), Effect.provideService(TenantScope, deps.tenantScope), Effect.provideContext(deps.services)));

package/dist/runtime/payloads/versions.d.ts

@@ -0,0 +1,65 @@
+import { Effect } from "effect";
+import { SqlClient } from "effect/sql";
+import { type PayloadDeclaration } from "../../members/payload.ts";
+/** How long a runtime's writer rows stay live without a refresh, by default. */
+export declare const DEFAULT_WRITER_WINDOW_MS = 120000;
+/** A stored version the deployment could not read, or a removal that would strand one. */
+export interface PayloadProblem {
+    readonly actorType: string;
+    readonly kind: "event" | "job";
+    readonly tag: string;
+    /** What would be stranded, e.g. `version 2 recorded above this chain's current version 1`. */
+    readonly problem: string;
+}
+/** A one-line operator-facing description of a payload problem. */
+export declare const formatPayloadProblem: (problem: PayloadProblem) => string;
+/**
+ * Compares declared chains with the versions the database may hold. A
+ * version recorded above a chain's current version is a rollback past a
+ * schema change. A chain that starts above version `v` can't read values of
+ * `v`: an event version counts as stored until `durable payloads clear` marks
+ * it cleared. Every stored event has a recorded version, because a runtime
+ * records what it writes before it takes a shard and the migration refused
+ * databases that held rows before it. Job versions are read from the
+ * outbox and dead letters directly. `writers` names the actor types whose
+ * turns this deployment runs: an event tag one of them no longer declares is
+ * refused while a subscription still has undelivered events of it.
+ */
+export declare const findPayloadProblems: (declarations: readonly PayloadDeclaration[], writers?: readonly {
+    readonly actorType: string;
+    readonly events: ReadonlyArray<string>;
+}[] | undefined) => Effect.Effect<PayloadProblem[], import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;
+/**
+ * Records the version each written class is written at, and marks every
+ * lower recorded version superseded. Writing a version again clears its
+ * `superseded` and `cleared` marks, since values of it are being stored anew.
+ */
+export declare const recordPayloadVersions: (declarations: readonly PayloadDeclaration[]) => Effect.Effect<void, import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;
+/** Upserts this runtime's writer row for each class it writes, stamped now, in one statement. */
+export declare const refreshWriters: (runtimeId: string, windowMs: number, declarations: readonly PayloadDeclaration[]) => Effect.Effect<void, import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;
+/** Drops a stopping runtime's writer rows, so a clear need not wait out its window. */
+export declare const dropWriters: (runtimeId: string) => Effect.Effect<void, import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;
+/** `durable payloads check`: the startup check for `actors`, read-only. */
+export declare const checkPayloads: (actors: ReadonlyArray<object>) => Effect.Effect<PayloadProblem[], import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;
+/** What `durable payloads clear` found for one superseded event version. */
+export interface ClearResult {
+    readonly actorType: string;
+    readonly tag: string;
+    readonly version: number;
+    /**
+     * `cleared`, or why not: a runtime refreshed a writer row for the version
+     * within its window plus the longest command timeout, or an event of the
+     * version is still stored.
+     */
+    readonly outcome: "cleared" | "writer" | "stored";
+}
+/**
+ * `durable payloads clear`: marks each superseded event version of `actors`
+ * cleared once its retention horizon has passed, no runtime can still write
+ * it, and no event of it remains. The version row is locked first, the
+ * writer rows are read again after the scan, and each statement of the
+ * transaction reads a fresh snapshot, so a writer that registers during the
+ * scan fails the clear instead of racing it. A writer counts as live until
+ * its window and then the longest command timeout have passed.
+ */
+export declare const clearPayloads: (actors: ReadonlyArray<object>) => Effect.Effect<ClearResult[], import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;