@wenathlan/saddle 1.8.1

package/storage/adapter.js

@@ -0,0 +1,8 @@
+/**
+ * storage adapters keep remote services out of the engine core.
+ */
+export function storageadapter(methods) {
+  const required = ["put", "get", "head", "delete", "list"];
+  for (const name of required) if (typeof methods?.[name] !== "function") throw new TypeError(`storage adapter requires ${name}`);
+  return methods;
+}

package/storage/cache.js

@@ -0,0 +1,54 @@
+/**
+ * tiered cache keeps a bounded hot tier and an optional persistent cold tier with stale-while-revalidate.
+ */
+
+/** Creates a cache with caller supplied encode, decode, clock and persistent storage policies. */
+export function tieredcache(options = {}) {
+  const hot = new Map();
+  const maxentries = Number(options.maxentries ?? 256);
+  const ttl = Number(options.ttl ?? 300000);
+  const stale = Number(options.stale ?? ttl);
+  const now = options.now ?? (() => Date.now());
+  const cold = options.storage;
+  const encode = options.encode ?? ((value) => new TextEncoder().encode(JSON.stringify(value)));
+  const decode = options.decode ?? ((bytes) => JSON.parse(new TextDecoder().decode(bytes)));
+  const stats = { hits: 0, misses: 0, stalehits: 0, evictions: 0, revalidations: 0 };
+
+  function readhot(key) {
+    const item = hot.get(key);
+    if (!item) return null;
+    const current = now();
+    if (current <= item.expires) { stats.hits += 1; return { value: item.value, fresh: true }; }
+    if (current <= item.stale) { stats.stalehits += 1; return { value: item.value, fresh: false }; }
+    hot.delete(key);
+    return null;
+  }
+
+  function writehot(key, value, options = {}) {
+    if (hot.size >= maxentries && !hot.has(key)) { hot.delete(hot.keys().next().value); stats.evictions += 1; }
+    const current = now();
+    hot.set(key, { value, expires: current + Number(options.ttl ?? ttl), stale: current + Number(options.stale ?? stale) });
+    return value;
+  }
+
+  async function get(key, options = {}) {
+    const hotvalue = readhot(key);
+    if (hotvalue?.fresh || (hotvalue && options.allowstale !== false)) return hotvalue.value;
+    if (!cold) { stats.misses += 1; return null; }
+    try { const value = decode(await cold.get(key)); writehot(key, value, options); return value; } catch { stats.misses += 1; return null; }
+  }
+
+  async function set(key, value, valueoptions = {}) { writehot(key, value, valueoptions); if (cold) await cold.put({ key, data: encode(value), contenttype: "application/json" }); return value; }
+  async function getorload(key, loader, options = {}) {
+    if (typeof loader !== "function") throw new TypeError("cache loader must be a function");
+    const current = readhot(key);
+    if (current?.fresh) return current.value;
+    if (current && options.allowstale !== false) { stats.revalidations += 1; Promise.resolve(loader()).then((value) => set(key, value, options)).catch(() => undefined); return current.value; }
+    const value = await loader();
+    return set(key, value, options);
+  }
+  async function remove(key) { hot.delete(key); await cold?.delete?.(key); }
+  function clear() { hot.clear(); }
+  function inspect() { return { ...stats, hotentries: hot.size, maxentries, ttl, stale }; }
+  return { get, set, getorload, delete: remove, clear, inspect };
+}

package/storage/checksum.js

@@ -0,0 +1,17 @@
+/**
+ * byte collection and hashing are grouped because every storage adapter uses them.
+ */
+import { sha256 } from "../core/hash.js";
+
+export { sha256 } from "../core/hash.js";
+
+export async function collectbytes(input) {
+  if (input instanceof Uint8Array) return input;
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of input) { chunks.push(chunk); size += chunk.byteLength; }
+  const output = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) { output.set(chunk, offset); offset += chunk.byteLength; }
+  return output;
+}

package/storage/chunked.js

