@mostra/protocol 0.0.0-stage → 0.1.0

package/src/methods/events/ack.ts

@@ -0,0 +1,41 @@
+import * as z from "zod";
+import { Cursor } from "../../ids.ts";
+import { defineMethod, type MethodDefinition } from "../../method.ts";
+import { wireRegistry } from "../../wire-registry.ts";
+
+/** The params of `events/ack` (INTERFACES §6). */
+export interface EventsAckParams {
+  /** The subscription, as `events/subscribe` returned it. */
+  readonly subscriptionId: string;
+  /** Every event up to this cursor is handled. An earlier cursor than the last ack changes nothing. */
+  readonly cursor: string;
+  /** Accepted for uniformity (H-03); acknowledging is idempotent by itself. */
+  readonly requestId?: string;
+}
+
+/** The result of `events/ack`. */
+export type EventsAckResult = Record<string, never>;
+
+const params: z.ZodType<EventsAckParams> = z
+  .object({
+    subscriptionId: z.string().min(1),
+    cursor: Cursor.schema,
+    requestId: z.string().min(1).exactOptional(),
+  })
+  .register(wireRegistry, { id: "EventsAckParams" });
+
+const result: z.ZodType<EventsAckResult> = z
+  .object({})
+  .register(wireRegistry, { id: "EventsAckResult" });
+
+/**
+ * `events/ack`: records that a subscriber handled every event up to a cursor. For a named
+ * subscription it is durable: the next subscription with that name resumes after it (IN-08).
+ */
+export const eventsAckMethod: MethodDefinition<EventsAckParams, EventsAckResult> = defineMethod({
+  method: "events/ack",
+  direction: "client-to-instance",
+  mutating: true,
+  params,
+  result,
+});

package/src/methods/events/read.ts

@@ -0,0 +1,67 @@
+import * as z from "zod";
+import { Diagnostic } from "../../diagnostics/diagnostic.ts";
+import { Cursor } from "../../ids.ts";
+import { EventFilter, EventRecord } from "../../interaction.ts";
+import { defineMethod, type MethodDefinition } from "../../method.ts";
+import { wireRegistry } from "../../wire-registry.ts";
+
+/** The most events one `events/read` returns. */
+export const EVENTS_READ_MAX = 1000;
+
+/** The params of `events/read` (INTERFACES §6). */
+export interface EventsReadParams {
+  /** Which events; absent: every event. */
+  readonly filter?: EventFilter;
+  /** Events after this cursor; absent: from the start. */
+  readonly after?: string;
+  /** At most this many events (default 100, at most 1000), and about 8 MiB. */
+  readonly limit?: number;
+  /**
+   * When `after` lies inside a compacted range, read on through it instead of being refused with
+   * `MOSTRA_HOST_CURSOR_COMPACTED`: the `artifact.compacted` summary arrives in cursor order among
+   * the other events, and `compacted` says that events after `after` were lost (DATA_MODEL §4).
+   */
+  readonly acceptCompacted?: boolean;
+}
+
+/** The result of `events/read`. */
+export interface EventsReadResult {
+  /** Matching events in cursor order. */
+  readonly events: readonly EventRecord[];
+  /** Where the next read continues: everything up to it was examined. */
+  readonly cursor: string;
+  /**
+   * `MOSTRA_HOST_CURSOR_COMPACTED`, when `acceptCompacted` let the read pass a summary of events
+   * this reader had partly seen: some events after `after` are gone, and `events` holds the summary.
+   */
+  readonly compacted?: Diagnostic;
+}
+
+const params: z.ZodType<EventsReadParams> = z
+  .object({
+    filter: EventFilter.exactOptional(),
+    after: Cursor.schema.exactOptional(),
+    limit: z.int().min(1).max(EVENTS_READ_MAX).exactOptional(),
+    acceptCompacted: z.boolean().exactOptional(),
+  })
+  .register(wireRegistry, { id: "EventsReadParams" });
+
+const result: z.ZodType<EventsReadResult> = z
+  .object({
+    events: z.array(EventRecord).readonly(),
+    cursor: Cursor.schema,
+    compacted: Diagnostic.exactOptional(),
+  })
+  .register(wireRegistry, { id: "EventsReadResult" });
+
+/**
+ * `events/read`: reads durable events after a cursor, in order, without gaps (IN-08). Pass the
+ * returned cursor to continue.
+ */
+export const eventsReadMethod: MethodDefinition<EventsReadParams, EventsReadResult> = defineMethod({
+  method: "events/read",
+  direction: "client-to-instance",
+  mutating: false,
+  params,
+  result,
+});

