@mostra/protocol 0.0.0-placeholder → 0.1.0

package/src/methods/live/push.ts

@@ -0,0 +1,54 @@
+import * as z from "zod";
+import { LIVE_KEY_PATTERN } from "../../actions.ts";
+import { ArtifactRef } from "../../artifact.ts";
+import { defineMethod, type MethodDefinition } from "../../method.ts";
+import { wireRegistry } from "../../wire-registry.ts";
+
+/** The params of `live/push` (INTERFACES §6, D56). */
+export interface LivePushParams {
+  /** The artifact. */
+  readonly artifact: ArtifactRef;
+  /** The live source's key; a key `live.ts` doesn't define is created by the push. */
+  readonly key: string;
+  /** Any JSON, at most 4 MiB. */
+  readonly value: unknown;
+  /** `replace` (default): the new latest value. `append`: also kept in the source's ring. */
+  readonly mode?: "replace" | "append";
+  /** Makes retries idempotent: a repeated `requestId` returns the recorded result (H-03). */
+  readonly requestId?: string;
+}
+
+/** The result of `live/push`. */
+export interface LivePushResult {
+  /** The value's revision. */
+  readonly revision: string;
+}
+
+const params: z.ZodType<LivePushParams> = z
+  .object({
+    artifact: ArtifactRef,
+    key: z.string().regex(LIVE_KEY_PATTERN),
+    value: z.unknown(),
+    mode: z.enum(["replace", "append"]).exactOptional(),
+    requestId: z.string().min(1).exactOptional(),
+  })
+  .register(wireRegistry, {
+    id: "LivePushParams",
+    description: "A value pushed into an artifact's live source.",
+  }) as z.ZodType<LivePushParams>;
+
+const result: z.ZodType<LivePushResult> = z
+  .object({ revision: z.string() })
+  .register(wireRegistry, { id: "LivePushResult", description: "The pushed value's revision." });
+
+/**
+ * `live/push`: writes a value into an artifact's live source (D56), which every open page reading
+ * it receives at once. The latest value persists; updates are never stored as events (D63).
+ */
+export const livePushMethod: MethodDefinition<LivePushParams, LivePushResult> = defineMethod({
+  method: "live/push",
+  direction: "client-to-instance",
+  mutating: true,
+  params,
+  result,
+});

package/src/methods/mostra/initialize.ts

