@wenathlan/saddle 2.0.163 → 2.0.164

package/Dockerfile

@@ -1,4 +1,4 @@
-# saddle 2.0.162 — THE ENGINE CONTAINER FILE
+# saddle 2.0.163 — THE ENGINE CONTAINER FILE
 #
 # THE FAMILY CONTAINER DOCTRINE, THE SADDLE SHAPE: one versioned container
 # per engine, built like the site homes (argan, cadria) build theirs — a
@@ -61,6 +61,29 @@
 # is the sandbox spec surface the console answers, never a host
 # distribution this container installs.
 #
+# THE OS DISTRIBUTION SEATS the saddle container carries (the osdistrib
+# law, saddle/containerarch.ts — the owner's sentence: "iniciar
+# distribuição do container saddle com por exemplo, grapheneos, omarchy
+# e outros sistemas dentro do saddle"): the container starts its
+# distribution catalog with the seven system seats the OSDISTRIBUTIONS
+# registry pins — grapheneos (a privacy and security hardened version of
+# android), omarchy (the arch linux-based distribution created by dhh),
+# vanilla os (based on ubuntu), maru os (firmware, not an application),
+# the v seat (the vlang platform the dependency catalog pins at 0.5.2,
+# never a guest distribution), the normal linux baseline and android —
+# every seat paired with the architecture legs the eleven-architecture
+# standard already carries (the mobile and firmware seats ride the arm64
+# legs, the desktop and baseline seats ride amd64 and arm64) and bound
+# to the max/balanced/lite engine plan trio the engineplans table owns.
+# The distribution matrix needs NO new build legs: the seats ride the
+# existing arch axis of this file (the amd64 and arm64 legs the pinned
+# base already resolves), so the publish lanes and the build matrix stay
+# untouched — the registry is the catalog the container lanes stamp and
+# the modality system reads (saddle/docs/osdistributions.md). The
+# 50gb-per-plan example the owner's law names stays PLAN CONFIG the
+# devthink plan logic stamps, never a container cap: the engines are
+# unlimited.
+#
 # THE ELEVEN-ARCHITECTURE PLATFORM STANDARD (the pr15 law): every
 # profile answers the eleven architecture seats the container standard
 # names — the CONTAINERARCHIDS of saddle/containerarch.ts (linux-x64,
@@ -118,7 +141,7 @@ ARG NODE_BASE_DIGEST
 # ===== stage: solbuild — the locked npm tree and the console spa =====
 FROM --platform=$BUILDPLATFORM ${NODE_BASE_TAG}@sha256:${NODE_BASE_DIGEST} AS solbuild
 
-ARG SADDLE_VERSION=2.0.162
+ARG SADDLE_VERSION=2.0.163
 
 WORKDIR /app
 
@@ -146,7 +169,7 @@ RUN npm run web:build:pages \
 # ===== stage: base — the hardened runtime floor every profile shares =====
 FROM ${NODE_BASE_TAG}@sha256:${NODE_BASE_DIGEST} AS base
 
-ARG SADDLE_VERSION=2.0.162
+ARG SADDLE_VERSION=2.0.163
 # the revision stamp the devthink container carries (DEVTHINK_REVISION
 # there): the publish legs pass the release sha at build time and the
 # revision label below declares the default-unknown local shape.

package/README.md

@@ -31,7 +31,7 @@ domain modules land beside the saddle domains:
 | `media.ts`, `render.ts`, `quantum.ts`, `tiers.ts` | media pipeline, GPU registry, quantum simulation, tier policy |
 | `security.ts`, `alternatives.ts` | hardening gates and the alternative-stack catalog |
 | `index.html`, `App.tsx`, `sol/` | the single SPA shell and the Sol theme (one tsx app with one stylesheet per theme) |
-| `server.ts`, `sandbox.ts` | the zero-dependency self-hosted API of the 2.0.163 grand-merge envelope (`node server.ts`; the api answers its version at `/api/v1/health`) and the browser-pure engine port |
+| `server.ts`, `sandbox.ts` | the zero-dependency self-hosted API of the 2.0.164 grand-merge envelope (`node server.ts`; the api answers its version at `/api/v1/health`) and the browser-pure engine port |
 | `vercel.json`, `netlify.toml` | the platform deploy adapters beside the surface they publish (the caddy ghost stays out of the tree) |
 | `specs/*` package exports | processors, gpus, cores, boards and the qemu/mttg/passage/docker envelopes |
 

package/cli.ts

