@wenathlan/saddle 1.8.1

package/core/hash.js

@@ -0,0 +1,73 @@
+/**
+ * hash helpers use standard JavaScript primitives so transport-neutral modules do not require node:crypto.
+ */
+
+const constants = Object.freeze([
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+  0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+  0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+  0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+  0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+  0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+  0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+  0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2
+]);
+
+/** Returns a SHA-256 hexadecimal digest for bytes or text. */
+export function sha256(value) { return tohex(hashbytes(value)); }
+
+/** Returns an HMAC-SHA-256 hexadecimal digest for bytes or text. */
+export function hmacsha256(value, secret) {
+  let key = tobytes(secret);
+  if (key.length > 64) key = hashbytes(key);
+  const padded = new Uint8Array(64);
+  padded.set(key);
+  const outer = new Uint8Array(64);
+  const inner = new Uint8Array(64);
+  for (let index = 0; index < 64; index += 1) { outer[index] = padded[index] ^ 0x5c; inner[index] = padded[index] ^ 0x36; }
+  return sha256(concat(outer, hashbytes(concat(inner, tobytes(value)))));
+}
+
+/** Compares hexadecimal values without early exit based on content. */
+export function constanttimeequal(left, right) { const a = String(left ?? ""); const b = String(right ?? ""); let difference = a.length ^ b.length; const length = Math.max(a.length, b.length); for (let index = 0; index < length; index += 1) difference |= (a.charCodeAt(index) || 0) ^ (b.charCodeAt(index) || 0); return difference === 0; }
+
+function hashbytes(value) {
+  const input = tobytes(value);
+  const bitlength = BigInt(input.length) * 8n;
+  const length = Math.ceil((input.length + 9) / 64) * 64;
+  const padded = new Uint8Array(length);
+  padded.set(input);
+  padded[input.length] = 0x80;
+  const inputview = new DataView(padded.buffer);
+  inputview.setUint32(length - 8, Number((bitlength >> 32n) & 0xffffffffn));
+  inputview.setUint32(length - 4, Number(bitlength & 0xffffffffn));
+  const state = new Uint32Array([0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19]);
+  const words = new Uint32Array(64);
+  for (let offset = 0; offset < length; offset += 64) {
+    for (let index = 0; index < 16; index += 1) words[index] = inputview.getUint32(offset + index * 4);
+    for (let index = 16; index < 64; index += 1) {
+      const sigma0 = smallright(words[index - 15], 7) ^ smallright(words[index - 15], 18) ^ (words[index - 15] >>> 3);
+      const sigma1 = smallright(words[index - 2], 17) ^ smallright(words[index - 2], 19) ^ (words[index - 2] >>> 10);
+      words[index] = (sigma1 + words[index - 7] + sigma0 + words[index - 16]) >>> 0;
+    }
+    let [a, b, c, d, e, f, g, h] = state;
+    for (let index = 0; index < 64; index += 1) {
+      const choose = (e & f) ^ (~e & g);
+      const majority = (a & b) ^ (a & c) ^ (b & c);
+      const first = (h + (smallright(e, 6) ^ smallright(e, 11) ^ smallright(e, 25)) + choose + constants[index] + words[index]) >>> 0;
+      const second = ((smallright(a, 2) ^ smallright(a, 13) ^ smallright(a, 22)) + majority) >>> 0;
+      [h, g, f, e, d, c, b, a] = [g, f, e, (d + first) >>> 0, c, b, a, (first + second) >>> 0];
+    }
+    state[0] = (state[0] + a) >>> 0; state[1] = (state[1] + b) >>> 0; state[2] = (state[2] + c) >>> 0; state[3] = (state[3] + d) >>> 0;
+    state[4] = (state[4] + e) >>> 0; state[5] = (state[5] + f) >>> 0; state[6] = (state[6] + g) >>> 0; state[7] = (state[7] + h) >>> 0;
+  }
+  const output = new Uint8Array(32);
+  const view = new DataView(output.buffer);
+  state.forEach((word, index) => view.setUint32(index * 4, word));
+  return output;
+}
+
+function tobytes(value) { if (value instanceof Uint8Array) return value; if (value instanceof ArrayBuffer) return new Uint8Array(value); return new TextEncoder().encode(String(value ?? "")); }
+function concat(left, right) { const result = new Uint8Array(left.length + right.length); result.set(left); result.set(right, left.length); return result; }
+function smallright(value, amount) { return (value >>> amount) | (value << (32 - amount)); }
+function tohex(value) { return [...value].map((byte) => byte.toString(16).padStart(2, "0")).join(""); }

package/core/ids.js

@@ -0,0 +1,15 @@
+/**
+ * injectable time and id factories make every engine path reproducible.
+ */
+export function systemclock() {
+  return { now: () => Date.now() };
+}
+
+export function idfactory(randomuuid = globalThis.crypto?.randomUUID?.bind(globalThis.crypto)) {
+  return {
+    next(prefix) {
+      const suffix = randomuuid?.() ?? `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 10)}`;
+      return `${prefix}${suffix}`;
+    }
+  };
+}

