@akterjs/effect 0.0.0-stage → 0.1.1

package/dist/contract/computer/computer.schema.mjs

@@ -0,0 +1,117 @@
+import { ComputerSecret } from "../secret/secret.schema.mjs";
+import { ComputerCopy, ComputerCopyResult, ComputerFileRequest, computerFileBytes } from "./files/computer-files.schema.mjs";
+import { Schema } from "effect";
+// src/contract/computer/computer.schema.ts
+const kib = 1024;
+const mib = kib * kib;
+const inputKib = 100;
+const outputMib = 4;
+const smallest = 1;
+const nothing = 0;
+/**
+* Archil's serverless exec limits, applied to every exec step so a step behaves the same in any engine: five
+* minutes, 100 KiB of command and standard input together, and 4 MiB of each output stream returned. Longer work
+* runs as a process in the computer; longer output belongs in files.
+*/
+const execLimits = {
+	inputBytes: inputKib * kib,
+	outputBytes: outputMib * mib,
+	seconds: 300
+};
+const encoder = new globalThis.TextEncoder();
+/** One of an actor's computers. Lowercase letters, digits and hyphens, starting with a letter. */
+const ComputerName = Schema.String.check(Schema.isPattern(new RegExp(`^[a-z][a-z0-9-]{0,62}$`, "u"))).pipe(Schema.brand("ComputerName")).annotate({ description: "A computer's name, unique among its actor's computers." });
+const Seconds = Schema.Int.check(Schema.isBetween({
+	maximum: execLimits.seconds,
+	minimum: smallest
+}));
+const Positive = Schema.Int.check(Schema.isGreaterThanOrEqualTo(smallest));
+const ComputerSize = Schema.Struct({
+	memoryMib: Positive,
+	vcpu: Positive
+});
+/**
+* A computer to keep: its image, its size and the hosts it may reach. `egress` lists hosts or rules, never
+* credentials. `secrets` names the credentials the platform adds to an allowed host's requests on the way out, from
+* the actor's declared secrets, so no value ever reaches the computer.
+*/
+const ComputerSpec = Schema.Struct({
+	egress: Schema.Array(Schema.String),
+	image: Schema.String,
+	name: ComputerName,
+	secrets: Schema.optionalKey(Schema.Array(ComputerSecret)),
+	size: ComputerSize
+});
+/**
+* Where a computer is. `paused` keeps its memory, processes and files; `stopped` and `failed` keep only its files;
+* `gone` means its disk no longer exists, so it is never recreated empty under the same name by accident.
+*/
+const ComputerState = Schema.Literals([
+	"starting",
+	"running",
+	"paused",
+	"stopped",
+	"failed",
+	"gone"
+]);
+const Computer = Schema.Struct({
+	...ComputerSpec.fields,
+	state: ComputerState
+});
+const withinInput = Schema.makeFilter((request) => encoder.encode(request.command).byteLength + (request.stdin?.byteLength ?? nothing) <= execLimits.inputBytes, { expected: `a command and standard input of at most ${execLimits.inputBytes} bytes together` });
+/**
+* One exec step. `key` is the step's stable logical-operation key, such as `Activity.idempotencyKey(name)`: the
+* computer records the outcome under it, so the same step sent again reads that outcome back instead of running.
+*/
+const ExecRequest = Schema.Struct({
+	command: Schema.String,
+	cwd: Schema.optionalKey(Schema.String),
+	key: Schema.String.check(Schema.isMinLength(smallest)),
+	stdin: Schema.optionalKey(Schema.Uint8Array),
+	timeoutSeconds: Schema.optionalKey(Seconds)
+}).check(withinInput);
+/**
+* The step ran to an end, or its recorded outcome was read back; the two look the same. `exitCode` is absent when
+* the process was ended without one, such as at the time limit. Past 4 MiB a stream, output is not returned and
+* `truncated` is set; the whole of each stream stays in the step's directory on the computer.
+*/
+const ExecRan = Schema.TaggedStruct("Ran", {
+	exitCode: Schema.optionalKey(Schema.Int),
+	stderr: Schema.String,
+	stdout: Schema.String,
+	truncated: Schema.Boolean
+});
+/**
+* The step started once but no outcome was recorded: the computer lost power, or the step is still running. It is
+* not run again, because whatever it did outside the computer may already have happened. Reconcile with the
+* outside system by the step's key.
+*/
+const ExecUnknown = Schema.TaggedStruct("Unknown", {});
+const ExecResult = Schema.Union([ExecRan, ExecUnknown]);
+/** How much a log page returns at most, and when a request names no limit. */
+const logPageLines = 1e3;
+/**
+* One line of a computer's log, oldest first: what the platform did to it (made, paused, resumed, stopped, forked,
+* deleted) and each exec step's key and outcome. `seq` rises by one per line of the computer, so a reader passes the
+* last `seq` it saw as `after` to read on.
+*/
+const ComputerLogLine = Schema.Struct({
+	at: Schema.Int,
+	level: Schema.Literals([
+		"info",
+		"warn",
+		"error"
+	]),
+	message: Schema.String,
+	seq: Schema.Int
+});
+const LogLimit = Schema.Int.check(Schema.isBetween({
+	maximum: logPageLines,
+	minimum: smallest
+}));
+/** A page of a computer's log: the lines after `after`, at most `limit` (1 to 1,000; 1,000 when absent). */
+const ComputerLogPage = Schema.Struct({
+	after: Schema.optionalKey(Schema.Int),
+	limit: Schema.optionalKey(LogLimit)
+});
+export { Computer, ComputerCopy, ComputerCopyResult, ComputerFileRequest, ComputerLogLine, ComputerLogPage, ComputerName, ComputerSecret, ComputerSize, ComputerSpec, ComputerState, ExecRan, ExecRequest, ExecResult, ExecUnknown, computerFileBytes, execLimits, logPageLines };

