npm - @unifedev/thread-pages - Versions diffs - 0.3.2 → 1.0.3 - Mend

@unifedev/thread-pages 0.3.2 → 1.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (90) hide show

package/README.md +77 -129
package/dist/server.js +11426 -11802
package/dist/server.meta.json +2 -2
package/package.json +25 -18
package/server.ts +3 -2175
package/src/agent/cli.ts +193 -0
package/src/agent/guide.ts +355 -0
package/src/agent/instruction.ts +59 -0
package/src/agent/seed/seed.ts +69 -0
package/{theme.ts → src/agent/seed/theme-css.ts} +4 -11
package/src/agent/starter-hub.ts +217 -0
package/src/bb/activity.ts +59 -0
package/src/bb/bb-host.ts +280 -0
package/src/bb/public-origin.ts +45 -0
package/src/config/settings.ts +82 -0
package/src/domain/capabilities/contract.ts +48 -0
package/src/domain/capabilities/index.ts +10 -0
package/src/domain/capabilities/protocol.ts +112 -0
package/src/domain/capabilities/registry.ts +48 -0
package/src/domain/capabilities/schema.ts +198 -0
package/src/domain/capabilities/specs.ts +479 -0
package/src/domain/eligibility.ts +43 -0
package/src/domain/errors.ts +116 -0
package/src/domain/html/document.ts +109 -0
package/src/domain/html/escape.ts +16 -0
package/src/domain/ids.ts +37 -0
package/src/domain/json/canonical.ts +19 -0
package/src/domain/json/strict-json.ts +139 -0
package/src/domain/limits.ts +88 -0
package/src/domain/rate-limit.ts +64 -0
package/src/domain/revision.ts +27 -0
package/src/domain/submissions/idempotency.ts +59 -0
package/src/domain/submissions/message.ts +42 -0
package/src/domain/submissions/parse.ts +105 -0
package/src/domain/tokens/action-token.ts +52 -0
package/src/domain/tokens/confirmation.ts +99 -0
package/src/domain/tokens/mac.ts +50 -0
package/src/generated/kernel-runtime.ts +3 -0
package/src/generated/shell-runtime.ts +3 -0
package/src/host/contract.ts +65 -0
package/src/host/types.ts +89 -0
package/src/pages/layout.ts +65 -0
package/src/pages/page-store.ts +136 -0
package/src/pages/site.ts +36 -0
package/src/plugin.ts +71 -0
package/src/runtime/kernel/anchors.ts +45 -0
package/src/runtime/kernel/api.ts +15 -0
package/src/runtime/kernel/bridge-client.ts +148 -0
package/src/runtime/kernel/dirty.ts +51 -0
package/src/runtime/kernel/forms.ts +114 -0
package/src/runtime/kernel/install.ts +156 -0
package/src/runtime/kernel/labels.ts +98 -0
package/src/runtime/kernel/main.ts +6 -0
package/src/runtime/kernel/readonly.ts +75 -0
package/src/runtime/shared/protocol.ts +125 -0
package/src/runtime/shell/confirm.ts +70 -0
package/src/runtime/shell/install.ts +79 -0
package/src/runtime/shell/main.ts +12 -0
package/src/runtime/shell/navigate.ts +64 -0
package/src/runtime/shell/poll.ts +125 -0
package/src/runtime/shell/relay.ts +185 -0
package/src/serving/action-request.ts +32 -0
package/src/serving/bridge/dispatcher.ts +112 -0
package/src/serving/bridge/handler.ts +37 -0
package/src/serving/bridge/handlers/index.ts +26 -0
package/src/serving/bridge/handlers/navigation.ts +43 -0
package/src/serving/bridge/handlers/reads.ts +186 -0
package/src/serving/bridge/handlers/writes.ts +175 -0
package/src/serving/bridge/selection-store.ts +58 -0
package/src/serving/bridge-route.ts +23 -0
package/src/serving/context.ts +34 -0
package/src/serving/document-route.ts +37 -0
package/src/serving/home-route.ts +23 -0
package/src/serving/responses.ts +81 -0
package/src/serving/routes.ts +26 -0
package/src/serving/session-access.ts +22 -0
package/src/serving/shell-html.ts +77 -0
package/src/serving/shell-route.ts +51 -0
package/src/serving/signing-key.ts +25 -0
package/src/serving/submit-route.ts +47 -0
package/src/serving/upload-route.ts +46 -0
package/tsconfig.json +10 -6
package/ARCHITECTURE.md +0 -230
package/PLUGIN_OVERVIEW.md +0 -83
package/authoring.ts +0 -368
package/bridge.ts +0 -1721
package/docs/MODEL.md +0 -211
package/docs/ROADMAP.md +0 -96
package/home.ts +0 -419
package/page.ts +0 -782

