@mostra/protocol 0.0.0-placeholder → 0.1.0

package/dist/browser.js

@@ -0,0 +1,156 @@
+import { wireRegistry } from "./wire-registry.js";
+import { ArtifactId, Cursor, MutationId, ViewId } from "./ids.js";
+import { SubmissionPolicy } from "./manifest.js";
+import { REVIEW_SET_ID_PATTERN, SubmitChannel, TrustedControl, VersionRef, ViewContext, ViewContextWire, readViewContext } from "./view.js";
+import { DocumentRevision, EventRecord, FieldOp, FieldState, SubmissionSummary, Viewer } from "./interaction.js";
+import * as z from "zod";
+//#region src/browser.ts
+/**
+* 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: … });
+* ```
+*/
+/** Every browser-protocol revision this release serves, oldest first. */
+const BROWSER_PROTOCOL_REVISIONS = ["2026-10-15"];
+/** The newest browser-protocol revision: what a client runtime built now speaks. */
+const BROWSER_PROTOCOL_REVISION = "2026-10-15";
+/** The longest JSON a signal's payload may be, in UTF-8 bytes (D106). */
+const SIGNAL_PAYLOAD_MAX_BYTES = 65536;
+/** The Zod schema of the `FieldsRequest` type. */
+const FieldsRequest = z.object({
+	mutationId: MutationId.schema,
+	scope: z.enum(["viewer", "artifact"]),
+	baseRevision: DocumentRevision,
+	viewId: ViewId.schema,
+	ops: z.array(FieldOp).min(1).max(1e3).readonly()
+}).register(wireRegistry, {
+	id: "FieldsRequest",
+	description: "A browser mutation: its ID, scope, base revision, view and field ops."
+});
+/** The Zod schema of the `SubmitRequest` type. */
+const 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."
+});
+/** The Zod schema of the `SignalRequest` type. */
+const 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."
+});
+/** The Zod schema of the `DocumentSnapshot` type. */
+const 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 Zod schema of the `StreamSnapshot` type. */
+const 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."
+});
+/** The Zod schema of the `PollResult` type. */
+const 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."
+});
+/** The Zod schema of the `FrameTicket` type. */
+const 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 Zod schema of the `ShellSubmitRequest` type. */
+const 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."
+});
+/** The Zod schema of the `ChooseRequest` type. */
+const 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."
+});
+/** The Zod schema of the `FollowRequest` type. */
+const FollowRequest = z.object({ follow: z.boolean() }).register(wireRegistry, {
+	id: "FollowRequest",
+	description: "Whether the viewer follows the artifact's new versions."
+});
+/** The Zod schema of the `OrphanedField` type. */
+const 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."
+});
+/** The Zod schema of the `CarryOver` type. */
+const 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."
+});
+//#endregion
+export { BROWSER_PROTOCOL_REVISION, BROWSER_PROTOCOL_REVISIONS, CarryOver, ChooseRequest, DocumentSnapshot, FieldsRequest, FollowRequest, FrameTicket, OrphanedField, PollResult, REVIEW_SET_ID_PATTERN, SIGNAL_PAYLOAD_MAX_BYTES, ShellSubmitRequest, SignalRequest, StreamSnapshot, SubmitRequest, VersionRef, ViewContext, ViewContextWire, readViewContext };
+
+//# sourceMappingURL=browser.js.map

package/dist/browser.js.map

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

package/dist/bundle.d.ts

