@mostra/protocol 0.0.0-placeholder → 0.1.0

package/src/manifest.ts

@@ -0,0 +1,206 @@
+/**
+ * The artifact manifest (INTERFACES §2.2, D51): the metadata an artifact declares in its entry, as
+ * `export const artifact = defineArtifact({...})` in TSX or as YAML frontmatter in MDX. Mostra reads
+ * it statically, so every value is a literal. The same type checks `defineArtifact` for authors,
+ * validates the extracted literal in the supervisor and travels on the wire in `artifact/get`.
+ *
+ * ```ts
+ * const checked = ArtifactManifest.safeParse(extracted);
+ * ```
+ */
+import * as z from "zod";
+import { ArtifactId } from "./ids.ts";
+import { wireRegistry } from "./wire-registry.ts";
+
+/** The families Mostra's templates and gallery know; any other string is allowed too. */
+export type ArtifactFamily =
+  | "questionnaire"
+  | "proposal"
+  | "prototype"
+  | "review"
+  | "dashboard"
+  | "deck"
+  | "demo"
+  | "inbox"
+  | "tasks"
+  | (string & {});
+
+/** A related artifact (PRODUCT J6): a later round, a follow-up, a replacement. */
+export interface ArtifactLink {
+  /** How this artifact relates to the other one. */
+  readonly rel: "round-of" | "follows" | "replaces" | (string & {});
+  /** The other artifact's ID. */
+  readonly artifact: string;
+}
+
+/**
+ * The submission policy an artifact requests (D10, D39, D63). The host decides the policy in force;
+ * the manifest only asks for one.
+ */
+export type SubmissionPolicy =
+  | { readonly policy: "once"; readonly scope?: "per-artifact" | "per-viewer" }
+  | { readonly policy: "epochs" }
+  | { readonly policy: "none" };
+
+/** A live terminal session the artifact declares (ROUND-3 §5.1, D65). */
+export interface TerminalSpec {
+  /** The program and its arguments. */
+  readonly command: readonly string[];
+  /** Its working directory, relative to the artifact's source. */
+  readonly cwd?: string;
+  /** Extra environment variables. */
+  readonly env?: Readonly<Record<string, string>>;
+  /** The terminal's width in cells. */
+  readonly cols?: number;
+  /** The terminal's height in cells. */
+  readonly rows?: number;
+  /** Whether viewers may type into it. Sessions are read-only by default. */
+  readonly input?: boolean;
+}
+
+/** A web demo the artifact declares (ROUND-3 §5.4, TM-08): a command to run, or a port to attach to. */
+export type DemoSpec =
+  | {
+      readonly command: readonly string[];
+      readonly cwd?: string;
+      readonly ready?: string;
+      readonly bridge?: boolean;
+    }
+  | { readonly attach: number; readonly bridge?: boolean };
+
+/** The artifact manifest (INTERFACES §2.2). Every field except `title` is optional. */
+export interface ArtifactManifest {
+  /** The artifact's ID. Written by `mostra new`; without one, the artifact is bound to its source path at first publish (D51). */
+  readonly id?: string;
+  /** The title people see. */
+  readonly title: string;
+  /** One or two sentences on what the artifact is for. */
+  readonly description?: string;
+  /** What kind of artifact it is; templates and the gallery group by it. */
+  readonly family?: ArtifactFamily;
+  /** Related artifacts. */
+  readonly links?: readonly ArtifactLink[];
+  /** How the artifact is built and served: `spa`, the default and the only mode in v1 (D19). */
+  readonly mode?: "spa";
+  /** The submission policy the artifact requests; the host decides (D39, D63). */
+  readonly submission?: SubmissionPolicy;
+  /** The kit's shadcn base (default `base`, D72) and theme. */
+  readonly kit?: { readonly base?: "base" | "radix"; readonly theme?: string };
+  /** Live terminal sessions by name (D65). */
+  readonly terminals?: Readonly<Record<string, TerminalSpec>>;
+  /** Web demos by name (D65). */
+  readonly demos?: Readonly<Record<string, DemoSpec>>;
+  /** Stability limits for the artifact's worker (D62). */
+  readonly limits?: {
+    readonly heapMb?: number;
+    readonly watchdogMs?: number;
+    readonly idleMinutes?: number;
+  };
+  /** `verify` settings (D65). */
+  readonly verify?: {
+    readonly viewports?: readonly string[];
+    readonly frames?: readonly string[];
+    readonly extraChecks?: readonly string[];
+    readonly smoke?: boolean;
+  };
+}
+
+/** The keys of the artifact manifest, in INTERFACES §2.2 order. Other keys are warnings (FAILURE_MODEL §10). */
+export const ARTIFACT_MANIFEST_KEYS: readonly (keyof ArtifactManifest)[] = [
+  "id",
+  "title",
+  "description",
+  "family",
+  "links",
+  "mode",
+  "submission",
+  "kit",
+  "terminals",
+  "demos",
+  "limits",
+  "verify",
+];
+
+const strings = z.array(z.string()).readonly();
+
+/** The Zod schema of the `ArtifactLink` type. */
+export const ArtifactLink: z.ZodType<ArtifactLink> = z
+  .object({ rel: z.string().min(1), artifact: z.string().min(1) })
+  .register(wireRegistry, {
+    id: "ArtifactLink",
+    description: "A related artifact: how this one relates (rel) and the other artifact's ID.",
+  });
+
+/** The Zod schema of the `SubmissionPolicy` type. */
+export const SubmissionPolicy: z.ZodType<SubmissionPolicy> = z
+  .discriminatedUnion("policy", [
+    z.object({
+      policy: z.literal("once"),
+      scope: z.enum(["per-artifact", "per-viewer"]).exactOptional(),
+    }),
+    z.object({ policy: z.literal("epochs") }),
+    z.object({ policy: z.literal("none") }),
+  ])
+  .register(wireRegistry, {
+    id: "SubmissionPolicy",
+    description: "A submission policy: once (per-artifact or per-viewer), epochs, or none.",
+  });
+
+const TerminalSpec: z.ZodType<TerminalSpec> = z.object({
+  command: z.array(z.string()).min(1).readonly(),
+  cwd: z.string().exactOptional(),
+  env: z.record(z.string(), z.string()).readonly().exactOptional(),
+  cols: z.int().min(1).exactOptional(),
+  rows: z.int().min(1).exactOptional(),
+  input: z.boolean().exactOptional(),
+});
+
+const DemoSpec: z.ZodType<DemoSpec> = z.union([
+  z.object({
+    command: z.array(z.string()).min(1).readonly(),
+    cwd: z.string().exactOptional(),
+    ready: z.string().exactOptional(),
+    bridge: z.boolean().exactOptional(),
+  }),
+  z.object({ attach: z.int().min(1).max(65535), bridge: z.boolean().exactOptional() }),
+]);
+
+/** The Zod schema of the `ArtifactManifest` type. Objects stay open, so newer keys pass through. */
+export const ArtifactManifest: z.ZodType<ArtifactManifest> = z
+  .object({
+    id: ArtifactId.schema.exactOptional(),
+    title: z.string().min(1),
+    description: z.string().exactOptional(),
+    family: z.string().min(1).exactOptional(),
+    links: z.array(ArtifactLink).readonly().exactOptional(),
+    mode: z.literal("spa").exactOptional(),
+    submission: SubmissionPolicy.exactOptional(),
+    kit: z
+      .object({
+        base: z.enum(["base", "radix"]).exactOptional(),
+        theme: z.string().exactOptional(),
+      })
+      .exactOptional(),
+    terminals: z.record(z.string(), TerminalSpec).readonly().exactOptional(),
+    demos: z.record(z.string(), DemoSpec).readonly().exactOptional(),
+    limits: z
+      .object({
+        heapMb: z.int().min(1).exactOptional(),
+        watchdogMs: z.int().min(1).exactOptional(),
+        idleMinutes: z.number().min(0).exactOptional(),
+      })
+      .exactOptional(),
+    verify: z
+      .object({
+        viewports: strings.exactOptional(),
+        frames: strings.exactOptional(),
+        extraChecks: strings.exactOptional(),
+        smoke: z.boolean().exactOptional(),
+      })
+      .exactOptional(),
+  })
+  .register(wireRegistry, {
+    id: "ArtifactManifest",
+    description:
+      "The artifact manifest (INTERFACES §2.2): literal metadata from the entry's defineArtifact call or MDX frontmatter.",
+  });