package/src/domain/html/document.ts ADDED Viewed

@@ -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 ADDED Viewed

@@ -0,0 +1,16 @@
+export function escapeHtml(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -0,0 +1,88 @@
+/**
+ * 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 */
+  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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 === "*");
+}

package/src/domain/submissions/idempotency.ts ADDED Viewed

@@ -0,0 +1,59 @@
+import { LIMITS } from "../limits.ts";
+/**
+ * Bounded, expiring memory of outcomes keyed by a client id. A repeat with
+ * the same fingerprint replays the first outcome; a repeat with a different
+ * fingerprint is a conflict. spec R2.33, R2.34, R5.17
+ */
+export type Remembered<T> =
+  | { readonly kind: "fresh"; readonly outcome: Promise<T> }
+  | { readonly kind: "replay"; readonly outcome: Promise<T> }
+  | { readonly kind: "conflict" };
+interface Record<T> {
+  expiresAt: number;
+  fingerprint: string;
+  outcome: Promise<T>;
+}
+export interface OutcomeMemory<T> {
+  remember(key: string, fingerprint: string, produce: () => Promise<T>, now: number): Remembered<T>;
+  size(): number;
+}
+export function createOutcomeMemory<T>(options: { maxRecords?: number; ttlMs?: number } = {}): OutcomeMemory<T> {
+  const maxRecords = options.maxRecords ?? LIMITS.idempotencyRecords;
+  const ttlMs = options.ttlMs ?? LIMITS.idempotencyMs;
+  const records = new Map<string, Record<T>>();
+  function prune(now: number): void {
+    for (const [key, record] of records) {
+      if (record.expiresAt <= now) records.delete(key);
+    }
+    while (records.size >= maxRecords) {
+      const oldest = records.keys().next().value;
+      if (oldest === undefined) break;
+      records.delete(oldest);
+    }
+  }
+  return {
+    remember(key, fingerprint, produce, now) {
+      prune(now);
+      const existing = records.get(key);
+      if (existing) {
+        if (existing.fingerprint !== fingerprint) return { kind: "conflict" };
+        return { kind: "replay", outcome: existing.outcome };
+      }
+      const outcome = produce();
+      const record: Record<T> = { expiresAt: now + ttlMs, fingerprint, outcome };
+      records.set(key, record);
+      // A failed attempt must not poison the key: the next try is fresh.
+      outcome.catch(() => {
+        if (records.get(key) === record) records.delete(key);
+      });
+      return { kind: "fresh", outcome };
+    },
+    size: () => records.size,
+  };
+}

package/src/domain/submissions/message.ts ADDED Viewed

@@ -0,0 +1,42 @@
+import type { JsonValue } from "../json/strict-json.ts";
+import { UPLOAD_DIR } from "../../pages/layout.ts";
+import type { Submission } from "./parse.ts";
+/**
+ * The message a form submission becomes. It names itself, names the form,
+ * leads with the chosen action, presents each answer under the label the
+ * reader saw, and states blanks explicitly. spec R2.35, R2.36
+ */
+export function formatSubmissionMessage(submission: Submission): string {
+  const heading = submission.title.trim() || "Thread Page";
+  const sections = submission.answers.map((answer) => {
+    const label = answer.label.trim() || answer.name;
+    return `**${label}**\n${formatValue(answer.value)}`;
+  });
+  if (submission.files.length > 0) {
+    sections.push(
+      [
+        "**Attached files**",
+        ...submission.files.map((file) => `- \`$BB_THREAD_STORAGE/${file.path}\` (${file.name}, ${file.sizeBytes} bytes)`),
+        `They are in the \`${UPLOAD_DIR}/\` directory of your page root; read them with your normal tools.`,
+      ].join("\n"),
+    );
+  }
+  return [`The user answered the form on your Thread Page — ${heading}.`, ...sections].join("\n\n");
+}
+function formatValue(value: string | string[] | boolean): string {
+  if (typeof value === "boolean") return value ? "Yes" : "No";
+  if (Array.isArray(value)) return value.length > 0 ? value.join(", ") : "(left blank)";
+  return value.length > 0 ? value : "(left blank)";
+}
+/** The message a `session.reply` becomes. spec R5.16 */
+export function formatReplyMessage(title: string | undefined, result: JsonValue): string {
+  const heading = title?.trim() || "Interactive response";
+  const serialized = JSON.stringify(result, null, 2) ?? "null";
+  let longestRun = 0;
+  for (const match of serialized.matchAll(/`+/g)) longestRun = Math.max(longestRun, match[0].length);
+  const fence = "`".repeat(Math.max(3, longestRun + 1));
+  return [`The user sent an interactive response from your Thread Page — ${heading}.`, `**Result**\n\n${fence}json\n${serialized}\n${fence}`].join("\n\n");
+}