@@ -0,0 +1,58 @@
+/**
+ * chunked storage keeps large payloads split without forcing a database blob.
+ */
+import { collectbytes, sha256 } from "./checksum.js";
+
+export function chunkedstorage(storage, options = {}) {
+  const chunkbytes = options.chunkbytes;
+  if (!Number.isInteger(chunkbytes) || chunkbytes < 1) throw new TypeError("chunkbytes must be a positive integer");
+  return {
+    async put(input) {
+      const data = await collectbytes(input.data);
+      const chunks = [];
+      for (let offset = 0; offset < data.byteLength; offset += chunkbytes) {
+        const index = chunks.length;
+        const key = `${input.key}/chunk${String(index).padStart(8, "0")}`;
+        const part = data.slice(offset, Math.min(offset + chunkbytes, data.byteLength));
+        const manifest = await storage.put({ key, data: part, contenttype: input.contenttype, metadata: { parent: input.key, index: String(index) } });
+        chunks.push({ key, sizebytes: part.byteLength, sha256: manifest.sha256 });
+      }
+      const manifest = { version: 1, key: input.key, sizebytes: data.byteLength, chunks, chunkbytes, sha256: sha256(data), contenttype: input.contenttype ?? "application/octet-stream", status: "complete", completed: chunks.length, updatedat: Date.now(), metadata: { ...(input.metadata ?? {}) } };
+      await storage.put({ key: `${input.key}/manifest`, data: new TextEncoder().encode(JSON.stringify(manifest)), contenttype: "application/json" });
+      return manifest;
+    },
+    async get(key) {
+      const raw = await storage.get(`${key}/manifest`);
+      const manifest = JSON.parse(new TextDecoder().decode(raw));
+      const parts = await Promise.all(manifest.chunks.map((chunk) => storage.get(chunk.key)));
+      const output = new Uint8Array(manifest.sizebytes);
+      let offset = 0;
+      for (const part of parts) { output.set(part, offset); offset += part.byteLength; }
+      return output;
+    },
+    async getrange(key, start = 0, end) {
+      const manifest = await this.head(key);
+      if (!manifest) throw new Error(`chunk manifest not found: ${key}`);
+      const from = Math.max(0, Number(start));
+      const to = Math.min(manifest.sizebytes, end === undefined ? manifest.sizebytes : Number(end));
+      if (!Number.isInteger(from) || !Number.isInteger(to) || from > to) throw new TypeError("chunk range is invalid");
+      if (from === to) return new Uint8Array();
+      const first = Math.floor(from / manifest.chunkbytes);
+      const last = Math.ceil(to / manifest.chunkbytes) - 1;
+      const parts = await Promise.all(manifest.chunks.slice(first, last + 1).map((chunk) => storage.get(chunk.key)));
+      const output = new Uint8Array(to - from);
+      let offset = 0;
+      for (let index = 0; index < parts.length; index += 1) {
+        const chunkstart = (first + index) * manifest.chunkbytes;
+        const begin = Math.max(from, chunkstart);
+        const finish = Math.min(to, chunkstart + parts[index].byteLength);
+        output.set(parts[index].slice(begin - chunkstart, finish - chunkstart), offset);
+        offset += finish - begin;
+      }
+      return output;
+    },
+    async head(key) { const raw = await storage.get(`${key}/manifest`).catch(() => null); return raw ? JSON.parse(new TextDecoder().decode(raw)) : null; },
+    async delete(key) { const manifest = await this.head(key); if (!manifest) return; for (const chunk of manifest.chunks) await storage.delete(chunk.key); await storage.delete(`${key}/manifest`); },
+    async list(prefix) { return storage.list(prefix); }
+  };
+}

package/storage/content.js

@@ -0,0 +1,42 @@
+/**
+ * content addressed storage deduplicates immutable bytes while keeping logical references separate.
+ */
+
+import { collectbytes, sha256 } from "./checksum.js";
+
+/** Creates a content-addressed view over a caller supplied storage adapter. */
+export function contentstorage(storage, options = {}) {
+  const objectprefix = options.objectprefix ?? "objects";
+  const refprefix = options.refprefix ?? "refs";
+  const encode = options.encode ?? ((value) => new TextEncoder().encode(JSON.stringify(value)));
+  const decode = options.decode ?? ((bytes) => JSON.parse(new TextDecoder().decode(bytes)));
+  if (typeof storage?.put !== "function" || typeof storage?.get !== "function" || typeof storage?.head !== "function") throw new TypeError("content storage requires put, get and head");
+
+  async function put(input = {}) {
+    const data = await collectbytes(input.data);
+    const digest = sha256(data);
+    const objectkey = `${objectprefix}/${digest}`;
+    if (!(await storage.head(objectkey))) await storage.put({ key: objectkey, data, contenttype: input.contenttype, metadata: { ...(input.metadata ?? {}), immutable: "true", sha256: digest } });
+    const reference = { version: 1, key: String(input.key), objectkey, sha256: digest, sizebytes: data.byteLength, contenttype: input.contenttype ?? "application/octet-stream", metadata: { ...(input.metadata ?? {}) } };
+    await storage.put({ key: `${refprefix}/${input.key}`, data: encode(reference), contenttype: "application/json" });
+    return reference;
+  }
+
+  async function get(key) {
+    const reference = decode(await storage.get(`${refprefix}/${key}`));
+    return storage.get(reference.objectkey);
+  }
+
+  async function head(key) {
+    try { return decode(await storage.get(`${refprefix}/${key}`)); } catch { return null; }
+  }
+
+  async function remove(key) {
+    const reference = await head(key);
+    if (!reference) return false;
+    await storage.delete?.(`${refprefix}/${key}`);
+    return true;
+  }
+
+  return { put, get, head, delete: remove, capabilities: { immutableobjects: true, dedupe: true, references: true } };
+}

