@wenathlan/saddle 1.8.1

package/modes/modes.js

@@ -0,0 +1,16 @@
+/**
+ * mode profiles describe paired operation surfaces without changing engine contracts.
+ */
+const names = ["computer", "library", "application", "browser", "desktop", "mobile", "extension", "cli", "binary", "internet", "physicalfile", "vectorfile", "visible", "headless"];
+
+export function modeprofile(options = {}) {
+  const enabled = new Set(options.enabled ?? ["library", "cli", "binary"]);
+  return Object.fromEntries(names.map((name) => [name, { name, enabled: enabled.has(name), paired: Boolean(options.paired?.includes(name)) }]));
+}
+
+export function librarymode(factory) { return { name: "library", start: factory, stop: async () => undefined }; }
+export function climode(run) { return { name: "cli", run }; }
+export function binarymode(run) { return { name: "binary", run }; }
+export function browsermode(adapter) { return { name: "browser", adapter }; }
+export function headlessmode(adapter) { return { name: "headless", adapter }; }
+export function computemode(adapter) { return { name: "computer", adapter }; }

package/modes/resolve.js

@@ -0,0 +1,39 @@
+/**
+ * mode resolver selects open defaults while preserving every caller choice.
+ */
+import { modeaxes, validatemode } from "./matrix.js";
+
+/** Resolves an execution profile without starting a process or opening a socket. */
+export function resolvemode(options = {}) {
+  const profile = {
+    execution: options.execution ?? "library",
+    runtime: options.runtime ?? "unknown",
+    memory: options.memory ?? "internal",
+    file: options.file ?? "internal",
+    dependency: options.dependency ?? "internal",
+    visibility: options.visibility ?? "headless",
+    pair: options.pair ?? "without"
+  };
+  for (const [axis, value] of Object.entries(profile)) if (!validatemode(axis, value)) throw new TypeError(`unsupported mode ${axis}:${value}`);
+  return { ...profile, capabilities: modecapabilities(profile) };
+}
+
+/** Returns stable capabilities for adapters and diagnostics. */
+export function modecapabilities(profile) {
+  return {
+    library: profile.execution === "library" || profile.execution === "application",
+    browser: profile.execution === "browser" || profile.execution === "extension" || profile.runtime === "browser" || profile.runtime === "worker",
+    cli: profile.execution === "cli" || profile.execution === "binary",
+    physicalmemory: profile.memory === "physical",
+    vectorizedmemory: profile.memory === "vectorized",
+    externalmemory: profile.memory === "external",
+    externalfile: profile.file === "external",
+    externaldependency: profile.dependency === "external",
+    visible: profile.visibility === "visible"
+  };
+}
+
+/** Applies one profile to a caller supplied operation. */
+export async function withmode(options, operation) { if (typeof operation !== "function") throw new TypeError("mode operation is required"); return operation(resolvemode(options)); }
+
+export { modeaxes };

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@wenathlan/saddle",
+  "version": "1.8.1",
+  "description": "binary computing engine that turns distributed storage into a publishable working set",
+  "type": "module",
+  "license": "GPL-3.0-only",
+  "publishConfig": { "access": "public" },
+  "repository": { "type": "git", "url": "https://github.com/iakadion/saddle.git" },
+  "bugs": { "url": "https://github.com/iakadion/saddle/issues" },
+  "homepage": "https://github.com/iakadion/saddle#readme",
+  "keywords": ["distributed computing", "virtual memory", "runner", "storage", "automation"],
+  "engines": { "node": ">=22" },
+  "bin": { "saddle": "./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",
+    "./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",
+    "./worker": "./runtime/worker.js"
+  },
+  "files": ["core", "domain", "memory", "runners", "runtime", "storage", "sessions", "modes", "adapters", "persistence", "queue", "dispatch", "scrape", "crawl", "api", "mcp", "browser", "proxy", "captcha", "ai", "webhook", "surfaces", "library", "errors", "retry", "server", "binary", "format", "packager", "bot", "protocol", "workflow", "cli", "extension", "index.js", "docs", "examples", "README.md", "LICENSE"],
+  "scripts": {
+    "check": "node --check index.js && node --check runtime/engine.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/popup.js",
+    "formatcheck": "node format/check.js",
+    "test": "node --test tests/*.test.js",
+    "run": "node cli/main.js",
+    "pack:check": "npm run check && npm run formatcheck && npm test && npm pack --dry-run",
+    "prepublishOnly": "npm run pack:check"
+  }
+}