package/crawl/crawler.js

@@ -0,0 +1,29 @@
+/**
+ * crawler performs bounded breadth first traversal through the scraper contract.
+ */
+import { normalizeurl, sameorigin } from "./normalize.js";
+import { crawlfrontier } from "./frontier.js";
+
+export async function crawl(start, options = {}) {
+  const maxdepth = options.maxdepth ?? 1;
+  const maxpages = options.maxpages ?? 20;
+  const sameDomain = options.samedomain ?? true;
+  const frontier = crawlfrontier({ maxpages, maxperdomain: options.maxperdomain ?? maxpages });
+  frontier.add({ url: normalizeurl(start), depth: 0, priority: options.startpriority ?? 0 });
+  const results = [];
+  while (frontier.state().queued && results.length < maxpages) {
+    const current = frontier.next();
+    if (!current || current.depth > maxdepth) continue;
+    const result = await options.scrape(current.url);
+    results.push({ ...result, depth: current.depth });
+    frontier.complete(current.url);
+    if (current.depth >= maxdepth) continue;
+    for (const link of result.links ?? []) {
+      let url;
+      try { url = normalizeurl(link); } catch { continue; }
+      if (sameDomain && !sameorigin(start, url)) continue;
+      frontier.add({ url, depth: current.depth + 1, priority: Number(options.priority?.(url, result) ?? 0) });
+    }
+  }
+  return { results, stats: { ...frontier.state(), completed: results.length, maxdepth, maxpages } };
+}

package/crawl/frontier.js

@@ -0,0 +1,34 @@
+/**
+ * crawl frontier provides priorities, per-domain budgets and persistent-friendly queue state.
+ */
+
+/** Creates a bounded priority frontier for crawler and queue adapters. */
+export function crawlfrontier(options = {}) {
+  const maxpages = Number(options.maxpages ?? 20);
+  const maxperdomain = Number(options.maxperdomain ?? maxpages);
+  const queue = [];
+  const seen = new Set();
+  const completed = new Set();
+  const domains = new Map();
+  function add(input = {}) {
+    const url = String(input.url ?? "");
+    if (!url || seen.has(url) || seen.size >= maxpages) return false;
+    seen.add(url);
+    queue.push({ url, depth: Number(input.depth ?? 0), priority: Number(input.priority ?? 0), discoveredat: Number(input.discoveredat ?? Date.now()) });
+    queue.sort((left, right) => right.priority - left.priority || left.discoveredat - right.discoveredat);
+    return true;
+  }
+  function next() {
+    while (queue.length) {
+      const item = queue.shift();
+      const domain = new URL(item.url).hostname;
+      if ((domains.get(domain) ?? 0) >= maxperdomain) continue;
+      domains.set(domain, (domains.get(domain) ?? 0) + 1);
+      return { ...item };
+    }
+    return null;
+  }
+  function complete(url) { completed.add(String(url)); }
+  function state() { return { maxpages, maxperdomain, queued: queue.length, discovered: seen.size, completed: completed.size, domains: Object.fromEntries(domains) }; }
+  return { add, next, complete, state, list() { return queue.map((item) => ({ ...item })); } };
+}

package/crawl/normalize.js

@@ -0,0 +1,14 @@
+/**
+ * url normalization removes tracking noise before frontier deduplication.
+ */
+const tracking = /^(utm_|fbclid$|msclkid$|gclid$|gclsrc$|dclid$|gbraid$|wbraid$|twclid$|campaign$|content$|term$|source$|medium$|ref$|share_id$)/i;
+
+export function normalizeurl(value) {
+  const url = new URL(value);
+  url.hash = "";
+  for (const key of [...url.searchParams.keys()]) if (tracking.test(key)) url.searchParams.delete(key);
+  if (url.pathname.length > 1) url.pathname = url.pathname.replace(/\/+$/, "");
+  return url.href;
+}
+
+export function sameorigin(left, right) { return new URL(left).origin === new URL(right).origin; }

package/crawl/persistent.js

@@ -0,0 +1,13 @@
+/**
+ * persistent crawl queue uses an injected store and falls back to memory when no store exists.
+ */
+export function persistentqueue(options = {}) {
+  const store = options.store;
+  const values = [];
+  const seen = new Set();
+  async function restore() { if (typeof store?.list !== "function") return; for (const item of await store.list()) if (!seen.has(item.url) && item.status !== "done") { seen.add(item.url); values.push(item); } }
+  async function add(item) { if (!item?.url || seen.has(item.url)) return false; const value = { url: item.url, depth: item.depth ?? 0, status: "queued", createdat: Date.now(), metadata: item.metadata ?? {} }; seen.add(value.url); values.push(value); if (typeof store?.save === "function") await store.save(value); return true; }
+  async function next() { const item = values.find((value) => value.status === "queued"); if (!item) return null; item.status = "running"; if (typeof store?.update === "function") await store.update(item.url, item); return item; }
+  async function complete(url, patch = {}) { const item = values.find((value) => value.url === url); if (!item) return null; Object.assign(item, patch, { status: patch.status ?? "done", processedat: Date.now() }); if (typeof store?.update === "function") await store.update(url, item); return item; }
+  return { restore, add, next, complete, list() { return values.map((value) => ({ ...value })); } };
+}

