@wenathlan/saddle 1.8.1

package/license.md

@@ -0,0 +1,203 @@
+                    PROPRIETARY SOURCE-AVAILABLE LICENSE - VIEW ONLY
+                       Version 1.0, August 2026
+
+ Copyright (C) August 2026 devthink, nathlan, iakadion, nathu filho, allan neris, andraneris
+ Everyone is permitted to view this license document, but changing it
+ is not allowed. This license is NOT an Open Source license.
+
+                            Preamble
+
+  This License governs the source code made available by the Licensor.
+  Unlike free software licenses such as the GNU GPL, this is a
+  proprietary, source-available license.
+
+  The Software is made visible for transparency and verification
+  purposes only. It is NOT free software. It is NOT open source.
+
+  When we speak of proprietary, we are referring to full ownership and
+  restriction, not freedom. Our intention is to protect the Licensor's
+  exclusive rights to copy, modify, distribute and use the work. By
+  contrast to the GPL which guarantees your freedom to share and change,
+  this License is intended to guarantee that the Software remains the
+  exclusive property of its authors and that no rights beyond viewing
+  are granted.
+
+  To protect our rights, we must prevent others from copying, modifying,
+  distributing, or using the Software without permission. Therefore,
+  you have no rights to convey, modify, or use the Software beyond
+  viewing it in its public repository form.
+
+  For the authors' protection, this License clearly explains that there
+  is no warranty for this proprietary software and that any unauthorized
+  use will be treated as copyright infringement.
+
+  The precise terms and conditions for viewing and restriction follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 1.0 of the Proprietary Source-Available
+  License - View Only.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+  works.
+
+  "The Program" or "The Software" refers to any copyrightable work licensed
+  under this License, including source code, object code, documentation,
+  and associated files. Each licensee is addressed as "you".
+
+  "Licensor" refers to the copyright holders: devthink, nathlan, iakadion,
+  nathu filho, allan neris, andraneris.
+
+  To "view" means to read and examine the Software in its public repository
+  form through a web browser, without creating a local copy beyond the
+  temporary cache of your browser.
+
+  To "use" means to execute, run, compile, deploy, host, or otherwise
+  benefit from the functionality of the Software, which is NOT permitted.
+
+  1. Ownership and Intellectual Property.
+
+  The Software is and shall remain the exclusive property of the Licensor.
+  All right, title, and interest in and to the Software, including all
+  copyrights, trademarks, trade secrets, and other intellectual property
+  rights, are owned solely by the Licensor.
+
+  No ownership rights, implied or otherwise, are transferred to you under
+  this License. All rights not expressly granted are reserved.
+
+  2. Grant of Rights - VIEW ONLY.
+
+  Subject to the terms of this License, Licensor grants you a limited,
+  non-exclusive, non-transferable, revocable license solely to VIEW the
+  Software in its public repository form for personal evaluation.
+
+  This grant DOES NOT include any right to:
+
+    a) use, execute, or run the Software;
+    b) copy, reproduce, or duplicate;
+    c) modify, adapt, or create derivative works;
+    d) distribute, publish, sublicense, or sell;
+    e) reverse engineer or decompile.
+
+  3. Prohibitions and Restrictions.
+
+  You are STRICTLY PROHIBITED from undertaking any of the following
+  without prior written permission from the Licensor:
+
+    a) Copying, reproducing, duplicating, or storing the Software, in
+    whole or in part, in any medium;
+
+    b) Modifying, adapting, translating, transforming, or creating
+    derivative works based on the Software;
+
+    c) Distributing, publishing, sublicensing, disclosing, or otherwise
+    making the Software available to third parties, whether gratis or
+    for a fee;
+
+    d) Using the Software for any purpose, including but not limited to
+    development, production, commercial use, internal business operations,
+    offering as a service (SaaS), or training artificial intelligence
+    models;
+
+    e) Removing, altering, or obscuring any copyright, proprietary, or
+    license notices contained in the Software;
+
+    f) Reverse engineering, decompiling, disassembling, or attempting to
+    derive the source code of the Software.
+
+  Any use beyond viewing constitutes copyright infringement and will be
+  prosecuted to the fullest extent of the law.
+
+  4. Confidentiality.
+
+  The Software contains confidential information and proprietary trade
+  secrets of the Licensor. Unauthorized access, inspection, or disclosure
+  is strictly prohibited and may result in civil and criminal liability.
+
+  5. No Warranty.
+
+  The Software is provided for viewing only and may contain errors or
+  omissions. No support, maintenance, or updates are implied.
+
+  6. Acceptance Not Required for Viewing.
+
+  You are not required to accept this License to view the Software in a
+  web browser. However, any action beyond viewing, such as copying,
+  modifying, or using the Software, requires explicit written permission
+  and a separate license agreement. By doing so without permission, you
+  infringe copyright.
+
+  7. Termination.
+
+  This License and all rights granted herein automatically terminate upon
+  any breach of Section 3 by you. Upon termination, you must cease all
+  viewing and destroy all copies, including cached or local copies, of
+  the Software in your possession.
+
+  Moreover, termination does not terminate the rights of the Licensor
+  to seek damages or injunctive relief.
+
+  8. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+  APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+  HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+  OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+  THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+  PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+  IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+  ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  9. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+  WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO HAS VIEWED THE PROGRAM
+  AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+  GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+  VIEWING OR INABILITY TO VIEW THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS
+  OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+  PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE), EVEN IF SUCH HOLDER OR
+  OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+  10. Interpretation and Governing Law.
+
+  If the disclaimer of warranty and limitation of liability provided above
+  cannot be given local legal effect according to their terms, reviewing
+  courts shall apply local law that most closely approximates an absolute
+  waiver of all civil liability in connection with the Program, unless a
+  warranty or assumption of liability accompanies a copy of the Program
+  in return for a fee.
+
+  This License shall be governed by the laws of Brazil.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to remain proprietary and
+  fully owned by you, with source visible but with no rights granted, the
+  best way to achieve this is to attach the following notices to the program.
+  It is safest to attach them to the start of each source file.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) August 2026 devthink, nathlan, iakadion, nathu filho, allan neris, andraneris
+    Project ID: saddle
+
+    This program is proprietary and confidential: you can view its source
+    code for evaluation purposes only under the terms of the Proprietary
+    Source-Available License - View Only as published by the Licensor.
+    You are not permitted to copy, modify, distribute, or use this program
+    without prior written permission.
+
+    This program is distributed in the hope that it will be transparent,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+    Proprietary Source-Available License for more details.
+
+    You should have received a copy of the Proprietary Source-Available
+    License along with this program. If not, see
+    <https://github.com/iakadion/saddle/blob/main/license.txt>
+
+  Also add information on how to contact you by electronic and paper mail.

