@wenathlan/saddle 2.0.163 → 2.0.165

package/docs/osdistributions.md

@@ -0,0 +1,149 @@
+# os.distributions — the seven system seats the saddle container carries
+
+> the owner order (pr15, verbatim): "iniciar distribuição do container
+> saddle com por exemplo, grapheneos, omarchy e outros sistemas dentro do
+> saddle" — the saddle container starts its distribution catalog with
+> grapheneos, omarchy and the other systems inside the saddle. and:
+> "saddle também vira com outras distribuições de sistema operacional
+> além de linux como por exemplo, maru os is firmware not an application
+> / vanilla os is based on ubuntu / v / omarchy is arch linux-based
+> distribution created by dhh / grapheneos is a privacy and security
+> hardened version of android / linux normal / max / lite / balanced /
+> android / arm64 / amd64 / vgpu / vcpu / por exemplo, 50gb por plano
+> via config."
+
+## the registry
+
+`saddle/containerarch.ts` — the file that already owned the
+eleven-architecture standard and the build architecture table — now
+carries the os distribution catalog beside them (section 1c of the
+file): one honest row per system seat, pure data and pure functions,
+frozen at module load, zero storage, zero node-only imports (the one
+import it takes — `engineplans.ts` — is itself pure data).
+
+| seat | kind | base (the true fact) | package | arch pairing | legs | tiers |
+| --- | --- | --- | --- | --- | --- | --- |
+| grapheneos | mobile | android | apk | linux-arm64, darwin-arm64-v8 | arm64 | max/balanced/lite |
+| omarchy | desktop | arch linux | pacman | linux-x64, linux-x64-musl, linux-arm64 | amd64+arm64 | max/balanced/lite |
+| vanillaos | distribution | ubuntu | apt | linux-x64, linux-x64-musl, linux-arm64 | amd64+arm64 | max/balanced/lite |
+| maruos | firmware | android firmware with a debian desktop | abuild | linux-arm64, darwin-arm64-v8 | arm64 | max/balanced/lite |
+| v | languageos | the v language platform (vlang, the 0.5.2 catalog seat) | vpm | linux-x64, linux-arm64, darwin-arm64, darwin-x64, windows-x64, wasm32 | amd64+arm64 | max/balanced/lite |
+| linux | distribution | the plain linux baseline the engine container rides | apt | linux-x64, linux-x64-musl, linux-arm64, linux-riscv64 | amd64+arm64+riscv64 | max/balanced/lite |
+| android | mobile | the android application platform | apk | linux-arm64, darwin-arm64-v8 | arm64 | max/balanced/lite |
+
+the true facts the owner's law pins, verbatim in the rows' notes:
+
+- **grapheneos** is a privacy and security hardened version of android
+  (the hardened mobile seat, the apk grammar, the arm64 legs).
+- **omarchy** is the arch linux-based distribution created by dhh (the
+  desktop seat, the pacman grammar, the amd64 and arm64 legs).
+- **vanilla os** is based on ubuntu (the atomic desktop seat beside the
+  plain linux baseline).
+- **maru os** is firmware, not an application (the catalog carries the
+  seat honestly, the engine never installs it as a guest application —
+  it rides no vgpu path).
+- **v** names the v language platform the dependency catalog pins at
+  0.5.2 (`package.json` carries `"v": "^0.5.2"`), never a guest
+  distribution — the languagev compiler seat of the ninety modalities
+  answers it (the owner's nickname law, the same law
+  `docs/ninetymodalities.md` records).
+- **linux** is the normal baseline: the default distribution the saddle
+  container itself rides (the resolver's default), every linux seat the
+  standard carries answers it.
+- **android** is the mobile platform the grapheneos hardening builds on.
+
+## the pairings (real joins, never duplicated lists)
+
+- the **arch pairing**: every `archs` entry of every row is a real seat
+  id of the eleven-architecture standard (`CONTAINERARCHIDS` — the
+  tests assert it, never an invented seat id). the legs column is not
+  stored data: `osdistributiondockerarchs(id)` derives the amd64/arm64
+  docker legs by joining the row's pairings against the carried seats
+  of `CONTAINERARCHES` (the target seats the v row pairs contribute no
+  leg — the binary and npm lanes own them).
+- the **tier binding**: every seat binds the full max/balanced/lite
+  engine plan trio, and the trio itself is derived from
+  `ENGINEPLANS.map((row) => row.id)` — the ids stay the engineplans
+  table's own, never a duplicated tier list. the tier axis scales the
+  virtual hardware plan, never the catalog: the tier and the seat stay
+  orthogonal, exactly like the sandbox bases (`SANDBOXBASES`) stay
+  orthogonal to the guest os ids.
+- the **virtual device law** (vgpu/vcpu): `vgpu` and `vcpu` are law
+  fields, not caps — vgpu marks the seats that present a virtual gpu
+  path (false for the firmware seat and the language seat), vcpu pins
+  that every seat rides the engine's virtual cpu bank. the counts
+  arrive from the engine plan profile, never from the catalog.
+
+## the plan-resource law (config, never a cap)
+
+the owner's law: "por exemplo, 50gb por plano via config". the
+`OSDISTRIBUTIONPLANLAW` row carries it as data:
+
+- `examplestoragegb: 50` — the example per-plan storage quota, plan
+  config data a plan row stamps;
+- `quotaowner: "devthink"` — the devthink system plan logic owns every
+  quota;
+- `enginelimits: ENGINELIMITS` — the engineplans limits law rides the
+  row verbatim (the reuse law): unlimited workloads, unlimited
+  sessions, unlimited modalities, unlimited artifacts.
+
+no row of the catalog carries a numeric resource field — the tests scan
+every field of every row and fail on any number. the 50 gb is plan
+config, the engine is unlimited, and the catalog never bakes a ceiling
+(an engine limit would be a product decision wearing an engine costume
+— the same law `docs/planningengine.md` and `engineplans.ts` record).
+
+## the consumable surface (what the container and the modality system read)
+
+`containerarch.ts` exports the catalog the same way it exports the
+arch standard:
+
+- `OSDISTRIBUTIONIDS`, `OSDISTRIBUTIONS`, `OSDISTRIBUTIONCOUNT` — the
+  catalog rows (the publish matrix and the modality seats read the ids);
+- `OSDISTRIBUTIONPROFILEIDS` — the derived engine plan trio (the tier
+  binding);
+- `OSDISTRIBUTIONPLANLAW` — the plan-resource law of record;
+- `getosdistribution`, `resolveosdistribution`, `osdistributionerror`
+  — the resolver (undefined/null answers the linux row, a known id
+  answers its row, anything else throws the coded
+  `OS_DISTRIBUTION_UNKNOWN` refusal naming the seven seats);
+- `osdistributionsforarch`, `osdistributionsforprofile` — the joins the
+  modality system reads (which seats ride one arch seat; which seats
+  ride one tier — an unknown tier throws
+  `OS_DISTRIBUTION_PROFILE_UNKNOWN`);
+- `osdistributiondockerarchs` — the derived docker legs (amd64, arm64,
+  riscv64) the container matrix reads;
+- `osdistributioncoverage`, `osdistributionlines` — the honest coverage
+  report and the rendered table lines the container lanes stamp on
+  every profile run.
+
+## the build wiring (why no new build legs)
+
+the distribution seats ride the arch axis the pinned base already
+resolves: the mobile and firmware seats ride the arm64 legs, the
+desktop and baseline seats ride the amd64 and arm64 legs — the same
+legs the eleven-architecture standard carries. the dockerfile documents
+the law (the `THE OS DISTRIBUTION SEATS` paragraph) and the publish
+lanes stay untouched: no per-os build matrix exists or is needed, the
+container itself keeps riding the normal linux baseline (the container
+lane law) and the seven seats are the catalog the modality system hosts
+inside the engine, never host distributions the container installs.
+
+## the visitor law (the critical law)
+
+every system seat of the catalog is a hosted GUEST the engine drives on
+its own twenty-four hour internet infrastructure — the catalog never
+describes the visitor machine (no visitor gpu, no visitor cpu, no
+visitor browser, no visitor local storage, no localforage). the engine
+owns every cycle it spends through saddle and vault edge processing.
+
+## the pinning battery
+
+`saddle/tests/osdistrib.test.ts` (eight tests, green): the seven seats
+in law order, the true facts verbatim, the arch pairing honesty (every
+pairing a real seat of the standard, the derived legs per seat), the
+tier binding reused from engineplans (the deep-equality against
+`ENGINEPLANS.map`), the plan-resource law (50 as plan config, the
+engine unlimited, zero numeric fields in the rows), the resolver (the
+linux default, the coded refusals), the arch and profile joins, and the
+coverage report plus the rendered lines.

package/integration.ts

@@ -0,0 +1,221 @@
+/**
+ * integration.ts — replaceable forge, application, MCP and transport adapters.
+ *
+ * This file is the v2.0.0 grand-merge consolidation of the former nested
+ * folders of the repository (adapters) 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 { jsondecode, jsonencode } from "./communication.ts";
+
+/* ════════════════════════════════════════════════════════════════════ */
+/* Section 1: adapters/transport.ts — transport centralizes timeout retry and jitter without choosing a host or vendor. */
+/* ════════════════════════════════════════════════════════════════════ */
+/**
+ * transport centralizes timeout retry and jitter without choosing a host or vendor.
+ */
+export function transport(options = {}) {
+  const fetcher = options.fetcher ?? fetch;
+  const attempts = options.attempts ?? 3;
+  const timeout = options.timeout ?? 30000;
+  const retrycodes = new Set(options.retrycodes ?? [408, 409, 429, 500, 502, 503, 504]);
+  async function request(url, init = {}) {
+    let last;
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeout);
+      try {
+        const response = await fetcher(url, { ...init, signal: init.signal ?? controller.signal });
+        if (response.ok || !retrycodes.has(response.status) || attempt === attempts - 1) return response;
+        last = new Error(`request failed with ${response.status}`);
+      } catch (error) {
+        last = error;
+        if (attempt === attempts - 1) throw error;
+      } finally { clearTimeout(timer); }
+      await delay(backoff(options, attempt));
+    }
+    throw last ?? new Error("request failed");
+  }
+  return { request };
+}
+
+function backoff(options, attempt) { const base = options.backoff ?? 250; const jitter = options.jitter ?? 0; return base * 2 ** attempt + Math.floor(Math.random() * jitter); }
+function delay(milliseconds) { return new Promise((resolve) => setTimeout(resolve, milliseconds)); }
+
+/* ════════════════════════════════════════════════════════════════════ */
+/* Section 2: adapters/socket.ts — socket adapter keeps realtime optional and accepts a caller supplied websocket constructor. */
+/* ════════════════════════════════════════════════════════════════════ */
+/**
+ * socket adapter keeps realtime optional and accepts a caller supplied websocket constructor.
+ */
+export function socketadapter(options = {}) {
+  const websocket = options.websocket ?? globalThis.WebSocket;
+  if (!websocket) throw new Error("websocket implementation is required");
+  return {
+    connect(url, protocols) {
+      if (!url) throw new TypeError("socket url is required");
+      const socket = new websocket(url, protocols);
+      return { socket, send(value) { socket.send(typeof value === "string" ? value : JSON.stringify(value)); }, close(code, reason) { socket.close(code, reason); } };
+    }
+  };
+}
+
+/* ════════════════════════════════════════════════════════════════════ */
+/* Section 3: adapters/github.ts — github adapter uses caller supplied credentials and base url configuration. */
+/* ════════════════════════════════════════════════════════════════════ */
+/**
+ * github adapter uses caller supplied credentials and base url configuration.
+ */
+
+export function githubadapter(options = {}) {
+  if (!options.baseurl || typeof options.token !== "function") throw new TypeError("github adapter requires baseurl and token function");
+  const client = transport({ fetcher: options.fetcher, attempts: options.attempts, timeout: options.timeout });
+  async function call(path, init = {}) {
+    const token = await options.token();
+    const headers = { accept: "application/vnd.github+json", authorization: `Bearer ${token}`, "x-github-api-version": options.apiversion ?? "2022-11-28", ...(init.headers ?? {}) };
+    return client.request(new URL(path, options.baseurl), { ...init, headers });
+  }
+  return {
+    async health() { const response = await call("/rate_limit"); return { ok: response.ok, status: response.status }; },
+    async dispatch(owner, repository, workflow, input = {}) { const response = await call(`/repos/${owner}/${repository}/actions/workflows/${workflow}/dispatches`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ ref: input.ref ?? "main", inputs: input.inputs ?? {} }) }); return { accepted: response.status === 204, status: response.status }; },
+    async run(owner, repository, runid) { const response = await call(`/repos/${owner}/${repository}/actions/runs/${runid}`); return response.json(); }
+  };
+}
+
+/* ════════════════════════════════════════════════════════════════════ */
+/* Section 4: adapters/gitlab.ts — gitlab adapter keeps project addressing and token ownership outside the package. */
+/* ════════════════════════════════════════════════════════════════════ */
+/**
+ * gitlab adapter keeps project addressing and token ownership outside the package.
+ */
+
+export function gitlabadapter(options = {}) {
+  const project = encodeURIComponent(options.project ?? "");
+  const base = forgeadapter({ ...options, kind: "gitlab" });
+  return { ...base, async dispatch(spec) { return base.dispatch({ ...spec, path: spec.path ?? `/api/v4/projects/${project}/pipeline` }); } };
+}
+
+/* ════════════════════════════════════════════════════════════════════ */
+/* Section 5: adapters/forge.ts — forge adapter defines the common dispatch and artifact surface for compatible forges. */
+/* ════════════════════════════════════════════════════════════════════ */
+/**
+ * forge adapter defines the common dispatch and artifact surface for compatible forges.
+ */
+
+export function forgeadapter(options = {}) {
+  if (!options.baseurl || typeof options.token !== "function") throw new TypeError("forge adapter requires baseurl and token function");
+  const client = transport({ fetcher: options.fetcher, attempts: options.attempts, timeout: options.timeout });
+  async function call(path, init = {}) { const token = await options.token(); return client.request(new URL(path, options.baseurl), { ...init, headers: { authorization: `Bearer ${token}`, accept: "application/json", ...(init.headers ?? {}) } }); }
+  return {
+    kind: options.kind ?? "forge",
+    async health(path = "/") { const response = await call(path); return { ok: response.ok, status: response.status }; },
+    async dispatch(spec) { if (!spec?.path || !spec.ref) throw new TypeError("forge dispatch requires path and ref"); const response = await call(spec.path, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ ref: spec.ref, inputs: spec.inputs ?? {} }) }); return { accepted: response.ok, status: response.status, body: response.json ? await response.json() : undefined }; },
+    async upload(spec) { if (!spec?.path || !spec.data) throw new TypeError("forge upload requires path and data"); const response = await call(spec.path, { method: "PUT", headers: { "content-type": spec.contenttype ?? "application/octet-stream" }, body: spec.data }); return { accepted: response.ok, status: response.status }; }
+  };
+}
+
+/* ════════════════════════════════════════════════════════════════════ */
+/* Section 6: adapters/forgejo.ts — forgejo and gitea can reuse the open forge contract with a caller supplied base url. */
+/* ════════════════════════════════════════════════════════════════════ */
+/**
+ * forgejo and gitea can reuse the open forge contract with a caller supplied base url.
+ */
+
+export function forgejoadapter(options = {}) { return forgeadapter({ ...options, kind: "forgejo" }); }
+export function giteaadapter(options = {}) { return forgeadapter({ ...options, kind: "gitea" }); }
+export function codebergadapter(options = {}) { return forgeadapter({ ...options, kind: "codeberg" }); }
+
+/* ════════════════════════════════════════════════════════════════════ */
+/* Section 7: adapters/huggingface.ts — hugging face storage remains an explicit adapter with caller supplied repository path. */
+/* ════════════════════════════════════════════════════════════════════ */
+/**
+ * hugging face storage remains an explicit adapter with caller supplied repository path.
+ */
+
+export function huggingfaceadapter(options = {}) { return forgeadapter({ ...options, kind: "huggingface" }); }
+
+/* ════════════════════════════════════════════════════════════════════ */
+/* Section 8: adapters/apps.ts — app registry keeps installation, scope and revocation state outside platform credentials. */
+/* ════════════════════════════════════════════════════════════════════ */
+/**
+ * app registry keeps installation, scope and revocation state outside platform credentials.
+ */
+
+export const appstatuses = Object.freeze(["installed", "suspended", "revoked"]);
+
+/** Creates a caller-owned app installation registry with explicit scopes. */
+export function appregistry(options = {}) {
+  const values = new Map(options.apps ? options.apps.map((app) => [app.id, normalize(app)]) : []);
+  function install(input = {}) { if (!input.id || !input.name) throw new TypeError("app installation requires id and name"); const app = normalize({ ...input, status: "installed", installedat: input.installedat ?? Date.now() }); values.set(app.id, app); return { ...app, scopes: [...app.scopes] }; }
+  function suspend(id) { return transition(id, "suspended"); }
+  function revoke(id) { return transition(id, "revoked"); }
+  function restore(id) { return transition(id, "installed"); }
+  function authorize(id, required = []) { const app = requireapp(id); if (app.status !== "installed") return { allowed: false, reason: `app-${app.status}` }; const missing = required.filter((scope) => !app.scopes.includes(scope)); return { allowed: missing.length === 0, missing, appid: app.id }; }
+  function get(id) { const app = values.get(String(id)); return app ? { ...app, scopes: [...app.scopes] } : null; }
+  function list() { return [...values.values()].map((app) => ({ ...app, scopes: [...app.scopes] })); }
+  return { install, suspend, revoke, restore, authorize, get, list };
+  function requireapp(id) { const app = values.get(String(id)); if (!app) throw new Error(`app not found: ${id}`); return app; }
+  function transition(id, status) { const app = requireapp(id); if (!appstatuses.includes(status)) throw new TypeError(`unsupported app status: ${status}`); app.status = status; app.updatedat = Date.now(); return get(id); }
+}
+
+function normalize(input) { return { id: String(input.id), name: String(input.name), status: input.status ?? "installed", scopes: [...new Set((input.scopes ?? []).map(String))], installedat: Number(input.installedat ?? Date.now()), updatedat: Number(input.updatedat ?? Date.now()), metadata: { ...(input.metadata ?? {}) } }; }
+
+/* ════════════════════════════════════════════════════════════════════ */
+/* Section 9: adapters/mcptransport.ts — mcp transport keeps JSON RPC framing separate from the tool server. */
+/* ════════════════════════════════════════════════════════════════════ */
+/**
+ * mcp transport keeps JSON RPC framing separate from the tool server.
+ */
+
+/** Creates JSONL and HTTP handlers for the transport agnostic MCP server. */
+export function mcptransport(server) {
+  if (typeof server?.handle !== "function") throw new TypeError("mcp transport requires server");
+  return {
+    async handleline(line) { const request = jsondecode(line); return jsonencode(await server.handle(request)); },
+    async *stream(lines) { for await (const line of lines) if (String(line).trim()) yield await this.handleline(line); },
+    async handlehttp(request) { const body = await request.text(); const response = await server.handle(jsondecode(body)); return new Response(jsonencode(response), { status: 200, headers: { "content-type": "application/json" } }); }
+  };
+}
+
+/* ════════════════════════════════════════════════════════════════════ */
+/* Section 10: adapters/mcpserver.ts — mcp server implements a small JSON RPC tool surface and remains transport agnostic. */
+/* ════════════════════════════════════════════════════════════════════ */
+/**
+ * mcp server implements a small JSON RPC tool surface and remains transport agnostic.
+ */
+
+export function mcpserver(options = {}) {
+  const tools = {
+    serialize: async (input) => jsonencode(input.value),
+    ...(options.browser ? browsertools(options.browser) : {}),
+    ...(options.tools ?? {})
+  };
+  return {
+    listtools() { return Object.keys(tools).map((name) => ({ name, description: `saddle ${name} tool` })); },
+    async handle(request) {
+      if (request.method === "tools/list") return { jsonrpc: "2.0", id: request.id, result: { tools: this.listtools() } };
+      if (request.method === "tools/call") { const handler = tools[request.params?.name]; if (!handler) return { jsonrpc: "2.0", id: request.id, error: { code: -32601, message: "tool not found" } }; try { return { jsonrpc: "2.0", id: request.id, result: { content: [{ type: "text", text: JSON.stringify(await handler(request.params.arguments ?? {})) }] } }; } catch (error) { return { jsonrpc: "2.0", id: request.id, error: { code: -32000, message: error.message } }; } }
+      return { jsonrpc: "2.0", id: request.id, error: { code: -32601, message: "method not found" } };
+    }
+  };
+}
+
+/* ════════════════════════════════════════════════════════════════════ */
+/* Section 11: adapters/mcpbrowser.ts — browser MCP tools expose snapshots and actions only through an injected browser adapter. */
+/* ════════════════════════════════════════════════════════════════════ */
+/**
+ * browser MCP tools expose snapshots and actions only through an injected browser adapter.
+ */
+
+/** Creates optional browser tools for an MCP server without selecting Playwright or another vendor. */
+export function browsertools(browser) {
+  if (typeof browser?.snapshot !== "function" || typeof browser?.action !== "function") throw new TypeError("browser MCP tools require snapshot and action");
+  return {
+    browser_snapshot: async (input = {}) => browser.snapshot(input),
+    browser_action: async (input = {}) => browser.action(input)
+  };
+}