@akterjs/effect 0.0.0-stage → 0.1.0

package/src/contract/command/command.contract.ts

@@ -0,0 +1,334 @@
+import {
+  Array as Arr,
+  Context,
+  Duration,
+  Effect,
+  Option,
+  Record as Rec,
+  Schema,
+  SchemaTransformation,
+  Struct,
+  pipe,
+} from "effect";
+import type { Exit } from "effect";
+import { Workflow } from "effect/workflow";
+
+import { carrying, patchedOf, patchesKey, withPatches } from "#src/contract/job/job-patches.contract";
+import { ReservedPayloadFieldError } from "#src/contract/job/reserved-payload-field.errors";
+
+type PlainSchema = Schema.Top & {
+  readonly DecodingServices: never;
+  readonly EncodingServices: never;
+};
+
+type PlainFields = Readonly<Record<PropertyKey, PlainSchema>>;
+
+type Declared = PlainFields | PlainSchema;
+
+type DeclaredSchema<Input extends Declared> = Input extends PlainFields ? Schema.Struct<Input> : Input;
+
+interface Command<
+  Payload extends PlainSchema,
+  Success extends PlainSchema,
+  Failure extends PlainSchema,
+  Kinds extends string = string,
+> {
+  readonly callers: Option.Option<readonly Kinds[]>;
+  readonly error: Failure;
+  readonly payload: Payload;
+  readonly success: Success;
+}
+
+interface Query<
+  Payload extends PlainSchema,
+  Success extends PlainSchema,
+  Failure extends PlainSchema,
+  Kinds extends string = string,
+> extends Command<Payload, Success, Failure, Kinds> {
+  /** How old an answer may be when no `atLeast` asks for newer; none means every answer is fresh. */
+  readonly staleFor: Option.Option<Duration.Duration>;
+}
+
+type AnyCommand = Command<PlainSchema, PlainSchema, PlainSchema>;
+
+type AnyQuery = Query<PlainSchema, PlainSchema, PlainSchema>;
+
+interface DeclarationOptions {
+  readonly callers?: readonly string[];
+  readonly error?: PlainSchema;
+  readonly payload?: Declared;
+  readonly success?: PlainSchema;
+}
+
+interface QueryOptions extends DeclarationOptions {
+  /**
+   * How old an answer to this query may be. A read is at most `staleFor` old, and never older than the version the
+   * caller's `atLeast` names, so a caller reads its own writes. An engine may always answer fresher. Without it, every
+   * answer is fresh.
+   */
+  readonly staleFor?: Duration.Input;
+}
+
+type PayloadOf<Options extends DeclarationOptions> = Options extends { readonly payload: infer Input extends Declared }
+  ? DeclaredSchema<Input>
+  : Schema.Void;
+
+type SuccessOf<Options extends DeclarationOptions> = Options extends {
+  readonly success: infer Success extends PlainSchema;
+}
+  ? Success
+  : Schema.Void;
+
+type ErrorOf<Options extends DeclarationOptions> = Options extends { readonly error: infer Failure extends PlainSchema }
+  ? Failure
+  : Schema.Never;
+
+type KindsOf<Options extends DeclarationOptions> = Options extends {
+  readonly callers: readonly (infer Kinds extends string)[];
+}
+  ? Kinds
+  : never;
+
+function declaredSchema<Input extends Declared>(input: Input): DeclaredSchema<Input>;
+function declaredSchema(input: Declared): PlainSchema {
+  if (Schema.isSchema(input)) {
+    return input;
+  }
+
+  return Schema.Struct(input);
+}
+
+const payloadSchema = (options: DeclarationOptions): PlainSchema =>
+  pipe(
+    Option.fromNullishOr(options.payload),
+    Option.match({ onNone: (): PlainSchema => Schema.Void, onSome: (input): PlainSchema => declaredSchema(input) }),
+  );
+
+function command<const Options extends DeclarationOptions>(
+  options?: Options,
+): Command<PayloadOf<Options>, SuccessOf<Options>, ErrorOf<Options>, KindsOf<Options>>;
+function command(options: DeclarationOptions = {}): AnyCommand {
+  return {
+    callers: Option.fromNullishOr(options.callers),
+    error: options.error ?? Schema.Never,
+    payload: payloadSchema(options),
+    success: options.success ?? Schema.Void,
+  };
+}
+
+function query<const Options extends QueryOptions>(
+  options?: Options,
+): Query<PayloadOf<Options>, SuccessOf<Options>, ErrorOf<Options>, KindsOf<Options>>;
+function query(options: QueryOptions = {}): AnyQuery {
+  return {
+    ...command(options),
+    staleFor: Option.map(Option.fromNullishOr(options.staleFor), Duration.fromInputUnsafe),
+  };
+}
+
+interface JobOptions {
+  readonly error?: PlainSchema;
+  readonly payload: PlainFields;
+  /**
+   * Named changes to the job's code. A job started while its contract declares a patch sees it with `Akter.patched`
+   * for its whole run; a job started before the patch existed doesn't, even after a deploy adds it.
+   */
+  readonly patches?: readonly string[];
+  readonly success?: PlainSchema;
+}
+
+interface Job<
+  Fields extends PlainFields,
+  Success extends PlainSchema,
+  Failure extends PlainSchema,
+  Patch extends string = never,
+> {
+  readonly error: Failure;
+  readonly patches: readonly Patch[];
+  readonly payload: Fields;
+  readonly success: Success;
+}
+
+/**
+ * How the host reads and writes a job's payload and result. The host reads only the decoders and `encodeResult`
+ * (host interface item 2); `startedPayload` is the bundle's own, which `Akter.start` encodes with.
+ */
+interface JobCodecs {
+  readonly decodePayload: (text: string) => Effect.Effect<unknown, Schema.SchemaError>;
+  readonly decodeResult: (text: string) => Effect.Effect<Exit.Exit<unknown, unknown>, Schema.SchemaError>;
+  readonly encodeResult: (exit: Exit.Exit<unknown, unknown>) => Effect.Effect<string, Schema.SchemaError>;
+  /** The declared payload, encoded as the journal keeps it: with the patches the job declares, when it declares any. */
+  readonly startedPayload?: Schema.Codec<unknown, string>;
+}
+
+type AnyJob = Job<PlainFields, PlainSchema, PlainSchema, string>;
+
+type PatchesOf<Options extends JobOptions> = Options extends {
+  readonly patches: readonly (infer Patch extends string)[];
+}
+  ? Patch
+  : never;
+
+type Jobs = Readonly<Record<string, AnyJob>>;
+
+type NoJobs = Readonly<Record<string, never>>;
+
+type JobWorkflow<Tag extends string, Declaring extends AnyJob> = Workflow.Workflow<
+  Tag,
+  Schema.Struct<Declaring["payload"]>,
+  Declaring["success"],
+  Declaring["error"]
+> & {
+  /** The patches the job's contract declares now. */
+  readonly patches: Declaring["patches"];
+  /**
+   * Inside the job's run: whether the code that started this run declared `name`. Gate a change to the job's code
+   * with it while jobs started before the change are still in flight.
+   */
+  readonly patched: (name: Declaring["patches"][number]) => Effect.Effect<boolean>;
+};
+
+type ActorJobs<Name extends string, Declaring extends Jobs> = {
+  readonly [Member in keyof Declaring & string]: JobWorkflow<`${Name}/${Member}`, Declaring[Member]>;
+};
+
+interface StartableJob {
+  readonly _tag: string;
+  readonly annotations: Context.Context<never>;
+  readonly payloadSchema: PlainSchema;
+}
+
+interface Tagging {
+  readonly actor: string;
+  readonly member: string;
+}
+
+interface DeclaredJobs<Name extends string, Declaring extends Jobs> {
+  readonly jobs: Declaring;
+  readonly name: Name;
+}
+
+const JobCodecsOf = Context.Reference<Option.Option<JobCodecs>>(
+  "@akterjs/effect/contract/command/command.contract/JobCodecsOf",
+  { defaultValue: Option.none },
+);
+
+function job<const Options extends JobOptions>(
+  options: Options,
+): Job<Options["payload"], SuccessOf<Options>, ErrorOf<Options>, PatchesOf<Options>>;
+function job(options: JobOptions): AnyJob {
+  return {
+    error: options.error ?? Schema.Never,
+    patches: options.patches ?? [],
+    payload: options.payload,
+    success: options.success ?? Schema.Void,
+  };
+}
+
+const jobTag = ({ actor, member }: Tagging): string => `${actor}/${member}`;
+
+const jobResult = ({
+  error,
+  success,
+}: Pick<AnyJob, "error" | "success">): Schema.Exit<PlainSchema, PlainSchema, Schema.Defect> =>
+  Schema.Exit(success, error, Schema.Defect());
+
+/**
+ * A job's payload as its journal keeps it: the declared fields, plus the patches the starting code declared under
+ * `patchesKey` when it declared any. Code that predates patches ignores the extra key, so a rollback still reads it.
+ */
+const jobCodecs = (declared: AnyJob): JobCodecs => {
+  const fields = Schema.Struct(declared.payload);
+  const stored = Schema.Struct({ ...declared.payload, [patchesKey]: Schema.optionalKey(Schema.Array(Schema.String)) });
+  const result = Schema.fromJsonString(Schema.toCodecJson(jobResult(declared)));
+  const decodeStored = Schema.decodeEffect(Schema.fromJsonString(Schema.toCodecJson(stored)));
+
+  const withDeclaredPatches = (payload: typeof fields.Encoded): typeof stored.Encoded => {
+    if (Arr.isReadonlyArrayEmpty(declared.patches)) {
+      return payload;
+    }
+
+    return { ...payload, [patchesKey]: declared.patches };
+  };
+
+  // Between the encoded forms: the declared fields encode as they always have, and the patches ride beside them.
+  const started = Schema.toEncoded(stored).pipe(
+    Schema.decodeTo(
+      fields,
+      SchemaTransformation.transform({
+        decode: (payload) => Struct.omit(payload, [patchesKey]),
+        encode: withDeclaredPatches,
+      }),
+    ),
+  );
+
+  return {
+    decodePayload: (text) =>
+      Effect.map(decodeStored(text), (payload) =>
+        carrying({ fields: Struct.omit(payload, [patchesKey]), patches: payload[patchesKey] }),
+      ),
+    decodeResult: Schema.decodeEffect(result),
+    encodeResult: Schema.encodeEffect(result),
+    startedPayload: Schema.fromJsonString(Schema.toCodecJson(started)),
+  };
+};
+
+const workflowOf = (name: string, member: string, declared: AnyJob): JobWorkflow<string, AnyJob> => {
+  // The stored payload keeps the job's patches under `patchesKey`, so a declared field of that name would collide.
+  if (Rec.has(declared.payload, patchesKey)) {
+    throw ReservedPayloadFieldError.make({ field: patchesKey, job: jobTag({ actor: name, member }) });
+  }
+
+  const annotations = Context.make(JobCodecsOf, Option.some(jobCodecs(declared)));
+
+  const made = Workflow.make(jobTag({ actor: name, member }), {
+    annotations,
+    error: declared.error,
+    idempotencyKey: () => jobTag({ actor: name, member }),
+    payload: declared.payload,
+    success: declared.success,
+  });
+
+  const register = made.toLayer.bind(made);
+
+  // The job's run sees the patches its start declared (`patched`); the rest of the Workflow is Effect's own.
+  const toLayer: typeof made.toLayer = (execute) => register(withPatches(execute));
+
+  return Object.assign(made, {
+    patched: patchedOf({ patches: declared.patches, tag: jobTag({ actor: name, member }) }),
+    patches: declared.patches,
+    toLayer,
+  });
+};
+
+function jobsOf<Name extends string, Declaring extends Jobs>(
+  declaring: DeclaredJobs<Name, Declaring>,
+): ActorJobs<Name, Declaring>;
+function jobsOf({ jobs, name }: DeclaredJobs<string, Jobs>): Readonly<Record<string, JobWorkflow<string, AnyJob>>> {
+  return Rec.map(jobs, (declared, member) => workflowOf(name, member, declared));
+}
+
+export { JobCodecsOf, command, declaredSchema, job, jobCodecs, jobResult, jobTag, jobsOf, query };
+
+export type {
+  ActorJobs,
+  AnyCommand,
+  AnyJob,
+  AnyQuery,
+  Command,
+  Declared,
+  DeclaredSchema,
+  DeclarationOptions,
+  Job,
+  JobOptions,
+  JobCodecs,
+  JobWorkflow,
+  Jobs,
+  NoJobs,
+  PatchesOf,
+  PlainFields,
+  PlainSchema,
+  Query,
+  QueryOptions,
+  StartableJob,
+};