package/storage/filehosting.js

@@ -0,0 +1,17 @@
+/**
+ * file hosting adapter accepts a caller supplied request function for s3compatible or webdav.
+ */
+import { collectbytes, sha256 } from "./checksum.js";
+import { storageadapter } from "./adapter.js";
+
+export function filehosting(options = {}) {
+  if (!options.host || typeof options.request !== "function") throw new TypeError("file hosting requires host and request");
+  const method = options.method ?? "s3compatible";
+  return storageadapter({
+    async put(input) { const data = await collectbytes(input.data); await options.request({ method: method === "webdav" ? "PUT" : "put", url: new URL(input.key, options.host).href, data, headers: { "content-type": input.contenttype ?? "application/octet-stream" } }); return { key: input.key, sizebytes: data.byteLength, sha256: sha256(data), contenttype: input.contenttype ?? "application/octet-stream", createdat: Date.now(), metadata: input.metadata ?? {} }; },
+    async get(key) { const result = await options.request({ method: method === "webdav" ? "GET" : "get", url: new URL(key, options.host).href }); return result.data ?? result; },
+    async head(key) { try { const result = await options.request({ method: "head", url: new URL(key, options.host).href }); return { key, sizebytes: Number(result.headers?.["content-length"] ?? 0), sha256: result.headers?.etag ?? "", contenttype: result.headers?.["content-type"] ?? "application/octet-stream", createdat: Date.now(), metadata: {} }; } catch { return null; } },
+    async delete(key) { await options.request({ method: method === "webdav" ? "DELETE" : "delete", url: new URL(key, options.host).href }); },
+    async list(prefix = "") { const result = await options.request({ method: method === "webdav" ? "PROPFIND" : "list", url: new URL(prefix, options.host).href }); return result.items ?? []; }
+  });
+}

package/storage/githubcontents.js

@@ -0,0 +1,18 @@
+/**
+ * github contents storage maps artifacts to repository files through an injected token.
+ */
+import { collectbytes, sha256 } from "./checksum.js";
+import { storageadapter } from "./adapter.js";
+
+export function githubcontents(options = {}) {
+  if (!options.baseurl || !options.owner || !options.repo || typeof options.token !== "function") throw new TypeError("github contents requires baseurl owner repo and token");
+  const fetcher = options.fetcher ?? fetch;
+  async function request(method, key, body) { const token = await options.token(); const response = await fetcher(new URL(`/repos/${options.owner}/${options.repo}/contents/${key}`, options.baseurl), { method, headers: { accept: "application/vnd.github+json", authorization: `Bearer ${token}`, "content-type": "application/json" }, body: body ? JSON.stringify(body) : undefined }); if (!response.ok) throw new Error(`github contents request failed with ${response.status}`); return response; }
+  return storageadapter({
+    async put(input) { const data = await collectbytes(input.data); let sha; try { sha = (await (await request("GET", input.key)).json()).sha; } catch {} const response = await request("PUT", input.key, { message: input.message ?? `saddle write ${input.key}`, content: Buffer.from(data).toString("base64"), branch: options.branch ?? "main", sha }); const result = await response.json(); return { key: input.key, sizebytes: data.byteLength, sha256: sha256(data), contenttype: input.contenttype ?? "application/octet-stream", createdat: Date.now(), metadata: { url: result.content?.download_url, commit: result.commit?.sha, ...(input.metadata ?? {}) } }; },
+    async get(key) { const result = await (await request("GET", key)).json(); return new Uint8Array(Buffer.from(result.content.replaceAll("\n", ""), "base64")); },
+    async head(key) { try { const result = await (await request("GET", key)).json(); return { key, sizebytes: result.size, sha256: result.sha ?? "", contenttype: "application/octet-stream", createdat: Date.now(), metadata: { url: result.download_url } }; } catch { return null; } },
+    async delete(key) { const result = await (await request("GET", key)).json(); await request("DELETE", key, { message: `saddle delete ${key}`, sha: result.sha, branch: options.branch ?? "main" }); },
+    async list(prefix = "") { const result = await (await request("GET", prefix)).json(); return (Array.isArray(result) ? result : []).filter((item) => item.type === "file").map((item) => ({ key: item.path, sizebytes: item.size, sha256: item.sha, contenttype: "application/octet-stream", createdat: Date.now(), metadata: { url: item.download_url } })); }
+  });
+}

package/storage/index.js