@@ -0,0 +1,249 @@
+import * as z from "zod";
+import { Diagnostic } from "../../diagnostics/diagnostic.ts";
+import { SubmitChannel } from "../../interaction.ts";
+import { SubmissionPolicy } from "../../manifest.ts";
+import { defineMethod, type MethodDefinition } from "../../method.ts";
+import { Revision } from "../../revision.ts";
+import { wireRegistry } from "../../wire-registry.ts";
+
+/**
+ * A host port name (INTERFACES §7). Port names are open strings on the wire, so an older instance
+ * answers a newer port with a warning instead of refusing the session (D84). `ai` is reserved for
+ * the AI port, which is not part of v1 (D46).
+ */
+export type PortName =
+  | "identity"
+  | "submissions"
+  | "drafts"
+  | "reviews"
+  | "addressing"
+  | "trustedControls"
+  | "capture"
+  | "secrets"
+  | "pty"
+  | "ai"
+  | (string & {});
+
+/** The Zod schema of the `PortName` type. */
+export const PortName: z.ZodType<PortName, string> = z
+  .string()
+  .regex(/^[a-z][a-zA-Z0-9]*$/)
+  .register(wireRegistry, {
+    id: "PortName",
+    description:
+      "A host port name: identity, submissions, drafts, reviews, addressing, trustedControls, capture, secrets, pty, or ai (reserved). Open for later ports.",
+  });
+
+/**
+ * The standalone CLI's client name (D140 item 4). The supervisor marks a home as configured by a
+ * host when any other client sends `home` or `ports`, and the CLI never sends telemetry for such a
+ * home. A host that uses this name as its own is out of scope.
+ */
+export const CLI_CLIENT_NAME = "mostra-cli";
+
+/** The client that opens a connection. */
+export interface ClientInfo {
+  /** The client's name, for logs and status (`mostra-cli`, `jcode`). */
+  readonly name: string;
+  /** The client's own version. */
+  readonly version: string;
+}
+
+/** What the client can handle (D84). */
+export interface ClientCapabilities {
+  /** Notification methods the client accepts. The instance sends no others. */
+  readonly notifications?: readonly string[];
+}
+
+/**
+ * Home settings from a spawning host (INTERFACES §6). Each setting arrives with the package that
+ * implements it.
+ */
+export interface HomeConfig {
+  /**
+   * The home the client expects. A check, not a setting (D84): the instance chose and locked its
+   * home at start-up, and refuses the session with `MOSTRA_HOME_MISMATCH` when this names a
+   * different one.
+   */
+  readonly path?: string;
+  /**
+   * The dependency policy (D43, D95), kept in the home's `config.json` for every later client:
+   * `auto` (the default) installs any package an artifact imports; `explicit` installs only what
+   * `deps/add` adds and reports other imports as `MOSTRA_DEP_MISSING`.
+   */
+  readonly dependencies?: DependencyPolicy;
+  /**
+   * The home's submission policy (D102), kept in `config.json`: it applies to every artifact whose
+   * `artifact/publish` names no policy, before the manifest's request.
+   */
+  readonly submission?: SubmissionPolicy;
+  /**
+   * The ports this client always provides, kept in `config.json` under its `client.name` (D105).
+   * Submissions made while it is away wait in the outbox for it; an empty list stops that.
+   */
+  readonly ports?: readonly PortName[];
+  /**
+   * The submit channels the home accepts (D40, D108), kept in `config.json`: `["shell"]` lets only
+   * the shell's trusted Submit and Choose make submissions and choices; absent, both channels are
+   * allowed. A host's `trustedControls` port answers per view instead, when it is connected.
+   */
+  readonly submitChannels?: readonly SubmitChannel[];
+}
+
+/** How packages enter an artifact's lockfile (D43). */
+export type DependencyPolicy = "auto" | "explicit";
+
+/** The Zod schema of the `DependencyPolicy` type. */
+export const DependencyPolicy: z.ZodType<DependencyPolicy> = z
+  .enum(["auto", "explicit"])
+  .register(wireRegistry, {
+    id: "DependencyPolicy",
+    description:
+      "How packages enter an artifact's lockfile: auto installs what artifacts import; explicit only what deps/add adds (D43).",
+  });
+
+/** The params of `mostra/initialize` (INTERFACES §6). */
+export interface MostraInitializeParams {
+  /** Who is connecting. */
+  readonly client: ClientInfo;
+  /**
+   * The host protocol revisions the client speaks. The instance picks the newest one it also
+   * supports, or refuses with `MOSTRA_HOST_REVISION_UNSUPPORTED`. Entries that aren't revisions
+   * never match.
+   */
+  readonly revisions: readonly string[];
+  /** What the client can handle. */
+  readonly capabilities: ClientCapabilities;
+  /**
+   * Ports the client implements. The instance calls a port only on the connection that registered
+   * it; ports it doesn't support get a `MOSTRA_HOST_PORT_UNSUPPORTED` warning.
+   */
+  readonly ports: readonly PortName[];
+  /** Home settings and the home check. */
+  readonly home?: HomeConfig;
+}
+
+/** The instance a client is connected to. */
+export interface InstanceInfo {
+  /** The runtime release (`@mostra/runtime` version). */
+  readonly version: string;
+  /** The home's real path. */
+  readonly home: string;
+  /** The platform as `<os>-<arch>`, for example `darwin-arm64`. */
+  readonly platform: string;
+  /** The supervisor's process ID. */
+  readonly pid: number;
+  /** `host` when spawned over stdio (`mostra-runtime host`), `daemon` when started as a daemon. */
+  readonly mode: "host" | "daemon";
+}
+
+/** What the instance offers (D84). */
+export interface InstanceCapabilities {
+  /** Every method the instance serves. */
+  readonly methods: readonly string[];
+  /** Every notification the instance may send. */
+  readonly notifications: readonly string[];
+  /** The ports the instance calls when a client registers them. */
+  readonly ports: readonly PortName[];
+}
+
+/** The result of `mostra/initialize`. */
+export interface MostraInitializeResult {
+  /** The negotiated host protocol revision: the newest both sides support. */
+  readonly revision: Revision;
+  /** The instance the client is connected to. */
+  readonly instance: InstanceInfo;
+  /** What the instance offers. */
+  readonly capabilities: InstanceCapabilities;
+  /** Warnings about the session, such as ports the instance doesn't support. */
+  readonly warnings: readonly Diagnostic[];
+}
+
+/** The Zod schema of the `ClientInfo` type. */
+export const ClientInfo: z.ZodType<ClientInfo> = z
+  .object({ name: z.string().min(1), version: z.string() })
+  .register(wireRegistry, { id: "ClientInfo", description: "The client that opens a connection." });
+
+/** The Zod schema of the `ClientCapabilities` type. */
+export const ClientCapabilities: z.ZodType<ClientCapabilities> = z
+  .object({ notifications: z.array(z.string()).readonly().exactOptional() })
+  .register(wireRegistry, {
+    id: "ClientCapabilities",
+    description: "What the client can handle: the notification methods it accepts.",
+  });
+
+/** The Zod schema of the `HomeConfig` type. */
+export const HomeConfig: z.ZodType<HomeConfig> = z
+  .object({
+    path: z.string().min(1).exactOptional(),
+    dependencies: DependencyPolicy.exactOptional(),
+    submission: SubmissionPolicy.exactOptional(),
+    ports: z.array(PortName).max(32).readonly().exactOptional(),
+    submitChannels: z.array(SubmitChannel).min(1).max(2).readonly().exactOptional(),
+  })
+  .register(wireRegistry, {
+    id: "HomeConfig",
+    description:
+      "Home settings from a spawning host; path is a check against the instance's home (D84), dependencies the dependency policy (D43), submission the home's policy (D102), ports those the host always provides (D105).",
+  });
+
+/** The Zod schema of the `InstanceInfo` type. */
+export const InstanceInfo: z.ZodType<InstanceInfo> = z
+  .object({
+    version: z.string(),
+    home: z.string(),
+    platform: z.string(),
+    pid: z.int().min(1),
+    mode: z.enum(["host", "daemon"]),
+  })
+  .register(wireRegistry, {
+    id: "InstanceInfo",
+    description: "The instance a client is connected to.",
+  });
+
+/** The Zod schema of the `InstanceCapabilities` type. */
+export const InstanceCapabilities: z.ZodType<InstanceCapabilities> = z
+  .object({
+    methods: z.array(z.string()).readonly(),
+    notifications: z.array(z.string()).readonly(),
+    ports: z.array(PortName).readonly(),
+  })
+  .register(wireRegistry, {
+    id: "InstanceCapabilities",
+    description: "What the instance offers: methods, notifications and supported ports.",
+  });
+
+const params: z.ZodType<MostraInitializeParams> = z
+  .object({
+    client: ClientInfo,
+    revisions: z.array(z.string()).readonly(),
+    capabilities: ClientCapabilities,
+    ports: z.array(PortName).readonly(),
+    home: HomeConfig.exactOptional(),
+  })
+  .register(wireRegistry, { id: "MostraInitializeParams" });
+
+const result: z.ZodType<MostraInitializeResult> = z
+  .object({
+    revision: Revision.schema,
+    instance: InstanceInfo,
+    capabilities: InstanceCapabilities,
+    warnings: z.array(Diagnostic).readonly(),
+  })
+  .register(wireRegistry, { id: "MostraInitializeResult" });
+
+/**
+ * `mostra/initialize`: opens a session. It must be the first request on a connection and is sent
+ * once. It negotiates the protocol revision, registers the client's ports on this connection and
+ * checks the home (D59, D84).
+ */
+export const mostraInitializeMethod: MethodDefinition<
+  MostraInitializeParams,
+  MostraInitializeResult
+> = defineMethod({
+  method: "mostra/initialize",
+  direction: "client-to-instance",
+  mutating: false,
+  params,
+  result,
+});