package/src/contract/command/outbox-id.pure.ts

@@ -0,0 +1,25 @@
+import { String as Str } from "effect";
+
+import type { OutboxMessage } from "./outbox.schema.js";
+
+const outboxPrefix = "outbox:";
+
+const outboxCommandId = (id: string): string => `${outboxPrefix}${id}`;
+
+const isOutboxCommandId: (commandId: string) => boolean = Str.startsWith(outboxPrefix);
+
+const mintedIdOf = (commandId: string): string => {
+  if (isOutboxCommandId(commandId)) {
+    return Str.slice(outboxPrefix.length)(commandId);
+  }
+
+  return commandId;
+};
+
+interface Unsent extends Omit<OutboxMessage, "commandId"> {
+  readonly id: string;
+}
+
+const outboxMessage = ({ id, ...unsent }: Unsent): OutboxMessage => ({ ...unsent, commandId: outboxCommandId(id) });
+
+export { isOutboxCommandId, mintedIdOf, outboxCommandId, outboxMessage };

package/src/contract/command/outbox.schema.ts

@@ -0,0 +1,11 @@
+import { Schema } from "effect";
+
+export const OutboxMessage = Schema.Struct({
+  actor: Schema.String,
+  commandId: Schema.String,
+  key: Schema.String,
+  member: Schema.String,
+  payload: Schema.String,
+});
+
+export type OutboxMessage = typeof OutboxMessage.Type;

