@mostra/protocol 0.0.0-stage → 0.1.0

package/dist/diagnostics/spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.d.ts","names":[],"sources":["../../src/diagnostics/spec.ts"],"mappings":";;;iBAeiB;;WAEN,UAAU;;WAEV,OAAO;;WAEP;;WAEA;;WAEA;;aAEE;;aAEA;;;;;;WAMF;;;YAIC,YAAY,oBAAoB,0CAChC,KAAK,IAAI;;;;;qBAOR;;wBAGG,QAAQ,cAAc;;iBAOrB;;WAEN;;WAEA;;WAEA,MAAM;;WAEN,WAAW;;WAEX"}

package/dist/diagnostics/spec.js

@@ -0,0 +1,31 @@
+//#region src/diagnostics/spec.ts
+/**
+* Where diagnostics link by default: the GitHub Pages docs site (D37). Hosts and the runtime pass
+* their own base when the docs move.
+*/
+const DEFAULT_DOCS_BASE = "https://mostra-dev.github.io/mostra";
+/** The docs page for `code` under `docsBase`: `${docsBase}/errors/${code}`. */
+function docsUrl(code, docsBase = DEFAULT_DOCS_BASE) {
+	let end = docsBase.length;
+	while (end > 0 && docsBase.charCodeAt(end - 1) === 47) end--;
+	return `${docsBase.slice(0, end)}/errors/${code}`;
+}
+/**
+* Builds a diagnostic for a cataloged code: severity, phase, hint and docs link come from `spec`,
+* the rest from `details`.
+*/
+function buildDiagnostic(code, spec, details, docsBase = DEFAULT_DOCS_BASE) {
+	const { hint = spec.hint, ...rest } = details;
+	return {
+		code,
+		severity: spec.severity,
+		phase: spec.phase,
+		docs: docsUrl(code, docsBase),
+		hint,
+		...rest
+	};
+}
+//#endregion
+export { DEFAULT_DOCS_BASE, buildDiagnostic, docsUrl };
+
+//# sourceMappingURL=spec.js.map

package/dist/diagnostics/spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.js","names":[],"sources":["../../src/diagnostics/spec.ts"],"sourcesContent":["/**\n * The diagnostic catalog: one entry per code, declared in one source file per area under\n * `codes/`. The catalog feeds `createDiagnostic`, the generated catalog JSON and one docs\n * page per code (AX-03).\n */\nimport type {\n  Diagnostic,\n  DiagnosticArea,\n  DiagnosticFix,\n  DiagnosticLocation,\n  DiagnosticPhase,\n  DiagnosticSeverity,\n} from \"./diagnostic.ts\";\n\n/** Everything Mostra knows about one code, besides the code itself. */\nexport interface DiagnosticSpec {\n  /** The severity of every occurrence. */\n  readonly severity: DiagnosticSeverity;\n  /** The stage of work that reports it. */\n  readonly phase: DiagnosticPhase;\n  /** One line naming the condition. It is the docs page's title. */\n  readonly title: string;\n  /** The default hint: one imperative sentence. An occurrence may give a more specific one. */\n  readonly hint: string;\n  /** The docs page body. */\n  readonly docs: {\n    /** What the code means and when Mostra reports it. */\n    readonly explanation: string;\n    /** The minimal fix. */\n    readonly fix: string;\n  };\n  /**\n   * Set when Mostra no longer reports the code, saying what replaced it. Codes are never\n   * removed (AX-03).\n   */\n  readonly deprecated?: string;\n}\n\n/** The catalog of one area: exactly the codes `C`, each with its spec. */\nexport type AreaCatalog<C extends `MOSTRA_${DiagnosticArea}_${string}`> = {\n  readonly [K in C]: DiagnosticSpec;\n};\n\n/**\n * Where diagnostics link by default: the GitHub Pages docs site (D37). Hosts and the runtime pass\n * their own base when the docs move.\n */\nexport const DEFAULT_DOCS_BASE: string = \"https://mostra-dev.github.io/mostra\";\n\n/** The docs page for `code` under `docsBase`: `${docsBase}/errors/${code}`. */\nexport function docsUrl(code: string, docsBase: string = DEFAULT_DOCS_BASE): string {\n  let end = docsBase.length;\n  while (end > 0 && docsBase.charCodeAt(end - 1) === 47 /* \"/\" */) end--;\n  return `${docsBase.slice(0, end)}/errors/${code}`;\n}\n\n/** The parts of a diagnostic that belong to one occurrence rather than to its code. */\nexport interface DiagnosticDetails {\n  /** What is wrong, for this occurrence. Never include secrets or capability tokens. */\n  readonly message: string;\n  /** Replaces the catalog's default hint when the occurrence allows a more specific one. */\n  readonly hint?: string;\n  /** A machine-applicable fix. */\n  readonly fix?: DiagnosticFix;\n  /** Where the problem is. */\n  readonly location?: DiagnosticLocation;\n  /** How many identical occurrences this one stands for. */\n  readonly count?: number;\n}\n\n/**\n * Builds a diagnostic for a cataloged code: severity, phase, hint and docs link come from `spec`,\n * the rest from `details`.\n */\nexport function buildDiagnostic(\n  code: Diagnostic[\"code\"],\n  spec: DiagnosticSpec,\n  details: DiagnosticDetails,\n  docsBase: string = DEFAULT_DOCS_BASE,\n): Diagnostic {\n  const { hint = spec.hint, ...rest } = details;\n  return {\n    code,\n    severity: spec.severity,\n    phase: spec.phase,\n    docs: docsUrl(code, docsBase),\n    hint,\n    ...rest,\n  };\n}\n"],"mappings":";;;;;AA+CA,MAAa,oBAA4B;;AAGzC,SAAgB,QAAQ,MAAc,WAAmB,mBAA2B;CAClF,IAAI,MAAM,SAAS;CACnB,OAAO,MAAM,KAAK,SAAS,WAAW,MAAM,CAAC,MAAM,IAAc;CACjE,OAAO,GAAG,SAAS,MAAM,GAAG,GAAG,EAAE,UAAU;AAC7C;;;;;AAoBA,SAAgB,gBACd,MACA,MACA,SACA,WAAmB,mBACP;CACZ,MAAM,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS;CACtC,OAAO;EACL;EACA,UAAU,KAAK;EACf,OAAO,KAAK;EACZ,MAAM,QAAQ,MAAM,QAAQ;EAC5B;EACA,GAAG;CACL;AACF"}

package/dist/hygiene.d.ts