@@ -0,0 +1,10 @@
+/**
+ * storage surface exports adapters and working-set helpers without selecting a vendor backend.
+ */
+export * from "./adapter.js";
+export * from "./cache.js";
+export * from "./checksum.js";
+export * from "./chunked.js";
+export * from "./content.js";
+export * from "./memory.js";
+export * from "./sync.js";

package/storage/local.js

@@ -0,0 +1,35 @@
+/**
+ * local storage is explicit, temporary friendly, and protected against traversal.
+ */
+import { mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { artifactnotfound, validationerror } from "../core/errors.js";
+import { artifactmanifest } from "../domain/artifacts.js";
+import { collectbytes, sha256 } from "./checksum.js";
+import { storageadapter } from "./adapter.js";
+
+export function localstorage(root) {
+  const base = resolve(root);
+  function safepath(key) {
+    const normalized = String(key ?? "").replaceAll("\\", "/");
+    if (!normalized || normalized.startsWith("/") || normalized.split("/").includes("..")) throw validationerror("storage key is not safe", { key });
+    const path = resolve(base, normalized);
+    if (path !== base && !path.startsWith(`${base}${sep}`)) throw validationerror("storage key escapes adapter root", { key });
+    return path;
+  }
+  function manifest(key, data, contenttype, metadata) {
+    return artifactmanifest({ key, sizebytes: data.byteLength, sha256: sha256(data), contenttype, createdat: Date.now(), metadata });
+  }
+  async function walk(directory, keys) {
+    let entries;
+    try { entries = await readdir(directory, { withFileTypes: true }); } catch (error) { if (error.code === "ENOENT") return; throw error; }
+    for (const entry of entries) { const path = join(directory, entry.name); if (entry.isDirectory()) await walk(path, keys); else keys.push(relative(base, path).split(sep).join("/")); }
+  }
+  return storageadapter({
+    async put(input) { const path = safepath(input.key); const data = await collectbytes(input.data); await mkdir(dirname(path), { recursive: true }); await writeFile(path, data); return manifest(input.key, data, input.contenttype ?? "application/octet-stream", input.metadata); },
+    async get(key) { try { return await readFile(safepath(key)); } catch (error) { if (error.code === "ENOENT") throw artifactnotfound(key); throw error; } },
+    async head(key) { try { const data = await this.get(key); const file = await stat(safepath(key)); return manifest(key, data, "application/octet-stream", { mtime: String(file.mtimeMs) }); } catch (error) { if (error.name === "saddleerror" && error.code === "ARTIFACT_NOT_FOUND") return null; throw error; } },
+    async delete(key) { try { await rm(safepath(key)); } catch (error) { if (error.code !== "ENOENT") throw error; } },
+    async list(prefix = "") { const keys = []; await walk(safepath(prefix || "."), keys); return Promise.all(keys.map((key) => this.head(key))); }
+  });
+}

package/storage/memory.js

@@ -0,0 +1,28 @@
+/**
+ * memory storage keeps bytes in a bounded process-local map for browser workers, Deno, Bun and tests.
+ */
+
+import { artifactmanifest } from "../domain/artifacts.js";
+import { sha256 } from "./checksum.js";
+import { storageadapter } from "./adapter.js";
+
+/** Creates a transport-neutral in-memory storage adapter with optional capacity limits. */
+export function memorystorage(options = {}) {
+  const values = new Map();
+  const maxbytes = Number(options.maxbytes ?? Number.POSITIVE_INFINITY);
+  if (!Number.isFinite(maxbytes) || maxbytes < 0) throw new TypeError("memory storage maxbytes is invalid");
+  let usedbytes = 0;
+
+  function manifest(key, data, input = {}) { return artifactmanifest({ key, sizebytes: data.byteLength, sha256: sha256(data), contenttype: input.contenttype ?? "application/octet-stream", createdat: input.createdat ?? Date.now(), metadata: input.metadata }); }
+  function copy(value) { return new Uint8Array(value); }
+  function ensurecapacity(previous, next) { if (usedbytes - previous + next > maxbytes) { const error = new Error("memory storage capacity exceeded"); error.code = "STORAGE_CAPACITY"; throw error; } }
+
+  return storageadapter({
+    async put(input = {}) { const key = String(input.key ?? ""); if (!key) throw new TypeError("memory storage key is required"); const data = copy(input.data ?? new Uint8Array()); const previous = values.get(key)?.data?.byteLength ?? 0; ensurecapacity(previous, data.byteLength); const item = { data, manifest: manifest(key, data, input) }; values.set(key, item); usedbytes += data.byteLength - previous; return { ...item.manifest }; },
+    async get(key) { const item = values.get(String(key)); if (!item) { const error = new Error(`artifact not found: ${key}`); error.code = "ARTIFACT_NOT_FOUND"; throw error; } return copy(item.data); },
+    async head(key) { const item = values.get(String(key)); return item ? { ...item.manifest } : null; },
+    async delete(key) { const value = values.get(String(key)); if (!value) return false; values.delete(String(key)); usedbytes -= value.data.byteLength; return true; },
+    async list(prefix = "") { return [...values].filter(([key]) => key.startsWith(String(prefix))).map(([, value]) => ({ ...value.manifest })); },
+    usage() { return { usedbytes, maxbytes }; }
+  });
+}

package/storage/s3compatible.js

@@ -0,0 +1,23 @@
+/**
+ * s3 compatible storage stays open by accepting a caller supplied signer.
+ */
+import { storageadapter } from "./adapter.js";
+
+export function s3compatible(options = {}) {
+  if (!options.endpoint || !options.bucket || typeof options.sign !== "function") throw new TypeError("s3 compatible storage requires endpoint bucket and sign");
+  const endpoint = new URL(options.endpoint);
+  const fetcher = options.fetcher ?? fetch;
+  async function request(method, key, body) {
+    const signed = await options.sign({ method, endpoint, bucket: options.bucket, key, body });
+    const response = await fetcher(signed.url, { method, headers: signed.headers, body });
+    if (!response.ok) throw new Error(`storage request failed with ${response.status}`);
+    return response;
+  }
+  return storageadapter({
+    async put(input) { const data = await (input.data instanceof Uint8Array ? input.data : (await import("./checksum.js")).collectbytes(input.data)); await request("PUT", input.key, data); return { key: input.key, sizebytes: data.byteLength, sha256: (await import("./checksum.js")).sha256(data), contenttype: input.contenttype ?? "application/octet-stream", createdat: Date.now(), metadata: { ...(input.metadata ?? {}) } }; },
+    async get(key) { const response = await request("GET", key); return new Uint8Array(await response.arrayBuffer()); },
+    async head(key) { try { const response = await request("HEAD", key); return { key, sizebytes: Number(response.headers.get("content-length") ?? 0), sha256: response.headers.get("etag") ?? "", contenttype: response.headers.get("content-type") ?? "application/octet-stream", createdat: Date.now(), metadata: {} }; } catch { return null; } },
+    async delete(key) { await request("DELETE", key); },
+    async list() { throw new Error("s3 compatible list requires a provider specific implementation"); }
+  });
+}

package/storage/sync.js

@@ -0,0 +1,55 @@
+/**
+ * storage synchronization compares versioned manifests and keeps conflict policy explicit.
+ */
+
+import { collectbytes, sha256 } from "./checksum.js";
+
+/** Describes capabilities exposed by a storage adapter without forcing optional methods. */
+export function storagecapabilities(storage) {
+  return Object.freeze({ range: typeof storage?.getrange === "function", conditional: typeof storage?.putifmatch === "function", metadata: typeof storage?.head === "function", delete: typeof storage?.delete === "function" });
+}
+
+/** Creates a comparable object manifest from bytes and caller metadata. */
+export async function objectmanifest(key, data, options = {}) {
+  const bytes = await collectbytes(data);
+  return { version: 1, key: String(key), sizebytes: bytes.byteLength, sha256: sha256(bytes), updatedat: Number(options.updatedat ?? Date.now()), etag: options.etag ?? sha256(bytes), metadata: { ...(options.metadata ?? {}) } };
+}
+
+/** Compares two manifests and classifies an update or conflict. */
+export function comparemanifests(local, remote) {
+  if (!local && !remote) return { state: "empty" };
+  if (!local) return { state: "remoteonly", remote };
+  if (!remote) return { state: "localonly", local };
+  if (local.sha256 === remote.sha256) return { state: "identical", local, remote };
+  if (local.updatedat > remote.updatedat) return { state: "localnewer", local, remote };
+  if (remote.updatedat > local.updatedat) return { state: "remotenewer", local, remote };
+  return { state: "conflict", local, remote };
+}
+
+/** Synchronizes one logical object between two adapters with explicit conflict handling. */
+export async function syncobject(source, target, key, options = {}) {
+  if (typeof source?.head !== "function" || typeof source?.get !== "function" || typeof target?.head !== "function" || typeof target?.put !== "function") throw new TypeError("sync requires source and target head, get and put");
+  const sourcehead = await source.head(key);
+  const targethead = await target.head(key);
+  const comparison = comparemanifests(normalizemanifest(sourcehead, key), normalizemanifest(targethead, key));
+  if (["empty", "identical"].includes(comparison.state)) return { key: String(key), state: comparison.state, manifest: comparison.local ?? comparison.remote };
+  if (comparison.state === "conflict" && typeof options.resolve !== "function") { const error = new Error(`storage conflict for key: ${key}`); error.code = "STORAGE_CONFLICT"; error.retryable = false; throw error; }
+  if (comparison.state === "conflict") { const choice = await options.resolve(comparison); if (!["source", "target"].includes(choice)) throw new TypeError("sync conflict resolver must return source or target"); if (choice === "target") return { key: String(key), state: "kepttarget", manifest: comparison.remote }; }
+  const data = await source.get(key);
+  const manifest = await objectmanifest(key, data, { updatedat: comparison.local?.updatedat ?? Date.now(), metadata: sourcehead?.metadata });
+  await target.put({ key: String(key), data, contenttype: sourcehead?.contenttype, metadata: { ...(sourcehead?.metadata ?? {}), sha256: manifest.sha256, updatedat: String(manifest.updatedat) } });
+  return { key: String(key), state: comparison.state === "conflict" ? "resolvedsource" : "copied", manifest };
+}
+
+/** Synchronizes one object to multiple backends and returns each outcome. */
+export async function syncbackends(source, targets = [], key, options = {}) {
+  if (!Array.isArray(targets)) throw new TypeError("sync targets must be an array");
+  const results = [];
+  for (const target of targets) {
+    try { results.push(await syncobject(source, target, key, options)); }
+    catch (error) { results.push({ key: String(key), state: "failed", code: error.code ?? "STORAGE_SYNC_FAILED", message: error.message }); if (options.stoponerror) break; }
+  }
+  return results;
+}
+
+function normalizemanifest(value, key) { return value ? { ...value, key: String(value.key ?? key), sha256: value.sha256 ?? value.etag, updatedat: Number(value.updatedat ?? 0) } : null; }

package/surfaces/adapters.js

@@ -0,0 +1,48 @@
+/**
+ * surface adapters define caller-owned desktop and mobile operations without selecting a vendor runtime.
+ */
+
+const profiles = Object.freeze({
+  desktop: { capabilities: ["window", "file", "notification"], formats: ["appimage", "dmg", "msi"] },
+  mobile: { capabilities: ["screen", "storage", "network"], formats: ["apk", "ipa"] }
+});
+
+/** Creates a transport-neutral adapter contract for a desktop or mobile surface. */
+export function surfaceadapter(options = {}) {
+  const target = String(options.target ?? "");
+  const profile = profiles[target];
+  if (!profile) throw new TypeError(`unsupported surface adapter: ${target}`);
+  const operations = [...new Set(options.operations ?? ["open", "close", "invoke", "status"])]
+    .map((operation) => String(operation));
+  if (!operations.length || operations.some((operation) => !/^[a-z][a-z0-9]*$/.test(operation))) throw new TypeError("surface adapter operations are invalid");
+  const handlers = { ...(options.handlers ?? {}) };
+  for (const [operation, handler] of Object.entries(handlers)) if (typeof handler !== "function") throw new TypeError(`surface handler is not callable: ${operation}`);
+
+  async function invoke(operation, input, context = {}) {
+    const name = String(operation ?? "");
+    if (!operations.includes(name)) throw new TypeError(`unsupported surface operation: ${name}`);
+    const handler = handlers[name];
+    if (!handler) return { target, operation: name, supported: false, result: undefined };
+    try {
+      return { target, operation: name, supported: true, result: await handler(input, context) };
+    } catch (error) {
+      return { target, operation: name, supported: true, ok: false, code: String(error?.code ?? "SURFACE_OPERATION_FAILED"), message: String(error?.message ?? error) };
+    }
+  }
+
+  return {
+    target,
+    version: 1,
+    capabilities: [...(options.capabilities ?? profile.capabilities)],
+    formats: [...(options.formats ?? profile.formats)],
+    operations,
+    invoke,
+    status: () => ({ target, ready: true, operations: [...operations], capabilities: [...(options.capabilities ?? profile.capabilities)] })
+  };
+}
+
+/** Creates a desktop adapter contract with caller-owned handlers. */
+export function desktopadapter(options = {}) { return surfaceadapter({ ...options, target: "desktop" }); }
+
+/** Creates a mobile adapter contract with caller-owned handlers. */
+export function mobileadapter(options = {}) { return surfaceadapter({ ...options, target: "mobile" }); }

package/surfaces/controls.js

@@ -0,0 +1,37 @@
+/**
+ * control surfaces provide an operator contract for jobs, sessions, storage, runners, permissions, logs and artifacts.
+ */
+
+export const controlresources = Object.freeze(["jobs", "sessions", "storage", "runners", "permissions", "logs", "artifacts"]);
+export const controloperations = Object.freeze(["list", "get", "create", "update", "cancel", "retry", "delete", "check"]);
+
+/** Creates a caller-owned operator surface with resource handlers and optional audit recording. */
+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 respond({ ok: false, code: "UNSUPPORTED_CONTROL", message: `${resource}.${operation} is not configured`, context, audit });
+    try {
+      const result = await handler(request.input ?? {}, context);
+      return respond({ ok: true, result, context, audit });
+    } catch (error) {
+      return respond({ ok: false, code: String(error?.code ?? "CONTROL_FAILED"), message: String(error?.message ?? 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)) }) };
+}
+
+async function respond({ 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 = String(error?.message ?? error); }
+  return response;
+}