package/license.txt

@@ -0,0 +1,203 @@
+                    PROPRIETARY SOURCE-AVAILABLE LICENSE - VIEW ONLY
+                       Version 1.0, August 2026
+
+ Copyright (C) August 2026 devthink, nathlan, iakadion, nathu filho, allan neris, andraneris
+ Everyone is permitted to view this license document, but changing it
+ is not allowed. This license is NOT an Open Source license.
+
+                            Preamble
+
+  This License governs the source code made available by the Licensor.
+  Unlike free software licenses such as the GNU GPL, this is a
+  proprietary, source-available license.
+
+  The Software is made visible for transparency and verification
+  purposes only. It is NOT free software. It is NOT open source.
+
+  When we speak of proprietary, we are referring to full ownership and
+  restriction, not freedom. Our intention is to protect the Licensor's
+  exclusive rights to copy, modify, distribute and use the work. By
+  contrast to the GPL which guarantees your freedom to share and change,
+  this License is intended to guarantee that the Software remains the
+  exclusive property of its authors and that no rights beyond viewing
+  are granted.
+
+  To protect our rights, we must prevent others from copying, modifying,
+  distributing, or using the Software without permission. Therefore,
+  you have no rights to convey, modify, or use the Software beyond
+  viewing it in its public repository form.
+
+  For the authors' protection, this License clearly explains that there
+  is no warranty for this proprietary software and that any unauthorized
+  use will be treated as copyright infringement.
+
+  The precise terms and conditions for viewing and restriction follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 1.0 of the Proprietary Source-Available
+  License - View Only.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+  works.
+
+  "The Program" or "The Software" refers to any copyrightable work licensed
+  under this License, including source code, object code, documentation,
+  and associated files. Each licensee is addressed as "you".
+
+  "Licensor" refers to the copyright holders: devthink, nathlan, iakadion,
+  nathu filho, allan neris, andraneris.
+
+  To "view" means to read and examine the Software in its public repository
+  form through a web browser, without creating a local copy beyond the
+  temporary cache of your browser.
+
+  To "use" means to execute, run, compile, deploy, host, or otherwise
+  benefit from the functionality of the Software, which is NOT permitted.
+
+  1. Ownership and Intellectual Property.
+
+  The Software is and shall remain the exclusive property of the Licensor.
+  All right, title, and interest in and to the Software, including all
+  copyrights, trademarks, trade secrets, and other intellectual property
+  rights, are owned solely by the Licensor.
+
+  No ownership rights, implied or otherwise, are transferred to you under
+  this License. All rights not expressly granted are reserved.
+
+  2. Grant of Rights - VIEW ONLY.
+
+  Subject to the terms of this License, Licensor grants you a limited,
+  non-exclusive, non-transferable, revocable license solely to VIEW the
+  Software in its public repository form for personal evaluation.
+
+  This grant DOES NOT include any right to:
+
+    a) use, execute, or run the Software;
+    b) copy, reproduce, or duplicate;
+    c) modify, adapt, or create derivative works;
+    d) distribute, publish, sublicense, or sell;
+    e) reverse engineer or decompile.
+
+  3. Prohibitions and Restrictions.
+
+  You are STRICTLY PROHIBITED from undertaking any of the following
+  without prior written permission from the Licensor:
+
+    a) Copying, reproducing, duplicating, or storing the Software, in
+    whole or in part, in any medium;
+
+    b) Modifying, adapting, translating, transforming, or creating
+    derivative works based on the Software;
+
+    c) Distributing, publishing, sublicensing, disclosing, or otherwise
+    making the Software available to third parties, whether gratis or
+    for a fee;
+
+    d) Using the Software for any purpose, including but not limited to
+    development, production, commercial use, internal business operations,
+    offering as a service (SaaS), or training artificial intelligence
+    models;
+
+    e) Removing, altering, or obscuring any copyright, proprietary, or
+    license notices contained in the Software;
+
+    f) Reverse engineering, decompiling, disassembling, or attempting to
+    derive the source code of the Software.
+
+  Any use beyond viewing constitutes copyright infringement and will be
+  prosecuted to the fullest extent of the law.
+
+  4. Confidentiality.
+
+  The Software contains confidential information and proprietary trade
+  secrets of the Licensor. Unauthorized access, inspection, or disclosure
+  is strictly prohibited and may result in civil and criminal liability.
+
+  5. No Warranty.
+
+  The Software is provided for viewing only and may contain errors or
+  omissions. No support, maintenance, or updates are implied.
+
+  6. Acceptance Not Required for Viewing.
+
+  You are not required to accept this License to view the Software in a
+  web browser. However, any action beyond viewing, such as copying,
+  modifying, or using the Software, requires explicit written permission
+  and a separate license agreement. By doing so without permission, you
+  infringe copyright.
+
+  7. Termination.
+
+  This License and all rights granted herein automatically terminate upon
+  any breach of Section 3 by you. Upon termination, you must cease all
+  viewing and destroy all copies, including cached or local copies, of
+  the Software in your possession.
+
+  Moreover, termination does not terminate the rights of the Licensor
+  to seek damages or injunctive relief.
+
+  8. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+  APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+  HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+  OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+  THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+  PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+  IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+  ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  9. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+  WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO HAS VIEWED THE PROGRAM
+  AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+  GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+  VIEWING OR INABILITY TO VIEW THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS
+  OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+  PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE), EVEN IF SUCH HOLDER OR
+  OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+  10. Interpretation and Governing Law.
+
+  If the disclaimer of warranty and limitation of liability provided above
+  cannot be given local legal effect according to their terms, reviewing
+  courts shall apply local law that most closely approximates an absolute
+  waiver of all civil liability in connection with the Program, unless a
+  warranty or assumption of liability accompanies a copy of the Program
+  in return for a fee.
+
+  This License shall be governed by the laws of Brazil.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to remain proprietary and
+  fully owned by you, with source visible but with no rights granted, the
+  best way to achieve this is to attach the following notices to the program.
+  It is safest to attach them to the start of each source file.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) August 2026 devthink, nathlan, iakadion, nathu filho, allan neris, andraneris
+    Project ID: saddle
+
+    This program is proprietary and confidential: you can view its source
+    code for evaluation purposes only under the terms of the Proprietary
+    Source-Available License - View Only as published by the Licensor.
+    You are not permitted to copy, modify, distribute, or use this program
+    without prior written permission.
+
+    This program is distributed in the hope that it will be transparent,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+    Proprietary Source-Available License for more details.
+
+    You should have received a copy of the Proprietary Source-Available
+    License along with this program. If not, see
+    <https://github.com/iakadion/saddle/blob/main/license.txt>
+
+  Also add information on how to contact you by electronic and paper mail.

