@wenathlan/saddle 1.8.8 → 1.8.9

package/docs/gapmatrix.md

@@ -19,11 +19,11 @@ This matrix turns the supplied README and conclusions into implementation decisi
 | Browser agent | Implemented injected action adapter for navigate, click, type, screenshot, DOM, title, scroll and command batches | Vendor-neutral action results and bounded action batches are public; optional Playwright provider is isolated behind `browser-playwright` | P1 | Keep the adapter boundary; browser binaries and credentials remain caller-owned |
 | Browser snapshots | Implemented public contract | Snapshot ids, bounded elements, stable refs, stale checks and diffs are covered by deterministic tests | P0 | Reuse the contract from MCP and extension transport |
 | Session replay | Implemented | Replay restores caller-owned window, tab and frame context before actions; context identifiers are validated and counted | P1 | Keep browser selection and restoration in injected adapters |
-| Extension runtime | Manifest V3 manifest, service worker, content bridge, popup, snapshot diffs, context metadata and deterministic build artifact are implemented | Cross-browser manifests remain unbundled | P2 | Keep a pure JavaScript MV3 reference surface with minimal permissions |
+| Extension runtime | TypeScript-first Manifest V3 source, service worker, content bridge, popup, snapshot diffs, context metadata and deterministic JavaScript build artifact are implemented | Cross-browser manifests remain unbundled | P2 | Keep the compiled MV3 artifact minimal and keep cross-browser profiles caller-owned |
 | Extension messaging | Versioned envelope, correlation id, timeout, sender metadata and error response contract are implemented | Long-lived ports remain caller-owned | P1 | Keep transport-neutral messages and explicit runtime adapters |
 | Service worker resilience | Implemented contract slice | Pending command envelopes, attempt metadata and snapshot summaries persist through injected storage; resume remains explicit and user-owned | P0 | Rehydrate metadata on startup and never replay a command without an explicit caller action |
 | Permissions | Contract slice | `permissionpolicy` keeps the base permissions minimal and optional escalation caller-owned | P0 | Start with `storage` and no broad host permissions; make host access caller-configured |
-| Content isolation | Implemented read-only page-to-extension boundary | The page world cannot invoke extension commands; richer page facts remain bounded | P1 | Keep `pagebridge.js` read-only, token-correlated and caller-controlled |
+| Content isolation | Implemented read-only page-to-extension boundary | The page world cannot invoke extension commands; richer page facts remain bounded | P1 | Keep the compiled page bridge read-only, token-correlated and caller-controlled |
 | Task agent | Partial | Jobs, workflows and bot commands exist, but no browser task planner or tool registry | P1 | Reuse workflow, trigger and bot contracts; add browser task commands only after snapshots |
 | MCP | Implemented scrape, crawl, batch, extract and serialize tools with JSON-RPC handling | No browser snapshot or browser action MCP tools | P1 | Add browser tools as an optional adapter over the same snapshot/action contracts |
 | API security | Implemented URL protocol and private hostname/IP checks | Request envelopes, optional authorization, security headers, redirect bounds and injected DNS resolution checks are now available | P0 | Keep credentials caller-owned and reject private or rebinding targets before transport |

package/docs/libraryapi.md

@@ -56,7 +56,7 @@ The `fetcher`, browser adapter, persistence adapter, proxy pool, captcha solver,
 
 ## package surfaces
 
-The package exposes explicit subpaths for `./browser`, `./bot`, `./captcha`, `./memory-engine`, and `./deploy`. Desktop, mobile, and n8n contracts are exported from the root entry; the root entry remains the complete JavaScript API for consumers that prefer one import.
+The package exposes explicit subpaths for `./browser`, `./bot`, `./captcha`, `./memory-engine`, and `./deploy`. Desktop, mobile, target-plan and n8n contracts are exported from the root entry; the root entry remains the complete compiled JavaScript API with generated TypeScript declarations for consumers that prefer one import.
 
 The `./extension` subpath exposes browser-neutral message, snapshot and service-worker routing contracts. The concrete Manifest V3 files live in `extension/`; they are not imported by the core at runtime and do not require Chrome when the library is used as a Node package. The browser surface also exposes snapshots, tab/frame context, action results, bounded action batches and recording through `./browser`.
 

package/docs/release.md

@@ -6,10 +6,10 @@ The release path is intentionally split into source validation, package validati
 
 | step | owner | condition |
 |---|---|---|
