@synsema/wasm 0.6.45 → 0.6.47

package/README.md

@@ -34,6 +34,7 @@ const r = await syn.runAsync(code, {
   host,
   labels: true,                                    // information-flow labels on
   input: { var: "customer", value: row, sources: { card: ["customer"] } },
+  result: "out",                                   // r.result = the final value of `out`
   timeoutMs: 2000,                                 // the Worker is stopped past this
   maxSteps: 5_000_000,                             // interpreter steps, deterministic
   maxMemoryMb: 64,                                 // memory the run reserves
@@ -44,19 +45,84 @@ const r = await syn.runAsync(code, {
   private value, or a branch that depended on one, never reaches `print`, your `http` hook
   (`fetch`/`http_*`), your `kv` (`state_*`, `remember`), your `llm` or your `sleep` (its number
   crosses to the host): the call fails with `label_violation` before the hook runs.
-  `r.private_seen` says whether one went through.
+  `r.private_seen` says whether one went through; then `r.steps` is `null` (how many steps the
+  run took depended on the data). `sources` needs `labels: true`.
+- `result: "out"` returns the final value of the global `out` in `r.result`, with its labels: a
+  private part comes back as `{"$private": ["customer"], "value": …}`. `r.declassify` lists each
+  `declassify` the run made. Without `labels`, `result` is plain JSON.
 - `timeoutMs` (async mode): `0` means no deadline; otherwise milliseconds, up to 2147483647,
-  counted from when the call starts running, not while it waits in the queue. Past it the call fails with a clear error and its Worker is replaced. The server's own
-  thread never blocks. A host hook with no deadline of its own that never answers keeps its Worker
-  busy unless the call has a `timeoutMs`.
+  counted from when the call starts running, not while it waits in the queue. Past it the call
+  fails with a clear error and its Worker is replaced. The server's own thread never blocks. A
+  host hook already running (a `fetch`) is not cut; its result is discarded. A host hook with no
+  deadline of its own that never answers keeps its Worker busy unless the call has a `timeoutMs`.
 - `maxSteps` and `maxMemoryMb` (both modes): the run ends with `ok: false` and an error that says
   which limit it hit — never a trap. `maxSteps` counts interpreter steps from the start of the run
   (in `handle`, of each request); `maxMemoryMb` counts the memory the run reserves, not what the
-  instance already held.
+  instance already held. Both are positive integers: `0` is an error, not "no limit". No call
+  inherits the limits of the previous one.
 - Concurrent async calls wait in one queue and go to the first free Worker (up to `workers: n`). A
   Worker that does not start in `startMs` (an option of `Synsema.load`/`loadNode`, default 30 s) is
-  stopped. In the sync API a trap
-  recreates the instance by itself.
+  stopped. A Worker that dies fails the call it was running (not retried: it may have had
+  effects) and is replaced. `close()` is final: what waits fails with "closed".
+- A host hook that returns something that is not JSON (a `BigInt`, a circular object) or throws a
+  value without a message counts as that hook failing in that call, in both APIs — not a hung
+  Worker or a trapped module.
+- In the sync API a trap recreates the instance by itself (the call throws
+  `synsema: the module trapped (…); the instance was recreated`; the next call works).
+- With `labels: true`, a run that hits `maxMemoryMb` reports `steps: null` and
+  `private_seen: true` (whether it ran out of memory can depend on a private value): treat it as
+  sensitive, like any run with `private_seen`.
+
+### Ceilings for labelled code (v0.6.46)
+
+- **`declassify` is bounded by `ceiling`.** With `labels: true` and a ceiling, only the principals
+  the ceiling names can be published: `ceiling: "stdout,declassify=customers"` (globs work:
+  `declassify=cust*`; a bare `declassify` allows any; `"sandbox"` never grants it). Otherwise
+  `declassify` fails with `label_violation: declassify is not granted for what this value is private
+  to (customers) …`, which `try`/`recover` cannot catch. Without a ceiling, or without `labels`,
+  nothing changes. **Breaking** for a host that runs labelled code under a ceiling and expects it to
+  publish: add `declassify=<principal>`.
+- **Private data to your `llm` hook:** the program declares `require llm("customers")` and the
+  ceiling says `llm=customers@embedder` (or `llm=customers@*`). Then the prompt carries the data,
+  your hook gets `info.principals` (`["customers"]`), the answer comes back private, and `audit`
+  has `llm("customers@embedder")` (source `llm-data`). Anything less (`llm=customers@local`,
+  `llm=customers`, no ceiling, a bare `require llm`) refuses it before the hook runs. `judge` is the
+  same with `require judge("…")` and `judge=…@embedder`.
+- **`judge` checks its capability:** a `ceiling` without `judge` refuses a `judge` block
+  (`Capability not granted: judge — declared but above the host ceiling …`).
+
+### Trusted tools: `trusted`, `trustedCeiling` (v0.6.46)
+
+```js
+const trusted = { tools: `export task first_name(c)
+    require declassify("customers")
+    give declassify(c.name, "the customer's own name")
+` };
+const code = `use "trusted:tools" as t
+let c be private({"name": "Ana", "card": "4111"}, "customers")
+print(t.first_name(c))`;
+syn.run(code, { labels: true, ceiling: "stdout", trusted, trustedCeiling: "declassify=customers" });  // prints Ana
+```
+
+Code you do not trust can only call the exported tasks of a module you lend; each runs with its own
+`require`, bounded by `trustedCeiling` (give one: without it a trusted task declassifies any
+principal), and nothing from the caller. Its arguments are data (a task or a lambda among them is
+an error). Works in `run`, `test`, `handle` and their `*Async` forms.
+
+### Sealed receipts: `auditor` (v0.6.46)
+
+The engine accepts `auditor` (an X25519 public key in base64url, from `synsema receipt keygen`) and
+`sealed_bytes` (4096–16777216, default 65536) in a `run` request and returns the sealed receipt in
+`receipt`. In v0.6.46 `run()`/`runAsync()` do not pass `auditor` on; use the low-level API:
+
+```js
+import { Synsema, instantiateSync, dispatchHostSync, offersOf } from "@synsema/wasm";
+const syn = await Synsema.loadNode();
+const host = { kv: { get: (ns, k) => null, set: (ns, k, v) => {} } };
+const inst = instantiateSync(syn.module, (kind, payload) => dispatchHostSync(host, kind, payload));
+const r = inst.call({ op: "run", source: code, filename: "app.syn", labels: true, auditor: AUDITOR_PUBLIC_KEY, host: offersOf(host) });
+r.receipt;   // the receipt object: write it as one JSON line for `synsema receipt verify` / `open`
+```
 
 ## Lending capabilities (the host)
 
@@ -68,7 +134,7 @@ makes the builtin fail with a clear error; a `ceiling` denies above what the hos
 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 }),
+  llm: (op, prompt, info) => ({ content: "…", tokens: 12 }),   // info.principals (v0.6.46)
   log: (line) => console.log(line),
 };
 
@@ -77,11 +143,69 @@ syn.run(`require llm\nprint(reason about "the weather")`, { host, ceiling: "stdo
 ```
 
 - `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.
+  `memory:<declared name>`) and `state_*` (namespace `state`). `delete` and `list` are optional
+  (without `list`, `state_all()` is `{}`). `get` returns the stored **text** or `null`/`undefined`;
+  `list` returns the key names as an array of strings.
+- `kv.cas(ns, key, expected, value)` (optional) is compare-and-swap: write `value` only if the
+  stored text is exactly `expected` (`null` = the key does not exist) and return `true` or
+  `false` — anything else fails the call with `kv.cas must return true or false`. Your store must
+  compare and write in one step (a transaction, a conditional put):
+
+  ```js
+  cas: (ns, k, expected, v) => {
+    if ((store.get(ns + "/" + k) ?? null) !== expected) return false;
+    store.set(ns + "/" + k, v);
+    return true;
+  },
+  ```
+
+  `state_merge(key, map)` and `state_cas(key, expected, new)` depend on it. With a host `kv`
+  that has `cas` they are atomic, also across instances sharing the store. With a host `kv`
+  without `cas` they fail saying so (`the host's kv does not offer cas (kv.cas) …`) instead of
+  risking a lost write. With no host `kv`, the state belongs to the wasm instance and is atomic:
+  it lasts across that instance's `handle` requests, and each `run` starts with an empty state.
+- `llm(op, prompt, info)` backs `reason`/`decide`/`analyze`/`generate`; `llm_usage()` sums the
+  tokens you report. `info.principals` lists the owners of the private data in the prompt (`[]`
+  with public data).
 - `http` backs `fetch`/`http_*` and the blockchain read-side RPC — after the `net(host)`
   gate, with the same URL canonicalization as the native binary.
 
+### What a hook must answer (v0.6.46 — breaking)
+
+A hook that fails, or answers something unexpected, is an **error of the builtin that asked**, not
+"the key is not there" (before, the next write replaced what your store held):
+
+| Your hook | The program gets |
+|---|---|
+| `kv.get` throws / rejects | `state_get: host kv.get failed: <message>` |
+| `kv.get` returns a number, boolean or object | `… kv.get must return a string or null, got a number` |
+| the stored text is not JSON | `state_incr: the stored value of 'c' is not JSON (…)`; nothing is written |
+| `kv.list` throws, or returns `{keys: [{name}]}` (Cloudflare KV), `[{name}]`, `undefined` | `state_all: host kv.list failed: kv.list must return a list of strings, got an object` |
+| a declared `memory` fails to load or is unreadable | the memory is not opened: `memory "agenda" could not be loaded (…); nothing was loaded, so nothing is written over it` |
+| reading the audit log of `reveal`/`sign`/`wallet`/`spend` fails | the operation is refused; the log stays as it was |
+| `llm` throws | that call fails with the hook's message (`the host's llm hook threw` without one); redacted when the prompt carried private data |
+
+To migrate: give back the exact text the engine handed to `set` (it is JSON; do not parse it), and
+make `list` return key names. Over a store whose `list` answers `{keys: [{name}]}`:
+
+```js
+list: async (ns) => (await store.list({ prefix: `${ns}/` })).keys.map((x) => x.name.slice(ns.length + 1)),
+```
+
+### The `http` hook: redirects and private addresses (v0.6.46)
+
+- A request that carries a secret (URL, query, body, form or any header) arrives with
+  `req.redirect === "error"`. Honor it — with `fetch`, pass `redirect: req.redirect ?? "follow"` —
+  or a 3xx carries the key to a host the program never named.
+- In wasm the engine checks the host **name** against `require net`, never the address. Natively a
+  wildcard `net` grant reaches only public addresses; here that is your hook's job if the programs
+  are not yours: resolve the name, check the address against loopback, the private networks (RFC
+  1918, CGNAT `100.64.0.0/10`, ULA `fc00::/7`), link-local (`169.254.0.0/16`, the cloud metadata
+  endpoint, `fe80::/10`), multicast and the documentation ranges (an IPv4 inside an IPv6 counts as
+  that IPv4), and connect to that same address. The hook does not know whether the program named
+  the host, so name the private destinations your programs need in the hook. A complete Node hook
+  (`node:https` with a checking `lookup`) is in the Synsema docs, *WebAssembly*.
+
 ## Async hosts (browser `fetch`, IndexedDB, LLM SDKs)
 
 The interpreter is synchronous. `runAsync`/`handleAsync` run it in a Worker and block on
@@ -108,7 +232,8 @@ 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
+pagination and `state_*` (durable through your `kv`) work as in the native server. `receipt()`
+in a handler lists only what that request read (v0.6.46: not what the top-level read). Not in
 handler mode: `stream` (SSE), `proxy to`, rate limits, `static` mounts, vhosts, TLS —
 your edge platform does those before calling the handler.
 
@@ -120,8 +245,12 @@ 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
+source). `now()` comes from `Date.now()`. Each call asks the host once for 32 bytes of
+entropy (`crypto.getRandomValues`), which seed that run's own ChaCha generator: `random()`,
+`random_bytes(n)`, `token()` and RSA blinding draw from it and never ask the host again, so how
+much randomness a run used does not show. With `labels`, `now()` returns the clock read at the
+start of the run and at each interaction with the host (a hook call), so when and how often the
+program read the clock does not show either. For file-based confidential jobs use the wasip1 build
 under wasmtime (see the Synsema docs, *WebAssembly*).
 
 ## Other languages

package/index.d.ts

@@ -11,6 +11,12 @@ export interface HttpRequestPayload {
   body_base64?: string;
   /** Segundos. */
   timeout: number;
+  /**
+   * v0.6.46: `"error"` cuando la request lleva un secret (en la URL, la query, el body o un header:
+   * `fetch` sólo quita `Authorization` al cambiar de host). Pasalo a `fetch` (`{redirect: req.redirect}`): un redirect no puede llevar la clave
+   * a otro host. Un hook que lo ignore queda fuera de lo que el motor puede imponer.
+   */
+  redirect?: "error";
 }
 
 export interface HttpResponsePayload {
@@ -48,9 +54,26 @@ export interface LlmResult {
  * En la API síncrona los hooks deben ser síncronos; en `*Async` pueden devolver Promise.
  */
 export interface Host {
+  /**
+   * v0.6.46: en nativo, un `require net` con comodín sólo llega a IPs públicas (el motor resuelve
+   * y chequea la IP antes de conectar). Acá la conexión es tuya y el motor no ve la IP: si el
+   * programa no es tuyo, resolvé el nombre y chequeá la IP a la que vas a conectar (un nombre como
+   * `127.0.0.1.nip.io` resuelve al loopback), y conectá a ésa. Negá loopback (`127.0.0.0/8`,
+   * `::1`), las redes privadas (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, CGNAT
+   * `100.64.0.0/10`, ULA `fc00::/7`), link-local (`169.254.0.0/16` con la metadata de la nube
+   * `169.254.169.254`, `fe80::/10`), multicast y los rangos de documentación; una IPv4 dentro de una
+   * IPv6 (`::ffff:a.b.c.d`) cuenta como esa IPv4. El hook no sabe si el programa nombró el host
+   * (`require net("db")`): si tus programas necesitan llegar a una red privada, nombrá vos esos
+   * destinos en el hook.
+   */
   http?(req: HttpRequestPayload): HttpResponsePayload | Promise<HttpResponsePayload>;
   kv?: KvStore;
-  llm?(op: string, prompt: string): string | LlmResult | Promise<string | LlmResult>;
+  /**
+   * `info.principals`: los dueños de lo privado que lleva el prompt (vacío con datos públicos).
+   * Sólo llega al hook si el techo lo permite (`llm=<principal>@embedder`). Un hook que lanza hace
+   * fallar esa llamada con su mensaje.
+   */
+  llm?(op: string, prompt: string, info: { principals: 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;
@@ -99,6 +122,17 @@ export interface RunOptions {
    * Igual que `maxSteps`. Un entero positivo.
    */
   maxMemoryMb?: number;
+  /**
+   * v0.6.46 — módulos de confianza: `{ nombre: fuente }`. El programa los importa con
+   * `use "trusted:nombre" as t` y sólo puede llamar a sus tasks exportadas, que corren con SUS
+   * `require` (acotados por `trustedCeiling`) y nada de lo del programa. Es la forma de dejar que
+   * código escrito por un modelo, bajo un `ceiling` sin `declassify`, publique sólo lo que la
+   * política de una persona publica. Los argumentos de una task de confianza son datos (una task
+   * o una lambda entre ellos es error).
+   */
+  trusted?: Record<string, string>;
+  /** El techo de los módulos de confianza, con la gramática de `ceiling` (`"stdout,declassify=clientes"`). */
+  trustedCeiling?: string;
 }
 
 export interface AuditEntry {
@@ -119,12 +153,18 @@ export interface RunResult {
   llm_tokens: number;
   /** v0.6.42 — el código de salida: el de `exit(code)` si el programa lo pidió, si no 0 (ok) o 1. */
   exit: number;
+  /** Los pasos del intérprete que llevó la corrida; `null` con `labels` si tocó un valor o una rama privada. */
+  steps: number | null;
   /** Con `result`: el valor final de esa variable (las partes privadas como `{"$private": [...]}`). */
   result?: unknown;
   /** Con `labels`: cada `declassify` que corrió (quién, qué principal, dónde). */
   declassify?: unknown[];
   /** Con `labels`: si algún valor privado pasó por la corrida (entonces `steps` no se publica). */
   private_seen?: boolean;
+  /** v0.6.47 — con `labels`, si un corte de etiquetas paró la corrida: qué falló, dónde y cómo arreglarlo. Es
+   * 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;
 }
 
 export interface TestResult {
@@ -161,6 +201,10 @@ export interface HandleResult {
   /** Errores de preparación del programa (parse/top-level); el status es 500. */
   errors: string[];
   audit: AuditEntry[];
+  /** v0.6.47 — con `labels`, si un corte de etiquetas paró la corrida: qué falló, dónde y cómo arreglarlo. Es
+   * 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;
 }
 
 export type ModuleSource = WebAssembly.Module | Uint8Array | ArrayBuffer | URL | string | Response;

package/index.mjs

@@ -14,6 +14,11 @@
 //    En el navegador requiere cross-origin isolation (COOP/COEP) para SharedArrayBuffer.
 //
 // No hay estado global: cada `load()` es una instancia (memoria lineal propia).
+//
+// v0.6.46 (E7): la conexión del `http` del host es del embebedor, y el motor no ve a qué IP va. En
+// nativo un `net` con comodín sólo llega a IPs públicas; acá eso lo tiene que hacer tu hook:
+// resolver el nombre, chequear la IP a la que conecta (los rangos están en `Host.http`, en
+// index.d.ts) y conectar a ésa. El hook no sabe si el programa nombró el host.
 
 const te = new TextEncoder();
 const td = new TextDecoder();
@@ -122,7 +127,7 @@ export function dispatchHostSync(host, kind, payload) {
         ? casReply(syncOnly("kv.cas", host.kv.cas(payload.ns, payload.key, payload.expected ?? null, payload.value)))
         : undefined;
     case "llm":
-      return typeof host.llm === "function" ? normalizeLlm(syncOnly("llm", host.llm(payload.op, payload.prompt))) : undefined;
+      return typeof host.llm === "function" ? normalizeLlm(syncOnly("llm", host.llm(payload.op, payload.prompt, { principals: payload.principals ?? [] }))) : undefined;
     case "log":
       if (typeof host.log !== "function") return undefined;
       syncOnly("log", host.log(payload.line));
@@ -165,7 +170,7 @@ export async function dispatchHostAsync(host, kind, payload) {
         ? casReply(await host.kv.cas(payload.ns, payload.key, payload.expected ?? null, payload.value))
         : undefined;
     case "llm":
-      return typeof host.llm === "function" ? normalizeLlm(await host.llm(payload.op, payload.prompt)) : undefined;
+      return typeof host.llm === "function" ? normalizeLlm(await host.llm(payload.op, payload.prompt, { principals: payload.principals ?? [] })) : undefined;
     case "log":
       if (typeof host.log !== "function") return undefined;
       await host.log(payload.line);
@@ -344,7 +349,15 @@ function limitResult(request) {
     };
   }
   if (request.op === "test") return { ok: false, passed: 0, failed: 0, lines: [MEMORY_LIMIT], audit: [] };
-  return { ok: false, output: [], errors: [MEMORY_LIMIT], audit: [], llm_tokens: 0, exit: 1 };
+  const r = { ok: false, output: [], errors: [MEMORY_LIMIT], audit: [], llm_tokens: 0, exit: 1 };
+  // v0.6.46 (E6): con etiquetas, que la corrida se haya cortado por memoria puede depender de un
+  // valor privado (un bit por corrida, como cualquier error suyo): el host lo trata como sensible,
+  // igual que una corrida que terminó con `private_seen`. Sin saber si tocó algo privado, sí.
+  if (request.labels) {
+    r.steps = null;
+    r.private_seen = true;
+  }
+  return r;
 }
 
 /**
@@ -370,6 +383,9 @@ function requestOf(op, source, opts = {}) {
   // se descartaba por falsy y la corrida quedaba sin límite.
   if (opts.maxSteps != null) r.max_steps = opts.maxSteps;
   if (opts.maxMemoryMb != null) r.max_memory_mb = opts.maxMemoryMb;
+  // v0.6.46 (E3b): módulos de confianza del embebedor y su techo.
+  if (opts.trusted) r.trusted = opts.trusted;
+  if (opts.trustedCeiling) r.trusted_ceiling = opts.trustedCeiling;
   return r;
 }
 

package/package.json

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