package/mcp/browser.js

@@ -0,0 +1,12 @@
+/**
+ * browser MCP tools expose snapshots and actions only through an injected browser adapter.
+ */
+
+/** Creates optional browser tools for an MCP server without selecting Playwright or another vendor. */
+export function browsertools(browser) {
+  if (typeof browser?.snapshot !== "function" || typeof browser?.action !== "function") throw new TypeError("browser MCP tools require snapshot and action");
+  return {
+    browser_snapshot: async (input = {}) => browser.snapshot(input),
+    browser_action: async (input = {}) => browser.action(input)
+  };
+}

package/mcp/server.js

@@ -0,0 +1,28 @@
+/**
+ * mcp server implements a small JSON RPC tool surface and remains transport agnostic.
+ */
+import { crawl } from "../crawl/crawler.js";
+import { extractwithschema } from "../scrape/schema.js";
+import { jsonencode } from "../protocol/json.js";
+import { browsertools } from "./browser.js";
+
+export function mcpserver(options = {}) {
+  if (typeof options.scrape !== "function") throw new TypeError("mcp server requires scrape");
+  const tools = {
+    scrape: async (input) => options.scrape(input.url, input),
+    crawl: async (input) => crawl(input.url, { ...input, scrape: (url) => options.scrape(url, input) }),
+    batch: async (input) => ({ results: await Promise.all((input.urls ?? []).map((url) => options.scrape(url, input))) }),
+    extract: async (input) => extractwithschema(input.html, input.schema, input.url),
+    serialize: async (input) => jsonencode(input.value),
+    ...(options.browser ? browsertools(options.browser) : {}),
+    ...(options.tools ?? {})
+  };
+  return {
+    listtools() { return Object.keys(tools).map((name) => ({ name, description: `saddle ${name} tool` })); },
+    async handle(request) {
+      if (request.method === "tools/list") return { jsonrpc: "2.0", id: request.id, result: { tools: this.listtools() } };
+      if (request.method === "tools/call") { const handler = tools[request.params?.name]; if (!handler) return { jsonrpc: "2.0", id: request.id, error: { code: -32601, message: "tool not found" } }; try { return { jsonrpc: "2.0", id: request.id, result: { content: [{ type: "text", text: JSON.stringify(await handler(request.params.arguments ?? {})) }] } }; } catch (error) { return { jsonrpc: "2.0", id: request.id, error: { code: -32000, message: error.message } }; } }
+      return { jsonrpc: "2.0", id: request.id, error: { code: -32601, message: "method not found" } };
+    }
+  };
+}