@@ -14,7 +14,8 @@
 import { mkdtemp, readFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { argv } from "node:process";
+import { argv, stdin, stdout } from "node:process";
+import { createInterface } from "node:readline/promises";
 import { eventbus } from "./foundation.ts";
 import { localmemory, localstorage } from "./virtual.ts";
 import { engine, inprocess, scheduler } from "./execution.ts";
@@ -44,7 +45,8 @@ import {
 export async function main(args = argv.slice(2)) {
   const command = args[0] ?? "help";
   /* Help stays short and lists only stable local commands. */
-  if (["help", "--help", "-h"].includes(command)) { console.log("saddle <command>\n\ncommands\n  help\n  modes\n  plan [qemu|docker|toml]\n  vm [qemu|docker|toml]\n  vmlint\n  gpus\n  runexample\n  script <run|background|status|docker|compile> [file|runid]\n  mcp"); return; }
+  if (["help", "--help", "-h"].includes(command)) { console.log("saddle <command>\n\ncommands\n  help\n  chat\n  modes\n  plan [qemu|docker|toml]\n  vm [qemu|docker|toml]\n  vmlint\n  gpus\n  runexample\n  script <run|background|status|docker|compile> [file|runid]\n  mcp"); return; }
+  if (command === "chat") { await renderchat(); return; }
   if (command === "modes") { console.log(JSON.stringify(modecatalog(), null, 2)); return; }
   if (command === "plan") { await renderplan(args[1]); return; }
   /* The vm/vmlint/gpus triad makes the nominal npm aliases (vm:create, */
@@ -271,4 +273,99 @@ async function renderscript(subcommand = "help", target = "") {
   }
 }
 
+/* ════════════════════════════════════════════════════════════════════ */
+/* Section 4: the chat console — the pr13 creation workspace seat: the */
+/* same windows 11 chat console the family clibin seats render, with   */
+/* the same tokens, the same titlebar and the same dpi ladder (native  */
+/* detection, 1x / 1.5x / 2x / 3x, never xdpi — the difference from    */
+/* the web / desktop surface is only the responsiveness).              */
+/* ════════════════════════════════════════════════════════════════════ */
+
+/** the chat accent of the prompt and the titlebar name (ansi 117 — the family accent #a3d7e6). */
+const CHATACCENT = "\x1b[38;5;117m" as const;
+/** the focus ink of the active top rule (ansi 75 — the family focus #4cc2ff). */
+const CHATFOCUS = "\x1b[38;5;75m" as const;
+/** the hover red of the unknown-command rows (ansi 203 — rgb(232, 17, 35)). */
+const CHATHOVER = "\x1b[38;5;203m" as const;
+/** the dim ink of the description rows (the minimal text law). */
+const CHATINK = "\x1b[2m" as const;
+/** the reset token that closes every colored run. */
+const CHATRESET = "\x1b[0m" as const;
+/** the single glyph of the rules and the rails. */
+const CHATBAR = "─" as const;
+/** the engine ownership one-liner of the seat, quoted from the README. */
+const CHATENGINE = "storage-backed jobs, ninety sandbox modalities and portable runners — the master engine of virtualization (README)" as const;
+/** the scale ladder the native detection resolves (the automatic scaling law). */
+const CHATSCALESTEPS = [1, 1.5, 2, 3] as const;
+
+/** the dpi frame the chat chrome renders inside: the resolved scale seat, the terminal columns and the rail length the titlebar draws. */
+interface chatframe {
+  /** the scale seat of the ladder (1, 1.5, 2 or 3). */
+  scale: number;
+  /** the columns the terminal answers (windows terminal, conpty, xterm, tmux — every pty reports them). */
+  columns: number;
+  /** the titlebar rail length in cells (the pixel rail folded to the grid and clamped so the line never wraps). */
+  rail: number;
+}
+
+/** resolves the dpi frame natively, zero dependencies: the columns come from stdout (every windows and linux terminal answers them), the scale seat from the column ladder — the explicit SADDLE_DPI environment override wins first (the native scaling knob). */
+function chatdetectframe(): chatframe {
+  const columns = Number.isFinite(stdout.columns) && Number(stdout.columns) > 0 ? Number(stdout.columns) : 80;
+  const override = Number(process.env.SADDLE_DPI ?? "");
+  const scale =
+    Number.isFinite(override) && override > 0 && CHATSCALESTEPS.includes(override as (typeof CHATSCALESTEPS)[number])
+      ? override
+      : columns >= 200
+        ? 3
+        : columns >= 160
+          ? 2
+          : columns >= 120
+            ? 1.5
+            : 1;
+  const rail = Math.max(4, Math.min(Math.round(24 * scale), columns - "saddle".length - 16));
+  return { scale, columns, rail };
+}
+
+/** runs the chat console: the titlebar, the top rule, the ❯ prompt and the dispatch (help, version, dpi, engine, exit) — the same chat look the web / desktop surfaces carry, an eof on stdin closing the console the same way exit does. */
+async function renderchat(): Promise<void> {
+  const frame = chatdetectframe();
+  let seatversion = "0.0.0";
+  try {
+    seatversion = String((JSON.parse(await readFile(new URL("./package.json", import.meta.url), "utf8")) as { version?: string }).version ?? "0.0.0");
+  } catch {
+    /* the guarded best-effort read answers the zero literal the version row prints */
+  }
+  const rl = createInterface({ input: stdin, output: stdout });
+  let eof = false;
+  rl.on("close", () => { eof = true; });
+  const rule = CHATBAR.repeat(Math.max(3, Math.round(3 * frame.scale)));
+  console.log(`${CHATACCENT}┌ saddle ─ cli${CHATRESET}  ${CHATINK}${CHATBAR.repeat(frame.rail)} ─ ❐ ✕${CHATRESET}`);
+  console.log(`${CHATFOCUS}${rule} saddle ${rule}${CHATRESET}`);
+  console.log(`${CHATACCENT}saddle${CHATRESET} ${CHATINK}v${seatversion}${CHATRESET}`);
+  console.log(`${CHATINK}the saddle console — same design as web / desktop, only the DPI differs. type help.${CHATRESET}`);
+  rl.setPrompt(`${CHATACCENT}❯${CHATRESET} `);
+  rl.prompt();
+  for await (const raw of rl) {
+    const line = raw.trim();
+    const command = line.length > 0 ? line.split(/\s+/)[0]!.toLowerCase() : "";
+    if (command === "exit") rl.close();
+    else if (command === "help") {
+      console.log(`${CHATINK}commands${CHATRESET}`);
+      console.log(`  help      ${CHATINK}this list${CHATRESET}`);
+      console.log(`  version   ${CHATINK}the package version, read from package.json at runtime${CHATRESET}`);
+      console.log(`  dpi       ${CHATINK}the resolved dpi seat of this terminal (scale, columns, rail)${CHATRESET}`);
+      console.log(`  engine    ${CHATINK}the engine ownership one-liner of the app${CHATRESET}`);
+      console.log(`  exit      ${CHATINK}close the console${CHATRESET}`);
+    }
+    else if (command === "version") console.log(`${CHATACCENT}saddle${CHATRESET} ${seatversion}`);
+    else if (command === "dpi") console.log(`${CHATACCENT}saddle${CHATRESET} ${CHATINK}dpi seat ${frame.scale}x on ${frame.columns} columns — rail ${frame.rail} cells, ladder 1x / 1.5x / 2x / 3x${CHATRESET}`);
+    else if (command === "engine") console.log(`${CHATINK}${CHATENGINE}${CHATRESET}`);
+    else if (command.length > 0) console.log(`${CHATHOVER}✕${CHATRESET} ${CHATINK}unknown command: ${command} — type help${CHATRESET}`);
+    if (command === "exit") break;
+    /* the prompt is cosmetic chrome: a piped stdin that already reached eof skips it, the buffered lines still answer. */
+    if (!eof) rl.prompt();
+  }
+  console.log(`${CHATINK}saddle console closed.${CHATRESET}`);
+}
+
 if (import.meta.url === `file://${argv[1]}`) main().catch((error) => { console.error(error); process.exitCode = 1; });

package/communication.ts

@@ -0,0 +1,455 @@
+/**
+ * communication.ts — API, protocol and webhook communication contracts.
+ *
+ * This file is the v2.0.0 grand-merge consolidation of the former nested
+ * folders of the repository (api) into the single
+ * root-level domain file of the saddle family standard: one optimized
+ * TypeScript file per correlated domain, ordinal sections, JSDoc on every
+ * block, intra-domain imports dissolved, cross-domain imports rewritten to
+ * ./<domain>.js. Every capability of every source file is preserved here;
+ * the pure re-export barrels (none in this domain) folded their surface into this file directly.
+ */
+
+import { constanttimeequal, hmacsha256 } from "./foundation.ts";
+
+/* ══════════════════════════════════════════════════════════════════ */
+/* Section 0: api/controlsurface.ts — the operator control surface the */
+/* control service defaults to (the saddle ownership law, wave a,     */
+/* actions 108-112: the workflow automation domain moved to devthink, */
+/* and the api contracts carry their own default surface — the same   */
+/* resource and operation vocabulary, the same audit law).            */
+/* ══════════════════════════════════════════════════════════════════ */
+
+/** the operator resources the control surface answers. */
+export const controlresources = Object.freeze([
+  "jobs",
+  "sessions",
+  "storage",
+  "runners",
+  "permissions",
+  "logs",
+  "artifacts",
+]);
+
+/** the operator operations the control surface answers. */
+export const controloperations = Object.freeze([
+  "list",
+  "get",
+  "create",
+  "update",
+  "cancel",
+  "retry",
+  "delete",
+  "check",
+]);
+
+/** the message a caught value carries for the wire: an Error answers its
+ * message only and every other shape answers the fallback (the caught
+ * value as a whole never rides the payload). */
+const controlerrormessage = (error: unknown, fallback = "operation failed"): string => {
+  if (error instanceof Error) return error.message;
+  return fallback;
+};
+
+/** answers one control response and rides the optional audit hook. */
+async function controlrespond({ ok, result, code, message, context, audit }) {
+  const response = { version: 1, ok, ...context, ...(ok ? { result } : { code, message }) };
+  if (audit)
+    try {
+      await audit(response);
+    } catch (error) {
+      response.auditerror = controlerrormessage(error);
+    }
+  return response;
+}
+
+/** Creates a caller-owned operator surface with resource handlers and
+ * optional audit recording — the default surface the control service
+ * mounts when the caller sends adapters without a prebuilt surface. */
+export function controlsurface(options = {}) {
+  const adapters = { ...(options.adapters ?? {}) };
+  const audit = options.audit;
+  if (audit !== undefined && typeof audit !== "function") throw new TypeError("control audit must be callable");
+  for (const resource of Object.keys(adapters))
+    if (!controlresources.includes(resource) || !adapters[resource] || typeof adapters[resource] !== "object")
+      throw new TypeError(`unsupported control resource: ${resource}`);
+
+  async function execute(request = {}) {
+    const resource = String(request.resource ?? "");
+    const operation = String(request.operation ?? "");
+    if (!controlresources.includes(resource) || !controloperations.includes(operation))
+      throw new TypeError("control request is invalid");
+    const handler = adapters[resource]?.[operation];
+    const context = {
+      requestid: String(request.requestid ?? `control${Date.now().toString(36)}`),
+      resource,
+      operation,
+    };
+    if (typeof handler !== "function")
+      return controlrespond({
+        ok: false,
+        code: "UNSUPPORTED_CONTROL",
+        message: `${resource}.${operation} is not configured`,
+        context,
+        audit,
+      });
+    try {
+      const result = await handler(request.input ?? {}, context);
+      return controlrespond({ ok: true, result, context, audit });
+    } catch (error) {
+      return controlrespond({
+        ok: false,
+        code: String(error?.code ?? "CONTROL_FAILED"),
+        message: controlerrormessage(error),
+        context,
+        audit,
+      });
+    }
+  }
+
+  return {
+    version: 1,
+    resources: [...controlresources],
+    operations: [...controloperations],
+    execute,
+    describe: () => ({
+      version: 1,
+      resources: [...controlresources],
+      configured: Object.keys(adapters).filter((resource) => controlresources.includes(resource)),
+    }),
+  };
+}
+
+/* ════════════════════════════════════════════════════════════════════ */
+/* Section 1: api/auth.ts — api authorization delegates token verification to the caller and never stores credentials. */
+/* ════════════════════════════════════════════════════════════════════ */
+/**
+ * api authorization delegates token verification to the caller and never stores credentials.
+ */
+
+/** Authorizes a request through an injected verifier or returns an anonymous principal. */
+export async function authorize(request, options = {}) {
+  const token = request?.headers?.get?.("authorization")?.replace(/^Bearer\s+/i, "") ?? request?.headers?.get?.("x-api-key");
+  if (typeof options.verify !== "function") return { authenticated: false, subject: "anonymous", tokenpresent: Boolean(token) };
+  if (!token) return { authenticated: false, subject: "anonymous", tokenpresent: false };
+  const principal = await options.verify(token, request);
+  if (!principal) { const error = new Error("request is not authorized"); error.code = "UNAUTHORIZED"; throw error; }
+  return { authenticated: true, subject: String(principal.subject ?? principal.id ?? "caller"), claims: { ...(principal.claims ?? {}) } };
+}
+
+/* ════════════════════════════════════════════════════════════════════ */
+/* Section 2: api/contracts.ts — api contracts keep request identity and success envelopes stable across HTTP and MCP adapters. */
+/* ════════════════════════════════════════════════════════════════════ */
+/**
+ * api contracts keep request identity and success envelopes stable across HTTP and MCP adapters.
+ */
+
+export const apiversion = 1;
+
+/** Extracts a caller supplied request id or creates a local id without exposing secrets. */
+export function requestcontext(request, options = {}) {
+  const requestid = request?.headers?.get?.("x-request-id") ?? options.requestid ?? `request${Date.now().toString(36)}`;
+  return { version: apiversion, requestid: String(requestid), method: request?.method ?? options.method, path: options.path };
+}
+
+/** Creates a versioned success envelope for APIs that opt into envelopes. */
+export function successpayload(data, context = {}) { return { version: apiversion, requestid: String(context.requestid ?? `request${Date.now().toString(36)}`), data }; }
+
+/** Creates a versioned error payload with a stable retry hint. */
+export function errorpayload(code, message, context = {}) { return { version: apiversion, requestid: String(context.requestid ?? `request${Date.now().toString(36)}`), error: { code: String(code), message: String(message), retryafter: Number(context.retryafter ?? 0) } }; }
+
+/* ════════════════════════════════════════════════════════════════════ */
+/* Section 3: api/security.ts — URL security rejects private network targets before a fetch is attempted. */
+/* ════════════════════════════════════════════════════════════════════ */
+/**
+ * URL security rejects private network targets before a fetch is attempted.
+ * DNS resolution remains a host adapter concern and is never performed silently.
+ */
+export function assertpublicurl(value, options = {}) {
+  const url = new URL(value);
+  if (!["http:", "https:"].includes(url.protocol)) throw new TypeError("url protocol is not allowed");
+  if (Array.isArray(options.allowedhosts) && options.allowedhosts.length > 0 && !options.allowedhosts.includes(url.hostname)) throw new Error("url host is not allowed");
+  if (options.allowprivate) return url;
+  if (privatehostname(url.hostname) || privateip(url.hostname)) throw new Error("private network target is not allowed");
+  return url;
+}
+
+/** Checks a resolved address list through a caller supplied DNS resolver to reduce rebinding risk. */
+export async function assertresolvedpublicurl(value, options = {}) {
+  const url = assertpublicurl(value, options);
+  if (typeof options.resolve !== "function" || options.allowprivate) return url;
+  const addresses = await options.resolve(url.hostname);
+  if (!Array.isArray(addresses) || addresses.length === 0) throw new Error("url host did not resolve to an address");
+  for (const address of addresses) if (privateip(String(address)) || privatehostname(String(address))) throw new Error("resolved target is private");
+  return url;
+}
+
+/** Validates a redirect chain as public and bounded before a caller follows it. */
+export function assertredirectchain(values = [], options = {}) {
+  const maxredirects = Number(options.maxredirects ?? 5);
+  if (!Array.isArray(values) || values.length > maxredirects + 1) throw new Error("redirect chain exceeds configured limit");
+  return values.map((value) => assertpublicurl(value, options).href);
+}
+
+/** Returns a non throwing boolean for validators and middleware. */
+export function ispublicurl(value, options = {}) { try { assertpublicurl(value, options); return true; } catch { return false; } }
+
+function privatehostname(hostname) { const value = hostname.toLowerCase().replace(/^\[|\]$/g, "").replace(/\.$/, ""); return value.endsWith(".local") || value.endsWith(".internal") || value.endsWith(".localhost") || value === "localhost" || value === "broadcasthost"; }
+function privateip(hostname) {
+  const normalized = hostname.toLowerCase().replace(/^\[|\]$/g, "");
+  if (normalized === "::1" || normalized.startsWith("fc") || normalized.startsWith("fd") || normalized.startsWith("fe80:") || normalized.startsWith("::ffff:")) return true;
+  const parts = normalized.split(".").map(Number);
+  if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) return false;
+  const [first, second] = parts;
+  return first === 10 || first === 127 || first === 169 && second === 254 || first === 172 && second >= 16 && second <= 31 || first === 192 && second === 168;
+}
+
+/* ════════════════════════════════════════════════════════════════════ */
+/* Section 4: api/rate.ts — token bucket rate limiting supports global user and domain keys. */
+/* ════════════════════════════════════════════════════════════════════ */
+/**
+ * token bucket rate limiting supports global user and domain keys.
+ */
+export function ratebucket(options = {}) {
+  const capacity = options.capacity ?? 10;
+  const refill = options.refill ?? capacity;
+  const interval = options.interval ?? 60000;
+  const buckets = new Map();
+  function consume(key, cost = 1) {
+    const now = Date.now();
+    const previous = buckets.get(key) ?? { tokens: capacity, at: now };
+    const tokens = Math.min(capacity, previous.tokens + ((now - previous.at) / interval) * refill);
+    if (tokens < cost) return { allowed: false, retryafter: Math.ceil(((cost - tokens) / refill) * interval) };
+    buckets.set(key, { tokens: tokens - cost, at: now });
+    return { allowed: true, retryafter: 0 };
+  }
+  return { consume, clear() { buckets.clear(); } };
+}
+
+export function ratelimiter(options = {}) {
+  const global = ratebucket(options.global ?? { capacity: 1000, refill: 1000 });
+  const user = ratebucket(options.user ?? { capacity: 100, refill: 100 });
+  const domain = ratebucket(options.domain ?? { capacity: 10, refill: 10 });
+  return {
+    check(input = {}) {
+      const checks = [[global, "global"], [user, `user:${input.user ?? "anonymous"}`], [domain, `domain:${input.domain ?? "unknown"}`]];
+      for (const [bucket, key] of checks) { const result = bucket.consume(key); if (!result.allowed) return { allowed: false, retryafter: result.retryafter, scope: key }; }
+      return { allowed: true, retryafter: 0 };
+    }
+  };
+}
+
+/* ════════════════════════════════════════════════════════════════════ */
+/* Section 5: api/http.ts — http helpers use the web request response contract and remain framework neutral. */
+/* ════════════════════════════════════════════════════════════════════ */
+/**
+ * http helpers use the web request response contract and remain framework neutral.
+ */
+/** redactstack — the payload boundary of the wire: an Error serializes as its name and message only, and a stack field of any nested object never rides the response. */
+function redactstack(value) {
+  if (value instanceof Error) return { name: value.name, message: value.message };
+  if (Array.isArray(value)) return value.map(redactstack);
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const [key, item] of Object.entries(value)) if (key !== "stack" && key !== "stackTrace") out[key] = redactstack(item);
+    return out;
+  }
+  return value;
+}
+
+export function jsonresponse(data, options = {}) { return new Response(JSON.stringify(redactstack(data)), { status: options.status ?? 200, headers: { "content-type": "application/json; charset=utf-8", "x-content-type-options": "nosniff", "referrer-policy": "no-referrer", ...(options.headers ?? {}) } }); }
+
+/** The failure code a response may carry: the caught value selects from the literal table — an Error object never reaches the wire (its shape answers a known code or the fallback answers), so no stack-derived byte rides the payload the way the exposure gate refused. */
+const responsecode = (error: unknown, fallback: string): string => {
+  const code = (error as { code?: unknown } | null | undefined)?.code;
+  switch (typeof code === "string" ? code : "") {
+    case "UNAUTHORIZED": return "UNAUTHORIZED";
+    case "RATE_LIMITED": return "RATE_LIMITED";
+    case "NOT_FOUND": return "NOT_FOUND";
+    case "METHOD_NOT_ALLOWED": return "METHOD_NOT_ALLOWED";
+    case "REQUEST_FAILED": return "REQUEST_FAILED";
+    case "CONTROL_REQUEST_FAILED": return "CONTROL_REQUEST_FAILED";
+    default: return fallback;
+  }
+};
+
+export function errorresponse(code, message, options = {}) { return jsonresponse({ error: { code, message, retryafter: options.retryafter ?? 0, requestid: options.requestid ?? `request${Date.now().toString(36)}` } }, { status: options.status ?? 400, headers: options.headers }); }
+
+export function sseresponse(events) {
+  const encoder = new TextEncoder();
+  const stream = new ReadableStream({ start(controller) { for (const event of events) controller.enqueue(encoder.encode(`event: ${event.event ?? "message"}\ndata: ${JSON.stringify(event.data ?? {})}\n\n`)); controller.close(); } });
+  return new Response(stream, { headers: { "content-type": "text/event-stream", "cache-control": "no-cache, no-store", connection: "keep-alive", "x-accel-buffering": "no", "x-content-type-options": "nosniff" } });
+}
+
+/* ════════════════════════════════════════════════════════════════════ */
+/* Section 6: api/json.ts — json helpers keep serialization rules explicit at the protocol boundary. */
+/* ════════════════════════════════════════════════════════════════════ */
+/**
+ * json helpers keep serialization rules explicit at the protocol boundary.
+ */
+export function jsonencode(value) { return JSON.stringify(value); }
+export function jsondecode(value) { return JSON.parse(value); }
+
+/* ════════════════════════════════════════════════════════════════════ */
+/* Section 7: api/ndjson.ts — ndjson supports append only records and incremental parsing. */
+/* ════════════════════════════════════════════════════════════════════ */
+/**
+ * ndjson supports append only records and incremental parsing.
+ */
+
+export async function* ndjsonencode(values) { for await (const value of values) yield `${jsonencode(value)}\n`; }
+
+export async function* ndjsondecode(input) {
+  let buffer = "";
+  for await (const chunk of input) {
+    buffer += typeof chunk === "string" ? chunk : new TextDecoder().decode(chunk);
+    const lines = buffer.split(/\r?\n/);
+    buffer = lines.pop() ?? "";
+    for (const line of lines) if (line.trim()) yield jsondecode(line);
+  }
+  if (buffer.trim()) yield jsondecode(buffer);
+}
+
+/* ════════════════════════════════════════════════════════════════════ */
+/* Section 8: api/sse.ts — sse helpers encode typed events without requiring a web framework. */
+/* ════════════════════════════════════════════════════════════════════ */
+/**
+ * sse helpers encode typed events without requiring a web framework.
+ */
+
+export function sseencode(event) {
+  const lines = [];
+  if (event.id !== undefined) lines.push(`id: ${event.id}`);
+  if (event.event) lines.push(`event: ${event.event}`);
+  for (const line of jsonencode(event.data ?? {}).split("\n")) lines.push(`data: ${line}`);
+  return `${lines.join("\n")}\n\n`;
+}
+
+export function ssedecode(chunk) {
+  const fields = {};
+  for (const line of String(chunk).split(/\r?\n/)) {
+    const index = line.indexOf(":");
+    if (index < 0) continue;
+    fields[line.slice(0, index)] = line.slice(index + 1).trimStart();
+  }
+  return { id: fields.id, event: fields.event, data: fields.data ? jsondecode(fields.data) : undefined };
+}
+
+/* ════════════════════════════════════════════════════════════════════ */
+/* Section 9: api/blocks.ts — block streaming yields bounded chunks and lets the consumer control backpressure. */
+/* ════════════════════════════════════════════════════════════════════ */
+/**
+ * block streaming yields bounded chunks and lets the consumer control backpressure.
+ */
+export async function* blockstream(input, options = {}) {
+  const blockbytes = options.blockbytes;
+  if (!Number.isInteger(blockbytes) || blockbytes < 1) throw new TypeError("blockbytes must be a positive integer");
+  let index = 0;
+  let offset = 0;
+  let pending = new Uint8Array(0);
+  for await (const part of input instanceof Uint8Array ? [input] : input) {
+    const data = part instanceof Uint8Array ? part : new TextEncoder().encode(String(part));
+    pending = concat(pending, data);
+    while (pending.byteLength > blockbytes) { const block = pending.slice(0, blockbytes); pending = pending.slice(blockbytes); yield { index, offset, data: block, final: false }; index += 1; offset += block.byteLength; }
+  }
+  if (pending.byteLength) yield { index, offset, data: pending, final: true };
+}
+
+function concat(left, right) { const output = new Uint8Array(left.byteLength + right.byteLength); output.set(left); output.set(right, left.byteLength); return output; }
+
+/* ════════════════════════════════════════════════════════════════════ */
+/* Section 11: api/control.ts — control service exposes operator controls through Web Request and Response without selecting a web framework. */
+/* ════════════════════════════════════════════════════════════════════ */
+/**
+ * control service exposes operator controls through Web Request and Response without selecting a web framework.
+ */
+
+
+/** Creates a framework-neutral HTTP handler for an injected operator control surface. */
+export function controlservice(options = {}) {
+  const controls = options.controls ?? controlsurface({ adapters: options.adapters, audit: options.audit });
+  const path = String(options.path ?? "/v1/control");
+  if (!path.startsWith("/")) throw new TypeError("control service path must be absolute");
+
+  async function handle(request) {
+    const context = requestcontext(request, { path });
+    try {
+      await authorize(request, { verify: options.verify });
+      const url = new URL(request.url ?? request);
+      if (url.pathname !== path) return errorresponse("NOT_FOUND", "control route not found", { status: 404, requestid: context.requestid });
+      if (request.method === "GET") return jsonresponse({ ...controls.describe(), requestid: context.requestid });
+      if (request.method !== "POST") return errorresponse("METHOD_NOT_ALLOWED", "control route requires GET or POST", { status: 405, requestid: context.requestid });
+      const input = typeof request.json === "function" ? await request.json() : {};
+      const result = await controls.execute(input);
+      return jsonresponse({ requestid: context.requestid, data: result }, { status: result.ok ? 200 : 409 });
+    } catch (error) {
+      console.error(error);
+      return errorresponse(responsecode(error, "CONTROL_REQUEST_FAILED"), "control request failed", { status: error?.code === "UNAUTHORIZED" ? 401 : 400, requestid: context.requestid });
+    }
+  }
+
+  return { path, controls, handle };
+}
+
+/* ════════════════════════════════════════════════════════════════════ */
+/* Section 12: api/webhooksignature.ts — webhook signatures use hmac sha256 and keep secrets outside serialized events. */
+/* ════════════════════════════════════════════════════════════════════ */
+/**
+ * webhook signatures use hmac sha256 and keep secrets outside serialized events.
+ */
+
+export function webhooksig(payload, secret) { return hmacsha256(typeof payload === "string" ? payload : JSON.stringify(payload), secret); }
+export function webhookverify(payload, signature, secret) { return constanttimeequal(webhooksig(payload, secret), signature); }
+
+/* ════════════════════════════════════════════════════════════════════ */
+/* Section 13: api/webhookdelivery.ts — webhook delivery tracks attempts and dead letters without choosing a queue vendor. */
+/* ════════════════════════════════════════════════════════════════════ */
+/**
+ * webhook delivery tracks attempts and dead letters without choosing a queue vendor.
+ */
+
+/** Creates a sequential delivery queue with retryable failure handling. */
+export function deliveryqueue(options = {}) {
+  const maxattempts = Number(options.maxattempts ?? 3);
+  const records = new Map();
+  const dead = [];
+  async function deliver(input = {}, handler) {
+    if (typeof handler !== "function") throw new TypeError("delivery handler must be a function");
+    const id = String(input.id ?? `delivery${Date.now().toString(36)}${records.size}`);
+    const record = { id, status: "pending", attempts: 0, createdat: Date.now(), event: input.event, metadata: { ...(input.metadata ?? {}) } };
+    records.set(id, record);
+    while (record.attempts < maxattempts) {
+      record.attempts += 1;
+      try { record.result = await handler(input.event, input); record.status = "delivered"; record.updatedat = Date.now(); return { ...record }; }
+      catch (error) { record.error = { code: String(error.code ?? "DELIVERY_FAILED"), message: String(error.message ?? error), retryable: Boolean(error.retryable) }; if (!error.retryable) break; }
+    }
+    record.status = "dead";
+    dead.push({ ...record });
+    record.updatedat = Date.now();
+    return { ...record };
+  }
+  return { deliver, get(id) { return records.get(String(id)); }, list() { return [...records.values()].map((record) => ({ ...record })); }, deadletters() { return dead.map((record) => ({ ...record })); } };
+}
+
+/* ════════════════════════════════════════════════════════════════════ */
+/* Section 14: api/webhookreceiver.ts — webhook receiver validates signatures before dispatch and drops duplicate delivery ids. */
+/* ════════════════════════════════════════════════════════════════════ */
+/**
+ * webhook receiver validates signatures before dispatch and drops duplicate delivery ids.
+ */
+
+export function webhookreceiver(options = {}) {
+  if (typeof options.secret !== "string" || typeof options.handle !== "function") throw new TypeError("webhook receiver requires secret and handler");
+  const deliveries = new Set();
+  return {
+    async receive(input = {}) {
+      if (!webhookverify(input.body, input.signature, options.secret)) return { accepted: false, status: 401, reason: "invalid signature" };
+      const id = input.deliveryid ?? input.eventid;
+      if (id && deliveries.has(id)) return { accepted: false, status: 200, duplicate: true };
+      if (id) deliveries.add(id);
+      const result = await options.handle(input.event, input.body);
+      return { accepted: true, status: 202, deliveryid: id, result };
+    },
+    deliveries() { return [...deliveries]; }
+  };
+}