@wenathlan/saddle 2.0.162 → 2.0.164

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/distribution.ts

@@ -366,7 +366,20 @@ export async function writeTargetPlan(target: string, format = target, output =
   return filename;
 }
 
-if (process.argv[1]?.endsWith("targetcli.js") || process.argv[1]?.endsWith("targetcli.ts")) {
+/** The cli entry seat: argv[1] only exists under the node runtime — the
+ * family browser bridges import this module through the modes ladder for
+ * the publish contracts, and the raw process.argv[1] read throws at
+ * import time in the browser (the blank-window era of the forge and
+ * foundry seats). the guard answers undefined everywhere but node. */
+const cliseat =
+  typeof process === "object" &&
+  process !== null &&
+  Array.isArray(process.argv) &&
+  typeof process.argv[1] === "string"
+    ? process.argv[1]
+    : undefined;
+
+if (cliseat?.endsWith("targetcli.js") || cliseat?.endsWith("targetcli.ts")) {
   const [, , target = "library", format = target, output = "build/targets"] = process.argv;
   writeTargetPlan(target, format, output).then((filename) => console.log(`target plan: ${filename}`)).catch((error) => { console.error(error.message); process.exitCode = 1; });
 }
@@ -511,7 +524,7 @@ function normalizeupdatedat(value) { const normalized = Number(value ?? 0); if (
 
 function comparefreshness(left, right) { return right.updatedat - left.updatedat || right.bytes - left.bytes || left.name.localeCompare(right.name); }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) createassets(parsearguments(process.argv.slice(2))).then(({ output }) => { console.log(`release assets: ${output}`); }).catch((error) => { console.error(error.message); process.exitCode = 1; });
+if (cliseat !== undefined && cliseat === fileURLToPath(import.meta.url)) createassets(parsearguments(process.argv.slice(2))).then(({ output }) => { console.log(`release assets: ${output}`); }).catch((error) => { console.error(error.message); process.exitCode = 1; });
 
 /* ════════════════════════════════════════════════════════════════════ */
 /* Section 9: release/verify.ts — Release verification checks artifact digests, manifest consistency and */
@@ -613,7 +626,7 @@ function verifyparsearguments(argumentslist) {
   return options;
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) verifyassets(verifyparsearguments(process.argv.slice(2))).then((result) => { console.log(JSON.stringify(result)); }).catch((error) => { console.error(error.message); process.exitCode = 1; });
+if (cliseat !== undefined && cliseat === fileURLToPath(import.meta.url)) verifyassets(verifyparsearguments(process.argv.slice(2))).then((result) => { console.log(JSON.stringify(result)); }).catch((error) => { console.error(error.message); process.exitCode = 1; });
 
 /* ════════════════════════════════════════════════════════════════════ */
 /* Section 10: release/evidence.ts — Release evidence evaluates caller-supplied metadata without fetching, signing, */

package/docs/acceptableusepolicy.md

@@ -0,0 +1,9 @@
+# Saddle acceptable use policy
+
+Copyright (C) 2026 devthink, nathlan, iakadion, nathu filho, allan neris, andraneris, and contributors.
+
+The Saddle source code is licensed under the GNU General Public License version 3.0 only. This policy governs hosted services, credentials, runners and integrations operated with Saddle; it does not reduce rights granted by the GPL.
+
+Operators must use Saddle lawfully, respect the terms of each connected provider, protect credentials, and obtain authorization before accessing systems or data. Operators must not use Saddle to distribute malware, evade access controls, attack third-party systems, violate privacy, infringe intellectual property, or exceed provider quotas.
+
+The project may suspend a hosted integration or reject an unsafe request when necessary to protect users, providers or the public. These operational controls do not restrict lawful use, modification or redistribution of the GPL-licensed software itself.

package/docs/authors.md

@@ -0,0 +1,16 @@
+# Saddle authors
+
+Copyright (C) 2026 devthink, nathlan, iakadion, nathu filho, allan neris, andraneris, and contributors.
+
+The project authors and historical copyright holders are:
+
+| Contributor | Role |
+|---|---|
+| devthink | Historical author and project contributor |
+| nathlan | Project owner and maintainer |
+| iakadion | Historical author and project contributor |
+| nathu filho | Historical author and project contributor |
+| allan neris | Historical author and project contributor |
+| andraneris | Historical author and project contributor |
+
+Saddle is maintained at https://github.com/wenathlan/saddle and distributed under GPL-3.0-only. Contributors retain copyright in their original contributions unless a separate written agreement states otherwise.

package/docs/bugreport.md

@@ -0,0 +1,16 @@
+---
+name: Bug Report
+about: Report a reproducible issue in Saddle
+title: "[BUG]"
+labels: bug
+---
+
+# Saddle is licensed under GPL-3.0-only. Please do not include secrets or private data.
+
+**Describe the issue:**
+
+**File / Line:**
+
+**Expected behavior:**
+
+**Additional context:**

package/docs/cla.md

@@ -0,0 +1,9 @@
+# Saddle contributor terms
+
+Copyright (C) 2026 devthink, nathlan, iakadion, nathu filho, allan neris, andraneris, and contributors.
+
+Saddle does not require an exclusive proprietary assignment of contributions. A contributor submitting a change represents that the contributor has the right to submit it and grants the project the permissions necessary to review, merge, reproduce, distribute and maintain the contribution under GPL-3.0-only.
+
+The contributor keeps copyright in the contribution. The project may include the contribution in source and binary releases under GPL-3.0-only and may preserve attribution and required notices.
+
+If a separate contributor agreement is required for a particular institutional or commercial arrangement, it must be reviewed and accepted in writing before the contribution is merged. This file is not a replacement for legal advice or a bespoke agreement.

package/docs/codeofconduct.md

@@ -0,0 +1,9 @@
+# Saddle code of conduct
+
+Copyright (C) 2026 devthink, nathlan, iakadion, nathu filho, allan neris, andraneris, and contributors.
+
+The Saddle community follows a respectful, inclusive and technically constructive standard. Participants communicate in good faith, explain technical concerns with evidence, respect different backgrounds and experience levels, and protect private information.
+
+Unacceptable conduct includes harassment, discrimination, threats, deliberate disclosure of private information, malicious interference, impersonation, spam, and behavior that violates applicable law or the project policies.
+
+Project maintainers may moderate discussions, remove harmful content, or restrict participation when necessary. Reports should be sent through the repository security or support channels, with private disclosure used for security-sensitive matters.

package/docs/contributing.md

@@ -0,0 +1,9 @@
+# Contributing to Saddle
+
+Copyright (C) 2026 devthink, nathlan, iakadion, nathu filho, allan neris, andraneris, and contributors.
+
+Saddle welcomes contributions that improve the library, its adapters, target builds, documentation, tests and security posture. Contributions are licensed under GPL-3.0-only unless a different compatible arrangement is agreed in writing before acceptance.
+
+A pull request should explain the change, include focused verification, preserve the root-first architecture and avoid credentials, private data or generated artifacts. Security vulnerabilities must use the private process in `SECURITY.md` rather than a public issue.
+
+Maintainers may review, request changes, decline or merge a contribution. No contributor is required to transfer exclusive ownership of their work merely to submit a pull request.

package/docs/copyright.md

@@ -0,0 +1,7 @@
+# Saddle copyright notice
+
+Copyright (C) 2026 devthink, nathlan, iakadion, nathu filho, allan neris, andraneris, and contributors.
+
+The Saddle source code and original documentation are distributed under the GNU General Public License version 3.0 only. The complete license text is kept in the root `LICENSE` file and must be distributed with covered copies.
+
+Copyright ownership remains with the respective authors and contributors. Copyright ownership does not remove the rights granted by GPL-3.0-only. The Saddle name, logos and other marks are covered separately by `trademarkpolicy.md`.

package/docs/disclaimer.md

@@ -0,0 +1,7 @@
+# Saddle disclaimer
+
+Copyright (C) 2026 devthink, nathlan, iakadion, nathu filho, allan neris, andraneris, and contributors.
+
+Saddle is provided under GPL-3.0-only and without warranty to the maximum extent permitted by law. The project does not guarantee availability, correctness, security, compatibility, performance or fitness for a particular purpose.
+
+Operators remain responsible for reviewing source code, configuring integrations, protecting credentials, validating outputs and complying with the terms of connected services. Nothing in this disclaimer removes rights or obligations established by GPL-3.0-only.

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)."