-| package version | repository | `package.json` matches the release tag, for example `1.8.8` |
+| package version | repository | `package.json` matches the release tag, for example `1.8.9` |
 | quality gate | GitHub Actions | `npm run pack:check` passes |
-| tag | repository owner | tag `v1.8.8` points to the validated release commit |
-| GitHub release | repository owner | release `v1.8.8` is created from the validated tag |
+| tag | repository owner | tag `v1.8.9` points to the validated release commit |
+| GitHub release | repository owner | release `v1.8.9` is created from the validated tag |
 | GitHub Packages | GitHub Actions | `publishgithubnpm.yml`, `publishghcr.yml`, `publishmaven.yml`, `publishnuget.yml`, and `publishrubygems.yml` use `GITHUB_TOKEN` |
 | public npmjs | owner-managed GitHub Actions secret | `publishnpmjs.yml` uses `NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}` and derives the version from the release tag or latest release in manual maintenance runs |
 | extension zip | GitHub Actions | `buildextension.yml` derives the version from the release tag, validates the unpacked artifact and attaches `saddle-extension-<version>.zip` |
@@ -22,8 +22,8 @@ The npm token previously sent in chat is compromised and must not be used. GitHu
 
 ```text
 npm run pack:check
-git tag v1.8.8
-git push origin v1.8.8
+git tag v1.8.9
+git push origin v1.8.9
 ```
 
 The release-created event is the publication and extension-asset trigger for the release workflows. A dry-run verifies package shape and local tests, but cannot verify registry ownership, Trusted Publisher configuration, package scope authorization, package visibility or browser-store submission; those remain settings controlled by the owner.

package/docs/releaseassets.md

