@akterjs/sdk 0.0.0-stage → 0.1.0

package/dist/actor/plain-handlers.contract.mjs

@@ -0,0 +1,94 @@
+import { PlainCompiler } from "./plain-compile.contract.mjs";
+import { PlainErrors } from "./plain-error.schema.mjs";
+import { PlainFiles } from "./resource/plain-files.contract.mjs";
+import { Array, Cause, Effect, Exit, Option, Predicate, Record, Result, Schema } from "effect";
+import { Akter } from "@akterjs/effect/contract";
+import { DurableDeferred } from "effect/workflow";
+// src/actor/plain-handlers.contract.ts
+const TimerId = Schema.String.pipe(Schema.brand("TimerId"));
+const notSynchronous = "A plain command, query, create or result handler must return synchronously; do I/O in a job (ADR 0007).";
+const sqlOf = (scope, run) => (strings, ...values) => run(scope.sql(strings, ...values));
+/** What a handler threw: a declared error fails the call, anything else is a defect. */
+const failureOf = (errors, cause) => {
+	const isDeclared = Schema.is(PlainErrors.errorsCodec(errors));
+	return Option.match(Option.liftPredicate(cause, isDeclared), {
+		onNone: () => Effect.die(cause),
+		onSome: Effect.fail
+	});
+};
+const returned = (value) => {
+	if (Predicate.isPromiseLike(value)) return Effect.die(/* @__PURE__ */ new TypeError(notSynchronous));
+	return Effect.succeed(value);
+};
+/** Runs a handler: a declared error it throws fails the call; anything else it throws, or a Promise it returns, is a defect. */
+const settle = (errors, call) => Effect.suspend(() => Result.match(Result.try({
+	catch: (cause) => cause,
+	try: call
+}), {
+	onFailure: (cause) => failureOf(errors, cause),
+	onSuccess: returned
+}));
+const undeclared = (ref, kind) => /* @__PURE__ */ new TypeError(`${ref.actor}.${ref.member} is not a ${kind} Akter.make declared`);
+const addressed = (ref) => {
+	const target = Option.getOrThrowWith(PlainCompiler.commandTargetOf(ref), () => undeclared(ref, "command"));
+	return Option.getOrThrow(PlainCompiler.addressedOf(target.compilation(), target.member));
+};
+const startable = (ref) => {
+	const target = Option.getOrThrowWith(PlainCompiler.jobTargetOf(ref), () => undeclared(ref, "job"));
+	return Option.getOrThrow(PlainCompiler.startableOf(target.compilation(), target.member));
+};
+/** The durable deferred a plain job waits on with `steps.waitFor(name)` and a command fills with `ctx.signal`. */
+const signalNamed = (name) => DurableDeferred.make(name, { success: Schema.Json });
+/** The payload after a target, as `ctx.send(Ledger.commands.credit, key, payload)` passes it. */
+const firstOf = (payload) => Option.getOrUndefined(Array.head(payload));
+const commandContext = ({ run, scope, state, update }) => ({
+	cancel: (timer) => {
+		run(Akter.cancel(TimerId.make(timer)));
+	},
+	files: PlainFiles.filesOf(run),
+	id: () => run(scope.id),
+	key: scope.key,
+	now: () => run(scope.now),
+	principal: scope.principal,
+	schedule: (delay, command, ...payload) => run(Akter.schedule(delay, addressed(command), firstOf(payload))),
+	send: (command, key, ...payload) => {
+		run(Akter.send(addressed(command), key, firstOf(payload)));
+	},
+	signal: (job, name, value) => {
+		run(Akter.signal(signalNamed(name), {
+			job,
+			value
+		}));
+	},
+	sql: sqlOf(scope, run),
+	start: (job, ...payload) => run(Akter.start(startable(job), { input: firstOf(payload) })),
+	state,
+	update
+});
+const migrationsOf = (migrations) => Record.map(migrations, (statements) => (sql) => Effect.forEach(Array.ensure(statements), (text) => sql.unsafe(text), { discard: true }));
+const jobResultOf = (exit) => Exit.match(exit, {
+	onFailure: (cause) => Option.match(Cause.findErrorOption(cause), {
+		onNone: () => ({
+			defect: Cause.pretty(cause),
+			outcome: "defect"
+		}),
+		onSome: (error) => ({
+			error,
+			outcome: "failure"
+		})
+	}),
+	onSuccess: (value) => ({
+		outcome: "success",
+		value
+	})
+});
+const PlainHandlerBridge = {
+	commandContext,
+	failureOf,
+	jobResultOf,
+	migrationsOf,
+	settle,
+	signalNamed,
+	sqlOf
+};
+export { PlainHandlerBridge };