package/src/method.ts

@@ -0,0 +1,42 @@
+/**
+ * Host protocol methods (INTERFACES §6, D59): JSON-RPC 2.0 methods between clients and an
+ * instance, each defined once with Zod schemas for its params and result. `pnpm gen
+ * protocol-method <group>/<name>` adds one in the right shape; the method modules live in
+ * `methods/` and are listed in `methods/index.ts`.
+ */
+import type * as z from "zod";
+
+/** Who sends the request: a client to the instance, or the instance to a registering host (ports). */
+export type MethodDirection = "client-to-instance" | "instance-to-host";
+
+/** One protocol method. */
+export interface MethodDefinition<Params, Result> {
+  /** The JSON-RPC method name: `group/name` (`artifact/publish`) or a bare name (`wait`). */
+  readonly method: string;
+  /** Who sends the request. */
+  readonly direction: MethodDirection;
+  /**
+   * Whether the method changes durable state. Mutating methods take an optional `requestId`, and a
+   * retry with the same ID returns the recorded result (H-03).
+   */
+  readonly mutating: boolean;
+  /** The schema of the request's `params`. */
+  readonly params: z.ZodType<Params>;
+  /** The schema of a successful response's `result`. */
+  readonly result: z.ZodType<Result>;
+}
+
+/** A method of any params and result type. */
+export type AnyMethod = MethodDefinition<unknown, unknown>;
+
+/** Defines a protocol method, checking its name has the `group/name` (or bare `name`) form. */
+export function defineMethod<Params, Result>(
+  definition: MethodDefinition<Params, Result>,
+): MethodDefinition<Params, Result> {
+  if (!/^([a-z][a-zA-Z]*\/)?[a-z][a-zA-Z.]*$/.test(definition.method)) {
+    throw new Error(
+      `Protocol method names have the form group/name or name, got "${definition.method}".`,
+    );
+  }
+  return definition;
+}