@@ -4,7 +4,7 @@ The Node-only release adapter creates deterministic metadata for caller-selected
 
 ```bash
 npm run release:assets -- \
-  --version 1.8.8 \
+  --version 1.8.9 \
   --output build/release \
   --artifact build/saddle.tgz \
   --build-type caller-build \

package/docs/reorganization-1.8.9.md

@@ -0,0 +1,28 @@
+# Reorganization 1.8.9
+
+## Scope
+
+Version 1.8.9 converts the active engine and its deterministic test surface to a root-based TypeScript source layout. The source tree does not gain `src/`; generated JavaScript, declarations, source maps and target plans are created in ignored `dist/` or `build/` directories by local scripts and release workflows.
+
+## Ownership groups
+
+| Group | Canonical source context | Compatibility rule |
+| --- | --- | --- |
+| Public engine | `index.ts`, `library`, `domain`, `core`, `runtime` | Root exports keep their public names and emit stable `dist/*.js` paths. |
+| Storage and memory | `storage`, `memory`, `persistence` | Physical, vector, remote and in-process adapters remain caller-owned. |
+| Acquisition | `scrape`, `browser`, `captcha`, `proxy` | Scrape, crawl, browser and evidence contracts remain separate where their capabilities differ. |
+| Operations | `queue`, `dispatch`, `workflow`, `runners`, `observability` | Retry, circuit, scheduling and resume contracts stay grouped by lifecycle responsibility. |
+| Delivery | `packager`, `release`, `binary`, `surfaces`, `extension`, `cli` | Delivery modules describe plans or build adapters; they do not own store credentials or signing keys. |
+| Web | `web/App.tsx`, `web/components`, `web/pages`, `web/lib`, `web/contexts`, `web/hooks` | The static React surface remains root based and TypeScript. The dynamic debug collector is an explicit `@ts-nocheck` browser instrumentation boundary. |
+
+## Build boundary
+
+The project uses a project-local TypeScript 7 compiler. `npm run build:engine` removes and regenerates `dist/`; package `main`, `module`, `browser`, `types`, `bin` and all declared export targets point at that generated output. The npm package includes `dist`, but the Git repository does not commit generated output.
+
+## Target boundary
+
+Application, computer, desktop, mobile, Android, iOS, browser, extension, web, CLI, binary, LibreOffice, MCP, VSIX and container formats are represented by declarative manifests. The workflow produces plans for each target and uploads them as CI artifacts. Actual Android SDK, Xcode, desktop installer, browser-store, LibreOffice and signing toolchains remain caller-selected adapters because the core cannot safely embed platform credentials or vendor infrastructure.
+
+## Verification
+
+The active Node contract has 98 passing tests. The preserved legacy scrape TypeScript surface has 69 passing Vitest tests. Web `tsc`, Pages build, format checks, package dry-run and high-severity audit remain release gates. A target plan is accepted only when it contains the release version, canonical compiled entry, output path, caller-managed credentials marker and reproducible metadata.

package/docs/toolchainresearch-1.8.9.md

@@ -0,0 +1,18 @@
+# Toolchain research 1.8.9
+
+## Date
+
+The migration baseline is **2026-08-13**.
+
+## Verified sources
+
+| Area | Verified finding | Source |
+| --- | --- | --- |
+| TypeScript | The official TypeScript download page states that TypeScript 7.0 is currently available and recommends a project-local npm installation for reproducible lockfiles. | [TypeScript download](https://www.typescriptlang.org/download/) |
+| TypeScript release | The official TypeScript team blog announces TypeScript 7.0 as the current native compiler release. | [Announcing TypeScript 7.0](https://devblogs.microsoft.com/typescript/announcing-typescript-7-0/) |
+| Node.js | Node.js 26.7.0 is the current release in the v26 line as of 2026-08-05. | [Node.js 26.7.0](https://nodejs.org/en/blog/release/v26.7.0) |
+| Node.js support | The official release table identifies v26 as Current and v24 as LTS; production targets should remain caller-selectable between supported Current and LTS runtimes. | [Node.js releases](https://nodejs.org/en/about/previous-releases) |
+
+## Migration decision
+
+The root project will use a project-local TypeScript compiler pinned in `package.json` and `package-lock.json`. The engine target remains Node.js `>=26.7.0`, while target manifests may declare a different runtime only when the target adapter and workflow provide an explicit compatibility contract. Generated JavaScript, declaration files, source maps and bundles remain build output and are not committed as source.

package/extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Saddle browser bridge",
-  "version": "1.8.8",
+  "version": "1.8.9",
   "description": "User initiated page snapshots through the Saddle browser contract.",
   "minimum_chrome_version": "110",
   "permissions": ["activeTab", "scripting", "storage"],

package/package.json

@@ -1,15 +1,16 @@
 {
   "name": "@wenathlan/saddle",
-  "version": "1.8.8",
+  "version": "1.8.9",
   "description": "binary computing engine that turns distributed storage into a publishable working set",
   "type": "module",
   "private": false,
   "license": "GPL-3.0-only",
   "author": "Wenathlan",
   "sideEffects": false,
-  "main": "./index.js",
-  "module": "./index.js",
-  "browser": "./index.js",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "browser": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "packageManager": "npm@12.0.2",
   "publishConfig": {
     "access": "public"
@@ -42,80 +43,51 @@
     }
   },
   "bin": {
-    "saddle": "./cli/main.js"
+    "saddle": "./dist/cli/main.js"
   },
   "exports": {
-    ".": "./index.js",
-    "./memory": "./memory/bridge.js",
-    "./memory-node": "./memory/bridge.js",
-    "./memory-engine": "./memory/engine.js",
-    "./storage": "./storage/index.js",
-    "./storage-node": "./storage/local.js",
-    "./runners": "./runners/scheduler.js",
-    "./sessions": "./domain/sessions.js",
-    "./modes": "./modes/resolve.js",
-    "./mode": "./modes/matrix.js",
-    "./browser": "./browser/index.js",
-    "./browser-playwright": "./browser/playwright.js",
-    "./bot": "./bot/bot.js",
-    "./captcha": "./captcha/contract.js",
-    "./deploy": "./deploy/index.js",
-    "./extension": "./extension/index.js",
-    "./server-node": "./server/node.js",
-    "./sessions-file": "./sessions/file.js",
-    "./sessions-store": "./sessions/store.js",
-    "./queue-persistent": "./queue/persistent.js",
-    "./captcha-evidence": "./captcha/evidence.js",
-    "./hash": "./core/hash.js",
-    "./release-assets": "./release/assets.js",
-    "./worker": "./runtime/worker.js"
+    ".": "./dist/index.js",
+    "./memory": "./dist/memory/bridge.js",
+    "./memory-node": "./dist/memory/bridge.js",
+    "./memory-engine": "./dist/memory/engine.js",
+    "./storage": "./dist/storage/index.js",
+    "./storage-node": "./dist/storage/local.js",
+    "./runners": "./dist/runners/scheduler.js",
+    "./sessions": "./dist/domain/sessions.js",
+    "./modes": "./dist/modes/resolve.js",
+    "./mode": "./dist/modes/matrix.js",
+    "./browser": "./dist/browser/index.js",
+    "./browser-playwright": "./dist/browser/playwright.js",
+    "./bot": "./dist/bot/bot.js",
+    "./captcha": "./dist/captcha/contract.js",
+    "./deploy": "./dist/deploy/index.js",
+    "./extension": "./dist/extension/index.js",
+    "./server-node": "./dist/server/node.js",
+    "./sessions-file": "./dist/sessions/file.js",
+    "./sessions-store": "./dist/sessions/store.js",
+    "./queue-persistent": "./dist/queue/persistent.js",
+    "./captcha-evidence": "./dist/captcha/evidence.js",
+    "./hash": "./dist/core/hash.js",
+    "./release-assets": "./dist/release/assets.js",
+    "./worker": "./dist/runtime/worker.js"
   },
   "files": [
-    "core",
-    "domain",
-    "memory",
-    "runners",
-    "runtime",
-    "storage",
-    "sessions",
-    "modes",
-    "adapters",
-    "persistence",
-    "queue",
-    "dispatch",
-    "scrape",
-    "api",
-    "mcp",
-    "browser",
-    "proxy",
-    "captcha",
-    "ai",
-    "webhook",
-    "surfaces",
-    "library",
-    "server",
-    "binary",
-    "format",
-    "packager",
-    "bot",
-    "protocol",
-    "workflow",
-    "cli",
-    "extension",
-    "release",
-    "index.js",
+    "dist",
+    "extension/manifest.json",
     "docs",
-    "examples",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
-    "check": "node --check index.js && node --check runtime/engine.js && node --check runtime/retry.js && node --check cli/main.js && node --check extension/protocol.js && node --check extension/serviceworker.js && node --check extension/worker.js && node --check extension/content.js && node --check extension/pagebridge.js && node --check extension/popup.js && node --check extension/permissions.js && node --check extension/build.js && node --check release/assets.js && node --check sessions/replay.js && node --check browser/recorder.js && node --check scrape/normalize.js && node --check scrape/crawl.js",
-    "formatcheck": "node format/check.js",
-    "test": "node --test tests/*.test.js",
-    "run": "node cli/main.js",
-    "extension:build": "node extension/build.js",
-    "release:assets": "node release/assets.js",
+    "build:engine": "node tests/scripts/buildengine.mjs",
+    "check": "npm run build:engine && node --check dist/index.js && node --check dist/runtime/engine.js && node --check dist/cli/main.js && node --check dist/extension/serviceworker.js && node --check dist/release/assets.js",
+    "formatcheck": "node --import tsx format/check.ts",
+    "test": "npm run build:engine && node --import tsx --test tests/engine.test.ts tests/extension.test.ts tests/package.test.ts tests/release.test.ts",
+    "test:legacy": "vitest run tests/agent-utils.test.ts tests/cache.test.ts tests/chunking.test.ts tests/core.test.ts tests/errors.test.ts tests/llms-txt.test.ts tests/middleware.test.ts tests/proxy.test.ts tests/tokens.test.ts",
+    "run": "npm run build:engine && node dist/cli/main.js",
+    "extension:build": "npm run build:engine && node dist/extension/build.js",
+    "release:assets": "npm run build:engine && node dist/release/assets.js",
+    "target:manifest": "npm run build:engine && node dist/packager/targetcli.js",
     "pack:check": "npm run check && npm run formatcheck && npm test && npm pack --dry-run",
     "prepublishOnly": "npm run pack:check",
     "web:dev": "vite --config web/vite.config.ts --host",
@@ -151,17 +123,31 @@
     "@radix-ui/react-toggle": "^1.1.10",
     "@radix-ui/react-toggle-group": "^1.1.11",
     "@radix-ui/react-tooltip": "^1.2.8",
+    "@tailwindcss/typography": "^0.5.15",
+    "@tailwindcss/vite": "^4.1.3",
+    "@types/express": "4.17.21",
+    "@types/google.maps": "^3.58.1",
+    "@types/node": "^24.7.0",
+    "@types/react": "^19.2.1",
+    "@types/react-dom": "^19.2.1",
+    "@vitejs/plugin-react": "^5.0.4",
+    "add": "^2.0.6",
+    "autoprefixer": "^10.4.20",
     "axios": "^1.12.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
     "embla-carousel-react": "^8.6.0",
+    "esbuild": "^0.25.0",
     "express": "^4.21.2",
     "framer-motion": "^12.23.22",
     "input-otp": "^1.4.2",
+    "jsdom": "26.1.0",
     "lucide-react": "^0.453.0",
     "nanoid": "^5.1.5",
     "next-themes": "^0.4.6",
+    "postcss": "^8.4.47",
+    "prettier": "^3.6.2",
     "react": "^19.2.1",
     "react-day-picker": "^9.11.1",
     "react-dom": "^19.2.1",
@@ -171,29 +157,16 @@
     "sonner": "^2.0.7",
     "streamdown": "^1.4.0",
     "tailwind-merge": "^3.3.1",
-    "tailwindcss-animate": "^1.0.7",
-    "vaul": "^1.1.2",
-    "wouter": "^3.3.5",
-    "zod": "^4.1.12",
-    "@tailwindcss/typography": "^0.5.15",
-    "@tailwindcss/vite": "^4.1.3",
-    "@types/express": "4.17.21",
-    "@types/google.maps": "^3.58.1",
-    "@types/node": "^24.7.0",
-    "@types/react": "^19.2.1",
-    "@types/react-dom": "^19.2.1",
-    "@vitejs/plugin-react": "^5.0.4",
-    "add": "^2.0.6",
-    "autoprefixer": "^10.4.20",
-    "esbuild": "^0.25.0",
-    "postcss": "^8.4.47",
-    "prettier": "^3.6.2",
     "tailwindcss": "^4.1.14",
+    "tailwindcss-animate": "^1.0.7",
     "tsx": "^4.19.1",
     "tw-animate-css": "^1.4.0",
-    "typescript": "5.6.3",
+    "typescript": "7.0.2",
+    "vaul": "^1.1.2",
     "vite": "^7.1.7",
     "vite-plugin-manus-runtime": "^0.0.58",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.10",
+    "wouter": "^3.3.5",
+    "zod": "^4.1.12"
   }
 }

package/adapters/forge.js

@@ -1,16 +0,0 @@
-/**
- * forge adapter defines the common dispatch and artifact surface for compatible forges.
- */
-import { transport } from "./transport.js";
-
-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 }; }
-  };
-}