@@ -0,0 +1,155 @@
+import * as z from "zod";
+//#region src/bundle.d.ts
+/** The platforms v1 ships a bundle for (D35; Windows follows in v1.1, D120). */
+export declare const BUNDLE_PLATFORMS: readonly ["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 declare const BUNDLE_NAME = "mostra-runtime-bundle";
+/** The marker setup writes at a bundle's root once its files and its browser are verified. */
+export declare const BUNDLE_SETUP_MARKER = ".mostra-setup.json";
+/** The archive a release attaches for a version and platform. */
+export declare function bundleAssetName(version: string, platform: BundlePlatform): string;
+/** The platform schema. */
+export declare const BundlePlatformSchema: z.ZodType<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 declare const BundleFileEntry: z.ZodType<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 declare const BundleLinkEntry: z.ZodType<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 declare const BundleFiles: z.ZodType<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 declare const BundleBrowser: z.ZodType<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 declare const BundleInfo: z.ZodType<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 declare const BundleAsset: z.ZodType<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 declare const BundlePins: z.ZodType<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 declare const BundleSetup: z.ZodType<BundleSetup>;
+//#endregion
+//# sourceMappingURL=bundle.d.ts.map

package/dist/bundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle.d.ts","names":[],"sources":["../src/bundle.ts"],"mappings":";;;qBAuBa;;YAID,yBAAyB;;qBAGxB;;qBAGA;;wBAGG,gBAAgB,iBAAiB,UAAU;;qBAmB9C,sBAAsB,EAAE,QAAQ;;iBAK5B;;WAEN;;WAEA;;WAEA;;WAEA;;;qBAIE,iBAAiB,EAAE,QAAQ;;iBAUvB;;WAEN;;WAEA;;;qBAIE,iBAAiB,EAAE,QAAQ;;iBAKvB;;WAEN;;WAEA,gBAAgB;;WAEhB,gBAAgB;;;qBAId,aAAa,EAAE,QAAQ;;iBASnB;;WAEN;;WAEA;;WAEA;;WAEA;;WAEA,gBAAgB;;;qBAId,eAAe,EAAE,QAAQ;;iBAWrB;;WAEN;;WAEA,aAAa;;WAEb;;WAEA,UAAU;;WAEV;aAAiB;aAA0B;;;WAE3C;;aAEE;;aAEA;;aAEA;;;WAGF;aAAkB;aAAuB;;;WAEzC,SAAS;;WAET;aAAoB;aAA6B;;;;qBAI/C,YAAY,EAAE,QAAQ;;iBAelB;;WAEN;;WAEA;;WAEA;;WAEA;;;qBAIE,aAAa,EAAE,QAAQ;;;;;iBAiBnB;;WAEN;;WAEA;;WAEA;;WAEA,QAAQ,QAAQ,OAAO,gBAAgB;;;;;;;qBAQrC,YAAY,EAAE,QAAQ;;iBAUlB;;WAEN;;WAEA;;WAEA,UAAU;;WAEV;;WAEA;aAAoB;;;WAEpB;;;qBAIE,aAAa,EAAE,QAAQ"}

package/dist/bundle.js

@@ -0,0 +1,130 @@
+import { wireRegistry } from "./wire-registry.js";
+import * as z from "zod";
+//#region src/bundle.ts
+/**
+* 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).
+*/
+/** The platforms v1 ships a bundle for (D35; Windows follows in v1.1, D120). */
+const BUNDLE_PLATFORMS = [
+	"darwin-arm64",
+	"darwin-x64",
+	"linux-x64",
+	"linux-arm64"
+];
+/** The `name` every `bundle.json` carries, so a stray JSON file is never taken for one. */
+const BUNDLE_NAME = "mostra-runtime-bundle";
+/** The marker setup writes at a bundle's root once its files and its browser are verified. */
+const BUNDLE_SETUP_MARKER = ".mostra-setup.json";
+/** The archive a release attaches for a version and platform. */
+function bundleAssetName(version, platform) {
+	return `mostra-${version}-${platform}.tar.gz`;
+}
+const sha256 = 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.string().min(1).regex(/^[^/\0]/);
+/** The platform schema. */
+const BundlePlatformSchema = z.enum(BUNDLE_PLATFORMS).register(wireRegistry, { id: "BundlePlatform" });
+/** The file entry schema. */
+const BundleFileEntry = z.object({
+	path: bundlePath,
+	size: z.int().min(0),
+	sha256,
+	executable: z.boolean()
+}).register(wireRegistry, { id: "BundleFileEntry" });
+/** The link entry schema. */
+const BundleLinkEntry = z.object({
+	path: bundlePath,
+	target: z.string().min(1)
+}).register(wireRegistry, { id: "BundleLinkEntry" });
+/** The `files.json` schema. */
+const BundleFiles = z.object({
+	schemaVersion: z.literal(1),
+	files: z.array(BundleFileEntry),
+	links: z.array(BundleLinkEntry)
+}).register(wireRegistry, { id: "BundleFiles" });
+/** The browser pin schema. */
+const 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" });
+/** The `bundle.json` schema. */
+const 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" });
+/** The asset schema. */
+const BundleAsset = z.object({
+	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" });
+/**
+* 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.
+*/
+const 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" });
+/** The setup marker's schema. */
+const 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" });
+//#endregion
+export { BUNDLE_NAME, BUNDLE_PLATFORMS, BUNDLE_SETUP_MARKER, BundleAsset, BundleBrowser, BundleFileEntry, BundleFiles, BundleInfo, BundleLinkEntry, BundlePins, BundlePlatformSchema, BundleSetup, bundleAssetName };
+
+//# sourceMappingURL=bundle.js.map

package/dist/bundle.js.map

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

package/dist/canonical.d.ts

@@ -0,0 +1,23 @@
+//#region src/canonical.d.ts
+/**
+ * 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 declare function canonicalJson(value: unknown): string;
+//#endregion
+//# sourceMappingURL=canonical.d.ts.map

package/dist/canonical.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.d.ts","names":[],"sources":["../src/canonical.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;wBAoBgB,cAAc"}

package/dist/canonical.js

@@ -0,0 +1,45 @@
+//#region src/canonical.ts
+/**
+* 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.
+*/
+function canonicalJson(value) {
+	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).filter(([, item]) => item !== void 0);
+			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) {
+	if (!text.isWellFormed()) throw new TypeError("JSON strings must be well-formed Unicode.");
+	return JSON.stringify(text);
+}
+//#endregion
+export { canonicalJson };
+
+//# sourceMappingURL=canonical.js.map

package/dist/canonical.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.js","names":[],"sources":["../src/canonical.ts"],"sourcesContent":["/**\n * Canonical JSON (RFC 8785, the JSON Canonicalization Scheme): one exact text for a JSON value,\n * so equal values hash equally wherever they are hashed. A submission's digest is the SHA-256 of\n * its stored snapshot in this form (DATA_MODEL §3). The snapshot stays in the ledger; results carry\n * the digest as the snapshot's identity, so two results with the same digest hold the same answers.\n *\n * ```ts\n * canonicalJson({ b: [1, \"x\"], a: null }); // '{\"a\":null,\"b\":[1,\"x\"]}'\n * ```\n */\n\n/**\n * The canonical JSON text of `value` (RFC 8785 §3.2): no whitespace; strings, numbers and\n * literals as ECMAScript's `JSON.stringify` writes them; object properties sorted by their UTF-16\n * code units at every depth; array order kept. Properties whose value is `undefined` are left out,\n * as `JSON.stringify` does.\n *\n * @throws TypeError for anything I-JSON can't hold: a non-finite number, a lone surrogate, a\n *   bigint, a function or symbol, or an `undefined` outside an object.\n */\nexport function canonicalJson(value: unknown): string {\n  switch (typeof value) {\n    case \"string\":\n      return canonicalString(value);\n    case \"number\":\n      if (!Number.isFinite(value)) throw new TypeError(\"JSON numbers must be finite.\");\n      return JSON.stringify(value);\n    case \"boolean\":\n      return value ? \"true\" : \"false\";\n    case \"object\": {\n      if (value === null) return \"null\";\n      if (Array.isArray(value)) return `[${value.map((item) => canonicalJson(item)).join(\",\")}]`;\n      const entries = Object.entries(value as Record<string, unknown>).filter(\n        ([, item]) => item !== undefined,\n      );\n      // The default sort compares UTF-16 code units, which is RFC 8785's order.\n      entries.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));\n      return `{${entries.map(([key, item]) => `${canonicalString(key)}:${canonicalJson(item)}`).join(\",\")}}`;\n    }\n    default:\n      throw new TypeError(`A ${typeof value} has no JSON form.`);\n  }\n}\n\nfunction canonicalString(text: string): string {\n  // RFC 8785 §3.2.2.2: invalid Unicode (a lone surrogate) must fail rather than be escaped.\n  if (!text.isWellFormed()) throw new TypeError(\"JSON strings must be well-formed Unicode.\");\n  return JSON.stringify(text);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAoBA,SAAgB,cAAc,OAAwB;CACpD,QAAQ,OAAO,OAAf;EACE,KAAK,UACH,OAAO,gBAAgB,KAAK;EAC9B,KAAK;GACH,IAAI,CAAC,OAAO,SAAS,KAAK,GAAG,MAAM,IAAI,UAAU,8BAA8B;GAC/E,OAAO,KAAK,UAAU,KAAK;EAC7B,KAAK,WACH,OAAO,QAAQ,SAAS;EAC1B,KAAK,UAAU;GACb,IAAI,UAAU,MAAM,OAAO;GAC3B,IAAI,MAAM,QAAQ,KAAK,GAAG,OAAO,IAAI,MAAM,KAAK,SAAS,cAAc,IAAI,CAAC,CAAC,CAAC,KAAK,GAAG,EAAE;GACxF,MAAM,UAAU,OAAO,QAAQ,KAAgC,CAAC,CAAC,QAC9D,GAAG,UAAU,SAAS,KAAA,CACzB;GAEA,QAAQ,MAAM,CAAC,IAAI,CAAC,OAAQ,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,CAAE;GACvD,OAAO,IAAI,QAAQ,KAAK,CAAC,KAAK,UAAU,GAAG,gBAAgB,GAAG,EAAE,GAAG,cAAc,IAAI,GAAG,CAAC,CAAC,KAAK,GAAG,EAAE;EACtG;EACA,SACE,MAAM,IAAI,UAAU,KAAK,OAAO,MAAM,mBAAmB;CAC7D;AACF;AAEA,SAAS,gBAAgB,MAAsB;CAE7C,IAAI,CAAC,KAAK,aAAa,GAAG,MAAM,IAAI,UAAU,2CAA2C;CACzF,OAAO,KAAK,UAAU,IAAI;AAC5B"}

package/dist/capability.d.ts

@@ -0,0 +1,38 @@
+import * as z from "zod";
+//#region src/capability.d.ts
+/**
+ * What a capability token allows (HY-03, D97):
+ * - `view`: open the artifact; every token has it.
+ * - `draft`: save answers and other field values.
+ * - `submit`: submit.
+ * - `review`: comment and choose.
+ * - `signal`: raise a signal for the host's attention (D10), which a waiting agent may act on.
+ * - `action:*`: run every server function; `action:<export>` runs that export of any
+ *   `"use server"` module; `action:<module path>#<export>` runs one function ID.
+ */
+export type CapabilityScope = "view" | "draft" | "submit" | "review" | "signal" | `action:${string}`;
+/** The Zod schema of the `CapabilityScope` type. */
+export declare const CapabilityScope: z.ZodType<CapabilityScope>;
+/** Every scope at once: what a link minted without `scopes`, and every default link, carries. */
+export declare const ALL_SCOPES: readonly CapabilityScope[];
+/**
+ * A duration: a positive whole number and a unit, `s`, `m`, `h` or `d` (`30m`, `24h`, `7d`), as
+ * INTERFACES §1 writes durations in flags and manifests.
+ */
+export type Duration = `${number}${"s" | "m" | "h" | "d"}`;
+/** The Zod schema of the `Duration` type. */
+export declare const Duration: z.ZodType<Duration>;
+/** The length of a `Duration` in milliseconds. */
+export declare function durationMs(duration: Duration): number;
+/**
+ * The scopes a token holds after normalization: `view` added, duplicates removed, sorted, so equal
+ * grants compare equal.
+ */
+export declare function normalizeScopes(scopes: readonly CapabilityScope[]): CapabilityScope[];
+/**
+ * Whether `scopes` grant `required`. A plain scope must be held as written. An action scope
+ * `action:<module path>#<export>` is granted by `action:*`, by `action:<export>` and by itself.
+ */
+export declare function scopeAllows(scopes: readonly CapabilityScope[], required: CapabilityScope): boolean;
+//#endregion
+//# sourceMappingURL=capability.d.ts.map

package/dist/capability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.d.ts","names":[],"sources":["../src/capability.ts"],"mappings":";;;;;;;;;;;;YAkBY;;qBASC,iBAAiB,EAAE,QAAQ;;qBAU3B,qBAAqB;;;;;YAatB;;qBAGC,UAAU,EAAE,QAAQ;;wBAWjB,WAAW,UAAU;;;;;wBASrB,gBAAgB,iBAAiB,oBAAoB;;;;;wBAQrD,YACd,iBAAiB,mBACjB,UAAU"}