@@ -0,0 +1,66 @@
+import { Diagnostic } from "./diagnostics/diagnostic.js";
+import { HygieneDiagnosticCode } from "./diagnostics/codes/hygiene.js";
+//#region src/hygiene.d.ts
+/** What one listener serves: its own origin and the exact `Host` values it accepts. */
+export interface RequestPolicy {
+  /** The listener's origin, such as `http://127.0.0.1:23456`; `Origin` headers must equal it. */
+  readonly origin: string;
+  /** Every `host:port` this listener answers to (lowercase): its URL host, plus registered tunnels. */
+  readonly hosts: readonly string[];
+}
+/**
+ * What a request is for, which decides the checks beyond the envelope:
+ * - `read`: a GET or HEAD of a page or file; a foreign `Origin` is refused, none is fine.
+ * - `stream`: an event stream (GET); same-origin only, by `Origin` or `Sec-Fetch-Site`.
+ * - `upgrade`: a WebSocket upgrade; `Origin` must be present and equal.
+ * - `exchange`: a mutation that starts a session (a capability token or ticket in the body):
+ *   `Origin` and a JSON content type, but no CSRF token yet.
+ * - `mutation`: any other state change: `Origin`, a JSON content type and the session's CSRF
+ *   token in `X-Mostra-CSRF`.
+ */
+export type RequestIntent = "read" | "stream" | "upgrade" | "exchange" | "mutation";
+/** One request as the transport received it. */
+export interface RequestFacts {
+  /** The method, as sent. */
+  readonly method: string;
+  /** The request target exactly as sent: an origin-form path with its query. */
+  readonly target: string;
+  /** Every header as `[name, value]` in arrival order, so repeated headers are visible. */
+  readonly headers: readonly (readonly [string, string])[];
+  /** The intent the matched route declared; omit to check only the envelope. */
+  readonly intent?: RequestIntent;
+  /** The session's CSRF token, for `mutation` requests. */
+  readonly csrf?: string;
+}
+/** A refused request: the HTTP status to answer with and the diagnostic for its body. */
+export interface Refusal {
+  /** The HTTP status: 400, 401, 403, 404, 410, 415, 421 or 429. */
+  readonly status: number;
+  /** What was refused and why, for the response body and the log. */
+  readonly diagnostic: Diagnostic;
+}
+/** The header that carries a session's CSRF token on every mutation (D98). */
+export declare const CSRF_HEADER = "x-mostra-csrf";
+/** Builds a refusal with the status the code's HTTP mapping gives (FAILURE_MODEL §8). */
+export declare function refusal(code: HygieneDiagnosticCode, message: string, status?: number): Refusal;
+/** Constant-time comparison of two strings, so timing reveals nothing about a secret. */
+export declare function safeEqual(a: string, b: string): boolean;
+/**
+ * The path a request target names, decoded, or `undefined` when it isn't a safe origin-form path:
+ * absolute and authority forms, `*`, encoded `/` or `\`, `.` or `..` segments (encoded or not),
+ * NUL and other controls, and invalid percent-encoding are all refused.
+ */
+export declare function safePath(target: string): string | undefined;
+/** The value of a header (case-insensitive name), or `undefined`. */
+export declare function headerValue(headers: readonly (readonly [string, string])[], name: string): string | undefined;
+/** Whether a `Content-Type` value is JSON (`application/json`, any parameters). */
+export declare function isJsonContentType(value: string | undefined): boolean;
+/**
+ * Checks a request's envelope (the `Host` allowlist, the request target, repeated and malformed
+ * headers) and, when `intent` is given, what that intent needs: `Origin`, the JSON content type
+ * and the CSRF token. Returns the first refusal, or `undefined` when the request may proceed.
+ * Session, token and scope checks follow in the endpoint, which knows its session.
+ */
+export declare function checkRequest(policy: RequestPolicy, request: RequestFacts): Refusal | undefined;
+//#endregion
+//# sourceMappingURL=hygiene.d.ts.map

package/dist/hygiene.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hygiene.d.ts","names":[],"sources":["../src/hygiene.ts"],"mappings":";;;;iBAoBiB;;WAEN;;WAEA;;;;;;;;;;;;YAaC;;iBAGK;;WAEN;;WAEA;;WAEA;;WAEA,SAAS;;WAET;;;iBAIM;;WAEN;;WAEA,YAAY;;;qBAIV;;wBAmBG,QAAQ,MAAM,uBAAuB,iBAAiB,kBAAkB;;wBAexE,UAAU,WAAW;;;;;;wBAcrB,SAAS;;wBAiBT,YACd,iDACA;;wBAOc,kBAAkB;;;;;;;wBAWlB,aAAa,QAAQ,eAAe,SAAS,eAAe"}

package/dist/hygiene.js

