@akterjs/effect 0.0.0-stage → 0.1.0

package/src/host/command/command-runner.service.ts

@@ -0,0 +1,320 @@
+import { Clock, Context, Duration, Effect, HashMap, Layer, Option } from "effect";
+import type { SqlClient, SqlError } from "effect/sql";
+
+import type { CommandEnvironment, HostedError, HostedOutcome, HostedRequest } from "#src/contract/actor/actor.contract";
+
+import type { OpenedActor } from "#src/host/actor/actor-database.service";
+import { HandlerSql } from "#src/host/query/query-policy.pure";
+import { CommandContext } from "./command-context.adapter.js";
+import { checkCommandId } from "./command-id-age.pure.js";
+import {
+  isResultCommandId,
+  isTimerCommandId,
+  jobIdOfResult,
+  jobOfResult,
+  refuseReserved,
+  refuseReuse,
+  resultMember,
+  reuseDefect,
+  sameCommand,
+} from "./command-id-reuse.pure.js";
+import type { Reuse } from "./command-id-reuse.pure.js";
+import {
+  CommandBatchJournal,
+  currentState,
+  pruneJournal,
+  recordCommand,
+  recordedCommand,
+  settle,
+} from "./command-journal.sql.js";
+import type { JournalRow, RecordedCommand } from "./command-journal.sql.js";
+
+import { journalFailure, replyOf } from "./command-reply.pure.js";
+
+interface CommandRequest {
+  readonly commandId: string;
+  readonly key: string;
+  readonly member: string;
+  readonly payload: string;
+  readonly principal: string;
+}
+
+interface CreationRequest {
+  readonly commandId: string;
+  readonly key: string;
+  readonly mode: "create" | "ensure";
+  readonly payload: string;
+  readonly principal: string;
+}
+
+interface ResultRequest {
+  readonly commandId: string;
+  readonly job: string;
+  readonly key: string;
+  readonly payload: string;
+  readonly principal: string;
+}
+
+interface Resulting {
+  readonly opened: OpenedActor;
+  readonly request: ResultRequest;
+}
+
+interface Running {
+  readonly opened: OpenedActor;
+  readonly request: CommandRequest;
+}
+
+interface Creating {
+  readonly opened: OpenedActor;
+  readonly request: CreationRequest;
+}
+
+interface Pruning {
+  readonly before: number;
+  readonly opened: OpenedActor;
+}
+
+type Invoke = (request: HostedRequest, environment: CommandEnvironment) => Effect.Effect<HostedOutcome, HostedError>;
+
+interface Executing extends Running {
+  readonly context: CommandContext["Service"];
+  readonly invoke: Invoke;
+}
+
+type Outcome = Effect.Effect<string, HostedError | SqlError.SqlError>;
+
+type Admit = (running: Running) => Effect.Effect<void, HostedError>;
+
+interface Gate {
+  readonly admit: Admit;
+  readonly reused: (reuse: Reuse) => Effect.Effect<never, HostedError>;
+  readonly screen: Admit;
+}
+
+const creationModes = HashMap.make(["akter.create", "create" as const], ["akter.ensure", "ensure" as const]);
+
+const internal: Gate = { admit: () => Effect.void, reused: reuseDefect, screen: () => Effect.void };
+
+const HistoryRetention = Context.Reference<Duration.Duration>(
+  "@akterjs/effect/host/command/command-runner.service/HistoryRetention",
+  { defaultValue: () => Duration.infinity },
+);
+
+const admitting =
+  (retention: Duration.Duration): Admit =>
+  ({ opened, request }) => {
+    if (!Duration.isFinite(retention)) {
+      return Effect.void;
+    }
+
+    return Effect.flatMap(Clock.currentTimeMillis, (now) =>
+      checkCommandId({
+        actor: opened.actor.name,
+        commandId: request.commandId,
+        keptSince: now - Duration.toMillis(retention),
+        now,
+      }),
+    );
+  };
+
+const fromClient = (retention: Duration.Duration): Gate => ({
+  admit: admitting(retention),
+  reused: refuseReuse,
+  screen: ({ opened, request }) =>
+    refuseReserved({ actor: opened.actor.name, commandId: request.commandId, principal: request.principal }),
+});
+
+interface Settling {
+  readonly at: number;
+  readonly handled: Effect.Effect<HostedOutcome, HostedError>;
+  readonly principal: string;
+  readonly sql: SqlClient.SqlClient;
+}
+
+/** Runs the handler and saves its outcome in one savepoint; the outcome's writes go through the batch's writer. */
+const settled = Effect.fnUntraced(function* settled({ at, handled, principal, sql }: Settling) {
+  const writer = yield* CommandBatchJournal.writer(sql);
+
+  const saving = Effect.flatMap(handled, (outcome) =>
+    Effect.tap(settle({ at, outcome, principal, sql: writer }), () =>
+      Option.match(outcome.state, { onNone: () => Effect.void, onSome: CommandBatchJournal.saved }),
+    ),
+  );
+
+  return yield* sql.withTransaction(saving).pipe(
+    Effect.catchTags({
+      ActorAlreadyExistsError: journalFailure,
+      CommandRejectedError: (rejected) => Effect.succeed(rejected.exit),
+      HandlerFailedError: journalFailure,
+    }),
+  );
+});
+
+/** Writes the command's journal row; inside an engine batch, at the seq the batch journal gives it. */
+const journal = Effect.fnUntraced(function* journal(row: JournalRow, sql: SqlClient.SqlClient) {
+  const { command, commandId, exit, principal } = row;
+  const seq = yield* CommandBatchJournal.record(commandId, { command, exit, principal });
+
+  yield* recordCommand({ row, seq, sql: yield* CommandBatchJournal.writer(sql) });
+});
+
+const execute = Effect.fnUntraced(function* execute({ context, invoke, opened, request }: Executing) {
+  const { sql } = opened;
+  const at = yield* Clock.currentTimeMillis;
+  const state = yield* CommandBatchJournal.state(sql, currentState(sql));
+  const tracked = yield* context.track({ files: opened.files(sql), key: request.key, sql });
+  const handled = Effect.provideService(invoke({ ...request, state }, tracked.environment), HandlerSql, true);
+  const journaled = yield* settled({ at, handled, principal: request.principal, sql });
+
+  const recorded = yield* tracked.recorded;
+  const { commandId, member: command, payload, principal } = request;
+
+  yield* journal({ ...recorded, at, command, commandId, exit: journaled, payload, principal }, sql);
+
+  return journaled;
+});
+
+const replayed = (
+  gate: Gate,
+  { opened, request }: Running,
+  recorded: RecordedCommand,
+): Effect.Effect<string, HostedError> => {
+  const reuse: Reuse = {
+    actor: opened.actor.name,
+    commandId: request.commandId,
+    member: request.member,
+    principal: request.principal,
+    recordedMember: recorded.command,
+    recordedPrincipal: recorded.principal,
+  };
+
+  if (!sameCommand(reuse)) {
+    return gate.reused(reuse);
+  }
+
+  return Effect.succeed(recorded.exit);
+};
+
+type Once = (running: Running, invoke: Invoke, gate: Gate) => Outcome;
+
+const onceWith = (context: CommandContext["Service"]): Once =>
+  Effect.fnUntraced(function* once(running: Running, invoke: Invoke, gate: Gate) {
+    const { opened, request } = running;
+
+    yield* gate.screen(running);
+
+    const journaled = yield* opened.sql.withTransaction(
+      Effect.gen(function* runOnce() {
+        const recorded = yield* CommandBatchJournal.recorded(
+          opened.sql,
+          request.commandId,
+          recordedCommand({ commandId: request.commandId, sql: opened.sql }),
+        );
+
+        if (Option.isSome(recorded)) {
+          return yield* replayed(gate, running, recorded.value);
+        }
+
+        yield* gate.admit(running);
+
+        // A failed statement's full message is logged under the command's id when the caller gets a generic one.
+        return yield* execute({ context, invoke, opened, request }).pipe(
+          Effect.annotateLogs({ actor: opened.actor.name, commandId: request.commandId }),
+        );
+      }),
+    );
+
+    return yield* replyOf(journaled);
+  });
+
+interface Paths {
+  readonly create: (creating: Creating) => Outcome;
+  readonly result: (resulting: Resulting) => Outcome;
+  readonly run: (running: Running) => Outcome;
+  readonly runOwn: (running: Running) => Outcome;
+}
+
+const replayWith =
+  ({ create, result, run, runOwn }: Paths) =>
+  (running: Running): Outcome => {
+    const { opened, request } = running;
+
+    if (isTimerCommandId(request.commandId)) {
+      return runOwn(running);
+    }
+
+    if (isResultCommandId(request.commandId)) {
+      return result({ opened, request: { ...request, job: jobOfResult(request.member) } });
+    }
+
+    return Option.match(HashMap.get(creationModes, request.member), {
+      onNone: () => run(running),
+      onSome: (mode) => create({ opened, request: { ...request, mode } }),
+    });
+  };
+
+const prune = ({ before, opened }: Pruning): Effect.Effect<void, SqlError.SqlError> =>
+  Effect.andThen(pruneJournal({ before, sql: opened.sql }), CommandBatchJournal.forget);
+
+export class CommandRunner extends Context.Service<
+  CommandRunner,
+  {
+    readonly create: (creating: Creating) => Outcome;
+    readonly prune: (pruning: Pruning) => Effect.Effect<void, SqlError.SqlError>;
+    readonly replay: (running: Running) => Outcome;
+    readonly result: (resulting: Resulting) => Outcome;
+    readonly run: (running: Running) => Outcome;
+    readonly runOwn: (running: Running) => Outcome;
+  }
+>()("@akterjs/effect/host/command/command-runner.service/CommandRunner", {
+  make: Effect.gen(function* makeCommandRunner() {
+    const context = yield* CommandContext;
+    const retention = yield* HistoryRetention;
+    const once = onceWith(context);
+    const client = fromClient(retention);
+
+    const run = Effect.fn("CommandRunner.run")(function* run(running: Running) {
+      return yield* once(running, running.opened.actor.runCommand, client);
+    });
+
+    const create = Effect.fn("CommandRunner.create")(function* create({ opened, request }: Creating) {
+      const member = `akter.${request.mode}`;
+
+      return yield* once(
+        { opened, request: { ...request, member } },
+        (hosted, environment) => opened.actor.runCreate({ ...hosted, member: request.mode }, environment),
+        client,
+      );
+    });
+
+    const result = Effect.fn("CommandRunner.result")(function* result({
+      opened,
+      request: { job, ...rest },
+    }: Resulting) {
+      const member = resultMember(job);
+
+      return yield* once(
+        { opened, request: { ...rest, member } },
+        (hosted, environment) =>
+          opened.actor.runResult({ ...hosted, jobId: jobIdOfResult(rest.commandId), member: job }, environment),
+        internal,
+      );
+    });
+
+    const runOwn = Effect.fn("CommandRunner.runOwn")(function* runOwn(running: Running) {
+      return yield* once(running, running.opened.actor.runCommand, internal);
+    });
+
+    return { create, prune, replay: replayWith({ create, result, run, runOwn }), result, run, runOwn } as const;
+  }),
+}) {
+  public static readonly historyRetention = HistoryRetention;
+
+  /** Whether a failed statement's message reaches the caller or only the host's log. */
+  public static readonly statementDetail = CommandContext.statementDetail;
+
+  public static readonly layer = Layer.effect(this, this.make).pipe(Layer.provide(CommandContext.layer));
+}
+
+export type { CommandRequest, CreationRequest, Running };