package/packager/manifest.js

@@ -0,0 +1,28 @@
+/**
+ * distribution manifests describe targets without executing a platform command.
+ */
+export function distributionmanifest(options = {}) {
+  if (!options.name || !options.version || !options.entry) throw new TypeError("distribution manifest requires name version and entry");
+  return {
+    name: options.name,
+    version: options.version,
+    entry: options.entry,
+    modes: options.modes ?? ["library", "cli", "binary"],
+    targets: options.targets ?? ["node", "container"],
+    files: options.files ?? [],
+    metadata: options.metadata ?? {}
+  };
+}
+
+export function binaryplan(manifest, options = {}) {
+  return { tool: options.tool ?? "node", command: options.command ?? `node --experimental-sea-config ${options.config ?? "sea.config.json"}`, entry: manifest.entry, targets: options.targets ?? ["linux", "windows", "macos"] };
+}
+
+export function containerplan(manifest, options = {}) {
+  const base = options.base ?? "node:22-alpine";
+  const workdir = options.workdir ?? "/app";
+  const command = options.command ?? ["node", manifest.entry];
+  const lines = [`from ${base}`, `workdir ${workdir}`, "copy package.json package-lock.json ./", "run npm ci --omit=dev", "copy . .", `cmd ${JSON.stringify(command)}`];
+  if (options.port) lines.splice(3, 0, `expose ${options.port}`);
+  return { base, workdir, command, dockerfile: `${lines.join("\n")}\n` };
+}

package/packager/publish.js

@@ -0,0 +1,15 @@
+/**
+ * publish plans describe registry targets without executing a publish or requiring credentials.
+ */
+export function publishplan(manifest, options = {}) {
+  const version = manifest.version;
+  const packageName = manifest.name;
+  return {
+    package: { registry: options.npm ?? "npm", name: packageName, version, command: "npm publish --access public" },
+    github: { repository: options.repository ?? "", packages: true, command: "git push --follow-tags" },
+    container: { registry: options.ghcr ?? "ghcr.io", image: options.image ?? packageName, version, command: "docker push" },
+    cdn: [{ name: "jsdelivr", url: `https://cdn.jsdelivr.net/npm/${packageName}@${version}/index.js` }, { name: "unpkg", url: `https://unpkg.com/${packageName}@${version}/index.js` }, { name: "esm", url: `https://esm.sh/${packageName}@${version}` }]
+  };
+}
+
+export function registrymanifest(manifest, options = {}) { return { name: manifest.name, version: manifest.version, surfaces: ["library", "cli", "binary", "container", ...(options.surfaces ?? [])], registries: ["npm", "github", "ghcr", "jsdelivr", "unpkg", "esm.sh"] }; }

package/persistence/adapter.js

@@ -0,0 +1,8 @@
+/**
+ * persistence adapters keep database and remote state outside the runtime core.
+ */
+export function persistenceadapter(methods) {
+  const required = ["savejob", "getjob", "updatejob", "listjobs", "saveevent", "listevents", "savesession", "readsession", "saveartifact", "getartifact", "savechunk", "getchunks"];
+  for (const name of required) if (typeof methods?.[name] !== "function") throw new TypeError(`persistence adapter requires ${name}`);
+  return methods;
+}

package/persistence/drizzle.js