package/dist/contract/computer/computers-unavailable.errors.d.mts

@@ -0,0 +1,9 @@
+import { Schema } from "effect";
+declare const ComputersUnavailableError_base: Schema.Class<ComputersUnavailableError, Schema.TaggedStruct<"ComputersUnavailableError", {
+  readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError & {
+  readonly brand: unique symbol;
+}>;
+/** This engine runs no computers, or their provider didn't answer. */
+export declare class ComputersUnavailableError extends ComputersUnavailableError_base {}
+export {};

package/dist/contract/computer/computers-unavailable.errors.mjs

@@ -0,0 +1,5 @@
+import { Schema } from "effect";
+// src/contract/computer/computers-unavailable.errors.ts
+/** This engine runs no computers, or their provider didn't answer. */
+var ComputersUnavailableError = class extends Schema.TaggedError()("ComputersUnavailableError", { message: Schema.String }) {};
+export { ComputersUnavailableError };

package/dist/contract/computer/files/computer-files.schema.d.mts

@@ -0,0 +1,28 @@
+import { Schema } from "effect";
+/** One file per call, bounded before crossing the host/control link. Paths are relative to the computer's files directory. */
+declare const computerFileBytes = 1048576;
+declare const ComputerFileRequest: Schema.TaggedUnion<{
+  readonly Read: Schema.TaggedStruct<"Read", {
+    readonly path: Schema.String;
+  }>;
+  readonly Write: Schema.TaggedStruct<"Write", {
+    readonly content: Schema.Uint8ArrayFromBase64;
+    readonly path: Schema.String;
+  }>;
+}>;
+type ComputerFileRequest = typeof ComputerFileRequest.Type;
+declare const ComputerCopy: Schema.Struct<{
+  readonly computer: Schema.String;
+  readonly computerPath: Schema.String;
+  readonly direction: Schema.Literals<readonly ["toComputer", "fromComputer"]>;
+  readonly key: Schema.String;
+  readonly path: Schema.String;
+}>;
+type ComputerCopy = typeof ComputerCopy.Type;
+/** Copy-back returns an upload receipt; only an actor command can attach it to an actor path. */
+declare const ComputerCopyResult: Schema.Struct<{
+  readonly bytes: Schema.Int;
+  readonly receipt: Schema.optionalKey<Schema.String>;
+}>;
+type ComputerCopyResult = typeof ComputerCopyResult.Type;
+export { ComputerCopy, ComputerCopyResult, ComputerFileRequest, computerFileBytes };

package/dist/contract/computer/files/computer-files.schema.mjs

@@ -0,0 +1,24 @@
+import { Schema } from "effect";
+// src/contract/computer/files/computer-files.schema.ts
+/** One file per call, bounded before crossing the host/control link. Paths are relative to the computer's files directory. */
+const computerFileBytes = 1048576;
+const ComputerFileRequest = Schema.TaggedUnion({
+	Read: { path: Schema.String },
+	Write: {
+		content: Schema.Uint8ArrayFromBase64,
+		path: Schema.String
+	}
+});
+const ComputerCopy = Schema.Struct({
+	computer: Schema.String,
+	computerPath: Schema.String,
+	direction: Schema.Literals(["toComputer", "fromComputer"]),
+	key: Schema.String,
+	path: Schema.String
+});
+/** Copy-back returns an upload receipt; only an actor command can attach it to an actor path. */
+const ComputerCopyResult = Schema.Struct({
+	bytes: Schema.Int,
+	receipt: Schema.optionalKey(Schema.String)
+});
+export { ComputerCopy, ComputerCopyResult, ComputerFileRequest, computerFileBytes };

package/dist/contract/computer/rpc/computer-rpc.contract.d.mts

@@ -0,0 +1,108 @@
+import { ActorErasedError } from "../../actor/actor-erased.errors.mjs";
+import { ActorNotCreatedError } from "../../actor/actor-not-created.errors.mjs";
+import { ActorUnavailableError } from "../../client/actor-unavailable.errors.mjs";
+import { BillingUnavailableError } from "../../spend/billing-unavailable.errors.mjs";
+import { CallerNotAllowedError } from "../../caller/caller-not-allowed.errors.mjs";
+import { CommandIdExpiredError } from "../../command/command-id-expired.errors.mjs";
+import { HandlerFailedError } from "../../hosted/handler-failed.errors.mjs";
+import { InvalidRequestError } from "../../client/invalid-request.errors.mjs";
+import { SpendCapReachedError } from "../../spend/spend-cap-reached.errors.mjs";
+import { StorageLimitError } from "../../client/storage-limit.errors.mjs";
+import { ComputerHeldError } from "../computer-held.errors.mjs";
+import { ComputerLostError } from "../computer-lost.errors.mjs";
+import { ComputerNotFoundError } from "../computer-not-found.errors.mjs";
+import { ComputersUnavailableError } from "../computers-unavailable.errors.mjs";
+import { ComputerCopy, ComputerCopyResult } from "../files/computer-files.schema.mjs";
+import { Computer } from "../computer.schema.mjs";
+import { ComputerStep } from "../step/computer-step.schema.mjs";
+import { StepNotFoundError } from "../step/step-not-found.errors.mjs";
+import { Schema } from "effect";
+import { Rpc } from "effect/rpc";
+declare const ComputerRpcFailure: Schema.Union<readonly [Schema.Union<readonly [typeof ActorErasedError, typeof ActorNotCreatedError, typeof ActorUnavailableError, typeof BillingUnavailableError, typeof CallerNotAllowedError, typeof CommandIdExpiredError, typeof HandlerFailedError, typeof InvalidRequestError, typeof SpendCapReachedError, typeof StorageLimitError]>, typeof ComputerHeldError, typeof ComputerLostError, typeof ComputerNotFoundError, typeof ComputersUnavailableError, typeof StepNotFoundError]>;
+type ComputerRpcFailureSchema = typeof ComputerRpcFailure;
+type ComputerRpcFailureType = ComputerRpcFailureSchema["Type"];
+/** The actor's encoded key, as every actor RPC carries it. */
+declare const Keyed: {
+  key: Schema.String;
+};
+/** One computer of the actor, by name. */
+declare const Named: {
+  computer: Schema.String;
+  key: Schema.String;
+};
+declare const Logs: {
+  after: Schema.optionalKey<Schema.Int>;
+  limit: Schema.optionalKey<Schema.Int>;
+  computer: Schema.String;
+  key: Schema.String;
+};
+/** A page of the actor's durable steps. */
+declare const Paged: {
+  limit: Schema.optionalKey<Schema.Int>;
+  key: Schema.String;
+};
+/** One durable step of the actor, by its key. */
+declare const Stepped: {
+  key: Schema.String;
+  step: Schema.String;
+};
+declare const Computers: Schema.$Array<Schema.Struct<{
+  readonly egress: Schema.$Array<Schema.String>;
+  readonly image: Schema.String;
+  readonly name: Schema.brand<Schema.String, "ComputerName">;
+  readonly secrets: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+    readonly header: Schema.String;
+    readonly host: Schema.String;
+    readonly prefix: Schema.optionalKey<Schema.String>;
+    readonly secret: Schema.String;
+  }>>>;
+  readonly size: Schema.Struct<{
+    readonly memoryMib: Schema.Int;
+    readonly vcpu: Schema.Int;
+  }>;
+  readonly state: Schema.Literals<readonly ["starting", "running", "paused", "stopped", "failed", "gone"]>;
+}>>;
+declare const Steps: Schema.$Array<Schema.Struct<{
+  readonly command: Schema.String;
+  readonly computer: Schema.String;
+  readonly endedAt: Schema.optionalKey<Schema.Int>;
+  readonly exitCode: Schema.optionalKey<Schema.Int>;
+  readonly failure: Schema.optionalKey<Schema.String>;
+  readonly job: Schema.String;
+  readonly name: Schema.String;
+  readonly startedAt: Schema.Int;
+  readonly state: Schema.Literals<readonly ["running", "ran", "unknown", "failed"]>;
+  readonly stderr: Schema.optionalKey<Schema.String>;
+  readonly stdout: Schema.optionalKey<Schema.String>;
+  readonly step: Schema.String;
+  readonly timeoutSeconds: Schema.Int;
+  readonly truncated: Schema.optionalKey<Schema.Boolean>;
+}>>;
+declare const LogLines: Schema.$Array<Schema.Struct<{
+  readonly at: Schema.Int;
+  readonly level: Schema.Literals<readonly ["info", "warn", "error"]>;
+  readonly message: Schema.String;
+  readonly seq: Schema.Int;
+}>>;
+/** Moves a computer to a state and answers it as it is then. */
+type ComputerMove = "pause" | "resume" | "stop";
+type ComputerRpcOperation = ComputerMove | "delete" | "files" | "get" | "list" | "logs" | "step" | "steps";
+type ComputerTag<Operation extends ComputerRpcOperation = ComputerRpcOperation, Actor extends string = string> = `${Actor}/computer/${Operation}`;
+declare const computerTag: <Operation extends ComputerRpcOperation, Actor extends string>({ actor, operation }: {
+  readonly actor: Actor;
+  readonly operation: Operation;
+}) => ComputerTag<Operation, Actor>;
+type NamedRpc<Operation extends ComputerRpcOperation, Success extends Schema.Top, Actor extends string> = Rpc.Rpc<ComputerTag<Operation, Actor>, Schema.Struct<typeof Named>, Success, ComputerRpcFailureSchema>;
+/** One computer RPC of the actor named `Actor`, so a client of a known actor sends exact tags. */
+type ComputerRpc<Actor extends string = string> = Rpc.Rpc<ComputerTag<"files", Actor>, typeof ComputerCopy, typeof ComputerCopyResult, ComputerRpcFailureSchema> | Rpc.Rpc<ComputerTag<"list", Actor>, Schema.Struct<typeof Keyed>, typeof Computers, ComputerRpcFailureSchema> | Rpc.Rpc<ComputerTag<"logs", Actor>, Schema.Struct<typeof Logs>, typeof LogLines, ComputerRpcFailureSchema> | Rpc.Rpc<ComputerTag<"steps", Actor>, Schema.Struct<typeof Paged>, typeof Steps, ComputerRpcFailureSchema> | Rpc.Rpc<ComputerTag<"step", Actor>, Schema.Struct<typeof Stepped>, typeof ComputerStep, ComputerRpcFailureSchema> | NamedRpc<"delete", typeof Schema.Void, Actor> | NamedRpc<"get", typeof Computer, Actor> | NamedRpc<"pause", typeof Computer, Actor> | NamedRpc<"resume", typeof Computer, Actor> | NamedRpc<"stop", typeof Computer, Actor>;
+/**
+ * An actor's computers as seen from outside the actor, under the tags docs/adr/0016 reserves:
+ * `<Actor>/computer/<operation>`. Every payload carries the actor's encoded key. `list` and `get` answer computers as
+ * they are; `pause`, `resume` and `stop` drive one there and answer it, and a `resume` of a computer a fork holds
+ * fails with `ComputerHeldError`; `delete` removes one with its disk and answers nothing, so a client confirms it
+ * first; `logs` reads a page of its log. There is no outside `exec` and no `ensure`: only the actor makes and runs
+ * its computers. `steps` reads a page of the actor's durable steps, newest first, and `step` one step by its key with its
+ * output (`StepNotFoundError` when the journal has none); both read the actor's own journal, not a computer.
+ */
+declare const computerRpcsOf: <Actor extends string>(actor: Actor) => readonly ComputerRpc<Actor>[];
+export { type ComputerMove, type ComputerRpc, type ComputerRpcFailureType, type ComputerRpcOperation, type ComputerTag, computerRpcsOf, computerTag };