package/surfaces/manifest.js

@@ -0,0 +1,25 @@
+/**
+ * surface manifests describe repackaging targets without adding target code to the engine.
+ */
+export const surfaces = Object.freeze(["browser", "extension", "desktop", "mobile", "n8n", "cli", "binary", "library"]);
+
+export const surfaceformats = Object.freeze({ desktop: Object.freeze(["appimage", "dmg", "msi"]), mobile: Object.freeze(["apk", "ipa"]) });
+
+export function surfacemanifest(options = {}) {
+  const target = options.target ?? "library";
+  if (!surfaces.includes(target)) throw new TypeError(`unsupported surface: ${target}`);
+  return { target, name: options.name ?? "saddle", entry: options.entry ?? "index.js", runtime: options.runtime ?? "caller", formats: [...(options.formats ?? surfaceformats[target] ?? [])], permissions: options.permissions ?? [], capabilities: options.capabilities ?? ["memory", "scrape", "workflow"], metadata: options.metadata ?? {} };
+}
+
+/** Creates a desktop surface manifest with caller-selected packaging formats. */
+export function desktopmanifest(options = {}) { return surfacemanifest({ ...options, target: "desktop", formats: options.formats ?? surfaceformats.desktop }); }
+
+/** Creates a mobile surface manifest with caller-selected packaging formats. */
+export function mobilemanifest(options = {}) { return surfacemanifest({ ...options, target: "mobile", formats: options.formats ?? surfaceformats.mobile }); }
+
+/** Describes installation without performing a package or platform mutation. */
+export function surfacebundle(manifest) {
+  if (!manifest?.target || !surfaces.includes(manifest.target)) throw new TypeError("surface bundle requires a valid manifest");
+  const install = { n8n: "n8n import", browser: "import by url", extension: "load unpacked", desktop: "caller desktop bundle", mobile: "caller mobile bundle" }[manifest.target] ?? "npm install";
+  return { ...manifest, files: [...new Set([manifest.entry, ...(manifest.files ?? [])])], install };
+}

