@gjermundgaraba/clankerbox-sdk 0.15.6 → 0.18.0

package/dist/index.d.mts

@@ -1,423 +1,154 @@
-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, PlatformError, Schema, Scope } 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
- * bounds its own reads of runtime state under it, so a list answers in time.
- */
-export declare const readTimeout: Duration.Duration;
-/**
- * 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.
- */
-export declare const versionHeader = "clankerbox-version";
-export declare const Http: ActionHttp.Binding<readonly [Action.Action<"listMachines", Schema.$Record<Schema.String, Schema.Never>, Schema.$Array<Schema.Struct<{
-  readonly id: Schema.String;
-  readonly runtime: Schema.Literals<readonly ["smolvm", "tart", "boat"]>;
-  readonly createdAt: Schema.DateTimeUtcFromString;
-  readonly base: Schema.String;
-  readonly profile: Schema.optionalKey<Schema.String>;
-  readonly cpu: Schema.Int;
-  readonly ramMib: Schema.Int;
-  readonly diskGib: Schema.Int;
-  readonly state: Schema.Literals<readonly ["running", "stopped", "missing", "unknown"]>;
-  readonly made: Schema.Boolean;
-  readonly action: Schema.Struct<{
-    readonly name: Schema.Literals<readonly ["create", "start", "stop", "delete", "fork", "restore", "capture"]>;
-    readonly status: Schema.Literals<readonly ["running", "failed", "done"]>;
-    readonly error: Schema.optionalKey<Schema.Struct<{
-      readonly tag: Schema.Literals<("Capacity" | "Conflict" | "Internal" | "Invalid" | "NotFound" | "Precondition")[]>;
-      readonly message: Schema.String;
-    }>>;
-  }>;
-  readonly ssh: Schema.optionalKey<Schema.Struct<{
-    readonly host: Schema.String;
-    readonly port: Schema.Int;
-    readonly user: Schema.String;
-  }>>;
-  readonly hostKey: Schema.optionalKey<Schema.String>;
-}>>, readonly (typeof Invalid | typeof NotFound | typeof Conflict | typeof Precondition | typeof Capacity | typeof Internal)[], true, typeof Action.Anyone>, Action.Action<"getMachine", Schema.Struct<{
-  readonly id: Schema.String;
-}>, Schema.Struct<{
-  readonly id: Schema.String;
-  readonly runtime: Schema.Literals<readonly ["smolvm", "tart", "boat"]>;
-  readonly createdAt: Schema.DateTimeUtcFromString;
-  readonly base: Schema.String;
-  readonly profile: Schema.optionalKey<Schema.String>;
-  readonly cpu: Schema.Int;
-  readonly ramMib: Schema.Int;
-  readonly diskGib: Schema.Int;
-  readonly state: Schema.Literals<readonly ["running", "stopped", "missing", "unknown"]>;
-  readonly made: Schema.Boolean;
-  readonly action: Schema.Struct<{
-    readonly name: Schema.Literals<readonly ["create", "start", "stop", "delete", "fork", "restore", "capture"]>;
-    readonly status: Schema.Literals<readonly ["running", "failed", "done"]>;
-    readonly error: Schema.optionalKey<Schema.Struct<{
-      readonly tag: Schema.Literals<("Capacity" | "Conflict" | "Internal" | "Invalid" | "NotFound" | "Precondition")[]>;
-      readonly message: Schema.String;
-    }>>;
-  }>;
-  readonly ssh: Schema.optionalKey<Schema.Struct<{
-    readonly host: Schema.String;
-    readonly port: Schema.Int;
-    readonly user: Schema.String;
-  }>>;
-  readonly hostKey: Schema.optionalKey<Schema.String>;
-}>, readonly (typeof Invalid | typeof NotFound | typeof Conflict | typeof Precondition | typeof Capacity | typeof Internal)[], true, typeof Action.Anyone>, Action.Action<"createMachine", Schema.Struct<{
-  readonly base: Schema.String;
-  readonly cpu: Schema.Int;
-  readonly ramMib: Schema.Int;
-  readonly diskGib: Schema.Int;
-  readonly setup: Schema.optionalKey<Schema.Struct<{
-    readonly script: Schema.String;
-    readonly timeoutSeconds: Schema.optionalKey<Schema.Int>;
-  }>>;
-  readonly profile: Schema.optionalKey<Schema.String>;
-  readonly id: Schema.String;
-}>, Schema.Struct<{
-  readonly id: Schema.String;
-  readonly runtime: Schema.Literals<readonly ["smolvm", "tart", "boat"]>;
-  readonly createdAt: Schema.DateTimeUtcFromString;
-  readonly base: Schema.String;
-  readonly profile: Schema.optionalKey<Schema.String>;
-  readonly cpu: Schema.Int;
-  readonly ramMib: Schema.Int;
-  readonly diskGib: Schema.Int;
-  readonly state: Schema.Literals<readonly ["running", "stopped", "missing", "unknown"]>;
-  readonly made: Schema.Boolean;
-  readonly action: Schema.Struct<{
-    readonly name: Schema.Literals<readonly ["create", "start", "stop", "delete", "fork", "restore", "capture"]>;
-    readonly status: Schema.Literals<readonly ["running", "failed", "done"]>;
-    readonly error: Schema.optionalKey<Schema.Struct<{
-      readonly tag: Schema.Literals<("Capacity" | "Conflict" | "Internal" | "Invalid" | "NotFound" | "Precondition")[]>;
-      readonly message: Schema.String;
-    }>>;
-  }>;
-  readonly ssh: Schema.optionalKey<Schema.Struct<{
-    readonly host: Schema.String;
-    readonly port: Schema.Int;
-    readonly user: Schema.String;
-  }>>;
-  readonly hostKey: Schema.optionalKey<Schema.String>;
-}>, readonly (typeof Invalid | typeof NotFound | typeof Conflict | typeof Precondition | typeof Capacity | typeof Internal)[], false, typeof Action.Anyone>, Action.Action<"startMachine", Schema.Struct<{
-  readonly id: Schema.String;
-}>, Schema.Struct<{
-  readonly id: Schema.String;
-  readonly runtime: Schema.Literals<readonly ["smolvm", "tart", "boat"]>;
-  readonly createdAt: Schema.DateTimeUtcFromString;
-  readonly base: Schema.String;
-  readonly profile: Schema.optionalKey<Schema.String>;
-  readonly cpu: Schema.Int;
-  readonly ramMib: Schema.Int;
-  readonly diskGib: Schema.Int;
-  readonly state: Schema.Literals<readonly ["running", "stopped", "missing", "unknown"]>;
-  readonly made: Schema.Boolean;
-  readonly action: Schema.Struct<{
-    readonly name: Schema.Literals<readonly ["create", "start", "stop", "delete", "fork", "restore", "capture"]>;
-    readonly status: Schema.Literals<readonly ["running", "failed", "done"]>;
-    readonly error: Schema.optionalKey<Schema.Struct<{
-      readonly tag: Schema.Literals<("Capacity" | "Conflict" | "Internal" | "Invalid" | "NotFound" | "Precondition")[]>;
-      readonly message: Schema.String;
-    }>>;
-  }>;
-  readonly ssh: Schema.optionalKey<Schema.Struct<{
-    readonly host: Schema.String;
-    readonly port: Schema.Int;
-    readonly user: Schema.String;
-  }>>;
-  readonly hostKey: Schema.optionalKey<Schema.String>;
-}>, readonly (typeof Invalid | typeof NotFound | typeof Conflict | typeof Precondition | typeof Capacity | typeof Internal)[], false, typeof Action.Anyone>, Action.Action<"stopMachine", Schema.Struct<{
-  readonly id: Schema.String;
-}>, Schema.Struct<{
-  readonly id: Schema.String;
-  readonly runtime: Schema.Literals<readonly ["smolvm", "tart", "boat"]>;
-  readonly createdAt: Schema.DateTimeUtcFromString;
-  readonly base: Schema.String;
-  readonly profile: Schema.optionalKey<Schema.String>;
-  readonly cpu: Schema.Int;
-  readonly ramMib: Schema.Int;
-  readonly diskGib: Schema.Int;
-  readonly state: Schema.Literals<readonly ["running", "stopped", "missing", "unknown"]>;
-  readonly made: Schema.Boolean;
-  readonly action: Schema.Struct<{
-    readonly name: Schema.Literals<readonly ["create", "start", "stop", "delete", "fork", "restore", "capture"]>;
-    readonly status: Schema.Literals<readonly ["running", "failed", "done"]>;
-    readonly error: Schema.optionalKey<Schema.Struct<{
-      readonly tag: Schema.Literals<("Capacity" | "Conflict" | "Internal" | "Invalid" | "NotFound" | "Precondition")[]>;
-      readonly message: Schema.String;
-    }>>;
-  }>;
-  readonly ssh: Schema.optionalKey<Schema.Struct<{
-    readonly host: Schema.String;
-    readonly port: Schema.Int;
-    readonly user: Schema.String;
-  }>>;
-  readonly hostKey: Schema.optionalKey<Schema.String>;
-}>, readonly (typeof Invalid | typeof NotFound | typeof Conflict | typeof Precondition | typeof Capacity | typeof Internal)[], false, typeof Action.Anyone>, Action.Action<"deleteMachine", Schema.Struct<{
-  readonly id: Schema.String;
-}>, Schema.Void, readonly (typeof Invalid | typeof NotFound | typeof Conflict | typeof Precondition | typeof Capacity | typeof Internal)[], false, typeof Action.Anyone>, Action.Action<"forkMachine", Schema.Struct<{
-  readonly machine: Schema.String;
-  readonly name: Schema.String;
-}>, Schema.Struct<{
-  readonly id: Schema.String;
-  readonly runtime: Schema.Literals<readonly ["smolvm", "tart", "boat"]>;
-  readonly createdAt: Schema.DateTimeUtcFromString;
-  readonly base: Schema.String;
-  readonly profile: Schema.optionalKey<Schema.String>;
-  readonly cpu: Schema.Int;
-  readonly ramMib: Schema.Int;
-  readonly diskGib: Schema.Int;
-  readonly state: Schema.Literals<readonly ["running", "stopped", "missing", "unknown"]>;
-  readonly made: Schema.Boolean;
-  readonly action: Schema.Struct<{
-    readonly name: Schema.Literals<readonly ["create", "start", "stop", "delete", "fork", "restore", "capture"]>;
-    readonly status: Schema.Literals<readonly ["running", "failed", "done"]>;
-    readonly error: Schema.optionalKey<Schema.Struct<{
-      readonly tag: Schema.Literals<("Capacity" | "Conflict" | "Internal" | "Invalid" | "NotFound" | "Precondition")[]>;
-      readonly message: Schema.String;
-    }>>;
-  }>;
-  readonly ssh: Schema.optionalKey<Schema.Struct<{
-    readonly host: Schema.String;
-    readonly port: Schema.Int;
-    readonly user: Schema.String;
-  }>>;
-  readonly hostKey: Schema.optionalKey<Schema.String>;
-}>, readonly (typeof Invalid | typeof NotFound | typeof Conflict | typeof Precondition | typeof Capacity | typeof Internal)[], false, typeof Action.Anyone>, Action.Action<"restoreMachine", Schema.Struct<{
-  readonly checkpoint: Schema.String;
-  readonly name: Schema.String;
-}>, Schema.Struct<{
-  readonly id: Schema.String;
-  readonly runtime: Schema.Literals<readonly ["smolvm", "tart", "boat"]>;
-  readonly createdAt: Schema.DateTimeUtcFromString;
-  readonly base: Schema.String;
-  readonly profile: Schema.optionalKey<Schema.String>;
-  readonly cpu: Schema.Int;
-  readonly ramMib: Schema.Int;
-  readonly diskGib: Schema.Int;
-  readonly state: Schema.Literals<readonly ["running", "stopped", "missing", "unknown"]>;
-  readonly made: Schema.Boolean;
-  readonly action: Schema.Struct<{
-    readonly name: Schema.Literals<readonly ["create", "start", "stop", "delete", "fork", "restore", "capture"]>;
-    readonly status: Schema.Literals<readonly ["running", "failed", "done"]>;
-    readonly error: Schema.optionalKey<Schema.Struct<{
-      readonly tag: Schema.Literals<("Capacity" | "Conflict" | "Internal" | "Invalid" | "NotFound" | "Precondition")[]>;
-      readonly message: Schema.String;
-    }>>;
-  }>;
-  readonly ssh: Schema.optionalKey<Schema.Struct<{
-    readonly host: Schema.String;
-    readonly port: Schema.Int;
-    readonly user: Schema.String;
-  }>>;
-  readonly hostKey: Schema.optionalKey<Schema.String>;
-}>, readonly (typeof Invalid | typeof NotFound | typeof Conflict | typeof Precondition | typeof Capacity | typeof Internal)[], false, typeof Action.Anyone>, Action.Action<"listCheckpoints", Schema.$Record<Schema.String, Schema.Never>, Schema.$Array<Schema.Struct<{
-  readonly id: Schema.String;
-  readonly createdAt: Schema.DateTimeUtcFromString;
-  readonly machine: Schema.String;
-  readonly kind: Schema.Literals<readonly ["ram", "disk"]>;
-  readonly base: Schema.String;
-  readonly profile: Schema.optionalKey<Schema.String>;
-  readonly cpu: Schema.Int;
-  readonly ramMib: Schema.Int;
-  readonly diskGib: Schema.Int;
-  readonly action: Schema.Struct<{
-    readonly name: Schema.Literals<readonly ["create", "start", "stop", "delete", "fork", "restore", "capture"]>;
-    readonly status: Schema.Literals<readonly ["running", "failed", "done"]>;
-    readonly error: Schema.optionalKey<Schema.Struct<{
-      readonly tag: Schema.Literals<("Capacity" | "Conflict" | "Internal" | "Invalid" | "NotFound" | "Precondition")[]>;
-      readonly message: Schema.String;
-    }>>;
-  }>;
-}>>, readonly (typeof Invalid | typeof NotFound | typeof Conflict | typeof Precondition | typeof Capacity | typeof Internal)[], true, typeof Action.Anyone>, Action.Action<"getCheckpoint", Schema.Struct<{
-  readonly id: Schema.String;
-}>, Schema.Struct<{
-  readonly id: Schema.String;
-  readonly createdAt: Schema.DateTimeUtcFromString;
-  readonly machine: Schema.String;
-  readonly kind: Schema.Literals<readonly ["ram", "disk"]>;
-  readonly base: Schema.String;
-  readonly profile: Schema.optionalKey<Schema.String>;
-  readonly cpu: Schema.Int;
-  readonly ramMib: Schema.Int;
-  readonly diskGib: Schema.Int;
-  readonly action: Schema.Struct<{
-    readonly name: Schema.Literals<readonly ["create", "start", "stop", "delete", "fork", "restore", "capture"]>;
-    readonly status: Schema.Literals<readonly ["running", "failed", "done"]>;
-    readonly error: Schema.optionalKey<Schema.Struct<{
-      readonly tag: Schema.Literals<("Capacity" | "Conflict" | "Internal" | "Invalid" | "NotFound" | "Precondition")[]>;
-      readonly message: Schema.String;
-    }>>;
-  }>;
-}>, readonly (typeof Invalid | typeof NotFound | typeof Conflict | typeof Precondition | typeof Capacity | typeof Internal)[], true, typeof Action.Anyone>, Action.Action<"captureCheckpoint", Schema.Struct<{
-  readonly machine: Schema.String;
-  readonly name: Schema.String;
-}>, Schema.Struct<{
-  readonly id: Schema.String;
-  readonly createdAt: Schema.DateTimeUtcFromString;
-  readonly machine: Schema.String;
-  readonly kind: Schema.Literals<readonly ["ram", "disk"]>;
-  readonly base: Schema.String;
-  readonly profile: Schema.optionalKey<Schema.String>;
-  readonly cpu: Schema.Int;
-  readonly ramMib: Schema.Int;
-  readonly diskGib: Schema.Int;
-  readonly action: Schema.Struct<{
-    readonly name: Schema.Literals<readonly ["create", "start", "stop", "delete", "fork", "restore", "capture"]>;
-    readonly status: Schema.Literals<readonly ["running", "failed", "done"]>;
-    readonly error: Schema.optionalKey<Schema.Struct<{
-      readonly tag: Schema.Literals<("Capacity" | "Conflict" | "Internal" | "Invalid" | "NotFound" | "Precondition")[]>;
-      readonly message: Schema.String;
-    }>>;
-  }>;
-}>, readonly (typeof Invalid | typeof NotFound | typeof Conflict | typeof Precondition | typeof Capacity | typeof Internal)[], false, typeof Action.Anyone>, Action.Action<"deleteCheckpoint", Schema.Struct<{
-  readonly id: Schema.String;
-}>, Schema.Void, readonly (typeof Invalid | typeof NotFound | typeof Conflict | typeof Precondition | typeof Capacity | typeof Internal)[], false, typeof Action.Anyone>, Action.Action<"getHost", Schema.$Record<Schema.String, Schema.Never>, Schema.Struct<{
-  readonly id: Schema.String;
-  readonly runtime: Schema.Literals<readonly ["smolvm", "tart", "boat"]>;
-  readonly version: Schema.String;
-  readonly runtimeVersion: Schema.String;
-  readonly bases: Schema.$Array<Schema.String>;
-}>, readonly (typeof Invalid | typeof NotFound | typeof Conflict | typeof Precondition | typeof Capacity | typeof Internal)[], true, typeof Action.Anyone>, Action.Action<"getCapacity", Schema.$Record<Schema.String, Schema.Never>, Schema.$Array<Schema.Struct<{
-  readonly host: Schema.String;
-  readonly resource: Schema.Literals<readonly ["ramMib", "runningVms", "activeSandboxes", "startsPerMinute", "startsPerHour", "startsPerDay"]>;
-  readonly limit: Schema.Int;
-  readonly used: Schema.Int;
-}>>, readonly (typeof Invalid | typeof NotFound | typeof Conflict | typeof Precondition | typeof Capacity | typeof Internal)[], true, typeof Action.Anyone>], [], undefined>;
-//#endregion
+import { A as ConflictKind, B as Refused, C as Declared, D as Capacity, E as readTimeout, F as NotFound, G as hostErrors, H as Unavailable, I as NotMade, K as retryable, L as NotOffered, M as Internal, N as Invalid, O as ClankerboxError, P as Missing, R as NotReady, S as stateLabel, T as actionsByName, U as Unsizable, V as ScriptFailed, W as WrongState, _ as Setup, b as Usage, c as ActionRecord, d as CreateRequest, f as Host, g as Runtime, h as Reading, i as Interface, j as HostError, k as Conflict, l as ActionStatus, m as MachineSpec, n as CreateOptions$1, o as client_d_exports, p as Machine, s as ActionName, u as Checkpoint, v as SshEndpoint, w as Http, x as isReady, y as SshLogin, z as PinMismatch } from "./client-8af586hb.mjs";
+import { Effect, FileSystem, Path, PlatformError, Schema, Scope } from "effect";
 //#region src/ids.d.ts