package/src/contract/command/timer.schema.ts

@@ -0,0 +1,21 @@
+import { Schema } from "effect";
+
+export const TimerId = Schema.String.pipe(Schema.brand("TimerId"));
+
+export type TimerId = typeof TimerId.Type;
+
+export const ScheduledTimer = Schema.Struct({
+  after: Schema.Duration,
+  command: Schema.String,
+  id: TimerId,
+  payload: Schema.String,
+});
+
+export type ScheduledTimer = typeof ScheduledTimer.Type;
+
+export const TimerChanges = Schema.Struct({
+  cancelled: Schema.Array(TimerId),
+  scheduled: Schema.Array(ScheduledTimer),
+});
+
+export type TimerChanges = typeof TimerChanges.Type;

package/src/contract/computer/checkpoint-expired.errors.ts

@@ -0,0 +1,12 @@
+import { Schema } from "effect";
+
+/**
+ * The computer's saved checkpoint can no longer be forked: Archil keeps only the current session's checkpoint and
+ * the one before it. Resume the computer to take a new one, or fork without it.
+ */
+export class CheckpointExpiredError extends Schema.TaggedError<
+  CheckpointExpiredError,
+  { readonly brand: unique symbol }
+>()("CheckpointExpiredError", {
+  computer: Schema.String,
+}) {}