@@ -0,0 +1,134 @@
+import { buildDiagnostic } from "./diagnostics/spec.js";
+import { hygieneDiagnostics } from "./diagnostics/codes/hygiene.js";
+//#region src/hygiene.ts
+/**
+* Request hygiene (D06, ARCHITECTURE §10, HY-01): the checks every Mostra HTTP endpoint applies
+* before it acts on a request, as pure functions with no I/O. The gateway runs them on every
+* request, and `mostra mcp --http` (WP-15) runs the same code (D96), so a request a stranger's
+* page could send is refused the same way everywhere. None of them limits what an artifact, an
+* agent or a viewer may do; they only make sure a request comes from the page it claims to.
+*
+* ```ts
+* const refusal = checkRequest(
+*   { origin: "http://127.0.0.1:23456", hosts: ["127.0.0.1:23456"] },
+*   { method: "POST", target: "/a/art_…/_mostra/ticket", headers, intent: "mutation", csrf },
+* );
+* if (refusal) return respond(refusal.status, refusal.diagnostic);
+* ```
+*/
+/** The header that carries a session's CSRF token on every mutation (D98). */
+const CSRF_HEADER = "x-mostra-csrf";
+const STATUS = {
+	MOSTRA_HYGIENE_HOST_REFUSED: 421,
+	MOSTRA_HYGIENE_ORIGIN_REFUSED: 403,
+	MOSTRA_HYGIENE_CSRF_MISSING: 403,
+	MOSTRA_HYGIENE_CONTENT_TYPE: 415,
+	MOSTRA_HYGIENE_REQUEST_MALFORMED: 400,
+	MOSTRA_HYGIENE_SESSION_MISSING: 401,
+	MOSTRA_HYGIENE_TOKEN_INVALID: 401,
+	MOSTRA_HYGIENE_TOKEN_REVOKED: 410,
+	MOSTRA_HYGIENE_SCOPE_DENIED: 403,
+	MOSTRA_HYGIENE_RATE_LIMITED: 429,
+	MOSTRA_HYGIENE_NOT_SERVED: 404,
+	MOSTRA_HYGIENE_SESSION_CONFLICT: 409,
+	MOSTRA_HYGIENE_HEADERS_TOO_LARGE: 431
+};
+/** Builds a refusal with the status the code's HTTP mapping gives (FAILURE_MODEL §8). */
+function refusal(code, message, status) {
+	return {
+		status: status ?? STATUS[code],
+		diagnostic: buildDiagnostic(code, hygieneDiagnostics[code], { message })
+	};
+}
+/** Headers that must appear at most once: a second copy could mean two different things. */
+const SINGLE = /* @__PURE__ */ new Set([
+	"host",
+	"origin",
+	"content-type",
+	"content-length",
+	CSRF_HEADER,
+	"cookie"
+]);
+/** Characters no header value or path may carry: controls other than tab, and DEL. */
+const CONTROL = /[\u0000-\u0008\u000a-\u001f\u007f]/;
+/** Constant-time comparison of two strings, so timing reveals nothing about a secret. */
+function safeEqual(a, b) {
+	let difference = a.length ^ b.length;
+	const length = Math.max(a.length, b.length);
+	for (let index = 0; index < length; index++) difference |= (a.charCodeAt(index) | 0) ^ (b.charCodeAt(index) | 0);
+	return difference === 0;
+}
+/**
+* The path a request target names, decoded, or `undefined` when it isn't a safe origin-form path:
+* absolute and authority forms, `*`, encoded `/` or `\`, `.` or `..` segments (encoded or not),
+* NUL and other controls, and invalid percent-encoding are all refused.
+*/
+function safePath(target) {
+	if (!target.startsWith("/") || target.startsWith("//")) return void 0;
+	const end = target.search(/[?#]/);
+	const raw = end < 0 ? target : target.slice(0, end);
+	if (/%(2f|5c)/i.test(raw) || raw.includes("\\")) return void 0;
+	let path;
+	try {
+		path = decodeURIComponent(raw);
+	} catch {
+		return;
+	}
+	if (CONTROL.test(path) || path.includes("\0")) return void 0;
+	if (path.split("/").some((segment) => segment === "." || segment === "..")) return void 0;
+	return path;
+}
+/** The value of a header (case-insensitive name), or `undefined`. */
+function headerValue(headers, name) {
+	const lower = name.toLowerCase();
+	return headers.find(([key]) => key.toLowerCase() === lower)?.[1];
+}
+/** Whether a `Content-Type` value is JSON (`application/json`, any parameters). */
+function isJsonContentType(value) {
+	if (value === void 0) return false;
+	return value.split(";")[0]?.trim().toLowerCase() === "application/json";
+}
+/**
+* Checks a request's envelope (the `Host` allowlist, the request target, repeated and malformed
+* headers) and, when `intent` is given, what that intent needs: `Origin`, the JSON content type
+* and the CSRF token. Returns the first refusal, or `undefined` when the request may proceed.
+* Session, token and scope checks follow in the endpoint, which knows its session.
+*/
+function checkRequest(policy, request) {
+	const counts = /* @__PURE__ */ new Map();
+	for (const [name, value] of request.headers) {
+		const lower = name.toLowerCase();
+		counts.set(lower, (counts.get(lower) ?? 0) + 1);
+		if (CONTROL.test(value)) return refusal("MOSTRA_HYGIENE_REQUEST_MALFORMED", `The ${lower} header has control characters.`);
+	}
+	for (const name of SINGLE) if ((counts.get(name) ?? 0) > 1) return refusal("MOSTRA_HYGIENE_REQUEST_MALFORMED", `The request repeats the ${name} header.`);
+	const host = headerValue(request.headers, "host")?.toLowerCase();
+	if (host === void 0 || !policy.hosts.includes(host)) return refusal("MOSTRA_HYGIENE_HOST_REFUSED", host === void 0 ? "The request has no Host header." : "The request's Host isn't one this listener serves.");
+	if (safePath(request.target) === void 0) return refusal("MOSTRA_HYGIENE_REQUEST_MALFORMED", "The request target isn't a plain path inside the served tree.");
+	if (request.intent === void 0) return void 0;
+	const origin = headerValue(request.headers, "origin");
+	switch (request.intent) {
+		case "read":
+			if (origin !== void 0 && origin !== policy.origin) return refusal("MOSTRA_HYGIENE_ORIGIN_REFUSED", "The request came from another origin.");
+			return;
+		case "stream": {
+			const site = headerValue(request.headers, "sec-fetch-site");
+			return (origin === void 0 ? site === "same-origin" : origin === policy.origin) ? void 0 : refusal("MOSTRA_HYGIENE_ORIGIN_REFUSED", "A stream must be opened by its own origin.");
+		}
+		case "upgrade":
+		case "exchange":
+		case "mutation": {
+			if (origin !== policy.origin) return refusal("MOSTRA_HYGIENE_ORIGIN_REFUSED", origin === void 0 ? "The request has no Origin header." : "The request came from another origin.");
+			if (request.intent === "upgrade") return void 0;
+			if (!isJsonContentType(headerValue(request.headers, "content-type"))) return refusal("MOSTRA_HYGIENE_CONTENT_TYPE", "The request's body isn't declared as JSON.");
+			if (request.intent === "exchange") return void 0;
+			const sent = headerValue(request.headers, CSRF_HEADER);
+			if (request.csrf === void 0 || sent === void 0 || !safeEqual(sent, request.csrf)) return refusal("MOSTRA_HYGIENE_CSRF_MISSING", sent === void 0 ? `The request has no ${CSRF_HEADER} header.` : `The request's ${CSRF_HEADER} header doesn't match its session.`);
+			return;
+		}
+	}
+}
+//#endregion
+export { CSRF_HEADER, checkRequest, headerValue, isJsonContentType, refusal, safeEqual, safePath };
+
+//# sourceMappingURL=hygiene.js.map

package/dist/hygiene.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hygiene.js","names":[],"sources":["../src/hygiene.ts"],"sourcesContent":["/**\n * Request hygiene (D06, ARCHITECTURE §10, HY-01): the checks every Mostra HTTP endpoint applies\n * before it acts on a request, as pure functions with no I/O. The gateway runs them on every\n * request, and `mostra mcp --http` (WP-15) runs the same code (D96), so a request a stranger's\n * page could send is refused the same way everywhere. None of them limits what an artifact, an\n * agent or a viewer may do; they only make sure a request comes from the page it claims to.\n *\n * ```ts\n * const refusal = checkRequest(\n *   { origin: \"http://127.0.0.1:23456\", hosts: [\"127.0.0.1:23456\"] },\n *   { method: \"POST\", target: \"/a/art_…/_mostra/ticket\", headers, intent: \"mutation\", csrf },\n * );\n * if (refusal) return respond(refusal.status, refusal.diagnostic);\n * ```\n */\nimport { type HygieneDiagnosticCode, hygieneDiagnostics } from \"./diagnostics/codes/hygiene.ts\";\nimport type { Diagnostic } from \"./diagnostics/diagnostic.ts\";\nimport { buildDiagnostic } from \"./diagnostics/spec.ts\";\n\n/** What one listener serves: its own origin and the exact `Host` values it accepts. */\nexport interface RequestPolicy {\n  /** The listener's origin, such as `http://127.0.0.1:23456`; `Origin` headers must equal it. */\n  readonly origin: string;\n  /** Every `host:port` this listener answers to (lowercase): its URL host, plus registered tunnels. */\n  readonly hosts: readonly string[];\n}\n\n/**\n * What a request is for, which decides the checks beyond the envelope:\n * - `read`: a GET or HEAD of a page or file; a foreign `Origin` is refused, none is fine.\n * - `stream`: an event stream (GET); same-origin only, by `Origin` or `Sec-Fetch-Site`.\n * - `upgrade`: a WebSocket upgrade; `Origin` must be present and equal.\n * - `exchange`: a mutation that starts a session (a capability token or ticket in the body):\n *   `Origin` and a JSON content type, but no CSRF token yet.\n * - `mutation`: any other state change: `Origin`, a JSON content type and the session's CSRF\n *   token in `X-Mostra-CSRF`.\n */\nexport type RequestIntent = \"read\" | \"stream\" | \"upgrade\" | \"exchange\" | \"mutation\";\n\n/** One request as the transport received it. */\nexport interface RequestFacts {\n  /** The method, as sent. */\n  readonly method: string;\n  /** The request target exactly as sent: an origin-form path with its query. */\n  readonly target: string;\n  /** Every header as `[name, value]` in arrival order, so repeated headers are visible. */\n  readonly headers: readonly (readonly [string, string])[];\n  /** The intent the matched route declared; omit to check only the envelope. */\n  readonly intent?: RequestIntent;\n  /** The session's CSRF token, for `mutation` requests. */\n  readonly csrf?: string;\n}\n\n/** A refused request: the HTTP status to answer with and the diagnostic for its body. */\nexport interface Refusal {\n  /** The HTTP status: 400, 401, 403, 404, 410, 415, 421 or 429. */\n  readonly status: number;\n  /** What was refused and why, for the response body and the log. */\n  readonly diagnostic: Diagnostic;\n}\n\n/** The header that carries a session's CSRF token on every mutation (D98). */\nexport const CSRF_HEADER = \"x-mostra-csrf\";\n\nconst STATUS: Readonly<Record<HygieneDiagnosticCode, number>> = {\n  MOSTRA_HYGIENE_HOST_REFUSED: 421,\n  MOSTRA_HYGIENE_ORIGIN_REFUSED: 403,\n  MOSTRA_HYGIENE_CSRF_MISSING: 403,\n  MOSTRA_HYGIENE_CONTENT_TYPE: 415,\n  MOSTRA_HYGIENE_REQUEST_MALFORMED: 400,\n  MOSTRA_HYGIENE_SESSION_MISSING: 401,\n  MOSTRA_HYGIENE_TOKEN_INVALID: 401,\n  MOSTRA_HYGIENE_TOKEN_REVOKED: 410,\n  MOSTRA_HYGIENE_SCOPE_DENIED: 403,\n  MOSTRA_HYGIENE_RATE_LIMITED: 429,\n  MOSTRA_HYGIENE_NOT_SERVED: 404,\n  MOSTRA_HYGIENE_SESSION_CONFLICT: 409,\n  MOSTRA_HYGIENE_HEADERS_TOO_LARGE: 431,\n};\n\n/** Builds a refusal with the status the code's HTTP mapping gives (FAILURE_MODEL §8). */\nexport function refusal(code: HygieneDiagnosticCode, message: string, status?: number): Refusal {\n  return {\n    status: status ?? STATUS[code],\n    diagnostic: buildDiagnostic(code, hygieneDiagnostics[code], { message }),\n  };\n}\n\n/** Headers that must appear at most once: a second copy could mean two different things. */\nconst SINGLE = new Set([\"host\", \"origin\", \"content-type\", \"content-length\", CSRF_HEADER, \"cookie\"]);\n\n/** Characters no header value or path may carry: controls other than tab, and DEL. */\n// biome-ignore lint/suspicious/noControlCharactersInRegex: matching control characters is the point.\nconst CONTROL = /[\\u0000-\\u0008\\u000a-\\u001f\\u007f]/;\n\n/** Constant-time comparison of two strings, so timing reveals nothing about a secret. */\nexport function safeEqual(a: string, b: string): boolean {\n  let difference = a.length ^ b.length;\n  const length = Math.max(a.length, b.length);\n  for (let index = 0; index < length; index++) {\n    difference |= (a.charCodeAt(index) | 0) ^ (b.charCodeAt(index) | 0);\n  }\n  return difference === 0;\n}\n\n/**\n * The path a request target names, decoded, or `undefined` when it isn't a safe origin-form path:\n * absolute and authority forms, `*`, encoded `/` or `\\`, `.` or `..` segments (encoded or not),\n * NUL and other controls, and invalid percent-encoding are all refused.\n */\nexport function safePath(target: string): string | undefined {\n  if (!target.startsWith(\"/\") || target.startsWith(\"//\")) return undefined;\n  const end = target.search(/[?#]/);\n  const raw = end < 0 ? target : target.slice(0, end);\n  if (/%(2f|5c)/i.test(raw) || raw.includes(\"\\\\\")) return undefined;\n  let path: string;\n  try {\n    path = decodeURIComponent(raw);\n  } catch {\n    return undefined;\n  }\n  if (CONTROL.test(path) || path.includes(\"\\u0000\")) return undefined;\n  if (path.split(\"/\").some((segment) => segment === \".\" || segment === \"..\")) return undefined;\n  return path;\n}\n\n/** The value of a header (case-insensitive name), or `undefined`. */\nexport function headerValue(\n  headers: readonly (readonly [string, string])[],\n  name: string,\n): string | undefined {\n  const lower = name.toLowerCase();\n  return headers.find(([key]) => key.toLowerCase() === lower)?.[1];\n}\n\n/** Whether a `Content-Type` value is JSON (`application/json`, any parameters). */\nexport function isJsonContentType(value: string | undefined): boolean {\n  if (value === undefined) return false;\n  return value.split(\";\")[0]?.trim().toLowerCase() === \"application/json\";\n}\n\n/**\n * Checks a request's envelope (the `Host` allowlist, the request target, repeated and malformed\n * headers) and, when `intent` is given, what that intent needs: `Origin`, the JSON content type\n * and the CSRF token. Returns the first refusal, or `undefined` when the request may proceed.\n * Session, token and scope checks follow in the endpoint, which knows its session.\n */\nexport function checkRequest(policy: RequestPolicy, request: RequestFacts): Refusal | undefined {\n  const counts = new Map<string, number>();\n  for (const [name, value] of request.headers) {\n    const lower = name.toLowerCase();\n    counts.set(lower, (counts.get(lower) ?? 0) + 1);\n    if (CONTROL.test(value)) {\n      return refusal(\n        \"MOSTRA_HYGIENE_REQUEST_MALFORMED\",\n        `The ${lower} header has control characters.`,\n      );\n    }\n  }\n  for (const name of SINGLE) {\n    if ((counts.get(name) ?? 0) > 1) {\n      return refusal(\"MOSTRA_HYGIENE_REQUEST_MALFORMED\", `The request repeats the ${name} header.`);\n    }\n  }\n  const host = headerValue(request.headers, \"host\")?.toLowerCase();\n  if (host === undefined || !policy.hosts.includes(host)) {\n    return refusal(\n      \"MOSTRA_HYGIENE_HOST_REFUSED\",\n      host === undefined\n        ? \"The request has no Host header.\"\n        : \"The request's Host isn't one this listener serves.\",\n    );\n  }\n  if (safePath(request.target) === undefined) {\n    return refusal(\n      \"MOSTRA_HYGIENE_REQUEST_MALFORMED\",\n      \"The request target isn't a plain path inside the served tree.\",\n    );\n  }\n  if (request.intent === undefined) return undefined;\n\n  const origin = headerValue(request.headers, \"origin\");\n  switch (request.intent) {\n    case \"read\":\n      if (origin !== undefined && origin !== policy.origin) {\n        return refusal(\"MOSTRA_HYGIENE_ORIGIN_REFUSED\", \"The request came from another origin.\");\n      }\n      return undefined;\n    case \"stream\": {\n      const site = headerValue(request.headers, \"sec-fetch-site\");\n      const sameOrigin = origin === undefined ? site === \"same-origin\" : origin === policy.origin;\n      return sameOrigin\n        ? undefined\n        : refusal(\"MOSTRA_HYGIENE_ORIGIN_REFUSED\", \"A stream must be opened by its own origin.\");\n    }\n    case \"upgrade\":\n    case \"exchange\":\n    case \"mutation\": {\n      if (origin !== policy.origin) {\n        return refusal(\n          \"MOSTRA_HYGIENE_ORIGIN_REFUSED\",\n          origin === undefined\n            ? \"The request has no Origin header.\"\n            : \"The request came from another origin.\",\n        );\n      }\n      if (request.intent === \"upgrade\") return undefined;\n      if (!isJsonContentType(headerValue(request.headers, \"content-type\"))) {\n        return refusal(\"MOSTRA_HYGIENE_CONTENT_TYPE\", \"The request's body isn't declared as JSON.\");\n      }\n      if (request.intent === \"exchange\") return undefined;\n      const sent = headerValue(request.headers, CSRF_HEADER);\n      if (request.csrf === undefined || sent === undefined || !safeEqual(sent, request.csrf)) {\n        return refusal(\n          \"MOSTRA_HYGIENE_CSRF_MISSING\",\n          sent === undefined\n            ? `The request has no ${CSRF_HEADER} header.`\n            : `The request's ${CSRF_HEADER} header doesn't match its session.`,\n        );\n      }\n      return undefined;\n    }\n  }\n}\n"],"mappings":"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"}

