@mostra/protocol 0.0.0-stage → 0.1.0

package/src/browser.ts

@@ -0,0 +1,374 @@
+/**
+ * The browser protocol (INTERFACES §4, D106): what the client runtime in an artifact's frame sends
+ * to the gateway and receives from it. Published versions embed the client runtime, so a gateway
+ * serves every revision it ever shipped (FAILURE_MODEL §7); within a revision payloads only grow.
+ * Paths are `/_mostra/v/{revision}/…` on the artifact's origin.
+ *
+ * ```ts
+ * const body: FieldsRequest = { mutationId, scope: "viewer", baseRevision: "3", viewId, ops };
+ * await fetch(`/_mostra/v/${BROWSER_PROTOCOL_REVISION}/fields`, { method: "POST", body: … });
+ * ```
+ */
+import * as z from "zod";
+import type { EphemeralMessage } from "./actions.ts";
+import { ArtifactId, Cursor, MutationId, ViewId } from "./ids.ts";
+import {
+  DocumentRevision,
+  EventRecord,
+  FieldOp,
+  FieldState,
+  SubmissionSummary,
+  Viewer,
+} from "./interaction.ts";
+import { SubmissionPolicy } from "./manifest.ts";
+import {
+  REVIEW_SET_ID_PATTERN,
+  SubmitChannel,
+  TrustedControl,
+  VersionRef,
+  type ViewContext,
+} from "./view.ts";
+import { wireRegistry } from "./wire-registry.ts";
+
+export {
+  type DeliveryTarget,
+  REVIEW_SET_ID_PATTERN,
+  readViewContext,
+  VersionRef,
+  ViewContext,
+  ViewContextWire,
+} from "./view.ts";
+
+/** Every browser-protocol revision this release serves, oldest first. */
+export const BROWSER_PROTOCOL_REVISIONS: readonly ["2026-10-15"] = ["2026-10-15"];
+
+/** The newest browser-protocol revision: what a client runtime built now speaks. */
+export const BROWSER_PROTOCOL_REVISION = "2026-10-15";
+
+/** The longest JSON a signal's payload may be, in UTF-8 bytes (D106). */
+export const SIGNAL_PAYLOAD_MAX_BYTES: number = 64 * 1024;
+
+/** `POST …/fields`: one mutation of the viewer's draft or the artifact's state. */
+export interface FieldsRequest {
+  /** A fresh `mut_` ID per change; a retry repeats it and gets the recorded result. */
+  readonly mutationId: string;
+  /** Which document: the viewer's draft or the artifact's shared state. */
+  readonly scope: "viewer" | "artifact";
+  /** The document revision the page last saw; fields changed after it come back as conflicts. */
+  readonly baseRevision: DocumentRevision;
+  /** The view the page was opened as (D104). */
+  readonly viewId: string;
+  /** The field changes, applied together under one revision. */
+  readonly ops: readonly FieldOp[];
+}
+
+/** The Zod schema of the `FieldsRequest` type. */
+export const FieldsRequest: z.ZodType<FieldsRequest> = z
+  .object({
+    mutationId: MutationId.schema,
+    scope: z.enum(["viewer", "artifact"]),
+    baseRevision: DocumentRevision,
+    viewId: ViewId.schema,
+    ops: z.array(FieldOp).min(1).max(1000).readonly(),
+  })
+  .register(wireRegistry, {
+    id: "FieldsRequest",
+    description: "A browser mutation: its ID, scope, base revision, view and field ops.",
+  });
+
+/** `POST …/submit`: submit the viewer's draft from the artifact's own code (D40). */
+export interface SubmitRequest {
+  /** The view the page was opened as (D104); its version is what the submission names. */
+  readonly viewId: string;
+  /** The draft revision the viewer saw; another one is `MOSTRA_SUBMIT_REVISION_MOVED`. */
+  readonly expectedRevision: DocumentRevision;
+  /** Always `artifact` on this route; the shell's trusted Submit is the `shell` channel (D40). */
+  readonly channel: "artifact";
+}
+
+/** The Zod schema of the `SubmitRequest` type. */
+export const SubmitRequest: z.ZodType<SubmitRequest> = z
+  .object({
+    viewId: ViewId.schema,
+    expectedRevision: DocumentRevision,
+    channel: z.literal("artifact"),
+  })
+  .register(wireRegistry, {
+    id: "SubmitRequest",
+    description: "A browser submit: the view and the draft revision the viewer saw.",
+  });
+
+/** `POST …/signal`: raise a named signal for the host's attention (IN-09). */
+export interface SignalRequest {
+  /** The view the page was opened as (D104). */
+  readonly viewId: string;
+  /** Letters, digits, `.`, `_` and `-`; `submit` is reserved. */
+  readonly name: string;
+  /** Any JSON, at most 64 KiB. */
+  readonly payload?: unknown;
+}
+
+/** The Zod schema of the `SignalRequest` type. */
+export const SignalRequest: z.ZodType<SignalRequest> = z
+  .object({
+    viewId: ViewId.schema,
+    name: z.string().min(1).max(64),
+    payload: z.unknown().exactOptional(),
+  })
+  .register(wireRegistry, {
+    id: "SignalRequest",
+    description: "A browser signal: the view, the signal's name and an optional JSON payload.",
+  }) as z.ZodType<SignalRequest>;
+
+/** A document as the page loads it: its revision and fields. */
+export interface DocumentSnapshot {
+  /** The document's revision. */
+  readonly revision: DocumentRevision;
+  /** The draft's epoch (D103); 1 for artifact state. */
+  readonly epoch: number;
+  /** Every field by ID. */
+  readonly fields: Readonly<Record<string, FieldState>>;
+}
+
+/** The Zod schema of the `DocumentSnapshot` type. */
+export const DocumentSnapshot: z.ZodType<DocumentSnapshot> = z
+  .object({
+    revision: DocumentRevision,
+    epoch: z.int().min(1),
+    fields: z.record(z.string(), FieldState),
+  })
+  .register(wireRegistry, {
+    id: "DocumentSnapshot",
+    description: "A document's revision, epoch and fields, as a page loads it.",
+  });
+
+/**
+ * The first message of a browser event stream, and a poll's `snapshot`: where the page stands,
+ * so it renders the canonical draft and state before applying events after `cursor`.
+ */
+export interface StreamSnapshot {
+  /** Events after this cursor follow. */
+  readonly cursor: string;
+  /** Who the page acts as. */
+  readonly viewer: Viewer;
+  /** The viewer's draft. */
+  readonly draft: DocumentSnapshot;
+  /** The artifact's shared state. */
+  readonly state: DocumentSnapshot;
+  /** The submission that closed this draft, or this viewer's latest under `epochs`. */
+  readonly submission?: SubmissionSummary;
+  /**
+   * The artifact's latest version when the snapshot was read (WP-07): a reader that missed its
+   * `version.published` event (published between a frame ticket and the stream, or compacted)
+   * still learns of it.
+   */
+  readonly latest?: VersionRef;
+}
+
+/** The Zod schema of the `StreamSnapshot` type. */
+export const StreamSnapshot: z.ZodType<StreamSnapshot> = z
+  .object({
+    cursor: Cursor.schema,
+    viewer: Viewer,
+    draft: DocumentSnapshot,
+    state: DocumentSnapshot,
+    submission: SubmissionSummary.exactOptional(),
+    latest: VersionRef.exactOptional(),
+  })
+  .register(wireRegistry, {
+    id: "StreamSnapshot",
+    description: "Where a page stands: cursor, viewer, draft, artifact state and its submission.",
+  });
+
+/** `GET …/events/poll`: the long-poll answer on the same cursor as the stream (D47). */
+export interface PollResult {
+  /** Where the next poll continues. */
+  readonly cursor: string;
+  /** The events for this page after the cursor asked for, in order. */
+  readonly events: readonly EventRecord[];
+  /** Present when the poll asked for none or its cursor was compacted away. */
+  readonly snapshot?: StreamSnapshot;
+  /**
+   * Run and live updates for this view since its last poll (WP-08): lossy and never stored as
+   * events, the long-poll's counterpart of the stream's `run` and `live` messages.
+   */
+  readonly ephemeral?: readonly EphemeralMessage[];
+}
+
+/** The Zod schema of the `PollResult` type. */
+export const PollResult: z.ZodType<PollResult> = z
+  .object({
+    cursor: Cursor.schema,
+    events: z.array(EventRecord).readonly(),
+    snapshot: StreamSnapshot.exactOptional(),
+    ephemeral: z.array(z.record(z.string(), z.unknown())).readonly().exactOptional(),
+  })
+  .register(wireRegistry, {
+    id: "PollResult",
+    description: "A long-poll answer: the cursor, the events after the asked one, and a snapshot.",
+  }) as unknown as z.ZodType<PollResult>;
+
+/**
+ * `POST /a/{artifactId}/_mostra/ticket`'s answer on the shell origin: a single-use frame ticket,
+ * the view it opens and what the shell needs to render the view's trusted controls (D104, D108).
+ */
+export interface FrameTicket extends ViewContext {
+  /** The frame's entry URL, carrying the single-use ticket. */
+  readonly src: string;
+  /** The artifact's origin: the only origin the bridge accepts messages from. */
+  readonly artifactOrigin: string;
+  /** Whether this viewer follows the artifact's new versions (D63). */
+  readonly follow: boolean;
+  /** Whether the link opens this version only (D97 item 9): then the shell offers no newer one. */
+  readonly pinned: boolean;
+  /**
+   * The version's server code keeps crashing and is parked (WP-08, FAILURE_MODEL §2): the shell
+   * says so, since the page's actions and live data won't work until a new publish.
+   */
+  readonly serverParked?: true;
+  /**
+   * The frame shows `mostra dev`'s development preview of unpublished source (D140 item 12): the
+   * shell says so, and it is never a published version.
+   */
+  readonly devPreview?: true;
+}
+
+/** The Zod schema of the `FrameTicket` type. */
+export const FrameTicket: z.ZodType<FrameTicket> = z
+  .object({
+    artifactId: ArtifactId.schema,
+    viewId: ViewId.schema,
+    version: VersionRef,
+    latest: VersionRef,
+    policy: SubmissionPolicy,
+    submitChannels: z.array(SubmitChannel).min(1).max(2).readonly(),
+    controls: z.array(TrustedControl).max(32).readonly(),
+    target: z.enum(["live", "static", "mcp-app", "verify"]),
+    src: z.string().min(1),
+    artifactOrigin: z.string().min(1),
+    follow: z.boolean(),
+    pinned: z.boolean(),
+    serverParked: z.literal(true).exactOptional(),
+    devPreview: z.literal(true).exactOptional(),
+  })
+  .register(wireRegistry, {
+    id: "FrameTicket",
+    description: "A frame ticket: the view it opens, where to load it, and the view's controls.",
+  });
+
+// ── The shell's own routes (WP-07, on the shell origin) ──────────────────────────────────
+
+/**
+ * `POST /a/{artifactId}/_mostra/v/{rev}/submit`: the shell's trusted Submit (the `shell` channel,
+ * D40). Only the shell's page can send it: the route takes the shell's session, its exact origin
+ * and its CSRF token, none of which an artifact's page has.
+ */
+export interface ShellSubmitRequest {
+  /** The view the shell's frame shows (D104); its version is what the submission names. */
+  readonly viewId: string;
+  /** The draft revision the viewer saw, after the frame flushed its saves. */
+  readonly expectedRevision: DocumentRevision;
+}
+
+/** The Zod schema of the `ShellSubmitRequest` type. */
+export const ShellSubmitRequest: z.ZodType<ShellSubmitRequest> = z
+  .object({ viewId: ViewId.schema, expectedRevision: DocumentRevision })
+  .register(wireRegistry, {
+    id: "ShellSubmitRequest",
+    description: "The shell's trusted Submit: the view and the draft revision the viewer saw.",
+  });
+
+/**
+ * `POST /a/{artifactId}/_mostra/v/{rev}/review/choose`: the shell's trusted Choose (D65, D113).
+ * It writes the viewer's draft field `review.<reviewSetId>.choice` like any mutation, so a stale
+ * base revision comes back as a conflict.
+ */
+export interface ChooseRequest {
+  /** The view the shell's frame shows. */
+  readonly viewId: string;
+  /** A fresh `mut_` ID; a retry repeats it. */
+  readonly mutationId: string;
+  /** The draft revision the shell last saw. */
+  readonly baseRevision: DocumentRevision;
+  /** The review set. */
+  readonly reviewSetId: string;
+  /** The chosen candidate's ID. */
+  readonly candidateId: string;
+  /** The candidate's label, kept with the choice for results. */
+  readonly label?: string;
+}
+
+/** The Zod schema of the `ChooseRequest` type. */
+export const ChooseRequest: z.ZodType<ChooseRequest> = z
+  .object({
+    viewId: ViewId.schema,
+    mutationId: MutationId.schema,
+    baseRevision: DocumentRevision,
+    reviewSetId: z.string().regex(REVIEW_SET_ID_PATTERN),
+    candidateId: z.string().min(1).max(256),
+    label: z.string().max(256).exactOptional(),
+  })
+  .register(wireRegistry, {
+    id: "ChooseRequest",
+    description:
+      "The shell's trusted Choose: the view, mutation, base revision, set and candidate.",
+  });
+
+/** `POST /a/{artifactId}/_mostra/v/{rev}/follow`: the viewer's "Always follow this artifact" (D63). */
+export interface FollowRequest {
+  /** `true` to load new versions automatically, `false` to stop. */
+  readonly follow: boolean;
+}
+
+/** The Zod schema of the `FollowRequest` type. */
+export const FollowRequest: z.ZodType<FollowRequest> = z
+  .object({ follow: z.boolean() })
+  .register(wireRegistry, {
+    id: "FollowRequest",
+    description: "Whether the viewer follows the artifact's new versions.",
+  });
+
+/** A draft field a version doesn't cover (D42, D109): kept, shown read-only and delivered. */
+export interface OrphanedField {
+  /** The field's ID. */
+  readonly id: string;
+  /** Its label, when it has one. */
+  readonly label?: string;
+  /** Its value. */
+  readonly value: unknown;
+  /** The version whose view last wrote it. */
+  readonly fromVersion: number;
+}
+
+/** The Zod schema of the `OrphanedField` type. */
+export const OrphanedField: z.ZodType<OrphanedField> = z
+  .object({
+    id: z.string(),
+    label: z.string().exactOptional(),
+    value: z.unknown(),
+    fromVersion: z.int().min(1),
+  })
+  .register(wireRegistry, {
+    id: "OrphanedField",
+    description: "A draft field a version doesn't cover: its ID, label, value and source version.",
+  }) as z.ZodType<OrphanedField>;
+
+/**
+ * `GET /a/{artifactId}/_mostra/v/{rev}/carry?version=<number>`: which of the viewer's answers a
+ * version doesn't carry over (D42, D109). The banner counts them before a switch; the "Not
+ * carried over" panel lists them for the version shown.
+ */
+export interface CarryOver {
+  /** The version asked about. */
+  readonly version: VersionRef;
+  /** The viewer's draft fields the version doesn't cover. */
+  readonly orphans: readonly OrphanedField[];
+}
+
+/** The Zod schema of the `CarryOver` type. */
+export const CarryOver: z.ZodType<CarryOver> = z
+  .object({ version: VersionRef, orphans: z.array(OrphanedField).readonly() })
+  .register(wireRegistry, {
+    id: "CarryOver",
+    description: "The viewer's answers a version doesn't carry over.",
+  });