@@ -0,0 +1,10 @@
+/**
+ * drizzle persistence accepts a small repository object generated by the caller's schema.
+ */
+import { persistenceadapter } from "./adapter.js";
+
+export function drizzlepersistence(repository) {
+  const required = ["savejob", "getjob", "updatejob", "listjobs", "saveevent", "listevents", "savesession", "readsession", "saveartifact", "getartifact", "savechunk", "getchunks"];
+  for (const name of required) if (typeof repository?.[name] !== "function") throw new TypeError(`drizzle repository requires ${name}`);
+  return persistenceadapter(repository);
+}

package/persistence/memory.js

@@ -0,0 +1,26 @@
+/**
+ * memory persistence is the local baseline for tests and offline operation.
+ */
+import { persistenceadapter } from "./adapter.js";
+
+export function memorypersistence() {
+  const jobs = new Map();
+  const events = new Map();
+  const sessions = new Map();
+  const artifacts = new Map();
+  const chunks = new Map();
+  return persistenceadapter({
+    async savejob(job) { jobs.set(job.id, structuredClone(job)); return jobs.get(job.id); },
+    async getjob(id) { return jobs.get(id) ? structuredClone(jobs.get(id)) : null; },
+    async updatejob(id, patch) { const current = jobs.get(id); if (!current) return null; const next = { ...current, ...patch, updatedat: Date.now() }; jobs.set(id, next); return structuredClone(next); },
+    async listjobs(filter = {}) { return [...jobs.values()].filter((job) => Object.entries(filter).every(([key, value]) => job[key] === value)).map((job) => structuredClone(job)); },
+    async saveevent(event) { const list = events.get(event.jobid) ?? []; list.push(structuredClone(event)); events.set(event.jobid, list); return event; },
+    async listevents(jobid) { return (events.get(jobid) ?? []).map((event) => structuredClone(event)); },
+    async savesession(session) { sessions.set(session.id, structuredClone(session)); return structuredClone(session); },
+    async readsession(id) { return sessions.get(id) ? structuredClone(sessions.get(id)) : null; },
+    async saveartifact(artifact) { artifacts.set(artifact.key, structuredClone(artifact)); return structuredClone(artifact); },
+    async getartifact(key) { return artifacts.get(key) ? structuredClone(artifacts.get(key)) : null; },
+    async savechunk(chunk) { chunks.set(chunk.id, structuredClone(chunk)); return structuredClone(chunk); },
+    async getchunks(artifactkey) { return [...chunks.values()].filter((chunk) => chunk.artifactkey === artifactkey).sort((left, right) => left.index - right.index).map((chunk) => structuredClone(chunk)); }
+  });
+}

package/persistence/migrations.js

@@ -0,0 +1,14 @@
+/**
+ * migration plans stay neutral so Prisma, Drizzle, MySQL2, Turso, and another SQL driver can map them.
+ */
+export const migrationlist = Object.freeze([
+  { version: 1, name: "baseoperational", tables: ["jobs", "events", "sessions", "artifacts", "chunks"] },
+  { version: 2, name: "persistentqueue", tables: ["queueitems"] },
+  { version: 3, name: "webhookdeliveries", tables: ["webhookdeliveries"] }
+]);
+
+/** Returns pending migration statements for a dialect. */
+export function migrationplan(options = {}) { const current = options.current ?? 0; const dialect = options.dialect ?? "mysql"; return migrationlist.filter((migration) => migration.version > current).map((migration) => ({ ...migration, statements: migration.version === 2 ? [`create table if not exists queueitems (id text primary key, status text not null, attempts integer not null, payload json not null, result json, error json, createdat bigint not null, updatedat bigint not null)`] : migration.version === 3 ? [`create table if not exists webhookdeliveries (id text primary key, event text not null, receivedat bigint not null, processedat bigint, payload json not null)`] : [], dialect })); }
+
+/** Returns the latest schema version. */
+export function latestmigration() { return migrationlist.at(-1).version; }

package/persistence/prisma.js