package/src/host/command/files/command-file-inputs.sql.ts

@@ -0,0 +1,114 @@
+import { Array as Arr, Effect, Option, Ref, Schema } from "effect";
+import type { SqlClient, SqlError } from "effect/sql";
+
+import type { FileStorage } from "#src/contract/file/actor-files.contract";
+import { BlobTransferError } from "#src/contract/file/blob-transfer.errors";
+
+const ReceiptInput = Schema.Struct({
+  actor: Schema.String,
+  blob: Schema.String,
+  bytes: Schema.Int,
+  claim: Schema.String,
+  expiresAt: Schema.Int,
+  grant: Schema.String,
+  receipt: Schema.String,
+  sha256: Schema.String,
+  state: Schema.Literals(["uploading", "prepared", "consumed", "canceled"]),
+});
+
+const FileInput = Schema.Struct({ receipt: Schema.String, row: Schema.Option(ReceiptInput) });
+
+const FileInputs = Schema.fromJsonString(Schema.toCodecJson(Schema.Array(FileInput)));
+
+type FileInputValue = typeof FileInput.Type;
+
+const consumedInput = 1;
+
+interface Capturing {
+  readonly files: FileStorage;
+  readonly sql: SqlClient.SqlClient;
+  readonly used: Ref.Ref<readonly FileInputValue[]>;
+}
+
+interface Replaying {
+  readonly files: FileStorage;
+  readonly inputs: readonly FileInputValue[];
+  readonly sql: SqlClient.SqlClient;
+}
+
+interface Retaining {
+  readonly commandId: string;
+  readonly recorded: string;
+  readonly sql: SqlClient.SqlClient;
+}
+
+const fileInput = (sql: SqlClient.SqlClient, receipt: string): Effect.Effect<FileInputValue, SqlError.SqlError> =>
+  Effect.map(
+    sql<
+      typeof ReceiptInput.Type
+    >`SELECT actor, blob, bytes, claim, expires_at AS expiresAt, grant, receipt, sha256, state FROM akter_blob_receipts WHERE receipt = ${receipt}`,
+    (rows) => ({ receipt, row: Arr.head(rows) }),
+  );
+
+const captureFileInputs = ({ files, sql, used }: Capturing): FileStorage => ({
+  ...files,
+  attach: (attaching) =>
+    Effect.gen(function* captureAttachment() {
+      yield* files.available;
+      const input = yield* fileInput(sql, attaching.receipt);
+
+      yield* Ref.update(used, (inputs) => Arr.append(inputs, input));
+
+      return yield* files.attach(attaching);
+    }),
+});
+
+const restoreInput = (sql: SqlClient.SqlClient, input: FileInputValue): Effect.Effect<void, SqlError.SqlError> =>
+  Option.match(input.row, {
+    onNone: () => Effect.asVoid(sql`DELETE FROM akter_blob_receipts WHERE receipt = ${input.receipt}`),
+    onSome: (row) =>
+      Effect.asVoid(
+        sql`INSERT INTO akter_blob_receipts (receipt, actor, blob, claim, expires_at, bytes, sha256, grant, state) VALUES (${row.receipt}, ${row.actor}, ${row.blob}, ${row.claim}, ${row.expiresAt}, ${row.bytes}, ${row.sha256}, ${row.grant}, ${row.state}) ON CONFLICT (receipt) DO UPDATE SET actor = excluded.actor, blob = excluded.blob, claim = excluded.claim, expires_at = excluded.expires_at, bytes = excluded.bytes, sha256 = excluded.sha256, grant = excluded.grant, state = excluded.state`,
+      ),
+  });
+
+const replayFileInputs = ({ files, sql, inputs }: Replaying): Effect.Effect<FileStorage> =>
+  Effect.map(Ref.make(inputs), (left) => ({
+    ...files,
+    attach: (attaching) =>
+      Effect.gen(function* replayAttachment() {
+        const input = yield* Ref.modify(
+          left,
+          (remaining) => [Arr.head(remaining), Arr.drop(remaining, consumedInput)] as const,
+        );
+
+        if (Option.isNone(input) || input.value.receipt !== attaching.receipt) {
+          return yield* BlobTransferError.make({ blob: "", message: "the replay did not record this upload receipt" });
+        }
+
+        yield* restoreInput(sql, input.value);
+
+        return yield* files.attach(attaching);
+      }),
+  }));
+
+const retainFileInputs = ({ sql, commandId, recorded }: Retaining): Effect.Effect<void, SqlError.SqlError> =>
+  Effect.flatMap(Effect.orDie(Schema.decodeEffect(FileInputs)(recorded)), (inputs) =>
+    Effect.forEach(
+      inputs,
+      (input) =>
+        Option.match(input.row, {
+          onNone: () => Effect.void,
+          onSome: (row) =>
+            Effect.andThen(
+              sql`INSERT INTO akter_blob_history (command_id, claim, actor, blob) VALUES (${commandId}, ${row.claim}, ${row.actor}, ${row.blob}) ON CONFLICT DO NOTHING`,
+              Effect.asVoid(sql`DELETE FROM akter_blob_releases WHERE claim = ${row.claim}`),
+            ),
+        }),
+      { discard: true },
+    ),
+  );
+
+export { captureFileInputs, FileInputs, replayFileInputs, retainFileInputs };
+
+export type { FileInputValue };