package/dist/contract/computer/rpc/computer-rpc.contract.mjs

@@ -0,0 +1,117 @@
+import { HostedFailure } from "../../hosted/hosted-failure.schema.mjs";
+import { ComputerHeldError } from "../computer-held.errors.mjs";
+import { ComputerLostError } from "../computer-lost.errors.mjs";
+import { ComputerNotFoundError } from "../computer-not-found.errors.mjs";
+import { ComputersUnavailableError } from "../computers-unavailable.errors.mjs";
+import { Computer, ComputerLogLine, ComputerLogPage } from "../computer.schema.mjs";
+import { ComputerCopy, ComputerCopyResult } from "../files/computer-files.schema.mjs";
+import { ComputerStep, StepPage } from "../step/computer-step.schema.mjs";
+import { StepNotFoundError } from "../step/step-not-found.errors.mjs";
+import { Schema } from "effect";
+import { Rpc } from "effect/rpc";
+// src/contract/computer/rpc/computer-rpc.contract.ts
+const ComputerRpcFailure = Schema.Union([
+	HostedFailure,
+	ComputerHeldError,
+	ComputerLostError,
+	ComputerNotFoundError,
+	ComputersUnavailableError,
+	StepNotFoundError
+]);
+/** The actor's encoded key, as every actor RPC carries it. */
+const Keyed = { key: Schema.String };
+/** One computer of the actor, by name. */
+const Named = {
+	computer: Schema.String,
+	key: Schema.String
+};
+const Logs = {
+	...Named,
+	...ComputerLogPage.fields
+};
+/** A page of the actor's durable steps. */
+const Paged = {
+	...Keyed,
+	...StepPage.fields
+};
+/** One durable step of the actor, by its key. */
+const Stepped = {
+	key: Schema.String,
+	step: Schema.String
+};
+const Computers = Schema.Array(Computer);
+const Steps = Schema.Array(ComputerStep);
+const LogLines = Schema.Array(ComputerLogLine);
+const computerTag = ({ actor, operation }) => `${actor}/computer/${operation}`;
+const named = (actor, operation) => Rpc.make(computerTag({
+	actor,
+	operation
+}), {
+	error: ComputerRpcFailure,
+	payload: Named,
+	success: Computer
+});
+/**
+* An actor's computers as seen from outside the actor, under the tags docs/adr/0016 reserves:
+* `<Actor>/computer/<operation>`. Every payload carries the actor's encoded key. `list` and `get` answer computers as
+* they are; `pause`, `resume` and `stop` drive one there and answer it, and a `resume` of a computer a fork holds
+* fails with `ComputerHeldError`; `delete` removes one with its disk and answers nothing, so a client confirms it
+* first; `logs` reads a page of its log. There is no outside `exec` and no `ensure`: only the actor makes and runs
+* its computers. `steps` reads a page of the actor's durable steps, newest first, and `step` one step by its key with its
+* output (`StepNotFoundError` when the journal has none); both read the actor's own journal, not a computer.
+*/
+const computerRpcsOf = (actor) => [
+	Rpc.make(computerTag({
+		actor,
+		operation: "files"
+	}), {
+		error: ComputerRpcFailure,
+		payload: ComputerCopy,
+		success: ComputerCopyResult
+	}),
+	Rpc.make(computerTag({
+		actor,
+		operation: "list"
+	}), {
+		error: ComputerRpcFailure,
+		payload: Keyed,
+		success: Computers
+	}),
+	named(actor, "get"),
+	named(actor, "pause"),
+	named(actor, "resume"),
+	named(actor, "stop"),
+	Rpc.make(computerTag({
+		actor,
+		operation: "delete"
+	}), {
+		error: ComputerRpcFailure,
+		payload: Named,
+		success: Schema.Void
+	}),
+	Rpc.make(computerTag({
+		actor,
+		operation: "logs"
+	}), {
+		error: ComputerRpcFailure,
+		payload: Logs,
+		success: LogLines
+	}),
+	Rpc.make(computerTag({
+		actor,
+		operation: "steps"
+	}), {
+		error: ComputerRpcFailure,
+		payload: Paged,
+		success: Steps
+	}),
+	Rpc.make(computerTag({
+		actor,
+		operation: "step"
+	}), {
+		error: ComputerRpcFailure,
+		payload: Stepped,
+		success: ComputerStep
+	})
+];
+export { computerRpcsOf, computerTag };