package/src/contract/computer/computer-client-failure.contract.ts

@@ -0,0 +1,27 @@
+import type { ActorUnavailableError } from "#src/contract/client/actor-unavailable.errors";
+import type { CallerNotAllowedError } from "#src/contract/caller/caller-not-allowed.errors";
+import type { UnauthenticatedError } from "#src/contract/caller/unauthenticated.errors";
+import type { InvalidRequestError } from "#src/contract/client/invalid-request.errors";
+import type { ComputerHeldError } from "./computer-held.errors.js";
+import type { ComputerLimitError } from "./computer-limit.errors.js";
+import type { ComputerLostError } from "./computer-lost.errors.js";
+import type { ComputerNotFoundError } from "./computer-not-found.errors.js";
+import type { ComputersUnavailableError } from "./computers-unavailable.errors.js";
+
+/**
+ * What a computer client can fail with. A network client adds the caller's refusals, `CallerNotAllowedError` and
+ * `UnauthenticatedError`; a host's own client never refuses its caller. A request past the exec limits is an
+ * `InvalidRequestError`.
+ */
+type ComputerClientFailure =
+  | ActorUnavailableError
+  | CallerNotAllowedError
+  | ComputerHeldError
+  | ComputerLimitError
+  | ComputerLostError
+  | ComputerNotFoundError
+  | ComputersUnavailableError
+  | InvalidRequestError
+  | UnauthenticatedError;
+
+export type { ComputerClientFailure };