package/src/methods/mostra/shutdown.ts

@@ -0,0 +1,31 @@
+import * as z from "zod";
+import { defineMethod, type MethodDefinition } from "../../method.ts";
+import { wireRegistry } from "../../wire-registry.ts";
+
+/** The params of `mostra/shutdown` (INTERFACES §6): none. */
+export type MostraShutdownParams = Record<string, never>;
+
+/** The result of `mostra/shutdown`, sent before the instance stops: empty. */
+export type MostraShutdownResult = Record<string, never>;
+
+const params: z.ZodType<MostraShutdownParams> = z
+  .object({})
+  .register(wireRegistry, { id: "MostraShutdownParams" });
+
+const result: z.ZodType<MostraShutdownResult> = z
+  .object({})
+  .register(wireRegistry, { id: "MostraShutdownResult" });
+
+/**
+ * `mostra/shutdown`: stops the instance cleanly. The instance answers first, then finishes its
+ * ledger work, stops its children, removes its socket and `instance.json`, and exits. Available to
+ * the spawning host and to every attached client of a daemon (D87).
+ */
+export const mostraShutdownMethod: MethodDefinition<MostraShutdownParams, MostraShutdownResult> =
+  defineMethod({
+    method: "mostra/shutdown",
+    direction: "client-to-instance",
+    mutating: false,
+    params,
+    result,
+  });