package/src/methods/artifact/create.ts

@@ -0,0 +1,56 @@
+import * as z from "zod";
+import { ArtifactId } from "../../ids.ts";
+import { defineMethod, type MethodDefinition } from "../../method.ts";
+import { wireRegistry } from "../../wire-registry.ts";
+
+/** The params of `artifact/create` (INTERFACES §6). */
+export interface ArtifactCreateParams {
+  /** The new artifact's directory, absolute. It must not exist yet, or be empty. */
+  readonly dir: string;
+  /** A template to start from. Templates arrive with `mostra new` (WP-26); none is the default. */
+  readonly template?: string;
+  /** The artifact's title. Default: the directory's name. */
+  readonly title?: string;
+  /** Makes retries idempotent: a repeated `requestId` returns the recorded result (H-03). */
+  readonly requestId?: string;
+}
+
+/** The result of `artifact/create`. */
+export interface ArtifactCreateResult {
+  /** The generated artifact ID, written into the entry's manifest. */
+  readonly artifactId: string;
+  /** The artifact's directory (its real path). */
+  readonly dir: string;
+  /** The files written, relative to `dir`. */
+  readonly files: readonly string[];
+}
+
+const params: z.ZodType<ArtifactCreateParams> = z
+  .object({
+    dir: z.string().regex(/^\//),
+    template: z.string().min(1).exactOptional(),
+    title: z.string().min(1).exactOptional(),
+    requestId: z.string().min(1).exactOptional(),
+  })
+  .register(wireRegistry, { id: "ArtifactCreateParams" });
+
+const result: z.ZodType<ArtifactCreateResult> = z
+  .object({
+    artifactId: ArtifactId.schema,
+    dir: z.string(),
+    files: z.array(z.string()).readonly(),
+  })
+  .register(wireRegistry, { id: "ArtifactCreateResult" });
+
+/**
+ * `artifact/create`: writes a new artifact's entry, with a generated artifact ID in its manifest, into
+ * an empty directory. The artifact appears in `artifact/list` once it is published.
+ */
+export const artifactCreateMethod: MethodDefinition<ArtifactCreateParams, ArtifactCreateResult> =
+  defineMethod({
+    method: "artifact/create",
+    direction: "client-to-instance",
+    mutating: true,
+    params,
+    result,
+  });

package/src/methods/artifact/get.ts

@@ -0,0 +1,30 @@
+import * as z from "zod";
+import { ArtifactDetail, ArtifactRef } from "../../artifact.ts";
+import { defineMethod, type MethodDefinition } from "../../method.ts";
+import { wireRegistry } from "../../wire-registry.ts";
+
+/** The params of `artifact/get` (INTERFACES §6). */
+export interface ArtifactGetParams {
+  /** The artifact, by ID or by a source path bound to it. */
+  readonly artifact: ArtifactRef;
+}
+
+/** The result of `artifact/get`. */
+export type ArtifactGetResult = ArtifactDetail;
+
+const params: z.ZodType<ArtifactGetParams> = z
+  .object({ artifact: ArtifactRef })
+  .register(wireRegistry, { id: "ArtifactGetParams" });
+
+/**
+ * `artifact/get`: one artifact with its metadata, policy, source and every version. An unknown
+ * artifact is `MOSTRA_ARTIFACT_NOT_FOUND`.
+ */
+export const artifactGetMethod: MethodDefinition<ArtifactGetParams, ArtifactGetResult> =
+  defineMethod({
+    method: "artifact/get",
+    direction: "client-to-instance",
+    mutating: false,
+    params,
+    result: ArtifactDetail,
+  });

package/src/methods/artifact/list.ts

@@ -0,0 +1,42 @@
+import * as z from "zod";
+import { ArtifactSummary } from "../../artifact.ts";
+import { defineMethod, type MethodDefinition } from "../../method.ts";
+import { wireRegistry } from "../../wire-registry.ts";
+
+/** Narrows `artifact/list`. */
+export interface ArtifactListFilter {
+  /** Only artifacts of this family (INTERFACES §2.2). */
+  readonly family?: string;
+}
+
+/** The params of `artifact/list` (INTERFACES §6). */
+export interface ArtifactListParams {
+  /** Narrows the list; all artifacts when absent. */
+  readonly filter?: ArtifactListFilter;
+}
+
+/** The result of `artifact/list`. */
+export interface ArtifactListResult {
+  /** The home's published artifacts, most recently published first. */
+  readonly artifacts: readonly ArtifactSummary[];
+}
+
+const params: z.ZodType<ArtifactListParams> = z
+  .object({
+    filter: z.object({ family: z.string().min(1).exactOptional() }).exactOptional(),
+  })
+  .register(wireRegistry, { id: "ArtifactListParams" });
+
+const result: z.ZodType<ArtifactListResult> = z
+  .object({ artifacts: z.array(ArtifactSummary).readonly() })
+  .register(wireRegistry, { id: "ArtifactListResult" });
+
+/** `artifact/list`: lists the home's published artifacts. */
+export const artifactListMethod: MethodDefinition<ArtifactListParams, ArtifactListResult> =
+  defineMethod({
+    method: "artifact/list",
+    direction: "client-to-instance",
+    mutating: false,
+    params,
+    result,
+  });

package/src/methods/artifact/publish.ts

@@ -0,0 +1,46 @@
+import * as z from "zod";
+import { PublishReceipt, SourceRef } from "../../artifact.ts";
+import { SubmissionPolicy } from "../../manifest.ts";
+import { defineMethod, type MethodDefinition } from "../../method.ts";
+import { wireRegistry } from "../../wire-registry.ts";
+
+/** The params of `artifact/publish` (INTERFACES §6). */
+export interface ArtifactPublishParams {
+  /** What to publish: a source path, or an artifact ID meaning the path it was last published from. */
+  readonly source: SourceRef;
+  /**
+   * Publish even when `verify` reports errors, recording their codes in the version (D41). The
+   * verify gate arrives with WP-09; until then publish runs no verify and `force` changes nothing.
+   */
+  readonly force?: boolean;
+  /** The submission policy the host decides on, overriding the manifest's request (D39). */
+  readonly policy?: SubmissionPolicy;
+  /** Makes retries idempotent: a repeated `requestId` returns the recorded result (H-03). */
+  readonly requestId?: string;
+}
+
+/** The result of `artifact/publish`: the receipt, durable before it is sent (H-07). */
+export type ArtifactPublishResult = PublishReceipt;
+
+const params: z.ZodType<ArtifactPublishParams> = z
+  .object({
+    source: SourceRef,
+    force: z.boolean().exactOptional(),
+    policy: SubmissionPolicy.exactOptional(),
+    requestId: z.string().min(1).exactOptional(),
+  })
+  .register(wireRegistry, { id: "ArtifactPublishParams" });
+
+/**
+ * `artifact/publish`: freezes an artifact's source into an immutable, content-addressed version and
+ * returns its receipt. A failed publish leaves no version (VR-02); the same source and environment
+ * publish as the existing version (`reused`).
+ */
+export const artifactPublishMethod: MethodDefinition<ArtifactPublishParams, ArtifactPublishResult> =
+  defineMethod({
+    method: "artifact/publish",
+    direction: "client-to-instance",
+    mutating: true,
+    params,
+    result: PublishReceipt,
+  });

package/src/methods/artifact/verify.ts

@@ -0,0 +1,46 @@
+import * as z from "zod";
+import { SourceRef } from "../../artifact.ts";
+import { defineMethod, type MethodDefinition } from "../../method.ts";
+import { ScreenshotPolicy, VerifyVerdict } from "../../verify.ts";
+import { wireRegistry } from "../../wire-registry.ts";
+
+/** The params of `artifact/verify` (INTERFACES §6). */
+export interface ArtifactVerifyParams {
+  /** What to verify: a source path, or an artifact ID meaning the path it was last published from. */
+  readonly source: SourceRef;
+  /**
+   * When the verdict's screenshots are returned to the caller (AX-05): `on-failure` (the default),
+   * `always` or `never`. Screenshots are taken either way; this sets their `returned` flag.
+   */
+  readonly screenshots?: ScreenshotPolicy;
+  /**
+   * Asks for `artifact/progress` notifications carrying this token as the stages run, when the
+   * client accepts them in `mostra/initialize`.
+   */
+  readonly progressToken?: string;
+}
+
+/** The result of `artifact/verify`: the verdict, also cached for the publish that follows (D41). */
+export type ArtifactVerifyResult = VerifyVerdict;
+
+const params: z.ZodType<ArtifactVerifyParams> = z
+  .object({
+    source: SourceRef,
+    screenshots: ScreenshotPolicy.exactOptional(),
+    progressToken: z.string().min(1).max(200).exactOptional(),
+  })
+  .register(wireRegistry, { id: "ArtifactVerifyParams" });
+
+/**
+ * `artifact/verify`: builds, type-checks, renders and exercises an artifact's source headlessly,
+ * compares it with its last passing version, and returns one verdict (D29, D138). It never
+ * publishes and never touches the home's drafts, state, events or deliveries.
+ */
+export const artifactVerifyMethod: MethodDefinition<ArtifactVerifyParams, ArtifactVerifyResult> =
+  defineMethod({
+    method: "artifact/verify",
+    direction: "client-to-instance",
+    mutating: false,
+    params,
+    result: VerifyVerdict,
+  });

package/src/methods/deps/add.ts

@@ -0,0 +1,72 @@
+import * as z from "zod";
+import { SourceRef } from "../../artifact.ts";
+import { defineMethod, type MethodDefinition } from "../../method.ts";
+import { wireRegistry } from "../../wire-registry.ts";
+
+/** The params of `deps/add` (INTERFACES §6, D95). */
+export interface DepsAddParams {
+  /** The artifact whose lockfile gains the packages: a source path, or an artifact ID. */
+  readonly artifact: SourceRef;
+  /**
+   * npm package specs: `name`, `name@version`, `name@range` or `name@tag`, scoped names included.
+   * A spec without an exact version takes the newest release at least a day old (D95).
+   */
+  readonly packages: readonly string[];
+  /** Makes retries idempotent: a repeated `requestId` returns the recorded result (H-03). */
+  readonly requestId?: string;
+}
+
+/** One package `deps/add` settled. */
+export interface AddedPackage {
+  /** The package's name. */
+  readonly name: string;
+  /** The exact version the artifact's lockfile now holds. */
+  readonly version: string;
+  /** Whether it comes from the warm set, which every artifact resolves without an install. */
+  readonly warm: boolean;
+}
+
+/** The result of `deps/add`. */
+export interface DepsAddResult {
+  /** Each requested package, in request order, with the version it resolved to. */
+  readonly packages: readonly AddedPackage[];
+  /** The SHA-256 of the artifact's lockfile after the change: the `lockDigest` its next publish uses. */
+  readonly lockDigest: string;
+}
+
+/** The Zod schema of the `AddedPackage` type. */
+export const AddedPackage: z.ZodType<AddedPackage> = z
+  .object({ name: z.string().min(1), version: z.string().min(1), warm: z.boolean() })
+  .register(wireRegistry, {
+    id: "AddedPackage",
+    description: "A package deps/add settled: its name, exact version and whether it is warm.",
+  });
+
+const params: z.ZodType<DepsAddParams> = z
+  .object({
+    artifact: SourceRef,
+    packages: z.array(z.string().min(1)).min(1).readonly(),
+    requestId: z.string().min(1).exactOptional(),
+  })
+  .register(wireRegistry, { id: "DepsAddParams" });
+
+const result: z.ZodType<DepsAddResult> = z
+  .object({
+    packages: z.array(AddedPackage).readonly(),
+    lockDigest: z.string().regex(/^[0-9a-f]{64}$/),
+  })
+  .register(wireRegistry, { id: "DepsAddResult" });
+
+/**
+ * `deps/add`: installs npm packages into the home's shared store and records them, at exact
+ * versions, in the artifact's lockfile, so its next publish builds with them, offline too. The
+ * method behind `mostra add` (D43, D95), and the only way packages enter a lockfile under the
+ * `explicit` dependency policy.
+ */
+export const depsAddMethod: MethodDefinition<DepsAddParams, DepsAddResult> = defineMethod({
+  method: "deps/add",
+  direction: "client-to-instance",
+  mutating: true,
+  params,
+  result,
+});

package/src/methods/dev/start.ts

@@ -0,0 +1,84 @@
+import * as z from "zod";
+import { SourceRef } from "../../artifact.ts";
+import { Diagnostic } from "../../diagnostics/diagnostic.ts";
+import { defineMethod, type MethodDefinition } from "../../method.ts";
+import { wireRegistry } from "../../wire-registry.ts";
+
+/** The params of `dev/start` (INTERFACES §6, D140 item 12, VR-08). */
+export interface DevStartParams {
+  /** The artifact source to serve with hot reload. */
+  readonly source: SourceRef;
+  /** The loopback port for the dev page; one the operating system assigns when absent. */
+  readonly port?: number;
+}
+
+/** The result of `dev/start`. */
+export interface DevStartResult {
+  /** The dev page, with the session's secret in its fragment (`#t=…`). Never a capability URL. */
+  readonly url: string;
+  /** The loopback port the dev page listens on. */
+  readonly port: number;
+  /** The session, for `dev/stop` and `dev/notify`. */
+  readonly sessionId: string;
+}
+
+const params: z.ZodType<DevStartParams> = z
+  .object({ source: SourceRef, port: z.int().min(1).max(65535).exactOptional() })
+  .register(wireRegistry, { id: "DevStartParams" });
+
+const result: z.ZodType<DevStartResult> = z
+  .object({
+    url: z.string().min(1),
+    port: z.int().min(1).max(65535),
+    sessionId: z.string().min(1),
+  })
+  .register(wireRegistry, { id: "DevStartResult", description: "A running dev session." });
+
+/** The notification a dev session sends the connection that started it (D140 item 12). */
+export const DEV_NOTIFY = "dev/notify";
+
+/** What happened in a dev session. */
+export type DevEventKind = "built" | "reloaded" | "server-restarted" | "submission" | "diagnostics";
+
+/** The params of `dev/notify`. */
+export interface DevNotifyParams {
+  /** The session it happened in. */
+  readonly sessionId: string;
+  /** What happened. */
+  readonly kind: DevEventKind;
+  /** When it happened (RFC 3339, UTC). */
+  readonly at: string;
+  /** What the build or the server code reported (`built`, `diagnostics`, `server-restarted`). */
+  readonly diagnostics?: readonly Diagnostic[];
+  /** The changed files that caused it (`reloaded`, `server-restarted`), relative to the source. */
+  readonly files?: readonly string[];
+  /** A submission's Results JSON (INTERFACES §8), for `submission`; it was delivered nowhere. */
+  readonly results?: unknown;
+}
+
+/** The Zod schema of `dev/notify`'s params. */
+export const DevNotifyParams: z.ZodType<DevNotifyParams> = z
+  .object({
+    sessionId: z.string().min(1),
+    kind: z.enum(["built", "reloaded", "server-restarted", "submission", "diagnostics"]),
+    at: z.iso.datetime(),
+    diagnostics: z.array(Diagnostic).readonly().exactOptional(),
+    files: z.array(z.string()).readonly().exactOptional(),
+    results: z.unknown().exactOptional(),
+  })
+  .register(wireRegistry, { id: "DevNotifyParams", description: "One event of a dev session." });
+
+/**
+ * `dev/start`: serves an artifact's source with Vite's hot module reload on its own loopback
+ * port (VR-08, D140 item 12), with every server feature through a scratch sandbox like verify's:
+ * nothing reaches the home's drafts, state, events, hosts or deliveries, and no capability URL
+ * reaches it. The session belongs to this connection and ends when it closes or with `dev/stop`;
+ * a client that accepts `dev/notify` receives its events.
+ */
+export const devStartMethod: MethodDefinition<DevStartParams, DevStartResult> = defineMethod({
+  method: "dev/start",
+  direction: "client-to-instance",
+  mutating: true,
+  params,
+  result,
+});

package/src/methods/dev/stop.ts

@@ -0,0 +1,32 @@
+import * as z from "zod";
+import { defineMethod, type MethodDefinition } from "../../method.ts";
+import { wireRegistry } from "../../wire-registry.ts";
+
+/** The params of `dev/stop` (INTERFACES §6, D140 item 12). */
+export interface DevStopParams {
+  /** The session `dev/start` returned. */
+  readonly sessionId: string;
+}
+
+/** The result of `dev/stop`. */
+export type DevStopResult = Record<string, never>;
+
+const params: z.ZodType<DevStopParams> = z
+  .object({ sessionId: z.string().min(1) })
+  .register(wireRegistry, { id: "DevStopParams" });
+
+const result: z.ZodType<DevStopResult> = z
+  .object({})
+  .register(wireRegistry, { id: "DevStopResult" });
+
+/**
+ * `dev/stop`: ends a dev session this connection started, stopping its Vite child and workers
+ * and deleting its scratch state. Stopping a session that already ended succeeds.
+ */
+export const devStopMethod: MethodDefinition<DevStopParams, DevStopResult> = defineMethod({
+  method: "dev/stop",
+  direction: "client-to-instance",
+  mutating: true,
+  params,
+  result,
+});