@@ -0,0 +1,23 @@
+/**
+ * prisma persistence maps model delegates through an explicit model configuration.
+ */
+import { persistenceadapter } from "./adapter.js";
+
+export function prismapersistence(client, options = {}) {
+  const models = { jobs: options.jobs ?? client?.job, events: options.events ?? client?.event, sessions: options.sessions ?? client?.session, artifacts: options.artifacts ?? client?.artifact, chunks: options.chunks ?? client?.chunk };
+  for (const [name, model] of Object.entries(models)) if (!model) throw new TypeError(`prisma model is missing: ${name}`);
+  return persistenceadapter({
+    async savejob(job) { return models.jobs.upsert({ where: { id: job.id }, create: job, update: job }); },
+    async getjob(id) { return models.jobs.findUnique({ where: { id } }); },
+    async updatejob(id, patch) { return models.jobs.update({ where: { id }, data: { ...patch, updatedat: Date.now() } }); },
+    async listjobs(filter = {}) { return models.jobs.findMany({ where: filter, orderBy: { createdat: "desc" } }); },
+    async saveevent(event) { return models.events.create({ data: event }); },
+    async listevents(jobid) { return models.events.findMany({ where: { jobid }, orderBy: { at: "asc" } }); },
+    async savesession(session) { return models.sessions.upsert({ where: { id: session.id }, create: session, update: session }); },
+    async readsession(id) { return models.sessions.findUnique({ where: { id } }); },
+    async saveartifact(artifact) { return models.artifacts.upsert({ where: { key: artifact.key }, create: artifact, update: artifact }); },
+    async getartifact(key) { return models.artifacts.findUnique({ where: { key } }); },
+    async savechunk(chunk) { return models.chunks.upsert({ where: { id: chunk.id }, create: chunk, update: chunk }); },
+    async getchunks(artifactkey) { return models.chunks.findMany({ where: { artifactkey }, orderBy: { index: "asc" } }); }
+  });
+}

package/persistence/schema.js

@@ -0,0 +1,29 @@
+/**
+ * the schema descriptor is neutral so prisma drizzle mysql2 or another driver can map it.
+ */
+export const schemadefinition = Object.freeze({
+  jobs: { id: "text primary key", name: "text", status: "text", priority: "integer", input: "json", outputkey: "text", createdat: "integer", updatedat: "integer" },
+  events: { id: "text primary key", jobid: "text", type: "text", at: "integer", data: "json" },
+  sessions: { id: "text primary key", version: "integer", agentname: "text", originurl: "text", seed: "text", status: "text", startedat: "integer", finishedat: "integer", events: "json" },
+  artifacts: { key: "text primary key", sizebytes: "bigint", sha256: "text", contenttype: "text", createdat: "integer", metadata: "json" },
+  chunks: { id: "text primary key", artifactkey: "text", index: "integer", offset: "bigint", sizebytes: "integer", sha256: "text", storagekey: "text" }
+  ,queueitems: { id: "text primary key", status: "text", attempts: "integer", payload: "json", result: "json", error: "json", createdat: "bigint", updatedat: "bigint" }
+});
+
+export function schemasql(options = {}) {
+  const dialect = options.dialect ?? "mysql";
+  const json = dialect === "postgres" ? "jsonb" : "json";
+  const bigint = dialect === "sqlite" ? "integer" : "bigint";
+  return [
+    `create table if not exists jobs (id text primary key, name text not null, status text not null, priority integer not null, input ${json}, outputkey text, createdat ${bigint} not null, updatedat ${bigint} not null)`,
+    `create table if not exists events (id text primary key, jobid text not null, type text not null, at ${bigint} not null, data ${json} not null)`,
+    `create table if not exists sessions (id text primary key, version integer not null, agentname text not null, originurl text not null, seed text not null, status text not null, startedat ${bigint} not null, finishedat ${bigint}, events ${json} not null)`,
+    `create table if not exists artifacts (key text primary key, sizebytes ${bigint} not null, sha256 text not null, contenttype text not null, createdat ${bigint} not null, metadata ${json} not null)`,
+    `create table if not exists chunks (id text primary key, artifactkey text not null, chunkindex integer not null, byteoffset ${bigint} not null, sizebytes integer not null, sha256 text not null, storagekey text not null)`
+    ,`create table if not exists queueitems (id text primary key, status text not null, attempts integer not null, payload ${json} not null, result ${json}, error ${json}, createdat ${bigint} not null, updatedat ${bigint} not null)`
+  ];
+}
+
+export function prismaschema() {
+  return `model job { id String @id name String status String priority Int input Json? outputkey String? createdat BigInt updatedat BigInt }\nmodel event { id String @id jobid String type String at BigInt data Json }\nmodel session { id String @id version Int agentname String originurl String seed String status String startedat BigInt finishedat BigInt? events Json }\nmodel artifact { key String @id sizebytes BigInt sha256 String contenttype String createdat BigInt metadata Json }\nmodel chunk { id String @id artifactkey String chunkindex Int byteoffset BigInt sizebytes Int sha256 String storagekey String }`;
+}