package/dispatch/resumable.js

@@ -0,0 +1,31 @@
+/**
+ * resumable runs keep remote execution state explicit and recoverable across process restarts.
+ */
+
+export const runstatuses = Object.freeze(["created", "submitted", "running", "succeeded", "failed", "cancelled"]);
+const transitions = { created: ["submitted", "cancelled"], submitted: ["running", "failed", "cancelled"], running: ["succeeded", "failed", "cancelled"], succeeded: [], failed: ["submitted", "cancelled"], cancelled: [] };
+
+/** Creates a validated run record with explicit transition history. */
+export function runrecord(input = {}) {
+  if (!input.requestid || !input.name) throw new TypeError("run record requires requestid and name");
+  return { version: 1, requestid: String(input.requestid), name: String(input.name), status: input.status ?? "created", runid: input.runid, attempt: Number(input.attempt ?? 0), createdat: Number(input.createdat ?? Date.now()), updatedat: Number(input.updatedat ?? Date.now()), history: Array.isArray(input.history) ? input.history.map((event) => ({ ...event })) : [], metadata: { ...(input.metadata ?? {}) } };
+}
+
+/** Moves a run through a legal state transition and appends an auditable event. */
+export function transitionrun(record, status, options = {}) {
+  const current = runrecord(record);
+  if (!runstatuses.includes(status) || !transitions[current.status]?.includes(status)) { const error = new Error(`invalid run transition: ${current.status} to ${status}`); error.code = "INVALID_RUN_TRANSITION"; throw error; }
+  const event = { from: current.status, to: status, at: Number(options.at ?? Date.now()), reason: options.reason };
+  return { ...current, status, runid: options.runid ?? current.runid, attempt: status === "submitted" ? current.attempt + 1 : current.attempt, updatedat: event.at, history: [...current.history, event] };
+}
+
+/** Coordinates submit, status, resume and cancel operations through an injected remote adapter. */
+export function resumablerun(adapter, input = {}) {
+  if (typeof adapter?.submit !== "function" || typeof adapter?.status !== "function") throw new TypeError("resumable run adapter requires submit and status");
+  let record = runrecord(input);
+  async function submit() { const response = await adapter.submit(input); record = transitionrun(record, "submitted", { runid: response?.runid, reason: "submitted" }); return { ...record, response }; }
+  async function resume() { if (record.status === "created") await submit(); if (typeof adapter.resume === "function") await adapter.resume(record); const response = await adapter.status(record.runid); if (response?.status && response.status !== record.status && transitions[record.status]?.includes(response.status)) record = transitionrun(record, response.status, { reason: "remote-status" }); return { ...record, response }; }
+  async function cancel() { if (typeof adapter.cancel !== "function") throw new TypeError("resumable run adapter does not support cancel"); const response = await adapter.cancel(record.runid); if (record.status !== "cancelled" && transitions[record.status]?.includes("cancelled")) record = transitionrun(record, "cancelled", { reason: "cancelled" }); return { ...record, response }; }
+  function get() { return runrecord(record); }
+  return { submit, resume, cancel, get };
+}

package/dispatch/workflow.js

@@ -0,0 +1,33 @@
+/**
+ * workflow dispatch keeps remote execution explicit and records a stable request identity.
+ */
+import { idempotency } from "../queue/idempotency.js";
+
+export function workflowdispatch(adapter, options = {}) {
+  if (typeof adapter?.dispatch !== "function") throw new TypeError("workflow adapter requires dispatch");
+  const records = options.records ?? idempotency();
+  return {
+    async submit(spec) {
+      if (!spec?.owner || !spec.repository || !spec.workflow || !spec.ref) throw new TypeError("workflow owner repository workflow and ref are required");
+      const requestid = spec.requestid ?? `${spec.owner}/${spec.repository}/${spec.workflow}/${spec.ref}/${JSON.stringify(spec.inputs ?? {})}`;
+      if (records.has(requestid)) return records.get(requestid);
+      const response = await adapter.dispatch(spec.owner, spec.repository, spec.workflow, { ref: spec.ref, inputs: spec.inputs ?? {} });
+      const record = { requestid, ...spec, response, submittedat: Date.now() };
+      records.set(requestid, record);
+      return record;
+    },
+    get(requestid) { return records.get(requestid); }
+  };
+}
+
+export async function waitforrun(adapter, owner, repository, runid, options = {}) {
+  if (typeof adapter?.run !== "function") throw new TypeError("workflow adapter requires run");
+  const attempts = options.attempts ?? 20;
+  const interval = options.interval ?? 3000;
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    const run = await adapter.run(owner, repository, runid);
+    if (["completed", "failure", "cancelled", "success"].includes(run.status)) return run;
+    await new Promise((resolve) => setTimeout(resolve, interval));
+  }
+  throw new Error(`workflow run ${runid} did not finish within configured attempts`);
+}