package/src/methods/events/subscribe.ts

@@ -0,0 +1,91 @@
+import * as z from "zod";
+import { Diagnostic } from "../../diagnostics/diagnostic.ts";
+import { Cursor } from "../../ids.ts";
+import { EventFilter, EventRecord } from "../../interaction.ts";
+import { defineMethod, type MethodDefinition } from "../../method.ts";
+import { wireRegistry } from "../../wire-registry.ts";
+
+/** The notification that carries a subscription's events. */
+export const EVENTS_NOTIFY = "events/notify";
+
+/** The params of `events/subscribe` (INTERFACES §6). */
+export interface EventsSubscribeParams {
+  /** Which events; absent: every event. */
+  readonly filter?: EventFilter;
+  /**
+   * Deliver events after this cursor. Absent: after the named subscriber's acknowledged cursor
+   * (from the start for a new name), or from now on without a name.
+   */
+  readonly after?: string;
+  /**
+   * A durable subscriber name: `events/ack` keeps its cursor across connections and restarts,
+   * and a later subscription with the same name resumes there.
+   */
+  readonly name?: string;
+}
+
+/** The result of `events/subscribe`. */
+export interface EventsSubscribeResult {
+  /** The subscription's ID on this connection, for `events/ack` and `events/unsubscribe`. */
+  readonly subscriptionId: string;
+  /** Where delivery starts: events after this cursor follow as `events/notify`. */
+  readonly cursor: string;
+}
+
+/** The params of the `events/notify` notification. */
+export interface EventsNotifyParams {
+  /** The subscription the events belong to. */
+  readonly subscriptionId: string;
+  /** The next matching events, in cursor order. */
+  readonly events: readonly EventRecord[];
+  /** Everything up to this cursor was examined; acknowledge it once the events are handled. */
+  readonly cursor: string;
+  /**
+   * Set when compaction removed events after this subscription's cursor (DATA_MODEL §4):
+   * `MOSTRA_HOST_CURSOR_COMPACTED`, never a silent gap. `events` then holds the `artifact.compacted`
+   * summary, and the subscription continues after it.
+   */
+  readonly compacted?: Diagnostic;
+}
+
+const params: z.ZodType<EventsSubscribeParams> = z
+  .object({
+    filter: EventFilter.exactOptional(),
+    after: Cursor.schema.exactOptional(),
+    name: z
+      .string()
+      .regex(/^[A-Za-z0-9][A-Za-z0-9._:@-]{0,127}$/)
+      .exactOptional(),
+  })
+  .register(wireRegistry, { id: "EventsSubscribeParams" });
+
+const result: z.ZodType<EventsSubscribeResult> = z
+  .object({ subscriptionId: z.string().min(1), cursor: Cursor.schema })
+  .register(wireRegistry, { id: "EventsSubscribeResult" });
+
+/** The Zod schema of the `events/notify` notification's params. */
+export const EventsNotifyParams: z.ZodType<EventsNotifyParams> = z
+  .object({
+    subscriptionId: z.string().min(1),
+    events: z.array(EventRecord).readonly(),
+    cursor: Cursor.schema,
+    compacted: Diagnostic.exactOptional(),
+  })
+  .register(wireRegistry, {
+    id: "EventsNotifyParams",
+    description: "A subscription's next events, in cursor order, and the cursor examined up to.",
+  });
+
+/**
+ * `events/subscribe`: delivers matching events to this connection as `events/notify`
+ * notifications, in cursor order and without gaps (IN-08, H-09). The client must accept
+ * `events/notify` in `mostra/initialize`.
+ */
+export const eventsSubscribeMethod: MethodDefinition<EventsSubscribeParams, EventsSubscribeResult> =
+  defineMethod({
+    method: "events/subscribe",
+    direction: "client-to-instance",
+    mutating: false,
+    params,
+    result,
+  });