package/persistence/sql.js

@@ -0,0 +1,30 @@
+/**
+ * sql persistence keeps query execution injected for mysql2 drizzle or another sql client.
+ */
+import { persistenceadapter } from "./adapter.js";
+
+export function sqlpersistence(options = {}) {
+  if (typeof options.query !== "function") throw new TypeError("sql persistence requires query");
+  const table = options.table ?? { jobs: "jobs", events: "events", sessions: "sessions", artifacts: "artifacts", chunks: "chunks" };
+  async function one(statement, values = []) { const result = await options.query(statement, values); return result?.rows?.[0] ?? result?.[0]?.[0] ?? result?.[0] ?? null; }
+  async function many(statement, values = []) { const result = await options.query(statement, values); return result?.rows ?? result?.[0] ?? result ?? []; }
+  return persistenceadapter({
+    async savejob(job) { await options.query(`insert into ${table.jobs} (id,name,status,priority,input,outputkey,createdat,updatedat) values (?,?,?,?,?,?,?,?)`, [job.id, job.name, job.status, job.priority, JSON.stringify(job.input ?? null), job.outputkey ?? null, job.createdat, job.updatedat ?? job.createdat]); return job; },
+    async getjob(id) { const row = await one(`select * from ${table.jobs} where id = ?`, [id]); return row ? normalizejob(row) : null; },
+    async updatejob(id, patch) { const current = await this.getjob(id); if (!current) return null; const next = { ...current, ...patch, updatedat: Date.now() }; await options.query(`update ${table.jobs} set status = ?, priority = ?, input = ?, outputkey = ?, updatedat = ? where id = ?`, [next.status, next.priority, JSON.stringify(next.input ?? null), next.outputkey ?? null, next.updatedat, id]); return next; },
+    async listjobs(filter = {}) { const rows = await many(`select * from ${table.jobs} order by createdat desc`, []); return rows.map(normalizejob).filter((job) => Object.entries(filter).every(([key, value]) => job[key] === value)); },
+    async saveevent(event) { await options.query(`insert into ${table.events} (id,jobid,type,at,data) values (?,?,?,?,?)`, [event.id, event.jobid, event.type, event.at, JSON.stringify(event.data ?? {})]); return event; },
+    async listevents(jobid) { return (await many(`select * from ${table.events} where jobid = ? order by at asc`, [jobid])).map((row) => ({ ...row, data: parsejson(row.data) })); },
+    async savesession(session) { await options.query(`insert into ${table.sessions} (id,version,agentname,originurl,seed,status,startedat,finishedat,events) values (?,?,?,?,?,?,?,?,?)`, [session.id, session.version, session.agentname, session.originurl, session.seed, session.status, session.startedat, session.finishedat ?? null, JSON.stringify(session.events ?? [])]); return session; },
+    async readsession(id) { const row = await one(`select * from ${table.sessions} where id = ?`, [id]); return row ? { ...row, events: parsejson(row.events) } : null; },
+    async saveartifact(artifact) { await options.query(`insert into ${table.artifacts} (key,sizebytes,sha256,contenttype,createdat,metadata) values (?,?,?,?,?,?)`, [artifact.key, artifact.sizebytes, artifact.sha256, artifact.contenttype, artifact.createdat, JSON.stringify(artifact.metadata ?? {})]); return artifact; },
+    async getartifact(key) { const row = await one(`select * from ${table.artifacts} where key = ?`, [key]); return row ? { ...row, metadata: parsejson(row.metadata) } : null; },
+    async savechunk(chunk) { await options.query(`insert into ${table.chunks} (id,artifactkey,chunkindex,byteoffset,sizebytes,sha256,storagekey) values (?,?,?,?,?,?,?)`, [chunk.id, chunk.artifactkey, chunk.index, chunk.offset, chunk.sizebytes, chunk.sha256, chunk.storagekey]); return chunk; },
+    async getchunks(artifactkey) { return (await many(`select * from ${table.chunks} where artifactkey = ? order by chunkindex asc`, [artifactkey])).map((row) => ({ ...row, index: row.index ?? row.chunkindex, offset: row.offset ?? row.byteoffset })); }
+  });
+}
+
+export function mysql2persistence(pool, options = {}) { if (typeof pool?.execute !== "function") throw new TypeError("mysql2 pool requires execute"); return sqlpersistence({ ...options, query: async (statement, values) => pool.execute(statement, values) }); }
+
+function normalizejob(row) { return { ...row, input: parsejson(row.input) }; }
+function parsejson(value) { if (value == null || typeof value === "object") return value; try { return JSON.parse(value); } catch { return value; } }

