@mostra/protocol 0.0.0-stage → 0.1.0

package/src/methods/secret/delete.ts

@@ -0,0 +1,43 @@
+import * as z from "zod";
+import { SECRET_NAME_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 `secret/delete` (INTERFACES §6). */
+export interface SecretDeleteParams {
+  /** The secret's name. */
+  readonly name: string;
+  /** The artifact whose own secret to delete; absent: the home's shared one. */
+  readonly artifact?: ArtifactRef;
+}
+
+/** The result of `secret/delete`. */
+export interface SecretDeleteResult {
+  /** Whether a secret was there to delete. */
+  readonly deleted: boolean;
+}
+
+const params: z.ZodType<SecretDeleteParams> = z
+  .object({ name: z.string().regex(SECRET_NAME_PATTERN), artifact: ArtifactRef.exactOptional() })
+  .register(wireRegistry, { id: "SecretDeleteParams", description: "The secret to delete." });
+
+const result: z.ZodType<SecretDeleteResult> = z
+  .object({ deleted: z.boolean() })
+  .register(wireRegistry, {
+    id: "SecretDeleteResult",
+    description: "Whether a secret was deleted.",
+  });
+
+/**
+ * `secret/delete`: removes a secret from the home's store. Deleting one that isn't there succeeds
+ * with `deleted: false`, so the method is idempotent and takes no `requestId`.
+ */
+export const secretDeleteMethod: MethodDefinition<SecretDeleteParams, SecretDeleteResult> =
+  defineMethod({
+    method: "secret/delete",
+    direction: "client-to-instance",
+    mutating: false,
+    params,
+    result,
+  });

package/src/methods/secret/list.ts

@@ -0,0 +1,40 @@
+import * as z from "zod";
+import { ArtifactRef } from "../../artifact.ts";
+import { defineMethod, type MethodDefinition } from "../../method.ts";
+import { wireRegistry } from "../../wire-registry.ts";
+import { SecretEntry } from "./set.ts";
+
+/** The params of `secret/list` (INTERFACES §6). */
+export interface SecretListParams {
+  /** Also list this artifact's own secrets; the home's shared ones are always listed. */
+  readonly artifact?: ArtifactRef;
+}
+
+/** The result of `secret/list`: names and scopes, never values. */
+export interface SecretListResult {
+  /** The secrets, home ones first. */
+  readonly secrets: readonly SecretEntry[];
+}
+
+const params: z.ZodType<SecretListParams> = z
+  .object({ artifact: ArtifactRef.exactOptional() })
+  .register(wireRegistry, {
+    id: "SecretListParams",
+    description: "The artifact whose secrets to list.",
+  });
+
+const result: z.ZodType<SecretListResult> = z
+  .object({ secrets: z.array(SecretEntry).readonly() })
+  .register(wireRegistry, { id: "SecretListResult", description: "Secrets by name and scope." });
+
+/**
+ * `secret/list`: the names of the home's shared secrets, and of an artifact's own when one is
+ * named, with their scopes; a value is never returned (D44).
+ */
+export const secretListMethod: MethodDefinition<SecretListParams, SecretListResult> = defineMethod({
+  method: "secret/list",
+  direction: "client-to-instance",
+  mutating: false,
+  params,
+  result,
+});

package/src/methods/secret/set.ts

@@ -0,0 +1,69 @@
+import * as z from "zod";
+import { SECRET_NAME_PATTERN, SECRET_VALUE_MAX } from "../../actions.ts";
+import { ArtifactRef } from "../../artifact.ts";
+import { defineMethod, type MethodDefinition } from "../../method.ts";
+import { wireRegistry } from "../../wire-registry.ts";
+
+/** The params of `secret/set` (INTERFACES §6, D44). */
+export interface SecretSetParams {
+  /** Letters, digits, `_`, `.` and `-`, starting with a letter or `_`, at most 128 characters. */
+  readonly name: string;
+  /** The value, at most 64 KiB of UTF-8. Never returned by any method. */
+  readonly value: string;
+  /** The artifact the secret belongs to; absent: shared by every artifact of the home. */
+  readonly artifact?: ArtifactRef;
+}
+
+/** Where a secret lives. */
+export interface SecretEntry {
+  /** The secret's name. */
+  readonly name: string;
+  /** `artifact` for one artifact's secret, `home` for one every artifact shares. */
+  readonly scope: "artifact" | "home";
+  /** The artifact, for `scope: "artifact"`. */
+  readonly artifactId?: string;
+  /** When it was last set. */
+  readonly updatedAt: string;
+}
+
+/** The Zod schema of the `SecretEntry` type. */
+export const SecretEntry: z.ZodType<SecretEntry> = z
+  .object({
+    name: z.string(),
+    scope: z.enum(["artifact", "home"]),
+    artifactId: z.string().exactOptional(),
+    updatedAt: z.string(),
+  })
+  .register(wireRegistry, {
+    id: "SecretEntry",
+    description: "A secret's name, scope and when it was set; never its value.",
+  });
+
+/** The result of `secret/set`: the secret, without its value. */
+export type SecretSetResult = SecretEntry;
+
+const params: z.ZodType<SecretSetParams> = z
+  .object({
+    name: z.string().regex(SECRET_NAME_PATTERN),
+    // Characters here; the instance also refuses more than 64 KiB of UTF-8.
+    value: z.string().min(1).max(SECRET_VALUE_MAX),
+    artifact: ArtifactRef.exactOptional(),
+  })
+  .register(wireRegistry, {
+    id: "SecretSetParams",
+    description: "A secret's name, value and optional artifact scope.",
+  });
+
+/**
+ * `secret/set`: stores a named secret in the home's owner-only store (D44), for one artifact or
+ * for every artifact of the home; server code reads it with `secret(name)`. Setting it again
+ * replaces the value. Setting is idempotent by nature, so it takes no `requestId`: the ledger
+ * never records anything derived from a secret's value.
+ */
+export const secretSetMethod: MethodDefinition<SecretSetParams, SecretSetResult> = defineMethod({
+  method: "secret/set",
+  direction: "client-to-instance",
+  mutating: false,
+  params,
+  result: SecretEntry,
+});

package/src/methods/state/get.ts

@@ -0,0 +1,44 @@
+import * as z from "zod";
+import { ArtifactRef } from "../../artifact.ts";
+import { DocumentRevision, FieldState } from "../../interaction.ts";
+import { defineMethod, type MethodDefinition } from "../../method.ts";
+import { wireRegistry } from "../../wire-registry.ts";
+
+/** The params of `state/get` (INTERFACES §6, D63). */
+export interface StateGetParams {
+  /** The artifact whose shared state to read. */
+  readonly artifact: ArtifactRef;
+  /** Only these field IDs; absent: every field. */
+  readonly ids?: readonly string[];
+}
+
+/** The result of `state/get`: the artifact state's revision and its fields by ID. */
+export interface StateGetResult {
+  /** The state's revision; pass it as `baseRevision` to `state/patch` for compare-and-set. */
+  readonly revision: DocumentRevision;
+  /** The fields by ID. */
+  readonly fields: Readonly<Record<string, FieldState>>;
+}
+
+const params: z.ZodType<StateGetParams> = z
+  .object({
+    artifact: ArtifactRef,
+    ids: z.array(z.string().min(1).max(256)).max(10_000).readonly().exactOptional(),
+  })
+  .register(wireRegistry, { id: "StateGetParams" });
+
+const result: z.ZodType<StateGetResult> = z
+  .object({ revision: DocumentRevision, fields: z.record(z.string(), FieldState) })
+  .register(wireRegistry, { id: "StateGetResult" });
+
+/**
+ * `state/get`: reads an artifact's shared state (its artifact-scoped fields, D63) with each
+ * field's value, revision and last writer.
+ */
+export const stateGetMethod: MethodDefinition<StateGetParams, StateGetResult> = defineMethod({
+  method: "state/get",
+  direction: "client-to-instance",
+  mutating: false,
+  params,
+  result,
+});

package/src/methods/state/patch.ts

@@ -0,0 +1,51 @@
+import * as z from "zod";
+import { ArtifactRef } from "../../artifact.ts";
+import { MutationId } from "../../ids.ts";
+import { DocumentRevision, FieldOp, MutationResult } from "../../interaction.ts";
+import { defineMethod, type MethodDefinition } from "../../method.ts";
+import { wireRegistry } from "../../wire-registry.ts";
+
+/** The params of `state/patch` (INTERFACES §6, D63, D106). */
+export interface StatePatchParams {
+  /** The artifact whose shared state to write. */
+  readonly artifact: ArtifactRef;
+  /** The field changes, applied together under one revision. */
+  readonly ops: readonly FieldOp[];
+  /**
+   * The state revision the caller last read. A field changed after it is a conflict and keeps its
+   * value; the other ops apply. Absent: every op applies, whatever changed in between.
+   */
+  readonly baseRevision?: DocumentRevision;
+  /**
+   * The change's ID, the idempotency key of this method (H-03): a retry with the same ID and
+   * contents returns the recorded result.
+   */
+  readonly mutationId: string;
+  /** Who writes: `agent` (the default) or `host`, recorded as each field's last writer. */
+  readonly as?: "agent" | "host";
+}
+
+/** The result of `state/patch`. */
+export type StatePatchResult = MutationResult;
+
+const params: z.ZodType<StatePatchParams> = z
+  .object({
+    artifact: ArtifactRef,
+    ops: z.array(FieldOp).min(1).max(1000).readonly(),
+    baseRevision: DocumentRevision.exactOptional(),
+    mutationId: MutationId.schema,
+    as: z.enum(["agent", "host"]).exactOptional(),
+  })
+  .register(wireRegistry, { id: "StatePatchParams" });
+
+/**
+ * `state/patch`: writes an artifact's shared state with compare-and-set and per-field conflicts,
+ * through the same path as viewers' edits (D63). Changes append `state.changed`.
+ */
+export const statePatchMethod: MethodDefinition<StatePatchParams, StatePatchResult> = defineMethod({
+  method: "state/patch",
+  direction: "client-to-instance",
+  mutating: true,
+  params,
+  result: MutationResult,
+});

package/src/methods/view/default.ts

@@ -0,0 +1,32 @@
+import * as z from "zod";
+import { ArtifactRef } from "../../artifact.ts";
+import { defineMethod, type MethodDefinition } from "../../method.ts";
+import { wireRegistry } from "../../wire-registry.ts";
+import { CapabilityLink } from "./url.ts";
+
+/** The params of `view/default` (INTERFACES §6, D140). */
+export interface ViewDefaultParams {
+  /** The artifact whose default link to return. */
+  readonly artifact: ArtifactRef;
+}
+
+/** The result of `view/default`: the artifact's default link (D97 item 3). */
+export type ViewDefaultResult = CapabilityLink;
+
+const params: z.ZodType<ViewDefaultParams> = z
+  .object({ artifact: ArtifactRef })
+  .register(wireRegistry, { id: "ViewDefaultParams" });
+
+/**
+ * `view/default`: the artifact's default link, the one every publish receipt carries (D97 item
+ * 3), without minting a new token. When the default link was revoked, it mints a new default (the
+ * old token stays revoked). `view/url` always mints a separate link.
+ */
+export const viewDefaultMethod: MethodDefinition<ViewDefaultParams, ViewDefaultResult> =
+  defineMethod({
+    method: "view/default",
+    direction: "client-to-instance",
+    mutating: true,
+    params,
+    result: CapabilityLink,
+  });

package/src/methods/view/launch.ts

@@ -0,0 +1,47 @@
+import * as z from "zod";
+import { TokenId } from "../../ids.ts";
+import { defineMethod, type MethodDefinition } from "../../method.ts";
+import { wireRegistry } from "../../wire-registry.ts";
+
+/** The params of `view/launch` (INTERFACES §6, D140 item 15). */
+export interface ViewLaunchParams {
+  /** The link whose session the launch URL opens: a `CapabilityLink.tokenId`. */
+  readonly tokenId: string;
+}
+
+/** The result of `view/launch`. */
+export interface ViewLaunchResult {
+  /**
+   * `http://<url host>:<shell port>/a/<artifactId>[/v/<number>]#l=<ticket>`: a URL to hand a
+   * browser on its command line. The shell exchanges the single-use ticket for the session the
+   * link would give; the link's secret is never in it.
+   */
+  readonly url: string;
+  /** When the ticket stops working, 60 s after it was minted (RFC 3339, UTC). */
+  readonly expiresAt: string;
+}
+
+const params: z.ZodType<ViewLaunchParams> = z
+  .object({ tokenId: TokenId.schema })
+  .register(wireRegistry, { id: "ViewLaunchParams" });
+
+const result: z.ZodType<ViewLaunchResult> = z
+  .object({ url: z.string().min(1), expiresAt: z.iso.datetime() })
+  .register(wireRegistry, {
+    id: "ViewLaunchResult",
+    description: "A one-time launch URL for a browser.",
+  });
+
+/**
+ * `view/launch`: a one-time launch URL for a link (D140 item 15), so a browser opens it without
+ * the link's secret on a command line other local users can read. The ticket is single-use,
+ * lives 60 s and carries 130 bits, like a frame ticket; it is never recorded, so the method takes
+ * no `requestId`. A revoked or expired link is `MOSTRA_HYGIENE_TOKEN_REVOKED`.
+ */
+export const viewLaunchMethod: MethodDefinition<ViewLaunchParams, ViewLaunchResult> = defineMethod({
+  method: "view/launch",
+  direction: "client-to-instance",
+  mutating: true,
+  params,
+  result,
+});

package/src/methods/view/revoke.ts

@@ -0,0 +1,39 @@
+import * as z from "zod";
+import { TokenId } from "../../ids.ts";
+import { defineMethod, type MethodDefinition } from "../../method.ts";
+import { wireRegistry } from "../../wire-registry.ts";
+
+/** The params of `view/revoke` (INTERFACES §6, D97). */
+export interface ViewRevokeParams {
+  /** The token whose link stops working. */
+  readonly tokenId: string;
+  /** Makes retries idempotent: a repeated `requestId` returns the recorded result (H-03). */
+  readonly requestId?: string;
+}
+
+/** The result of `view/revoke`. */
+export type ViewRevokeResult = Record<string, never>;
+
+const params: z.ZodType<ViewRevokeParams> = z
+  .object({
+    tokenId: TokenId.schema,
+    requestId: z.string().min(1).exactOptional(),
+  })
+  .register(wireRegistry, { id: "ViewRevokeParams" });
+
+const result: z.ZodType<ViewRevokeResult> = z
+  .object({})
+  .register(wireRegistry, { id: "ViewRevokeResult" });
+
+/**
+ * `view/revoke`: ends a capability link and every session opened with it; both answer 410 from
+ * then on (HY-03). Revoking a revoked token succeeds; an unknown token is
+ * `MOSTRA_HYGIENE_TOKEN_INVALID`.
+ */
+export const viewRevokeMethod: MethodDefinition<ViewRevokeParams, ViewRevokeResult> = defineMethod({
+  method: "view/revoke",
+  direction: "client-to-instance",
+  mutating: true,
+  params,
+  result,
+});

package/src/methods/view/rotate.ts

@@ -0,0 +1,37 @@
+import * as z from "zod";
+import { TokenId } from "../../ids.ts";
+import { defineMethod, type MethodDefinition } from "../../method.ts";
+import { wireRegistry } from "../../wire-registry.ts";
+import { CapabilityLink } from "./url.ts";
+
+/** The params of `view/rotate` (D97). */
+export interface ViewRotateParams {
+  /** The token to replace. */
+  readonly tokenId: string;
+  /** Makes retries idempotent: a repeated `requestId` returns the same new link (H-03). */
+  readonly requestId?: string;
+}
+
+/** The result of `view/rotate`: the new link. */
+export type ViewRotateResult = CapabilityLink;
+
+const params: z.ZodType<ViewRotateParams> = z
+  .object({
+    tokenId: TokenId.schema,
+    requestId: z.string().min(1).exactOptional(),
+  })
+  .register(wireRegistry, { id: "ViewRotateParams" });
+
+/**
+ * `view/rotate`: replaces a capability link in one step. The new link has the same artifact,
+ * scopes and expiry; the old one and its sessions answer 410 from then on. Rotating the artifact's
+ * default link makes the new one its default. A revoked or expired token can't be rotated
+ * (`MOSTRA_HYGIENE_TOKEN_REVOKED`).
+ */
+export const viewRotateMethod: MethodDefinition<ViewRotateParams, ViewRotateResult> = defineMethod({
+  method: "view/rotate",
+  direction: "client-to-instance",
+  mutating: true,
+  params,
+  result: CapabilityLink,
+});

package/src/methods/view/url.ts

@@ -0,0 +1,84 @@
+import * as z from "zod";
+import { ArtifactRef } from "../../artifact.ts";
+import { CapabilityScope, Duration } from "../../capability.ts";
+import { TokenId, VersionId } from "../../ids.ts";
+import { Viewer, ViewerSpec } from "../../interaction.ts";
+import { defineMethod, type MethodDefinition } from "../../method.ts";
+import { wireRegistry } from "../../wire-registry.ts";
+
+/** The params of `view/url` (INTERFACES §6, D97). */
+export interface ViewUrlParams {
+  /** The artifact the link opens. */
+  readonly artifact: ArtifactRef;
+  /**
+   * The version the link opens, by number or ID. Without it the link opens the artifact's latest
+   * version whenever it is used.
+   */
+  readonly version?: number | string;
+  /** What the link allows (D97). Default: every scope. `view` is always included. */
+  readonly scopes?: readonly CapabilityScope[];
+  /** How long the link works, such as `24h` or `7d`. Default: until it is revoked (D63). */
+  readonly ttl?: Duration;
+  /**
+   * The person the link acts for (D104): its sessions draft, submit and sign as that viewer, so
+   * `once` per-viewer gives each person one submission. Absent: the home's local user.
+   */
+  readonly viewer?: ViewerSpec;
+  /** Makes retries idempotent: a repeated `requestId` returns the same link (H-03). */
+  readonly requestId?: string;
+}
+
+/** A capability link: what `view/url` and `view/rotate` return. */
+export interface CapabilityLink {
+  /** The capability URL. Holding it is the authorization (D06); share it like a password. */
+  readonly url: string;
+  /** The token's ID, for `view/rotate` and `view/revoke`. Never a secret. */
+  readonly tokenId: string;
+  /** The scopes the link carries, `view` included. */
+  readonly scopes: readonly CapabilityScope[];
+  /** When the link stops working; absent when it works until revoked. */
+  readonly expiresAt?: string;
+  /** The viewer the link acts for, when it was minted with one (D104). */
+  readonly viewer?: Viewer;
+}
+
+/** The result of `view/url`. */
+export type ViewUrlResult = CapabilityLink;
+
+/** The Zod schema of the `CapabilityLink` type. */
+export const CapabilityLink: z.ZodType<CapabilityLink> = z
+  .object({
+    url: z.string().min(1),
+    tokenId: TokenId.schema,
+    scopes: z.array(CapabilityScope).readonly(),
+    expiresAt: z.iso.datetime().exactOptional(),
+    viewer: Viewer.exactOptional(),
+  })
+  .register(wireRegistry, {
+    id: "CapabilityLink",
+    description: "A capability URL with its token ID, scopes and expiry.",
+  });
+
+const params: z.ZodType<ViewUrlParams> = z
+  .object({
+    artifact: ArtifactRef,
+    version: z.union([z.int().min(1), VersionId.schema]).exactOptional(),
+    scopes: z.array(CapabilityScope).min(1).readonly().exactOptional(),
+    ttl: Duration.exactOptional(),
+    viewer: ViewerSpec.exactOptional(),
+    requestId: z.string().min(1).exactOptional(),
+  })
+  .register(wireRegistry, { id: "ViewUrlParams" });
+
+/**
+ * `view/url`: mints a new capability link to an artifact, with the scopes and lifetime asked for.
+ * Each call mints a separate token that `view/revoke` ends on its own; the artifact's default link
+ * is the publish receipt's `url`.
+ */
+export const viewUrlMethod: MethodDefinition<ViewUrlParams, ViewUrlResult> = defineMethod({
+  method: "view/url",
+  direction: "client-to-instance",
+  mutating: true,
+  params,
+  result: CapabilityLink,
+});

package/src/methods/wait/wait.ts

@@ -0,0 +1,58 @@
+import * as z from "zod";
+import { ArtifactRef } from "../../artifact.ts";
+import { Cursor } from "../../ids.ts";
+import { EventRecord, WaitCondition } from "../../interaction.ts";
+import { defineMethod, type MethodDefinition } from "../../method.ts";
+import { wireRegistry } from "../../wire-registry.ts";
+
+/** The longest `wait`, in milliseconds: the longest timer JavaScript keeps (about 24.8 days). */
+export const WAIT_MAX_MS = 2_147_483_647;
+
+/** The params of `wait` (INTERFACES §6, ARCHITECTURE §6, D103). */
+export interface WaitParams {
+  /** The artifact to wait on. */
+  readonly artifact: ArtifactRef;
+  /** `submitted`, `signal:<name>`, `state:<fieldId>` or `event:<type>`. */
+  readonly until: WaitCondition;
+  /**
+   * Wait for what happens after this cursor (edge-triggered conditions, and `submitted` under
+   * `epochs`). Default: the cursor of the artifact's latest publish.
+   */
+  readonly after?: string;
+  /** How long to block, in milliseconds; 0 checks once. */
+  readonly timeoutMs: number;
+}
+
+/** The result of `wait`. */
+export type WaitResult =
+  | { readonly status: "satisfied"; readonly event: EventRecord; readonly cursor: string }
+  | { readonly status: "still_waiting"; readonly cursor: string };
+
+const params: z.ZodType<WaitParams> = z
+  .object({
+    artifact: ArtifactRef,
+    until: WaitCondition,
+    after: Cursor.schema.exactOptional(),
+    timeoutMs: z.int().min(0).max(WAIT_MAX_MS),
+  })
+  .register(wireRegistry, { id: "WaitParams" });
+
+const result: z.ZodType<WaitResult> = z
+  .discriminatedUnion("status", [
+    z.object({ status: z.literal("satisfied"), event: EventRecord, cursor: Cursor.schema }),
+    z.object({ status: z.literal("still_waiting"), cursor: Cursor.schema }),
+  ])
+  .register(wireRegistry, { id: "WaitResult" });
+
+/**
+ * `wait`: blocks until a condition holds or the timeout passes (IN-10). `satisfied` carries the
+ * event that met it; `still_waiting` carries the newest cursor examined, so a later wait from it
+ * misses nothing.
+ */
+export const waitMethod: MethodDefinition<WaitParams, WaitResult> = defineMethod({
+  method: "wait",
+  direction: "client-to-instance",
+  mutating: false,
+  params,
+  result,
+});

package/src/revision.ts

@@ -0,0 +1,101 @@
+/**
+ * Dated protocol revisions and their negotiation (INTERFACES §1, STANDARDS versioning, D59).
+ *
+ * The host protocol and the browser protocol each carry a revision named by a date
+ * (`2026-10-10`). A revision only changes additively. A breaking change needs a new revision, and
+ * the old one stays supported for at least 12 months.
+ */
+import * as z from "zod";
+import { type CreateDiagnosticOptions, createDiagnostic } from "./diagnostics/codes/index.ts";
+import type { Diagnostic } from "./diagnostics/diagnostic.ts";
+import { wireRegistry } from "./wire-registry.ts";
+
+/** A protocol revision: a calendar date in `YYYY-MM-DD` form. */
+export type Revision = string & { readonly __mostraRevision: true };
+
+const PATTERN = /^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$/;
+
+function isRevision(value: unknown): value is Revision {
+  if (typeof value !== "string" || !PATTERN.test(value)) return false;
+  const date = new Date(`${value}T00:00:00Z`);
+  return !Number.isNaN(date.getTime()) && date.toISOString().startsWith(value);
+}
+
+/** Protocol revisions. */
+export const Revision: {
+  /** The textual form. `is` and `parse` also reject impossible dates such as `2026-02-30`. */
+  readonly pattern: RegExp;
+  readonly schema: z.ZodType<Revision, string>;
+  is(value: unknown): value is Revision;
+  /** @throws TypeError when `value` is not a real calendar date in `YYYY-MM-DD` form. */
+  parse(value: string): Revision;
+  /** Orders revisions by date: negative when `a` is older than `b`. */
+  compare(a: Revision, b: Revision): number;
+} = {
+  pattern: PATTERN,
+  // z.iso.date() checks calendar validity in its emitted pattern, so the published JSON Schema
+  // rejects 2026-02-30 just as `parse` does.
+  schema: z.iso.date().register(wireRegistry, {
+    id: "Revision",
+    description: "Protocol revision: a calendar date in YYYY-MM-DD form.",
+  }) as unknown as z.ZodType<Revision, string>,
+  is: isRevision,
+  parse(value: string): Revision {
+    if (isRevision(value)) return value;
+    throw new TypeError("Expected a protocol revision: a calendar date in YYYY-MM-DD form.");
+  },
+  compare(a: Revision, b: Revision): number {
+    return a < b ? -1 : a > b ? 1 : 0;
+  },
+};
+
+/**
+ * The host protocol revisions this package's schemas describe, newest first. A runtime built on
+ * this package supports exactly these.
+ */
+export const HOST_PROTOCOL_REVISIONS: readonly Revision[] = [Revision.parse("2026-10-10")];
+
+/** The outcome of {@link negotiateRevision}. */
+export type RevisionNegotiation =
+  | { readonly ok: true; readonly revision: Revision }
+  | { readonly ok: false; readonly diagnostic: Diagnostic };
+
+const LISTED = 8;
+
+function list(revisions: readonly string[]): string {
+  const shown = revisions.slice(0, LISTED).join(", ");
+  return revisions.length > LISTED ? `${shown} and ${revisions.length - LISTED} more` : shown;
+}
+
+/**
+ * Picks the newest host protocol revision that both sides support. When there is none, returns
+ * the refusal diagnostic `MOSTRA_HOST_REVISION_UNSUPPORTED`, which the instance sends back as the
+ * error of `mostra/initialize`.
+ *
+ * Offered entries that are not revisions never match, and the message lists only well-formed
+ * ones, so a malformed offer can't inject text into the diagnostic.
+ */
+export function negotiateRevision(
+  offered: readonly string[],
+  supported: readonly Revision[] = HOST_PROTOCOL_REVISIONS,
+  options: CreateDiagnosticOptions = {},
+): RevisionNegotiation {
+  const offeredRevisions = [...new Set(offered.filter(isRevision))].sort(Revision.compare);
+  const common = offeredRevisions.filter((revision) => supported.includes(revision));
+  const newest = common.at(-1);
+  if (newest !== undefined) return { ok: true, revision: newest };
+
+  const supportedList = [...supported].sort(Revision.compare).reverse();
+  const offeredText =
+    offeredRevisions.length > 0
+      ? `The client offered host protocol revisions ${list(offeredRevisions.reverse())}`
+      : "The client offered no valid host protocol revision";
+  return {
+    ok: false,
+    diagnostic: createDiagnostic(
+      "MOSTRA_HOST_REVISION_UNSUPPORTED",
+      { message: `${offeredText}; this instance supports ${list(supportedList)}.` },
+      options,
+    ),
+  };
+}