package/surfaces/n8n.js

@@ -0,0 +1,24 @@
+/**
+ * n8n node metadata keeps workflow automation as a packaging surface.
+ */
+export function n8nnode(options = {}) {
+  const triggers = normalize(options.triggers ?? n8ntriggers);
+  const actions = normalize(options.actions ?? n8nactions);
+  return { name: options.name ?? "saddle", displayname: options.displayname ?? "Saddle", description: options.description ?? "Saddle engine operation", version: 1, inputs: options.inputs ?? ["main"], outputs: options.outputs ?? ["main"], triggers, actions, properties: options.properties ?? [{ displayname: "trigger", name: "trigger", type: "options", options: triggers.map((value) => ({ name: value, value })) }, { displayname: "command", name: "command", type: "options", options: actions.map((value) => ({ name: value, value })), default: "status" }] };
+}
+
+export const n8ntriggers = Object.freeze(["manual", "dispatch", "webhook", "schedule", "retry", "heartbeat"]);
+export const n8nactions = Object.freeze(["status", "scrape", "crawl", "extract", "batch", "browser", "memory", "sync"]);
+
+/** Matches an incoming event against the trigger declarations of a node. */
+export function n8nmatch(node, event = {}) { const type = String(event.type ?? "manual"); return { matched: Boolean(node?.triggers?.includes(type)), type, requestid: event.requestid ?? `${node?.name ?? "saddle"}/${type}` }; }
+
+/** Executes a declared n8n action through a caller-owned handler. */
+export async function n8nexecute(node, input, handler) {
+  if (typeof handler !== "function") throw new TypeError("n8n handler is required");
+  const action = String(input?.action ?? input?.command ?? "status");
+  if (!node?.actions?.includes(action)) throw new TypeError(`unsupported n8n action: ${action}`);
+  try { return await handler({ node, input: { ...(input ?? {}), action } }); } catch (error) { const failure = new Error(`n8n action failed: ${error?.message ?? error}`, { cause: error }); failure.code = String(error?.code ?? "N8N_ACTION_FAILED"); throw failure; }
+}
+
+function normalize(values) { const list = Array.isArray(values) ? values : [values]; if (!list.length || list.some((value) => typeof value !== "string" || !value)) throw new TypeError("n8n declarations are invalid"); return [...new Set(list)]; }