package/protocol/blocks.js

@@ -0,0 +1,18 @@
+/**
+ * block streaming yields bounded chunks and lets the consumer control backpressure.
+ */
+export async function* blockstream(input, options = {}) {
+  const blockbytes = options.blockbytes;
+  if (!Number.isInteger(blockbytes) || blockbytes < 1) throw new TypeError("blockbytes must be a positive integer");
+  let index = 0;
+  let offset = 0;
+  let pending = new Uint8Array(0);
+  for await (const part of input instanceof Uint8Array ? [input] : input) {
+    const data = part instanceof Uint8Array ? part : new TextEncoder().encode(String(part));
+    pending = concat(pending, data);
+    while (pending.byteLength > blockbytes) { const block = pending.slice(0, blockbytes); pending = pending.slice(blockbytes); yield { index, offset, data: block, final: false }; index += 1; offset += block.byteLength; }
+  }
+  if (pending.byteLength) yield { index, offset, data: pending, final: true };
+}
+
+function concat(left, right) { const output = new Uint8Array(left.byteLength + right.byteLength); output.set(left); output.set(right, left.byteLength); return output; }

package/protocol/json.js

@@ -0,0 +1,5 @@
+/**
+ * json helpers keep serialization rules explicit at the protocol boundary.
+ */
+export function jsonencode(value) { return JSON.stringify(value); }
+export function jsondecode(value) { return JSON.parse(value); }

package/protocol/ndjson.js

@@ -0,0 +1,17 @@
+/**
+ * ndjson supports append only records and incremental parsing.
+ */
+import { jsondecode, jsonencode } from "./json.js";
+
+export async function* ndjsonencode(values) { for await (const value of values) yield `${jsonencode(value)}\n`; }
+
+export async function* ndjsondecode(input) {
+  let buffer = "";
+  for await (const chunk of input) {
+    buffer += typeof chunk === "string" ? chunk : new TextDecoder().decode(chunk);
+    const lines = buffer.split(/\r?\n/);
+    buffer = lines.pop() ?? "";
+    for (const line of lines) if (line.trim()) yield jsondecode(line);
+  }
+  if (buffer.trim()) yield jsondecode(buffer);
+}

package/protocol/sse.js