package/dist/contract/computer/step/computer-step.contract.d.mts

@@ -0,0 +1,21 @@
+import { ComputerClient } from "../computer-client.contract.mjs";
+import { ExecResult } from "../computer.schema.mjs";
+import { ComputerClientFailure } from "../computer-client-failure.contract.mjs";
+import { StepRequest } from "./computer-step.schema.mjs";
+import { Effect } from "effect";
+import { WorkflowEngine } from "effect/workflow";
+/**
+ * Runs one command in one of the actor's computers as a durable step of the job that calls it, and answers its
+ * outcome. The step journals where it runs, its key and when it started before it sends anything, then its outcome,
+ * so `akter steps` reads it from the actor. A job replayed after a host or control plane restart reads both back: a
+ * settled step answers its journaled outcome without reaching the computer, and a step cut off mid-flight sends the
+ * same key again, which reads the command's own recorded outcome back and never runs it a second time. A command whose
+ * outcome no send could read before its deadline answers `Unknown`; reconcile it with the outside system by its key.
+ * Call it from a job, never from inside an activity, and give each step of a job its own name.
+ */
+declare const step: ({ client, computer, request }: {
+  readonly client: ComputerClient;
+  readonly computer: string;
+  readonly request: StepRequest;
+}) => Effect.Effect<ExecResult, ComputerClientFailure, WorkflowEngine.WorkflowEngine | WorkflowEngine.WorkflowInstance>;
+export { step };