package/src/contract/computer/computer-client.adapter.ts

@@ -0,0 +1,110 @@
+import { Array as Arr, Context, Effect, Option, Schema } from "effect";
+
+import type { ActorDefinition, Decoded } from "#src/contract/actor/actor.contract";
+import { InvalidRequestError } from "#src/contract/client/invalid-request.errors";
+import type {
+  ActorComputers,
+  ComputerAddress,
+  ComputerClient,
+  ComputerClientFailure,
+} from "./computer-client.contract.js";
+import { ComputerSpec, ExecRequest } from "./computer.schema.js";
+import type { ComputerLogLine, ComputerLogPage } from "./computer.schema.js";
+import { ComputersUnavailableError } from "./computers-unavailable.errors.js";
+import { SecretUnavailableError } from "#src/contract/secret/secret-unavailable.errors";
+import { step } from "./step/computer-step.contract.js";
+import { StepRequest } from "./step/computer-step.schema.js";
+
+interface ComputerClientSource {
+  readonly definition: ActorDefinition;
+  readonly name: string;
+}
+
+type ComputerClientOf<Definition extends ActorDefinition> = (
+  key: Definition["key"]["Type"],
+) => Effect.Effect<ActorComputers, ComputersUnavailableError | InvalidRequestError>;
+
+const checked = <Checked extends Schema.Decoder<unknown>>(
+  schema: Checked,
+  actor: string,
+): ((value: Checked["Type"]) => Effect.Effect<Checked["Type"], InvalidRequestError>) => {
+  const decode = Schema.decodeUnknownEffect(schema);
+
+  return (value) =>
+    Effect.mapError(decode(value), (invalid) => InvalidRequestError.make({ actor, message: invalid.message }));
+};
+
+/** A spec binds only secrets the actor declares, so a computer never gets a credential its actor may not read. */
+const declared =
+  ({ definition, name }: ComputerClientSource) =>
+  (spec: ComputerSpec): Effect.Effect<ComputerSpec, SecretUnavailableError> => {
+    const undeclared = Arr.findFirst(spec.secrets ?? [], ({ secret }) => !Arr.contains(definition.secrets, secret));
+
+    return Option.match(undeclared, {
+      onNone: () => Effect.succeed(spec),
+      onSome: ({ secret }) => Effect.fail(SecretUnavailableError.make({ actor: name, reason: "undeclared", secret })),
+    });
+  };
+
+/**
+ * Checks every spec and exec request against the contract, so an engine never sees one past the limits, and every
+ * secret a spec binds against the actor's declaration.
+ */
+const bounded = (client: ComputerClient, source: ComputerClientSource): ActorComputers => {
+  const spec = checked(ComputerSpec, source.name);
+  const request = checked(ExecRequest, source.name);
+  const allowed = declared(source);
+  const stepRequest = checked(StepRequest, source.name);
+
+  const checkedClient: ComputerClient = {
+    ...client,
+    ensure: (wanted) => Effect.flatMap(Effect.flatMap(spec(wanted), allowed), client.ensure),
+    exec: (computer, wanted) => Effect.flatMap(request(wanted), (valid) => client.exec(computer, valid)),
+  };
+
+  return {
+    ...checkedClient,
+    step: (computer, wanted) =>
+      Effect.flatMap(stepRequest(wanted), (valid) => step({ client: checkedClient, computer, request: valid })),
+  };
+};
+
+export class ActorComputerClients extends Context.Service<
+  ActorComputerClients,
+  {
+    readonly connect: (address: ComputerAddress) => ComputerClient;
+    /** A page of one computer's log, read from outside the actor (`<Actor>/computer/logs`). */
+    readonly logs: (
+      address: ComputerAddress,
+      computer: string,
+      page: ComputerLogPage,
+    ) => Effect.Effect<readonly ComputerLogLine[], ComputerClientFailure>;
+  }
+>()("@akterjs/effect/contract/computer/computer-client.adapter/ActorComputerClients") {
+  public static clientOf<Definition extends ActorDefinition>(
+    source: ComputerClientSource,
+  ): ComputerClientOf<Definition>;
+  public static clientOf({
+    definition,
+    name,
+  }: ComputerClientSource): (
+    key: Decoded,
+  ) => Effect.Effect<ActorComputers, ComputersUnavailableError | InvalidRequestError> {
+    return (key) =>
+      Effect.gen(function* connectComputers() {
+        const clients = yield* Effect.serviceOption(ActorComputerClients);
+
+        if (Option.isNone(clients)) {
+          return yield* ComputersUnavailableError.make({ message: "computers aren't available on this host" });
+        }
+
+        const encoded = yield* Schema.encodeEffect(definition.key)(key).pipe(
+          Effect.mapError(() => InvalidRequestError.make({ actor: name, message: "the actor key is invalid" })),
+        );
+
+        return bounded(clients.value.connect({ actor: name, key: encoded }), { definition, name });
+      });
+  }
+}
+
+export type { ComputerClientOf };