package/src/methods/port/drafts-mirror.ts

@@ -0,0 +1,52 @@
+import * as z from "zod";
+import { ArtifactId, ViewerId } from "../../ids.ts";
+import { DocumentRevision } from "../../interaction.ts";
+import { defineMethod, type MethodDefinition } from "../../method.ts";
+import { wireRegistry } from "../../wire-registry.ts";
+
+/** A viewer's draft, mirrored to a host as it changes (INTERFACES §7, D105). */
+export interface DraftMirror {
+  /** Always `draft`: a mirror is never a submission (IN-06). */
+  readonly kind: "draft";
+  /** The artifact. */
+  readonly artifactId: string;
+  /** Whose draft it is. */
+  readonly viewerId: string;
+  /** The draft's epoch (D103). */
+  readonly epoch: number;
+  /** The draft's revision; a later mirror has a higher one. */
+  readonly revision: DocumentRevision;
+  /** Every field of the draft by ID. */
+  readonly fields: Readonly<Record<string, unknown>>;
+}
+
+/** The result of `port/drafts.mirror`. */
+export type DraftsMirrorResult = unknown;
+
+/** The Zod schema of the `DraftMirror` type. */
+export const DraftMirror: z.ZodType<DraftMirror> = z
+  .object({
+    kind: z.literal("draft"),
+    artifactId: ArtifactId.schema,
+    viewerId: ViewerId.schema,
+    epoch: z.int().min(1),
+    revision: DocumentRevision,
+    fields: z.record(z.string(), z.unknown()),
+  })
+  .register(wireRegistry, {
+    id: "DraftMirror",
+    description: "A viewer's draft mirrored to a host: always kind draft, never a submission.",
+  });
+
+/**
+ * `port/drafts.mirror`: Mostra sends the latest revision of a viewer's draft to a host that
+ * registered the drafts port, best effort (D105). Mostra's ledger stays canonical (D58).
+ */
+export const portDraftsMirrorMethod: MethodDefinition<DraftMirror, DraftsMirrorResult> =
+  defineMethod({
+    method: "port/drafts.mirror",
+    direction: "instance-to-host",
+    mutating: false,
+    params: DraftMirror,
+    result: z.unknown(),
+  });