package/src/host/command/history-pruned.errors.ts

@@ -0,0 +1,10 @@
+import { Schema } from "effect";
+
+export class HistoryPrunedError extends Schema.TaggedError<HistoryPrunedError, { readonly brand: unique symbol }>()(
+  "HistoryPrunedError",
+  {
+    actor: Schema.String,
+    coveredSince: Schema.Int,
+    key: Schema.String,
+  },
+) {}

package/src/host/command/replay/replay-cursor-stalled.errors.ts

@@ -0,0 +1,9 @@
+import { Schema } from "effect";
+
+export class ReplayCursorStalledError extends Schema.TaggedError<
+  ReplayCursorStalledError,
+  { readonly brand: unique symbol }
+>()("ReplayCursorStalledError", {
+  after: Schema.Int,
+  cursor: Schema.Int,
+}) {}

package/src/host/command/replay/replay-cursor.pure.ts

@@ -0,0 +1,19 @@
+import { Option } from "effect";
+import { dual } from "effect/Function";
+
+import { ReplayCursorStalledError } from "./replay-cursor-stalled.errors.js";
+
+const dataFirstArity = 2;
+
+const stalledCursor: {
+  (after: number): (cursor: number) => Option.Option<ReplayCursorStalledError>;
+  (cursor: number, after: number): Option.Option<ReplayCursorStalledError>;
+} = dual(dataFirstArity, (cursor: number, after: number): Option.Option<ReplayCursorStalledError> => {
+  if (cursor > after) {
+    return Option.none();
+  }
+
+  return Option.some(ReplayCursorStalledError.make({ after, cursor }));
+});
+
+export { stalledCursor };