package/src/bundle.ts

@@ -0,0 +1,264 @@
+/**
+ * The runtime bundle's contract (RT-01, INTERFACES §16): what a host downloads, how it checks it
+ * and where its entry points are. The SDK, the CLI's bootstrap and the Rust crate (WP-12) all read
+ * these files, so they are wire schemas: published as JSON Schema and changed only additively.
+ *
+ * A release attaches one archive per platform, `mostra-<version>-<platform>.tar.gz`, whose single
+ * top directory holds:
+ *
+ * ```text
+ * bundle.json       BundleInfo: identity, entry points, the digest of files.json, the browser pin
+ * files.json        BundleFiles: every other file and link of the archive with its SHA-256
+ * node/             the official Node.js distribution for the platform
+ * lib/node_modules/ Mostra's packages (cli, runtime, worker, verify, shell, sdk, warm) and theirs
+ * bin/              the mostra, mostra-runtime and mostra-setup launchers
+ * ```
+ *
+ * The verify browser isn't in the archive: setup downloads the pinned revision through the
+ * bundle's own Playwright and checks every file against `BundleInfo.browser.files` (D142).
+ */
+import * as z from "zod";
+import { wireRegistry } from "./wire-registry.ts";
+
+/** The platforms v1 ships a bundle for (D35; Windows follows in v1.1, D120). */
+export const BUNDLE_PLATFORMS: readonly ["darwin-arm64", "darwin-x64", "linux-x64", "linux-arm64"] =
+  ["darwin-arm64", "darwin-x64", "linux-x64", "linux-arm64"];
+
+/** One platform a bundle is built for: `<os>-<arch>` as Node names them. */
+export type BundlePlatform = (typeof BUNDLE_PLATFORMS)[number];
+
+/** The `name` every `bundle.json` carries, so a stray JSON file is never taken for one. */
+export const BUNDLE_NAME = "mostra-runtime-bundle";
+
+/** The marker setup writes at a bundle's root once its files and its browser are verified. */
+export const BUNDLE_SETUP_MARKER = ".mostra-setup.json";
+
+/** The archive a release attaches for a version and platform. */
+export function bundleAssetName(version: string, platform: BundlePlatform): string {
+  return `mostra-${version}-${platform}.tar.gz`;
+}
+
+const sha256: z.ZodType<string> = z
+  .string()
+  .regex(/^[0-9a-f]{64}$/)
+  .register(wireRegistry, { id: "Sha256", description: "A SHA-256 digest in lowercase hex." });
+
+/**
+ * A path inside a bundle, `/`-separated and relative. Readers refuse absolute paths and `.` or
+ * `..` segments themselves; the pattern only keeps the obvious out.
+ */
+const bundlePath: z.ZodType<string> = z
+  .string()
+  .min(1)
+  .regex(/^[^/\0]/);
+
+/** The platform schema. */
+export const BundlePlatformSchema: z.ZodType<BundlePlatform> = z
+  .enum(BUNDLE_PLATFORMS)
+  .register(wireRegistry, { id: "BundlePlatform" });
+
+/** One regular file of a bundle or of its browser. */
+export interface BundleFileEntry {
+  /** Relative to the bundle's root (or to `browsers/` for the browser), `/`-separated. */
+  readonly path: string;
+  /** Its length in bytes. */
+  readonly size: number;
+  /** The SHA-256 of its bytes, lowercase hex. */
+  readonly sha256: string;
+  /** Whether its owner may execute it (mode 0755 rather than 0644 once extracted). */
+  readonly executable: boolean;
+}
+
+/** The file entry schema. */
+export const BundleFileEntry: z.ZodType<BundleFileEntry> = z
+  .object({
+    path: bundlePath,
+    size: z.int().min(0),
+    sha256,
+    executable: z.boolean(),
+  })
+  .register(wireRegistry, { id: "BundleFileEntry" });
+
+/** One symbolic link of a bundle. Its target is relative and resolves inside the bundle. */
+export interface BundleLinkEntry {
+  /** The link itself, relative to the bundle's root. */
+  readonly path: string;
+  /** What the link holds, exactly as written (relative). */
+  readonly target: string;
+}
+
+/** The link entry schema. */
+export const BundleLinkEntry: z.ZodType<BundleLinkEntry> = z
+  .object({ path: bundlePath, target: z.string().min(1) })
+  .register(wireRegistry, { id: "BundleLinkEntry" });
+
+/** `files.json`: everything in the archive besides `bundle.json`, each list sorted by path. */
+export interface BundleFiles {
+  /** The format's version; 1 today. */
+  readonly schemaVersion: 1;
+  /** Every regular file, sorted by path. */
+  readonly files: readonly BundleFileEntry[];
+  /** Every symbolic link, sorted by path. */
+  readonly links: readonly BundleLinkEntry[];
+}
+
+/** The `files.json` schema. */
+export const BundleFiles: z.ZodType<BundleFiles> = z
+  .object({
+    schemaVersion: z.literal(1),
+    files: z.array(BundleFileEntry),
+    links: z.array(BundleLinkEntry),
+  })
+  .register(wireRegistry, { id: "BundleFiles" });
+
+/** The verify browser a bundle pins: fetched at setup, checked file by file (D142). */
+export interface BundleBrowser {
+  /** Playwright's name for the browser. */
+  readonly name: "chromium-headless-shell";
+  /** Playwright's revision, the directory `browsers/chromium_headless_shell-<revision>`. */
+  readonly revision: string;
+  /** The browser's own version, for people and diagnostics. */
+  readonly browserVersion: string;
+  /** The bundle's Playwright CLI, run with the bundle's Node: `install chromium-headless-shell`. */
+  readonly installer: string;
+  /** Every file the install leaves under `browsers/`, besides Playwright's own markers. */
+  readonly files: readonly BundleFileEntry[];
+}
+
+/** The browser pin schema. */
+export const BundleBrowser: z.ZodType<BundleBrowser> = z
+  .object({
+    name: z.literal("chromium-headless-shell"),
+    revision: z.string().min(1),
+    browserVersion: z.string().min(1),
+    installer: bundlePath,
+    files: z.array(BundleFileEntry),
+  })
+  .register(wireRegistry, { id: "BundleBrowser" });
+
+/** `bundle.json`: a bundle's identity and entry points. */
+export interface BundleInfo {
+  /** The format's version; 1 today. */
+  readonly schemaVersion: 1;
+  /** Always {@link BUNDLE_NAME}, so a stray `bundle.json` isn't taken for one. */
+  readonly name: typeof BUNDLE_NAME;
+  /** The Mostra release: every Mostra package in the bundle has this version. */
+  readonly version: string;
+  /** The platform it was built on and for. */
+  readonly platform: BundlePlatform;
+  /** The private Node.js the bundle runs on (RT-01), and its executable. */
+  readonly node: { readonly version: string; readonly path: string };
+  /** Scripts each run as `<node.path> <entry> …`, paths relative to the bundle's root. */
+  readonly entries: {
+    /** `mostra-runtime host|daemon|service`: what a host spawns (D85). */
+    readonly runtime: string;
+    /** `mostra`, the CLI. */
+    readonly cli: string;
+    /** Verifies the bundle, fetches its browser and writes `.mostra-setup.json`. */
+    readonly setup: string;
+  };
+  /** `files.json` and its SHA-256, which ties every other file to this one. */
+  readonly files: { readonly path: string; readonly sha256: string };
+  /** The verify browser setup fetches and checks (D142 item 2). */
+  readonly browser: BundleBrowser;
+  /** Where it was built from. */
+  readonly source?: { readonly repository: string; readonly commit: string };
+}
+
+/** The `bundle.json` schema. */
+export const BundleInfo: z.ZodType<BundleInfo> = z
+  .object({
+    schemaVersion: z.literal(1),
+    name: z.literal(BUNDLE_NAME),
+    version: z.string().min(1),
+    platform: BundlePlatformSchema,
+    node: z.object({ version: z.string().min(1), path: bundlePath }),
+    entries: z.object({ runtime: bundlePath, cli: bundlePath, setup: bundlePath }),
+    files: z.object({ path: bundlePath, sha256 }),
+    browser: BundleBrowser,
+    source: z.object({ repository: z.string(), commit: z.string() }).exactOptional(),
+  })
+  .register(wireRegistry, { id: "BundleInfo" });
+
+/** One platform's archive in a release. */
+export interface BundleAsset {
+  /** The file name, {@link bundleAssetName}. */
+  readonly file: string;
+  /** The SHA-256 of the archive's bytes, lowercase hex. */
+  readonly sha256: string;
+  /** Bytes of the archive. */
+  readonly size: number;
+  /** Bytes once extracted, before the browser: what an installer checks free space against. */
+  readonly unpackedSize: number;
+}
+
+/** The asset schema. */
+export const BundleAsset: z.ZodType<BundleAsset> = z
+  .object({
+    // Exactly an archive's own name, no directory: an installer joins it to its scratch directory
+    // (Opus review finding 8), and `BundlePins` checks it names its release and platform.
+    file: z
+      .string()
+      .regex(/^mostra-[0-9A-Za-z][0-9A-Za-z.+-]*-(darwin|linux)-(arm64|x64)\.tar\.gz$/),
+    sha256,
+    size: z.int().positive(),
+    unpackedSize: z.int().positive(),
+  })
+  .register(wireRegistry, { id: "BundleAsset" });
+
+/**
+ * `bundles.json`: one release's archives, pinned by SHA-256. The release workflow writes it into
+ * `@mostra/sdk` before the package is published, so an npm install pins exactly what it fetches.
+ */
+export interface BundlePins {
+  /** The format's version; 1 today. */
+  readonly schemaVersion: 1;
+  /** The release these archives belong to: the SDK's own version. */
+  readonly version: string;
+  /** The base URL the archives are under: the GitHub release's download path. */
+  readonly release: string;
+  /** Each platform's archive. */
+  readonly assets: Partial<Record<BundlePlatform, BundleAsset>>;
+}
+
+/**
+ * The `bundles.json` schema. Each asset's `file` has an archive's shape (no directory); that it is
+ * exactly {@link bundleAssetName} of the pins' version and its platform is checked by the
+ * installer before any I/O, since JSON Schema can't express the comparison.
+ */
+export const BundlePins: z.ZodType<BundlePins> = z
+  .object({
+    schemaVersion: z.literal(1),
+    version: z.string().regex(/^[0-9A-Za-z][0-9A-Za-z.+-]*$/),
+    release: z.url({ protocol: /^https?$/ }),
+    assets: z.partialRecord(BundlePlatformSchema, BundleAsset),
+  })
+  .register(wireRegistry, { id: "BundlePins" });
+
+/** `.mostra-setup.json`: written by setup once the files and the browser are verified. */
+export interface BundleSetup {
+  /** The format's version; 1 today. */
+  readonly schemaVersion: 1;
+  /** The bundle's release. */
+  readonly version: string;
+  /** The bundle's platform. */
+  readonly platform: BundlePlatform;
+  /** `BundleInfo.files.sha256` of the bundle it describes. */
+  readonly files: string;
+  /** The browser revision setup fetched and checked. */
+  readonly browser: { readonly revision: string };
+  /** When setup finished (RFC 3339). */
+  readonly at: string;
+}
+
+/** The setup marker's schema. */
+export const BundleSetup: z.ZodType<BundleSetup> = z
+  .object({
+    schemaVersion: z.literal(1),
+    version: z.string().min(1),
+    platform: BundlePlatformSchema,
+    files: sha256,
+    browser: z.object({ revision: z.string().min(1) }),
+    at: z.string(),
+  })
+  .register(wireRegistry, { id: "BundleSetup" });