package/dist/contract/computer/step/computer-step.contract.mjs

@@ -0,0 +1,89 @@
+import { ActorUnavailableError } from "../../client/actor-unavailable.errors.mjs";
+import { ComputersUnavailableError } from "../computers-unavailable.errors.mjs";
+import { ExecRan, ExecUnknown, execLimits } from "../computer.schema.mjs";
+import { StepEnd, StepStart } from "./computer-step.schema.mjs";
+import { StepFailure } from "./step-failure.schema.mjs";
+import { Clock, Duration, Effect, Schedule, Schema, Struct } from "effect";
+import { Activity } from "effect/workflow";
+// src/contract/computer/step/computer-step.contract.ts
+/**
+* How long past its own time limit a step keeps asking for its outcome, measured from when it was first journaled: the
+* time between journaling and the computer starting the command, which a lost reply or a restart can stretch.
+*/
+const graceSeconds = 10;
+/** How often a step asks again while its computer is unreachable or its command has no outcome yet. */
+const askEverySeconds = 2;
+const millis = 1e3;
+const none = 0;
+/** The step was sent before and its command has no recorded outcome yet: it may still be running. */
+var NoOutcomeYetError = class extends Schema.TaggedError()("NoOutcomeYetError", {}) {};
+/** Failures that say nothing about the step: the engine or control plane between the job and the computer is away. */
+const isPassing = Schema.is(Schema.Union([
+	ActorUnavailableError,
+	ComputersUnavailableError,
+	NoOutcomeYetError
+]));
+const isRan = Schema.is(ExecRan);
+const sentOnce = (client, request, start) => {
+	const sent = client.exec(start.computer, {
+		...Struct.omit(request, ["name"]),
+		key: start.key,
+		timeoutSeconds: start.timeoutSeconds
+	});
+	return Effect.filterOrFail(sent, isRan, () => NoOutcomeYetError.make({}));
+};
+/**
+* Sends the step under its key until it has an outcome, asking again while its computer is unreachable or its command
+* runs on past a lost reply, until its time limit and the grace have passed since it was first journaled. The key
+* makes every send after the first read the command's outcome back instead of running it again. Past the deadline with
+* no outcome the step is `Unknown`: it may have done its work, and it never runs again.
+*/
+const settled = (client, request, start) => Effect.gen(function* settledStep() {
+	const now = yield* Clock.currentTimeMillis;
+	const deadline = start.startedAt + (start.timeoutSeconds + graceSeconds) * millis;
+	const remaining = Duration.millis(Math.max(none, deadline - now));
+	const asking = Schedule.spaced(Duration.seconds(askEverySeconds)).pipe(Schedule.upTo({ duration: remaining }));
+	const outcome = yield* sentOnce(client, request, start).pipe(Effect.retry({
+		schedule: asking,
+		while: isPassing
+	}), Effect.catchIf(isPassing, () => Effect.succeed(ExecUnknown.make({}))));
+	return {
+		endedAt: yield* Clock.currentTimeMillis,
+		outcome
+	};
+});
+const started = (computer, request) => Effect.gen(function* startedStep() {
+	const key = yield* Activity.idempotencyKey(`step/${request.name}`);
+	const startedAt = yield* Clock.currentTimeMillis;
+	const timeoutSeconds = request.timeoutSeconds ?? execLimits.seconds;
+	return {
+		command: request.command,
+		computer,
+		key,
+		startedAt,
+		timeoutSeconds
+	};
+});
+/**
+* Runs one command in one of the actor's computers as a durable step of the job that calls it, and answers its
+* outcome. The step journals where it runs, its key and when it started before it sends anything, then its outcome,
+* so `akter steps` reads it from the actor. A job replayed after a host or control plane restart reads both back: a
+* settled step answers its journaled outcome without reaching the computer, and a step cut off mid-flight sends the
+* same key again, which reads the command's own recorded outcome back and never runs it a second time. A command whose
+* outcome no send could read before its deadline answers `Unknown`; reconcile it with the outside system by its key.
+* Call it from a job, never from inside an activity, and give each step of a job its own name.
+*/
+const step = ({ client, computer, request }) => Effect.gen(function* durableStep() {
+	const start = yield* Activity.make({
+		execute: started(computer, request),
+		name: `step-start/${request.name}`,
+		success: StepStart
+	});
+	return (yield* Activity.make({
+		error: StepFailure,
+		execute: settled(client, request, start),
+		name: `step/${request.name}`,
+		success: StepEnd
+	})).outcome;
+});
+export { step };