package/src/host/computer/computer-steps.sql.ts

@@ -0,0 +1,120 @@
+import { Array as Arr, Cause, Effect, Exit, Option, Record as Rec, Schema, Struct } from "effect";
+import type { SqlClient, SqlError } from "effect/sql";
+
+import { ExecRan } from "#src/contract/computer/computer.schema";
+import { StepEnd, StepStart, largestPage, stepPage } from "#src/contract/computer/step/computer-step.schema";
+import type { ComputerStep, StepPage, StepState } from "#src/contract/computer/step/computer-step.schema";
+import { StoredExit } from "#src/contract/job/job-signal.schema";
+
+/** One journaled step: its start, its end when it settled, and whether its job has finished. */
+interface StepRow {
+  readonly end: string | null;
+  readonly finished: number;
+  readonly job: string;
+  readonly name: string;
+  readonly start: string;
+}
+
+type Sql<Value> = Effect.Effect<Value, SqlError.SqlError>;
+
+/**
+ * A durable step journals two activities in its job (`computer-step.contract.ts`): `step-start/<name>`, then
+ * `step/<name>`. Each is stored as `activity/<activity>/<attempt>`, and a step's name holds no slash.
+ */
+const startPrefix = "activity/step-start/";
+
+/** SQLite counts a string's characters from 1. */
+const firstCharacter = 1;
+
+const nameAt = startPrefix.length + firstCharacter;
+
+/** Every journaled step start with its name, its latest end, and whether its job has a result, filtered by `where`. */
+const stepRows = (where: string): string =>
+  `WITH starts AS (SELECT rowid AS seq, execution_id AS job, substr(entry, ${String(nameAt)}, instr(substr(entry, ${String(nameAt)}), '/') - 1) AS name, value AS start FROM akter_workflow WHERE substr(entry, 1, ${String(startPrefix.length)}) = '${startPrefix}') SELECT job, name, start, (SELECT e.value FROM akter_workflow e WHERE e.execution_id = starts.job AND substr(e.entry, 1, length('activity/step/' || starts.name || '/')) = 'activity/step/' || starts.name || '/' ORDER BY e.rowid DESC LIMIT 1) AS "end", EXISTS (SELECT 1 FROM akter_workflow r WHERE r.execution_id = starts.job AND r.entry = 'result') AS finished FROM starts WHERE ${where} ORDER BY seq DESC LIMIT ?`;
+
+const decodeExit = Schema.decodeUnknownOption(StoredExit);
+
+const decodeStart = Schema.decodeUnknownOption(Schema.toCodecJson(StepStart));
+
+const decodeEnd = Schema.decodeUnknownOption(Schema.toCodecJson(StepEnd));
+
+const isRan = Schema.is(ExecRan);
+
+const encodeFailure = Schema.encodeUnknownOption(Schema.fromJsonString(Schema.Unknown));
+
+const successOf = (stored: string): Option.Option<unknown> => Option.flatMap(decodeExit(stored), Exit.getSuccess);
+
+/** A failure as the error the step journaled, as JSON, such as `{"_tag":"ComputerLostError",…}`; `defect` when it died. */
+const failureOf = (cause: Cause.Cause<unknown>): string =>
+  Option.getOrElse(Option.flatMap(Cause.findErrorOption(cause), encodeFailure), () => "defect");
+
+/** A step with no journaled end: `running` while its job runs, `unknown` once the job finished without settling it. */
+const unsettled: readonly StepState[] = ["running", "unknown"];
+
+type Settled = Pick<ComputerStep, "endedAt" | "exitCode" | "failure" | "stderr" | "stdout" | "truncated"> & {
+  readonly state: StepState;
+};
+
+const endedWith = (end: StepEnd): Settled => {
+  if (!isRan(end.outcome)) {
+    return { endedAt: end.endedAt, state: "unknown" };
+  }
+
+  const { exitCode, stderr, stdout, truncated } = end.outcome;
+  const exit = Rec.getSomes({ exitCode: Option.fromUndefinedOr(exitCode) });
+
+  return { ...exit, endedAt: end.endedAt, state: "ran", stderr, stdout, truncated };
+};
+
+/** Where a step is: its journaled end, or `running` until its job finishes without one, which leaves it `unknown`. */
+const settledOf = (row: StepRow): Settled => {
+  const stored = Option.flatMap(Option.fromNullishOr(row.end), decodeExit);
+
+  return Option.match(stored, {
+    onNone: () => ({ state: Option.getOrElse(Arr.get(unsettled, row.finished), (): StepState => "unknown") }),
+    onSome: (exit) =>
+      Exit.match(exit, {
+        onFailure: (cause) => ({ failure: failureOf(cause), state: "failed" }),
+        onSuccess: (value) =>
+          Option.match(decodeEnd(value), { onNone: () => ({ state: "unknown" }), onSome: endedWith }),
+      }),
+  });
+};
+
+/** A row as a step; none when its start is not a step's, such as an activity of the app's own by that name. */
+const stepOf = (row: StepRow): Option.Option<ComputerStep> =>
+  Option.map(Option.flatMap(successOf(row.start), decodeStart), (start) => ({
+    command: start.command,
+    computer: start.computer,
+    job: row.job,
+    name: row.name,
+    startedAt: start.startedAt,
+    step: start.key,
+    timeoutSeconds: start.timeoutSeconds,
+    ...settledOf(row),
+  }));
+
+const withoutOutput = (step: ComputerStep): ComputerStep => Struct.omit(step, ["stderr", "stdout", "truncated"]);
+
+/** The actor's steps, newest first, without their output. */
+const stepsPage = ({
+  limit = stepPage,
+  sql,
+}: StepPage & { readonly sql: SqlClient.SqlClient }): Sql<readonly ComputerStep[]> =>
+  Effect.map(sql.unsafe<StepRow>(stepRows("1"), [limit]), (rows) =>
+    Arr.map(Arr.getSomes(Arr.map(rows, stepOf)), withoutOutput),
+  );
+
+/** One step by its key, with its output when it ran. */
+const stepByKey = ({
+  sql,
+  step,
+}: {
+  readonly sql: SqlClient.SqlClient;
+  readonly step: string;
+}): Sql<Option.Option<ComputerStep>> =>
+  Effect.map(sql.unsafe<StepRow>(stepRows("instr(start, ?) > 0"), [step, largestPage]), (rows) =>
+    Arr.findFirst(Arr.getSomes(Arr.map(rows, stepOf)), (found) => found.step === step),
+  );
+
+export { stepByKey, stepsPage };