-/** A host's part of every ID it holds. */
 export declare const HostId: Schema.String;
-/** A machine's or checkpoint's name, unique per host and per resource type. */
+/** Unique per host and per resource type. */
 export declare const Name: Schema.String;
-/** The parts of an ID: the host that holds the resource and the resource's name there. */
 export interface IdParts {
   readonly host: string;
   readonly name: string;
 }
-/** A full `<host>_<name>` ID. */
+/** `<host>_<name>`: neither part contains `_`, so an ID has exactly one. */
 export declare const Id: Schema.String;
-/** Splits an ID at its `_` into host and name. */
 export declare const parseId: (id: string) => Effect.Effect<IdParts, Invalid>;
-/** Checks a name on its own, before it is joined to a host. */
 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. */
+/** Checks 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 };
+  export { Built, CreateOptions, 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.
+ * A digest of the spec's label, base, sizes, 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 and
+ * the base's image are no part of it.
  */
 declare const nameOf: (spec: MachineSpec, host: Pick<Host, "runtimeVersion">) => Effect.Effect<string>;
+/** `fresh` runs the setup even when the host has a prebuild of the spec. */
+interface CreateOptions extends CreateOptions$1 {
+  readonly fresh?: boolean | undefined;
+}
 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.
+ * `client.create`, restoring the spec's prebuild when the host it is placed on has one whose
+ * capture is done, unless `fresh`. 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.
-   */
+  /** The builder's ID when its delete failed: it may still run, holding its RAM. */
   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`.
+ * Builds the spec's prebuild on the host a create of it is placed on, with a machine of its own
+ * that it deletes however it ends. A prebuild that is there and done is the answer, one that
+ * failed is deleted and built again, and one still running is `Conflict{busy}`, as its capture
+ * holds it. Of two builds of one spec at once, the second's capture is `Conflict`, and neither
+ * touches the other's machine.
  */
-declare const build: (client: Interface, spec: MachineSpec, options?: CreateOptions) => Effect.Effect<Built, ClankerboxError>;
+declare const build: (client: Interface, spec: MachineSpec & {
+  readonly setup: Setup;
+}, options?: CreateOptions$1) => Effect.Effect<Built, ClankerboxError>;
+//#endregion
+//#region src/release.d.ts
+/** Also the version of the clankerbox binaries it ships with. */
+export declare const version: string;
+/** major.minor: releases that share it speak the same API. */
+export declare const release: (of: string) => string;
+/** A host refuses a request whose `release` differs from its own, or that has none. */
+export declare const versionHeader = "clankerbox-version";
 //#endregion
 //#region src/profile.d.ts
-/** A profile file as read: its fields, with `setup.path` resolved, and its name as `label`. */
+/**
+ * A client-side file that fills in a create's spec; hosts never see it. `setup.path` is a script
+ * file or a recipe directory, relative to the profile file.
+ */
+export declare const Profile: Schema.Struct<{
+  readonly base: Schema.String;
+  readonly cpu: Schema.Int;
+  readonly ramMib: Schema.Int;
+  readonly diskGib: Schema.Int;
+  readonly setup: Schema.optionalKey<Schema.Struct<{
+    readonly path: Schema.String;
+    readonly timeoutSeconds: Schema.optionalKey<Schema.Int>;
+  }>>;
+  readonly host: Schema.optionalKey<Schema.String>;
+}>;
+export type Profile = typeof Profile.Type;
+/** `setup.path` resolved, and the file's name as `label`. */
 export interface LoadedProfile extends Profile {
   readonly label: string;
 }
 /**
- * Reads the profile file at `file`. Its name, the file name without `.json`, is the machine's
- * `profile` label, and its `setup.path` is resolved against the file's directory. The setup
- * itself is read by whoever sends it, with `readSetup`.
+ * Its file name without `.json` is the machine's `profile` label. Unknown keys are refused. The
+ * setup itself is read by whoever sends it, with `readSetup`.
  */
 export declare const loadProfile: (file: string) => Effect.Effect<LoadedProfile, Invalid, FileSystem.FileSystem | Path.Path>;
+type Sizes = Omit<Profile, "setup" | "host">;
+/** Each field given replaces the profile's. */
+export type Overrides = { readonly [K in keyof Sizes]?: Sizes[K] | undefined; } & {
+  /** A setup script or recipe directory, already resolved. */
+  readonly setup?: string | undefined;
+  readonly setupTimeoutSeconds?: number | undefined;
+  readonly host?: string | undefined;
+};
+export interface SpecRequest {
+  readonly spec: MachineSpec;
+  readonly host: string | undefined;
+}
+/**
+ * The spec and host a create of `profile` asks for, with the overrides applied and the setup
+ * read. Each refusal names `what`, and each field as `names` calls it.
+ */
+export declare const specRequest: (what: string, profile: LoadedProfile | undefined, overrides: Overrides, names?: ReadonlyMap<PropertyKey, string>) => Effect.Effect<SpecRequest, Invalid, FileSystem.FileSystem | Path.Path>;
 //#endregion
 //#region src/setup.d.ts
 /**
- * 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.
+ * Packs a recipe directory, a `setup.sh` and the files it needs, into one self-extracting script.
+ * Symlinks are recreated as they are and never walked into. The same files always pack into the
+ * same script, as a prebuild is named after it.
  */
 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. */
+/** 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>;
 //#endregion
 //#region src/ssh.d.ts
-/** What ssh needs of a machine: where it is reached, as whom, and the host key to pin. */
 export interface SshTarget {
   readonly id: string;
   readonly login: SshLogin;
   readonly hostKey: string;
 }
 /**
- * The machine's SSH target, or what it lacks: an endpoint, which only a running machine has, or
- * a host key, which preparation records.
+ * Only a running machine has an endpoint, and only a prepared one a host key; a machine without
+ * either is `WrongState`, naming what it lacks and why.
  */
-export declare const sshTarget: (machine: Machine) => SshTarget | {
-  readonly lacks: "SSH endpoint" | "SSH host key on record";
-};
+export declare const sshTarget: (machine: Machine) => Effect.Effect<SshTarget, WrongState>;
 /**
- * Writes a one-line known-hosts file pinning the target's host key, and returns the arguments
- * that run ssh against it with strict host key checking, as `user`. The file lasts as long as
- * the scope, which must outlast the ssh it is for. Ports change on fork and restore, and on
- * boat at every start, so a target is read anew for each ssh.
+ * ssh's arguments, pinned to the target's host key through a known-hosts file that lasts as long
+ * as the scope, which must outlast the ssh. Ports change on fork, restore, and every boat start,
+ * so read the target anew for each ssh.
  */
 export declare const pinnedSsh: (target: SshTarget, user: string, extra: ReadonlyArray<string>) => Effect.Effect<Array<string>, PlatformError.PlatformError, FileSystem.FileSystem | Path.Path | Scope.Scope>;
 //#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`.