package/src/methods/port/secrets-get.ts

@@ -0,0 +1,40 @@
+import * as z from "zod";
+import { defineMethod, type MethodDefinition } from "../../method.ts";
+import { wireRegistry } from "../../wire-registry.ts";
+
+/** The params of `port/secrets.get` (INTERFACES §7, D44). */
+export interface PortSecretsGetParams {
+  /** The artifact whose server code asks. */
+  readonly artifactId: string;
+  /** The secret's name. */
+  readonly name: string;
+}
+
+/** The result of `port/secrets.get`: the value, or `null` when the host has none. */
+export type PortSecretsGetResult = string | null;
+
+const params: z.ZodType<PortSecretsGetParams> = z
+  .object({ artifactId: z.string(), name: z.string() })
+  .register(wireRegistry, {
+    id: "PortSecretsGetParams",
+    description: "The artifact and the name of the secret its server code asks for.",
+  });
+
+const result: z.ZodType<PortSecretsGetResult> = z.string().nullable().register(wireRegistry, {
+  id: "PortSecretsGetResult",
+  description: "The secret's value, or null when the host has none.",
+});
+
+/**
+ * `port/secrets.get`: Mostra asks the host that registered the `secrets` port for a secret its
+ * artifact's server code reads (D44), with 30 seconds to answer. `null` falls back to the home's
+ * own store; a failure or a timeout fails the read with `MOSTRA_SECRET_MISSING`.
+ */
+export const portSecretsGetMethod: MethodDefinition<PortSecretsGetParams, PortSecretsGetResult> =
+  defineMethod({
+    method: "port/secrets.get",
+    direction: "instance-to-host",
+    mutating: false,
+    params,
+    result,
+  });

package/src/methods/port/submissions-deliver.ts

@@ -0,0 +1,70 @@
+import * as z from "zod";
+import { ArtifactId, DeliveryId, SubmissionId } from "../../ids.ts";
+import { Results } from "../../interaction.ts";
+import { defineMethod, type MethodDefinition } from "../../method.ts";
+import { wireRegistry } from "../../wire-registry.ts";
+
+/** One submission delivered to a host (INTERFACES §7, D105). */
+export interface SubmissionEnvelope {
+  /** Always `submission`: a draft never arrives through this port (IN-06). */
+  readonly kind: "submission";
+  /** Stable across redeliveries: treat a repeated ID as the same delivery (H-03). */
+  readonly deliveryId: string;
+  /** The submission. */
+  readonly submissionId: string;
+  /** Its artifact. */
+  readonly artifactId: string;
+  /** 1 for the first attempt; more after retries and restarts. */
+  readonly attempt: number;
+  /** The complete submission (INTERFACES §8), built from the immutable submission alone. */
+  readonly results: Results;
+}
+
+/** What a host answers a delivery. */
+export type SubmissionsDeliverResult =
+  | { readonly accepted: true }
+  | {
+      readonly accepted: false;
+      /** `duplicate` (already held), `undeliverable` (terminal, shown to the viewer), or the host's own. */
+      readonly reason: string;
+      /** `true` keeps the delivery pending and retries it with backoff. */
+      readonly retry: boolean;
+    };
+
+/** The Zod schema of the `SubmissionEnvelope` type. */
+export const SubmissionEnvelope: z.ZodType<SubmissionEnvelope> = z
+  .object({
+    kind: z.literal("submission"),
+    deliveryId: DeliveryId.schema,
+    submissionId: SubmissionId.schema,
+    artifactId: ArtifactId.schema,
+    attempt: z.int().min(1),
+    results: Results,
+  })
+  .register(wireRegistry, {
+    id: "SubmissionEnvelope",
+    description:
+      "One submission delivered to a host: delivery ID, attempt and the complete results.",
+  });
+
+const result: z.ZodType<SubmissionsDeliverResult> = z
+  .union([
+    z.object({ accepted: z.literal(true) }),
+    z.object({ accepted: z.literal(false), reason: z.string().min(1), retry: z.boolean() }),
+  ])
+  .register(wireRegistry, { id: "PortSubmissionsDeliverResult" });
+
+/**
+ * `port/submissions.deliver`: Mostra delivers one submission to the host that registered the
+ * submissions port, after the submission is durable (IN-12), one at a time in submission order.
+ */
+export const portSubmissionsDeliverMethod: MethodDefinition<
+  SubmissionEnvelope,
+  SubmissionsDeliverResult
+> = defineMethod({
+  method: "port/submissions.deliver",
+  direction: "instance-to-host",
+  mutating: false,
+  params: SubmissionEnvelope,
+  result,
+});