package/mcp/transport.js

@@ -0,0 +1,14 @@
+/**
+ * mcp transport keeps JSON RPC framing separate from the tool server.
+ */
+import { jsondecode, jsonencode } from "../protocol/json.js";
+
+/** Creates JSONL and HTTP handlers for the transport agnostic MCP server. */
+export function mcptransport(server) {
+  if (typeof server?.handle !== "function") throw new TypeError("mcp transport requires server");
+  return {
+    async handleline(line) { const request = jsondecode(line); return jsonencode(await server.handle(request)); },
+    async *stream(lines) { for await (const line of lines) if (String(line).trim()) yield await this.handleline(line); },
+    async handlehttp(request) { const body = await request.text(); const response = await server.handle(jsondecode(body)); return new Response(jsonencode(response), { status: 200, headers: { "content-type": "application/json" } }); }
+  };
+}

package/memory/bridge.js

@@ -0,0 +1,16 @@
+/**
+ * memory bridges materialize and clear temporary working sets.
+ */
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { syncresult, workingset } from "../domain/runtime.js";
+
+export function localmemory(options = {}) {
+  const base = options.base ?? tmpdir();
+  return {
+    async prepare(job) { const location = await mkdtemp(join(base, "saddlejob")); return workingset(job.id, location, join(location, "resultbin")); },
+    async sync(set, bytes) { await mkdir(set.location, { recursive: true }); await writeFile(set.resultpath, bytes); return syncresult(bytes.byteLength, set.resultpath); },
+    async cleanup(set) { await rm(set.location, { recursive: true, force: true }); }
+  };
+}