package/src/methods/events/unsubscribe.ts

@@ -0,0 +1,35 @@
+import * as z from "zod";
+import { defineMethod, type MethodDefinition } from "../../method.ts";
+import { wireRegistry } from "../../wire-registry.ts";
+
+/** The params of `events/unsubscribe`. */
+export interface EventsUnsubscribeParams {
+  /** The subscription, as `events/subscribe` returned it. */
+  readonly subscriptionId: string;
+}
+
+/** The result of `events/unsubscribe`. */
+export type EventsUnsubscribeResult = Record<string, never>;
+
+const params: z.ZodType<EventsUnsubscribeParams> = z
+  .object({ subscriptionId: z.string().min(1) })
+  .register(wireRegistry, { id: "EventsUnsubscribeParams" });
+
+const result: z.ZodType<EventsUnsubscribeResult> = z
+  .object({})
+  .register(wireRegistry, { id: "EventsUnsubscribeResult" });
+
+/**
+ * `events/unsubscribe`: ends a subscription on this connection. A named subscriber's acknowledged
+ * cursor stays.
+ */
+export const eventsUnsubscribeMethod: MethodDefinition<
+  EventsUnsubscribeParams,
+  EventsUnsubscribeResult
+> = defineMethod({
+  method: "events/unsubscribe",
+  direction: "client-to-instance",
+  mutating: false,
+  params,
+  result,
+});

package/src/methods/gc/run.ts

