@unifedev/thread-pages 0.3.2 → 1.1.0

package/src/domain/eligibility.ts

@@ -0,0 +1,43 @@
+/**
+ * Which sessions may own a page. spec 01 §Eligibility
+ *
+ * A session is eligible when it is visible (not an internal helper), a root
+ * (not a child, not a fork) and live (not archived, not deleted).
+ */
+export interface EligibilityFacts {
+  readonly visibility: "visible" | "hidden";
+  readonly parentId: string | null;
+  readonly forkOfId: string | null;
+  readonly archived: boolean;
+  readonly deleted: boolean;
+}
+
+export type IneligibleReason = "hidden" | "child" | "fork" | "archived" | "deleted";
+
+export function ineligibleReason(facts: EligibilityFacts): IneligibleReason | null {
+  if (facts.deleted) return "deleted";
+  if (facts.archived) return "archived";
+  if (facts.visibility !== "visible") return "hidden";
+  if (facts.parentId !== null) return "child";
+  if (facts.forkOfId !== null) return "fork";
+  return null;
+}
+
+export function isEligible(facts: EligibilityFacts): boolean {
+  return ineligibleReason(facts) === null;
+}
+
+export function describeIneligible(reason: IneligibleReason): string {
+  switch (reason) {
+    case "hidden":
+      return "this session is a hidden helper";
+    case "child":
+      return "this session is a child of another session";
+    case "fork":
+      return "this session is a fork of another session";
+    case "archived":
+      return "this session is archived";
+    case "deleted":
+      return "this session is deleted";
+  }
+}

package/src/domain/errors.ts

@@ -0,0 +1,116 @@
+import { LIMITS } from "./limits.ts";
+
+/** The fixed error set a page may see. spec R5.38 */
+export const BRIDGE_ERROR_CODES = [
+  "invalid_json",
+  "invalid_request",
+  "invalid_params",
+  "invalid_response",
+  "request_too_large",
+  "response_too_large",
+  "unsupported_version",
+  "unknown_method",
+  "stale_page",
+  "confirmation_required",
+  "confirmation_invalid",
+  "cancelled",
+  "not_found",
+  "conflict",
+  "unavailable",
+  "rate_limited",
+  "handler_error",
+  "invalid_result",
+] as const;
+
+export type BridgeErrorCode = (typeof BRIDGE_ERROR_CODES)[number];
+
+const BRIDGE_ERROR_CODE_SET: ReadonlySet<string> = new Set(BRIDGE_ERROR_CODES);
+
+export function isBridgeErrorCode(value: unknown): value is BridgeErrorCode {
+  return typeof value === "string" && BRIDGE_ERROR_CODE_SET.has(value);
+}
+
+/** Codes that only routes (not the bridge) produce. */
+export type RouteErrorCode =
+  | "forbidden"
+  | "ineligible"
+  | "invalid_session"
+  | "no_page"
+  | "page_too_large";
+
+export type PageErrorCode = BridgeErrorCode | RouteErrorCode;
+
+const STATUS_BY_CODE: Record<PageErrorCode, number> = {
+  invalid_json: 400,
+  invalid_request: 400,
+  invalid_params: 400,
+  invalid_response: 502,
+  request_too_large: 413,
+  response_too_large: 500,
+  unsupported_version: 400,
+  unknown_method: 404,
+  stale_page: 409,
+  confirmation_required: 401,
+  confirmation_invalid: 403,
+  cancelled: 400,
+  not_found: 404,
+  conflict: 409,
+  unavailable: 503,
+  rate_limited: 429,
+  handler_error: 500,
+  invalid_result: 500,
+  forbidden: 403,
+  ineligible: 404,
+  invalid_session: 400,
+  no_page: 404,
+  page_too_large: 413,
+};
+
+/**
+ * One failure: a machine code, a message safe to show a reader or a page,
+ * an HTTP status, and (server-side only) the real cause for the log.
+ * spec R2.41–R2.43
+ */
+export class PageError extends Error {
+  readonly code: PageErrorCode;
+  readonly status: number;
+  override readonly cause: unknown;
+
+  constructor(code: PageErrorCode, publicMessage: string, options?: { cause?: unknown; status?: number }) {
+    super(boundedMessage(publicMessage));
+    this.name = "PageError";
+    this.code = code;
+    this.status = options?.status ?? STATUS_BY_CODE[code];
+    this.cause = options?.cause;
+  }
+
+  static is(value: unknown): value is PageError {
+    return value instanceof PageError;
+  }
+}
+
+export function boundedMessage(message: string): string {
+  const normalized = message.replace(/\s+/g, " ").trim() || "Request failed";
+  return normalized.length <= LIMITS.errorMessageChars
+    ? normalized
+    : `${normalized.slice(0, LIMITS.errorMessageChars - 1)}…`;
+}
+
+/** The text of an unknown error, for logs only (never for a page). */
+export function errorText(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  return String(error);
+}
+
+export const PUBLIC_MESSAGES = Object.freeze({
+  noPage: "This session has no page yet. Run `bb thread-page init` in the session first.",
+  ineligible: "Only visible root sessions have pages.",
+  pageTooLarge: `The page's entry document is larger than ${LIMITS.entryDocumentBytes / (1024 * 1024)} MiB and was not served.`,
+  unavailable: "The page's source is unreachable. Reconnect its host and try again.",
+  staleCopy: "The source host is offline; this cached page is read-only.",
+  stalePage: "This page changed; reload it before responding.",
+  handler: "Could not execute the page action.",
+  rateLimited: "Too many requests from this page; try again shortly.",
+  invalidSession: "A valid session id is required.",
+  tokenInvalid: "This page session is invalid or expired; reload the page.",
+});