package/docs/assets/architecture.svg

@@ -0,0 +1,45 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 360" role="img" aria-labelledby="title desc">
+  <title id="title">Saddle runtime architecture</title>
+  <desc id="desc">Storage enters a bridge, becomes a working set, runs through an injected runner, and returns as an artifact.</desc>
+  <defs>
+    <linearGradient id="paper" x1="0" x2="1" y1="0" y2="1">
+      <stop offset="0" stop-color="#fbf7f0"/>
+      <stop offset="1" stop-color="#efe6d8"/>
+    </linearGradient>
+    <marker id="arrow" markerHeight="8" markerWidth="8" orient="auto" refX="7" refY="4">
+      <path d="M0 0 8 4 0 8Z" fill="#d35d3d"/>
+    </marker>
+  </defs>
+  <rect width="1200" height="360" rx="30" fill="url(#paper)"/>
+  <path d="M60 72H1140M60 286H1140" stroke="#d9cdbc" stroke-dasharray="5 9"/>
+  <g font-family="Arial, Helvetica, sans-serif">
+    <g transform="translate(70 108)">
+      <rect width="205" height="130" rx="18" fill="#202a2f"/>
+      <text x="24" y="38" fill="#f7f1e8" font-size="14" letter-spacing="2">01 · STORAGE</text>
+      <text x="24" y="76" fill="#fff" font-size="23" font-weight="700">Objects</text>
+      <text x="24" y="104" fill="#b8c4c1" font-size="14">local · S3 · forge</text>
+    </g>
+    <path d="M290 173h80" fill="none" stroke="#d35d3d" stroke-width="4" marker-end="url(#arrow)"/>
+    <g transform="translate(390 108)">
+      <rect width="205" height="130" rx="18" fill="#d35d3d"/>
+      <text x="24" y="38" fill="#fff3e7" font-size="14" letter-spacing="2">02 · BRIDGE</text>
+      <text x="24" y="76" fill="#fff" font-size="23" font-weight="700">Working set</text>
+      <text x="24" y="104" fill="#ffe5d5" font-size="14">load · transform · sync</text>
+    </g>
+    <path d="M610 173h80" fill="none" stroke="#d35d3d" stroke-width="4" marker-end="url(#arrow)"/>
+    <g transform="translate(710 108)">
+      <rect width="205" height="130" rx="18" fill="#e5c26f"/>
+      <text x="24" y="38" fill="#4b3d22" font-size="14" letter-spacing="2">03 · RUNNER</text>
+      <text x="24" y="76" fill="#202a2f" font-size="23" font-weight="700">Job cycle</text>
+      <text x="24" y="104" fill="#4b3d22" font-size="14">prepare · process · cleanup</text>
+    </g>
+    <path d="M930 173h80" fill="none" stroke="#d35d3d" stroke-width="4" marker-end="url(#arrow)"/>
+    <g transform="translate(1030 108)">
+      <rect width="100" height="130" rx="18" fill="#fff" stroke="#202a2f" stroke-width="2"/>
+      <text x="18" y="38" fill="#202a2f" font-size="14" letter-spacing="2">04</text>
+      <text x="18" y="74" fill="#202a2f" font-size="20" font-weight="700">Artifact</text>
+      <text x="18" y="102" fill="#6d7777" font-size="13">persist</text>
+    </g>
+    <text x="70" y="319" fill="#6d7777" font-size="14">Saddle owns the contracts. The caller chooses credentials, transports, storage, browser and runner.</text>
+  </g>
+</svg>

package/docs/assets/saddlemark.svg

@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 720 180" role="img" aria-labelledby="title desc">
+  <title id="title">Saddle</title>
+  <desc id="desc">Saddle wordmark with a warm ember mark and a storage-to-compute arc.</desc>
+  <rect width="720" height="180" rx="28" fill="#f7f1e8"/>
+  <g transform="translate(42 34)">
+    <path d="M52 10c-27 0-48 20-48 45 0 32 24 57 57 57 19 0 35-8 46-22-13 5-25 7-36 7-23 0-39-17-39-39 0-19 13-35 31-42 12-5 25-6 39-4C90 18 73 10 52 10Z" fill="#d35d3d"/>
+    <path d="M31 76c15 11 33 17 54 17 25 0 44-9 59-28" fill="none" stroke="#202a2f" stroke-linecap="round" stroke-width="8"/>
+    <circle cx="35" cy="45" r="7" fill="#f7f1e8"/>
+    <circle cx="137" cy="65" r="7" fill="#d35d3d"/>
+  </g>
+  <text x="220" y="91" fill="#202a2f" font-family="Arial, Helvetica, sans-serif" font-size="58" font-weight="700" letter-spacing="10">SADDLE</text>
+  <text x="224" y="126" fill="#6d7777" font-family="Arial, Helvetica, sans-serif" font-size="14" letter-spacing="3">STORAGE · WORKING SET · RUNNER</text>
+</svg>