@@ -0,0 +1,125 @@
+import * as z from "zod";
+import { Diagnostic } from "../../diagnostics/diagnostic.ts";
+import { ArtifactId, VersionId } from "../../ids.ts";
+import { defineMethod, type MethodDefinition } from "../../method.ts";
+import { wireRegistry } from "../../wire-registry.ts";
+
+/** Event compaction, which `gc/run` does only when asked (D47, DATA_MODEL §4). */
+export interface GcCompactEvents {
+  /** Compact every artifact's events before this cursor. */
+  readonly before: string;
+}
+
+/** The params of `gc/run` (INTERFACES §6, D140 item 18). */
+export interface GcRunParams {
+  /** List what a run would remove, and remove nothing. */
+  readonly dryRun?: boolean;
+  /** Also compact events before a cursor (`mostra gc --compact-events --before <cursor>`). */
+  readonly compactEvents?: GcCompactEvents;
+}
+
+/** One version gc collects, or would: its files go, its row, ID and number stay (D140). */
+export interface GcVersion {
+  /** Its artifact. */
+  readonly artifactId: string;
+  /** Its ID, which stays in the ledger. */
+  readonly versionId: string;
+  /** Its number, which stays too. */
+  readonly number: number;
+  /** The bytes its directory holds. */
+  readonly bytes: number;
+}
+
+/** What one kind of collection reclaims. */
+export interface GcCount {
+  /** How many items. */
+  readonly count: number;
+  /** How many bytes. */
+  readonly bytes: number;
+}
+
+/** What event compaction did, per artifact. */
+export interface GcCompacted {
+  /** The artifacts whose events were compacted, with how many events each lost. */
+  readonly artifacts: readonly { readonly artifactId: string; readonly removed: number }[];
+  /** Every event removed. */
+  readonly removed: number;
+}
+
+/** The result of `gc/run`: what it removed, or with `dryRun` what it would remove. */
+export interface GcRunResult {
+  /** Whether this was a dry run: then nothing was removed. */
+  readonly dryRun: boolean;
+  /** The unreferenced versions whose files go. */
+  readonly versions: readonly GcVersion[];
+  /** Source snapshots no kept version uses. */
+  readonly snapshots: GcCount;
+  /** Lock layouts in `deps/locks` no working lockfile and no kept version names (D95, D135). */
+  readonly lockLayouts: GcCount;
+  /** Packages `pnpm store prune` removes from the shared store. */
+  readonly storePackages: GcCount;
+  /** Build caches past the 5 GB cap, and verify's files no cached verdict names. */
+  readonly caches: GcCount;
+  /** Every byte reclaimed. */
+  readonly bytes: number;
+  /** Present when `compactEvents` was given. */
+  readonly compacted?: GcCompacted;
+  /**
+   * A step that couldn't finish (`MOSTRA_HOME_GC_INCOMPLETE`): it left its files in place, and
+   * the counts above say what this run did remove. Absent when every step finished.
+   */
+  readonly warnings?: readonly Diagnostic[];
+}
+
+const count = z.object({ count: z.int().min(0), bytes: z.int().min(0) });
+
+const params: z.ZodType<GcRunParams> = z
+  .object({
+    dryRun: z.boolean().exactOptional(),
+    compactEvents: z.object({ before: z.string().regex(/^[0-9]+$/) }).exactOptional(),
+  })
+  .register(wireRegistry, { id: "GcRunParams" });
+
+const result: z.ZodType<GcRunResult> = z
+  .object({
+    dryRun: z.boolean(),
+    versions: z
+      .array(
+        z.object({
+          artifactId: ArtifactId.schema,
+          versionId: VersionId.schema,
+          number: z.int().min(1),
+          bytes: z.int().min(0),
+        }),
+      )
+      .readonly(),
+    snapshots: count,
+    lockLayouts: count,
+    storePackages: count,
+    caches: count,
+    bytes: z.int().min(0),
+    compacted: z
+      .object({
+        artifacts: z
+          .array(z.object({ artifactId: ArtifactId.schema, removed: z.int().min(0) }))
+          .readonly(),
+        removed: z.int().min(0),
+      })
+      .exactOptional(),
+    warnings: z.array(Diagnostic).readonly().exactOptional(),
+  })
+  .register(wireRegistry, { id: "GcRunResult", description: "What gc reclaimed." });
+
+/**
+ * `gc/run`: collects what nothing references (VR-06, D47, D140): versions' files (each keeps its
+ * ledger row as a tombstone), unused source snapshots, lock layouts, the shared store's unused
+ * packages and caches; with `compactEvents`, it also compacts events before a cursor. A dry run
+ * lists exactly what a real run removes. It runs one at a time with publish, verify and installs.
+ */
+export const gcRunMethod: MethodDefinition<GcRunParams, GcRunResult> = defineMethod({
+  method: "gc/run",
+  direction: "client-to-instance",
+  mutating: true,
+  params,
+  result,
+});

package/src/methods/index.ts

