@akterjs/conformance 0.0.0-stage → 0.1.1

package/src/workbench/computer-conformance.suite.ts

@@ -0,0 +1,380 @@
+import { ActorHost } from "@akterjs/effect";
+import { expect } from "@effect/vitest";
+import type { Vitest } from "@effect/vitest";
+import {
+  Array as Arr,
+  Clock,
+  Context,
+  Effect,
+  Layer,
+  Option,
+  Predicate,
+  Record as Rec,
+  Schedule,
+  String as Str,
+} from "effect";
+
+import type { Engine, Storage } from "#src/engine-conformance.suite.js";
+import { computerGuaranteeTitles } from "#src/guarantee-titles.pure.js";
+import type { Host, Unexpected } from "#src/ledger/ledger-calls.pure.js";
+import { WorkbenchLive } from "./workbench.actor.js";
+import { ComputerOp } from "./workbench.contract.js";
+import { bench, ensure, get, list, remove, stop, unfinished, workbenchHost } from "./workbench-calls.pure.js";
+
+type Checked<Failure> = Effect.Effect<void, Failure | Unexpected>;
+
+const { Pause, Resume, Step } = ComputerOp.cases;
+
+const { exec, outcomesOf, ran, startedRun } = workbenchHost;
+
+const holding = (hold?: string): { readonly hold?: string } => Rec.getSomes({ hold: Option.fromUndefinedOr(hold) });
+
+const pause = (computer: string, hold?: string): ComputerOp => Pause.make({ computer, ...holding(hold) });
+
+const resume = (computer: string, hold?: string): ComputerOp => Resume.make({ computer, ...holding(hold) });
+
+/** A durable step on `box`, named `name`, with an optional limit in seconds. */
+const step = (name: string, command: string, timeoutSeconds?: number): ComputerOp => {
+  const limit = Rec.getSomes({ timeoutSeconds: Option.fromUndefinedOr(timeoutSeconds) });
+
+  return Step.make({ command, computer: "box", name, ...limit });
+};
+
+/** Runs `use` on the Workbench on the real clock: a computer's calls wait on real processes and machines. */
+const onBench = <Failure, Success>(
+  storage: Storage<Failure>,
+  use: (host: Host) => Effect.Effect<Success, Unexpected>,
+): Effect.Effect<Success, Failure | Unexpected> => {
+  const engine = storage.pipe(Layer.provide(WorkbenchLive));
+  const run = Effect.flatMap(Layer.build(engine), (services) => use(Context.get(services, ActorHost)));
+
+  return Effect.provideService(Effect.scoped(run), Clock.Clock, Clock.Clock.defaultValue());
+};
+
+/** A step that counts how many times it ran, in a file on the computer. */
+const counting = "echo ran >> runs; grep -c ran runs";
+
+const stepRunsOnce = <Failure>(storage: Storage<Failure>): Checked<Failure> =>
+  Effect.gen(function* resendAcrossRestart() {
+    const live = yield* onBench(storage, (host) =>
+      ran(host, "r-1", [ensure("box"), exec("box", "count", counting), exec("box", "count", counting)]),
+    );
+
+    const restarted = yield* onBench(storage, (host) =>
+      ran(host, "r-2", [exec("box", "count", counting), exec("box", "read", "grep -c ran runs")]),
+    );
+
+    expect([live, restarted]).toStrictEqual([
+      ["up", "exit 0: 1\n", "exit 0: 1\n"],
+      ["exit 0: 1\n", "exit 0: 1\n"],
+    ]);
+  });
+
+const keepsFiles = <Failure>(storage: Storage<Failure>): Checked<Failure> =>
+  Effect.gen(function* writePauseStopRestart() {
+    const live = yield* onBench(storage, (host) =>
+      ran(host, "k-1", [
+        ensure("box"),
+        exec("box", "write", "echo kept > notes"),
+        pause("box"),
+        resume("box"),
+        stop("box"),
+      ]),
+    );
+
+    const restarted = yield* onBench(storage, (host) =>
+      ran(host, "k-2", [get("box"), exec("box", "read", "cat notes"), get("box")]),
+    );
+
+    expect([live, restarted]).toStrictEqual([
+      ["up", "exit 0: ", "paused", "up", "stopped"],
+      ["stopped", "exit 0: kept\n", "up"],
+    ]);
+  });
+
+/** Neither a plain pause nor a held pause starts a stopped computer; a plain pause cannot interfere with its hold. */
+const stoppedStaysStopped = (host: Host): Effect.Effect<void, Unexpected> =>
+  Effect.gen(function* pauseStopped() {
+    const asked = yield* ran(host, "h-2", [
+      ensure("idle"),
+      stop("idle"),
+      pause("idle"),
+      pause("idle", "fork-3"),
+      pause("idle"),
+      exec("idle", "step", "true"),
+      get("idle"),
+      resume("idle", "fork-3"),
+      exec("idle", "step", "echo again"),
+    ]);
+
+    expect(asked).toStrictEqual([
+      "up",
+      "stopped",
+      "stopped",
+      "stopped",
+      "ComputerHeldError",
+      "ComputerHeldError",
+      "stopped",
+      "stopped",
+      "exit 0: again\n",
+    ]);
+  });
+
+const heldStaysPaused = <Failure>(storage: Storage<Failure>): Checked<Failure> =>
+  onBench(storage, (host) =>
+    Effect.gen(function* holdThenRelease() {
+      const outcomes = yield* ran(host, "h-1", [
+        ensure("box"),
+        pause("box", "fork-1"),
+        exec("box", "step", "true"),
+        ensure("box"),
+        resume("box"),
+        resume("box", "fork-2"),
+        pause("box"),
+        pause("box", "fork-2"),
+        pause("box", "fork-1"),
+        get("box"),
+        resume("box", "fork-1"),
+        resume("box", "fork-1"),
+        exec("box", "step", "echo once"),
+      ]);
+
+      const held = "ComputerHeldError";
+
+      expect(outcomes).toStrictEqual([
+        "up",
+        "paused",
+        held,
+        held,
+        held,
+        held,
+        held,
+        held,
+        "paused",
+        "paused",
+        "up",
+        "up",
+        "exit 0: once\n",
+      ]);
+
+      yield* stoppedStaysStopped(host);
+    }),
+  );
+
+const tried = 8;
+
+const none = 0;
+
+const first = 1;
+
+/** `value` `count` times, for a count from none to `tried`. */
+const times = (value: string, count: number): readonly string[] => Arr.take(Arr.replicate(value, tried), count);
+
+const listed = (names: readonly string[]): string => `[${Arr.join(Arr.sort(names, Str.Order), ",")}]`;
+
+const limitHolds = <Failure>(storage: Storage<Failure>): Checked<Failure> =>
+  onBench(storage, (host) =>
+    Effect.gen(function* fillThenFree() {
+      const names = Arr.makeBy(tried, (index) => `c${String(index)}`);
+      const filled = yield* ran(host, "l-1", [...Arr.map(names, ensure), list]);
+      const made = Arr.takeWhile(filled, (outcome) => outcome === "up").length;
+      const refused = `ComputerLimitError store ${String(made)}`;
+      const kept = Arr.take(names, made);
+      const freed = yield* ran(host, "l-2", [remove("c0"), ensure("again"), ensure("more"), list]);
+
+      expect({ filled, freed, made: made > none && made < tried }).toStrictEqual({
+        filled: [...times("up", made), ...times(refused, tried - made), listed(kept)],
+        freed: ["removed", "up", refused, listed([...Arr.drop(kept, first), "again"])],
+        made: true,
+      });
+    }),
+  );
+
+const removedIsGone = <Failure>(storage: Storage<Failure>): Checked<Failure> =>
+  onBench(storage, (host) =>
+    Effect.gen(function* removeThenEnsure() {
+      const outcomes = yield* ran(host, "g-1", [
+        ensure("box"),
+        exec("box", "write", "echo x > left"),
+        remove("box"),
+        get("box"),
+        exec("box", "after", "true"),
+        remove("box"),
+        list,
+        ensure("box"),
+        exec("box", "look", "ls"),
+      ]);
+
+      const missing = "ComputerNotFoundError";
+
+      expect(outcomes).toStrictEqual([
+        "up",
+        "exit 0: ",
+        "removed",
+        missing,
+        missing,
+        "removed",
+        "[]",
+        "up",
+        "exit 0: ",
+      ]);
+    }),
+  );
+
+/** Each journaled step as `akter steps list` reads it, newest first: its name, its state and its exit code once it ran. */
+const journaled = (host: Host): Effect.Effect<readonly string[], Unexpected> =>
+  Effect.map(host.steps({ actor: "Workbench", key: bench }), (steps) =>
+    Arr.map(steps, ({ exitCode, name, state }) => {
+      const exit = Option.map(Option.fromUndefinedOr(exitCode), String);
+
+      return Arr.join([name, state, ...Option.toArray(exit)], " ");
+    }),
+  );
+
+const stepJournaled = <Failure>(storage: Storage<Failure>): Checked<Failure> =>
+  onBench(storage, (host) =>
+    Effect.gen(function* stepThenRead() {
+      const outcomes = yield* ran(host, "j-1", [ensure("box"), step("hello", "echo hi"), step("no", "exit 3")]);
+
+      const steps = yield* host.steps({ actor: "Workbench", key: bench });
+      const hello = Arr.filter(steps, ({ name }) => name === "hello");
+
+      const read = yield* Effect.forEach(hello, ({ step: id }) =>
+        host.step({ actor: "Workbench", key: bench, step: id }),
+      );
+
+      const missing = yield* host.step({ actor: "Workbench", key: bench, step: "no-such-step" });
+      const journal = yield* journaled(host);
+
+      expect({
+        journal,
+        missing: Option.isNone(missing),
+        outcomes,
+        output: Arr.map(Arr.getSomes(read), ({ computer, stdout }) => [computer, stdout]),
+        quiet: Arr.every(steps, ({ stdout }) => Predicate.isUndefined(stdout)),
+      }).toStrictEqual({
+        journal: ["no ran 3", "hello ran 0"],
+        missing: true,
+        outcomes: ["up", "exit 0: hi\n", "exit 3: "],
+        output: [["box", "hi\n"]],
+        quiet: true,
+      });
+    }),
+  );
+
+/** How long a cut-off guarantee waits for the step to be journaled before the engine under it stops. */
+const journalPolls = 200;
+
+const pollEvery = "100 millis";
+
+/** How long it waits for the replayed job to settle the step: past the step's limit and grace, with room under load. */
+const settlePolls = 400;
+
+/** A step that counts its runs, then outlives the moment the engine stops under it, within its 3 s limit. */
+const slow = "echo ran >> runs; sleep 2";
+
+const slowLimit = 3;
+
+/**
+ * Starts a job whose durable step is cut off by the engine stopping once the step is journaled, then restarts it.
+ * Wherever the stop fell, the step ran at most once and its job settles it: with the outcome the computer recorded
+ * when the command finished before the stop reached it, or `unknown` once its limit has passed without one.
+ */
+const stepSurvivesRestart = <Failure>(storage: Storage<Failure>): Checked<Failure> =>
+  Effect.gen(function* cutThenReplay() {
+    const job = yield* onBench(storage, (host) =>
+      Effect.gen(function* startThenStop() {
+        const started = yield* startedRun(host, {
+          commandId: "c-1",
+          key: bench,
+          ops: [ensure("box"), step("slow", slow, slowLimit)],
+        });
+
+        yield* Effect.repeat(journaled(host), {
+          schedule: Schedule.spaced(pollEvery),
+          times: journalPolls,
+          until: Arr.isReadonlyArrayNonEmpty,
+        });
+
+        return started;
+      }),
+    );
+
+    const settled = yield* onBench(storage, (host) =>
+      Effect.gen(function* replayThenCount() {
+        // The engine reopens its actors and resumes their jobs in the background, so a drain can run before the job is back.
+        const outcomes = yield* Effect.repeat(outcomesOf(host, bench, job), {
+          schedule: Schedule.spaced(pollEvery),
+          times: settlePolls,
+          until: (found) => !Arr.contains(found, unfinished),
+        });
+
+        const counted = yield* ran(host, "c-2", [exec("box", "count", "grep -c ran runs")]);
+        const journal = yield* journaled(host);
+
+        return { counted, journal, outcomes };
+      }),
+    );
+
+    const recorded = { journal: ["slow ran 0"], outcomes: ["up", "exit 0: "] };
+    const unknown = { journal: ["slow unknown"], outcomes: ["up", "unknown"] };
+    const { counted, ...settledAs } = settled;
+
+    expect(counted).toStrictEqual(["exit 0: 1\n"]);
+    expect([recorded, unknown]).toContainEqual(settledAs);
+  });
+
+type ComputerGuaranteeName = keyof typeof computerGuaranteeTitles;
+
+type Guarantee = <Failure>(storage: Storage<Failure>) => Checked<Failure>;
+
+/** The computer guarantees, by name; each runs the Workbench on a fresh store. */
+const computerGuarantees = {
+  computerHeldStaysPaused: heldStaysPaused,
+  computerKeepsFiles: keepsFiles,
+  computerLimitHolds: limitHolds,
+  computerRemovedIsGone: removedIsGone,
+  computerStepJournaled: stepJournaled,
+  computerStepRunsOnce: stepRunsOnce,
+  computerStepSurvivesRestart: stepSurvivesRestart,
+} as const satisfies Record<ComputerGuaranteeName, Guarantee>;
+
+const everyComputerGuarantee: readonly ComputerGuaranteeName[] = Rec.keys(computerGuarantees);
+
+interface ComputerSkipping<Failure, Services> {
+  /** An engine that serves `Workbench/bench-1`, with its computers bound to the job runtime's `Actor.computer(key)`. */
+  readonly engine: Engine<Failure, Services>;
+  readonly skip: Readonly<Partial<Record<ComputerGuaranteeName, string>>>;
+}
+
+/**
+ * Registers every computer guarantee against `engine`, each on fresh storage, skipping only those `skip` names with a
+ * reason. A guarantee added later runs on every engine that registers the suite.
+ */
+const computerConformanceOf =
+  <Failure, Services>({
+    engine,
+    skip,
+  }: ComputerSkipping<Failure, Services>): ((test: Vitest.MethodsNonLive<Services>) => void) =>
+  (test) => {
+    for (const name of everyComputerGuarantee) {
+      const title = computerGuaranteeTitles[name];
+      const guarantee: Guarantee = computerGuarantees[name];
+
+      const run = (): Effect.Effect<void, Failure | Unexpected, Services> =>
+        Effect.scoped(Effect.flatMap(engine, (storage) => guarantee(storage)));
+
+      Option.match(Option.fromNullishOr(skip[name]), {
+        onNone: () => {
+          test.effect(title, run);
+        },
+        onSome: (reason) => {
+          test.effect.skip(`${title} (skipped: ${reason})`, run);
+        },
+      });
+    }
+  };
+
+export { computerConformanceOf };
+
+export type { ComputerGuaranteeName };