package/surfaces/operations.js

@@ -0,0 +1,43 @@
+/**
+ * operations describe bounded telemetry, retention, recovery and threat boundaries without selecting storage or telemetry vendors.
+ */
+
+export const operationmetrics = Object.freeze(["latency", "retries", "queuedepth", "runnerselection", "storagebytes", "failures"]);
+
+/** Binds the standard operational metric names to an injected metric collector. */
+export function operationsmetrics(options = {}) {
+  const collector = options.collector;
+  if (!collector || typeof collector.count !== "function" || typeof collector.observe !== "function" || typeof collector.snapshot !== "function") throw new TypeError("operations metrics requires a collector");
+  function record(name, value = 1, labels = {}) {
+    if (!operationmetrics.includes(name)) throw new TypeError(`unsupported operation metric: ${name}`);
+    return name === "latency" ? collector.observe(name, value, labels) : collector.count(name, value, labels);
+  }
+  return { names: [...operationmetrics], record, snapshot: () => collector.snapshot() };
+}
+
+/** Creates a deterministic retention policy for caller-owned records. */
+export function retentionpolicy(options = {}) {
+  const days = Number(options.days ?? 30);
+  const maxbytes = Number(options.maxbytes ?? Number.POSITIVE_INFINITY);
+  if (!Number.isFinite(days) || days < 0 || !Number.isFinite(maxbytes) || maxbytes < 0) throw new TypeError("retention policy limits are invalid");
+  return { days, maxbytes, cutoff(now = Date.now()) { return Number(now) - days * 86400000; }, keeps(record, now = Date.now()) { return Number(record?.updatedat ?? record?.createdat ?? 0) >= this.cutoff(now) && Number(record?.bytes ?? 0) <= maxbytes; } };
+}
+
+/** Defines caller-owned backup and restore functions with explicit capability errors. */
+export function backupplan(options = {}) {
+  const backup = options.backup;
+  const restore = options.restore;
+  return { version: 1, backup: async (input) => execute(backup, input, "backup"), restore: async (input) => execute(restore, input, "restore") };
+}
+
+/** Records the security boundary and prevents the core from claiming threat coverage it does not own. */
+export function threatmodel(options = {}) {
+  const boundaries = [...new Set((options.boundaries ?? ["credentials", "network", "permissions", "persistence"]).map(String))];
+  if (!boundaries.length) throw new TypeError("threat model requires boundaries");
+  return { version: 1, boundaries, owner: options.owner ?? "caller", controls: [...new Set((options.controls ?? []).map(String))], disclaimer: "The caller remains responsible for deployment, credentials, service terms and abuse response." };
+}
+
+async function execute(handler, input, name) {
+  if (typeof handler !== "function") { const error = new Error(`${name} handler is not configured`); error.code = "UNSUPPORTED_OPERATION"; throw error; }
+  try { return await handler(input); } catch (error) { const failure = new Error(`${name} failed: ${error?.message ?? error}`, { cause: error }); failure.code = String(error?.code ?? "OPERATION_FAILED"); throw failure; }
+}