package/src/methods/port/trusted-controls-activated.ts

@@ -0,0 +1,51 @@
+import * as z from "zod";
+import { ArtifactId, ViewId } from "../../ids.ts";
+import { TrustedControl, Viewer } from "../../interaction.ts";
+import { defineMethod, type MethodDefinition } from "../../method.ts";
+import { wireRegistry } from "../../wire-registry.ts";
+
+/** The params of `port/trustedControls.activated` (INTERFACES §7): a person used a trusted control. */
+export interface PortTrustedControlsActivatedParams {
+  /** The artifact. */
+  readonly artifactId: string;
+  /** The control: `submit` or `choose`. */
+  readonly control: TrustedControl;
+  /** Who used it. */
+  readonly viewer: Viewer;
+  /** The view it was used in. */
+  readonly viewId: string;
+  /** What it did: the submission it made, or the review set and candidate it chose. */
+  readonly detail?: Readonly<Record<string, string>>;
+}
+
+/** The result of `port/trustedControls.activated`; its content is ignored. */
+export type PortTrustedControlsActivatedResult = unknown;
+
+const params: z.ZodType<PortTrustedControlsActivatedParams> = z
+  .object({
+    artifactId: ArtifactId.schema,
+    control: TrustedControl,
+    viewer: Viewer,
+    viewId: ViewId.schema,
+    detail: z.record(z.string(), z.string()).exactOptional(),
+  })
+  .register(wireRegistry, {
+    id: "PortTrustedControlsActivatedParams",
+    description: "A trusted control a person used: the artifact, control, viewer, view and detail.",
+  });
+
+/**
+ * `port/trustedControls.activated`: after a trusted control's change commits, Mostra tells the
+ * host that registered the `trustedControls` port, best effort and never retried (D108). The
+ * change itself is durable already; this call only lets a host react at once.
+ */
+export const portTrustedControlsActivatedMethod: MethodDefinition<
+  PortTrustedControlsActivatedParams,
+  PortTrustedControlsActivatedResult
+> = defineMethod({
+  method: "port/trustedControls.activated",
+  direction: "instance-to-host",
+  mutating: false,
+  params,
+  result: z.unknown(),
+});

package/src/methods/port/trusted-controls-policy.ts

