@synsema/wasm 0.6.1

package/README.md

@@ -0,0 +1,90 @@
+# @synsema/wasm
+
+[Synsema](https://github.com/kitecosmic/synsema) — the programming language for AI agents —
+embedded as WebAssembly. Run `.syn` programs inside a browser, Node/Bun/Deno or an edge
+runtime, and lend them exactly the capabilities your app decides to: `http`, a `kv`
+store, an `llm`, a `log`. No Synsema backend, nothing to install on the host.
+
+```js
+import { Synsema } from "@synsema/wasm";
+
+const syn = await Synsema.load(new URL("@synsema/wasm/synsema.wasm", import.meta.url));
+await syn.ready();
+
+const r = syn.run(`print(keccak256("hola"))`);
+r.output;  // ["…"]  — the program's print lines
+r.errors;  // []     — parse/runtime errors are data, never exceptions
+r.audit;   // every capability check the program made
+```
+
+## Lending capabilities (the host)
+
+The program keeps its manifest (`require net("api.example")`, `require llm`,
+`require memory("agenda")`) and your app decides what it actually gets. A missing hook
+makes the builtin fail with a clear error; a `ceiling` denies above what the host offers.
+
+```js
+const host = {
+  http: (req) => ({ status: 200, headers: [["content-type", "application/json"]], body: "{}" }),
+  kv: { get: (ns, k) => store.get(ns + "/" + k) ?? null, set: (ns, k, v) => store.set(ns + "/" + k, v) },
+  llm: (op, prompt) => ({ content: "…", tokens: 12 }),
+  log: (line) => console.log(line),
+};
+
+syn.run(`require memory("agenda")\nremember("preference", "dark mode")`, { host, filename: "agenda.syn" });
+syn.run(`require llm\nprint(reason about "the weather")`, { host, ceiling: "stdout" }); // denied: ceiling wins
+```
+
+- `kv` backs persistent agent memory (`remember`/`recall`, rules, progress — namespace
+  `memory:<declared name>`) and `state_*` (namespace `state`).
+- `llm` backs `reason`/`decide`/`analyze`/`generate`; `llm_usage()` sums the tokens you report.
+- `http` backs `fetch`/`http_*` and the blockchain read-side RPC — after the `net(host)`
+  gate, with the same URL canonicalization as the native binary.
+
+## Async hosts (browser `fetch`, IndexedDB, LLM SDKs)
+
+The interpreter is synchronous. `runAsync`/`handleAsync` run it in a Worker and block on
+`Atomics.wait` while your Promises resolve on the main thread:
+
+```js
+const r = await syn.runAsync(program, { host: { async http(req) { const res = await fetch(req.url); return { status: res.status, headers: res.headers, body: await res.text() }; } } });
+await syn.close();
+```
+
+Node/Bun/Deno: works out of the box. Browsers: needs cross-origin isolation
+(`Cross-Origin-Opener-Policy: same-origin` + `Cross-Origin-Embedder-Policy: require-corp`)
+for `SharedArrayBuffer`. Without it, use the sync API with a sync host.
+
+## `serve` without sockets (edge handler)
+
+```js
+const app = `require serve(8080)
+serve on 8080
+    route "GET /hello/:name"
+        give {"hi": params.name, "visits": state_incr("visits")}`;
+const res = syn.handle(app, { method: "GET", path: "/hello/ana", headers: {} }, { host });
+res.status; res.content_type; res.headers; res.body;
+```
+
+Routes, params, query, `auth with`, `errors with`, `content()` negotiation, `redirect`,
+pagination and `state_*` (durable through your `kv`) work as in the native server. Not in
+handler mode: `stream` (SSE), `proxy to`, rate limits, `static` mounts, vhosts, TLS —
+your edge platform does those before calling the handler.
+
+## Also: `test`, `check`, `version`
+
+`syn.test(source)` runs the file's `test` blocks; `syn.check(source)` parses and
+validates without running; `syn.version()` is the artifact's release tag.
+
+## Files, time, randomness
+
+This artifact has **no filesystem** (`read_file` says so; pass data through `env` or the
+source). `now()` comes from `Date.now()`; `random()`, `token()` and every signature nonce
+come from `crypto.getRandomValues`. For file-based confidential jobs use the wasip1 build
+under wasmtime (see the Synsema docs, *WebAssembly*).
+
+## Other languages
+
+The `.wasm` has a plain JSON ABI (`synsema_call`) and three imports (`synsema_host`),
+so it embeds anywhere: see `examples/embed/python` (wasmtime-py) and `examples/embed/go`
+(wazero) in the repository.

package/bridge.mjs

@@ -0,0 +1,134 @@
+// Bridge asíncrono: el intérprete (síncrono) corre en un Worker; cuando necesita al
+// host (http/kv/llm/log/sleep) manda el pedido al main thread y se bloquea con
+// Atomics.wait sobre un SharedArrayBuffer hasta que la Promise del host resuelve.
+//
+// Layout del SAB: Int32Array ctrl = [estado, len_chunk, restante]; datos desde el
+// byte 16. Estados: 0 = esperando, 1 = último chunk listo, 2 = chunk listo (hay más),
+// 3 = el host no ofrece ese hook. Respuestas más grandes que el SAB viajan en chunks:
+// el worker copia, pone 0, avisa con `ack` y el main escribe el siguiente.
+//
+// Navegador: SharedArrayBuffer requiere cross-origin isolation (headers
+// Cross-Origin-Opener-Policy: same-origin + Cross-Origin-Embedder-Policy: require-corp).
+// Node/Bun/Deno: funciona sin más.
+
+import { dispatchHostAsync } from "./index.mjs";
+
+const te = new TextEncoder();
+const IS_NODE = typeof process !== "undefined" && process.versions && process.versions.node;
+const DATA_OFFSET = 16;
+
+async function spawnWorker() {
+  const url = new URL("./worker.mjs", import.meta.url);
+  if (IS_NODE) {
+    const { Worker } = await import("node:worker_threads");
+    const w = new Worker(url);
+    return {
+      post: (m) => w.postMessage(m),
+      onMessage: (fn) => w.on("message", fn),
+      onError: (fn) => w.on("error", fn),
+      terminate: () => w.terminate(),
+    };
+  }
+  const w = new Worker(url, { type: "module" });
+  return {
+    post: (m) => w.postMessage(m),
+    onMessage: (fn) => (w.onmessage = (e) => fn(e.data)),
+    onError: (fn) => (w.onerror = (e) => fn(e.error ?? new Error(e.message))),
+    terminate: () => w.terminate(),
+  };
+}
+
+export async function createBridge(module, { bridgeBytes = 4 * 1024 * 1024 } = {}) {
+  if (typeof SharedArrayBuffer === "undefined") {
+    throw new Error(
+      "synsema: the async mode needs SharedArrayBuffer (in browsers, serve the page cross-origin isolated: COOP same-origin + COEP require-corp); use the sync API with a sync host instead",
+    );
+  }
+  const sab = new SharedArrayBuffer(DATA_OFFSET + bridgeBytes);
+  const ctrl = new Int32Array(sab, 0, 4);
+  const data = new Uint8Array(sab, DATA_OFFSET);
+  const w = await spawnWorker();
+
+  let pending = null; // { resolve, reject, host }
+  let sending = null; // { bytes, offset }
+
+  function writeChunk() {
+    const { bytes } = sending;
+    const n = Math.min(bytes.length - sending.offset, data.length);
+    data.set(bytes.subarray(sending.offset, sending.offset + n));
+    sending.offset += n;
+    const remaining = bytes.length - sending.offset;
+    Atomics.store(ctrl, 1, n);
+    Atomics.store(ctrl, 2, remaining);
+    Atomics.store(ctrl, 0, remaining > 0 ? 2 : 1);
+    Atomics.notify(ctrl, 0);
+    if (remaining === 0) sending = null;
+  }
+
+  function reply(result) {
+    if (result === undefined) {
+      Atomics.store(ctrl, 0, 3);
+      Atomics.notify(ctrl, 0);
+      return;
+    }
+    sending = { bytes: te.encode(JSON.stringify(result ?? null)), offset: 0 };
+    writeChunk();
+  }
+
+  const ready = new Promise((resolve, reject) => {
+    w.onError((e) => {
+      const p = pending;
+      pending = null;
+      if (p) p.reject(e);
+      else reject(e);
+    });
+    w.onMessage(async (m) => {
+      switch (m.type) {
+        case "ready":
+          resolve();
+          break;
+        case "host": {
+          let result;
+          try {
+            result = await dispatchHostAsync(pending?.host, m.kind, m.payload);
+          } catch (e) {
+            result = { error: String(e && e.message ? e.message : e) };
+          }
+          reply(result);
+          break;
+        }
+        case "ack":
+          if (sending) writeChunk();
+          break;
+        case "result": {
+          const p = pending;
+          pending = null;
+          p?.resolve(m.response);
+          break;
+        }
+        case "error": {
+          const p = pending;
+          pending = null;
+          p?.reject(new Error(m.message));
+          break;
+        }
+      }
+    });
+  });
+  w.post({ type: "init", module, sab });
+  await ready;
+
+  return {
+    call(request, host) {
+      if (pending) return Promise.reject(new Error("synsema: one call at a time per instance"));
+      return new Promise((resolve, reject) => {
+        pending = { resolve, reject, host };
+        Atomics.store(ctrl, 0, 0);
+        w.post({ type: "call", request });
+      });
+    },
+    async close() {
+      await w.terminate();
+    },
+  };
+}

package/index.d.ts

@@ -0,0 +1,141 @@
+// Tipos de @synsema/wasm — la frontera JSON de synsema-wasm-web.
+
+export type HeaderPairs = Array<[string, string]>;
+
+export interface HttpRequestPayload {
+  method: string;
+  url: string;
+  headers: HeaderPairs;
+  /** Body como texto (o `body_base64` si era binario). */
+  body?: string | null;
+  body_base64?: string;
+  /** Segundos. */
+  timeout: number;
+}
+
+export interface HttpResponsePayload {
+  status: number;
+  headers?: HeaderPairs | Record<string, string> | Headers;
+  body?: string | Uint8Array | ArrayBuffer | null;
+  /** Error de transporte (DNS, timeout…): el programa lo ve en `{error: …}`. */
+  error?: string;
+}
+
+export interface KvStore {
+  get(ns: string, key: string): string | null | undefined | Promise<string | null | undefined>;
+  set(ns: string, key: string, value: string): void | Promise<void>;
+  delete?(ns: string, key: string): void | Promise<void>;
+  /** Claves del namespace (para `state_all`). */
+  list?(ns: string): string[] | Promise<string[]>;
+}
+
+export interface LlmResult {
+  content: string;
+  /** Tokens consumidos (alimenta `llm_usage()`). */
+  tokens?: number;
+}
+
+/**
+ * Lo que tu app le PRESTA al programa. Cada hook es opcional; lo que falta hace que el
+ * builtin correspondiente falle con un error claro. El programa igual debe declarar
+ * `require net("host")` / `require llm` / `require memory("x")`, y `ceiling` manda.
+ * En la API síncrona los hooks deben ser síncronos; en `*Async` pueden devolver Promise.
+ */
+export interface Host {
+  http?(req: HttpRequestPayload): HttpResponsePayload | Promise<HttpResponsePayload>;
+  kv?: KvStore;
+  llm?(op: string, prompt: string): string | LlmResult | Promise<string | LlmResult>;
+  log?(line: string): void | Promise<void>;
+  /** Una función, o `true` para la pausa por defecto (Atomics.wait / setTimeout). */
+  sleep?: ((secs: number) => void | Promise<void>) | true;
+}
+
+export interface RunOptions {
+  filename?: string;
+  /** Reemplaza al `.env`: `secret("KEY")`/`env("KEY")` resuelven de acá. */
+  env?: Record<string, string>;
+  /** `"sandbox"` (stdout + time) o la lista de `--cap-set`: `"stdout,secret=ETH_*"`. */
+  ceiling?: string;
+  host?: Host;
+}
+
+export interface AuditEntry {
+  capability: string;
+  granted: boolean;
+  source: string;
+  reason: string;
+}
+
+export interface RunResult {
+  ok: boolean;
+  /** Las líneas de `print`. */
+  output: string[];
+  errors: string[];
+  audit: AuditEntry[];
+  llm_tokens: number;
+}
+
+export interface TestResult {
+  ok: boolean;
+  passed: number;
+  failed: number;
+  lines: string[];
+  audit: AuditEntry[];
+}
+
+export interface CheckResult {
+  ok: boolean;
+  errors: string[];
+}
+
+export interface HandleRequest {
+  method?: string;
+  /** Path, con `?query` opcional. */
+  path?: string;
+  headers?: HeaderPairs | Record<string, string> | Headers;
+  body?: string | Uint8Array | ArrayBuffer | null;
+  ip?: string;
+}
+
+export interface HandleResult {
+  status: number;
+  content_type: string;
+  headers: HeaderPairs;
+  body?: string;
+  /** Cuerpo binario (cuando no es UTF-8). */
+  body_base64?: string;
+  /** Líneas de `print` del handler. */
+  log: string[];
+  /** Errores de preparación del programa (parse/top-level); el status es 500. */
+  errors: string[];
+  audit: AuditEntry[];
+}
+
+export type ModuleSource = WebAssembly.Module | Uint8Array | ArrayBuffer | URL | string | Response;
+
+export declare function readModule(src: ModuleSource): Promise<WebAssembly.Module>;
+export declare function offersOf(host?: Host): Record<string, boolean>;
+export declare function sleepSync(secs: number): void;
+export declare function instantiate(
+  module: WebAssembly.Module,
+  hostCall: (kind: string, payload: any) => any,
+): Promise<{ exports: WebAssembly.Exports; call(request: object): any }>;
+
+export declare class Synsema {
+  constructor(module: WebAssembly.Module);
+  static load(src: ModuleSource): Promise<Synsema>;
+  /** Prepara la instancia síncrona (obligatorio antes de run/test/check/handle). */
+  ready(): Promise<this>;
+  version(): string;
+  run(source: string, opts?: RunOptions): RunResult;
+  test(source: string, opts?: RunOptions): TestResult;
+  check(source: string, opts?: { filename?: string }): CheckResult;
+  handle(source: string, request: HandleRequest, opts?: RunOptions): HandleResult;
+  /** Modo asíncrono (Worker + Atomics): los hooks del host pueden ser async. */
+  runAsync(source: string, opts?: RunOptions): Promise<RunResult>;
+  testAsync(source: string, opts?: RunOptions): Promise<TestResult>;
+  handleAsync(source: string, request: HandleRequest, opts?: RunOptions): Promise<HandleResult>;
+  close(): Promise<void>;
+}
+
+export default Synsema;

package/index.mjs

@@ -0,0 +1,371 @@
+// @synsema/wasm — Synsema embebido en JS/TS (navegador, Node ≥ 18, Bun, Deno).
+//
+// Glue de la ABI cruda de `synsema-wasm-web` (ver engine/crates/synsema-wasm-web):
+//   exports  synsema_alloc / synsema_free / synsema_call(json) -> [u32 len][json]
+//   imports  synsema_host.{host_call, host_random_fill, host_now_ms}
+//
+// Dos modos:
+//  - SÍNCRONO (`Synsema.run/test/check/handle`): el host que le pasás (http/kv/llm/log/
+//    sleep) debe responder de forma síncrona. Ideal en Node con un KV en memoria o un
+//    archivo JSON, o sin host.
+//  - ASÍNCRONO (`Synsema.runAsync/handleAsync`): el intérprete corre en un Worker y
+//    bloquea con Atomics.wait sobre un SharedArrayBuffer mientras tu `http`/`kv`/`llm`
+//    async resuelven en el main thread (fetch del navegador, IndexedDB, un SDK de LLM).
+//    En el navegador requiere cross-origin isolation (COOP/COEP) para SharedArrayBuffer.
+//
+// No hay estado global: cada `load()` es una instancia (memoria lineal propia).
+
+const te = new TextEncoder();
+const td = new TextDecoder();
+
+const IS_NODE = typeof process !== "undefined" && process.versions && process.versions.node;
+
+/** Lee el .wasm desde bytes, Module, URL/path o Response. */
+export async function readModule(src) {
+  if (src instanceof WebAssembly.Module) return src;
+  if (src instanceof Uint8Array || src instanceof ArrayBuffer) return WebAssembly.compile(src);
+  if (typeof Response !== "undefined" && src instanceof Response) {
+    return WebAssembly.compile(await src.arrayBuffer());
+  }
+  const isFileLike =
+    IS_NODE && (typeof src === "string" ? !/^https?:/.test(src) : src instanceof URL && src.protocol === "file:");
+  if (isFileLike) {
+    const { readFile } = await import("node:fs/promises");
+    const { fileURLToPath } = await import("node:url");
+    const p = typeof src === "string" ? src : fileURLToPath(src);
+    return WebAssembly.compile(await readFile(p));
+  }
+  const res = await fetch(src);
+  if (!res.ok) throw new Error(`synsema: cannot fetch ${src}: ${res.status}`);
+  if (WebAssembly.compileStreaming) return WebAssembly.compileStreaming(res);
+  return WebAssembly.compile(await res.arrayBuffer());
+}
+
+function randomFill(bytes) {
+  const c = globalThis.crypto;
+  if (!c || !c.getRandomValues) throw new Error("synsema: no crypto.getRandomValues in this host");
+  // getRandomValues acepta hasta 65536 bytes por llamada.
+  for (let i = 0; i < bytes.length; i += 65536) c.getRandomValues(bytes.subarray(i, Math.min(i + 65536, bytes.length)));
+}
+
+/** Qué ofrece un host: derivado de las funciones presentes. */
+export function offersOf(host) {
+  if (!host) return {};
+  const o = {};
+  if (typeof host.http === "function") o.http = true;
+  if (host.kv && typeof host.kv.get === "function") o.kv = true;
+  if (typeof host.llm === "function") o.llm = true;
+  if (typeof host.log === "function") o.log = true;
+  if (typeof host.sleep === "function" || host.sleep === true) o.sleep = true;
+  return o;
+}
+
+/** Un hook async usado desde la API síncrona devolvería una Promise donde el intérprete
+ *  espera un valor: en vez de un `{status: 0}` mudo, un error que nombra el fix. */
+function syncOnly(kind, r) {
+  if (r && typeof r.then === "function") {
+    throw new Error(`synsema: the host \`${kind}\` hook returned a Promise — use runAsync/handleAsync (Worker + Atomics) or make the hook synchronous`);
+  }
+  return r;
+}
+
+/** Despacha un `host_call` (kind, payload) a un host SÍNCRONO. Devuelve un objeto
+ *  JSON-serializable, o `undefined` si el host no ofrece ese hook. Un hook que devuelve
+ *  una Promise es un error (lo ve el programa como `{error}` / lo lanza `synsema_call`). */
+export function dispatchHostSync(host, kind, payload) {
+  if (!host) return undefined;
+  switch (kind) {
+    case "http":
+      return typeof host.http === "function" ? normalizeHttp(syncOnly("http", host.http(payload))) : undefined;
+    case "kv_get":
+      return host.kv ? { value: syncOnly("kv.get", host.kv.get(payload.ns, payload.key)) ?? null } : undefined;
+    case "kv_set":
+      if (!host.kv) return undefined;
+      syncOnly("kv.set", host.kv.set(payload.ns, payload.key, payload.value));
+      return {};
+    case "kv_delete":
+      if (!host.kv) return undefined;
+      syncOnly("kv.delete", host.kv.delete?.(payload.ns, payload.key));
+      return {};
+    case "kv_list":
+      return host.kv ? { keys: host.kv.list ? syncOnly("kv.list", host.kv.list(payload.ns)) : [] } : undefined;
+    case "llm":
+      return typeof host.llm === "function" ? normalizeLlm(syncOnly("llm", host.llm(payload.op, payload.prompt))) : undefined;
+    case "log":
+      if (typeof host.log !== "function") return undefined;
+      host.log(payload.line);
+      return {};
+    case "sleep":
+      if (typeof host.sleep === "function") {
+        host.sleep(payload.secs);
+        return {};
+      }
+      if (host.sleep === true) {
+        sleepSync(payload.secs);
+        return {};
+      }
+      return undefined;
+    default:
+      return undefined;
+  }
+}
+
+/** Igual que dispatchHostSync pero el host puede devolver Promises. */
+export async function dispatchHostAsync(host, kind, payload) {
+  if (!host) return undefined;
+  switch (kind) {
+    case "http":
+      return typeof host.http === "function" ? normalizeHttp(await host.http(payload)) : undefined;
+    case "kv_get":
+      return host.kv ? { value: (await host.kv.get(payload.ns, payload.key)) ?? null } : undefined;
+    case "kv_set":
+      if (!host.kv) return undefined;
+      await host.kv.set(payload.ns, payload.key, payload.value);
+      return {};
+    case "kv_delete":
+      if (!host.kv) return undefined;
+      await host.kv.delete?.(payload.ns, payload.key);
+      return {};
+    case "kv_list":
+      return host.kv ? { keys: host.kv.list ? await host.kv.list(payload.ns) : [] } : undefined;
+    case "llm":
+      return typeof host.llm === "function" ? normalizeLlm(await host.llm(payload.op, payload.prompt)) : undefined;
+    case "log":
+      if (typeof host.log !== "function") return undefined;
+      await host.log(payload.line);
+      return {};
+    case "sleep":
+      if (typeof host.sleep === "function") {
+        await host.sleep(payload.secs);
+        return {};
+      }
+      if (host.sleep === true) {
+        await new Promise((r) => setTimeout(r, payload.secs * 1000));
+        return {};
+      }
+      return undefined;
+    default:
+      return undefined;
+  }
+}
+
+function normalizeHttp(r) {
+  if (!r || typeof r !== "object") return { error: "host http returned nothing" };
+  const out = { status: r.status | 0, headers: [] };
+  if (r.error) out.error = String(r.error);
+  if (r.headers) {
+    if (Array.isArray(r.headers)) out.headers = r.headers;
+    else if (typeof r.headers.forEach === "function" && !(r.headers instanceof Array)) {
+      // Headers de fetch
+      r.headers.forEach((v, k) => out.headers.push([k, v]));
+    } else out.headers = Object.entries(r.headers);
+  }
+  if (r.body instanceof Uint8Array || r.body instanceof ArrayBuffer) {
+    out.body_base64 = b64(r.body instanceof Uint8Array ? r.body : new Uint8Array(r.body));
+  } else if (r.body != null) out.body = String(r.body);
+  return out;
+}
+
+function normalizeLlm(r) {
+  if (typeof r === "string") return { content: r, tokens: 0 };
+  if (r && typeof r === "object") return { content: String(r.content ?? ""), tokens: r.tokens | 0 };
+  return { content: "", tokens: 0 };
+}
+
+function b64(bytes) {
+  if (typeof Buffer !== "undefined") return Buffer.from(bytes).toString("base64");
+  let s = "";
+  for (let i = 0; i < bytes.length; i++) s += String.fromCharCode(bytes[i]);
+  return btoa(s);
+}
+
+export function sleepSync(secs) {
+  try {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, Math.max(0, secs * 1000));
+  } catch {
+    // Main thread del navegador: Atomics.wait no está permitido. Espera activa acotada.
+    const until = Date.now() + Math.min(secs, 5) * 1000;
+    while (Date.now() < until) { /* busy */ }
+  }
+}
+
+/**
+ * Instancia el módulo con un `hostCall(kind, payload) -> objeto | undefined` SÍNCRONO
+ * (el bridge async lo implementa con Atomics). Devuelve `{ call(request) -> response }`.
+ */
+export async function instantiate(module, hostCall) {
+  let exports = null;
+  const mem = () => new Uint8Array(exports.memory.buffer);
+  const writeBytes = (bytes) => {
+    const ptr = exports.synsema_alloc(bytes.length);
+    mem().set(bytes, ptr);
+    return ptr;
+  };
+  const imports = {
+    synsema_host: {
+      host_call(kp, kl, pp, pl) {
+        const kind = td.decode(mem().subarray(kp, kp + kl));
+        const payload = JSON.parse(td.decode(mem().subarray(pp, pp + pl)));
+        let result;
+        try {
+          result = hostCall(kind, payload);
+        } catch (e) {
+          result = { error: String(e && e.message ? e.message : e) };
+        }
+        if (result === undefined) return 0;
+        const bytes = te.encode(JSON.stringify(result ?? null));
+        const ptr = exports.synsema_alloc(4 + bytes.length);
+        const m = mem();
+        new DataView(m.buffer).setUint32(ptr, bytes.length, true);
+        m.set(bytes, ptr + 4);
+        return ptr;
+      },
+      host_random_fill(ptr, len) {
+        try {
+          randomFill(mem().subarray(ptr, ptr + len));
+          return 0;
+        } catch {
+          return 1;
+        }
+      },
+      host_now_ms() {
+        return Date.now();
+      },
+    },
+  };
+  const instance = await WebAssembly.instantiate(module, imports);
+  exports = instance.exports;
+  return {
+    exports,
+    call(request) {
+      const req = te.encode(JSON.stringify(request));
+      const rp = writeBytes(req);
+      let out;
+      try {
+        out = exports.synsema_call(rp, req.length);
+      } finally {
+        exports.synsema_free(rp, req.length);
+      }
+      const m = mem();
+      const len = new DataView(m.buffer).getUint32(out, true);
+      const json = td.decode(m.subarray(out + 4, out + 4 + len));
+      exports.synsema_free(out, 4 + len);
+      return JSON.parse(json);
+    },
+  };
+}
+
+function requestOf(op, source, opts = {}) {
+  const r = { op, source, filename: opts.filename ?? "<embedded>" };
+  if (opts.env) r.env = opts.env;
+  if (opts.ceiling) r.ceiling = opts.ceiling;
+  if (opts.host) r.host = offersOf(opts.host);
+  return r;
+}
+
+function normalizeRequest(request) {
+  const headers = Array.isArray(request.headers)
+    ? request.headers
+    : request.headers && typeof request.headers.forEach === "function"
+      ? (() => { const h = []; request.headers.forEach((v, k) => h.push([k, v])); return h; })()
+      : Object.entries(request.headers ?? {});
+  const out = { method: request.method ?? "GET", path: request.path ?? "/", headers, ip: request.ip ?? "" };
+  if (request.body instanceof Uint8Array || request.body instanceof ArrayBuffer) {
+    out.body_base64 = b64(request.body instanceof Uint8Array ? request.body : new Uint8Array(request.body));
+  } else out.body = request.body == null ? "" : String(request.body);
+  return out;
+}
+
+export class Synsema {
+  /** @param {WebAssembly.Module} module */
+  constructor(module) {
+    this.module = module;
+    this._inst = null;
+  }
+
+  /** Carga el .wasm (bytes, Module, URL/path, Response). */
+  static async load(src) {
+    return new Synsema(await readModule(src));
+  }
+
+  async _instance() {
+    if (!this._inst) {
+      // Cada llamada síncrona lleva su host; la instancia es una y despacha al host
+      // de la llamada en curso.
+      const self = this;
+      this._inst = await instantiate(this.module, (kind, payload) => dispatchHostSync(self._host, kind, payload));
+    }
+    return this._inst;
+  }
+
+  _callSync(request, host) {
+    const inst = this._instSync();
+    this._host = host;
+    try {
+      return inst.call(request);
+    } catch (e) {
+      // Un trap deja la instancia inservible: se reinstancia en la próxima llamada.
+      this._inst = null;
+      this._ready = null;
+      throw new Error(`synsema: the module trapped (${e && e.message ? e.message : e}); the instance was discarded`);
+    } finally {
+      this._host = null;
+    }
+  }
+
+  _instSync() {
+    if (!this._inst) throw new Error("synsema: call `await syn.ready()` (or use the *Async methods) before the first call");
+    return this._inst;
+  }
+
+  /** Prepara la instancia síncrona. Idempotente. */
+  async ready() {
+    if (!this._ready) this._ready = this._instance();
+    await this._ready;
+    return this;
+  }
+
+  version() {
+    return this._callSync({ op: "version" }).version;
+  }
+  run(source, opts = {}) {
+    return this._callSync(requestOf("run", source, opts), opts.host);
+  }
+  test(source, opts = {}) {
+    return this._callSync(requestOf("test", source, opts), opts.host);
+  }
+  check(source, opts = {}) {
+    return this._callSync({ op: "check", source, filename: opts.filename ?? "<embedded>" });
+  }
+  handle(source, request, opts = {}) {
+    return this._callSync({ ...requestOf("handle", source, opts), request: normalizeRequest(request) }, opts.host);
+  }
+
+  // ---- modo asíncrono (Worker + Atomics) ----
+
+  async _bridge() {
+    if (!this._worker) {
+      const { createBridge } = await import("./bridge.mjs");
+      this._worker = await createBridge(this.module);
+    }
+    return this._worker;
+  }
+  async runAsync(source, opts = {}) {
+    return (await this._bridge()).call(requestOf("run", source, opts), opts.host);
+  }
+  async testAsync(source, opts = {}) {
+    return (await this._bridge()).call(requestOf("test", source, opts), opts.host);
+  }
+  async handleAsync(source, request, opts = {}) {
+    return (await this._bridge()).call({ ...requestOf("handle", source, opts), request: normalizeRequest(request) }, opts.host);
+  }
+  /** Termina el Worker del modo asíncrono (si se creó). */
+  async close() {
+    if (this._worker) {
+      await this._worker.close();
+      this._worker = null;
+    }
+  }
+}
+
+export default Synsema;

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@synsema/wasm",
+  "version": "0.6.1",
+  "description": "Synsema — the programming language for AI agents — embedded as WebAssembly: run .syn programs inside browsers, Node/Bun/Deno and edge runtimes, lending them http/kv/llm from your app",
+  "license": "MIT",
+  "type": "module",
+  "main": "./index.mjs",
+  "module": "./index.mjs",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.mjs"
+    },
+    "./synsema.wasm": "./synsema.wasm",
+    "./bridge.mjs": "./bridge.mjs",
+    "./worker.mjs": "./worker.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "bridge.mjs",
+    "worker.mjs",
+    "index.d.ts",
+    "synsema.wasm",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kitecosmic/synsema.git",
+    "directory": "packages/synsema-wasm"
+  },
+  "keywords": [
+    "synsema",
+    "wasm",
+    "webassembly",
+    "agents",
+    "llm",
+    "edge"
+  ]
+}