package/src/host/computer/job-computers.service.ts

@@ -0,0 +1,84 @@
+import { Config, Context, Effect, Layer, Option, Ref } from "effect";
+
+import { ActorComputerClients } from "#src/contract/computer/computer-client.adapter";
+import type { ComputerAddress, ComputerClient } from "#src/contract/computer/computer-client.contract";
+import { ComputersUnavailableError } from "#src/contract/computer/computers-unavailable.errors";
+
+type Clients = ActorComputerClients["Service"];
+
+const unbound = ComputersUnavailableError.make({ message: "computers aren't available on this host" });
+
+/** Each operation reaches the clients bound when it runs, so a host bound after the app was built still answers. */
+const clientThrough = (current: Effect.Effect<Clients, ComputersUnavailableError>) => {
+  const connected = (address: ComputerAddress): Effect.Effect<ComputerClient, ComputersUnavailableError> =>
+    Effect.map(current, (clients) => clients.connect(address));
+
+  return (address: ComputerAddress): ComputerClient => {
+    const client = connected(address);
+
+    return {
+      ensure: (spec) => Effect.flatMap(client, (bound) => bound.ensure(spec)),
+      exec: (computer, request) => Effect.flatMap(client, (bound) => bound.exec(computer, request)),
+      files: (computer, request) => Effect.flatMap(client, (bound) => bound.files(computer, request)),
+      fork: (computer, fork) => Effect.flatMap(client, (bound) => bound.fork(computer, fork)),
+      get: (computer) => Effect.flatMap(client, (bound) => bound.get(computer)),
+      list: Effect.flatMap(client, (bound) => bound.list),
+      pause: (computer, hold) => Effect.flatMap(client, (bound) => bound.pause(computer, hold)),
+      remove: (computer) => Effect.flatMap(client, (bound) => bound.remove(computer)),
+      resume: (computer, hold) => Effect.flatMap(client, (bound) => bound.resume(computer, hold)),
+      stop: (computer) => Effect.flatMap(client, (bound) => bound.stop(computer)),
+    };
+  };
+};
+
+/**
+ * Whether the local engine runs computers: off unless `AKTER_LOCAL_COMPUTERS` is `true`, because a local computer runs
+ * its steps on this machine. Off, the app's jobs see no computers, as before the local engine had them.
+ */
+const localComputersOn = Config.Boolean("AKTER_LOCAL_COMPUTERS").pipe(Config.withDefault(false));
+
+const make = Effect.gen(function* makeJobComputers() {
+  const bound = yield* Ref.make(Option.none<Clients>());
+  const current = Effect.flatMap(Ref.get(bound), (found) => Effect.mapError(Effect.fromOption(found), () => unbound));
+
+  const clients = ActorComputerClients.of({
+    connect: clientThrough(current),
+    logs: (address, computer, page) => Effect.flatMap(current, (found) => found.logs(address, computer, page)),
+  });
+
+  return {
+    bind: (host: Clients): Effect.Effect<void> => Ref.set(bound, Option.some(host)),
+    clients,
+  };
+});
+
+/**
+ * The computers a job runtime's activities reach through `Actor.computer(key)`: whichever the engine hosting the app
+ * bound last. Job handlers keep the context the app layer was built in, and the app is built before the engine that
+ * hosts it, so the engine binds its computers here once it knows where they live, as the local engine does for each
+ * environment it serves. Until one binds, every call fails with `ComputersUnavailableError`. `Akter.jobs` and
+ * `Akter.local` share one through the layer memo, as they share the job engine. Its layer gives the app these
+ * computers only while `AKTER_LOCAL_COMPUTERS` is on; off, it gives none, so computers another layer provides stay
+ * visible and `Actor.computer(key)` answers as on a host without computers.
+ */
+export class JobComputers extends Context.Service<
+  JobComputers,
+  {
+    readonly bind: (clients: Clients) => Effect.Effect<void>;
+    readonly clients: Clients;
+  }
+>()("@akterjs/effect/host/computer/job-computers.service/JobComputers") {
+  public static readonly layer: Layer.Layer<JobComputers> = Layer.effectContext(
+    Effect.gen(function* buildJobComputers() {
+      const computers = yield* make;
+      const on = yield* Effect.orDie(localComputersOn);
+      const context = Context.make(JobComputers, computers);
+
+      if (!on) {
+        return context;
+      }
+
+      return Context.add(context, ActorComputerClients, computers.clients);
+    }),
+  );
+}