package/src/canonical.ts

@@ -0,0 +1,49 @@
+/**
+ * Canonical JSON (RFC 8785, the JSON Canonicalization Scheme): one exact text for a JSON value,
+ * so equal values hash equally wherever they are hashed. A submission's digest is the SHA-256 of
+ * its stored snapshot in this form (DATA_MODEL §3). The snapshot stays in the ledger; results carry
+ * the digest as the snapshot's identity, so two results with the same digest hold the same answers.
+ *
+ * ```ts
+ * canonicalJson({ b: [1, "x"], a: null }); // '{"a":null,"b":[1,"x"]}'
+ * ```
+ */
+
+/**
+ * The canonical JSON text of `value` (RFC 8785 §3.2): no whitespace; strings, numbers and
+ * literals as ECMAScript's `JSON.stringify` writes them; object properties sorted by their UTF-16
+ * code units at every depth; array order kept. Properties whose value is `undefined` are left out,
+ * as `JSON.stringify` does.
+ *
+ * @throws TypeError for anything I-JSON can't hold: a non-finite number, a lone surrogate, a
+ *   bigint, a function or symbol, or an `undefined` outside an object.
+ */
+export function canonicalJson(value: unknown): string {
+  switch (typeof value) {
+    case "string":
+      return canonicalString(value);
+    case "number":
+      if (!Number.isFinite(value)) throw new TypeError("JSON numbers must be finite.");
+      return JSON.stringify(value);
+    case "boolean":
+      return value ? "true" : "false";
+    case "object": {
+      if (value === null) return "null";
+      if (Array.isArray(value)) return `[${value.map((item) => canonicalJson(item)).join(",")}]`;
+      const entries = Object.entries(value as Record<string, unknown>).filter(
+        ([, item]) => item !== undefined,
+      );
+      // The default sort compares UTF-16 code units, which is RFC 8785's order.
+      entries.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+      return `{${entries.map(([key, item]) => `${canonicalString(key)}:${canonicalJson(item)}`).join(",")}}`;
+    }
+    default:
+      throw new TypeError(`A ${typeof value} has no JSON form.`);
+  }
+}
+
+function canonicalString(text: string): string {
+  // RFC 8785 §3.2.2.2: invalid Unicode (a lone surrogate) must fail rather than be escaped.
+  if (!text.isWellFormed()) throw new TypeError("JSON strings must be well-formed Unicode.");
+  return JSON.stringify(text);
+}