@synsema/wasm 0.6.57 → 0.6.58

package/README.md

@@ -238,6 +238,34 @@ in a handler lists only what that request read (v0.6.46: not what the top-level
 handler mode: `stream` (SSE), `proxy to`, rate limits, `static` mounts, vhosts, TLS —
 your edge platform does those before calling the handler.
 
+## Packages: `project`, `packages` (v0.6.58)
+
+There is no `synsema get` here and no module cache: you hand the engine the program's
+`synsema.json` and the files of the packages it pins, and the engine checks every package
+against its hash before the first statement runs.
+
+```js
+const syn = await Synsema.load(wasmBytes, {
+  project: synsemaJson,                       // the text of synsema.json (or the object)
+  packages: { "tree-sha256:3cdf…": { "synsema.json": "…", "m.syn": "…" } },
+});
+await syn.ready();
+syn.run('use "tok" as tok\nprint(tok.encode("hola"))\n');
+```
+
+- `packages` is what `synsema get` left in the cache: per hash, every file of the package by its
+  path, the package's own `synsema.json` included. Files are text.
+- Both options go to `load`/`loadNode` and to each call. A call's `project` replaces the
+  instance's; its `packages` add to the instance's.
+- A package missing from `packages` stops the run with
+  `use "tok": module tok 0.1.0 is not in the packages the host passed`, and one whose files changed
+  with `… the files of tok (tree-sha256:…) do not match their hash`.
+- The instance keeps what it verified, by hash: a later call that brings (or only names) a
+  verified hash does not hash it again, and `@synsema/wasm` does not copy it to the Worker again.
+  Each response with a `project` lists those hashes in `packages_held`.
+- `receipt()` and the sealed receipt's header name the packages that ran
+  (`modules.packages`, with their version and hash).
+
 ## Also: `test`, `check`, `version`
 
 `syn.test(source)` runs the file's `test` blocks; `syn.check(source)` parses and

package/index.d.ts

@@ -79,7 +79,28 @@ export interface Host {
   sleep?: ((secs: number) => void | Promise<void>) | true;
 }
 
-export interface RunOptions {
+/**
+ * v0.6.58 — los paquetes que le pasás al motor, por su hash de árbol: `{"tree-sha256:…": {"<ruta>": "<texto>"}}`,
+ * con el `synsema.json` del paquete entre sus archivos (lo que `synsema get` dejó en el caché). El motor verifica
+ * cada hash antes de correr; un paquete que no coincide no corre.
+ */
+export type Packages = Record<string, Record<string, string>>;
+
+/** v0.6.58 — el proyecto de una llamada: el `synsema.json` del programa (texto u objeto) y sus paquetes. */
+export interface ProjectOptions {
+  /**
+   * El `synsema.json` del programa: fija qué paquete (y qué hash) es cada `use "nombre"`. El de una llamada
+   * reemplaza al de `load`/`loadNode`.
+   */
+  project?: string | Record<string, unknown>;
+  /**
+   * Los archivos de los paquetes que alcanza el programa. Los de una llamada se suman a los de `load`/`loadNode`.
+   * La instancia guarda lo verificado por su hash: lo que ya verificó no lo vuelve a hashear ni a copiar al Worker.
+   */
+  packages?: Packages;
+}
+
+export interface RunOptions extends ProjectOptions {
   filename?: string;
   /** Reemplaza al `.env`: `secret("KEY")`/`env("KEY")` resuelven de acá. */
   env?: Record<string, string>;
@@ -184,6 +205,8 @@ export interface RunResult {
    * armar, `ok` es false y `errors` lo dice.
    */
   receipt?: Record<string, unknown>;
+  /** v0.6.58 — los hashes que esta instancia ya verificó (no hace falta volver a mandarlos); en toda respuesta del motor. */
+  packages_held?: string[];
 }
 
 export interface TestResult {
@@ -192,11 +215,15 @@ export interface TestResult {
   failed: number;
   lines: string[];
   audit: AuditEntry[];
+  /** v0.6.58 — los hashes que esta instancia ya verificó (no hace falta volver a mandarlos); en toda respuesta del motor. */
+  packages_held?: string[];
 }
 
 export interface CheckResult {
   ok: boolean;
   errors: string[];
+  /** v0.6.58 — los hashes que esta instancia ya verificó (no hace falta volver a mandarlos); en toda respuesta del motor. */
+  packages_held?: string[];
 }
 
 export interface HandleRequest {
@@ -224,6 +251,8 @@ export interface HandleResult {
    * del operador: el programa (y el cliente) ven en `errors` un texto fijo, porque cuál sitio cortó lo eligió el
    * dato privado. No se lo devuelvas al modelo ni al cliente. */
   operator_detail?: string;
+  /** v0.6.58 — los hashes que esta instancia ya verificó (no hace falta volver a mandarlos); en toda respuesta del motor. */
+  packages_held?: string[];
 }
 
 export type ModuleSource = WebAssembly.Module | Uint8Array | ArrayBuffer | URL | string | Response;
@@ -238,7 +267,7 @@ export declare function instantiate(
   hostCall: (kind: string, payload: any) => any,
 ): Promise<{ exports: WebAssembly.Exports; call(request: object): any }>;
 
-export interface LoadOptions {
+export interface LoadOptions extends ProjectOptions {
   /** Cuántos Workers usa el modo asíncrono (default 1). Con más, `runAsync` corre en paralelo. */
   workers?: number;
   /**
@@ -271,7 +300,7 @@ export declare class Synsema {
   version(): string;
   run(source: string, opts?: RunOptions): RunResult;
   test(source: string, opts?: RunOptions): TestResult;
-  check(source: string, opts?: { filename?: string }): CheckResult;
+  check(source: string, opts?: { filename?: string } & ProjectOptions): CheckResult;
   handle(source: string, request: HandleRequest, opts?: RunOptions): HandleResult;
   /**
    * Modo asíncrono (Worker + Atomics): los hooks del host pueden ser async. Las llamadas esperan en

package/index.mjs

@@ -393,6 +393,53 @@ function requestOf(op, source, opts = {}) {
   return r;
 }
 
+/**
+ * v0.6.58 (§12, E-12) — el proyecto de una llamada: `project` (el texto de `synsema.json`, o el
+ * objeto) y `packages` (`{"tree-sha256:…": {"<ruta>": "<texto>"}}`). Los de la llamada van sobre los
+ * de `load`/`loadNode`: el `project` de la llamada reemplaza al de la instancia y sus `packages` se
+ * suman a los de la instancia.
+ */
+function withProject(request, defaults, opts) {
+  const project = opts.project ?? defaults.project;
+  if (project == null) {
+    if (opts.packages != null) request.packages = opts.packages;
+    return request;
+  }
+  request.project = typeof project === "string" ? project : JSON.stringify(project);
+  const packages = { ...(defaults.packages ?? {}), ...(opts.packages ?? {}) };
+  if (Object.keys(packages).length > 0) request.packages = packages;
+  return request;
+}
+
+/**
+ * W9: lo que la instancia de wasm ya verificó no se vuelve a mandar (ni a copiar al Worker): el
+ * motor lo tiene guardado por su hash, que es el del contenido. `held` es el conjunto de esa
+ * instancia; se actualiza con `packages_held` de cada respuesta.
+ */
+function withoutHeld(request, held) {
+  if (!request.packages || !held || held.size === 0) return request;
+  const left = {};
+  let dropped = false;
+  for (const [h, files] of Object.entries(request.packages)) {
+    if (held.has(h)) dropped = true;
+    else left[h] = files;
+  }
+  if (!dropped) return request;
+  const r = { ...request };
+  if (Object.keys(left).length > 0) r.packages = left;
+  else delete r.packages;
+  return r;
+}
+
+function noteHeld(holder, response) {
+  // M6 (ronda 1): una respuesta sin `packages_held` (o un error, en `_dispatch`) no dice qué guarda
+  // la instancia, que pudo recrearse: se olvida todo y la próxima llamada manda los paquetes. Ronda 2
+  // (N-r2-3): el motor lo pone en TODA respuesta suya (`version`, sin proyecto, un error), así que
+  // sólo falta cuando no respondió el motor (un trap, el resultado que arma el Worker).
+  holder._held = response && Array.isArray(response.packages_held) ? new Set(response.packages_held) : null;
+  return response;
+}
+
 function normalizeRequest(request) {
   const headers = Array.isArray(request.headers)
     ? request.headers
@@ -422,6 +469,12 @@ export class Synsema {
     }
     this._startMs = opts.startMs;
     this._bridges = [];
+    // v0.6.58 (§12): el proyecto y los paquetes de todas las llamadas de esta instancia.
+    this._defaults = { project: opts.project, packages: opts.packages };
+  }
+
+  _req(op, source, opts) {
+    return withProject(requestOf(op, source, opts), this._defaults, opts);
   }
 
   /** Carga el .wasm (bytes, Module, URL/path, Response). */
@@ -471,7 +524,7 @@ export class Synsema {
     const inst = this._instSync();
     this._host = host;
     try {
-      return inst.call(request);
+      return noteHeld(inst, inst.call(withoutHeld(request, inst._held)));
     } catch (e) {
       // Un trap deja la instancia inservible: se recrea ya (sincrónico, con el Module compilado),
       // así la próxima llamada anda sin `await syn.ready()` (v0.6.45, D4). Si el host no deja
@@ -508,16 +561,16 @@ export class Synsema {
     return this._callSync({ op: "version" }).version;
   }
   run(source, opts = {}) {
-    return this._callSync(requestOf("run", source, opts), opts.host);
+    return this._callSync(this._req("run", source, opts), opts.host);
   }
   test(source, opts = {}) {
-    return this._callSync(requestOf("test", source, opts), opts.host);
+    return this._callSync(this._req("test", source, opts), opts.host);
   }
   check(source, opts = {}) {
-    return this._callSync({ op: "check", source, filename: opts.filename ?? "<embedded>" });
+    return this._callSync(withProject({ op: "check", source, filename: opts.filename ?? "<embedded>" }, this._defaults, opts));
   }
   handle(source, request, opts = {}) {
-    return this._callSync({ ...requestOf("handle", source, opts), request: normalizeRequest(request) }, opts.host);
+    return this._callSync({ ...this._req("handle", source, opts), request: normalizeRequest(request) }, opts.host);
   }
 
   // ---- modo asíncrono (Worker + Atomics) ----
@@ -591,7 +644,10 @@ export class Synsema {
   }
 
   _dispatch(b, it) {
-    b.call(it.request, it.host, it.timeoutMs).then(it.resolve, (e) => {
+    // W9: cada Worker tiene su instancia de wasm, y con ella lo que ya verificó.
+    b.call(withoutHeld(it.request, b._held), it.host, it.timeoutMs).then((r) => it.resolve(noteHeld(b, r)), (e) => {
+      // M6 (ronda 1): el Worker pudo recrear su instancia (un trap) o morir: no guarda nada.
+      b._held = null;
       // No se llegó a mandar (el Worker se cerró antes): vuelve al principio de la cola. Lo que sí
       // corrió (un timeout, un Worker que murió en el medio) NO se reintenta: pudo tener efectos.
       if (e && e.synsemaWorkerClosed && !this._closed) {
@@ -622,13 +678,13 @@ export class Synsema {
     });
   }
   async runAsync(source, opts = {}) {
-    return this._callAsync(requestOf("run", source, opts), opts);
+    return this._callAsync(this._req("run", source, opts), opts);
   }
   async testAsync(source, opts = {}) {
-    return this._callAsync(requestOf("test", source, opts), opts);
+    return this._callAsync(this._req("test", source, opts), opts);
   }
   async handleAsync(source, request, opts = {}) {
-    return this._callAsync({ ...requestOf("handle", source, opts), request: normalizeRequest(request) }, opts);
+    return this._callAsync({ ...this._req("handle", source, opts), request: normalizeRequest(request) }, opts);
   }
   /**
    * Termina los Workers del modo asíncrono. Es FINAL (ronda 2, B1): lo que esperaba en la cola falla

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synsema/wasm",
-  "version": "0.6.57",
+  "version": "0.6.58",
   "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",

package/worker.mjs

@@ -84,7 +84,8 @@ onMessage(async (m) => {
         post({ type: "fatal", message: `the module trapped and could not be instantiated again: ${safeMsg(e2)}` });
         return;
       }
-      if (e && e.synsemaResult) post({ type: "result", response: e.synsemaResult });
+      // M6 (ronda 1): la instancia nueva no guarda ningún paquete, diga lo que diga la vieja.
+      if (e && e.synsemaResult) post({ type: "result", response: { ...e.synsemaResult, packages_held: [] } });
       else post({ type: "error", message: `synsema: the module trapped (${safeMsg(e)}); the instance was recreated` });
     }
   }