@@ -0,0 +1,81 @@
+/**
+ * Every host protocol method this package defines. `pnpm gen protocol-method` adds entries at the
+ * markers; the method itself lives in its own module under `methods/<group>/`.
+ */
+import type { AnyMethod } from "../method.ts";
+import { artifactCreateMethod } from "./artifact/create.ts";
+import { artifactGetMethod } from "./artifact/get.ts";
+import { artifactListMethod } from "./artifact/list.ts";
+import { artifactPublishMethod } from "./artifact/publish.ts";
+import { artifactVerifyMethod } from "./artifact/verify.ts";
+import { depsAddMethod } from "./deps/add.ts";
+import { devStartMethod } from "./dev/start.ts";
+import { devStopMethod } from "./dev/stop.ts";
+import { eventsAckMethod } from "./events/ack.ts";
+import { eventsReadMethod } from "./events/read.ts";
+import { eventsSubscribeMethod } from "./events/subscribe.ts";
+import { eventsUnsubscribeMethod } from "./events/unsubscribe.ts";
+import { gcRunMethod } from "./gc/run.ts";
+import { instanceCheckMethod } from "./instance/check.ts";
+import { instanceStatusMethod } from "./instance/status.ts";
+import { livePushMethod } from "./live/push.ts";
+import { mostraInitializeMethod } from "./mostra/initialize.ts";
+import { mostraShutdownMethod } from "./mostra/shutdown.ts";
+import { portDraftsMirrorMethod } from "./port/drafts-mirror.ts";
+import { portSecretsGetMethod } from "./port/secrets-get.ts";
+import { portSubmissionsDeliverMethod } from "./port/submissions-deliver.ts";
+import { portTrustedControlsActivatedMethod } from "./port/trusted-controls-activated.ts";
+import { portTrustedControlsPolicyMethod } from "./port/trusted-controls-policy.ts";
+import { resultsGetMethod } from "./results/get.ts";
+import { secretDeleteMethod } from "./secret/delete.ts";
+import { secretListMethod } from "./secret/list.ts";
+import { secretSetMethod } from "./secret/set.ts";
+import { stateGetMethod } from "./state/get.ts";
+import { statePatchMethod } from "./state/patch.ts";
+import { viewDefaultMethod } from "./view/default.ts";
+import { viewLaunchMethod } from "./view/launch.ts";
+import { viewRevokeMethod } from "./view/revoke.ts";
+import { viewRotateMethod } from "./view/rotate.ts";
+import { viewUrlMethod } from "./view/url.ts";
+import { waitMethod } from "./wait/wait.ts";
+// gen:method-imports
+
+/** Every host protocol method, in the order they were added. */
+export const hostMethods: readonly AnyMethod[] = [
+  mostraInitializeMethod,
+  mostraShutdownMethod,
+  instanceStatusMethod,
+  artifactCreateMethod,
+  artifactPublishMethod,
+  artifactListMethod,
+  artifactGetMethod,
+  depsAddMethod,
+  viewUrlMethod,
+  viewRevokeMethod,
+  viewRotateMethod,
+  stateGetMethod,
+  resultsGetMethod,
+  waitMethod,
+  eventsReadMethod,
+  eventsSubscribeMethod,
+  eventsUnsubscribeMethod,
+  statePatchMethod,
+  eventsAckMethod,
+  portSubmissionsDeliverMethod,
+  portDraftsMirrorMethod,
+  portTrustedControlsPolicyMethod,
+  portTrustedControlsActivatedMethod,
+  secretSetMethod,
+  secretListMethod,
+  secretDeleteMethod,
+  livePushMethod,
+  portSecretsGetMethod,
+  artifactVerifyMethod,
+  viewDefaultMethod,
+  viewLaunchMethod,
+  gcRunMethod,
+  instanceCheckMethod,
+  devStartMethod,
+  devStopMethod,
+  // gen:methods
+];

package/src/methods/instance/check.ts

@@ -0,0 +1,61 @@
+import * as z from "zod";
+import { Diagnostic } from "../../diagnostics/diagnostic.ts";
+import { defineMethod, type MethodDefinition } from "../../method.ts";
+import { wireRegistry } from "../../wire-registry.ts";
+
+/** The params of `instance/check` (INTERFACES §6, D140 item 18). */
+export interface InstanceCheckParams {
+  /** Also hash every version directory against its `outputDigest` (`mostra doctor --deep`). */
+  readonly deep?: boolean;
+}
+
+/** One check's outcome. */
+export interface InstanceCheck {
+  /** What was checked: `ledger`, `versions`, `ports`, `browser`, `shell`, `warm` and so on. */
+  readonly name: string;
+  /** `ok`, or how serious what it found is. */
+  readonly status: "ok" | "warning" | "error";
+  /** What is wrong and what to do, for a warning or an error. */
+  readonly diagnostic?: Diagnostic;
+}
+
+/** The result of `instance/check`. */
+export interface InstanceCheckResult {
+  /** Every check, in the order it ran. */
+  readonly checks: readonly InstanceCheck[];
+}
+
+const params: z.ZodType<InstanceCheckParams> = z
+  .object({ deep: z.boolean().exactOptional() })
+  .register(wireRegistry, { id: "InstanceCheckParams" });
+
+const result: z.ZodType<InstanceCheckResult> = z
+  .object({
+    checks: z
+      .array(
+        z.object({
+          name: z.string().min(1),
+          status: z.enum(["ok", "warning", "error"]),
+          diagnostic: Diagnostic.exactOptional(),
+        }),
+      )
+      .readonly(),
+  })
+  .register(wireRegistry, {
+    id: "InstanceCheckResult",
+    description: "The supervisor's own checks of its home.",
+  });
+
+/**
+ * `instance/check`: the checks only the supervisor can run, because it holds the ledger's lock
+ * (D81): the ledger's integrity, the version store, leased ports another program holds, and the
+ * runtime's browser, shell and warm set. `mostra doctor` adds the checks a client runs itself.
+ */
+export const instanceCheckMethod: MethodDefinition<InstanceCheckParams, InstanceCheckResult> =
+  defineMethod({
+    method: "instance/check",
+    direction: "client-to-instance",
+    mutating: false,
+    params,
+    result,
+  });