package/src/workbench/workbench-calls.pure.ts

@@ -0,0 +1,92 @@
+import { Option, Record as Rec, Schema, Effect } from "effect";
+
+import { ada, nothing } from "#src/ledger/ledger-calls.pure.js";
+import type { Host, Unexpected } from "#src/ledger/ledger-calls.pure.js";
+import { decodeReply } from "#src/ledger/ledger-checks.pure.js";
+import { ComputerOp, Workbench } from "./workbench.contract.js";
+
+/** The Workbench the computer guarantees run on, whose key every engine under test serves. */
+const bench = "bench-1";
+
+/**
+ * The key a fork of `bench` goes into. Akter Cloud forks only into a key on the parent's own shard, and `bench-250`
+ * hashes to `bench-1`'s shard there.
+ */
+const forkedBench = "bench-250";
+
+const encodeOps = Schema.encodeEffect(Schema.fromJsonString(Workbench.commands.run.payload));
+
+const { Ensure, Exec, Get, List, Remove, Stop } = ComputerOp.cases;
+
+const ensure = (computer: string): ComputerOp => Ensure.make({ computer });
+
+const get = (computer: string): ComputerOp => Get.make({ computer });
+
+const remove = (computer: string): ComputerOp => Remove.make({ computer });
+
+const stop = (computer: string): ComputerOp => Stop.make({ computer });
+
+const list: ComputerOp = List.make({});
+
+/** Starts the calls in one `run` job on the Workbench at `key` and answers the job's id. */
+const startedRun = (
+  host: Host,
+  { commandId, key, ops }: { readonly commandId: string; readonly key: string; readonly ops: readonly ComputerOp[] },
+): Effect.Effect<string, Unexpected> =>
+  Effect.gen(function* startRun() {
+    const payload = yield* encodeOps({ ops });
+
+    const sent = yield* host.command({
+      actor: "Workbench",
+      commandId,
+      key,
+      member: "run",
+      payload,
+      principal: ada,
+    });
+
+    return yield* Effect.flatten(decodeReply(Workbench.commands.run, sent));
+  });
+
+const unfinished = "the job had not finished";
+
+/** What each call of a job answered, once its result has reached the actor. */
+const outcomesOf = (host: Host, key: string, job: string): Effect.Effect<readonly string[], Unexpected> =>
+  Effect.gen(function* readOutcomes() {
+    yield* host.drain;
+
+    const reply = yield* host.query({
+      actor: "Workbench",
+      key,
+      member: "runs",
+      payload: nothing,
+      principal: ada,
+    });
+
+    const runs = yield* Effect.flatten(decodeReply(Workbench.queries.runs, reply));
+
+    return Option.getOrElse(Rec.get(runs, job), () => [unfinished]);
+  });
+
+/**
+ * Runs the calls in one `run` job on the Workbench at `key` and answers what each returned, once the job's result has
+ * reached the actor. A call is one activity, so `run` with the same command id after a restart answers the same job.
+ */
+const ranAt = (
+  host: Host,
+  key: string,
+  { commandId, ops }: { readonly commandId: string; readonly ops: readonly ComputerOp[] },
+): Effect.Effect<readonly string[], Unexpected> =>
+  Effect.flatMap(startedRun(host, { commandId, key, ops }), (job) => outcomesOf(host, key, job));
+
+/** Runs the calls in one `run` job on the suite's Workbench, `bench`, as `ranAt` does. */
+const ran = (host: Host, commandId: string, ops: readonly ComputerOp[]): Effect.Effect<readonly string[], Unexpected> =>
+  ranAt(host, bench, { commandId, ops });
+
+/** A step on `computer` under `key`, outside the job's journal. */
+const exec = (computer: string, key: string, command: string): ComputerOp => Exec.make({ command, computer, key });
+
+/** The calls, as one namespace: each takes the host first, and `exec`, which builds a step to run. */
+const workbenchHost = { exec, outcomesOf, ran, ranAt, startedRun };
+
+export { bench, ensure, forkedBench, get, list, remove, stop, unfinished, workbenchHost };