package/adapters/github.js

@@ -1,19 +0,0 @@
-/**
- * github adapter uses caller supplied credentials and base url configuration.
- */
-import { transport } from "./transport.js";
-
-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(); }
-  };
-}

package/adapters/gitlab.js

@@ -1,10 +0,0 @@
-/**
- * gitlab adapter keeps project addressing and token ownership outside the package.
- */
-import { forgeadapter } from "./forge.js";
-
-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` }); } };
-}

package/adapters/socket.js

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

package/adapters/transport.js

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

package/ai/chunk.js

@@ -1,22 +0,0 @@
-/**
- * markdown chunking preserves heading paths and uses paragraph boundaries before hard cuts.
- */
-import { estimatetokens } from "./tokens.js";
-
-export function chunkmarkdown(markdown, options = {}) {
-  const maxtokens = options.maxtokens ?? 512;
-  const overlap = options.overlaptokens ?? 50;
-  const lines = String(markdown ?? "").split(/\r?\n/);
-  const chunks = [];
-  let headingpath = [];
-  let buffer = [];
-  function flush() { if (!buffer.length) return; const content = buffer.join("\n").trim(); if (content) chunks.push({ content, headingpath: [...headingpath], tokencount: estimatetokens(content, options.model) }); buffer = []; }
-  for (const line of lines) {
-    const heading = line.match(/^(#{1,6})\s+(.+)$/);
-    if (heading) { flush(); const level = heading[1].length; headingpath = headingpath.slice(0, level - 1); headingpath[level - 1] = heading[2].trim(); buffer.push(line); continue; }
-    buffer.push(line);
-    if (estimatetokens(buffer.join("\n"), options.model) > maxtokens) { const last = buffer.pop(); flush(); const overlaptext = buffer.slice(-overlap).join("\n"); buffer = overlaptext ? [overlaptext, last] : [last]; }
-  }
-  flush();
-  return chunks.map((chunk, index) => ({ ...chunk, id: `chunk${index}` }));
-}

package/ai/llmstxt.js

@@ -1,12 +0,0 @@
-/**
- * llms text generation creates compact absolute links for agent consumption.
- */
-export function llmstxt(options = {}) {
-  const title = options.title ?? "saddle";
-  const description = options.description ?? "binary computing engine and browser automation library";
-  const pages = (options.pages ?? []).filter((page) => page?.url && /^https:\/\//.test(page.url)).slice(0, options.limit ?? 100);
-  const lines = [`# ${title}`, `> ${description}`, "", "## pages", "", ...pages.map((page) => `- [${page.title ?? page.url}](${page.url}): ${(page.description ?? "").slice(0, 100)}`)];
-  return `${lines.join("\n")}\n`;
-}
-
-export function llmsfull(options = {}) { return (options.pages ?? []).filter((page) => page?.url && /^https:\/\//.test(page.url)).map((page) => `# ${page.title ?? page.url}\n\nsource: ${page.url}\n\n${page.content ?? ""}`).join("\n\n---\n\n"); }

package/ai/provenance.js

@@ -1,18 +0,0 @@
-/**
- * context provenance links retrieved chunks to source, query and transformation metadata.
- */
-
-/** Creates a serializable retrieval record for an agent context result. */
-export function provenance(input = {}) {
-  if (!input.source && !input.sourceurl) throw new TypeError("provenance requires a source");
-  return { version: 1, source: input.source ?? input.sourceurl, sourceurl: input.sourceurl, documentid: input.documentid, query: input.query, retrievedat: Number(input.retrievedat ?? Date.now()), chunks: Array.isArray(input.chunks) ? input.chunks.map((chunk, index) => ({ id: String(chunk.id ?? index), contenthash: chunk.contenthash, score: chunk.score === undefined ? undefined : Number(chunk.score), headingpath: chunk.headingpath, tokencount: chunk.tokencount, citation: chunk.citation ?? input.sourceurl })) : [], metadata: { ...(input.metadata ?? {}) } };
-}
-
-/** Merges provenance records while deduplicating chunk identifiers. */
-export function mergeprovenance(records = []) {
-  const valid = records.filter(Boolean);
-  const chunks = [];
-  const seen = new Set();
-  for (const record of valid) for (const chunk of record.chunks ?? []) { const key = `${record.documentid ?? record.source}:${chunk.id}`; if (seen.has(key)) continue; seen.add(key); chunks.push({ ...chunk, source: record.source, documentid: record.documentid }); }
-  return { version: 1, sources: [...new Set(valid.map((record) => record.source))], chunks, mergedat: Date.now() };
-}

package/ai/rag.js

@@ -1,14 +0,0 @@
-/**
- * rag manifests connect chunks to embedding stores without forcing a vendor client.
- */
-export async function ragmanifest(input = {}) {
-  const chunks = input.chunks ?? [];
-  const unique = [];
-  const hashes = new Set();
-  for (const chunk of chunks) { const hash = await hashtext(chunk.content); if (hashes.has(hash)) continue; hashes.add(hash); unique.push({ ...chunk, contenthash: hash, documentid: hash.slice(0, 16), metadata: { ...(input.metadata ?? {}), ...(chunk.metadata ?? {}) } }); }
-  return { documentid: (await hashtext(input.source ?? unique.map((chunk) => chunk.content).join("\n"))).slice(0, 16), source: input.source, chunks: unique, embeddingmodel: input.embeddingmodel, embeddingdimensions: input.embeddingdimensions, createdat: Date.now() };
-}
-
-export function vectorrecord(chunk, vector, options = {}) { return { id: `${chunk.documentid}-${chunk.id}`, vector, metadata: { headingpath: chunk.headingpath, contenthash: chunk.contenthash, sourceurl: options.sourceurl, tokencount: chunk.tokencount, contenttype: options.contenttype ?? "text", language: options.language ?? "en", embeddingmodel: options.embeddingmodel, embeddingdimensions: vector?.length } }; }
-
-async function hashtext(text) { const bytes = new TextEncoder().encode(String(text)); if (globalThis.crypto?.subtle) { const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes); return [...new Uint8Array(digest)].map((value) => value.toString(16).padStart(2, "0")).join(""); } return Array.from(bytes).map((value) => value.toString(16).padStart(2, "0")).join("").slice(0, 64).padEnd(64, "0"); }

package/api/auth.js

@@ -1,13 +0,0 @@
-/**
- * api authorization delegates token verification to the caller and never stores credentials.
- */
-
-/** Authorizes a request through an injected verifier or returns an anonymous principal. */
-export async function authorize(request, options = {}) {
-  const token = request?.headers?.get?.("authorization")?.replace(/^Bearer\s+/i, "") ?? request?.headers?.get?.("x-api-key");
-  if (typeof options.verify !== "function") return { authenticated: false, subject: "anonymous", tokenpresent: Boolean(token) };
-  if (!token) return { authenticated: false, subject: "anonymous", tokenpresent: false };
-  const principal = await options.verify(token, request);
-  if (!principal) { const error = new Error("request is not authorized"); error.code = "UNAUTHORIZED"; throw error; }
-  return { authenticated: true, subject: String(principal.subject ?? principal.id ?? "caller"), claims: { ...(principal.claims ?? {}) } };
-}

package/api/control.js

@@ -1,33 +0,0 @@
-/**
- * control service exposes operator controls through Web Request and Response without selecting a web framework.
- */
-
-import { authorize } from "./auth.js";
-import { requestcontext } from "./contracts.js";
-import { errorresponse, jsonresponse } from "./http.js";
-import { controlsurface } from "../surfaces/controls.js";
-
-/** Creates a framework-neutral HTTP handler for an injected operator control surface. */
-export function controlservice(options = {}) {
-  const controls = options.controls ?? controlsurface({ adapters: options.adapters, audit: options.audit });
-  const path = String(options.path ?? "/v1/control");
-  if (!path.startsWith("/")) throw new TypeError("control service path must be absolute");
-
-  async function handle(request) {
-    const context = requestcontext(request, { path });
-    try {
-      await authorize(request, { verify: options.verify });
-      const url = new URL(request.url ?? request);
-      if (url.pathname !== path) return errorresponse("NOT_FOUND", "control route not found", { status: 404, requestid: context.requestid });
-      if (request.method === "GET") return jsonresponse({ ...controls.describe(), requestid: context.requestid });
-      if (request.method !== "POST") return errorresponse("METHOD_NOT_ALLOWED", "control route requires GET or POST", { status: 405, requestid: context.requestid });
-      const input = typeof request.json === "function" ? await request.json() : {};
-      const result = await controls.execute(input);
-      return jsonresponse({ requestid: context.requestid, data: result }, { status: result.ok ? 200 : 409 });
-    } catch (error) {
-      return errorresponse(error?.code ?? "CONTROL_REQUEST_FAILED", error?.message ?? error, { status: error?.code === "UNAUTHORIZED" ? 401 : 400, requestid: context.requestid });
-    }
-  }
-
-  return { path, controls, handle };
-}

package/api/rate.js

@@ -1,31 +0,0 @@
-/**
- * token bucket rate limiting supports global user and domain keys.
- */
-export function ratebucket(options = {}) {
-  const capacity = options.capacity ?? 10;
-  const refill = options.refill ?? capacity;
-  const interval = options.interval ?? 60000;
-  const buckets = new Map();
-  function consume(key, cost = 1) {
-    const now = Date.now();
-    const previous = buckets.get(key) ?? { tokens: capacity, at: now };
-    const tokens = Math.min(capacity, previous.tokens + ((now - previous.at) / interval) * refill);
-    if (tokens < cost) return { allowed: false, retryafter: Math.ceil(((cost - tokens) / refill) * interval) };
-    buckets.set(key, { tokens: tokens - cost, at: now });
-    return { allowed: true, retryafter: 0 };
-  }
-  return { consume, clear() { buckets.clear(); } };
-}
-
-export function ratelimiter(options = {}) {
-  const global = ratebucket(options.global ?? { capacity: 1000, refill: 1000 });
-  const user = ratebucket(options.user ?? { capacity: 100, refill: 100 });
-  const domain = ratebucket(options.domain ?? { capacity: 10, refill: 10 });
-  return {
-    check(input = {}) {
-      const checks = [[global, "global"], [user, `user:${input.user ?? "anonymous"}`], [domain, `domain:${input.domain ?? "unknown"}`]];
-      for (const [bucket, key] of checks) { const result = bucket.consume(key); if (!result.allowed) return { allowed: false, retryafter: result.retryafter, scope: key }; }
-      return { allowed: true, retryafter: 0 };
-    }
-  };
-}