package/dist/contract/computer/step/computer-step.schema.d.mts

@@ -0,0 +1,69 @@
+import { Schema } from "effect";
+declare const stepPage = 100;
+declare const largestPage = 1000;
+/**
+ * One durable step of a job (`step` on an actor's computers): the exec request without its key, which the step derives from its job and
+ * name, so the same step in a replayed job sends the same key.
+ */
+declare const StepRequest: Schema.Struct<{
+  readonly command: Schema.String;
+  readonly cwd: Schema.optionalKey<Schema.String>;
+  readonly name: Schema.String;
+  readonly stdin: Schema.optionalKey<Schema.Uint8Array>;
+  readonly timeoutSeconds: Schema.optionalKey<Schema.Int>;
+}>;
+type StepRequest = typeof StepRequest.Type;
+/** What a step journals before it sends anything: where it runs, its key, and when it first started. */
+declare const StepStart: Schema.Struct<{
+  readonly command: Schema.String;
+  readonly computer: Schema.String;
+  readonly key: Schema.String;
+  readonly startedAt: Schema.Int;
+  readonly timeoutSeconds: Schema.Int;
+}>;
+type StepStart = typeof StepStart.Type;
+/** What a step journals once it settles: its outcome, and when it settled. */
+declare const StepEnd: Schema.Struct<{
+  readonly endedAt: Schema.Int;
+  readonly outcome: Schema.Union<readonly [Schema.TaggedStruct<"Ran", {
+    readonly exitCode: Schema.optionalKey<Schema.Int>;
+    readonly stderr: Schema.String;
+    readonly stdout: Schema.String;
+    readonly truncated: Schema.Boolean;
+  }>, Schema.TaggedStruct<"Unknown", {}>]>;
+}>;
+type StepEnd = typeof StepEnd.Type;
+/**
+ * Where a step is. `running` has no outcome yet; `ran` ended with its exit code and output; `unknown` started and has no
+ * recorded outcome, so it may or may not have done its work, and is never run again; `failed` could not run, such as on
+ * a lost computer.
+ */
+declare const StepState: Schema.Literals<readonly ["running", "ran", "unknown", "failed"]>;
+type StepState = typeof StepState.Type;
+/**
+ * One step as the actor's journal holds it. `step` is its key, the id a reader asks for it by and the key an outside
+ * system reconciles an `unknown` step with. Output is only in a single step's read.
+ */
+declare const ComputerStep: Schema.Struct<{
+  readonly command: Schema.String;
+  readonly computer: Schema.String;
+  readonly endedAt: Schema.optionalKey<Schema.Int>;
+  readonly exitCode: Schema.optionalKey<Schema.Int>;
+  readonly failure: Schema.optionalKey<Schema.String>;
+  readonly job: Schema.String;
+  readonly name: Schema.String;
+  readonly startedAt: Schema.Int;
+  readonly state: Schema.Literals<readonly ["running", "ran", "unknown", "failed"]>;
+  readonly stderr: Schema.optionalKey<Schema.String>;
+  readonly stdout: Schema.optionalKey<Schema.String>;
+  readonly step: Schema.String;
+  readonly timeoutSeconds: Schema.Int;
+  readonly truncated: Schema.optionalKey<Schema.Boolean>;
+}>;
+type ComputerStep = typeof ComputerStep.Type;
+/** A page of an actor's steps, newest first: at most `limit` (1 to 1,000; 100 when absent). */
+declare const StepPage: Schema.Struct<{
+  readonly limit: Schema.optionalKey<Schema.Int>;
+}>;
+type StepPage = typeof StepPage.Type;
+export { ComputerStep, StepEnd, StepPage, StepRequest, StepStart, StepState, largestPage, stepPage };

