@gjermundgaraba/clankerbox-sdk 0.15.1 → 0.15.3

package/dist/{client-SX6jTU1R.d.mts → client-Cn1bj4It.d.mts}

@@ -297,6 +297,11 @@ interface Interface {
   readonly capacity: Effect.Effect<Gathered<Limit>>;
   readonly machine: (id: string) => Effect.Effect<Machine, ClankerboxError>;
   readonly checkpoint: (id: string) => Effect.Effect<Checkpoint, ClankerboxError>;
+  /**
+   * The host a create of `base` goes to: the options' host, or else the first host in the list
+   * that offers the base. It is read either way, so a caller knows its runtime before it creates.
+   */
+  readonly place: (base: string, options?: CreateOptions) => Effect.Effect<Host, ClankerboxError>;
   /**
    * Creates a machine named `name` on the options' host, or else on the first host in the
    * list that offers the spec's base.
@@ -320,4 +325,4 @@ declare class Client extends Client_base {}
  */
 declare const make: (hosts: ReadonlyArray<HostEntry>, options?: Options) => Effect.Effect<Interface, Invalid, HttpClient.HttpClient>;
 //#endregion
-export { Precondition as A, ConflictKind as C, Internal as D, HostErrorTag as E, hostErrors as M, Invalid as O, Conflict as S, HostError as T, SshLogin as _, ActionName as a, Capacity as b, CreateRequest as c, Machine as d, MachineSpec as f, SshEndpoint as g, Setup as h, client_d_exports as i, Unavailable as j, NotFound as k, Host as l, Runtime as m, HostEntry as n, ActionRecord as o, Profile as p, Options as r, Checkpoint as s, Client as t, Limit as u, release as v, ErrorTag as w, ClankerboxError as x, version as y };
+export { Invalid as A, ClankerboxError as C, HostError as D, ErrorTag as E, Precondition as M, Unavailable as N, HostErrorTag as O, hostErrors as P, Capacity as S, ConflictKind as T, Setup as _, Options as a, release as b, ActionRecord as c, Host as d, Limit as f, Runtime as g, Profile as h, Interface as i, NotFound as j, Internal as k, Checkpoint as l, MachineSpec as m, CreateOptions as n, client_d_exports as o, Machine as p, HostEntry as r, ActionName as s, Client as t, CreateRequest as u, SshEndpoint as v, Conflict as w, version as x, SshLogin as y };

package/dist/{client-DR7ytUZp.mjs → client-CtI-rSJQ.mjs}

@@ -1,7 +1,7 @@
 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 } from "effect";
+import { Context, Duration, Effect, Fiber, Match, Predicate, Result, Schema, SchemaIssue } from "effect";
 import { HttpClient, HttpClientRequest } from "effect/http";
 //#region src/errors.ts
 /**
@@ -129,7 +129,7 @@ const formatId = (host, name) => {
 };
 //#endregion
 //#region package.json
-var version$1 = "0.15.1";
+var version$1 = "0.15.3";
 //#endregion
 //#region src/resources.ts
 /** The resources a host reports: machines, checkpoints and the host itself. */
@@ -426,6 +426,41 @@ const Http = ActionHttp.make([
 	})
 ], { prefix: "/api" });
 //#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.
+*/
+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`.
+*/
+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.
+*/
+const describeFileError = ({ reason }) => {
+	if (Predicate.isTagged(reason, "NotFound")) return "no such file or directory";
+	if (Predicate.isTagged(reason, "PermissionDenied")) return "permission denied";
+	return reason.description ?? (reason.cause instanceof Error ? reason.cause.message : reason._tag);
+};
+//#endregion
 //#region src/client.ts
 /**
 * The client library: a host list in placement order, routing by ID, list fan-out and
@@ -497,7 +532,7 @@ const decodeHosts = Schema.decodeUnknownEffect(Schema.Array(HostEntry));
 */
 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).pipe(Effect.mapError((error) => new Invalid({ message: `host list: ${error.message}` })));
+	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) => ({
@@ -563,7 +598,7 @@ const make = (hosts, options) => Effect.gen(function* () {
 	* 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`.
 	*/