package/docs/comparativeaudit.md

@@ -0,0 +1,63 @@
+# comparative audit
+
+## sources reviewed
+
+### Chrome extension messaging
+
+Source: Chrome for Developers, [Message passing](https://developer.chrome.com/docs/extensions/develop/concepts/messaging).
+
+Manifest V3 extensions need explicit message contracts between service workers, extension pages and content scripts. Chrome exposes one-time request/response through `runtime.sendMessage()` and `tabs.sendMessage()`, plus long-lived connections through `runtime.connect()` and ports. Asynchronous responses must keep the channel open with an explicit `true` return in broadly compatible implementations; response values must be serializable, and sender errors need a defined handling path.
+
+Implication for Saddle: the future `extension/` surface needs a versioned message envelope, sender and tab metadata, request correlation, timeout handling, serializable payload validation and a distinction between one-shot commands and long-lived streams. The browser adapter contract alone is not enough for an extension runtime.
+
+### Vercel agent-browser
+
+Source: [vercel-labs/agent-browser](https://github.com/vercel-labs/agent-browser).
+
+The project separates a browser daemon from the CLI and exposes a compact interaction loop: open, snapshot an accessibility tree with stable refs, act on refs, read text, screenshot and close. It also supports traditional selectors, role-based finders, uploads, keyboard events, DOM reads, CDP connection and a remote browser mode. Its README emphasizes early click failure when an overlay covers a target and requires a fresh snapshot before retrying.
+
+Implication for Saddle: the browser contract should add snapshot identity and stale-reference errors, explicit action results, overlay or obstruction diagnostics, upload and keyboard primitives, session lifecycle, and a transport that can point to a local or remote browser without making the CLI the core.
+
+## initial gap hypotheses
+
+The current Saddle code has browser action names, sessions, replay, fingerprint and MCP contracts, but the audit still needs to verify whether it has snapshot references, stale-state detection, tab/frame ownership, extension messaging, permission minimization, content-script isolation and a real buildable Manifest V3 surface. These items remain hypotheses until the repository and more primary sources are reviewed.
+
+### Microsoft Playwright MCP
+
+Source: [microsoft/playwright-mcp](https://github.com/microsoft/playwright-mcp).
+
+Playwright MCP uses structured accessibility snapshots rather than pixel-only input and supports navigation, interaction, inspection and persistent browser context through an MCP server. Its own documentation distinguishes a CLI path for token-efficient coding-agent workflows from MCP for persistent state, rich introspection and long-running autonomous loops.
+
+Implication for Saddle: the extension and MCP layers should share a structured page snapshot model, while keeping a lower-level browser action contract underneath. The model should support stable element references, snapshot refresh, action diagnostics and a choice between compact command output and richer introspection.
+
+### Chrome content scripts
+
+Source: Chrome for Developers, [Content scripts](https://developer.chrome.com/docs/extensions/develop/concepts/content-scripts).
+
+Content scripts run in an isolated world, can use only a limited set of extension APIs directly, and must message the service worker for other capabilities. Static, dynamic and programmatic injection have different permission and lifecycle implications; host match patterns and web-accessible resources expand the security surface.
+
+Implication for Saddle: the first extension implementation should use a narrow static content script, an isolated DOM bridge, a service worker as the privileged coordinator and minimal host permissions. It should not expose the core package or arbitrary remote code as a web-accessible resource.
+
+### Manifest permissions and lifecycle
+
+Sources: Chrome for Developers, [Declare permissions](https://developer.chrome.com/docs/extensions/develop/concepts/declare-permissions) and [The extension service worker lifecycle](https://developer.chrome.com/docs/extensions/develop/concepts/service-workers/lifecycle).
+
+Permissions, host permissions, optional permissions and optional host permissions are separate manifest controls. Optional permissions should be preferred when a feature allows it because permission changes and broad match patterns can create install or runtime warnings. MV3 service workers are event-driven and can be terminated after inactivity or long-running limits; global variables do not survive shutdown, so durable state belongs in extension storage or IndexedDB and handlers must be reentrant.
+
+Implication for Saddle: the extension manifest should begin with `storage` and a deliberately small content match policy, avoid `tabs`, `cookies`, `webRequest`, debugger and broad host permissions until a tested feature requires them, and expose an explicit permission escalation flow. The service worker should rehydrate state per event, persist session metadata, and treat ports, messages and in-flight jobs as recoverable rather than process-local.
+
+### Browser Use
+
+Source: [browser-use/browser-use](https://github.com/browser-use/browser-use).
+
+Browser Use exposes a high-level task agent, a lower-level programmable library, custom tools, authentication profiles, persistent filesystem and memory, and a hosted execution path with scaling, proxy rotation and browser fingerprinting. It explicitly separates one-off CLI usage from repeatable automation embedded in code.
+
+Implication for Saddle: the core should distinguish task orchestration from browser primitives, provide tool registration and structured task history, and treat authentication profiles, persistence and remote execution as adapters. Saddle already has bot, workflow, session and storage contracts, but the extension surface needs a clear task-to-command bridge rather than exposing raw browser actions only.
+
+### WXT
+
+Source: [WXT](https://wxt.dev/).
+
+WXT demonstrates the value of an opinionated extension build surface: fast development reloads, multiple entrypoints, multi-browser output, automated packaging and publishing, and bundle analysis. The framework uses TypeScript by default, but its architectural lessons apply independently of language choice.
+
+Implication for Saddle: `extension/` should be a buildable, vendor-light surface with explicit manifest, background, content and control entrypoints, a packageable artifact, browser capability detection and a future adapter boundary for Chrome, Firefox and other WebExtension-compatible runtimes. The first implementation can stay pure JavaScript and avoid adding a framework dependency.

package/docs/ecosystemplan.md

@@ -0,0 +1,59 @@
+# ecosystem implementation plan
+
+Saddle is treated as the contract layer for a larger ecosystem. The implementation is progressive: each block adds a cohesive capability, tests it without real credentials, updates the public documentation and records the release impact before the next block begins.
+
+## north star
+
+The library remains usable as a root-based JavaScript ESM package in library, CLI, binary, browser, extension, desktop, mobile, container and runner contexts. A caller can choose storage, browser, provider, runner, database, proxy, bot and credential adapters without changing the core contracts.
+
+The engine owns **contracts, validation, orchestration, recovery and auditability**. The caller owns **accounts, credentials, remote infrastructure, browser profiles, service terms and deployment choices**.
+
+## non-negotiable invariants
+
+| Invariant | Rule |
+| --- | --- |
+| Runtime | JavaScript ESM, root-based, no `src/`, lowercase filenames and English JSDoc |
+| Infrastructure | no hardcoded host, port, credential, cloud account or vendor-specific function |
+| Library | works without an extension, browser, remote runner, external memory or database |
+| Security | validate URLs, isolate browser contexts, minimize permissions, verify webhooks and audit actions |
+| Recovery | jobs, commands, artifacts and sync operations are idempotent, retryable or explicitly terminal |
+| Evidence | a feature is complete only with an executable contract, deterministic tests and documentation |
+| Distribution | package contents, license, provenance, checksums and registry namespace are verified before release |
+
+## block order
+
+| Block | Scope | Current state | Exit evidence |
+| --- | --- | --- | --- |
+| 1 | audit and governance | active | gap matrix, sources, claims reconciled |
+| 2 | browser agent foundation | complete | snapshots, refs, stale errors, tabs, frames, action results and replay provenance tests |
+| 3 | extension runtime | first slice complete | MV3 unpacked surface, protocol, worker, content bridge and tests |
+| 4 | working set and storage | complete | range chunks, content dedupe, tiered cache, conflict sync and memory capabilities |
+| 5 | runners and execution | complete | provider health, triggers, cancellation, heartbeat and resumable runs |
+| 6 | scraping and context | complete | semantic extraction, crawl budgets, RAG lineage and low-cardinality metrics |
+| 7 | API, MCP and security | complete | request identity, optional auth, secure headers, browser MCP tools and redirect/DNS checks |
+| 8 | bots and integrations | complete | app lifecycle, command scopes, idempotency, delivery retries and dead letters |
+| 9 | packaging and distribution | partial; registry slice verified for 1.7.0 | reproducible extension, desktop, mobile, n8n and binary artifacts |
+| 10 | product surfaces and operations | first slice complete | desktop, mobile, n8n and operator control contracts; observability, retention and threat model remain |
+| 11 | cross-runtime compatibility | first slice complete | Node, Bun and Deno root probe; browser worker, extension and package tree-shaking checks remain |
+| 12 | release gates | active | deterministic checks, docs, clean diffs and claim/code parity |
+
+## execution method
+
+Each block follows the same loop:
+
+1. Compare the requested behavior with primary repositories or platform documentation.
+2. Record the gap and the intended boundary in `docs/gapmatrix.md`.
+3. Define the smallest transport-neutral contract.
+4. Implement grouped logic in the domain folder without adding a vendor dependency unless required.
+5. Add deterministic tests with fake transports and no real credentials.
+6. Update API docs, README claims, changelog and `todo.md`.
+7. Run format, syntax, tests, package and security checks.
+8. Commit and push the block before starting the next one.
+
+## current implementation
+
+Version 1.7 contains the first bot and integration lifecycle slice after browser, storage, runners, scraping and API hardening. It adds app installation and scope state, command authorization, idempotent bot execution, retryable webhook delivery and dead-letter records. The registry publication slice for 1.7.0 is verified for GitHub npm, GHCR, Maven, NuGet and RubyGems; public npmjs remains blocked because the owner account or scope still rejects the configured publication with HTTP 404. The first product surface slice adds desktop, mobile, n8n, operator control, operational policy and framework-neutral HTTP contracts. The first cross-runtime slice now validates the root on Node, Bun and Deno, while browser worker and extension import checks remain.
+
+## evidence sources
+
+The current plan is grounded in the repository's [`comparativeaudit.md`](comparativeaudit.md), [`gapmatrix.md`](gapmatrix.md), the supplied conclusions documents, and primary platform or project sources listed there. External claims remain evidence-backed notes; they do not become product promises until the corresponding block has executable tests.

package/docs/enginearchitecture.md

@@ -0,0 +1,83 @@
+# saddle engine architecture
+
+## purpose
+
+Saddle is a library first. The engine turns a serializable job into a temporary working set, runs the job through a selected provider, commits the result to a storage adapter, and leaves an event trail for observation.
+
+The engine does not claim that remote storage is physical vram. It models the same bytes under two usage flags: `keep` for persistent state and `process` for a temporary working set. Capacity, latency, durability, and availability remain properties of the selected backend.
+
+## root layout
+
+The project has no `src` folder. The root is the map of the engine.
+
+| folder | responsibility |
+|---|---|
+| `core` | errors, ids, clock, events, and tracing primitives |
+| `domain` | jobs, sessions, artifacts, providers, and runtime records |
+| `storage` | storage adapter contract, local backend, and checksums |
+| `memory` | working set preparation, sync, and cleanup |
+| `runners` | provider factories and deterministic scheduling |
+| `runtime` | engine orchestration and output encoding |
+| `cli` | explicit command surface with local error handling |
+| `tests` | local deterministic tests without credentials |
+| `examples` | small runnable integration examples |
+
+All internal file names are lowercase and contain no underscore or hyphen. Related logic stays grouped and each module remains small enough to reason about in isolation.
+
+## public contracts
+
+The public contract uses plain objects and factory functions. The engine never requires a class instance from a vendor adapter.
+
+| contract | responsibility | open choice |
+|---|---|---|
+| `storageadapter` | put, get, head, delete, and list artifacts | local, s3 compatible, webdav, hf, kaggle, or another backend |
+| `localmemory` | prepare, sync, and cleanup a working set | tmpfs, mmap, sqlite, r2, or a remote bridge |
+| `scheduler` | select the first available provider by stable priority | github, forgejo, gitea, gitlab, hf, kaggle, or custom |
+| `engine` | coordinate the lifecycle and emit events | library, cli, browser, desktop, mobile, or service |
+| `validatesession` | accept a versioned session record | browser capture, replay, or external event source |
+
+## execution lifecycle
+
+```text
+jobqueued
+  -> jobpreparing
+  -> runnerselected
+  -> jobrunning
+  -> jobsyncing
+  -> storagecommitted
+  -> jobcompleted
+```
+
+Failures emit `jobfailed` with an error code, retryability, and a short message. Cleanup runs in a `finally` path after a working set is created. No provider owns retry policy; retry stays at the scheduler and orchestration boundary.
+
+## operation modes
+
+The same contracts support paired modes. A mode can exist without its pair, and an application can add the pair without changing the engine core.
+
+| family | without | with |
+|---|---|---|
+| library | import the public factories | embed the engine inside an application |
+| cli | use the local command surface | connect a custom dispatch adapter |
+| binary | run the node entry point | package through a compiler or container |
+| memory | internal working set | external, physical, vectorized, or library memory |
+| file | internal artifact | external storage or content delivery |
+| browser | headless job definition | capture and replay adapter |
+| network | local deterministic job | remote provider and storage adapter |
+
+The first cut implements library, cli, binary entry point, internal memory, and internal file. The other modes are extension points, not hardcoded promises.
+
+## infrastructure rules
+
+The engine uses no Netlify Functions and no Vercel Functions. A deployment can use an open Node server, a container, a worker, a forge workflow, or another host that can run the package.
+
+The core does not hardcode a host or port. A future server adapter must receive both as configuration. A temporary session port must be drawn and locked by the caller before it is passed to the adapter. Credentials are never embedded in code and every external service is replaceable through a contract.
+
+Database work remains an adapter concern. Prisma, Drizzle, MySQL2, and other compatible implementations may persist manifests, sessions, chunks, and jobs. Realtime remains an adapter concern and may use Socket or another open transport.
+
+## security boundary
+
+The core does not execute untrusted network code and does not expose credentials to job handlers. A remote runner adapter must declare its permissions, network policy, and cleanup behavior. Captcha solving, anti detection, and browser control are separate opt in surfaces and are not silently enabled by the engine.
+
+## release rule
+
+Every feature is added as a small root module, tested without credentials, and committed after the package check succeeds. External backends arrive one at a time. The public factory signatures stay stable while adapters evolve.

package/docs/featureaudit.md

@@ -0,0 +1,63 @@
+# saddle feature audit
+
+This audit compares the current repository with the project README and the additional conclusions file. The repository is a library engine. It does not claim that a contract stub is the same as a production integration.
+
+## foundation and engine
+
+| feature | status | evidence or gap |
+|---|---|---|
+| root based JavaScript library | complete | no `src`; ESM package; grouped domains; lowercase paths |
+| memory bridge | complete | load, persist, release, safe load, targets, transforms |
+| memory modes | complete | internal, external, physical, vectorized, library contracts |
+| job engine | complete | prepare, process, sync, cleanup, runner selection, events |
+| chunked artifacts | complete | local and chunked adapters; checksums; manifest contracts |
+| sessions | partial | JSONL save, load, validation, replay; no real browser capture runtime |
+| crawler | partial | bounded BFS, same domain, robots, normalization, cache; no sitemap or adaptive renderer |
+| universal API | partial | web request handler and public library helpers; no production task service with durable polling API |
+| MCP | partial | optional tools contract; no external MCP SDK or packaged remote server mode |
+| queue | partial | in memory and file persistence; no SQLite queue with crash recovery semantics |
+| errors and retry | complete | taxonomy, recovery hints, retry policy, circuit breaker |
+
+## browser, captcha, and proxy
+
+| feature | status | decision |
+|---|---|---|
+| browser agent | partial | injected adapter only; Playwright, Brave, CDP, screenshots, and real input are not bundled |
+| session fingerprint | partial | coherent profile and proxy binding exist; no TLS or HTTP2 patch layer |
+| stealth patches | deferred | browser and network evasion is not silently embedded in a general library |
+| proxy pool | complete | least used selection, health failures, graveyard, revive |
+| captcha detection | complete | explicit contract, review pause, solver injection, evidence hash |
+| captcha bypass | not implemented by design | no automatic challenge bypass or token abuse is shipped |
+
+## storage, database, and compute
+
+| feature | status | gap |
+|---|---|---|
+| GitHub Contents | partial | adapter is injectable; no live GitHub App authentication or release asset flow |
+| S3 compatible and WebDAV | partial | generic file hosting adapter exists; no provider specific signing or multipart upload |
+| GitLab, Forgejo, Gitea, HF, Kaggle, ModelScope, Terabox, Telegram, Discord | partial | some forge workflow templates exist; provider storage and bot adapters are not complete |
+| Prisma, Drizzle, MySQL2 | partial | neutral contracts and query adapters exist; no deployed schema, migrations, or database runtime |
+| file as compute | partial | manifests and local working sets exist; no durable chunk table, job table, or real rebuild worker |
+| runner farm | partial | workflow manifests exist; no live first free runner dispatcher across accounts |
+| Docker and compose | partial | safe templates exist; no built and published image or runtime acceptance test |
+
+## productization
+
+| feature | status | gap |
+|---|---|---|
+| npm package metadata | partial | package is publishable but still version `0.2.0` |
+| GitHub release | missing | no release workflow, tag, changelog, or release assets for `1.0.0` |
+| npm publishing | missing | no publish workflow; `NPM_TOKEN` must be configured as a GitHub secret |
+| GitHub Packages and GHCR | missing | no package or image publishing jobs |
+| Maven, NuGet, RubyGems, PyPI | missing | no language specific wrappers or trusted publishing jobs |
+| jsDelivr, UNPKG, esm.sh | partial | URLs are documented; no release verification or SRI manifest |
+| browser extension | partial | surface manifest only; no CRX source or permissions manifest |
+| mobile and desktop apps | partial | target manifests only; no Tauri, Capacitor, Android, or iOS project |
+| site and per site database | missing | no `web` application, Hono server, Drizzle schema, Prisma schema, or site deployment adapter |
+| multi platform app identity | partial | generic bot and forge contracts; no OAuth or GitHub App installation flow |
+
+## safety and release decision
+
+The next production priority is not to add more vendor claims. It is to close the publish path: version metadata, changelog, release workflow, npm provenance, package smoke test, and a provider neutral durable job schema. Browser stealth, captcha bypass, account farming, and storage abuse are not release blockers because they are not safe defaults for this library.
+
+The exposed npm token is treated as compromised. It must be revoked before any publication. A new token must be stored as the GitHub repository secret `NPM_TOKEN` or replaced by npm trusted publishing through GitHub Actions OIDC. No token belongs in source, commit history, command output, or chat.