package/dist/actor/plain-implement.contract.d.mts

@@ -0,0 +1,27 @@
+import { Compilation } from "./plain-compile.contract.mjs";
+import { PlainHandlers } from "./plain-handlers.contract.mjs";
+import { PlainApp, PlainImplementation } from "./plain-types.contract.mjs";
+import { Layer, Option } from "effect";
+import { WorkflowEngine } from "effect/workflow";
+type ServedLayer = Layer.Layer<never, never, WorkflowEngine.WorkflowEngine>;
+/** Compiles a plain implementation to the actor's Effect layer and its job layers. */
+declare const implement: (compilation: Compilation, handlers: PlainHandlers) => ServedLayer;
+interface Implemented {
+  readonly actor: Compilation["compiled"]["actor"];
+  readonly layer: ServedLayer;
+}
+/** The Effect actors and layer an app serves, in the form `akter dev`, `akter deploy` and `Akter.serve` take. */
+interface Served {
+  readonly actors: readonly Implemented["actor"][];
+  readonly layer: ServedLayer;
+}
+declare const register: (implementation: PlainImplementation, implemented: Implemented) => void;
+declare const app: (declared: readonly PlainImplementation[]) => Served;
+declare const servedOf: (declared: PlainApp) => Option.Option<Served>;
+export declare const PlainImplement: {
+  readonly app: typeof app;
+  readonly implement: typeof implement;
+  readonly register: typeof register;
+  readonly servedOf: typeof servedOf;
+};
+export type { Served };

package/dist/actor/plain-implement.contract.mjs

