@gjermundgaraba/clankerbox-sdk 0.15.6 → 0.16.0

package/dist/{client-BkZhmYJx.mjs → client-CLemHDCl.mjs}

@@ -1,21 +1,33 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
 import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
-import { Context, Duration, Effect, Fiber, Match, Predicate, Result, Schema, SchemaIssue } from "effect";
+import { Context, Duration, Effect, Fiber, Layer, Match, Predicate, Result, Schema, SchemaIssue } from "effect";
 import { HttpClient, HttpClientRequest } from "effect/http";
 //#region src/errors.ts
+/** A host sends none of these; the client library sets them. */
+const located = {
+	host: Schema.optionalKey(Schema.String),
+	action: Schema.optionalKey(Schema.String),
+	id: Schema.optionalKey(Schema.String)
+};
 /**
-* The seven errors every clankerbox call can fail with. `retryable` is derived from the
-* tag, so callers never keep their own table of which failures to repeat.
+* The request is malformed, or the host list is one a client can't route by, or a config,
+* profile or setup file couldn't be read or doesn't hold what it should: then `file` names it.
 */
-/** The request is malformed: a bad ID or name, an undeclared field, a value out of range. */
-var Invalid = class extends Schema.TaggedError()("Invalid", { message: Schema.String }, { httpApiStatus: 400 }) {
+var Invalid = class extends Schema.TaggedError()("Invalid", {
+	message: Schema.String,
+	...located,
+	file: Schema.optionalKey(Schema.String)
+}, { httpApiStatus: 400 }) {
 	get retryable() {
 		return false;
 	}
 };
 /** The machine or checkpoint doesn't exist. A `delete` that meets it is done. */
-var NotFound = class extends Schema.TaggedError()("NotFound", { message: Schema.String }, { httpApiStatus: 404 }) {
+var NotFound = class extends Schema.TaggedError()("NotFound", {
+	message: Schema.String,
+	...located
+}, { httpApiStatus: 404 }) {
 	get retryable() {
 		return false;
 	}
@@ -24,43 +36,53 @@ const ConflictKind = Schema.Literals(["exists", "busy"]);
 /** The name is taken (`exists`), or another action holds the resource (`busy`). */
 var Conflict = class extends Schema.TaggedError()("Conflict", {
 	message: Schema.String,
-	kind: ConflictKind
+	kind: ConflictKind,
+	...located
 }, { httpApiStatus: 409 }) {
 	get retryable() {
 		return this.kind === "busy";
 	}
 };
 /** The resource's state doesn't allow the action, or no host offers the requested base. */
-var Precondition = class extends Schema.TaggedError()("Precondition", { message: Schema.String }, { httpApiStatus: 412 }) {
+var Precondition = class extends Schema.TaggedError()("Precondition", {
+	message: Schema.String,
+	...located
+}, { httpApiStatus: 412 }) {
 	get retryable() {
 		return false;
 	}
 };
 /** The host has no room now; room can free up, so a later call may succeed. */
-var Capacity = class extends Schema.TaggedError()("Capacity", { message: Schema.String }, { httpApiStatus: 503 }) {
+var Capacity = class extends Schema.TaggedError()("Capacity", {
+	message: Schema.String,
+	...located
+}, { httpApiStatus: 503 }) {
 	get retryable() {
 		return true;
 	}
 };
 /**
-* The client couldn't reach the host, or lost its reply. Only the client library produces
-* it. `readOnly` is that of the action that met it: a mutation's request may have reached
-* the host and run, so it is never retryable.
+* No reply: only the client library makes it. A mutation's request may have reached the host
+* and run, so it is retryable only when `readOnly`.
 */
 var Unavailable = class extends Schema.TaggedError()("Unavailable", {
 	message: Schema.String,
-	readOnly: Schema.Boolean
+	readOnly: Schema.Boolean,
+	...located
 }) {
 	get retryable() {
 		return this.readOnly;
 	}
 };
-var Internal = class extends Schema.TaggedError()("Internal", { message: Schema.String }, { httpApiStatus: 500 }) {
+var Internal = class extends Schema.TaggedError()("Internal", {
+	message: Schema.String,
+	...located
+}, { httpApiStatus: 500 }) {
 	get retryable() {
 		return false;
 	}
 };
-/** What a host answers with; every action declares these. */
+/** What a host may answer with; each action declares its own share. */
 const hostErrors = [
 	Invalid,
 	NotFound,
@@ -69,20 +91,13 @@ const hostErrors = [
 	Capacity,
 	Internal
 ];
-/** The tag a host records on a failed action: always one of the errors it answers with. */
+const ClankerboxError = Schema.Union([...hostErrors, Unavailable]);
 const HostErrorTag = Schema.Literals(hostErrors.map((error) => error.fields._tag.schema.literal));
-/** The tag of any error a call through the client library can fail with. */
-const ErrorTag = Schema.Literals([...HostErrorTag.literals, Unavailable.fields._tag.schema.literal]);
 //#endregion
 //#region src/ids.ts
-/**
-* Machine and checkpoint IDs, `<host>_<name>`: the one place that parses and formats them.
-* Neither part contains `_`, so an ID has exactly one. The whole ID matches
-* `^[A-Za-z0-9_-]{1,62}$` because it is written to `/var/lib/clankerbox/machine-id`, and
-* clankercreds accepts only that pattern.
-*/
 const separator = "_";
 const maxIdLength = 62;
+/** The ID is written to `/var/lib/clankerbox/machine-id`, and clankercreds accepts only this. */
 const idPattern = /^[A-Za-z0-9_-]{1,62}$/u;
 /**
 * boat's named snapshots are `cbx-<host>-<inst>`, and boat allows `^[a-z0-9][a-z0-9-]{0,62}$`:
@@ -96,9 +111,8 @@ const hostIdRule = "a host ID is 1 to 32 lowercase letters, digits and '-', star
 */
 const namePattern = /^[A-Za-z][A-Za-z0-9]*(?:-[A-Za-z0-9]+)*$/u;
 const nameRule = "a name starts with a letter, then letters, digits and '-', with no '--' and no '-' at the end";
-/** A host's part of every ID it holds. */
 const HostId = Schema.String.check(Schema.isPattern(hostIdPattern, { message: hostIdRule }));
-/** A machine's or checkpoint's name, unique per host and per resource type. */
+/** Unique per host and per resource type. */
 const Name = Schema.String.check(Schema.isPattern(namePattern, { message: nameRule }));
 const describeId = (id) => {
 	if (!idPattern.test(id)) return `ID ${JSON.stringify(id)} must be 1 to ${maxIdLength} letters, digits, '_' or '-'`;
@@ -107,9 +121,8 @@ const describeId = (id) => {
 	if (!hostIdPattern.test(id.slice(0, at))) return `ID ${JSON.stringify(id)} has an invalid host: ${hostIdRule}`;
 	if (!namePattern.test(id.slice(at + 1))) return `ID ${JSON.stringify(id)} has an invalid name: ${nameRule}`;
 };
-/** A full `<host>_<name>` ID. */
+/** `<host>_<name>`: neither part contains `_`, so an ID has exactly one. */
 const Id = Schema.String.check(Schema.makeFilter((id) => describeId(id) ?? true));
-/** Splits an ID at its `_` into host and name. */
 const parseId = (id) => {
 	const problem = describeId(id);
 	if (problem !== void 0) return Effect.fail(new Invalid({ message: problem }));
@@ -119,20 +132,15 @@ const parseId = (id) => {
 		name: id.slice(at + 1)
 	});
 };
-/** Checks a name on its own, before it is joined to a host. */
 const parseName = (name) => namePattern.test(name) ? Effect.succeed(name) : Effect.fail(new Invalid({ message: `name ${JSON.stringify(name)}: ${nameRule}` }));
-/** Joins a host ID and a name into the resource's ID, checking both parts and the whole. */
+/** Checks both parts and the whole. */
 const formatId = (host, name) => {
 	if (!hostIdPattern.test(host)) return Effect.fail(new Invalid({ message: `host ID ${JSON.stringify(host)}: ${hostIdRule}` }));
 	const id = `${host}${separator}${name}`;
 	return parseName(name).pipe(Effect.andThen(parseId(id)), Effect.as(id));
 };
 //#endregion
-//#region package.json
-var version$1 = "0.15.6";
-//#endregion
 //#region src/resources.ts
-/** The resources a host reports: machines, checkpoints and the host itself. */
 const Runtime = Schema.Literals([
 	"smolvm",
 	"tart",
@@ -149,23 +157,27 @@ const ActionName = Schema.Literals([
 	"restore",
 	"capture"
 ]);
-/**
-* A resource's last action: `running` while it holds the row, `failed` with its error
-* after a native failure, `done` after a success. The next action replaces it.
-*/
-const ActionRecord = Schema.Struct({
-	name: ActionName,
-	status: Schema.Literals([
-		"running",
-		"failed",
-		"done"
-	]),
-	error: Schema.optionalKey(Schema.Struct({
+const ActionStatus = Schema.Literals([
+	"running",
+	"failed",
+	"done"
+]);
+const actionRecord = (name) => Schema.Union([Schema.Struct({
+	name,
+	status: Schema.Literals(["running", "done"])
+}), Schema.Struct({
+	name,
+	status: Schema.Literal("failed"),
+	error: Schema.Struct({
 		tag: HostErrorTag,
 		message: Schema.String
-	}))
-});
-/** Where a machine's guest port 22 is reached. */
+	})
+})]);
+/** A resource's last action; the next action replaces it. */
+const ActionRecord = actionRecord(ActionName);
+/** A checkpoint is only ever captured or deleted. */
+const CheckpointActionName = Schema.Literals(["capture", "delete"]);
+const CheckpointActionRecord = actionRecord(CheckpointActionName);
 const SshEndpoint = Schema.Struct({
 	host: Schema.String,
 	port: Schema.Int.check(Schema.isBetween({
@@ -173,7 +185,6 @@ const SshEndpoint = Schema.Struct({
 		maximum: 65535
 	}))
 });
-/** Where a running machine's SSH is reached, and the guest user its runtime's logins are for. */
 const SshLogin = Schema.Struct({
 	user: Schema.String,
 	...SshEndpoint.fields
@@ -183,63 +194,51 @@ const Machine = Schema.Struct({
 	runtime: Runtime,
 	createdAt: Schema.DateTimeUtcFromString,
 	base: Schema.String,
-	/** The label the client passed at create, normally its profile's name. */
 	profile: Schema.optionalKey(Schema.String),
 	cpu: Size,
 	ramMib: Size,
 	diskGib: Size,
-	/**
-	* Read from the runtime, never stored: `missing` when the runtime doesn't have the machine,
-	* `unknown` when it couldn't be read.
-	*/
+	/** `missing`: the runtime doesn't have it; `unknown`: it couldn't be read. */
 	state: Schema.Literals([
 		"running",
 		"stopped",
 		"missing",
 		"unknown"
 	]),
-	/**
-	* Whether its create, fork or restore has made it. One that isn't made, because that action
-	* still runs or failed, can only be read, stopped or deleted.
-	*/
+	/** Until its create, fork or restore has made it, it can only be read, stopped or deleted. */
 	made: Schema.Boolean,
 	action: ActionRecord,
 	/** Only on a running machine whose runtime gives it an endpoint. */
 	ssh: Schema.optionalKey(SshLogin),
-	/** The guest's SSH host public key, as `<type> <base64>`, once preparation has recorded it. */
+	/** `<type> <base64>`, once preparation has recorded it. */
 	hostKey: Schema.optionalKey(Schema.String)
 }).annotate({ identifier: "Machine" });
 const Checkpoint = Schema.Struct({
 	id: Id,
 	createdAt: Schema.DateTimeUtcFromString,
-	/** The ID of the machine it was captured from. */
 	machine: Id,
-	/** What it holds, by runtime: `ram` (RAM and disks) on smolvm, `disk` on Tart and boat. */
+	/** `ram` (RAM and disks) on smolvm, `disk` on Tart and boat. */
 	kind: Schema.Literals(["ram", "disk"]),
 	base: Schema.String,
 	profile: Schema.optionalKey(Schema.String),
 	cpu: Size,
 	ramMib: Size,
 	diskGib: Size,
-	action: ActionRecord
+	action: CheckpointActionRecord
 }).annotate({ identifier: "Checkpoint" });
-/** The SDK's version, which is also the version of the clankerbox binaries it ships with. */
-const version = version$1;
-/** A version's major.minor: releases that share it speak the same API. */
-const release = (of) => of.split(".").slice(0, 2).join(".");
 const Host = Schema.Struct({
 	id: HostId,
 	runtime: Runtime,
-	/** The clankerbox version the host runs. */
 	version: Schema.String,
-	/** The runtime's version; for boat, its API version. */
+	/** For boat, its API version. */
 	runtimeVersion: Schema.String,
+	/** The state a machine must be in to be captured: Tart's is `stopped`. */
+	captureFrom: Schema.Literals(["running", "stopped"]),
 	bases: Schema.Array(Schema.String)
 }).annotate({ identifier: "Host" });
 /**
-* One limit a host's `Capacity` refusals come from, and how much of it is in use, counted as
-* the refusal counts it, so `used` needn't match the host's own machines. Read from the runtime,
-* never stored.
+* `used` is counted as a `Capacity` refusal counts it, so it needn't match the host's own
+* machines.
 */
 const Limit = Schema.Struct({
 	host: HostId,
@@ -258,10 +257,7 @@ const Limit = Schema.Struct({
 	limit: Schema.Int,
 	used: Schema.Int
 }).annotate({ identifier: "Limit" });
-/**
-* A setup script and how long it may run, the host's default when it doesn't say. Nothing logs
-* the script: it can carry secrets.
-*/
+/** Nothing logs the script: it can carry secrets. */
 const Setup = Schema.Struct({
 	script: Schema.String,
 	timeoutSeconds: Schema.optionalKey(Size)
@@ -274,117 +270,97 @@ const specFields = {
 	setup: Schema.optionalKey(Setup),
 	profile: Schema.optionalKey(Schema.String)
 };
-/**
-* What a new machine is made from: a base, its sizes, an optional setup script with its
-* timeout, and an optional `profile` label. A profile file fills these in; the host never
-* sees the profile itself.
-*/
+/** A profile file fills these in; the host sees only the `profile` label. */
 const MachineSpec = Schema.Struct(specFields);
-/**
-* `machine.create`'s input: the spec and the new machine's full ID. The host checks that the ID
-* names it, so a create never lands under another host's ID.
-*/
+/** The host checks that `id` names it, so a create never lands under another host's ID. */
 const CreateRequest = Schema.Struct({
 	id: Id,
 	...specFields
 });
-/**
-* A profile file: a client-side file that fills in a create request. `setup.path` is a script
-* file or a recipe directory, relative to the profile file; without a `timeoutSeconds` the host's
-* default applies. `host` places the create on that host instead of by base.
-*/
-const Profile = Schema.Struct({
-	base: specFields.base,
-	cpu: specFields.cpu,
-	ramMib: specFields.ramMib,
-	diskGib: specFields.diskGib,
-	setup: Schema.optionalKey(Schema.Struct({
-		path: Schema.String,
-		timeoutSeconds: Schema.optionalKey(Size)
-	})),
-	host: Schema.optionalKey(HostId)
-});
 //#endregion
 //#region src/api.ts
-/**
-* The host API: one effect-actions binding, each action a JSON POST route at `/api/<action>`.
-* A mutation replies when its action has finished. Every action is public: a host listens
-* only on the tailnet or loopback.
-*/
-/**
-* How long a client waits for a read's reply from one host, unless it sets its own. A host
-* bounds its own reads of runtime state under it, so a list answers in time.
-*/
+/** A host bounds its own reads of runtime state under it, so a list answers in time. */
 const readTimeout = Duration.seconds(10);
-/**
-* The header every client request carries the SDK's `version` in. A host refuses a request
-* whose release (major.minor) differs from its own, or that carries none, before it runs
-* anything.
-*/
-const versionHeader = "clankerbox-version";
 const ById = Schema.Struct({ id: Id });
-/** Input of the actions that make a new resource from a machine: its ID and the new name. */
 const FromMachine = Schema.Struct({
 	machine: Id,
 	name: Name
 });
-/**
-* What every action shares, by whether it reads or changes the host. Every action declares
-* `hostErrors`, so a client decodes the `Invalid` the host's version check answers with.
-*/
+/** Every action is public, as a host listens only on the tailnet or loopback. */
 const read = {
 	caller: Action.Anyone,
-	error: hostErrors,
 	readOnly: true
 };
 const write = {
 	caller: Action.Anyone,
-	error: hostErrors,
 	readOnly: false
 };
+/** What each action fails with; each has `Invalid`, which the host's version check answers. */
+const listing = [Invalid, Internal];
+const reading = [
+	Invalid,
+	NotFound,
+	Internal
+];
+const changing = [
+	Invalid,
+	NotFound,
+	Conflict,
+	Precondition,
+	Internal
+];
+const takingRoom = [...changing, Capacity];
 const Http = ActionHttp.make([
 	Action.make("listMachines", {
 		...read,
+		error: listing,
 		description: "List the host's machines.",
 		success: Schema.Array(Machine)
 	}),
 	Action.make("getMachine", {
 		...read,
+		error: reading,
 		description: "Read one machine.",
 		input: ById,
 		success: Machine
 	}),
 	Action.make("createMachine", {
 		...write,
+		error: takingRoom,
 		description: "Create a machine from a base, run its setup once, and prepare it.",
 		input: CreateRequest,
 		success: Machine
 	}),
 	Action.make("startMachine", {
 		...write,
+		error: takingRoom,
 		description: "Start a machine. On a running machine, run preparation again.",
 		input: ById,
 		success: Machine
 	}),
 	Action.make("stopMachine", {
 		...write,
-		description: "Stop a machine. A stopped machine stays stopped, and the stop is still its last action.",
+		error: changing,
+		description: "Stop a machine: a power-off that keeps its disk and ends its processes. A stopped machine stays stopped, and the stop is still its last action.",
 		input: ById,
 		success: Machine
 	}),
 	Action.make("deleteMachine", {
 		...write,
+		error: changing,
 		description: "Delete a machine and everything native it owns.",
 		input: ById
 	}),
 	Action.make("forkMachine", {
 		...write,
+		error: takingRoom,
 		description: "Copy a machine to a new name on the same host.",
 		input: FromMachine,
 		success: Machine
 	}),
 	Action.make("restoreMachine", {
 		...write,
+		error: takingRoom,
 		description: "Create a machine on the checkpoint's host from that checkpoint.",
 		input: Schema.Struct({
 			checkpoint: Id,
@@ -394,66 +370,74 @@ const Http = ActionHttp.make([
 	}),
 	Action.make("listCheckpoints", {
 		...read,
+		error: listing,
 		description: "List the host's checkpoints.",
 		success: Schema.Array(Checkpoint)
 	}),
 	Action.make("getCheckpoint", {
 		...read,
+		error: reading,
 		description: "Read one checkpoint.",
 		input: ById,
 		success: Checkpoint
 	}),
 	Action.make("captureCheckpoint", {
 		...write,
+		error: takingRoom,
 		description: "Capture a checkpoint of a machine. Its kind follows the runtime: ram on smolvm, which captures only a running machine, and disk on Tart and boat.",
 		input: FromMachine,
 		success: Checkpoint
 	}),
 	Action.make("deleteCheckpoint", {
 		...write,
+		error: changing,
 		description: "Delete a checkpoint.",
 		input: ById
 	}),
 	Action.make("getHost", {
 		...read,
+		error: [Invalid],
 		description: "Read the host: its runtime, versions and bases.",
 		success: Host
 	}),
 	Action.make("getCapacity", {
 		...read,
+		error: [
+			Invalid,
+			Precondition,
+			Internal
+		],
 		description: "Read the host's limits and how much of each is in use. It fails when the runtime can't be read.",
 		success: Schema.Array(Limit)
 	})
 ], { prefix: "/api" });
+const actionsByName = Action.byName(Http.actions);
+//#endregion
+//#region src/release.ts
+/** Also the version of the clankerbox binaries it ships with. */
+const version = "0.16.0";
+/** major.minor: releases that share it speak the same API. */
+const release = (of) => of.split(".").slice(0, 2).join(".");
+/** A host refuses a request whose `release` differs from its own, or that has none. */
+const versionHeader = "clankerbox-version";
 //#endregion
 //#region src/text.ts
-/** How sizes, decode failures and file failures read in a message or a table cell. */
 const mibPerGib = 1024;
-/**
-* A RAM size, exactly, as a size flag takes one: GiB when it is whole or half GiB, `32G` or
-* `1.5G`, and MiB when it isn't, `512M` or `1500M`.
-*/
-const formatMib = (mib) => mib >= mibPerGib && mib % (mibPerGib / 2) === 0 ? `${mib / mibPerGib}G` : `${mib}M`;
-/**
-* Where a decode failed, as a JSON path: `hosts[0].id`. `names` gives a top-level field the
-* name its caller knows it by.
-*/
+/** Exactly, as a size flag takes it: `32G`, `1.5G`, `512M`, `1500M`. */
+const formatMib = (mib) => mib >= 1024 && mib % 512 === 0 ? `${mib / mibPerGib}G` : `${mib}M`;
 const jsonPath = (path, names) => path.map((key, index) => {
 	if (Number.isInteger(key)) return `[${String(key)}]`;
 	return index === 0 ? names?.get(key) ?? String(key) : `.${String(key)}`;
 }).join("");
 const flatten = SchemaIssue.makeFormatterStandardSchemaV1({ leafHook: (issue) => Match.value(issue).pipe(Match.tag("MissingKey", () => "missing"), Match.tag("UnexpectedKey", () => "not a known field"), Match.orElse(SchemaIssue.defaultLeafHook)) });
-/**
-* Everything a decode refused, on one line, each under its JSON path: `cpu: missing; ram: not a
-* known field`. `names` renames top-level fields, as when a flag set each: `--cpu: missing`.
-*/
+/** On one line: `cpu: missing; ram: not a known field`. `names` renames top-level fields. */
 const describeIssues = (error, names) => flatten(error.issue).issues.map(({ path = [], message }) => {
 	const keys = path.map((segment) => Predicate.isPropertyKey(segment) ? segment : segment.key);
 	return keys.length === 0 ? message : `${jsonPath(keys, names)}: ${message}`;
 }).join("; ");
 /**
-* Why a file couldn't be read, without the platform call that met it. Node describes a failure
-* only in its cause, so what has no wording here reads as the system's own.
+* Node describes a failure only in its cause, so what has no wording here reads as the system's
+* own.
 */
 const describeFileError = ({ reason }) => {
 	if (Predicate.isTagged(reason, "NotFound")) return "no such file or directory";
@@ -462,47 +446,38 @@ const describeFileError = ({ reason }) => {
 };
 //#endregion
 //#region src/client.ts
-/**
-* The client library: a host list in placement order, routing by ID, list fan-out and
-* create placement. Nothing here retries: a mutation whose reply is lost, or that outlasts
-* the client's mutation timeout, is `Unavailable`, and the caller reads the resource to see
-* what happened.
-*/
 var client_exports = /* @__PURE__ */ __exportAll({
 	Client: () => Client,
 	HostEntry: () => HostEntry,
+	layer: () => layer,
 	make: () => make
 });
-/** One host a client talks to. `id` is the host part of every ID it holds. */
+/** `id` is the host part of every ID the host holds. */
 const HostEntry = Schema.Struct({
 	id: HostId,
 	url: Schema.String.check(Schema.makeFilter((url) => URL.canParse(url) || "a URL, such as http://linux:8484"))
 });
+/**
+* Nothing retries: a mutation whose reply is lost or times out is `Unavailable`, and the caller
+* reads the resource to see what happened.
+*/
 var Client = class extends Context.Service()("@gjermundgaraba/clankerbox-sdk/Client") {};
 /**
-* A client for one host. Every request carries the SDK's version, which the host checks
-* against its own. Input that doesn't encode fails as `InvalidInput` before anything is
-* sent, so a `SchemaError` that reaches `settle` is a reply that didn't decode.
+* Input that doesn't encode fails as `InvalidInput` before anything is sent, so a `SchemaError`
+* that reaches `settle` is a reply that didn't decode.
 */
-const makeHostApi = (entry) => ActionHttp.client(Http, {
+const hostApi = (entry) => ActionHttp.client(Http, {
 	baseUrl: entry.url,
 	transformClient: HttpClient.mapRequest(HttpClientRequest.setHeader(versionHeader, version))
 });
-/** Every action's contract, by name: a call's timeout and retry follow its `readOnly`. */
-const actions = Action.byName(Http.actions);
 const causeDetail = (error) => error.cause instanceof Error ? error.cause.message : error.message;
-/**
-* No reply came: the connection failed or dropped, or the timeout passed. A mutation's
-* request may or may not have reached its host, so it may have run.
-*/
 const unanswered = (context, detail) => context.readOnly ? new Unavailable({
-	message: `host ${context.host.id} (${context.host.url}) didn't answer ${context.action}: ${detail}`,
-	readOnly: context.readOnly
+	message: `host ${context.host.id} (${context.host.url}) didn't answer ${context.what}: ${detail}`,
+	readOnly: true
 }) : new Unavailable({
-	message: `no reply from host ${context.host.id} to ${context.action} (${detail}); the action may have run: read ${context.target ?? "the resource"} to see`,
-	readOnly: context.readOnly
+	message: `no reply from host ${context.host.id} to ${context.what} (${detail}); the action may have run: read ${context.target ?? "the resource"} to see`,
+	readOnly: false
 });
-/** Bounds the wait for the reply; the clock starts when the request is sent. */
 const bounded = (call, context) => {
 	const { timeout } = context;
 	return timeout === void 0 ? call : Effect.timeoutOrElse(call, {
@@ -510,32 +485,36 @@ const bounded = (call, context) => {
 		orElse: () => Effect.fail(unanswered(context, `timed out after ${Duration.format(timeout)}`))
 	});
 };
-/** The host answered with something the call doesn't expect. */
-const unexpected = (context, error) => new Internal({ message: `host ${context.host.id} answered ${context.action} unexpectedly: ${error.message}` });
+const unexpected = (context, error) => new Internal({ message: `host ${context.host.id} answered ${context.what} unexpectedly: ${error.message}` });
 const settle = (call, context) => bounded(call, context).pipe(Effect.catchTags({
 	HttpClientError: (error) => Effect.fail(Match.value(error.reason).pipe(Match.tag("TransportError", () => unanswered(context, causeDetail(error))), Match.when({
 		_tag: "DecodeError",
 		cause: (cause) => cause !== void 0 && !(cause instanceof SyntaxError)
 	}, () => unanswered(context, causeDetail(error))), Match.orElse(() => unexpected(context, error)))),
-	InvalidInput: (error) => Effect.fail(new Invalid({ message: `${context.action}: the request doesn't match the action's input: ${error.message}` })),
+	InvalidInput: (error) => Effect.fail(new Invalid({ message: `${context.what}: the request doesn't match the action's input: ${error.message}` })),
 	SchemaError: (error) => Effect.fail(new Internal({ message: `host ${context.host.id}'s reply didn't decode: ${error.message}` })),
 	Unauthenticated: (error) => Effect.fail(unexpected(context, error)),
 	Forbidden: (error) => Effect.fail(unexpected(context, error))
 }));
-/** A host this client can use: it calls itself by its entry's ID. */
+const encodeError = Schema.encodeSync(ClankerboxError);
+const decodeError = Schema.decodeSync(ClankerboxError);
+/** The error with the call's location set, and every other field it had. */
+const locate = (where) => (error) => decodeError({
+	...encodeError(error),
+	...where
+});
 const checkHost = (entry, host) => host.id === entry.id ? Effect.succeed(host) : Effect.fail(new Invalid({ message: `host ${entry.id} (${entry.url}) calls itself ${host.id}; its entry in the host list must use that ID` }));
-/** Every entry is checked here, so a call never meets a malformed URL. */
 const decodeHosts = Schema.decodeUnknownEffect(Schema.Array(HostEntry));
 /**
-* Builds a client over `hosts`, in placement order. Making it sends nothing. An empty list
-* is Invalid, and so is a malformed entry or a host ID that appears twice: IDs route by it.
+* A client over `hosts`, in placement order. It sends nothing until called. An empty list, a
+* malformed entry or a host ID that appears twice is Invalid.
 */
 const make = (hosts, options) => Effect.gen(function* () {
 	if (hosts.length === 0) return yield* new Invalid({ message: "the host list is empty: a client needs a host" });
 	yield* decodeHosts(hosts, { errors: "all" }).pipe(Effect.mapError((error) => new Invalid({ message: `host list: ${describeIssues(error)}` })));
 	const twice = hosts.find(({ id }, index) => hosts.findIndex((other) => other.id === id) < index);
 	if (twice !== void 0) return yield* new Invalid({ message: `host ${twice.id} appears twice in the host list` });
-	const routed = yield* Effect.forEach(hosts, (entry) => Effect.map(makeHostApi(entry), (api) => ({
+	const routed = yield* Effect.forEach(hosts, (entry) => Effect.map(hostApi(entry), (api) => ({
 		entry,
 		api
 	})));
@@ -545,25 +524,34 @@ const make = (hosts, options) => Effect.gen(function* () {
 		return found === void 0 ? Effect.fail(new Invalid({ message: `host ${host} isn't in the host list` })) : Effect.succeed(found);
 	};
 	/**
-	* Sends one call to one host, bounded by the read or the mutation timeout. `target` is the
-	* ID to read when a mutation's reply is lost.
+	* A call of `name` on one host, about `subject`. Its errors carry the host, the action and
+	* `target`, the resource it reads, changes or makes.
 	*/
-	const ask = ({ entry, api }, { readOnly }, action, call, target) => settle(call(api), {
-		host: entry,
-		timeout: readOnly ? options?.readTimeout ?? readTimeout : options?.timeout,
-		readOnly,
-		action,
-		target
-	});
+	const send = ({ entry, api }, name, input, subject, target = subject) => {
+		const { readOnly } = actionsByName[name];
+		const method = api[name];
+		return settle(method(input), {
+			host: entry,
+			timeout: readOnly ? options?.readTimeout ?? readTimeout : options?.timeout,
+			readOnly,
+			what: subject === void 0 ? name : `${name} ${subject}`,
+			target
+		}).pipe(Effect.mapError(locate(target === void 0 ? {
+			action: name,
+			host: entry.id
+		} : {
+			action: name,
+			host: entry.id,
+			id: target
+		})));
+	};
 	/**
-	* Routes a call by the ID's host part: no network is needed to find the host. `made` is
-	* the ID of the resource the call makes, if any, which is what to read after a lost reply.
+	* A call of `name` on the host of `id`. A fork, restore or capture names the one it makes as
+	* `made`, which its errors then carry, so a caller can find what a failure left behind.
 	*/
-	const byId = (id, contract, action, call, made) => Effect.gen(function* () {
-		const { host } = yield* parseId(id);
-		return yield* ask(yield* route(host), contract, action, call, made ?? id);
-	});
-	/** Asks every host at once; a host that fails is named rather than failing the whole. */
+	const byId = (name, id, input, made) => Effect.flatMap(Effect.flatMap(parseId(id), ({ host }) => route(host)), (found) => send(found, name, input, id, made ?? id));
+	/** An error raised before the call is sent names its action too. */
+	const naming = (name) => (effect) => Effect.mapError(effect, (error) => error.action === void 0 ? locate({ action: name })(error) : error);
 	const gather = (call) => Effect.forEach(routed, (route) => Effect.map(Effect.result(call(route)), (result) => ({
 		host: route.entry.id,
 		result
@@ -580,30 +568,27 @@ const make = (hosts, options) => Effect.gen(function* () {
 			unreachable
 		};
 	}));
-	/**
-	* Reads a host. IDs route by its entry's ID, so a host that calls itself something else
-	* fails rather than being placed on.
-	*/
-	const readHost = (route) => ask(route, actions.getHost, "get host", (api) => Effect.flatMap(api.getHost(), (host) => checkHost(route.entry, host)));
+	const readHost = (route) => Effect.flatMap(send(route, "getHost", {}), (host) => checkHost(route.entry, host)).pipe(Effect.mapError(locate({
+		action: "getHost",
+		host: route.entry.id
+	})));
 	const createOn = (host, name, spec) => Effect.gen(function* () {
 		const id = yield* formatId(host, name);
-		return yield* ask(yield* route(host), actions.createMachine, `create ${id}`, (api) => api.createMachine({
+		return yield* send(yield* route(host), "createMachine", {
 			...spec,
 			id
-		}), id);
+		}, id);
 	});
 	/**
-	* Asks every host at once and goes through the answers in list order: the first host
-	* that answers and offers `base` wins, and the requests still out are interrupted, so a
-	* silent host after it delays nothing. With no winner the create is `Unavailable` only if
-	* a host gave no reply; otherwise asking again changes nothing, and it is `Precondition`.
+	* The first host in list order that offers `base`; the requests still out are interrupted,
+	* so a silent host after it delays nothing. With no winner it is `Unavailable` only if a
+	* host gave no reply: otherwise asking again changes nothing, and it is `Precondition`.
 	*/
 	const offering = (base) => Effect.gen(function* () {
 		const asked = yield* Effect.forEach(routed, (route) => Effect.map(Effect.forkScoped(Effect.result(readHost(route))), (fiber) => ({
 			host: route.entry.id,
 			fiber
 		})));
-		/** What each host answered, in list order. */
 		const misses = [];
 		let noReply = false;
 		for (const { host, fiber } of asked) {
@@ -629,34 +614,34 @@ const make = (hosts, options) => Effect.gen(function* () {
 		return yield* createOn((yield* offering(spec.base)).id, name, spec);
 	});
 	const place = (base, options) => options?.host === void 0 ? offering(base) : Effect.flatMap(route(options.host), readHost);
-	/** The ID a call that makes a resource on `source`'s host gives it. */
 	const sibling = (source, name) => Effect.flatMap(parseId(source), ({ host }) => formatId(host, name));
 	return {
 		hosts: gather((route) => Effect.map(readHost(route), (host) => [host])),
-		machines: gather((route) => ask(route, actions.listMachines, "list machines", (api) => api.listMachines())),
-		checkpoints: gather((route) => ask(route, actions.listCheckpoints, "list checkpoints", (api) => api.listCheckpoints())),
-		capacity: gather((route) => ask(route, actions.getCapacity, "get capacity", (api) => api.getCapacity())),
-		machine: (id) => byId(id, actions.getMachine, `get ${id}`, (api) => api.getMachine({ id })),
-		checkpoint: (id) => byId(id, actions.getCheckpoint, `get ${id}`, (api) => api.getCheckpoint({ id })),
-		place,
-		create,
-		start: (id) => byId(id, actions.startMachine, `start ${id}`, (api) => api.startMachine({ id })),
-		stop: (id) => byId(id, actions.stopMachine, `stop ${id}`, (api) => api.stopMachine({ id })),
-		delete: (id) => byId(id, actions.deleteMachine, `delete ${id}`, (api) => api.deleteMachine({ id })),
-		fork: (machine, name) => Effect.flatMap(sibling(machine, name), (made) => byId(machine, actions.forkMachine, `fork ${machine} to ${made}`, (api) => api.forkMachine({
+		machines: gather((route) => send(route, "listMachines", {})),
+		checkpoints: gather((route) => send(route, "listCheckpoints", {})),
+		capacity: gather((route) => send(route, "getCapacity", {})),
+		machine: (id) => naming("getMachine")(byId("getMachine", id, { id })),
+		checkpoint: (id) => naming("getCheckpoint")(byId("getCheckpoint", id, { id })),
+		place: (base, options) => naming("getHost")(place(base, options)),
+		create: (name, spec, options) => naming("createMachine")(create(name, spec, options)),
+		start: (id) => naming("startMachine")(byId("startMachine", id, { id })),
+		stop: (id) => naming("stopMachine")(byId("stopMachine", id, { id })),
+		delete: (id) => naming("deleteMachine")(byId("deleteMachine", id, { id })),
+		fork: (machine, name) => naming("forkMachine")(Effect.flatMap(sibling(machine, name), (made) => byId("forkMachine", machine, {
 			machine,
 			name
-		}), made)),
-		restore: (checkpoint, name) => Effect.flatMap(sibling(checkpoint, name), (made) => byId(checkpoint, actions.restoreMachine, `restore ${checkpoint} to ${made}`, (api) => api.restoreMachine({
+		}, made))),
+		restore: (checkpoint, name) => naming("restoreMachine")(Effect.flatMap(sibling(checkpoint, name), (made) => byId("restoreMachine", checkpoint, {
 			checkpoint,
 			name
-		}), made)),
-		capture: (machine, name) => Effect.flatMap(sibling(machine, name), (made) => byId(machine, actions.captureCheckpoint, `capture ${machine} to ${made}`, (api) => api.captureCheckpoint({
+		}, made))),
+		capture: (machine, name) => naming("captureCheckpoint")(Effect.flatMap(sibling(machine, name), (made) => byId("captureCheckpoint", machine, {
 			machine,
 			name
-		}), made)),
-		deleteCheckpoint: (id) => byId(id, actions.deleteCheckpoint, `delete ${id}`, (api) => api.deleteCheckpoint({ id }))
+		}, made))),
+		deleteCheckpoint: (id) => naming("deleteCheckpoint")(byId("deleteCheckpoint", id, { id }))
 	};
 });
+const layer = (hosts, options) => Layer.effect(Client, make(hosts, options));
 //#endregion
-export { parseName as A, Unavailable as B, release as C, Name as D, Id as E, HostErrorTag as F, Internal as I, Invalid as L, Conflict as M, ConflictKind as N, formatId as O, ErrorTag as P, NotFound as R, SshLogin as S, HostId as T, hostErrors as V, MachineSpec as _, describeIssues as a, Setup as b, readTimeout as c, ActionRecord as d, Checkpoint as f, Machine as g, Limit as h, describeFileError as i, Capacity as j, parseId as k, versionHeader as l, Host as m, client_exports as n, formatMib as o, CreateRequest as p, make as r, Http as s, Client as t, ActionName as u, Profile as v, version as w, SshEndpoint as x, Runtime as y, Precondition as z };
+export { Name as A, Invalid as B, MachineSpec as C, SshLogin as D, SshEndpoint as E, ClankerboxError as F, Precondition as H, Conflict as I, ConflictKind as L, parseId as M, parseName as N, HostId as O, Capacity as P, HostErrorTag as R, Machine as S, Setup as T, Unavailable as U, NotFound as V, hostErrors as W, CheckpointActionName as _, formatMib as a, Host as b, version as c, actionsByName as d, readTimeout as f, Checkpoint as g, ActionStatus as h, describeIssues as i, formatId as j, Id as k, versionHeader as l, ActionRecord as m, layer as n, mibPerGib as o, ActionName as p, describeFileError as r, release as s, client_exports as t, Http as u, CheckpointActionRecord as v, Runtime as w, Limit as x, CreateRequest as y, Internal as z };