- */
+//#region src/describe.d.ts
+/** On one line: `cpu: missing; ram: not a known field`. `names` renames top-level fields. */
 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.
+ * 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, prebuild_d_exports as Prebuild, Precondition, Profile, Runtime, Setup, SshEndpoint, SshLogin, Unavailable, hostErrors, release, version };
+//#region src/sizes.d.ts
+export declare const mibPerGib = 1024;
+/** Exactly, as a size flag takes it: `32G`, `1.5G`, `512M`, `1500M`. */
+export declare const formatMib: (mib: number) => string;
+/** As a size flag takes it: `60G`. */
+export declare const formatGib: (gib: number) => string;
+//#endregion
+export { ActionName, ActionRecord, ActionStatus, Capacity, Checkpoint, ClankerboxError, client_d_exports as Client, Conflict, ConflictKind, CreateRequest, Declared, Host, HostError, Http, Internal, Invalid, Machine, MachineSpec, Missing, NotFound, NotMade, NotOffered, NotReady, PinMismatch, prebuild_d_exports as Prebuild, Reading, Refused, Runtime, ScriptFailed, Setup, SshEndpoint, SshLogin, Unavailable, Unsizable, Usage, WrongState, actionsByName, hostErrors, isReady, readTimeout, retryable, stateLabel };