@@ -0,0 +1,184 @@
+import { PlainCompiler } from "./plain-compile.contract.mjs";
+import { PlainComputers } from "./resource/plain-computers.contract.mjs";
+import { PlainFiles } from "./resource/plain-files.contract.mjs";
+import { PlainHandlerBridge } from "./plain-handlers.contract.mjs";
+import { bridgeState } from "./standard-schema.schema.mjs";
+import { Array, Effect, Equal, Layer, MutableRef, Option, Record, Schema } from "effect";
+import { Akter } from "@akterjs/effect/contract";
+import { Activity, DurableClock, DurableDeferred } from "effect/workflow";
+// src/actor/plain-implement.contract.ts
+const errorsFor = (compilation, member) => Option.getOrElse(Record.get(compilation.errors, member), () => []);
+/** The context of a handler that may change the actor: commands and result handlers. */
+const changingContext = Effect.fnUntraced(function* changingContext(compilation, state) {
+	const scope = yield* Akter;
+	const context = yield* Effect.context();
+	const run = Effect.runSyncWith(context);
+	return PlainHandlerBridge.commandContext({
+		run,
+		scope,
+		state,
+		update: (patch) => {
+			run(compilation.compiled.actor.update(patch));
+		}
+	});
+});
+/** The context of a handler that only reads. */
+const readingContext = Effect.fnUntraced(function* readingContext() {
+	const scope = yield* Akter;
+	const context = yield* Effect.context();
+	const run = Effect.runSyncWith(context);
+	return {
+		files: PlainFiles.readingFilesOf(run),
+		id: () => run(scope.id),
+		key: scope.key,
+		now: () => run(scope.now),
+		principal: scope.principal,
+		sql: PlainHandlerBridge.sqlOf(scope, run)
+	};
+});
+const commandHandler = ({ compilation, handle, member }) => (state, payload) => Effect.flatMap(changingContext(compilation, state), (ctx) => PlainHandlerBridge.settle(errorsFor(compilation, member), () => handle(ctx, payload)));
+const queryHandler = ({ compilation, handle, member }) => (state, payload) => Effect.flatMap(readingContext(), (reading) => PlainHandlerBridge.settle(errorsFor(compilation, member), () => handle({
+	files: reading.files,
+	key: reading.key,
+	principal: reading.principal,
+	sql: reading.sql,
+	state
+}, payload)));
+/** Whether the actor's `files.authorize` rule allows the call: only `true` does, and an actor without the rule allows none. */
+const allows = (rules, ctx, request) => Option.match(Option.fromUndefinedOr(rules), {
+	onNone: () => Effect.succeed(false),
+	onSome: (rule) => Effect.map(Effect.orDie(PlainHandlerBridge.settle([], () => rule.authorize(ctx, request))), (allowed) => Equal.equals(allowed, true))
+});
+/** The actor's `files.authorize` rule, run as a query: the call is refused unless the rule returns `true`. */
+const filesRule = (rules) => (state, request) => readingContext().pipe(Effect.flatMap((reading) => allows(rules, {
+	files: reading.files,
+	key: reading.key,
+	principal: reading.principal,
+	sql: reading.sql,
+	state
+}, request)), Effect.filterOrFail((allowed) => allowed, () => PlainFiles.denied(request)), Effect.asVoid);
+const createHandler = (handle) => (input) => Effect.flatMap(readingContext(), (ctx) => Effect.orDie(PlainHandlerBridge.settle([], () => handle(ctx, input))));
+const resultHandler = ({ compilation, handle }) => (state, exit, job) => Effect.flatMap(changingContext(compilation, state), (ctx) => Effect.orDie(PlainHandlerBridge.settle([], () => {
+	handle(ctx, PlainHandlerBridge.jobResultOf(exit), { id: job.id });
+})));
+/** Runs `effect` unless the job was suspended, in which case it stays interrupted. */
+const unlessSuspended = (suspended, effect) => Effect.suspend(() => {
+	if (MutableRef.get(suspended)) return Effect.interrupt;
+	return effect;
+});
+const computerOf = (actor, key) => {
+	const { compiled } = Option.getOrThrowWith(PlainCompiler.compilationOf(actor), () => /* @__PURE__ */ new TypeError(`${actor.name} is not an actor Akter.make defined`));
+	return compiled.actor.computer(key);
+};
+/** Runs a step's code with its idempotency key, as the activity named `name`. */
+const keyed = (name, execute) => Effect.flatMap(Activity.idempotencyKey(name), (key) => Effect.promise(() => execute({ key })));
+/** The job's steps as Promises: each runs as a recorded activity, a durable sleep or a durable wait in the workflow. */
+const stepsOf = ({ call, patched, run }) => ({
+	computer: (actor, key) => PlainComputers.computersOf({
+		actor: actor.name,
+		connected: computerOf(actor, key),
+		run: call
+	}),
+	patched,
+	run: (name, execute) => run(Activity.make({
+		execute: keyed(name, execute),
+		name,
+		success: Schema.Json
+	})),
+	sleep: (name, delay) => run(DurableClock.sleep({
+		duration: delay,
+		name
+	})),
+	waitFor: (name) => run(DurableDeferred.await(PlainHandlerBridge.signalNamed(name)))
+});
+const jobWork = ({ handling, input, workflow }) => Effect.gen(function* runPlainJob() {
+	const context = yield* Effect.context();
+	const run = Effect.runPromiseWith(context);
+	const suspended = MutableRef.make(false);
+	const steps = stepsOf({
+		call: run,
+		patched: (name) => Effect.runSyncWith(context)(workflow.patched(name)),
+		run: (effect) => run(Effect.onInterrupt(unlessSuspended(suspended, effect), () => Effect.sync(() => MutableRef.set(suspended, true))))
+	});
+	const value = yield* Effect.catchDefect(Effect.promise(() => handling.handle(input, steps)), (defect) => unlessSuspended(suspended, PlainHandlerBridge.failureOf(errorsFor(handling.compilation, handling.member), defect)));
+	return yield* unlessSuspended(suspended, Effect.succeed(value));
+});
+const jobLayer = (handling) => Option.map(PlainCompiler.startableOf(handling.compilation, handling.member), (workflow) => workflow.toLayer(({ input }) => jobWork({
+	handling,
+	input,
+	workflow
+})));
+const upgradeOf = (compilation, upgrading) => Akter.migrateState(bridgeState({
+	site: {
+		actor: compilation.name,
+		member: "state",
+		part: "from"
+	},
+	validator: upgrading.from
+}).codec, upgrading.upgrade);
+const actorLayer = (compilation, handlers, create) => {
+	if (compilation.compiled.mode === "initial") return compilation.compiled.actor.toLayer(handlers);
+	const handle = Option.getOrThrowWith(create, () => /* @__PURE__ */ new TypeError(`${compilation.name} declares create, so implement needs create`));
+	return compilation.compiled.actor.toLayer({
+		...handlers,
+		create: createHandler(handle)
+	});
+};
+/** Compiles a plain implementation to the actor's Effect layer and its job layers. */
+const implement = (compilation, handlers) => {
+	const actor = actorLayer(compilation, {
+		commands: Record.map(handlers.commands, (handle, member) => commandHandler({
+			compilation,
+			handle,
+			member
+		})),
+		files: { authorize: filesRule(handlers.files) },
+		migrations: PlainHandlerBridge.migrationsOf(handlers.migrations ?? {}),
+		queries: Record.map(handlers.queries ?? {}, (handle, member) => queryHandler({
+			compilation,
+			handle,
+			member
+		})),
+		results: Record.map(handlers.results ?? {}, (handle, member) => resultHandler({
+			compilation,
+			handle,
+			member
+		})),
+		...Option.match(Option.fromUndefinedOr(handlers.state), {
+			onNone: () => ({}),
+			onSome: (upgrading) => ({ state: upgradeOf(compilation, upgrading) })
+		})
+	}, Option.fromUndefinedOr(handlers.create));
+	const jobs = Array.flatMap(Record.toEntries(handlers.jobs ?? {}), ([member, handle]) => Option.toArray(jobLayer({
+		compilation,
+		handle,
+		member
+	})));
+	return Layer.mergeAll(actor, ...jobs);
+};
+const implementations = /* @__PURE__ */ new WeakMap();
+const apps = /* @__PURE__ */ new WeakMap();
+const register = (implementation, implemented) => {
+	implementations.set(implementation, implemented);
+};
+const served = (implemented) => ({
+	actors: Array.map(implemented, (each) => each.actor),
+	layer: Array.match(implemented, {
+		onEmpty: () => Layer.empty,
+		onNonEmpty: (all) => Layer.mergeAll(...Array.map(all, (each) => each.layer))
+	})
+});
+const app = (declared) => {
+	const implemented = Array.map(declared, (implementation) => Option.getOrThrowWith(Option.fromUndefinedOr(implementations.get(implementation)), () => /* @__PURE__ */ new TypeError(`${implementation.actor} was not implemented with implement()`)));
+	const result = served(implemented);
+	apps.set(result, implemented);
+	return result;
+};
+const servedOf = (declared) => Option.map(Option.fromUndefinedOr(apps.get(declared)), served);
+const PlainImplement = {
+	app,
+	implement,
+	register,
+	servedOf
+};
+export { PlainImplement };