package/memory/engine.js

@@ -0,0 +1,45 @@
+/**
+ * memory engine loads from the first backend and persists to every backend.
+ */
+import { memoryobject, tobytes } from "./objects.js";
+import { transformtocompute, transformtostorage } from "./transforms.js";
+import { storagecapabilities, syncbackends } from "../storage/sync.js";
+
+export function memoryengine(options = {}) {
+  const backends = options.backends ?? [];
+  const values = new Map();
+  async function load(key) {
+    if (!key) throw new TypeError("memory key is required");
+    if (values.has(key)) return values.get(key);
+    let last;
+    for (const backend of backends) {
+      try {
+        const value = await backend.get(key);
+        if (value == null) continue;
+        const object = memoryobject({ id: key, buffer: value.data ?? value, type: value.contenttype ?? value.type, metadata: value.metadata });
+        values.set(key, object);
+        return object;
+      } catch (error) { last = error; }
+    }
+    if (last) throw new Error(`memory engine load failed for key "${key}": ${last.message}`, { cause: last });
+    throw new Error(`memory engine load failed for key "${key}": not found`);
+  }
+  async function persist(key, data, options = {}) {
+    const payload = tobytes(data?.payload ?? data?.buffer ?? data);
+    const object = memoryobject({ id: key, buffer: payload, type: options.mimetype ?? data?.mimetype, metadata: options.metadata ?? data?.metadata });
+    for (const backend of backends) await backend.put(key, { data: object.buffer, contenttype: object.type, metadata: object.metadata });
+    values.set(key, object);
+    return object;
+  }
+  function release(key) { values.delete(key); }
+  async function safeload(key) { try { return { success: true, data: await load(key) }; } catch (error) { return { success: false, error }; } }
+  async function sync(key, options = {}) {
+    const sourceindex = Number(options.sourceindex ?? 0);
+    const source = backends[sourceindex];
+    if (!source) throw new TypeError("memory sync source backend is missing");
+    const targets = backends.filter((_backend, index) => index !== sourceindex);
+    return syncbackends(source, targets, key, options);
+  }
+  function capabilities() { return backends.map((backend, index) => ({ index, capabilities: storagecapabilities(backend) })); }
+  return { load, persist, release, safeload, sync, capabilities, transformtocompute, transformtostorage, list() { return [...values.keys()]; } };
+}