@@ -0,0 +1,22 @@
+/**
+ * sse helpers encode typed events without requiring a web framework.
+ */
+import { jsondecode, jsonencode } from "./json.js";
+
+export function sseencode(event) {
+  const lines = [];
+  if (event.id !== undefined) lines.push(`id: ${event.id}`);
+  if (event.event) lines.push(`event: ${event.event}`);
+  for (const line of jsonencode(event.data ?? {}).split("\n")) lines.push(`data: ${line}`);
+  return `${lines.join("\n")}\n\n`;
+}
+
+export function ssedecode(chunk) {
+  const fields = {};
+  for (const line of String(chunk).split(/\r?\n/)) {
+    const index = line.indexOf(":");
+    if (index < 0) continue;
+    fields[line.slice(0, index)] = line.slice(index + 1).trimStart();
+  }
+  return { id: fields.id, event: fields.event, data: fields.data ? jsondecode(fields.data) : undefined };
+}

package/proxy/pool.js

@@ -0,0 +1,12 @@
+/**
+ * proxy pool chooses healthy least used entries and never rotates blindly.
+ */
+export function proxypool(options = {}) {
+  const entries = (options.proxies ?? []).map((proxy) => ({ ...proxy, failures: 0, uses: 0, status: "active", lastused: 0 }));
+  const threshold = options.failurethreshold ?? 3;
+  const recovery = options.recoverytime ?? 300000;
+  function revive() { const now = Date.now(); for (const entry of entries) if (entry.status === "graveyard" && now - entry.failedat >= recovery) { entry.status = "active"; entry.failures = 0; } }
+  function choose() { revive(); const available = entries.filter((entry) => entry.status === "active"); if (!available.length) throw new Error("proxy pool has no healthy entries"); const selected = [...available].sort((left, right) => left.uses - right.uses || left.lastused - right.lastused)[0]; selected.uses += 1; selected.lastused = Date.now(); return { ...selected }; }
+  function report(id, result = {}) { const entry = entries.find((value) => value.id === id); if (!entry) return null; if (result.ok) { entry.failures = 0; entry.status = "active"; } else { entry.failures += 1; entry.status = entry.failures >= threshold ? "graveyard" : "active"; entry.failedat = Date.now(); } return { ...entry }; }
+  return { choose, report, list() { revive(); return entries.map((entry) => ({ ...entry })); } };
+}

package/queue/idempotency.js

@@ -0,0 +1,12 @@
+/**
+ * idempotency keys prevent duplicate delivery from at least once transports.
+ */
+export function idempotency() {
+  const results = new Map();
+  return {
+    has(key) { return results.has(key); },
+    get(key) { return results.get(key); },
+    set(key, value) { results.set(key, value); return value; },
+    delete(key) { results.delete(key); }
+  };
+}

package/queue/persistent.js