package/dist/actor/plain-types.contract.d.mts

@@ -0,0 +1,316 @@
+import { Computers } from "./resource/plain-computers.contract.mjs";
+import { FileAccessOf, FileRulesOf, PlainFileAccess } from "./resource/plain-file-access.contract.mjs";
+import { Files, ReadingFiles } from "./resource/plain-files.contract.mjs";
+import { Delay, Sql, SqlRow, SqlValue } from "./plain-values.contract.mjs";
+import { StandardJSONSchemaV1, StandardSchemaV1 } from "@standard-schema/spec";
+/** A JSON value: what the plain SDK stores, journals and sends (ADR 0015). */
+type Json = null | boolean | number | string | readonly Json[] | {
+  readonly [key: string]: Json;
+};
+/** An actor's state: a JSON object. */
+type StateFields = Readonly<Record<string, Json>>;
+/** A Standard Schema validator that also implements Standard JSON Schema, such as a Zod 4 or ArkType declaration, or Valibot through `toStandardJsonSchema`. */
+interface Validator<Input = unknown, Output = Input> {
+  readonly "~standard": StandardSchemaV1.Props<Input, Output> & StandardJSONSchemaV1.Props<Input, Output>;
+}
+type InputOf<Declaration extends Validator> = NonNullable<Declaration["~standard"]["types"]>["input"];
+type OutputOf<Declaration extends Validator> = NonNullable<Declaration["~standard"]["types"]>["output"];
+type DeclaredInput<Declaration> = Declaration extends Validator ? InputOf<Declaration> : never;
+type DeclaredOutput<Declaration> = Declaration extends Validator ? OutputOf<Declaration> : never;
+/** An error a handler throws and a caller catches by class. `_tag` names it on the wire. */
+type PlainError<Tag extends string> = Error & {
+  readonly _tag: Tag;
+};
+type NoFields = Readonly<Record<string, never>>;
+/** A declared error class: `new OverdrawnError({ balance })`, thrown by a handler and rejected to the caller. */
+type PlainErrorClass<Tag extends string, Input, Output> = (Input extends NoFields ? new () => PlainError<Tag> : new (fields: Input) => PlainError<Tag> & Readonly<Output>) & {
+  readonly _tag: Tag;
+};
+type AnyErrorClass = (abstract new (...fields: never) => Error) & {
+  readonly _tag: string;
+};
+type ErrorInput<Fields> = Fields extends Validator ? InputOf<Fields> : NoFields;
+type ErrorOutput<Fields> = Fields extends Validator ? OutputOf<Fields> : NoFields;
+interface MemberOptions {
+  readonly callers?: readonly string[];
+  readonly errors?: readonly AnyErrorClass[];
+  readonly payload?: Validator;
+  readonly success?: Validator;
+}
+interface JobOptions {
+  readonly errors?: readonly AnyErrorClass[];
+  /** Named changes to the job's code, which `steps.patched` answers by the code that started the job. */
+  readonly patches?: readonly string[];
+  readonly payload: Validator;
+  readonly success?: Validator;
+}
+/** A declared command: it changes the actor and commits with everything it did. */
+interface PlainCommand<Options extends MemberOptions = MemberOptions> {
+  readonly kind: "command";
+  readonly options: Options;
+}
+/** A declared query: it reads the actor and can be subscribed to. */
+interface PlainQuery<Options extends MemberOptions = MemberOptions> {
+  readonly kind: "query";
+  readonly options: Options;
+}
+/** A declared job: durable work a command starts, which runs after the command commits. */
+interface PlainJob<Options extends JobOptions = JobOptions> {
+  readonly kind: "job";
+  readonly options: Options;
+}
+/** What a caller sends: the payload's input, or `undefined` for a member declared without one. */
+type PayloadIn<Options> = Options extends {
+  readonly payload: infer Declaration;
+} ? DeclaredInput<Declaration> : undefined;
+/** What a handler receives: the payload's output, or `undefined` for a member declared without one. */
+type PayloadOut<Options> = Options extends {
+  readonly payload: infer Declaration;
+} ? DeclaredOutput<Declaration> : undefined;
+/** What a caller receives: the success output, or `undefined` for a member declared without one. */
+type SuccessOut<Options> = Options extends {
+  readonly success: infer Declaration extends Validator;
+} ? OutputOf<Declaration> : undefined;
+type ErrorsOf<Options> = Options extends {
+  readonly errors: infer Classes extends readonly AnyErrorClass[];
+} ? InstanceType<Classes[number]> : never;
+type OptionsOf<Declaration> = Declaration extends {
+  readonly options: infer Options;
+} ? Options : never;
+/** The arguments after a target: none when the payload is `undefined`. */
+type PayloadArgs<Payload> = [Payload] extends [undefined] ? [] : [payload: Payload];
+/** The members of a kind an actor declares none of. */
+type NoMembers = Readonly<Record<string, never>>;
+/** The names of the declared members, without the index signature of `NoMembers`. */
+type MemberNames<Members> = keyof { readonly [Member in keyof Members & string as Members[Member] extends never ? never : Member]: Member; };
+interface ActorOptions {
+  readonly callers?: Readonly<Record<string, Validator>>;
+  readonly commands: Readonly<Record<string, PlainCommand>>;
+  readonly create?: Validator;
+  readonly files?: PlainFileAccess;
+  readonly initial?: () => StateFields;
+  readonly jobs?: Readonly<Record<string, PlainJob>>;
+  readonly key: Validator<string, string>;
+  readonly queries?: Readonly<Record<string, PlainQuery>>;
+  readonly state: Validator<StateFields, StateFields>;
+}
+type StateOf<Options extends ActorOptions> = OutputOf<Options["state"]>;
+type KeyOf<Options extends ActorOptions> = OutputOf<Options["key"]>;
+type PrincipalOf<Options extends ActorOptions> = Options extends {
+  readonly callers: infer Callers extends Readonly<Record<string, Validator>>;
+} ? OutputOf<Callers[keyof Callers]> : {
+  readonly id: string;
+};
+type CommandsOf<Options extends ActorOptions> = Options["commands"];
+type QueriesOf<Options extends ActorOptions> = Options extends {
+  readonly queries: infer Queries extends Readonly<Record<string, PlainQuery>>;
+} ? Queries : NoMembers;
+type JobsOf<Options extends ActorOptions> = Options extends {
+  readonly jobs: infer Jobs extends Readonly<Record<string, PlainJob>>;
+} ? Jobs : NoMembers;
+type CreateOf<Options extends ActorOptions> = Options extends {
+  readonly create: infer Declaration;
+} ? Declaration : never;
+/** Names one command of one actor, for `ctx.schedule`, `ctx.send` and history. */
+interface CommandRef<Actor extends string = string, Key = unknown, Payload = unknown> {
+  readonly "~key"?: Key;
+  readonly "~payload"?: Payload;
+  readonly actor: Actor;
+  readonly member: string;
+}
+/** Names one job of one actor, for `ctx.start`. */
+interface JobRef<Actor extends string = string, Payload = unknown> {
+  readonly "~payload"?: Payload;
+  readonly actor: Actor;
+  readonly member: string;
+}
+interface CreateContext<Options extends ActorOptions> {
+  readonly id: () => string;
+  readonly key: KeyOf<Options>;
+  readonly now: () => number;
+  readonly principal: PrincipalOf<Options>;
+  readonly sql: Sql;
+}
+interface QueryContext<Options extends ActorOptions> {
+  readonly files: ReadingFiles;
+  readonly key: KeyOf<Options>;
+  readonly principal: PrincipalOf<Options>;
+  readonly sql: Sql;
+  readonly state: StateOf<Options>;
+}
+interface CommandContext<Name extends string, Options extends ActorOptions> extends QueryContext<Options> {
+  readonly cancel: (timer: string) => void;
+  readonly files: Files;
+  readonly id: () => string;
+  readonly now: () => number;
+  readonly schedule: <Payload>(delay: Delay, command: CommandRef<Name, KeyOf<Options>, Payload>, ...payload: PayloadArgs<Payload>) => string;
+  readonly send: <Key, Payload>(command: CommandRef<string, Key, Payload>, key: Key, ...payload: PayloadArgs<Payload>) => void;
+  /**
+   * Signals one of this actor's jobs waiting in `steps.waitFor(name)` with `value`, such as an approval. The signal is
+   * stored with the command and wakes the job once the command commits: a command that throws signals nothing, and a
+   * retried command signals once. A job that has finished, was never started or already has that signal ignores it.
+   * `job` is the id `ctx.start` returned; signal another actor's job by sending that actor a command.
+   */
+  readonly signal: (job: string, name: string, value: Json) => void;
+  readonly start: <Payload>(job: JobRef<Name, Payload>, ...payload: PayloadArgs<Payload>) => string;
+  readonly update: (patch: Partial<StateOf<Options>>) => void;
+}
+/** Why a step's value is not JSON, as the type error names it, such as `NotJson<"a Date">`. */
+interface NotJson<What extends string> {
+  readonly "~notJson": `${What} is not JSON; a step's value is recorded as JSON`;
+}
+/**
+ * `Value` when it is JSON: a JSON value, or an interface or type of one. Anything else becomes a `NotJson` naming the
+ * part that isn't, such as a function or method, a `Date`, a `bigint`, a symbol or an `undefined` field.
+ */
+type JsonSafe<Value> = Value extends Json ? Value : Value extends bigint ? NotJson<"a bigint"> : Value extends symbol ? NotJson<"a symbol"> : Value extends undefined ? NotJson<"undefined"> : Value extends ((...args: never) => void) ? NotJson<"a function"> : Value extends Date ? NotJson<"a Date"> : Value extends object ? { readonly [Key in keyof Value]: JsonSafe<Value[Key]>; } : NotJson<"this value">;
+/** The step `steps.run` is running. */
+interface JobStep {
+  /** The step's idempotency key: the same each time this job runs this step, and distinct from every other step. Pass it as an exec step's `key`. */
+  readonly key: string;
+}
+/** A job's steps. Each completed step is recorded, so a job that resumes after a restart does not repeat it. */
+interface JobSteps {
+  /** The computers of `actor` at `key`, such as `steps.computer(Task, key)`. Call them inside `steps.run`. */
+  readonly computer: <Name extends string, Options extends ActorOptions>(actor: PlainActor<Name, Options>, key: KeyOf<Options>) => Computers;
+  /** Whether the code that started this job declared the patch `name`, for the job's whole run. */
+  readonly patched: (name: string) => boolean;
+  /** Runs `execute` once and records its value, which must be JSON (`JsonSafe`); a resumed job reads it back. */
+  readonly run: <Value>(name: string, execute: (step: JobStep) => Promise<Value & JsonSafe<Value>>) => Promise<Value>;
+  readonly sleep: (name: string, delay: Delay) => Promise<void>;
+  /** Waits until a command signals this job with `ctx.signal(id, name, value)`, and returns the value, recorded. */
+  readonly waitFor: (name: string) => Promise<Json>;
+}
+/** The job a result belongs to: `id` is the id `ctx.start` returned when the job was started. */
+interface FinishedJob {
+  readonly id: string;
+}
+/** How a job ended, delivered to the actor's result handler. */
+type JobResult<Value, Failure> = {
+  readonly outcome: "defect";
+  readonly defect: string;
+} | {
+  readonly outcome: "failure";
+  readonly error: Failure;
+} | {
+  readonly outcome: "success";
+  readonly value: Value;
+};
+/** A command or query handler: it returns the success input, or nothing for a member declared without one. */
+type HandlerOf<Context, Options> = Options extends {
+  readonly success: infer Declaration extends Validator;
+} ? (ctx: Context, payload: PayloadOut<Options>) => InputOf<Declaration> : (ctx: Context, payload: PayloadOut<Options>) => void;
+type JobHandlerOf<Options> = Options extends {
+  readonly success: infer Declaration extends Validator;
+} ? (payload: PayloadOut<Options>, steps: JobSteps) => Promise<InputOf<Declaration>> : (payload: PayloadOut<Options>, steps: JobSteps) => Promise<void>;
+type CommandHandlers<Name extends string, Options extends ActorOptions> = { readonly [Member in MemberNames<CommandsOf<Options>>]: HandlerOf<CommandContext<Name, Options>, OptionsOf<CommandsOf<Options>[Member]>>; };
+type QueryHandlers<Options extends ActorOptions> = { readonly [Member in MemberNames<QueriesOf<Options>>]: HandlerOf<QueryContext<Options>, OptionsOf<QueriesOf<Options>[Member]>>; };
+type JobHandlers<Options extends ActorOptions> = { readonly [Member in MemberNames<JobsOf<Options>>]: JobHandlerOf<OptionsOf<JobsOf<Options>[Member]>>; };
+type ResultHandlers<Name extends string, Options extends ActorOptions> = { readonly [Member in MemberNames<JobsOf<Options>>]: (ctx: CommandContext<Name, Options>, result: JobResult<SuccessOut<OptionsOf<JobsOf<Options>[Member]>>, ErrorsOf<OptionsOf<JobsOf<Options>[Member]>>>, job: FinishedJob) => void; };
+/** Reads state stored under an older declaration and returns the current one. */
+interface StateUpgrade<State> {
+  readonly from: Validator<StateFields, StateFields>;
+  readonly upgrade: (stored: never) => State;
+}
+/** SQL statements per migration number. Each runs once, in order, when the actor first opens after a deploy. */
+type Migrations = Readonly<Record<number, string | readonly string[]>>;
+type Implementation<Name extends string, Options extends ActorOptions> = {
+  readonly commands: CommandHandlers<Name, Options>;
+  readonly migrations?: Migrations;
+  readonly state?: StateUpgrade<StateOf<Options>>;
+} & ([MemberNames<QueriesOf<Options>>] extends [never] ? unknown : {
+  readonly queries: QueryHandlers<Options>;
+}) & ([MemberNames<JobsOf<Options>>] extends [never] ? unknown : {
+  readonly jobs: JobHandlers<Options>;
+  readonly results: ResultHandlers<Name, Options>;
+}) & ([CreateOf<Options>] extends [never] ? unknown : {
+  readonly create: (ctx: CreateContext<Options>, input: DeclaredOutput<CreateOf<Options>>) => StateOf<Options>;
+}) & FileRulesOf<Options, QueryContext<Options>>;
+/** An actor's handlers, ready to serve. Pass it to `Akter.app`. */
+interface PlainImplementation<Name extends string = string> {
+  readonly actor: Name;
+}
+/** A JSON Schema document. */
+type JsonDocument = Readonly<Record<string, Json>>;
+/** The JSON Schema documents of one declaration, kept for history and devtools. */
+interface Documents {
+  readonly input: JsonDocument;
+  readonly output: JsonDocument;
+}
+interface MemberContract {
+  /** The caller kinds the member admits; absent when it admits every kind the actor declares. */
+  readonly callers?: readonly string[];
+  readonly errors: Readonly<Record<string, Documents>>;
+  /** Absent when the member takes no payload. */
+  readonly payload?: Documents;
+  /** Absent when the member replies with nothing. */
+  readonly success?: Documents;
+}
+/** An actor's declarations as JSON Schema, captured when the actor is defined. */
+interface ActorContract {
+  readonly callers: Readonly<Record<string, Documents>>;
+  readonly commands: Readonly<Record<string, MemberContract>>;
+  /** Absent when the actor starts from `initial`. */
+  readonly create?: Documents;
+  readonly jobs: Readonly<Record<string, MemberContract>>;
+  readonly key: Documents;
+  readonly name: string;
+  readonly queries: Readonly<Record<string, MemberContract>>;
+  readonly state: Documents;
+}
+/** A defined actor: its name, references to its commands and jobs, its contract, and `implement`. */
+interface PlainActor<Name extends string = string, Options extends ActorOptions = ActorOptions> {
+  readonly "~options"?: Options;
+  readonly commands: { readonly [Member in MemberNames<CommandsOf<Options>>]: CommandRef<Name, KeyOf<Options>, PayloadIn<OptionsOf<CommandsOf<Options>[Member]>>>; };
+  readonly contract: ActorContract;
+  readonly implement: (implementation: Implementation<Name, Options>) => PlainImplementation<Name>;
+  readonly jobs: { readonly [Member in MemberNames<JobsOf<Options>>]: JobRef<Name, PayloadIn<OptionsOf<JobsOf<Options>[Member]>>>; };
+  readonly name: Name;
+}
+/** The module `akter dev` and `akter deploy` load: `export const app = Akter.app([...])`. */
+interface PlainApp {
+  readonly actors: readonly object[];
+  readonly layer: object;
+}
+interface PlainAkter {
+  /** The principal another actor calls with: its name, key and id. Declare it as the `actor` caller to accept `ctx.send`. */
+  readonly ActorPrincipal: Validator<{
+    readonly actor: string;
+    readonly id: string;
+    readonly key: string;
+  }, {
+    readonly actor: string;
+    readonly id: string;
+    readonly key: string;
+  }>;
+  /** The default principal of a `user` caller: an id. */
+  readonly Principal: Validator<{
+    readonly id: string;
+  }, {
+    readonly id: string;
+  }>;
+  /** Declares an app from implemented actors. */
+  readonly app: (implementations: readonly PlainImplementation[]) => PlainApp;
+  /** Declares a command. */
+  readonly command: <const Options extends MemberOptions = MemberOptions>(options?: Options) => PlainCommand<Options>;
+  /** Declares an error class. Its fields, if any, are a Standard validator of an object. */
+  readonly error: <const Tag extends string, Fields extends Validator | undefined = undefined>(tag: Tag, fields?: Fields) => PlainErrorClass<Tag, ErrorInput<Fields>, ErrorOutput<Fields>>;
+  /** Declares which caller kinds may make file calls: `files: Akter.fileAccess({ callers: ["member"] })`. */
+  readonly fileAccess: FileAccessOf;
+  /** Declares a job. */
+  readonly job: <const Options extends JobOptions>(options: Options) => PlainJob<Options>;
+  /** Defines an actor. Refuses a declaration it cannot store as JSON with a PlainDefinitionError. */
+  readonly make: <const Name extends string, const Options extends ActorOptions>(name: Name, options: Options) => PlainActor<Name, Options>;
+  /** Declares a query. */
+  readonly query: <const Options extends MemberOptions = MemberOptions>(options?: Options) => PlainQuery<Options>;
+}
+/** What a definition throws for a declaration the plain SDK refuses (ADR 0015). */
+interface PlainDefinitionFailure extends Error {
+  readonly _tag: "PlainDefinitionError";
+  readonly actor: string;
+  readonly member: string;
+  /** Which part of the member was refused, such as `payload`, `state` or `principal`. */
+  readonly part: string;
+  readonly reasons: readonly string[];
+}
+export type { ActorContract, ActorOptions, AnyErrorClass, CommandContext, CommandRef, CreateContext, CreateOf, DeclaredInput, DeclaredOutput, Delay, Documents, ErrorInput, ErrorOutput, ErrorsOf, FinishedJob, Implementation, InputOf, JobOptions, JobRef, JobResult, JobStep, JobSteps, Json, JsonDocument, KeyOf, MemberContract, MemberNames, MemberOptions, Migrations, OptionsOf, OutputOf, PayloadArgs, PayloadIn, PayloadOut, PlainActor, PlainAkter, PlainApp, PlainCommand, PlainDefinitionFailure, PlainError, PlainErrorClass, PlainImplementation, PlainJob, PlainQuery, PrincipalOf, QueriesOf, QueryContext, Sql, SqlRow, SqlValue, StateFields, StateOf, StateUpgrade, SuccessOut, Validator };

package/dist/actor/plain-types.contract.mjs

@@ -0,0 +1 @@
+export {};

package/dist/actor/plain-values.contract.d.mts

@@ -0,0 +1,11 @@
+/** Values a plain handler hands the engine: SQL against its own database, and delays for timers. */
+/** A value bound into SQL. */
+type SqlValue = string | number | boolean | null | Uint8Array | bigint;
+/** One row a read returns, by column name. */
+type SqlRow = Readonly<Record<string, SqlValue>>;
+/** The actor's own SQLite database, as a tagged template that runs now and returns the rows. */
+type Sql = (strings: TemplateStringsArray, ...values: readonly SqlValue[]) => readonly SqlRow[];
+type DelayUnit = "day" | "days" | "hour" | "hours" | "milli" | "millis" | "minute" | "minutes" | "second" | "seconds" | "week" | "weeks";
+/** A delay in milliseconds, or text such as `"5 minutes"`. */
+type Delay = number | `${number} ${DelayUnit}`;
+export type { Delay, Sql, SqlRow, SqlValue };

package/dist/actor/plain-values.contract.mjs

@@ -0,0 +1 @@
+export {};