package/memory/modes.js

@@ -0,0 +1,55 @@
+/**
+ * memory modes expose the same byte contract with different backing choices.
+ */
+export function internalmemory(initial = {}) {
+  const values = new Map(Object.entries(initial).map(([key, value]) => [key, tobytes(value)]));
+  return {
+    mode: "internal",
+    async put(key, value) { values.set(key, tobytes(value)); return { key, bytes: values.get(key).byteLength }; },
+    async get(key) { return values.get(key) ?? null; },
+    async delete(key) { values.delete(key); },
+    async list() { return [...values.keys()]; }
+  };
+}
+
+export function externalmemory(storage) {
+  if (!storage?.put || !storage?.get) throw new TypeError("external memory requires storage adapter");
+  return {
+    mode: "external",
+    async put(key, value) { return storage.put({ key, data: tobytes(value) }); },
+    async get(key) { try { return await storage.get(key); } catch (error) { if (error.code === "ARTIFACT_NOT_FOUND") return null; throw error; } },
+    async delete(key) { return storage.delete(key); },
+    async list(prefix) { return storage.list(prefix); }
+  };
+}
+
+export function physicalmemory(options = {}) {
+  if (!options.path) throw new TypeError("physical memory requires a path");
+  return { mode: "physical", path: options.path, put: options.put, get: options.get, delete: options.delete, list: options.list };
+}
+
+export function vectorizedmemory() {
+  const vectors = new Map();
+  return {
+    mode: "vectorized",
+    async put(key, vector) { assertvector(vector); vectors.set(key, [...vector]); return { key, dimensions: vector.length }; },
+    async get(key) { return vectors.get(key) ?? null; },
+    async average(keys) { const selected = keys.map((key) => vectors.get(key)).filter(Boolean); if (!selected.length) return null; const size = selected[0].length; const result = Array.from({ length: size }, () => 0); for (const vector of selected) for (let index = 0; index < size; index += 1) result[index] += vector[index] / selected.length; return result; },
+    async list() { return [...vectors.keys()]; }
+  };
+}
+
+export function librarymemory(factory) {
+  if (typeof factory !== "function") throw new TypeError("library memory requires a factory");
+  return { mode: "library", async load(options) { return factory(options); } };
+}
+
+function tobytes(value) {
+  if (value instanceof Uint8Array) return value;
+  if (typeof value === "string") return new TextEncoder().encode(value);
+  return new TextEncoder().encode(JSON.stringify(value));
+}
+
+function assertvector(vector) {
+  if (!Array.isArray(vector) || vector.length === 0 || vector.some((value) => !Number.isFinite(value))) throw new TypeError("vector must be a non empty numeric array");
+}

package/memory/objects.js

@@ -0,0 +1,18 @@
+/**
+ * memory objects and compute results are serializable contracts between storage and runtime.
+ */
+export function memoryobject(options = {}) {
+  const buffer = tobytes(options.buffer ?? options.data ?? new Uint8Array(0));
+  return { id: options.id ?? `memory${Date.now().toString(36)}`, buffer, size: buffer.byteLength, type: options.type ?? "application/octet-stream", createdat: options.createdat ?? Date.now(), metadata: { ...(options.metadata ?? {}) } };
+}
+
+export function computeresult(options = {}) {
+  return { id: options.id ?? `result${Date.now().toString(36)}`, payload: options.payload, mimetype: options.mimetype, metadata: { ...(options.metadata ?? {}) }, processingtimems: options.processingtimems ?? 0, memoryusedbytes: options.memoryusedbytes ?? 0 };
+}
+
+export function tobytes(value) {
+  if (value instanceof Uint8Array) return value;
+  if (value instanceof ArrayBuffer) return new Uint8Array(value);
+  if (typeof value === "string") return new TextEncoder().encode(value);
+  return new TextEncoder().encode(JSON.stringify(value));
+}