package/dist/ids.d.ts

@@ -0,0 +1,119 @@
+import * as z from "zod";
+//#region src/ids.d.ts
+/** The prefixes INTERFACES §1 assigns, one per entity. */
+export type IdPrefix = "art" | "ver" | "vw" | "vwr" | "sub" | "dlv" | "run" | "thr" | "cmt" | "tok" | "mut";
+/**
+ * A branded ID string. The brand exists only at the type level, so an `Id<"art">` is a plain
+ * string at run time and on the wire.
+ */
+export type Id<P extends IdPrefix> = `${P}_${string}` & {
+  readonly __mostraIdPrefix: P;
+};
+/** How an ID kind's body is formed. */
+export type IdBody = "ulid" | "sha256-base32";
+/** One ID kind: its prefix, validation and schema. */
+export interface IdKind<P extends IdPrefix> {
+  /** The prefix, without the underscore. */
+  readonly prefix: P;
+  /** The entity the ID names, in the PRODUCT vocabulary. */
+  readonly entity: string;
+  /** How the body is formed. */
+  readonly body: IdBody;
+  /** The exact form, anchored at both ends. */
+  readonly pattern: RegExp;
+  /** The Zod schema for this ID, registered for JSON Schema output under the kind's type name. */
+  readonly schema: z.ZodType<Id<P>, string>;
+  /** Whether `value` is an ID of this kind. */
+  is(value: unknown): value is Id<P>;
+  /**
+   * Returns `value` as an ID of this kind.
+   *
+   * @throws TypeError when `value` is not of this kind's form. The message names the expected
+   *   form and never echoes the input.
+   */
+  parse(value: string): Id<P>;
+}
+/** An ID kind whose body is a ULID that the creator generates. */
+export interface GeneratedIdKind<P extends IdPrefix> extends IdKind<P> {
+  /** Generates a new ID from the current time and 80 bits of Web Crypto randomness. */
+  create(): Id<P>;
+}
+/** An artifact ID (`art_` + ULID). */
+export type ArtifactId = Id<"art">;
+/** Artifact IDs. */
+export declare const ArtifactId: GeneratedIdKind<"art">;
+/** A version ID (`ver_` + 26 characters of base32 SHA-256): content-addressed, never generated. */
+export type VersionId = Id<"ver">;
+/** The version ID kind, with the content-addressed constructor DATA_MODEL §2 defines. */
+export interface VersionIdKind extends IdKind<"ver"> {
+  /**
+   * Returns the version ID for a SHA-256 digest: `ver_` plus the first 26 characters of the
+   * digest in Crockford base32 (130 bits). The caller computes the digest of the artifact ID's
+   * UTF-8 bytes, a `0x00` byte, and the 32-byte `sourceDigest` and `envDigest` (DATA_MODEL §2,
+   * D89).
+   *
+   * @throws RangeError when `digest` is not 32 bytes long.
+   */
+  fromSha256(digest: Uint8Array): VersionId;
+}
+/** Version IDs. */
+export declare const VersionId: VersionIdKind;
+/** A view ID (`vw_` + ULID). */
+export type ViewId = Id<"vw">;
+/** View IDs. */
+export declare const ViewId: GeneratedIdKind<"vw">;
+/** A viewer ID (`vwr_` + ULID). */
+export type ViewerId = Id<"vwr">;
+/** Viewer IDs. */
+export declare const ViewerId: GeneratedIdKind<"vwr">;
+/** A submission ID (`sub_` + ULID). */
+export type SubmissionId = Id<"sub">;
+/** Submission IDs. */
+export declare const SubmissionId: GeneratedIdKind<"sub">;
+/**
+ * A delivery ID (`dlv_` + ULID): one submission's delivery to one host (D105). A redelivery after a
+ * crash repeats it, so a host can treat deliveries idempotently.
+ */
+export type DeliveryId = Id<"dlv">;
+/** Delivery IDs. */
+export declare const DeliveryId: GeneratedIdKind<"dlv">;
+/** An action run ID (`run_` + ULID). */
+export type RunId = Id<"run">;
+/** Action run IDs. */
+export declare const RunId: GeneratedIdKind<"run">;
+/** A review thread ID (`thr_` + ULID). */
+export type ThreadId = Id<"thr">;
+/** Review thread IDs. */
+export declare const ThreadId: GeneratedIdKind<"thr">;
+/** A comment ID (`cmt_` + ULID). */
+export type CommentId = Id<"cmt">;
+/** Comment IDs. */
+export declare const CommentId: GeneratedIdKind<"cmt">;
+/** A capability token ID (`tok_` + ULID). The token's secret is separate and never an ID. */
+export type TokenId = Id<"tok">;
+/** Capability token IDs. */
+export declare const TokenId: GeneratedIdKind<"tok">;
+/** A mutation ID (`mut_` + ULID), generated by the client that sends the mutation. */
+export type MutationId = Id<"mut">;
+/** Mutation IDs. */
+export declare const MutationId: GeneratedIdKind<"mut">;
+/**
+ * An event cursor: the decimal string of a home-wide event position (INTERFACES §1). Decimal
+ * strings keep 64-bit positions exact in JavaScript.
+ */
+export type Cursor = string & {
+  readonly __mostraCursor: true;
+};
+/** Event cursors. */
+export declare const Cursor: {
+  /** The exact form: a non-negative decimal integer without leading zeros, at most 19 digits. */
+  readonly pattern: RegExp;
+  readonly schema: z.ZodType<Cursor, string>;
+  is(value: unknown): value is Cursor;
+  /** @throws TypeError when `value` is not a cursor. */
+  parse(value: string): Cursor;
+  /** Orders two cursors: negative when `a` comes first, zero when equal, positive otherwise. */
+  compare(a: Cursor, b: Cursor): number;
+};
+//#endregion
+//# sourceMappingURL=ids.d.ts.map

