@wenathlan/saddle 2.0.163 → 2.0.165

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]; }
+  };
+}

package/docker.config

@@ -122,6 +122,61 @@
     "nativeBuild": true,
     "note": "the eleven-arch family standard (PR15b: amd64, amd64/v2, arm64, arm/v7, arm/v6, ppc64le, s390x, riscv64, 386, mips64le, loong64 - the complete linux platform surface docker/buildx carries, the owner's law: eleven OS architectures for every container of every application) the one container file and the publish lanes carry; amd64 and amd64/v2 build native, the other nine legs ride QEMU emulation; unknown/* stays rejected as not runnable"
   },
+  "profiles": {
+    "law": "the saddle-exclusive trio (the pr15 exotic law): the only app of the family that ships three container profiles - every profile rides the same engine graph (the same ninety modalities, the same console, the same health surface); only the declared virtual hardware plan differs, and the values mirror the engineplans table the publish matrix stamps",
+    "defaultProfile": "balanced",
+    "variants": [
+      {
+        "id": "max",
+        "target": "max",
+        "tagSuffix": "",
+        "cpu": "epyc9965",
+        "cpuName": "EPYC 9965",
+        "vcpus": 192,
+        "threads": 384,
+        "ramGb": 1024,
+        "gpu": "b200",
+        "gpus": 8,
+        "note": "the full profile catalog: the bare version tag the registry lane answers"
+      },
+      {
+        "id": "balanced",
+        "target": "balanced",
+        "tagSuffix": "-balanced",
+        "cpu": "threadripperpro9995wx",
+        "cpuName": "ThreadRipper PRO 9995WX",
+        "vcpus": 96,
+        "threads": 192,
+        "ramGb": 512,
+        "gpu": "b200",
+        "gpus": 2,
+        "note": "the default target: the last stage of the one container file answers the balanced profile when no --target rides the build"
+      },
+      {
+        "id": "lite",
+        "target": "lite",
+        "tagSuffix": "-lite",
+        "cpu": "ryzen9950x3d",
+        "cpuName": "Ryzen 9950X3D",
+        "vcpus": 16,
+        "threads": 32,
+        "ramGb": 128,
+        "gpu": "rtx5090",
+        "gpus": 1,
+        "note": "the lightest plan: a quarter of the max envelope, the -lite suffix tag the registry lane answers"
+      }
+    ],
+    "envStamp": [
+      "SADDLE_PROFILE",
+      "SADDLE_PROFILE_CPU",
+      "SADDLE_PROFILE_VCPUS",
+      "SADDLE_PROFILE_THREADS",
+      "SADDLE_PROFILE_RAM_GB",
+      "SADDLE_PROFILE_GPU",
+      "SADDLE_PROFILE_GPUS"
+    ],
+    "sourceOfTruth": "saddle/engineplans.ts (the plan values), saddle/Dockerfile (the variant targets), the saddle-vhe publish matrix of .github/workflows/publish.yml (the registry legs)"
+  },
   "runtimeBase": {
     "nodeImage": "node:26.7.0-alpine",
     "nodeAlt": "node:24.19.0-alpine",

package/docs/distributionlanes.md

@@ -0,0 +1,19 @@
+# Distribution lanes
+
+The eleven distribution lanes of the PR14 law and the honest status each lane answers for saddle at the 2.0.163 family rung. A lane never ships metadata its real surface cannot back: a lane without a real carrier stays a documented stub until the surface lands, and no version ever bumps to fake a lane.
+
+| Lane | Carrier | Status | Note |
+| --- | --- | --- | --- |
+| npmjs | package.json — @wenathlan/saddle | live | the family-npmjs lane publishes the engine envelope (the heaviest pass, always last) |
+| GitHub Packages npm | package.json — @wenathlan/saddle | live | the family-githubnpm lane publishes the same envelope idempotently |
+| Maven | pom.xml — io.github.wenathlan:saddle | live | the family-maven lane deploys the one real jar of the family (the Saddle.java adapter) |
+| NuGet | saddle.csproj | live | the family-nuget lane packs the engine envelope |
+| Gradle | build.gradle.kts — com.wenathlan:saddle | live | the family-gradle lane publishes the module beside the maven coordinates |
+| Ruby Gems | saddle.gemspec | live | the family-rubygems lane pushes the gem carrying the SaddleCli.rb process adapter |
+| Docker Container | Dockerfile | live | the saddle-container lane attaches the engine archive and the vhe lanes publish the max / balanced / lite profile indexes under the eleven-architecture standard of containerarch.ts |
+| Go Get | go.mod | stub | no Go source surface ships yet — the lane lands when a real Go adapter exists, never as an empty module |
+| Cargo Crates | Cargo.toml | stub | no Rust source surface ships yet — the lane lands with a real crate, never as an empty manifest (the tauri rust envelope stays runner-side toolchain output) |
+| PyPi | pyproject.toml | stub | no Python package surface ships yet — the qemubridge.py helper is a bridge script, not a wheel surface; the lane lands with a real package, never as an empty project table |
+| Homebrew | Formula | stub | no tap repository ships yet — the formula lands pointing at the real release binaries with real checksums, never at a placeholder |
+
+The engines block of package.json keeps Go, Rust and Python as declared toolchain floors — a catalog row is not a distribution lane. The dual npm law answers through the npmjs and GitHub Packages rows; the release binaries (the desktop bundles, the mobile artifacts, the vhe container archives) ride the family-desktop, family-mobile and saddle-container lanes every release rung.

package/docs/doc.go

@@ -0,0 +1,25 @@
+// Package docs carries the go module identity of the saddle engine
+// envelope — the binary computing engine that turns distributed storage
+// into a publishable working set, carrying the merged virtual-hardware
+// engine.
+//
+// The goget wave seats the go module rung beside the maven, nuget,
+// rubygems and gradle rungs: the module resolves at
+// github.com/wenathlan/devthink/saddle/v2 through the
+// proxy.golang.org chain, and the version answers the per-module tag
+// (saddle/vX.Y.Z on the release commit) the publish lane syncs — the
+// package carries no version constant the metadata lockstep would have
+// to stamp, the same way the gradle marker reads the envelope
+// package.json at build time. The identity carrier rides the
+// documentation support seat because the app root carries the C engine
+// sources the go package law refuses beside a package.
+package docs
+
+// ModulePath is the go module path the go get consumer resolves.
+const ModulePath = "github.com/wenathlan/devthink/saddle/v2"
+
+// Family is the distribution family every envelope of the monorepo answers.
+const Family = "wenathlan"
+
+// Description is the envelope summary the registry metadata carries.
+const Description = "The saddle engine envelope (the binary computing engine carrying the merged virtual-hardware engine)."

package/docs/ninetymodalities.md

@@ -189,3 +189,11 @@ os → grapheneos, omashi → omarchy, linux normal → linux. the owner's "v"
 names no guest os: it answers the language-v lane of the modality
 registry (the v compiler seat). nothing to add — the vocabulary already
 covers every name the owner used.
+
+the container side of the same law rides its own registry: the
+OSDISTRIBUTIONS catalog of saddle/containerarch.ts (section 1c) carries
+the seven system seats the saddle container starts its distribution with
+— grapheneos, omarchy, vanilla os, maru os, the v seat, the normal linux
+baseline and android — with the arch pairings, the engine plan trio
+binding and the plan-resource law. see
+[osdistributions.md](osdistributions.md) for the record.