package/src/workbench/workbench.actor.ts

@@ -0,0 +1,175 @@
+import { Akter as Engine } from "@akterjs/effect";
+import { Akter } from "@akterjs/effect/contract";
+import { ComputerName, ExecRan } from "@akterjs/effect/contract/computer";
+import type { Computer, ComputerSpec, ExecResult } from "@akterjs/effect/contract/computer";
+import type { ActorComputerClients } from "@akterjs/effect/contract/computer-clients";
+import { ComputerLimitError } from "@akterjs/effect/contract/errors";
+import {
+  Array as Arr,
+  Cause,
+  Effect,
+  Exit,
+  Layer,
+  Option,
+  Predicate,
+  Record as Rec,
+  Schema,
+  String as Str,
+} from "effect";
+import { Activity } from "effect/workflow";
+import type { WorkflowEngine } from "effect/workflow";
+
+import { ComputerOp, Workbench } from "./workbench.contract.js";
+
+type ComputerClient = ReturnType<ActorComputerClients["Service"]["connect"]>;
+
+/** Every failure a computer call can answer. */
+type CallFailure = Effect.Error<ReturnType<ComputerClient["ensure"]>>;
+
+/** Every failure reaching the computers or calling them can answer. */
+type Failed = CallFailure | Effect.Error<ReturnType<typeof Workbench.computer>>;
+
+const memoryMib = 1024;
+
+/** Every failure a computer call can answer, by tag. */
+const failures = [
+  "ActorUnavailableError",
+  "CallerNotAllowedError",
+  "ComputerHeldError",
+  "ComputerLostError",
+  "ComputerNotFoundError",
+  "ComputersUnavailableError",
+  "InvalidRequestError",
+  "SecretUnavailableError",
+  "UnauthenticatedError",
+] as const;
+
+const isLimit = Schema.is(ComputerLimitError);
+
+const isRan = Schema.is(ExecRan);
+
+const specOf = (computer: string): ComputerSpec => ({
+  egress: [],
+  image: "node:24-bookworm",
+  name: ComputerName.make(computer),
+  size: { memoryMib, vcpu: 1 },
+});
+
+const stepOf = (result: ExecResult): string => {
+  if (!isRan(result)) {
+    return "unknown";
+  }
+
+  const exit = Option.getOrElse(Option.map(Option.fromUndefinedOr(result.exitCode), String), () => "none");
+
+  return `exit ${exit}: ${result.stdout}`;
+};
+
+/** An engine may answer before the machine is up, so `starting` and `running` read the same: `up`. */
+const upStates: readonly Computer["state"][] = ["running", "starting"];
+
+const stateOf = ({ state }: Computer): string => {
+  if (Arr.contains(upStates, state)) {
+    return "up";
+  }
+
+  return state;
+};
+
+const holdOf = (hold: string | undefined): { readonly hold?: string } =>
+  Rec.getSomes({ hold: Option.fromUndefinedOr(hold) });
+
+const namesOf = (computers: readonly Computer[]): string =>
+  `[${Arr.join(
+    Arr.sort(
+      Arr.map(computers, ({ name }) => name),
+      Str.Order,
+    ),
+    ",",
+  )}]`;
+
+/** What one call answered, as the suite compares it: a state, a step's exit and output, names, or `removed`. */
+const called = (client: ComputerClient, op: ComputerOp): Effect.Effect<string, CallFailure> =>
+  ComputerOp.match(op, {
+    Ensure: ({ computer }) => Effect.map(client.ensure(specOf(computer)), stateOf),
+    Exec: ({ command, computer, key }) => Effect.map(client.exec(computer, { command, key }), stepOf),
+    Get: ({ computer }) => Effect.map(client.get(computer), stateOf),
+    List: () => Effect.map(client.list, namesOf),
+    Pause: ({ computer, hold }) => Effect.map(client.pause(computer, holdOf(hold)), stateOf),
+    Remove: ({ computer }) => Effect.as(client.remove(computer), "removed"),
+    Resume: ({ computer, hold }) => Effect.map(client.resume(computer, holdOf(hold)), stateOf),
+    Step: () => Effect.die("a durable step runs in the job, not in an activity"),
+    Stop: ({ computer }) => Effect.map(client.stop(computer), stateOf),
+  });
+
+/** A failure by its tag; a limit with the limit and its maximum, which the suite checks against what was made. */
+const failureOf = (failure: Failed): string => {
+  if (isLimit(failure)) {
+    return `ComputerLimitError ${failure.limit} ${String(failure.maximum)}`;
+  }
+
+  return Option.getOrElse(
+    Arr.findFirst(failures, (tag) => Predicate.isTagged(failure, tag)),
+    () => "unexpected failure",
+  );
+};
+
+const attempted = (key: string, op: ComputerOp): Effect.Effect<string, Failed> =>
+  Effect.flatMap(Workbench.computer(key), (client) => called(client, op));
+
+const answered = (key: string, op: ComputerOp): Effect.Effect<string> =>
+  Effect.match(attempted(key, op), { onFailure: failureOf, onSuccess: (outcome) => outcome });
+
+type StepOp = typeof ComputerOp.cases.Step.Type;
+
+const isStep = Schema.is(ComputerOp.cases.Step);
+
+const timeoutOf = (timeoutSeconds: number | undefined): { readonly timeoutSeconds?: number } =>
+  Rec.getSomes({ timeoutSeconds: Option.fromUndefinedOr(timeoutSeconds) });
+
+/** A durable step, made by the job itself: it journals its own start and outcome. */
+const stepped = (
+  key: string,
+  { command, computer, name, timeoutSeconds }: StepOp,
+): Effect.Effect<string, never, WorkflowEngine.WorkflowEngine | WorkflowEngine.WorkflowInstance> =>
+  Effect.match(
+    Effect.flatMap(Workbench.computer(key), (computers) =>
+      computers.step(computer, { command, name, ...timeoutOf(timeoutSeconds) }),
+    ),
+    { onFailure: failureOf, onSuccess: stepOf },
+  );
+
+/**
+ * Makes each call in its own activity, so a job resumed after a restart reads back the calls it already made, and each
+ * `Step` as a durable step of the job.
+ */
+const RunLive = Workbench.jobs.run.toLayer(({ key, ops }) =>
+  Effect.forEach(ops, (op, index) => {
+    if (isStep(op)) {
+      return stepped(key, op);
+    }
+
+    return Activity.make({ execute: answered(key, op), name: `call-${String(index)}`, success: Schema.String });
+  }),
+);
+
+const outcomesOf = (result: Exit.Exit<readonly string[]>): readonly string[] =>
+  Exit.match(result, {
+    onFailure: (cause) => [`job failed: ${Cause.pretty(cause)}`],
+    onSuccess: (outcomes) => outcomes,
+  });
+
+const WorkbenchHandlers = Workbench.toLayer({
+  commands: {
+    run: (_bench, { ops }) => Effect.flatMap(Akter.actorKey, (key) => Akter.start(Workbench.jobs.run, { key, ops })),
+  },
+  queries: { runs: (bench) => Effect.succeed(bench.runs) },
+  results: {
+    run: (bench, result, job) => Workbench.update({ runs: Rec.set(bench.runs, job.id, outcomesOf(result)) }),
+  },
+});
+
+/** The Workbench and its job on the engine's job runtime, whose activities reach the computers the engine bound. */
+const WorkbenchLive = Layer.merge(WorkbenchHandlers, RunLive).pipe(Layer.provide(Engine.jobs));
+
+export { WorkbenchLive };