package/memory/targets.js

@@ -0,0 +1,21 @@
+/**
+ * storage targets describe provider intent without importing a provider client.
+ */
+const types = new Set(["github", "gitlab", "forgejo", "gitea", "huggingface", "kaggle", "modelscope", "filehosting"]);
+
+export function targetfactory(type, options = {}) {
+  if (!types.has(type)) throw new TypeError(`unknown memory target: ${type}`);
+  if (type === "github" || type === "gitlab" || type === "forgejo" || type === "gitea") return { type, platform: type, owner: options.owner, repo: options.repo, branch: options.branch ?? "main", path: options.path, token: options.token };
+  if (type === "huggingface") return { type, space: options.space, revision: options.revision ?? "main", path: options.path, token: options.token };
+  if (type === "kaggle") return { type, dataset: options.dataset, sslverification: options.sslverification ?? true, path: options.path, token: options.token };
+  if (type === "modelscope") return { type, namespace: options.namespace, repo: options.repo, revision: options.revision ?? "master", path: options.path, token: options.token };
+  return { type, host: options.host, path: options.path, method: options.method ?? "s3compatible", token: options.token };
+}
+
+export function targeturi(target) {
+  if (target.type === "github" || target.type === "gitlab" || target.type === "forgejo" || target.type === "gitea") return `${target.type}://${target.owner}/${target.repo}/${target.path}`;
+  if (target.type === "huggingface") return `hf://${target.space}/${target.path}`;
+  if (target.type === "kaggle") return `kaggle://${target.dataset}/${target.path}`;
+  if (target.type === "modelscope") return `modelscope://${target.namespace}/${target.repo}/${target.path}`;
+  return `${target.method}://${target.host}/${target.path}`;
+}

package/memory/transforms.js

@@ -0,0 +1,15 @@
+/**
+ * transforms annotate byte movement without pretending remote storage is physical vram.
+ */
+import { computeresult, memoryobject, tobytes } from "./objects.js";
+
+export function transformtocompute(value, options = {}) {
+  const started = performance.now();
+  const object = memoryobject({ ...options, buffer: value?.buffer ?? value });
+  return { ...object, processingtimems: performance.now() - started, memoryusedbytes: object.size };
+}
+
+export function transformtostorage(value, options = {}) {
+  const payload = tobytes(value?.payload ?? value?.buffer ?? value);
+  return computeresult({ id: value?.id, payload, mimetype: options.mimetype ?? value?.mimetype ?? "application/octet-stream", metadata: options.metadata ?? value?.metadata, processingtimems: value?.processingtimems, memoryusedbytes: payload.byteLength });
+}

package/modes/matrix.js

@@ -0,0 +1,20 @@
+/**
+ * mode matrix keeps supported execution choices in one grouped contract.
+ */
+export const modeaxes = Object.freeze({
+  execution: ["library", "application", "browser", "desktopapp", "mobileapp", "extension", "cli", "binary", "computer", "internet"],
+  runtime: ["node", "browser", "deno", "bun", "worker", "unknown"],
+  memory: ["internal", "external", "physical", "vectorized", "library"],
+  file: ["internal", "external", "physical", "vector"],
+  dependency: ["internal", "external", "dev"],
+  visibility: ["visible", "headless"],
+  pair: ["without", "with"]
+});
+
+export const operationmodes = Object.freeze(modeaxes.execution.flatMap((execution) => modeaxes.pair.map((pair) => `${execution}${pair}`)));
+
+/** Returns true when the matrix contains the requested axis value. */
+export function validatemode(axis, value) { return Boolean(modeaxes[axis]?.includes(value)); }
+
+/** Returns a serializable snapshot for documentation and diagnostics. */
+export function modecatalog() { return { axes: Object.fromEntries(Object.entries(modeaxes).map(([key, values]) => [key, [...values]])), operationmodes: [...operationmodes] }; }