package/dist/ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.d.ts","names":[],"sources":["../src/ids.ts"],"mappings":";;;YAmBY;;;;;YAiBA,GAAG,UAAU,eAAe;WAA2B,kBAAkB;;;YAGzE;;iBAGK,OAAO,UAAU;;WAEvB,QAAQ;;WAER;;WAEA,MAAM;;WAEN,SAAS;;WAET,QAAQ,EAAE,QAAQ,GAAG;;EAE9B,GAAG,iBAAiB,SAAS,GAAG;;;;;;;EAOhC,MAAM,gBAAgB,GAAG;;;iBAIV,gBAAgB,UAAU,kBAAkB,OAAO;;EAElE,UAAU,GAAG;;;YAkFH,aAAa;;qBAEZ,YAAY;;YAKb,YAAY;;iBAEP,sBAAsB;;;;;;;;;EASrC,WAAW,QAAQ,aAAa;;;qBAGrB,WAAW;;YAWZ,SAAS;;qBAER,QAAQ;;YAGT,WAAW;;qBAEV,UAAU;;YAKX,eAAe;;qBAEd,cAAc;;;;;YAQf,aAAa;;qBAEZ,YAAY;;YAKb,QAAQ;;qBAEP,OAAO;;YAKR,WAAW;;qBAEV,UAAU;;YAKX,YAAY;;qBAEX,WAAW;;YAKZ,UAAU;;qBAET,SAAS;;YAKV,aAAa;;qBAEZ,YAAY;;;;;YAQb;WAA6B;;;qBAG5B;;WAEF,SAAS;WACT,QAAQ,EAAE,QAAQ;EAC3B,GAAG,iBAAiB,SAAS;;EAE7B,MAAM,gBAAgB;;EAEtB,QAAQ,GAAG,QAAQ,GAAG"}