package/src/domain/html/document.ts

@@ -0,0 +1,109 @@
+import { defaultTreeAdapter, parse as parseHtml, serialize as serializeHtml, type DefaultTreeAdapterTypes } from "parse5";
+import { escapeHtml } from "./escape.ts";
+
+/**
+ * Kernel injection. spec R4.1–R4.4
+ *
+ * The authored document is parsed the way a browser parses it, and two
+ * nodes at most are inserted at the very front of `<head>` (or the first
+ * element that can hold them): an optional `<base>` for the site strategy,
+ * then the kernel script with its configuration in a data attribute. Nothing
+ * else changes — no reformatting, no reordering, no rewritten URLs.
+ */
+export interface InjectionOptions {
+  /** The kernel runtime source (an IIFE). */
+  readonly kernel: string;
+  /** JSON-serialisable kernel configuration, carried in `data-config`. */
+  readonly config: unknown;
+  /** Same-origin base URL to inject, or null. */
+  readonly baseHref: string | null;
+}
+
+type HtmlDocument = DefaultTreeAdapterTypes.Document;
+type HtmlElement = DefaultTreeAdapterTypes.Element;
+type HtmlParent = HtmlDocument | HtmlElement;
+
+const XHTML = "http://www.w3.org/1999/xhtml";
+
+export function injectKernel(source: string, options: InjectionOptions): string {
+  const authored = parseAuthored(source);
+  if (authored) {
+    return injectInto(authored, options);
+  }
+  // Not a document at all: wrap it so the reader sees something and the
+  // kernel still runs. spec R4.4
+  return wrapFragment(source, options);
+}
+
+function directChild(parent: HtmlParent, tagName: string): HtmlElement | null {
+  for (const child of parent.childNodes) {
+    if (defaultTreeAdapter.isElementNode(child) && child.tagName === tagName && child.namespaceURI === XHTML) {
+      return child;
+    }
+  }
+  return null;
+}
+
+interface Authored {
+  document: HtmlDocument;
+  target: HtmlElement;
+}
+
+function parseAuthored(source: string): Authored | null {
+  const text = source.charCodeAt(0) === 0xfeff ? source.slice(1) : source;
+  const document = parseHtml(text, { scriptingEnabled: true, sourceCodeLocationInfo: true });
+  const html = directChild(document, "html");
+  if (!html) return null;
+  const head = directChild(html, "head");
+  const body = directChild(html, "body");
+  const frameset = directChild(html, "frameset");
+  const hasDoctype = document.childNodes.some(
+    (child) => defaultTreeAdapter.isDocumentTypeNode(child) && child.name.toLowerCase() === "html",
+  );
+  const hasAuthoredShell = [html, head, body, frameset].some((element) => element?.sourceCodeLocation != null);
+  if (!hasDoctype && !hasAuthoredShell) return null;
+  return { document, target: head ?? body ?? frameset ?? html };
+}
+
+function kernelElement(namespace: HtmlElement["namespaceURI"], options: InjectionOptions): HtmlElement {
+  const script = defaultTreeAdapter.createElement("script", namespace, [
+    { name: "data-thread-page-kernel", value: "" },
+    { name: "data-config", value: JSON.stringify(options.config) },
+  ]);
+  defaultTreeAdapter.insertText(script, options.kernel);
+  return script;
+}
+
+function injectInto(authored: Authored, options: InjectionOptions): string {
+  const namespace = authored.target.namespaceURI;
+  const nodes: HtmlElement[] = [];
+  if (options.baseHref) {
+    nodes.push(defaultTreeAdapter.createElement("base", namespace, [{ name: "href", value: options.baseHref }]));
+  }
+  nodes.push(kernelElement(namespace, options));
+  const anchor = defaultTreeAdapter.getFirstChild(authored.target);
+  for (const node of nodes) {
+    if (anchor) defaultTreeAdapter.insertBefore(authored.target, node, anchor);
+    else defaultTreeAdapter.appendChild(authored.target, node);
+  }
+  return serializeHtml(authored.document);
+}
+
+function wrapFragment(source: string, options: InjectionOptions): string {
+  const base = options.baseHref ? `<base href="${escapeHtml(options.baseHref)}">\n` : "";
+  const config = escapeHtml(JSON.stringify(options.config));
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">
+<meta name="color-scheme" content="light dark">
+<title>Thread Page</title>
+${base}<script data-thread-page-kernel data-config="${config}">${options.kernel}</script>
+<style>body{max-width:44rem;margin:2rem auto;padding:0 1rem;font:16px/1.55 system-ui,sans-serif;color:CanvasText;background:Canvas}</style>
+</head>
+<body>
+${source}
+</body>
+</html>`;
+}

package/src/domain/html/escape.ts

@@ -0,0 +1,16 @@
+export function escapeHtml(value: string): string {
+  return value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+}
+
+/** JSON that is safe inside an inline `<script>`: no `<`, no line separators. */
+export function jsonForScript(value: unknown): string {
+  return JSON.stringify(value)
+    .replace(/</g, "\\u003c")
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029");
+}

package/src/domain/ids.ts

@@ -0,0 +1,37 @@
+/** Identifier shapes accepted at every boundary. */
+
+const SESSION_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$/;
+const ENTITY_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+const REQUEST_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,95}$/;
+const METHOD_NAME = /^[a-z][a-zA-Z0-9]*(?:\.[a-z][a-zA-Z0-9]*)+$/;
+const REVISION = /^[a-f0-9]{64}$/;
+const OPAQUE_TOKEN = /^[A-Za-z0-9][A-Za-z0-9._~:-]{0,511}$/;
+const STORAGE_KEY = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+
+export function isSessionId(value: unknown): value is string {
+  return typeof value === "string" && SESSION_ID.test(value);
+}
+
+export function isEntityId(value: unknown): value is string {
+  return typeof value === "string" && ENTITY_ID.test(value);
+}
+
+export function isRequestId(value: unknown): value is string {
+  return typeof value === "string" && REQUEST_ID.test(value);
+}
+
+export function isMethodName(value: unknown): value is string {
+  return typeof value === "string" && value.length <= 96 && METHOD_NAME.test(value);
+}
+
+export function isRevision(value: unknown): value is string {
+  return typeof value === "string" && REVISION.test(value);
+}
+
+export function isOpaqueToken(value: unknown): value is string {
+  return typeof value === "string" && OPAQUE_TOKEN.test(value);
+}
+
+export function isStorageKey(value: unknown): value is string {
+  return typeof value === "string" && STORAGE_KEY.test(value);
+}

package/src/domain/json/canonical.ts

@@ -0,0 +1,19 @@
+import { createHash } from "node:crypto";
+import type { JsonValue } from "./strict-json.ts";
+
+/**
+ * Canonical serialisation: object keys sorted at every level, so reordering
+ * keys cannot change a fingerprint. spec R3.20
+ */
+export function canonicalJson(value: JsonValue): string {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map((item) => canonicalJson(item)).join(",")}]`;
+  return `{${Object.keys(value)
+    .sort()
+    .map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key] as JsonValue)}`)
+    .join(",")}}`;
+}
+
+export function fingerprint(value: JsonValue): string {
+  return createHash("sha256").update(canonicalJson(value), "utf8").digest("hex");
+}

package/src/domain/json/strict-json.ts

@@ -0,0 +1,139 @@
+import { LIMITS } from "../limits.ts";
+
+/**
+ * A value that survives a JSON round trip without loss, and the checks that
+ * establish it: no cycles, accessors, symbols, sparse arrays, unsafe keys,
+ * non-finite numbers, and bounded depth, node count and serialised size.
+ * spec R5.2
+ */
+export type JsonPrimitive = null | boolean | number | string;
+export type JsonObject = { [key: string]: JsonValue };
+export type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+
+export type IssueCode =
+  | "invalid_type"
+  | "invalid_value"
+  | "missing_key"
+  | "unknown_key"
+  | "not_json_safe"
+  | "too_deep"
+  | "too_large";
+
+export interface Issue {
+  readonly code: IssueCode;
+  readonly path: string;
+  readonly message: string;
+}
+
+export type Validation<T> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly issues: readonly Issue[] };
+
+export function valid<T>(value: T): Validation<T> {
+  return { ok: true, value };
+}
+
+export function invalid<T = never>(path: string, message: string, code: IssueCode = "invalid_value"): Validation<T> {
+  return { ok: false, issues: [{ code, path, message }] };
+}
+
+export interface JsonLimits {
+  readonly maxBytes?: number;
+  readonly maxDepth?: number;
+  readonly maxNodes?: number;
+}
+
+const UNSAFE_KEYS = new Set(["__proto__", "prototype", "constructor"]);
+
+export function pathForKey(parent: string, key: string): string {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? `${parent}.${key}` : `${parent}[${JSON.stringify(key)}]`;
+}
+
+export function utf8Bytes(value: string): number {
+  return new TextEncoder().encode(value).byteLength;
+}
+
+/** Validates without coercion and returns a detached copy of the value. */
+export function validateJson(input: unknown, limits: JsonLimits = {}): Validation<JsonValue> {
+  const maxBytes = limits.maxBytes ?? LIMITS.capabilityPayloadBytes;
+  const maxDepth = limits.maxDepth ?? LIMITS.capabilityJsonDepth;
+  const maxNodes = limits.maxNodes ?? LIMITS.capabilityJsonNodes;
+  const ancestors = new Set<object>();
+  let nodes = 0;
+
+  function visit(value: unknown, path: string, depth: number): Issue | null {
+    nodes += 1;
+    if (nodes > maxNodes) return { code: "too_large", path, message: `JSON exceeds ${maxNodes} nodes` };
+    if (depth > maxDepth) return { code: "too_deep", path, message: `JSON exceeds depth ${maxDepth}` };
+    if (value === null || typeof value === "string" || typeof value === "boolean") return null;
+    if (typeof value === "number") {
+      return Number.isFinite(value) ? null : { code: "not_json_safe", path, message: "Numbers must be finite" };
+    }
+    if (typeof value !== "object") {
+      return { code: "not_json_safe", path, message: `Unsupported value type: ${typeof value}` };
+    }
+    if (ancestors.has(value)) return { code: "not_json_safe", path, message: "Cyclic values are not JSON-safe" };
+    ancestors.add(value);
+    try {
+      if (Array.isArray(value)) {
+        for (const key of Reflect.ownKeys(value)) {
+          if (typeof key === "symbol") return { code: "not_json_safe", path, message: "Symbol properties are not JSON-safe" };
+          if (key !== "length" && !isCanonicalIndex(key, value.length)) {
+            return { code: "not_json_safe", path: pathForKey(path, key), message: "Arrays may not carry extra properties" };
+          }
+        }
+        for (let index = 0; index < value.length; index += 1) {
+          const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+          if (!descriptor || !("value" in descriptor) || !descriptor.enumerable) {
+            return { code: "not_json_safe", path: `${path}[${index}]`, message: "Sparse arrays and accessors are not JSON-safe" };
+          }
+          const issue = visit(descriptor.value, `${path}[${index}]`, depth + 1);
+          if (issue) return issue;
+        }
+        return null;
+      }
+      const prototype = Object.getPrototypeOf(value);
+      if (prototype !== Object.prototype && prototype !== null) {
+        return { code: "not_json_safe", path, message: "Only plain objects are JSON-safe" };
+      }
+      for (const key of Reflect.ownKeys(value)) {
+        if (typeof key === "symbol") return { code: "not_json_safe", path, message: "Symbol properties are not JSON-safe" };
+        if (UNSAFE_KEYS.has(key)) return { code: "not_json_safe", path: pathForKey(path, key), message: "Unsafe object key" };
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (!descriptor || !("value" in descriptor) || !descriptor.enumerable) {
+          return { code: "not_json_safe", path: pathForKey(path, key), message: "Entries must be enumerable data properties" };
+        }
+        const issue = visit(descriptor.value, pathForKey(path, key), depth + 1);
+        if (issue) return issue;
+      }
+      return null;
+    } catch {
+      return { code: "not_json_safe", path, message: "Value could not be inspected" };
+    } finally {
+      ancestors.delete(value);
+    }
+  }
+
+  const issue = visit(input, "$", 0);
+  if (issue) return { ok: false, issues: [issue] };
+  let serialized: string;
+  try {
+    serialized = JSON.stringify(input);
+  } catch {
+    return invalid("$", "Value could not be serialised", "not_json_safe");
+  }
+  if (utf8Bytes(serialized) > maxBytes) {
+    return invalid("$", `Serialised JSON exceeds ${maxBytes} bytes`, "too_large");
+  }
+  return valid(JSON.parse(serialized) as JsonValue);
+}
+
+function isCanonicalIndex(key: string, length: number): boolean {
+  if (!/^(0|[1-9][0-9]*)$/.test(key)) return false;
+  const index = Number(key);
+  return Number.isSafeInteger(index) && index >= 0 && index < length;
+}
+
+export function isJsonObject(value: JsonValue | undefined): value is JsonObject {
+  return value !== undefined && value !== null && typeof value === "object" && !Array.isArray(value);
+}

package/src/domain/limits.ts

@@ -0,0 +1,98 @@
+/**
+ * Every numeric limit the product enforces, in one place.
+ *
+ * The authoring guide is generated from this object (spec R6.25, R6.26), so a
+ * limit that is not here is a limit an agent cannot design against. Values
+ * follow spec/09-conformance.md §Limits except where rewrite decisions
+ * (RW-8) chose otherwise; each such case is noted.
+ */
+export const LIMITS = Object.freeze({
+  /** Entry document (`index.html`); refused above, never truncated. R1.7 */
+  entryDocumentBytes: 5 * 1024 * 1024,
+  /** One uploaded file. R4.23 */
+  uploadFileBytes: 24 * 1024 * 1024,
+  /** Files per form submission; extras are ignored visibly. R4.23 */
+  uploadsPerForm: 8,
+  /** Submission JSON body, excluding uploaded bytes. */
+  submissionBodyBytes: 64 * 1024,
+  /** Answers per submission, and characters per answer value. */
+  answersPerSubmission: 64,
+  answerValueChars: 8_000,
+  answerListItems: 64,
+  /** Capability request and response, serialised. R5.2 */
+  capabilityPayloadBytes: 64 * 1024,
+  capabilityJsonDepth: 16,
+  capabilityJsonNodes: 10_000,
+  /** `sessions.start` and `sessions.send` prompts. */
+  promptChars: 32 * 1024,
+  /** `session.reply` result, serialised. */
+  resultTextBytes: 64 * 1024,
+  /** Titles, names and labels shown to a reader. */
+  titleChars: 240,
+  /** One `storage` value, serialised. R5.19 */
+  storageValueBytes: 32 * 1024,
+  storageKeyChars: 128,
+  /** `sessions.snapshot` page size. R5.11 */
+  snapshotDefault: 100,
+  snapshotMax: 200,
+  /** `session.activity` items. */
+  activityDefault: 8,
+  activityMax: 20,
+  /** Action token lifetime. R2.9 */
+  actionTokenMs: 2 * 60 * 60 * 1000,
+  /** Confirmation challenge lifetime. R3.19 */
+  confirmationMs: 2 * 60 * 1000,
+  /** Folder-picker selection token lifetime; single use. R5.36 */
+  selectionTokenMs: 10 * 60 * 1000,
+  selectionTokens: 32,
+  /** Submission and reply idempotency records. R2.34 */
+  idempotencyRecords: 512,
+  idempotencyMs: 5 * 60 * 1000,
+  /**
+   * Effectful requests per page. RW-8: 120/min and 8 concurrent rather than
+   * the spec's 30/4, so a page that lists sessions and refreshes cannot
+   * exhaust its own budget (R2.40). The shell's revision poll is not counted.
+   */
+  ratePerMinute: 120,
+  rateConcurrent: 8,
+  /** Shell revision poll while the tab is visible. R2.17 */
+  shellPollMs: 10_000,
+  /** `watch` interval default and clamp. R4.30 */
+  watchDefaultMs: 8_000,
+  watchMinMs: 2_000,
+  watchMaxMs: 5 * 60 * 1000,
+  /** Offline copy of the entry document kept in the host's key-value store. R2.30 */
+  /**
+   * Resolving a page's own files into its entry document (see pages/inline.ts).
+   * The per-file cap is generous because a page's stylesheet and data set are
+   * the whole point; the total is what keeps one page from becoming a document
+   * no phone will load. Base64 costs a third on top of both.
+   */
+  inlineFileBytes: 2 * 1024 * 1024,
+  inlineTotalBytes: 3 * 1024 * 1024,
+  /** How far `url()` inside an inlined stylesheet is followed. */
+  inlineCssDepth: 3,
+  offlineCopyBytes: 200 * 1024,
+  offlineCacheEntries: 32,
+  offlineCacheBytes: 8 * 1024 * 1024,
+  /** Bridge envelope identifiers. */
+  requestIdChars: 96,
+  methodNameChars: 96,
+  tokenChars: 4_096,
+  errorMessageChars: 512,
+  summaryChars: 512,
+  /** Sizes of lists a capability may return. */
+  projectsMax: 200,
+  providersMax: 64,
+  modelsPerProvider: 64,
+});
+
+export type Limits = typeof LIMITS;
+
+export function mebibytes(bytes: number): string {
+  return `${Math.round((bytes / (1024 * 1024)) * 100) / 100} MiB`;
+}
+
+export function kibibytes(bytes: number): string {
+  return `${Math.round(bytes / 1024)} KiB`;
+}

package/src/domain/rate-limit.ts

@@ -0,0 +1,64 @@
+import { LIMITS } from "./limits.ts";
+
+/**
+ * Per-page budget for effectful requests: accepted requests per minute and
+ * requests in flight. spec R2.38–R2.40 (numbers: RW-8)
+ */
+export interface RateBudget {
+  readonly perMinute: number;
+  readonly concurrent: number;
+}
+
+interface Bucket {
+  windowStartedAt: number;
+  accepted: number;
+  inFlight: number;
+  touchedAt: number;
+}
+
+export interface RateLimiter {
+  /** Returns a release function, or null when the request is refused. */
+  acquire(key: string, now: number): (() => void) | null;
+  /** For tests and status. */
+  snapshot(key: string): { accepted: number; inFlight: number } | null;
+}
+
+export function createRateLimiter(budget: RateBudget = { perMinute: LIMITS.ratePerMinute, concurrent: LIMITS.rateConcurrent }): RateLimiter {
+  const buckets = new Map<string, Bucket>();
+
+  function prune(now: number): void {
+    for (const [key, bucket] of buckets) {
+      if (bucket.inFlight === 0 && now - bucket.touchedAt > 5 * 60_000) buckets.delete(key);
+    }
+  }
+
+  return {
+    acquire(key, now) {
+      prune(now);
+      const bucket = buckets.get(key) ?? { windowStartedAt: now, accepted: 0, inFlight: 0, touchedAt: now };
+      if (now - bucket.windowStartedAt >= 60_000) {
+        bucket.windowStartedAt = now;
+        bucket.accepted = 0;
+      }
+      if (bucket.inFlight >= budget.concurrent || bucket.accepted >= budget.perMinute) {
+        buckets.set(key, bucket);
+        return null;
+      }
+      bucket.accepted += 1;
+      bucket.inFlight += 1;
+      bucket.touchedAt = now;
+      buckets.set(key, bucket);
+      let released = false;
+      return () => {
+        if (released) return;
+        released = true;
+        bucket.inFlight = Math.max(0, bucket.inFlight - 1);
+        bucket.touchedAt = Date.now();
+      };
+    },
+    snapshot(key) {
+      const bucket = buckets.get(key);
+      return bucket ? { accepted: bucket.accepted, inFlight: bucket.inFlight } : null;
+    },
+  };
+}

package/src/domain/revision.ts

@@ -0,0 +1,27 @@
+import { createHash } from "node:crypto";
+
+/** A page revision is the SHA-256 of the entry document's bytes. spec R2.11 */
+export function revisionOf(content: string | Uint8Array): string {
+  const hash = createHash("sha256");
+  if (typeof content === "string") hash.update(content, "utf8");
+  else hash.update(content);
+  return hash.digest("hex");
+}
+
+export function sha256Hex(content: string | Uint8Array): string {
+  return revisionOf(content);
+}
+
+/** The revision doubles as the entity tag. spec R2.12 */
+export function etagFor(revision: string): string {
+  return `"${revision}"`;
+}
+
+/** Whether an `If-None-Match` header names the given entity tag. */
+export function ifNoneMatchMatches(header: string | undefined | null, etag: string): boolean {
+  if (!header) return false;
+  return header
+    .split(",")
+    .map((candidate) => candidate.trim().replace(/^W\//, ""))
+    .some((candidate) => candidate === etag || candidate === "*");
+}