@sealant/api-contracts-next 0.40.0-next.777 → 0.40.0-next.783

package/dist/core-api/resource-instances.d.ts

@@ -0,0 +1,636 @@
+/**
+ * Resource instances: long-running containers a resource domain (a project) runs, such as a
+ * Postgres server, a Redis or a mail catcher, with named volumes that outlive every stop.
+ *
+ * An instance is addressed by its domain and its `key`, the application's own name for it (Mend:
+ * `<definition>` or `<definition>@<worktree>`). Its `alias` is the short name a linked workspace
+ * resolves it by (`db`). An instance whose `worktreeKey` is null is reached by every workspace
+ * linked to the domain; one with a worktree key only by workspaces linked with that key.
+ *
+ * The spec has no field for privileged mode, capabilities, host networking, host paths, devices,
+ * the Docker socket or shared namespaces, and the decoder names each one it is sent.
+ */
+import { Schema } from "effect";
+import { HttpApiEndpoint, HttpApiGroup } from "effect/http-api";
+import { ResourceDomainForbiddenError, ResourceDomainInternalServerError, ResourceDomainNotFoundError } from "./resource-domains.js";
+export declare const RESOURCE_INSTANCE_ID_PREFIX = "rin:";
+export declare const ResourceInstanceId: Schema.brand<Schema.String, "ResourceInstanceId">;
+export type ResourceInstanceId = typeof ResourceInstanceId.Type;
+export declare const ResourceInstanceKey: Schema.brand<Schema.String, "ResourceInstanceKey">;
+export type ResourceInstanceKey = typeof ResourceInstanceKey.Type;
+/** One DNS label: the name a linked workspace resolves the instance by. */
+export declare const ResourceInstanceAlias: Schema.brand<Schema.String, "ResourceInstanceAlias">;
+export type ResourceInstanceAlias = typeof ResourceInstanceAlias.Type;
+/** The application's opaque name for a worktree: links and worktree instances match on it. */
+export declare const ResourceWorktreeKey: Schema.brand<Schema.String, "ResourceWorktreeKey">;
+export type ResourceWorktreeKey = typeof ResourceWorktreeKey.Type;
+/** An image pinned by digest (a tag may precede it). Core never resolves a tag. */
+export declare const ResourcePinnedImage: Schema.brand<Schema.String, "ResourcePinnedImage">;
+export type ResourcePinnedImage = typeof ResourcePinnedImage.Type;
+export declare const resourceInstanceVolumeSchema: Schema.Struct<{
+    readonly name: Schema.String;
+    readonly mountPath: Schema.String;
+}>;
+export type ResourceInstanceVolume = typeof resourceInstanceVolumeSchema.Type;
+export declare const resourceInstanceReadySchema: Schema.Union<readonly [Schema.Struct<{
+    readonly kind: Schema.Literal<"tcp">;
+    readonly port: Schema.Int;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"exec">;
+    readonly argv: Schema.$Array<Schema.String>;
+    readonly user: Schema.NullOr<Schema.String>;
+}>]>;
+export type ResourceInstanceReady = typeof resourceInstanceReadySchema.Type;
+/** Ten days: the longest an instance may wait unreached before Core stops it. */
+export declare const RESOURCE_INSTANCE_MAX_IDLE_SECONDS = 864000;
+/** What an instance runs. Excess keys are refused; see the header for what has no field. */
+export declare const resourceInstanceSpecSchema: Schema.Struct<{
+    readonly alias: Schema.brand<Schema.String, "ResourceInstanceAlias">;
+    /** Null: every workspace linked to the domain reaches it. Set: only links with this key. */
+    readonly worktreeKey: Schema.NullOr<Schema.brand<Schema.String, "ResourceWorktreeKey">>;
+    readonly image: Schema.brand<Schema.String, "ResourcePinnedImage">;
+    /** Replaces the image's CMD; its ENTRYPOINT always runs. */
+    readonly command: Schema.NullOr<Schema.$Array<Schema.String>>;
+    readonly env: Schema.$Record<Schema.String, Schema.String>;
+    /** Named volumes only. Every image `VOLUME` this does not cover gets a named volume too. */
+    readonly volumes: Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly mountPath: Schema.String;
+    }>>;
+    readonly limits: Schema.Struct<{
+        readonly cpuMillicores: Schema.Int;
+        readonly memoryBytes: Schema.Int;
+    }>;
+    readonly ready: Schema.Union<readonly [Schema.Struct<{
+        readonly kind: Schema.Literal<"tcp">;
+        readonly port: Schema.Int;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"exec">;
+        readonly argv: Schema.$Array<Schema.String>;
+        readonly user: Schema.NullOr<Schema.String>;
+    }>]>;
+    /** Seconds with no live linked executor reaching it before Core stops it. */
+    readonly idleStopAfterSeconds: Schema.Int;
+}>;
+export type ResourceInstanceSpec = typeof resourceInstanceSpecSchema.Type;
+export declare const resourceInstanceStopReasonSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly kind: Schema.Literal<"idle">;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"person">;
+    readonly by: Schema.String;
+}>]>;
+export type ResourceInstanceStopReason = typeof resourceInstanceStopReasonSchema.Type;
+/** What Core last observed of an instance, apart from what was asked of it. Times are ISO. */
+export declare const resourceInstanceStateSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly kind: Schema.Literal<"not-started">;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"starting">;
+    readonly since: Schema.String;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"running">;
+    readonly since: Schema.String;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"stopped">;
+    readonly at: Schema.String;
+    readonly reason: Schema.Union<readonly [Schema.Struct<{
+        readonly kind: Schema.Literal<"idle">;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"person">;
+        readonly by: Schema.String;
+    }>]>;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"exited">;
+    readonly at: Schema.String;
+    readonly exitCode: Schema.NullOr<Schema.Int>;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"failed">;
+    readonly at: Schema.String;
+    readonly message: Schema.String;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"archived">;
+    readonly at: Schema.String;
+}>]>;
+export type ResourceInstanceState = typeof resourceInstanceStateSchema.Type;
+/**
+ * What a spec may never ask for, by the names a caller might send it under, each with the sentence
+ * the refusal carries. None of them is a field of `resourceInstanceSpecSchema`.
+ */
+export declare const FORBIDDEN_RESOURCE_INSTANCE_SPEC_FIELDS: Readonly<Record<string, string>>;
+export interface ResourceInstanceSpecRefusal {
+    /** Where the spec is wrong (`privileged`, `volumes[0].mountPath`); never a value it held. */
+    readonly field: string;
+    readonly reason: string;
+}
+export type ResourceInstanceSpecDecoding = {
+    readonly kind: "spec";
+    readonly spec: ResourceInstanceSpec;
+} | {
+    readonly kind: "refused";
+    readonly refusals: ReadonlyArray<ResourceInstanceSpecRefusal>;
+};
+/**
+ * A spec from outside: each forbidden field refused by name with its sentence, then the schema's
+ * own decode with no excess key allowed.
+ */
+export declare const decodeResourceInstanceSpec: (input: unknown) => ResourceInstanceSpecDecoding;
+export declare const resourceInstanceUpCauseSchema: Schema.Literals<readonly ["use", "person"]>;
+export type ResourceInstanceUpCause = typeof resourceInstanceUpCauseSchema.Type;
+export declare const upResourceInstanceRequestSchema: Schema.Struct<{
+    /**
+     * A `ResourceInstanceSpec`, decoded by `decodeResourceInstanceSpec` so a refused field is named
+     * with its sentence (`ResourceInstanceSpecRefusedError`).
+     */
+    readonly spec: Schema.$Record<Schema.String, Schema.Unknown>;
+    /** `use`: a launch or a wake, which leaves a person's stop standing. `person`: a person's Start. */
+    readonly cause: Schema.Literals<readonly ["use", "person"]>;
+}>;
+export type UpResourceInstanceRequest = typeof upResourceInstanceRequestSchema.Type;
+export declare const stopResourceInstanceRequestSchema: Schema.Struct<{
+    /** The application's words for who stopped it (Mend: a display name). */
+    readonly by: Schema.String;
+}>;
+export type StopResourceInstanceRequest = typeof stopResourceInstanceRequestSchema.Type;
+export declare const resourceInstanceSchema: Schema.Struct<{
+    readonly resourceInstanceId: Schema.brand<Schema.String, "ResourceInstanceId">;
+    readonly key: Schema.brand<Schema.String, "ResourceInstanceKey">;
+    readonly alias: Schema.brand<Schema.String, "ResourceInstanceAlias">;
+    readonly worktreeKey: Schema.NullOr<Schema.brand<Schema.String, "ResourceWorktreeKey">>;
+    readonly specDigest: Schema.String;
+    /** What was asked of it. */
+    readonly desired: Schema.Literals<readonly ["running", "stopped", "archived"]>;
+    /** Why it is stopped, while `desired` is `stopped`. */
+    readonly stopReason: Schema.NullOr<Schema.Union<readonly [Schema.Struct<{
+        readonly kind: Schema.Literal<"idle">;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"person">;
+        readonly by: Schema.String;
+    }>]>>;
+    /** What Core last observed, and when. */
+    readonly state: Schema.Union<readonly [Schema.Struct<{
+        readonly kind: Schema.Literal<"not-started">;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"starting">;
+        readonly since: Schema.String;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"running">;
+        readonly since: Schema.String;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"stopped">;
+        readonly at: Schema.String;
+        readonly reason: Schema.Union<readonly [Schema.Struct<{
+            readonly kind: Schema.Literal<"idle">;
+        }>, Schema.Struct<{
+            readonly kind: Schema.Literal<"person">;
+            readonly by: Schema.String;
+        }>]>;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"exited">;
+        readonly at: Schema.String;
+        readonly exitCode: Schema.NullOr<Schema.Int>;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"failed">;
+        readonly at: Schema.String;
+        readonly message: Schema.String;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"archived">;
+        readonly at: Schema.String;
+    }>]>;
+    readonly observedAt: Schema.String;
+    readonly startedAt: Schema.NullOr<Schema.String>;
+    readonly lastReachedAt: Schema.NullOr<Schema.String>;
+    /** The Docker volumes it mounts, which outlive it. */
+    readonly volumes: Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly dockerName: Schema.String;
+    }>>;
+}>;
+export type ResourceInstanceWire = typeof resourceInstanceSchema.Type;
+export declare const resourceInstanceArchivedVolumeSchema: Schema.Struct<{
+    readonly instanceKey: Schema.brand<Schema.String, "ResourceInstanceKey">;
+    readonly name: Schema.String;
+    readonly dockerName: Schema.String;
+    /** Measured at archive; null when it could not be. */
+    readonly bytes: Schema.NullOr<Schema.Int>;
+}>;
+export type ResourceInstanceArchivedVolumeWire = typeof resourceInstanceArchivedVolumeSchema.Type;
+export declare const listResourceInstancesQuerySchema: Schema.Struct<{
+    /** `true`: the archived instances, whose volumes are kept. Otherwise every other one. */
+    readonly archived: Schema.optional<Schema.Literals<readonly ["true", "false"]>>;
+}>;
+export declare const linkResourceWorkspaceRequestSchema: Schema.Struct<{
+    readonly worktreeKey: Schema.brand<Schema.String, "ResourceWorktreeKey">;
+}>;
+export declare const resourceWorkspaceLinkSchema: Schema.Struct<{
+    readonly workspaceId: Schema.String;
+    readonly worktreeKey: Schema.brand<Schema.String, "ResourceWorktreeKey">;
+    /** How many of the workspace's live executors were attached by this call. */
+    readonly attachedExecutors: Schema.Int;
+}>;
+export type ResourceWorkspaceLinkWire = typeof resourceWorkspaceLinkSchema.Type;
+declare const ResourceInstanceSpecRefusedError_base: Schema.Class<ResourceInstanceSpecRefusedError, Schema.TaggedStruct<"ResourceInstanceSpecRefusedError", {
+    readonly message: Schema.String;
+    readonly refusals: Schema.$Array<Schema.Struct<{
+        readonly field: Schema.String;
+        readonly reason: Schema.String;
+    }>>;
+}>, import("effect/Cause").YieldableError>;
+/** The spec asks for what an instance may never have, or is not a spec; nothing was written. */
+export declare class ResourceInstanceSpecRefusedError extends ResourceInstanceSpecRefusedError_base {
+}
+declare const ResourceInstanceNotFoundError_base: Schema.Class<ResourceInstanceNotFoundError, Schema.TaggedStruct<"ResourceInstanceNotFoundError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class ResourceInstanceNotFoundError extends ResourceInstanceNotFoundError_base {
+}
+declare const ResourceRuntimeUnsupportedError_base: Schema.Class<ResourceRuntimeUnsupportedError, Schema.TaggedStruct<"ResourceRuntimeUnsupportedError", {
+    readonly message: Schema.String;
+    readonly runtime: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** This Sealant's workspace runtime cannot run instances: `resources run on Docker; this Sealant runs <runtime>`. */
+export declare class ResourceRuntimeUnsupportedError extends ResourceRuntimeUnsupportedError_base {
+}
+declare const ResourceInstanceArchivedError_base: Schema.Class<ResourceInstanceArchivedError, Schema.TaggedStruct<"ResourceInstanceArchivedError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** The key names an archived instance: it stays archived, and its volumes are kept. */
+export declare class ResourceInstanceArchivedError extends ResourceInstanceArchivedError_base {
+}
+declare const ResourceInstanceAliasTakenError_base: Schema.Class<ResourceInstanceAliasTakenError, Schema.TaggedStruct<"ResourceInstanceAliasTakenError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** Another instance that is not archived answers to this alias for the same worktree key. */
+export declare class ResourceInstanceAliasTakenError extends ResourceInstanceAliasTakenError_base {
+}
+declare const ResourceDomainNotActiveError_base: Schema.Class<ResourceDomainNotActiveError, Schema.TaggedStruct<"ResourceDomainNotActiveError", {
+    readonly message: Schema.String;
+    readonly state: Schema.Literals<readonly ["fenced", "archived"]>;
+}>, import("effect/Cause").YieldableError>;
+/** The domain is fenced or archived and admits no new instance or link. */
+export declare class ResourceDomainNotActiveError extends ResourceDomainNotActiveError_base {
+}
+declare const ResourceWorkspaceNotFoundError_base: Schema.Class<ResourceWorkspaceNotFoundError, Schema.TaggedStruct<"ResourceWorkspaceNotFoundError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class ResourceWorkspaceNotFoundError extends ResourceWorkspaceNotFoundError_base {
+}
+declare const ResourceWorkspaceLinkedElsewhereError_base: Schema.Class<ResourceWorkspaceLinkedElsewhereError, Schema.TaggedStruct<"ResourceWorkspaceLinkedElsewhereError", {
+    readonly message: Schema.String;
+    readonly resourceDomainId: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** A workspace links to one domain; it is linked to `resourceDomainId`. */
+export declare class ResourceWorkspaceLinkedElsewhereError extends ResourceWorkspaceLinkedElsewhereError_base {
+}
+export declare const ResourceInstancesGroup: HttpApiGroup.HttpApiGroup<"resourceInstances", HttpApiEndpoint.HttpApiEndpoint<"archiveResourceDomain", "POST", "/:resourceDomainId/archive", Schema.toCodecStringTree<Schema.Struct<{
+    readonly resourceDomainId: Schema.String;
+}>>, never, never, never, Schema.toCodecJson<Schema.Struct<{
+    readonly volumes: Schema.$Array<Schema.Struct<{
+        readonly instanceKey: Schema.brand<Schema.String, "ResourceInstanceKey">;
+        readonly name: Schema.String;
+        readonly dockerName: Schema.String;
+        /** Measured at archive; null when it could not be. */
+        readonly bytes: Schema.NullOr<Schema.Int>;
+    }>>;
+}>>, Schema.toCodecJson<typeof ResourceDomainForbiddenError | typeof ResourceDomainNotFoundError | typeof ResourceDomainInternalServerError | typeof ResourceRuntimeUnsupportedError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"archiveResourceInstance", "POST", "/:resourceDomainId/instances/:key/archive", Schema.toCodecStringTree<Schema.Struct<{
+    readonly resourceDomainId: Schema.String;
+    readonly key: Schema.brand<Schema.String, "ResourceInstanceKey">;
+}>>, never, never, never, Schema.toCodecJson<Schema.Struct<{
+    readonly instance: Schema.Struct<{
+        readonly resourceInstanceId: Schema.brand<Schema.String, "ResourceInstanceId">;
+        readonly key: Schema.brand<Schema.String, "ResourceInstanceKey">;
+        readonly alias: Schema.brand<Schema.String, "ResourceInstanceAlias">;
+        readonly worktreeKey: Schema.NullOr<Schema.brand<Schema.String, "ResourceWorktreeKey">>;
+        readonly specDigest: Schema.String;
+        /** What was asked of it. */
+        readonly desired: Schema.Literals<readonly ["running", "stopped", "archived"]>;
+        /** Why it is stopped, while `desired` is `stopped`. */
+        readonly stopReason: Schema.NullOr<Schema.Union<readonly [Schema.Struct<{
+            readonly kind: Schema.Literal<"idle">;
+        }>, Schema.Struct<{
+            readonly kind: Schema.Literal<"person">;
+            readonly by: Schema.String;
+        }>]>>;
+        /** What Core last observed, and when. */
+        readonly state: Schema.Union<readonly [Schema.Struct<{
+            readonly kind: Schema.Literal<"not-started">;
+        }>, Schema.Struct<{
+            readonly kind: Schema.Literal<"starting">;
+            readonly since: Schema.String;
+        }>, Schema.Struct<{
+            readonly kind: Schema.Literal<"running">;
+            readonly since: Schema.String;
+        }>, Schema.Struct<{
+            readonly kind: Schema.Literal<"stopped">;
+            readonly at: Schema.String;
+            readonly reason: Schema.Union<readonly [Schema.Struct<{
+                readonly kind: Schema.Literal<"idle">;
+            }>, Schema.Struct<{
+                readonly kind: Schema.Literal<"person">;
+                readonly by: Schema.String;
+            }>]>;
+        }>, Schema.Struct<{
+            readonly kind: Schema.Literal<"exited">;
+            readonly at: Schema.String;
+            readonly exitCode: Schema.NullOr<Schema.Int>;
+        }>, Schema.Struct<{
+            readonly kind: Schema.Literal<"failed">;
+            readonly at: Schema.String;
+            readonly message: Schema.String;
+        }>, Schema.Struct<{
+            readonly kind: Schema.Literal<"archived">;
+            readonly at: Schema.String;
+        }>]>;
+        readonly observedAt: Schema.String;
+        readonly startedAt: Schema.NullOr<Schema.String>;
+        readonly lastReachedAt: Schema.NullOr<Schema.String>;
+        /** The Docker volumes it mounts, which outlive it. */
+        readonly volumes: Schema.$Array<Schema.Struct<{
+            readonly name: Schema.String;
+            readonly dockerName: Schema.String;
+        }>>;
+    }>;
+    readonly volumes: Schema.$Array<Schema.Struct<{
+        readonly instanceKey: Schema.brand<Schema.String, "ResourceInstanceKey">;
+        readonly name: Schema.String;
+        readonly dockerName: Schema.String;
+        /** Measured at archive; null when it could not be. */
+        readonly bytes: Schema.NullOr<Schema.Int>;
+    }>>;
+}>>, Schema.toCodecJson<typeof ResourceDomainForbiddenError | typeof ResourceDomainNotFoundError | typeof ResourceDomainInternalServerError | typeof ResourceInstanceNotFoundError | typeof ResourceRuntimeUnsupportedError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"getResourceInstance", "GET", "/:resourceDomainId/instances/:key", Schema.toCodecStringTree<Schema.Struct<{
+    readonly resourceDomainId: Schema.String;
+    readonly key: Schema.brand<Schema.String, "ResourceInstanceKey">;
+}>>, never, never, never, Schema.toCodecJson<Schema.Struct<{
+    readonly resourceInstanceId: Schema.brand<Schema.String, "ResourceInstanceId">;
+    readonly key: Schema.brand<Schema.String, "ResourceInstanceKey">;
+    readonly alias: Schema.brand<Schema.String, "ResourceInstanceAlias">;
+    readonly worktreeKey: Schema.NullOr<Schema.brand<Schema.String, "ResourceWorktreeKey">>;
+    readonly specDigest: Schema.String;
+    /** What was asked of it. */
+    readonly desired: Schema.Literals<readonly ["running", "stopped", "archived"]>;
+    /** Why it is stopped, while `desired` is `stopped`. */
+    readonly stopReason: Schema.NullOr<Schema.Union<readonly [Schema.Struct<{
+        readonly kind: Schema.Literal<"idle">;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"person">;
+        readonly by: Schema.String;
+    }>]>>;
+    /** What Core last observed, and when. */
+    readonly state: Schema.Union<readonly [Schema.Struct<{
+        readonly kind: Schema.Literal<"not-started">;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"starting">;
+        readonly since: Schema.String;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"running">;
+        readonly since: Schema.String;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"stopped">;
+        readonly at: Schema.String;
+        readonly reason: Schema.Union<readonly [Schema.Struct<{
+            readonly kind: Schema.Literal<"idle">;
+        }>, Schema.Struct<{
+            readonly kind: Schema.Literal<"person">;
+            readonly by: Schema.String;
+        }>]>;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"exited">;
+        readonly at: Schema.String;
+        readonly exitCode: Schema.NullOr<Schema.Int>;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"failed">;
+        readonly at: Schema.String;
+        readonly message: Schema.String;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"archived">;
+        readonly at: Schema.String;
+    }>]>;
+    readonly observedAt: Schema.String;
+    readonly startedAt: Schema.NullOr<Schema.String>;
+    readonly lastReachedAt: Schema.NullOr<Schema.String>;
+    /** The Docker volumes it mounts, which outlive it. */
+    readonly volumes: Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly dockerName: Schema.String;
+    }>>;
+}>>, Schema.toCodecJson<typeof ResourceDomainForbiddenError | typeof ResourceDomainNotFoundError | typeof ResourceDomainInternalServerError | typeof ResourceInstanceNotFoundError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"linkResourceWorkspace", "PUT", "/:resourceDomainId/workspace-links/:workspaceId", Schema.toCodecStringTree<Schema.Struct<{
+    readonly resourceDomainId: Schema.String;
+    readonly workspaceId: Schema.String;
+}>>, never, Schema.toCodecJson<Schema.Struct<{
+    readonly worktreeKey: Schema.brand<Schema.String, "ResourceWorktreeKey">;
+}>>, never, Schema.toCodecJson<Schema.Struct<{
+    readonly workspaceId: Schema.String;
+    readonly worktreeKey: Schema.brand<Schema.String, "ResourceWorktreeKey">;
+    /** How many of the workspace's live executors were attached by this call. */
+    readonly attachedExecutors: Schema.Int;
+}>>, Schema.toCodecJson<typeof ResourceDomainForbiddenError | typeof ResourceDomainNotFoundError | typeof ResourceDomainInternalServerError | typeof ResourceRuntimeUnsupportedError | typeof ResourceDomainNotActiveError | typeof ResourceWorkspaceNotFoundError | typeof ResourceWorkspaceLinkedElsewhereError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"listResourceInstances", "GET", "/:resourceDomainId/instances", Schema.toCodecStringTree<Schema.Struct<{
+    readonly resourceDomainId: Schema.String;
+}>>, Schema.toCodecStringTree<Schema.Struct<{
+    /** `true`: the archived instances, whose volumes are kept. Otherwise every other one. */
+    readonly archived: Schema.optional<Schema.Literals<readonly ["true", "false"]>>;
+}>>, never, never, Schema.toCodecJson<Schema.Struct<{
+    readonly items: Schema.$Array<Schema.Struct<{
+        readonly resourceInstanceId: Schema.brand<Schema.String, "ResourceInstanceId">;
+        readonly key: Schema.brand<Schema.String, "ResourceInstanceKey">;
+        readonly alias: Schema.brand<Schema.String, "ResourceInstanceAlias">;
+        readonly worktreeKey: Schema.NullOr<Schema.brand<Schema.String, "ResourceWorktreeKey">>;
+        readonly specDigest: Schema.String;
+        /** What was asked of it. */
+        readonly desired: Schema.Literals<readonly ["running", "stopped", "archived"]>;
+        /** Why it is stopped, while `desired` is `stopped`. */
+        readonly stopReason: Schema.NullOr<Schema.Union<readonly [Schema.Struct<{
+            readonly kind: Schema.Literal<"idle">;
+        }>, Schema.Struct<{
+            readonly kind: Schema.Literal<"person">;
+            readonly by: Schema.String;
+        }>]>>;
+        /** What Core last observed, and when. */
+        readonly state: Schema.Union<readonly [Schema.Struct<{
+            readonly kind: Schema.Literal<"not-started">;
+        }>, Schema.Struct<{
+            readonly kind: Schema.Literal<"starting">;
+            readonly since: Schema.String;
+        }>, Schema.Struct<{
+            readonly kind: Schema.Literal<"running">;
+            readonly since: Schema.String;
+        }>, Schema.Struct<{
+            readonly kind: Schema.Literal<"stopped">;
+            readonly at: Schema.String;
+            readonly reason: Schema.Union<readonly [Schema.Struct<{
+                readonly kind: Schema.Literal<"idle">;
+            }>, Schema.Struct<{
+                readonly kind: Schema.Literal<"person">;
+                readonly by: Schema.String;
+            }>]>;
+        }>, Schema.Struct<{
+            readonly kind: Schema.Literal<"exited">;
+            readonly at: Schema.String;
+            readonly exitCode: Schema.NullOr<Schema.Int>;
+        }>, Schema.Struct<{
+            readonly kind: Schema.Literal<"failed">;
+            readonly at: Schema.String;
+            readonly message: Schema.String;
+        }>, Schema.Struct<{
+            readonly kind: Schema.Literal<"archived">;
+            readonly at: Schema.String;
+        }>]>;
+        readonly observedAt: Schema.String;
+        readonly startedAt: Schema.NullOr<Schema.String>;
+        readonly lastReachedAt: Schema.NullOr<Schema.String>;
+        /** The Docker volumes it mounts, which outlive it. */
+        readonly volumes: Schema.$Array<Schema.Struct<{
+            readonly name: Schema.String;
+            readonly dockerName: Schema.String;
+        }>>;
+    }>>;
+}>>, Schema.toCodecJson<typeof ResourceDomainForbiddenError | typeof ResourceDomainNotFoundError | typeof ResourceDomainInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"stopResourceInstance", "POST", "/:resourceDomainId/instances/:key/stop", Schema.toCodecStringTree<Schema.Struct<{
+    readonly resourceDomainId: Schema.String;
+    readonly key: Schema.brand<Schema.String, "ResourceInstanceKey">;
+}>>, never, Schema.toCodecJson<Schema.Struct<{
+    /** The application's words for who stopped it (Mend: a display name). */
+    readonly by: Schema.String;
+}>>, never, Schema.toCodecJson<Schema.Struct<{
+    readonly resourceInstanceId: Schema.brand<Schema.String, "ResourceInstanceId">;
+    readonly key: Schema.brand<Schema.String, "ResourceInstanceKey">;
+    readonly alias: Schema.brand<Schema.String, "ResourceInstanceAlias">;
+    readonly worktreeKey: Schema.NullOr<Schema.brand<Schema.String, "ResourceWorktreeKey">>;
+    readonly specDigest: Schema.String;
+    /** What was asked of it. */
+    readonly desired: Schema.Literals<readonly ["running", "stopped", "archived"]>;
+    /** Why it is stopped, while `desired` is `stopped`. */
+    readonly stopReason: Schema.NullOr<Schema.Union<readonly [Schema.Struct<{
+        readonly kind: Schema.Literal<"idle">;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"person">;
+        readonly by: Schema.String;
+    }>]>>;
+    /** What Core last observed, and when. */
+    readonly state: Schema.Union<readonly [Schema.Struct<{
+        readonly kind: Schema.Literal<"not-started">;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"starting">;
+        readonly since: Schema.String;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"running">;
+        readonly since: Schema.String;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"stopped">;
+        readonly at: Schema.String;
+        readonly reason: Schema.Union<readonly [Schema.Struct<{
+            readonly kind: Schema.Literal<"idle">;
+        }>, Schema.Struct<{
+            readonly kind: Schema.Literal<"person">;
+            readonly by: Schema.String;
+        }>]>;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"exited">;
+        readonly at: Schema.String;
+        readonly exitCode: Schema.NullOr<Schema.Int>;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"failed">;
+        readonly at: Schema.String;
+        readonly message: Schema.String;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"archived">;
+        readonly at: Schema.String;
+    }>]>;
+    readonly observedAt: Schema.String;
+    readonly startedAt: Schema.NullOr<Schema.String>;
+    readonly lastReachedAt: Schema.NullOr<Schema.String>;
+    /** The Docker volumes it mounts, which outlive it. */
+    readonly volumes: Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly dockerName: Schema.String;
+    }>>;
+}>>, Schema.toCodecJson<typeof ResourceDomainForbiddenError | typeof ResourceDomainNotFoundError | typeof ResourceDomainInternalServerError | typeof ResourceInstanceNotFoundError | typeof ResourceRuntimeUnsupportedError | typeof ResourceInstanceArchivedError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"upResourceInstance", "POST", "/:resourceDomainId/instances/:key/up", Schema.toCodecStringTree<Schema.Struct<{
+    readonly resourceDomainId: Schema.String;
+    readonly key: Schema.brand<Schema.String, "ResourceInstanceKey">;
+}>>, never, Schema.toCodecJson<Schema.Struct<{
+    /**
+     * A `ResourceInstanceSpec`, decoded by `decodeResourceInstanceSpec` so a refused field is named
+     * with its sentence (`ResourceInstanceSpecRefusedError`).
+     */
+    readonly spec: Schema.$Record<Schema.String, Schema.Unknown>;
+    /** `use`: a launch or a wake, which leaves a person's stop standing. `person`: a person's Start. */
+    readonly cause: Schema.Literals<readonly ["use", "person"]>;
+}>>, never, Schema.toCodecJson<Schema.Struct<{
+    readonly resourceInstanceId: Schema.brand<Schema.String, "ResourceInstanceId">;
+    readonly key: Schema.brand<Schema.String, "ResourceInstanceKey">;
+    readonly alias: Schema.brand<Schema.String, "ResourceInstanceAlias">;
+    readonly worktreeKey: Schema.NullOr<Schema.brand<Schema.String, "ResourceWorktreeKey">>;
+    readonly specDigest: Schema.String;
+    /** What was asked of it. */
+    readonly desired: Schema.Literals<readonly ["running", "stopped", "archived"]>;
+    /** Why it is stopped, while `desired` is `stopped`. */
+    readonly stopReason: Schema.NullOr<Schema.Union<readonly [Schema.Struct<{
+        readonly kind: Schema.Literal<"idle">;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"person">;
+        readonly by: Schema.String;
+    }>]>>;
+    /** What Core last observed, and when. */
+    readonly state: Schema.Union<readonly [Schema.Struct<{
+        readonly kind: Schema.Literal<"not-started">;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"starting">;
+        readonly since: Schema.String;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"running">;
+        readonly since: Schema.String;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"stopped">;
+        readonly at: Schema.String;
+        readonly reason: Schema.Union<readonly [Schema.Struct<{
+            readonly kind: Schema.Literal<"idle">;
+        }>, Schema.Struct<{
+            readonly kind: Schema.Literal<"person">;
+            readonly by: Schema.String;
+        }>]>;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"exited">;
+        readonly at: Schema.String;
+        readonly exitCode: Schema.NullOr<Schema.Int>;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"failed">;
+        readonly at: Schema.String;
+        readonly message: Schema.String;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"archived">;
+        readonly at: Schema.String;
+    }>]>;
+    readonly observedAt: Schema.String;
+    readonly startedAt: Schema.NullOr<Schema.String>;
+    readonly lastReachedAt: Schema.NullOr<Schema.String>;
+    /** The Docker volumes it mounts, which outlive it. */
+    readonly volumes: Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly dockerName: Schema.String;
+    }>>;
+}>>, Schema.toCodecJson<typeof ResourceDomainForbiddenError | typeof ResourceDomainNotFoundError | typeof ResourceDomainInternalServerError | typeof ResourceInstanceSpecRefusedError | typeof ResourceRuntimeUnsupportedError | typeof ResourceInstanceArchivedError | typeof ResourceInstanceAliasTakenError | typeof ResourceDomainNotActiveError>, never, never>, false>;
+/**
+ * The raw exec route, beside the contract: `POST /v1/resource-domains/:id/instances/:key/exec`.
+ * Its body is one JSON line (`execFrame`, at most `maxFrameBytes`) and then the command's stdin,
+ * raw, to the end of the body. It answers `ResourceInstanceExecResult` as JSON. No header, query or
+ * log line carries the argv or stdin, and no run record is written: a secret goes in stdin.
+ */
+export declare const RESOURCE_INSTANCE_EXEC: {
+    readonly path: "/v1/resource-domains/:resourceDomainId/instances/:key/exec";
+    readonly maxFrameBytes: number;
+    readonly defaultTimeoutMs: number;
+    readonly maxTimeoutMs: number;
+};
+export declare const resourceInstanceExecFrameSchema: Schema.Struct<{
+    readonly argv: Schema.$Array<Schema.String>;
+    readonly user: Schema.NullOr<Schema.String>;
+    readonly timeoutMs: Schema.Int;
+}>;
+export type ResourceInstanceExecFrame = typeof resourceInstanceExecFrameSchema.Type;
+export declare const resourceInstanceExecResultSchema: Schema.Struct<{
+    /** Null when the command was killed at its timeout. */
+    readonly exitCode: Schema.NullOr<Schema.Int>;
+    /** The tail of stdout, at most 1 MiB. */
+    readonly stdout: Schema.String;
+    readonly stderr: Schema.String;
+    readonly truncated: Schema.Boolean;
+    readonly timedOut: Schema.Boolean;
+}>;
+export type ResourceInstanceExecResult = typeof resourceInstanceExecResultSchema.Type;
+export {};