package/dist/ids.js

@@ -0,0 +1,135 @@
+import { wireRegistry } from "./wire-registry.js";
+import * as z from "zod";
+//#region src/ids.ts
+/**
+* Prefixed, opaque identifiers (INTERFACES §1, DATA_MODEL §2).
+*
+* Every Mostra entity is named by a string of the form `<prefix>_<body>`. Callers treat IDs as
+* opaque: they validate the form at a boundary and never read meaning out of the body. Each ID
+* kind below is both a type and a value with the same name:
+*
+* ```ts
+* const artifact: ArtifactId = ArtifactId.parse(input);
+* const mutation: MutationId = MutationId.create();
+* const Params = z.object({ artifactId: ArtifactId.schema });
+* ```
+*
+* @packageDocumentation
+*/
+/** Crockford's base32 alphabet, used by ULIDs and by content-addressed version IDs. */
+const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+const BODY_LENGTH = 26;
+/** A ULID's first character encodes at most 3 bits (48-bit time in 26 × 5 = 130 bits). */
+const ULID_BODY = "[0-7][0-9A-HJKMNP-TV-Z]{25}";
+const BASE32_BODY = "[0-9A-HJKMNP-TV-Z]{26}";
+function defineKind(prefix, entity, body, typeName) {
+	const pattern = new RegExp(`^${prefix}_${body === "ulid" ? ULID_BODY : BASE32_BODY}$`);
+	const form = body === "ulid" ? "a 26-character ULID" : "26 characters of Crockford base32";
+	const is = (value) => typeof value === "string" && pattern.test(value);
+	return {
+		prefix,
+		entity,
+		body,
+		pattern,
+		schema: z.string().regex(pattern).register(wireRegistry, {
+			id: typeName,
+			description: `${entity[0]?.toUpperCase()}${entity.slice(1)} ID: "${prefix}_" followed by ${form}.`
+		}),
+		is,
+		parse(value) {
+			if (is(value)) return value;
+			throw new TypeError(`Expected ${entity} ID "${prefix}_" followed by ${form}.`);
+		}
+	};
+}
+function generated(kind) {
+	return {
+		...kind,
+		create: () => kind.parse(`${kind.prefix}_${ulidBody(Date.now())}`)
+	};
+}
+/**
+* Encodes a ULID body: 48 bits of milliseconds since the Unix epoch, then 80 random bits, as 26
+* Crockford base32 characters.
+*/
+function ulidBody(now) {
+	if (!Number.isSafeInteger(now) || now < 0 || now > 0xffffffffffff) throw new RangeError("ULID time must be a millisecond timestamp between 0 and 2^48 - 1.");
+	let time = "";
+	let rest = now;
+	for (let i = 0; i < 10; i++) {
+		time = CROCKFORD.charAt(rest % 32) + time;
+		rest = Math.floor(rest / 32);
+	}
+	const random = /* @__PURE__ */ new Uint8Array(10);
+	globalThis.crypto.getRandomValues(random);
+	return time + base32(random).slice(0, 16);
+}
+/** Encodes bytes as Crockford base32, most significant bit first, padding the last group with 0. */
+function base32(bytes) {
+	let out = "";
+	let buffer = 0;
+	let bits = 0;
+	for (const byte of bytes) {
+		buffer = buffer << 8 | byte;
+		bits += 8;
+		while (bits >= 5) {
+			out += CROCKFORD.charAt(buffer >>> bits - 5 & 31);
+			bits -= 5;
+		}
+		buffer &= (1 << bits) - 1;
+	}
+	if (bits > 0) out += CROCKFORD.charAt(buffer << 5 - bits & 31);
+	return out;
+}
+/** Artifact IDs. */
+const ArtifactId = generated(defineKind("art", "artifact", "ulid", "ArtifactId"));
+/** Version IDs. */
+const VersionId = {
+	...defineKind("ver", "version", "sha256-base32", "VersionId"),
+	fromSha256(digest) {
+		if (digest.length !== 32) throw new RangeError(`A SHA-256 digest is 32 bytes, got ${digest.length}.`);
+		return VersionId.parse(`ver_${base32(digest).slice(0, BODY_LENGTH)}`);
+	}
+};
+/** View IDs. */
+const ViewId = generated(defineKind("vw", "view", "ulid", "ViewId"));
+/** Viewer IDs. */
+const ViewerId = generated(defineKind("vwr", "viewer", "ulid", "ViewerId"));
+/** Submission IDs. */
+const SubmissionId = generated(defineKind("sub", "submission", "ulid", "SubmissionId"));
+/** Delivery IDs. */
+const DeliveryId = generated(defineKind("dlv", "delivery", "ulid", "DeliveryId"));
+/** Action run IDs. */
+const RunId = generated(defineKind("run", "action run", "ulid", "RunId"));
+/** Review thread IDs. */
+const ThreadId = generated(defineKind("thr", "thread", "ulid", "ThreadId"));
+/** Comment IDs. */
+const CommentId = generated(defineKind("cmt", "comment", "ulid", "CommentId"));
+/** Capability token IDs. */
+const TokenId = generated(defineKind("tok", "capability token", "ulid", "TokenId"));
+/** Mutation IDs. */
+const MutationId = generated(defineKind("mut", "mutation", "ulid", "MutationId"));
+/** Event cursors. */
+const Cursor = (() => {
+	const pattern = /^(0|[1-9][0-9]{0,18})$/;
+	const is = (value) => typeof value === "string" && pattern.test(value);
+	return {
+		pattern,
+		schema: z.string().regex(pattern).register(wireRegistry, {
+			id: "Cursor",
+			description: "Event cursor: the decimal string of a home-wide event position."
+		}),
+		is,
+		parse(value) {
+			if (is(value)) return value;
+			throw new TypeError("Expected an event cursor: a non-negative decimal integer string.");
+		},
+		compare(a, b) {
+			return a.length === b.length ? a < b ? -1 : a > b ? 1 : 0 : a.length - b.length;
+		}
+	};
+})();
+//#endregion
+export { ArtifactId, CommentId, Cursor, DeliveryId, MutationId, RunId, SubmissionId, ThreadId, TokenId, VersionId, ViewId, ViewerId };
+
+//# sourceMappingURL=ids.js.map