package/src/methods/instance/status.ts

@@ -0,0 +1,172 @@
+import * as z from "zod";
+import { defineMethod, type MethodDefinition } from "../../method.ts";
+import { wireRegistry } from "../../wire-registry.ts";
+import { InstanceInfo } from "../mostra/initialize.ts";
+
+/** The params of `instance/status` (INTERFACES §6): none. */
+export type InstanceStatusParams = Record<string, never>;
+
+/** One child process the instance supervises. */
+export interface ChildProcessStatus {
+  /** The process ID. The child leads its own process group, so this is also its group ID. */
+  readonly pid: number;
+  /** What the child is: `builder`, `verify`, `worker`, `pty-host`, `demo`, `install` and so on. */
+  readonly kind: string;
+  /** What the child serves, such as an artifact or version ID. */
+  readonly ownerRef: string;
+  /** When the instance started it (RFC 3339, UTC). */
+  readonly startedAt: string;
+}
+
+/** Where the gateway listens (D99, WP-05). */
+export interface GatewayStatus {
+  /** The address its listeners bind: `127.0.0.1` unless the instance started with `--bind`. */
+  readonly bind: string;
+  /** The shell's origin, where every capability link points. */
+  readonly shell: string;
+  /** The artifact origins it is serving now, one per opened artifact. */
+  readonly artifacts: readonly { readonly artifactId: string; readonly origin: string }[];
+}
+
+/**
+ * The result of `instance/status`. The packages that add ports, deliveries, shares and versions
+ * add their fields here (INTERFACES §6).
+ */
+export interface InstanceStatusResult {
+  /** The instance itself. */
+  readonly instance: InstanceInfo;
+  /** When the instance took ownership of its home (RFC 3339, UTC). */
+  readonly startedAt: string;
+  /** The control socket clients attach to. */
+  readonly socket: string;
+  /** How many protocol connections are open, this one included. */
+  readonly connections: number;
+  /** The child processes the instance supervises. */
+  readonly processes: readonly ChildProcessStatus[];
+  /** Where the gateway listens, once it has started (WP-05). */
+  readonly gateway?: GatewayStatus;
+  /** The outbox per host (WP-06, D105): how many deliveries are in each state. */
+  readonly deliveries?: readonly DeliveryCounts[];
+  /** The artifact workers, one per active version with server code (WP-08, RT-03). */
+  readonly workers?: readonly WorkerStatus[];
+  /** When the daemon exits for lack of work, if it will (WP-08, RT-08); absent: it won't. */
+  readonly idleExitAt?: string;
+}
+
+/** One artifact version's worker (RT-03, D62). */
+export interface WorkerStatus {
+  /** The artifact. */
+  readonly artifactId: string;
+  /** The version. */
+  readonly versionId: string;
+  /**
+   * `starting`, `ready`, `backoff` (it crashed and restarts on the next request after `retryAt`),
+   * `parked` (it crashed more than 5 times in 10 minutes, FAILURE_MODEL §2), `stopped`.
+   */
+  readonly state: "starting" | "ready" | "backoff" | "parked" | "stopped";
+  /** The worker's process, while it runs locally. */
+  readonly pid?: number;
+  /** Crashes in the last 10 minutes. */
+  readonly crashes: number;
+  /** The last crash's cause, such as `out of memory` or `event loop blocked for 10 s`. */
+  readonly lastCause?: string;
+  /** When a worker in `backoff` may start again. */
+  readonly retryAt?: string;
+  /** Calls, runs and live producers it serves now. */
+  readonly active: number;
+}
+
+/** The Zod schema of the `WorkerStatus` type. */
+export const WorkerStatus: z.ZodType<WorkerStatus> = z
+  .object({
+    artifactId: z.string(),
+    versionId: z.string(),
+    state: z.enum(["starting", "ready", "backoff", "parked", "stopped"]),
+    pid: z.int().min(1).exactOptional(),
+    crashes: z.int().min(0),
+    lastCause: z.string().exactOptional(),
+    retryAt: z.string().exactOptional(),
+    active: z.int().min(0),
+  })
+  .register(wireRegistry, { id: "WorkerStatus", description: "One artifact version's worker." });
+
+/** One host's deliveries by state (D105). */
+export interface DeliveryCounts {
+  /** The host's client name; empty for Mostra's built-in adapter (D105). */
+  readonly owner: string;
+  /** Whether a connection of this host has the submissions port registered now. */
+  readonly connected: boolean;
+  /** Deliveries not yet answered terminally. */
+  readonly pending: number;
+  /** Deliveries the host accepted. */
+  readonly delivered: number;
+  /** Deliveries the host rejected terminally. */
+  readonly rejected: number;
+  /** Deliveries the host declared undeliverable. */
+  readonly undeliverable: number;
+}
+
+/** The Zod schema of the `DeliveryCounts` type. */
+export const DeliveryCounts: z.ZodType<DeliveryCounts> = z
+  .object({
+    owner: z.string(),
+    connected: z.boolean(),
+    pending: z.int().min(0),
+    delivered: z.int().min(0),
+    rejected: z.int().min(0),
+    undeliverable: z.int().min(0),
+  })
+  .register(wireRegistry, {
+    id: "DeliveryCounts",
+    description: "One host's deliveries by state, and whether it is connected.",
+  });
+
+/** The Zod schema of the `GatewayStatus` type. */
+export const GatewayStatus: z.ZodType<GatewayStatus> = z
+  .object({
+    bind: z.string(),
+    shell: z.string(),
+    artifacts: z.array(z.object({ artifactId: z.string(), origin: z.string() })).readonly(),
+  })
+  .register(wireRegistry, { id: "GatewayStatus", description: "Where the gateway listens." });
+
+/** The Zod schema of the `ChildProcessStatus` type. */
+export const ChildProcessStatus: z.ZodType<ChildProcessStatus> = z
+  .object({
+    pid: z.int().min(1),
+    kind: z.string(),
+    ownerRef: z.string(),
+    startedAt: z.iso.datetime(),
+  })
+  .register(wireRegistry, {
+    id: "ChildProcessStatus",
+    description: "One child process the instance supervises.",
+  });
+
+const params: z.ZodType<InstanceStatusParams> = z
+  .object({})
+  .register(wireRegistry, { id: "InstanceStatusParams" });
+
+const result: z.ZodType<InstanceStatusResult> = z
+  .object({
+    instance: InstanceInfo,
+    startedAt: z.iso.datetime(),
+    socket: z.string(),
+    connections: z.int().min(0),
+    processes: z.array(ChildProcessStatus).readonly(),
+    gateway: GatewayStatus.exactOptional(),
+    deliveries: z.array(DeliveryCounts).readonly().exactOptional(),
+    workers: z.array(WorkerStatus).readonly().exactOptional(),
+    idleExitAt: z.string().exactOptional(),
+  })
+  .register(wireRegistry, { id: "InstanceStatusResult" });
+
+/** `instance/status`: reports the instance, its socket, its connections and its child processes. */
+export const instanceStatusMethod: MethodDefinition<InstanceStatusParams, InstanceStatusResult> =
+  defineMethod({
+    method: "instance/status",
+    direction: "client-to-instance",
+    mutating: false,
+    params,
+    result,
+  });