package/surfaces/targets.js

@@ -0,0 +1,16 @@
+/**
+ * target profiles keep platform packaging open and describe capability boundaries.
+ */
+export const targetprofiles = Object.freeze({
+  computer: { runtime: "unknown", entry: "index.js", capabilities: ["memory", "storage", "runner"] },
+  desktopapp: { runtime: "unknown", entry: "index.js", capabilities: ["memory", "file", "visible"] },
+  mobileapp: { runtime: "browser", entry: "index.js", capabilities: ["memory", "network", "headless"] },
+  extension: { runtime: "browser", entry: "index.js", capabilities: ["browser", "network", "visible"] },
+  internet: { runtime: "unknown", entry: "index.js", capabilities: ["network", "webhook", "api"] }
+});
+
+/** Creates a surface target with caller supplied entry and capabilities. */
+export function targetmanifest(target, options = {}) { const profile = targetprofiles[target]; if (!profile) throw new TypeError(`unsupported target: ${target}`); return { target, runtime: options.runtime ?? profile.runtime, entry: options.entry ?? profile.entry, capabilities: options.capabilities ?? [...profile.capabilities], permissions: options.permissions ?? [], metadata: options.metadata ?? {} }; }
+
+/** Returns all supported target profiles for documentation and tooling. */
+export function targetcatalog() { return Object.fromEntries(Object.entries(targetprofiles).map(([key, value]) => [key, { ...value, capabilities: [...value.capabilities] }])); }

package/webhook/delivery.js

@@ -0,0 +1,26 @@
+/**
+ * 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 })); } };
+}