package/src/contract/computer/computer-client.contract.ts

@@ -0,0 +1,75 @@
+import type { Effect } from "effect";
+import type { WorkflowEngine } from "effect/workflow";
+
+import type { ComputerClientFailure } from "./computer-client-failure.contract.js";
+import type { Computer, ComputerName, ComputerSpec, ExecRequest, ExecResult } from "./computer.schema.js";
+import type { CheckpointExpiredError } from "./checkpoint-expired.errors.js";
+import type { SecretUnavailableError } from "#src/contract/secret/secret-unavailable.errors";
+import type { StepRequest } from "./step/computer-step.schema.js";
+import type { ComputerFileRequest } from "./files/computer-files.schema.js";
+
+interface ComputerAddress {
+  readonly actor: string;
+  readonly key: string;
+}
+
+/**
+ * One actor's computers. Each call reaches a provider, so call it from a job activity or the host, never from a
+ * command or query (ADR 0007). `ensure`, `pause`, `resume`, `stop` and `remove` drive the computer to that state
+ * and are safe to send again after a lost reply. `exec` runs one step, keyed so a resend reads its outcome back.
+ */
+/**
+ * Where a fork goes: another actor, by its encoded key, and optionally a new name. A live computer is paused for
+ * its checkpoint and resumed; a paused or stopped one forks from its saved checkpoint.
+ */
+interface ComputerFork {
+  readonly into: ComputerAddress;
+  readonly name?: ComputerName;
+}
+
+/**
+ * A hold on a computer, such as a fork's id. `pause` with a hold keeps the computer paused, or stopped if it was stopped: `ensure`, `exec`
+ * and a `resume` or `pause` without the same hold fail with `ComputerHeldError`, so nothing changes its pause under a fork. `resume` with the hold releases it and returns the computer to where the held `pause` found it, running, paused or stopped. A hold survives restarts, so a retried fork releases what an earlier attempt held.
+ */
+interface ComputerHold {
+  readonly hold?: string;
+}
+
+interface ComputerClient {
+  /** A spec's `secrets` must be among the actor's declared secrets, and set in its environment. */
+  readonly ensure: (spec: ComputerSpec) => Effect.Effect<Computer, ComputerClientFailure | SecretUnavailableError>;
+  readonly exec: (computer: string, request: ExecRequest) => Effect.Effect<ExecResult, ComputerClientFailure>;
+  /** Reads or replaces one file in the computer's files directory; a write answers empty bytes. */
+  readonly files: (computer: string, request: ComputerFileRequest) => Effect.Effect<Uint8Array, ComputerClientFailure>;
+  /** Copies the computer, its files and memory, to the target actor. A resend finds the copy already made. */
+  readonly fork: (
+    computer: string,
+    fork: ComputerFork,
+  ) => Effect.Effect<Computer, ComputerClientFailure | CheckpointExpiredError>;
+  readonly get: (computer: string) => Effect.Effect<Computer, ComputerClientFailure>;
+  readonly list: Effect.Effect<readonly Computer[], ComputerClientFailure>;
+  readonly pause: (computer: string, hold?: ComputerHold) => Effect.Effect<Computer, ComputerClientFailure>;
+  readonly remove: (computer: string) => Effect.Effect<void, ComputerClientFailure>;
+  readonly resume: (computer: string, hold?: ComputerHold) => Effect.Effect<Computer, ComputerClientFailure>;
+  readonly stop: (computer: string) => Effect.Effect<Computer, ComputerClientFailure>;
+}
+
+/**
+ * An actor's computers as its jobs reach them through `Actor.computer(key)`: the client, plus `step`, which runs one
+ * command as a durable step of the calling job (`./step/computer-step.contract.ts`). Call `step` from a job, never from
+ * inside an activity.
+ */
+interface ActorComputers extends ComputerClient {
+  readonly step: (
+    computer: string,
+    request: StepRequest,
+  ) => Effect.Effect<
+    ExecResult,
+    ComputerClientFailure,
+    WorkflowEngine.WorkflowEngine | WorkflowEngine.WorkflowInstance
+  >;
+}
+
+export type { ActorComputers, ComputerAddress, ComputerClient, ComputerFork, ComputerHold };
+
+export type { ComputerClientFailure } from "./computer-client-failure.contract.js";