package/dist/contract/computer/step/computer-step.schema.mjs

@@ -0,0 +1,71 @@
+import { ExecRequest, ExecResult } from "../computer.schema.mjs";
+import { Schema } from "effect";
+// src/contract/computer/step/computer-step.schema.ts
+const smallest = 1;
+const stepPage = 100;
+const largestPage = 1e3;
+/** A step's name, unique among its job's steps: lowercase letters, digits, dots, underscores and hyphens. */
+const StepName = Schema.String.check(Schema.isPattern(new RegExp(`^[a-z0-9][a-z0-9._-]{0,62}$`, "u"))).annotate({ description: "A step's name, unique among its job's steps." });
+const { command, cwd, stdin, timeoutSeconds } = ExecRequest.fields;
+/**
+* One durable step of a job (`step` on an actor's computers): the exec request without its key, which the step derives from its job and
+* name, so the same step in a replayed job sends the same key.
+*/
+const StepRequest = Schema.Struct({
+	command,
+	cwd,
+	name: StepName,
+	stdin,
+	timeoutSeconds
+});
+/** What a step journals before it sends anything: where it runs, its key, and when it first started. */
+const StepStart = Schema.Struct({
+	command: Schema.String,
+	computer: Schema.String,
+	key: Schema.String,
+	startedAt: Schema.Int,
+	timeoutSeconds: Schema.Int
+});
+/** What a step journals once it settles: its outcome, and when it settled. */
+const StepEnd = Schema.Struct({
+	endedAt: Schema.Int,
+	outcome: ExecResult
+});
+/**
+* Where a step is. `running` has no outcome yet; `ran` ended with its exit code and output; `unknown` started and has no
+* recorded outcome, so it may or may not have done its work, and is never run again; `failed` could not run, such as on
+* a lost computer.
+*/
+const StepState = Schema.Literals([
+	"running",
+	"ran",
+	"unknown",
+	"failed"
+]);
+/**
+* One step as the actor's journal holds it. `step` is its key, the id a reader asks for it by and the key an outside
+* system reconciles an `unknown` step with. Output is only in a single step's read.
+*/
+const ComputerStep = Schema.Struct({
+	command: Schema.String,
+	computer: Schema.String,
+	endedAt: Schema.optionalKey(Schema.Int),
+	exitCode: Schema.optionalKey(Schema.Int),
+	failure: Schema.optionalKey(Schema.String),
+	job: Schema.String,
+	name: Schema.String,
+	startedAt: Schema.Int,
+	state: StepState,
+	stderr: Schema.optionalKey(Schema.String),
+	stdout: Schema.optionalKey(Schema.String),
+	step: Schema.String,
+	timeoutSeconds: Schema.Int,
+	truncated: Schema.optionalKey(Schema.Boolean)
+});
+const StepLimit = Schema.Int.check(Schema.isBetween({
+	maximum: largestPage,
+	minimum: smallest
+}));
+/** A page of an actor's steps, newest first: at most `limit` (1 to 1,000; 100 when absent). */
+const StepPage = Schema.Struct({ limit: Schema.optionalKey(StepLimit) });
+export { ComputerStep, StepEnd, StepPage, StepRequest, StepStart, StepState, largestPage, stepPage };