package/worker.mjs

@@ -0,0 +1,76 @@
+// Lado Worker del bridge asíncrono (ver bridge.mjs). Corre en Node (worker_threads)
+// y en el navegador (module Worker). Instancia el .wasm con un hostCall que manda el
+// pedido al main thread y se bloquea con Atomics.wait hasta la respuesta.
+
+import { instantiate } from "./index.mjs";
+
+const td = new TextDecoder();
+const DATA_OFFSET = 16;
+const IS_NODE = typeof process !== "undefined" && process.versions && process.versions.node;
+
+let post;
+let onMessage;
+if (IS_NODE) {
+  const { parentPort } = await import("node:worker_threads");
+  post = (m) => parentPort.postMessage(m);
+  onMessage = (fn) => parentPort.on("message", fn);
+} else {
+  post = (m) => self.postMessage(m);
+  onMessage = (fn) => (self.onmessage = (e) => fn(e.data));
+}
+
+let module = null;
+let ctrl = null;
+let data = null;
+let inst = null;
+
+function hostCall(kind, payload) {
+  Atomics.store(ctrl, 0, 0);
+  post({ type: "host", kind, payload });
+  const parts = [];
+  for (;;) {
+    Atomics.wait(ctrl, 0, 0);
+    const state = Atomics.load(ctrl, 0);
+    if (state === 3) {
+      Atomics.store(ctrl, 0, 0);
+      return undefined;
+    }
+    const len = Atomics.load(ctrl, 1);
+    parts.push(data.slice(0, len));
+    if (state === 2) {
+      Atomics.store(ctrl, 0, 0);
+      post({ type: "ack" });
+      continue;
+    }
+    Atomics.store(ctrl, 0, 0);
+    break;
+  }
+  const total = parts.reduce((n, p) => n + p.length, 0);
+  const bytes = new Uint8Array(total);
+  let off = 0;
+  for (const p of parts) {
+    bytes.set(p, off);
+    off += p.length;
+  }
+  return JSON.parse(td.decode(bytes));
+}
+
+onMessage(async (m) => {
+  if (m.type === "init") {
+    module = m.module;
+    ctrl = new Int32Array(m.sab, 0, 4);
+    data = new Uint8Array(m.sab, DATA_OFFSET);
+    inst = await instantiate(module, hostCall);
+    post({ type: "ready" });
+    return;
+  }
+  if (m.type === "call") {
+    try {
+      const response = inst.call(m.request);
+      post({ type: "result", response });
+    } catch (e) {
+      post({ type: "error", message: `synsema: the module trapped (${e && e.message ? e.message : e}); the instance was recreated` });
+      inst = await instantiate(module, hostCall);
+    }
+  }
+});