package/src/contract/computer/computer-held.errors.ts

@@ -0,0 +1,10 @@
+import { Schema } from "effect";
+
+/**
+ * A fork holds the computer paused. Nothing but that fork's resume, carrying the same hold, may run or resume it;
+ * try again once the fork ends.
+ */
+export class ComputerHeldError extends Schema.TaggedError<ComputerHeldError, { readonly brand: unique symbol }>()(
+  "ComputerHeldError",
+  { computer: Schema.String, hold: Schema.String },
+) {}

package/src/contract/computer/computer-limit.errors.ts

@@ -0,0 +1,11 @@
+import { Schema } from "effect";
+
+/**
+ * A new computer would pass a limit, so none was made: `store`, the computers one app environment may keep, or
+ * `account`, the sandboxes the platform's provider account may run at once. Remove a computer, or try again once
+ * one is gone. Nothing waits for room.
+ */
+export class ComputerLimitError extends Schema.TaggedError<ComputerLimitError, { readonly brand: unique symbol }>()(
+  "ComputerLimitError",
+  { computer: Schema.String, limit: Schema.Literals(["store", "account"]), maximum: Schema.Int },
+) {}

package/src/contract/computer/computer-lost.errors.ts

@@ -0,0 +1,10 @@
+import { Schema } from "effect";
+
+/**
+ * The computer's disk no longer exists, so it can't be resumed or run in. It is not recreated empty under the same
+ * name; remove it and ensure it again to start over.
+ */
+export class ComputerLostError extends Schema.TaggedError<ComputerLostError, { readonly brand: unique symbol }>()(
+  "ComputerLostError",
+  { computer: Schema.String },
+) {}

package/src/contract/computer/computer-not-found.errors.ts

@@ -0,0 +1,9 @@
+import { Schema } from "effect";
+
+/** The actor has no computer of that name. */
+export class ComputerNotFoundError extends Schema.TaggedError<
+  ComputerNotFoundError,
+  { readonly brand: unique symbol }
+>()("ComputerNotFoundError", {
+  computer: Schema.String,
+}) {}