package/dist/ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.js","names":[],"sources":["../src/ids.ts"],"sourcesContent":["/**\n * Prefixed, opaque identifiers (INTERFACES §1, DATA_MODEL §2).\n *\n * Every Mostra entity is named by a string of the form `<prefix>_<body>`. Callers treat IDs as\n * opaque: they validate the form at a boundary and never read meaning out of the body. Each ID\n * kind below is both a type and a value with the same name:\n *\n * ```ts\n * const artifact: ArtifactId = ArtifactId.parse(input);\n * const mutation: MutationId = MutationId.create();\n * const Params = z.object({ artifactId: ArtifactId.schema });\n * ```\n *\n * @packageDocumentation\n */\nimport * as z from \"zod\";\nimport { wireRegistry } from \"./wire-registry.ts\";\n\n/** The prefixes INTERFACES §1 assigns, one per entity. */\nexport type IdPrefix =\n  | \"art\"\n  | \"ver\"\n  | \"vw\"\n  | \"vwr\"\n  | \"sub\"\n  | \"dlv\"\n  | \"run\"\n  | \"thr\"\n  | \"cmt\"\n  | \"tok\"\n  | \"mut\";\n\n/**\n * A branded ID string. The brand exists only at the type level, so an `Id<\"art\">` is a plain\n * string at run time and on the wire.\n */\nexport type Id<P extends IdPrefix> = `${P}_${string}` & { readonly __mostraIdPrefix: P };\n\n/** How an ID kind's body is formed. */\nexport type IdBody = \"ulid\" | \"sha256-base32\";\n\n/** One ID kind: its prefix, validation and schema. */\nexport interface IdKind<P extends IdPrefix> {\n  /** The prefix, without the underscore. */\n  readonly prefix: P;\n  /** The entity the ID names, in the PRODUCT vocabulary. */\n  readonly entity: string;\n  /** How the body is formed. */\n  readonly body: IdBody;\n  /** The exact form, anchored at both ends. */\n  readonly pattern: RegExp;\n  /** The Zod schema for this ID, registered for JSON Schema output under the kind's type name. */\n  readonly schema: z.ZodType<Id<P>, string>;\n  /** Whether `value` is an ID of this kind. */\n  is(value: unknown): value is Id<P>;\n  /**\n   * Returns `value` as an ID of this kind.\n   *\n   * @throws TypeError when `value` is not of this kind's form. The message names the expected\n   *   form and never echoes the input.\n   */\n  parse(value: string): Id<P>;\n}\n\n/** An ID kind whose body is a ULID that the creator generates. */\nexport interface GeneratedIdKind<P extends IdPrefix> extends IdKind<P> {\n  /** Generates a new ID from the current time and 80 bits of Web Crypto randomness. */\n  create(): Id<P>;\n}\n\n/** Crockford's base32 alphabet, used by ULIDs and by content-addressed version IDs. */\nconst CROCKFORD = \"0123456789ABCDEFGHJKMNPQRSTVWXYZ\";\nconst BODY_LENGTH = 26;\n/** A ULID's first character encodes at most 3 bits (48-bit time in 26 × 5 = 130 bits). */\nconst ULID_BODY = \"[0-7][0-9A-HJKMNP-TV-Z]{25}\";\nconst BASE32_BODY = \"[0-9A-HJKMNP-TV-Z]{26}\";\n\nfunction defineKind<P extends IdPrefix>(\n  prefix: P,\n  entity: string,\n  body: IdBody,\n  typeName: string,\n): IdKind<P> {\n  const pattern = new RegExp(`^${prefix}_${body === \"ulid\" ? ULID_BODY : BASE32_BODY}$`);\n  const form = body === \"ulid\" ? \"a 26-character ULID\" : \"26 characters of Crockford base32\";\n  const is = (value: unknown): value is Id<P> => typeof value === \"string\" && pattern.test(value);\n  const schema = z\n    .string()\n    .regex(pattern)\n    .register(wireRegistry, {\n      id: typeName,\n      description: `${entity[0]?.toUpperCase()}${entity.slice(1)} ID: \"${prefix}_\" followed by ${form}.`,\n    }) as unknown as z.ZodType<Id<P>, string>;\n  return {\n    prefix,\n    entity,\n    body,\n    pattern,\n    schema,\n    is,\n    parse(value: string): Id<P> {\n      if (is(value)) return value;\n      throw new TypeError(`Expected ${entity} ID \"${prefix}_\" followed by ${form}.`);\n    },\n  };\n}\n\nfunction generated<P extends IdPrefix>(kind: IdKind<P>): GeneratedIdKind<P> {\n  return { ...kind, create: () => kind.parse(`${kind.prefix}_${ulidBody(Date.now())}`) };\n}\n\n/**\n * Encodes a ULID body: 48 bits of milliseconds since the Unix epoch, then 80 random bits, as 26\n * Crockford base32 characters.\n */\nfunction ulidBody(now: number): string {\n  if (!Number.isSafeInteger(now) || now < 0 || now > 0xffff_ffff_ffff) {\n    throw new RangeError(\"ULID time must be a millisecond timestamp between 0 and 2^48 - 1.\");\n  }\n  let time = \"\";\n  let rest = now;\n  for (let i = 0; i < 10; i++) {\n    time = CROCKFORD.charAt(rest % 32) + time;\n    rest = Math.floor(rest / 32);\n  }\n  const random = new Uint8Array(10);\n  globalThis.crypto.getRandomValues(random);\n  return time + base32(random).slice(0, 16);\n}\n\n/** Encodes bytes as Crockford base32, most significant bit first, padding the last group with 0. */\nfunction base32(bytes: Uint8Array): string {\n  let out = \"\";\n  let buffer = 0;\n  let bits = 0;\n  for (const byte of bytes) {\n    buffer = (buffer << 8) | byte;\n    bits += 8;\n    while (bits >= 5) {\n      out += CROCKFORD.charAt((buffer >>> (bits - 5)) & 31);\n      bits -= 5;\n    }\n    buffer &= (1 << bits) - 1;\n  }\n  if (bits > 0) out += CROCKFORD.charAt((buffer << (5 - bits)) & 31);\n  return out;\n}\n\n/** An artifact ID (`art_` + ULID). */\nexport type ArtifactId = Id<\"art\">;\n/** Artifact IDs. */\nexport const ArtifactId: GeneratedIdKind<\"art\"> = generated(\n  defineKind(\"art\", \"artifact\", \"ulid\", \"ArtifactId\"),\n);\n\n/** A version ID (`ver_` + 26 characters of base32 SHA-256): content-addressed, never generated. */\nexport type VersionId = Id<\"ver\">;\n/** The version ID kind, with the content-addressed constructor DATA_MODEL §2 defines. */\nexport interface VersionIdKind extends IdKind<\"ver\"> {\n  /**\n   * Returns the version ID for a SHA-256 digest: `ver_` plus the first 26 characters of the\n   * digest in Crockford base32 (130 bits). The caller computes the digest of the artifact ID's\n   * UTF-8 bytes, a `0x00` byte, and the 32-byte `sourceDigest` and `envDigest` (DATA_MODEL §2,\n   * D89).\n   *\n   * @throws RangeError when `digest` is not 32 bytes long.\n   */\n  fromSha256(digest: Uint8Array): VersionId;\n}\n/** Version IDs. */\nexport const VersionId: VersionIdKind = {\n  ...defineKind(\"ver\", \"version\", \"sha256-base32\", \"VersionId\"),\n  fromSha256(digest: Uint8Array): VersionId {\n    if (digest.length !== 32) {\n      throw new RangeError(`A SHA-256 digest is 32 bytes, got ${digest.length}.`);\n    }\n    return VersionId.parse(`ver_${base32(digest).slice(0, BODY_LENGTH)}`);\n  },\n};\n\n/** A view ID (`vw_` + ULID). */\nexport type ViewId = Id<\"vw\">;\n/** View IDs. */\nexport const ViewId: GeneratedIdKind<\"vw\"> = generated(defineKind(\"vw\", \"view\", \"ulid\", \"ViewId\"));\n\n/** A viewer ID (`vwr_` + ULID). */\nexport type ViewerId = Id<\"vwr\">;\n/** Viewer IDs. */\nexport const ViewerId: GeneratedIdKind<\"vwr\"> = generated(\n  defineKind(\"vwr\", \"viewer\", \"ulid\", \"ViewerId\"),\n);\n\n/** A submission ID (`sub_` + ULID). */\nexport type SubmissionId = Id<\"sub\">;\n/** Submission IDs. */\nexport const SubmissionId: GeneratedIdKind<\"sub\"> = generated(\n  defineKind(\"sub\", \"submission\", \"ulid\", \"SubmissionId\"),\n);\n\n/**\n * A delivery ID (`dlv_` + ULID): one submission's delivery to one host (D105). A redelivery after a\n * crash repeats it, so a host can treat deliveries idempotently.\n */\nexport type DeliveryId = Id<\"dlv\">;\n/** Delivery IDs. */\nexport const DeliveryId: GeneratedIdKind<\"dlv\"> = generated(\n  defineKind(\"dlv\", \"delivery\", \"ulid\", \"DeliveryId\"),\n);\n\n/** An action run ID (`run_` + ULID). */\nexport type RunId = Id<\"run\">;\n/** Action run IDs. */\nexport const RunId: GeneratedIdKind<\"run\"> = generated(\n  defineKind(\"run\", \"action run\", \"ulid\", \"RunId\"),\n);\n\n/** A review thread ID (`thr_` + ULID). */\nexport type ThreadId = Id<\"thr\">;\n/** Review thread IDs. */\nexport const ThreadId: GeneratedIdKind<\"thr\"> = generated(\n  defineKind(\"thr\", \"thread\", \"ulid\", \"ThreadId\"),\n);\n\n/** A comment ID (`cmt_` + ULID). */\nexport type CommentId = Id<\"cmt\">;\n/** Comment IDs. */\nexport const CommentId: GeneratedIdKind<\"cmt\"> = generated(\n  defineKind(\"cmt\", \"comment\", \"ulid\", \"CommentId\"),\n);\n\n/** A capability token ID (`tok_` + ULID). The token's secret is separate and never an ID. */\nexport type TokenId = Id<\"tok\">;\n/** Capability token IDs. */\nexport const TokenId: GeneratedIdKind<\"tok\"> = generated(\n  defineKind(\"tok\", \"capability token\", \"ulid\", \"TokenId\"),\n);\n\n/** A mutation ID (`mut_` + ULID), generated by the client that sends the mutation. */\nexport type MutationId = Id<\"mut\">;\n/** Mutation IDs. */\nexport const MutationId: GeneratedIdKind<\"mut\"> = generated(\n  defineKind(\"mut\", \"mutation\", \"ulid\", \"MutationId\"),\n);\n\n/**\n * An event cursor: the decimal string of a home-wide event position (INTERFACES §1). Decimal\n * strings keep 64-bit positions exact in JavaScript.\n */\nexport type Cursor = string & { readonly __mostraCursor: true };\n\n/** Event cursors. */\nexport const Cursor: {\n  /** The exact form: a non-negative decimal integer without leading zeros, at most 19 digits. */\n  readonly pattern: RegExp;\n  readonly schema: z.ZodType<Cursor, string>;\n  is(value: unknown): value is Cursor;\n  /** @throws TypeError when `value` is not a cursor. */\n  parse(value: string): Cursor;\n  /** Orders two cursors: negative when `a` comes first, zero when equal, positive otherwise. */\n  compare(a: Cursor, b: Cursor): number;\n} = (() => {\n  const pattern = /^(0|[1-9][0-9]{0,18})$/;\n  const is = (value: unknown): value is Cursor => typeof value === \"string\" && pattern.test(value);\n  return {\n    pattern,\n    schema: z.string().regex(pattern).register(wireRegistry, {\n      id: \"Cursor\",\n      description: \"Event cursor: the decimal string of a home-wide event position.\",\n    }) as unknown as z.ZodType<Cursor, string>,\n    is,\n    parse(value: string): Cursor {\n      if (is(value)) return value;\n      throw new TypeError(\"Expected an event cursor: a non-negative decimal integer string.\");\n    },\n    compare(a: Cursor, b: Cursor): number {\n      return a.length === b.length ? (a < b ? -1 : a > b ? 1 : 0) : a.length - b.length;\n    },\n  };\n})();\n"],"mappings":"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"}