@@ -0,0 +1,44 @@
+/**
+ * persistent queue stores job state in a caller selected file.
+ * running items return to queued when a process restores after a crash.
+ */
+import { readFile, writeFile } from "node:fs/promises";
+
+/** Creates a crash recoverable queue with idempotent item identifiers. */
+export function persistentqueue(options = {}) {
+  if (!options.path) throw new TypeError("persistent queue requires path");
+  const maxattempts = options.maxattempts ?? 3;
+  let state = { version: 1, items: [] };
+  let loaded = false;
+
+  /** Reads the queue once and returns running jobs to the waiting state. */
+  async function restore() {
+    if (loaded) return state;
+    try { state = JSON.parse(await readFile(options.path, "utf8")); } catch (error) { if (error.code !== "ENOENT") throw error; }
+    for (const item of state.items ?? []) if (item.status === "running") item.status = "queued";
+    state.items ??= [];
+    loaded = true;
+    await persist();
+    return state;
+  }
+
+  /** Appends a queued job and persists the new state. */
+  async function enqueue(payload, metadata = {}) { await restore(); const id = metadata.id ?? `persistentjob${Date.now()}${state.items.length}`; if (state.items.some((item) => item.id === id)) return state.items.find((item) => item.id === id); const item = { id, payload, status: "queued", attempts: 0, createdat: Date.now(), updatedat: Date.now(), metadata }; state.items.push(item); await persist(); return { ...item }; }
+
+  /** Claims the first queued job with stable ordering. */
+  async function claim() { await restore(); const item = state.items.find((entry) => entry.status === "queued"); if (!item) return null; item.status = "running"; item.attempts += 1; item.updatedat = Date.now(); await persist(); return { ...item }; }
+
+  /** Commits a successful result. */
+  async function complete(id, result) { await restore(); const item = find(id); item.status = "completed"; item.result = result; item.updatedat = Date.now(); await persist(); return { ...item }; }
+
+  /** Records an error and either retries or closes the item as failed. */
+  async function fail(id, error) { await restore(); const item = find(id); item.error = { message: error?.message ?? String(error), code: error?.code }; item.status = item.attempts < maxattempts && error?.retryable !== false ? "queued" : "failed"; item.updatedat = Date.now(); await persist(); return { ...item }; }
+
+  /** Lists queue items for status and diagnostics. */
+  async function list(filter) { await restore(); return state.items.filter((item) => !filter || item.status === filter).map((item) => ({ ...item })); }
+
+  return { restore, enqueue, claim, complete, fail, list };
+
+  function find(id) { const item = state.items.find((entry) => entry.id === id); if (!item) throw new Error(`persistent queue item not found: ${id}`); return item; }
+  async function persist() { await writeFile(options.path, `${JSON.stringify(state, null, 2)}\n`, "utf8"); }
+}

package/queue/queue.js

@@ -0,0 +1,50 @@
+/**
+ * job queue groups concurrency retry timeout and idempotency at one boundary.
+ */
+import { idempotency } from "./idempotency.js";
+
+export function jobqueue(options = {}) {
+  const limit = options.concurrency ?? 1;
+  const attempts = options.maxattempts ?? 3;
+  const retryall = options.retryall ?? false;
+  const keys = options.idempotency ?? idempotency();
+  const pending = [];
+  let active = 0;
+  let sequence = 0;
+  async function drain() {
+    while (active < limit && pending.length) {
+      const item = pending.shift();
+      active += 1;
+      execute(item).then(item.resolve, item.reject).finally(() => { active -= 1; void drain(); });
+    }
+  }
+  async function execute(item) {
+    if (item.key && keys.has(item.key)) return keys.get(item.key);
+    let last;
+    for (let attempt = 1; attempt <= attempts; attempt += 1) {
+      try {
+        const result = await item.handler({ id: item.id, payload: item.payload, attempt });
+        if (item.key) keys.set(item.key, result);
+        return result;
+      } catch (error) {
+        last = error;
+        const retryable = retryall || error?.retryable === true || error?.code === "RUNNER_UNAVAILABLE";
+        if (!retryable || attempt === attempts) throw error;
+        await delay((options.backoff ?? 250) * 2 ** (attempt - 1));
+      }
+    }
+    throw last;
+  }
+  return {
+    add(payload, handler, options = {}) {
+      if (typeof handler !== "function") return Promise.reject(new TypeError("queue handler is required"));
+      const id = options.id ?? `queuejob${sequence++}`;
+      return new Promise((resolve, reject) => { pending.push({ id, payload, handler, key: options.key, resolve, reject }); void drain(); });
+    },
+    size() { return pending.length; },
+    active() { return active; },
+    async idle() { while (pending.length || active) await delay(10); }
+  };
+}
+
+function delay(milliseconds) { return new Promise((resolve) => setTimeout(resolve, milliseconds)); }

package/queue/saga.js

@@ -0,0 +1,13 @@
+/**
+ * saga executes compensations in reverse order when a multi step operation fails.
+ */
+export async function saga(steps, context = {}) {
+  const completed = [];
+  try {
+    for (const step of steps) { const value = await step.run(context); completed.push({ step, value }); }
+    return completed.map((item) => item.value);
+  } catch (error) {
+    for (const item of completed.reverse()) if (typeof item.step.compensate === "function") await item.step.compensate(context, item.value);
+    throw error;
+  }
+}