package/src/workbench/workbench.contract.ts

@@ -0,0 +1,47 @@
+import { Akter } from "@akterjs/effect/contract";
+import { Schema } from "effect";
+
+const Named = { computer: Schema.String };
+
+const Held = { ...Named, hold: Schema.optionalKey(Schema.String) };
+
+/** One call a `run` job makes to the actor's computers, in order. */
+const ComputerOp = Schema.TaggedUnion({
+  Ensure: Named,
+  Exec: { ...Named, command: Schema.String, key: Schema.String },
+  Get: Named,
+  List: {},
+  Pause: Held,
+  Remove: Named,
+  Resume: Held,
+  Step: { ...Named, command: Schema.String, name: Schema.String, timeoutSeconds: Schema.optionalKey(Schema.Int) },
+  Stop: Named,
+});
+
+type ComputerOp = typeof ComputerOp.Type;
+
+/** Each finished `run` job's outcomes, one per call, by the job's id. */
+const Runs = Schema.Record(Schema.String, Schema.Array(Schema.String));
+
+/**
+ * The suite's actor for computer guarantees. `run` starts a job that makes its calls to the actor's computers, each
+ * in an activity or, for a `Step`, as a durable step of the job, and records what each answered; `runs` reads those
+ * records back.
+ */
+const Workbench = Akter.make("Workbench", {
+  commands: {
+    run: Akter.command({ payload: { ops: Schema.Array(ComputerOp) }, success: Schema.String }),
+  },
+  initial: () => ({ runs: {} }),
+  jobs: {
+    run: Akter.job({
+      payload: { key: Schema.String, ops: Schema.Array(ComputerOp) },
+      success: Schema.Array(Schema.String),
+    }),
+  },
+  key: Schema.String,
+  queries: { runs: Akter.query({ success: Runs }) },
+  state: Schema.Struct({ runs: Runs }),
+});
+
+export { ComputerOp, Workbench };