-	const place = (base) => Effect.gen(function* () {
+	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
@@ -575,8 +610,8 @@ const make = (hosts, options) => Effect.gen(function* () {
 			const result = yield* Fiber.join(fiber);
 			if (Result.isFailure(result)) {
 				noReply ||= Predicate.isTagged(result.failure, "Unavailable");
-				misses.push(`${host} failed: ${result.failure._tag}: ${result.failure.message}`);
-			} else if (result.success.bases.includes(base)) return host;
+				misses.push(`${host} failed: ${result.failure.message}`);
+			} else if (result.success.bases.includes(base)) return result.success;
 			else {
 				const { bases } = result.success;
 				misses.push(`${host} offers ${bases.length > 0 ? bases.join(", ") : "no bases"}`);
@@ -591,8 +626,9 @@ const make = (hosts, options) => Effect.gen(function* () {
 	const create = (name, spec, options) => Effect.gen(function* () {
 		yield* parseName(name);
 		if (options?.host !== void 0) return yield* createOn(options.host, name, spec);
-		return yield* createOn(yield* place(spec.base), name, spec);
+		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 {
@@ -602,6 +638,7 @@ const make = (hosts, options) => Effect.gen(function* () {
 		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 })),
@@ -622,4 +659,4 @@ const make = (hosts, options) => Effect.gen(function* () {
 	};
 });
 //#endregion
-export { ConflictKind as A, Id as C, parseName as D, parseId as E, NotFound as F, Precondition as I, Unavailable as L, HostErrorTag as M, Internal as N, Capacity as O, Invalid as P, hostErrors as R, HostId as S, formatId as T, Setup as _, readTimeout as a, release as b, ActionRecord as c, Host as d, Limit as f, Runtime as g, Profile as h, Http as i, ErrorTag as j, Conflict as k, Checkpoint as l, MachineSpec as m, client_exports as n, versionHeader as o, Machine as p, make as r, ActionName as s, Client as t, CreateRequest as u, SshEndpoint as v, Name as w, version as x, SshLogin as y };
+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 };

package/dist/index.d.mts

@@ -1,8 +1,7 @@
-import { A as Precondition, C as ConflictKind, D as Internal, E as HostErrorTag, M as hostErrors, O as Invalid, S as Conflict, T as HostError, _ as SshLogin, a as ActionName, b as Capacity, c as CreateRequest, d as Machine, f as MachineSpec, g as SshEndpoint, h as Setup, i as client_d_exports, j as Unavailable, k as NotFound, l as Host, m as Runtime, o as ActionRecord, p as Profile, s as Checkpoint, u as Limit, v as release, w as ErrorTag, x as ClankerboxError, y as version } from "./client-SX6jTU1R.mjs";
+import { A as Invalid, C as ClankerboxError, D as HostError, E as ErrorTag, M as Precondition, N as Unavailable, O as HostErrorTag, P as hostErrors, S as Capacity, T as ConflictKind, _ as Setup, b as release, c as ActionRecord, d as Host, f as Limit, g as Runtime, h as Profile, i as Interface, j as NotFound, k as Internal, l as Checkpoint, m as MachineSpec, n as CreateOptions, o as client_d_exports, p as Machine, s as ActionName, u as CreateRequest, v as SshEndpoint, w as Conflict, x as version, y as SshLogin } from "./client-Cn1bj4It.mjs";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
 import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
-import { Duration, Effect, FileSystem, Path, Schema } from "effect";
-import { ChildProcessSpawner } from "effect/process";
+import { Duration, Effect, FileSystem, Path, PlatformError, Schema } from "effect";
 //#region src/api.d.ts
 /**
  * How long a client waits for a read's reply from one host, unless it sets its own. A host
@@ -307,6 +306,54 @@ export declare const parseId: (id: string) => Effect.Effect<IdParts, Invalid>;
 export declare const parseName: (name: string) => Effect.Effect<string, Invalid>;
 /** Joins a host ID and a name into the resource's ID, checking both parts and the whole. */
 export declare const formatId: (host: string, name: string) => Effect.Effect<string, Invalid>;
+declare namespace prebuild_d_exports {
+  export { Built, Created, build, create, nameOf };
+}
+/**
+ * The name of the spec's prebuild on a host: a digest of the spec's label, base and sizes, the
+ * setup script as sent, and the host's runtime version. A `ram` checkpoint restores only under
+ * the release that saved it, so after a runtime bump a create misses the old prebuild instead
+ * of failing to restore it. The setup's timeout is no part of it, and neither is the base's
+ * image: a host only names it. The script holds whatever secrets a recipe carries, and the name
+ * 12 hex characters of a digest of it.
+ */
+declare const nameOf: (spec: MachineSpec, host: Pick<Host, "runtimeVersion">) => Effect.Effect<string>;
+interface Created {
+  readonly machine: Machine;
+  /** The prebuild the machine was restored from; without one, its setup ran. */
+  readonly prebuild?: Checkpoint | undefined;
+}
+/**
+ * Creates a machine named `name` as `client.create` does, but restores it from the spec's
+ * prebuild when the host it lands on has one whose capture is done. A spec without a setup has
+ * none. Placement is the create's own, and a prebuild stays on the host that made it, so a spec
+ * placed on another host runs its setup. A failed restore is the reply.
+ */
+declare const create: (client: Interface, name: string, spec: MachineSpec, options?: CreateOptions) => Effect.Effect<Created, ClankerboxError>;
+interface Built {
+  readonly checkpoint: Checkpoint;
+  /** Whether this call built it; false when it was already there. */
+  readonly built: boolean;
+  /**
+   * The ID of the machine that built it, when its delete failed: it may still run, holding its
+   * RAM, until it is deleted.
+   */
+  readonly leftover?: string | undefined;
+}
+/**
+ * Builds the spec's prebuild on the host a create of it lands on: a machine of its own runs the
+ * setup, is captured under the prebuild's name, and is deleted. smolvm captures a running
+ * machine, RAM included, and boat a running one too; Tart only a stopped one, so its machine is
+ * stopped first. A prebuild whose capture is done is the answer as it is; one that failed or is
+ * still captured is refused.
+ *
+ * Each build's machine has a random name of its own, and the host takes a checkpoint name once,
+ * so of two builds of one spec at once both run the setup and the second's capture is
+ * `Conflict`: neither touches the other's machine or prebuild. A build deletes its machine
+ * however it ends. If that fails after a failure, the first failure is the reply; after a
+ * capture, the prebuild is made, and the machine is the reply's `leftover`.
+ */
+declare const build: (client: Interface, spec: MachineSpec, options?: CreateOptions) => Effect.Effect<Built, ClankerboxError>;
 //#endregion
 //#region src/profile.d.ts
 /** A profile file as read: its fields, with `setup.path` resolved, and its name as `label`. */
@@ -322,12 +369,33 @@ export declare const loadProfile: (file: string) => Effect.Effect<LoadedProfile,
 //#endregion
 //#region src/setup.d.ts
 /**
- * Packs a recipe directory into one self-extracting script: a base64 tar that unpacks into a
- * temporary directory, then runs `setup.sh` from there. `COPYFILE_DISABLE=1` and
- * `--no-xattrs` keep macOS `tar` from adding `._*` files and provenance headers.
+ * Packs a recipe directory into one self-extracting script, which makes each of its entries
+ * with plain shell: a directory with `mkdir`, a symlink with `ln -s` as it is, and a file from
+ * base64, made executable when any of its execute bits is set. A symlink is never walked into,
+ * so nothing outside the recipe is packed, and in the guest nothing is written through one.
+ * Of a mode only the execute bit is kept, as git keeps it, so a checkout's umask changes
+ * nothing. Entries go in sorted order and nothing records a time or an owner, so the same
+ * files pack into the same script: a prebuild is named after it.
  */
-export declare const packRecipe: (directory: string) => Effect.Effect<string, Invalid, FileSystem.FileSystem | ChildProcessSpawner.ChildProcessSpawner>;
+export declare const packRecipe: (directory: string) => Effect.Effect<string, Invalid, FileSystem.FileSystem>;
 /** Reads a setup: a script file's text, or a recipe directory packed into one script. */
-export declare const readSetup: (path: string) => Effect.Effect<string, Invalid, FileSystem.FileSystem | ChildProcessSpawner.ChildProcessSpawner>;
+export declare const readSetup: (path: string) => Effect.Effect<string, Invalid, FileSystem.FileSystem>;
+//#endregion
+//#region src/text.d.ts
+/**
+ * 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`.
+ */
+export declare const formatMib: (mib: number) => string;
+/**
+ * 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`.
+ */
+export declare const describeIssues: (error: Schema.SchemaError, names?: ReadonlyMap<PropertyKey, string>) => string;
+/**
+ * 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.
+ */
+export declare const describeFileError: ({ reason }: PlatformError.PlatformError) => string;
 //#endregion
-export { ActionName, ActionRecord, Capacity, Checkpoint, ClankerboxError, client_d_exports as Client, Conflict, ConflictKind, CreateRequest, ErrorTag, Host, HostError, HostErrorTag, Internal, Invalid, Limit, Machine, MachineSpec, NotFound, Precondition, Profile, Runtime, Setup, SshEndpoint, SshLogin, Unavailable, hostErrors, release, version };
+export { ActionName, ActionRecord, Capacity, Checkpoint, ClankerboxError, client_d_exports as Client, Conflict, ConflictKind, CreateRequest, ErrorTag, Host, HostError, HostErrorTag, Internal, Invalid, Limit, Machine, MachineSpec, NotFound, prebuild_d_exports as Prebuild, Precondition, Profile, Runtime, Setup, SshEndpoint, SshLogin, Unavailable, hostErrors, release, version };

package/dist/index.mjs

@@ -1,6 +1,105 @@
-import { A as ConflictKind, C as Id, D as parseName, E as parseId, F as NotFound, I as Precondition, L as Unavailable, M as HostErrorTag, N as Internal, O as Capacity, P as Invalid, R as hostErrors, S as HostId, T as formatId, _ as Setup, a as readTimeout, b as release, c as ActionRecord, d as Host, f as Limit, g as Runtime, h as Profile, i as Http, j as ErrorTag, k as Conflict, l as Checkpoint, m as MachineSpec, n as client_exports, o as versionHeader, p as Machine, s as ActionName, u as CreateRequest, v as SshEndpoint, w as Name, x as version, y as SshLogin } from "./client-DR7ytUZp.mjs";
-import { Effect, FileSystem, Path, Predicate, Schema, Stream } from "effect";
-import { ChildProcess, ChildProcessSpawner } from "effect/process";
+import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
+import { A as parseName, B as Unavailable, C as release, D as Name, E as Id, F as HostErrorTag, I as Internal, L as Invalid, M as Conflict, N as ConflictKind, O as formatId, P as ErrorTag, R as NotFound, S as SshLogin, T as HostId, V as hostErrors, _ as MachineSpec, a as describeIssues, b as Setup, c as readTimeout, d as ActionRecord, f as Checkpoint, g as Machine, h as Limit, i as describeFileError, j as Capacity, k as parseId, l as versionHeader, m as Host, n as client_exports, o as formatMib, p as CreateRequest, s as Http, u as ActionName, v as Profile, w as version, x as SshEndpoint, y as Runtime, z as Precondition } from "./client-CtI-rSJQ.mjs";
+import { Effect, FileSystem, Option, Path, Predicate, Schema } from "effect";
+//#region src/prebuild.ts
+/**
+* Prebuilds: a checkpoint of a machine whose setup has run, which a create of the same spec
+* restores instead of running the setup again. They are the client's alone. A prebuild is an
+* ordinary checkpoint under a name derived from what it is of, so a host stores no profile and
+* knows nothing of them, and a create finds its prebuild with one read by ID. A prebuild never
+* changes and nothing here deletes one: building anew is a `checkpoint delete` first.
+*/
+var prebuild_exports = /* @__PURE__ */ __exportAll({
+	build: () => build,
+	create: () => create,
+	nameOf: () => nameOf
+});
+const prefix = "prebuilt-";
+/** How much of the digest a prebuild's name carries. */
+const digestDigits = 12;
+/**
+* How many random bytes a builder's name carries: 64 bits, so no two builds draw one name. With
+* `prebuilding-`, it is 28 characters, inside the 29 a 32-character host ID and its `_` leave of
+* an ID's 62.
+*/
+const builderBytes = 8;
+const hex = (bytes) => Array.from(new Uint8Array(bytes), (byte) => byte.toString(16).padStart(2, "0")).join("");
+/**
+* The name of the spec's prebuild on a host: a digest of the spec's label, base and sizes, the
+* setup script as sent, and the host's runtime version. A `ram` checkpoint restores only under
+* the release that saved it, so after a runtime bump a create misses the old prebuild instead
+* of failing to restore it. The setup's timeout is no part of it, and neither is the base's
+* image: a host only names it. The script holds whatever secrets a recipe carries, and the name
+* 12 hex characters of a digest of it.
+*/
+const nameOf = (spec, host) => Effect.promise(() => globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(JSON.stringify([
+	spec.profile ?? null,
+	spec.base,
+	spec.cpu,
+	spec.ramMib,
+	spec.diskGib,
+	spec.setup?.script ?? null,
+	host.runtimeVersion
+])))).pipe(Effect.map((digest) => `${prefix}${hex(digest).slice(0, digestDigits)}`));
+/** The checkpoint `id`, if the host has it. */
+const lookup = (client, id) => client.checkpoint(id).pipe(Effect.map(Option.some), Effect.catchTag("NotFound", () => Effect.succeedNone));
+/**
+* Creates a machine named `name` as `client.create` does, but restores it from the spec's
+* prebuild when the host it lands on has one whose capture is done. A spec without a setup has
+* none. Placement is the create's own, and a prebuild stays on the host that made it, so a spec
+* placed on another host runs its setup. A failed restore is the reply.
+*/
+const create = (client, name, spec, options) => Effect.gen(function* () {
+	if (spec.setup === void 0) return { machine: yield* client.create(name, spec, options) };
+	const host = yield* client.place(spec.base, options);
+	const id = yield* formatId(host.id, yield* nameOf(spec, host));
+	const found = yield* lookup(client, id);
+	if (Option.isSome(found) && found.value.action.status === "done") return {
+		machine: yield* client.restore(id, name),
+		prebuild: found.value
+	};
+	return { machine: yield* client.create(name, spec, { host: host.id }) };
+});
+/**
+* Builds the spec's prebuild on the host a create of it lands on: a machine of its own runs the
+* setup, is captured under the prebuild's name, and is deleted. smolvm captures a running
+* machine, RAM included, and boat a running one too; Tart only a stopped one, so its machine is
+* stopped first. A prebuild whose capture is done is the answer as it is; one that failed or is
+* still captured is refused.
+*
+* Each build's machine has a random name of its own, and the host takes a checkpoint name once,
+* so of two builds of one spec at once both run the setup and the second's capture is
+* `Conflict`: neither touches the other's machine or prebuild. A build deletes its machine
+* however it ends. If that fails after a failure, the first failure is the reply; after a
+* capture, the prebuild is made, and the machine is the reply's `leftover`.
+*/
+const build = (client, spec, options) => Effect.gen(function* () {
+	if (spec.setup === void 0) return yield* new Invalid({ message: "a prebuild needs a setup" });
+	const host = yield* client.place(spec.base, options);
+	const name = yield* nameOf(spec, host);
+	const id = yield* formatId(host.id, name);
+	const found = yield* lookup(client, id);
+	if (Option.isSome(found)) {
+		const { action } = found.value;
+		return action.status === "done" ? {
+			checkpoint: found.value,
+			built: false
+		} : yield* new Precondition({ message: `prebuild ${id}'s ${action.name} is ${action.status}; delete it to prebuild again` });
+	}
+	const builder = `prebuilding-${hex(globalThis.crypto.getRandomValues(new Uint8Array(builderBytes)))}`;
+	const builderId = yield* formatId(host.id, builder);
+	const removal = Effect.catchTag(client.delete(builderId), "NotFound", () => Effect.void);
+	return {
+		checkpoint: yield* Effect.gen(function* () {
+			yield* client.create(builder, spec, { host: host.id });
+			if (host.runtime === "tart") yield* client.stop(builderId);
+			return yield* client.capture(builderId, name);
+		}).pipe(Effect.onError(() => Effect.ignore(removal))),
+		built: true,
+		leftover: yield* removal.pipe(Effect.as(void 0), Effect.catch(() => Effect.succeed(builderId)))
+	};
+});
+//#endregion
 //#region src/profile.ts
 /** Reads a profile file for `create`. Hosts never see a profile. */
 /** Profile files are JSON, decoded with closed input like every call: unknown keys are refused. */
@@ -13,8 +112,11 @@ const decodeProfile = Schema.decodeUnknownEffect(Schema.fromJsonString(Profile))
 const loadProfile = (file) => Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
 	const path = yield* Path.Path;
-	const text = yield* fs.readFileString(file).pipe(Effect.mapError((error) => new Invalid({ message: `couldn't read profile ${file}: ${error.message}` })));
-	const profile = yield* decodeProfile(text, { onExcessProperty: "error" }).pipe(Effect.mapError((error) => new Invalid({ message: `profile ${file}: ${error.message}` })));
+	const text = yield* fs.readFileString(file).pipe(Effect.mapError((error) => new Invalid({ message: `couldn't read profile ${file}: ${describeFileError(error)}` })));
+	const profile = yield* decodeProfile(text, {
+		onExcessProperty: "error",
+		errors: "all"
+	}).pipe(Effect.mapError((error) => new Invalid({ message: `profile ${file}: ${describeIssues(error)}` })));
 	const label = path.basename(file, ".json");
 	return profile.setup === void 0 ? {
 		...profile,
@@ -36,71 +138,84 @@ const loadProfile = (file) => Effect.gen(function* () {
 * script. Nothing here logs a script or a packed recipe: a recipe can carry secrets.
 */
 const lineLength = 76;
-/** base64 has no `_`, so no line of the payload can end the here-document early. */
+/** base64 has no `_`, so no line of a file's payload can end its here-document early. */
 const terminator = "CLANKERBOX_RECIPE";
 const wrap = (base64) => {
 	const lines = [];
 	for (let at = 0; at < base64.length; at += lineLength) lines.push(base64.slice(at, at + lineLength));
 	return lines.join("\n");
 };
+/** A string as one single-quoted shell word, whatever it holds. */
+const quote = (text) => `'${text.replaceAll("'", `'\\''`)}'`;
+/**
+* An entry's path as a command's argument: under `./`, so a name that starts with `-` is never
+* read as an option.
+*/
+const argument = (entry) => quote(`./${entry}`);
+/** Any execute bit, which is the one bit of a mode a recipe carries, as git does. */
+const executable = 73;
 /**
-* Pipes the archive into `tar -x` in a fresh directory, so no file of the recipe's can
-* collide with the archive, then runs `./setup.sh` from there: its `#!` line picks the
-* interpreter, as for a single-file setup, and the unpacker marks it executable whatever mode
-* it was packed with. The directory is under `/var/tmp`, as a single-file setup is, which
-* nothing mounts `noexec`, and is removed however setup ends. Setup runs as a child
-* rather than through `exec`, so the cleanup trap still runs after it. `--no-same-owner`
-* keeps the packer's uid off the files when root unpacks them in the guest.
+* Makes the recipe's files in a fresh directory, then runs `./setup.sh` from there: its `#!`
+* line picks the interpreter, as for a single-file setup, and the unpacker marks it executable
+* whatever mode it was packed with. The directory is under `/var/tmp`, as a single-file setup
+* is, which nothing mounts `noexec`, and is removed however setup ends. Setup runs as a child
+* rather than through `exec`, so the cleanup trap still runs after it.
 */
-const selfExtracting = (archive) => [
+const selfExtracting = (steps) => [
 	"#!/bin/sh",
 	"set -eu",
 	"recipe=$(mktemp -d /var/tmp/clankerbox-recipe.XXXXXX)",
 	`trap 'rm -rf "$recipe"' EXIT`,
 	"trap 'exit 1' HUP INT TERM",
-	`base64 -d <<'${terminator}' | tar -x -f - --no-same-owner -C "$recipe"`,
-	wrap(archive),
-	terminator,
 	"cd \"$recipe\"",
+	...steps,
 	"chmod +x setup.sh",
 	"./setup.sh",
 	""
 ].join("\n");
 /**
-* Packs a recipe directory into one self-extracting script: a base64 tar that unpacks into a
-* temporary directory, then runs `setup.sh` from there. `COPYFILE_DISABLE=1` and
-* `--no-xattrs` keep macOS `tar` from adding `._*` files and provenance headers.
+* Packs a recipe directory into one self-extracting script, which makes each of its entries
+* with plain shell: a directory with `mkdir`, a symlink with `ln -s` as it is, and a file from
+* base64, made executable when any of its execute bits is set. A symlink is never walked into,
+* so nothing outside the recipe is packed, and in the guest nothing is written through one.
+* Of a mode only the execute bit is kept, as git keeps it, so a checkout's umask changes
+* nothing. Entries go in sorted order and nothing records a time or an owner, so the same
+* files pack into the same script: a prebuild is named after it.
 */
 const packRecipe = (directory) => Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
 	const noSetup = new Invalid({ message: `recipe ${directory} has no setup.sh` });
 	if ((yield* fs.stat(`${directory}/setup.sh`).pipe(Effect.mapError((error) => Predicate.isTagged(error.reason, "NotFound") ? noSetup : error))).type !== "File") return yield* noSetup;
-	const tar = yield* (yield* ChildProcessSpawner.ChildProcessSpawner).spawn(ChildProcess.make("tar", [
-		"--no-xattrs",
-		"-c",
-		"-f",
-		"-",
-		"-C",
-		directory,
-		"."
-	], {
-		env: { COPYFILE_DISABLE: "1" },
-		extendEnv: true,
-		stdin: "ignore"
-	}));
-	const [archive, errors, code] = yield* Effect.all([
-		Stream.mkUint8Array(tar.stdout),
-		Stream.mkString(Stream.decodeText(tar.stderr)),
-		tar.exitCode
-	], { concurrency: "unbounded" });
-	if (code !== 0) return yield* new Invalid({ message: `tar couldn't pack recipe ${directory} (exit ${code}): ${errors.trim()}` });
-	return selfExtracting(Buffer.from(archive.buffer, archive.byteOffset, archive.byteLength).toString("base64"));
-}).pipe(Effect.scoped, Effect.catchTag("PlatformError", (error) => Effect.fail(new Invalid({ message: `couldn't pack recipe ${directory}: ${error.message}` }))));
+	const steps = [];
+	/** Packs the entries of the recipe's directory `under`, `""` being the recipe itself. */
+	const walk = (under) => Effect.gen(function* () {
+		const names = yield* fs.readDirectory(under === "" ? directory : `${directory}/${under}`);
+		for (const name of names.toSorted()) {
+			const entry = under === "" ? name : `${under}/${name}`;
+			const path = `${directory}/${entry}`;
+			const link = yield* Effect.option(fs.readLink(path));
+			if (Option.isSome(link)) {
+				steps.push(`ln -s -- ${quote(link.value)} ${argument(entry)}`);
+				continue;
+			}
+			const info = yield* fs.stat(path);
+			if (info.type === "Directory") {
+				steps.push(`mkdir ${argument(entry)}`);
+				yield* walk(entry);
+			} else if (info.type === "File") {
+				steps.push(`base64 -d >${argument(entry)} <<'${terminator}'`, wrap(Buffer.from(yield* fs.readFile(path)).toString("base64")), terminator);
+				if ((info.mode & executable) !== 0) steps.push(`chmod +x ${argument(entry)}`);
+			} else return yield* new Invalid({ message: `recipe ${directory} holds ${entry}, a ${info.type}: a recipe packs only files, directories and symlinks` });
+		}
+	});
+	yield* walk("");
+	return selfExtracting(steps);
+}).pipe(Effect.catchTag("PlatformError", (error) => Effect.fail(new Invalid({ message: `couldn't pack recipe ${directory}: ${describeFileError(error)}` }))));
 /** Reads a setup: a script file's text, or a recipe directory packed into one script. */
 const readSetup = (path) => Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
 	if ((yield* fs.stat(path)).type === "Directory") return yield* packRecipe(path);
 	return yield* fs.readFileString(path);
-}).pipe(Effect.catchTag("PlatformError", (error) => Effect.fail(new Invalid({ message: `couldn't read setup ${path}: ${error.message}` }))));
+}).pipe(Effect.catchTag("PlatformError", (error) => Effect.fail(new Invalid({ message: `couldn't read setup ${path}: ${describeFileError(error)}` }))));
 //#endregion
-export { ActionName, ActionRecord, Capacity, Checkpoint, client_exports as Client, Conflict, ConflictKind, CreateRequest, ErrorTag, Host, HostErrorTag, HostId, Http, Id, Internal, Invalid, Limit, Machine, MachineSpec, Name, NotFound, Precondition, Profile, Runtime, Setup, SshEndpoint, SshLogin, Unavailable, formatId, hostErrors, loadProfile, packRecipe, parseId, parseName, readSetup, readTimeout, release, version, versionHeader };
+export { ActionName, ActionRecord, Capacity, Checkpoint, client_exports as Client, Conflict, ConflictKind, CreateRequest, ErrorTag, Host, HostErrorTag, HostId, Http, Id, Internal, Invalid, Limit, Machine, MachineSpec, Name, NotFound, prebuild_exports as Prebuild, Precondition, Profile, Runtime, Setup, SshEndpoint, SshLogin, Unavailable, describeFileError, describeIssues, formatId, formatMib, hostErrors, loadProfile, packRecipe, parseId, parseName, readSetup, readTimeout, release, version, versionHeader };

package/dist/node.d.mts

@@ -1,4 +1,4 @@
-import { O as Invalid, n as HostEntry, r as Options, t as Client } from "./client-SX6jTU1R.mjs";
+import { A as Invalid, a as Options, r as HostEntry, t as Client } from "./client-Cn1bj4It.mjs";
 import { Layer } from "effect";
 //#region src/node.d.ts
 /** Node's `http` module sets no timeout of its own: a mutation can run for hours. */

package/dist/node.mjs

@@ -1,4 +1,4 @@
-import { r as make, t as Client } from "./client-DR7ytUZp.mjs";
+import { r as make, t as Client } from "./client-CtI-rSJQ.mjs";
 import { Layer } from "effect";
 import * as NodeHttpClient from "@effect/platform-node/NodeHttpClient";
 //#region src/node.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjermundgaraba/clankerbox-sdk",
-  "version": "0.15.1",
+  "version": "0.15.3",
   "description": "clankerbox's API contract and client library, for Effect",
   "license": "MIT",
   "repository": {