@@ -0,0 +1,38 @@
+import * as z from "zod";
+import { ArtifactSummary } from "../../artifact.ts";
+import { ControlsPolicy } from "../../interaction.ts";
+import { defineMethod, type MethodDefinition } from "../../method.ts";
+import { wireRegistry } from "../../wire-registry.ts";
+
+/** The params of `port/trustedControls.policy` (INTERFACES §7). */
+export interface PortTrustedControlsPolicyParams {
+  /** The artifact a frame is about to show, with the metadata of its latest version. */
+  readonly artifact: ArtifactSummary;
+}
+
+/** The result of `port/trustedControls.policy`: the channels and controls for the view (D108). */
+export type PortTrustedControlsPolicyResult = ControlsPolicy;
+
+const params: z.ZodType<PortTrustedControlsPolicyParams> = z
+  .object({ artifact: ArtifactSummary })
+  .register(wireRegistry, {
+    id: "PortTrustedControlsPolicyParams",
+    description: "The artifact a frame is about to show, for its host's controls policy.",
+  });
+
+/**
+ * `port/trustedControls.policy`: Mostra asks the host that registered the `trustedControls` port
+ * which submit channels a new view of an artifact accepts and which trusted controls its shell
+ * renders (D108). Asked once per frame load, with 5 seconds to answer; a failure narrows the view
+ * to the shell channel.
+ */
+export const portTrustedControlsPolicyMethod: MethodDefinition<
+  PortTrustedControlsPolicyParams,
+  PortTrustedControlsPolicyResult
+> = defineMethod({
+  method: "port/trustedControls.policy",
+  direction: "instance-to-host",
+  mutating: false,
+  params,
+  result: ControlsPolicy,
+});

package/src/methods/results/get.ts

@@ -0,0 +1,59 @@
+import * as z from "zod";
+import { ArtifactRef } from "../../artifact.ts";
+import { SubmissionId } from "../../ids.ts";
+import { Results } from "../../interaction.ts";
+import { defineMethod, type MethodDefinition } from "../../method.ts";
+import { wireRegistry } from "../../wire-registry.ts";
+
+/** The params of `results/get` (INTERFACES §6, §8). */
+export interface ResultsGetParams {
+  /** The artifact whose submission to read. */
+  readonly artifact: ArtifactRef;
+  /** The submission to read; absent: the artifact's latest. */
+  readonly submission?: string;
+  /** `json` (the default): the Results structure; `md`: Markdown for agents to read. */
+  readonly format?: "json" | "md";
+}
+
+/** Results rendered as Markdown (ROUND-2 §1.1). */
+export interface ResultsMarkdown {
+  /** The submission rendered. */
+  readonly submissionId: string;
+  /** The Markdown: a header with IDs, answers by label, choices, comments, actions, signals, orphans. */
+  readonly markdown: string;
+}
+
+/** The result of `results/get`: the Results structure, or its Markdown for `format: "md"`. */
+export type ResultsGetResult = Results | ResultsMarkdown;
+
+const params: z.ZodType<ResultsGetParams> = z
+  .object({
+    artifact: ArtifactRef,
+    submission: SubmissionId.schema.exactOptional(),
+    format: z.enum(["json", "md"]).exactOptional(),
+  })
+  .register(wireRegistry, { id: "ResultsGetParams" });
+
+/** The Zod schema of the `ResultsMarkdown` type. */
+export const ResultsMarkdown: z.ZodType<ResultsMarkdown> = z
+  .object({ submissionId: SubmissionId.schema, markdown: z.string() })
+  .register(wireRegistry, {
+    id: "ResultsMarkdown",
+    description: "A submission's results as Markdown for agents.",
+  });
+
+const result: z.ZodType<ResultsGetResult> = z
+  .union([Results, ResultsMarkdown])
+  .register(wireRegistry, { id: "ResultsGetResult" });
+
+/**
+ * `results/get`: the complete submission (INTERFACES §8), as JSON or as Markdown. Fails with
+ * `MOSTRA_SUBMIT_NOT_FOUND` when the artifact has no such submission yet.
+ */
+export const resultsGetMethod: MethodDefinition<ResultsGetParams, ResultsGetResult> = defineMethod({
+  method: "results/get",
+  direction: "client-to-instance",
+  mutating: false,
+  params,
+  result,
+});