@dcasegr/skein 0.0.0-stage → 0.1.2

package/kernel-zig/web/client.js

@@ -0,0 +1,65 @@
+// The page's side of the kernel's Worker (issue #35, worker.js): method calls
+// as promises, the kernel's notifications as a callback, and its blocking
+// requests answered by an async handler — the answer written into the shared
+// buffer the worker waits on. The page must be cross-origin isolated
+// (COOP: same-origin, COEP: require-corp) for SharedArrayBuffer.
+
+const enc = new TextEncoder();
+
+export class KernelWorker {
+  /**
+   * `wasm`: the kernel's URL or bytes. `onRequest(op, bytes)` → Promise<Uint8Array>
+   * (throw for an error answer); `onNotify(op, v)`.
+   */
+  constructor({ wasm, workerUrl = new URL("./worker.js", import.meta.url), onRequest, onNotify } = {}) {
+    if (!globalThis.crossOriginIsolated && typeof window !== "undefined") throw new Error("the kernel's worker needs a cross-origin isolated page (COOP/COEP)");
+    this.worker = new Worker(workerUrl, { type: "module" });
+    this.control = new SharedArrayBuffer(12);
+    this.ctrl = new Int32Array(this.control);
+    this.answer = new SharedArrayBuffer(1 << 16, { maxByteLength: 1 << 30 });
+    this.next = 1;
+    this.waiting = new Map();
+    this.onRequest = onRequest;
+    this.onNotify = onNotify;
+    this.worker.onmessage = (e) => this.onMessage(e.data);
+    this.worker.onerror = (e) => { for (const w of this.waiting.values()) w.reject(new Error(`kernel worker: ${e.message}`)); this.waiting.clear(); };
+    this.ready = this.call("init", typeof wasm === "string" ? new URL(wasm, globalThis.location?.href).href : wasm, this.control, this.answer);
+  }
+
+  call(method, ...args) {
+    const id = this.next++;
+    return new Promise((resolve, reject) => {
+      this.waiting.set(id, { resolve, reject });
+      this.worker.postMessage({ id, method, args });
+    });
+  }
+
+  async onMessage(m) {
+    if (m.id !== undefined) {
+      const w = this.waiting.get(m.id);
+      if (!w) return;
+      this.waiting.delete(m.id);
+      if (m.error !== undefined) w.reject(new Error(m.error)); else w.resolve(m.result);
+      return;
+    }
+    if (m.notify !== undefined) { try { this.onNotify?.(m.notify, m.v); } catch (e) { console.error(e); } return; }
+    if (m.request !== undefined) {
+      let status = 0, bytes;
+      try {
+        if (!this.onRequest) throw new Error(`this host answers no ${m.request}`);
+        bytes = await this.onRequest(m.request, m.v);
+      } catch (e) {
+        status = 1;
+        bytes = enc.encode(e?.message ?? String(e));
+      }
+      if (bytes.length > this.answer.byteLength) this.answer.grow(bytes.length);
+      new Uint8Array(this.answer, 0, bytes.length).set(bytes);
+      this.ctrl[1] = status;
+      this.ctrl[2] = bytes.length;
+      Atomics.store(this.ctrl, 0, 1);
+      Atomics.notify(this.ctrl, 0);
+    }
+  }
+
+  terminate() { this.worker.terminate(); }
+}

package/kernel-zig/web/kernel.d.ts

@@ -0,0 +1,59 @@
+// Types for kernel.js (the wasm kernel's dependency-free shim), for the TypeScript host that loads it.
+
+/** A store the kernel's `skein_store` imports reach by id. */
+export interface ShimStore {
+  getBlock(cid: Uint8Array): Uint8Array | undefined;
+  hasBlock(cid: Uint8Array): boolean;
+  putBlock(cid: Uint8Array, bytes: Uint8Array): boolean;
+  getPointer(name: string): Uint8Array | undefined;
+  setPointer(name: string, cid: Uint8Array): boolean;
+  begin(): void;
+  commit(): boolean;
+  rollback(): void;
+  entries?(): Iterable<[Uint8Array, Uint8Array]>;
+}
+
+export interface Peers {
+  request?(op: string, v: Uint8Array): { ok: Uint8Array } | { error: string };
+  notify?(op: string, v: Uint8Array | string): void;
+}
+
+export declare class MemoryStore implements ShimStore {
+  constructor(o?: { readOnly?: boolean });
+  blocks: Map<string, Uint8Array>;
+  pointers: Map<string, Uint8Array>;
+  getBlock(cid: Uint8Array): Uint8Array | undefined;
+  hasBlock(cid: Uint8Array): boolean;
+  putBlock(cid: Uint8Array, bytes: Uint8Array): boolean;
+  getPointer(name: string): Uint8Array | undefined;
+  setPointer(name: string, cid: Uint8Array): boolean;
+  begin(): void;
+  commit(): boolean;
+  rollback(): void;
+  entries(): Iterable<[Uint8Array, Uint8Array]>;
+}
+
+export declare function codecOf(cid: Uint8Array): number;
+
+export declare class Kernel {
+  constructor(module: WebAssembly.Module, o?: { stores?: Record<number, ShimStore>; peers?: Peers });
+  stores: Record<number, ShimStore>;
+  stats: { compiled: number; instances: number; hostCalls: number };
+  x: Record<string, (...a: number[]) => number> & { memory: WebAssembly.Memory };
+  push(bytes: Uint8Array | string): [number, number];
+  release(p: [number, number]): void;
+  result(n: number): Uint8Array;
+  check(r: number): number;
+  open(id: number): void;
+  modulesList(): Uint8Array;
+  putBlock(cid: Uint8Array, bytes: Uint8Array): void;
+  getBlock(cid: Uint8Array): Uint8Array | undefined;
+  call(frame: Uint8Array): Uint8Array;
+  admit(frame: Uint8Array): Uint8Array;
+  start(): Uint8Array;
+  drain(): Uint8Array;
+  state(): Uint8Array;
+  replay(src: number, dst: number): string;
+}
+
+export declare function replayInto(kernel: Kernel, srcId: number, dstId: number): string;

package/kernel-zig/web/kernel.js

@@ -0,0 +1,329 @@
+// The browser build's shim (issue #35): the JS around zig-out/web/skein-kernel.wasm.
+// Dependency-free and synchronous, so it runs wherever V8 does (a Worker in the
+// browser, node for the tests). It gives the kernel what it imports:
+//
+//   skein_engine   V8 as the kernel's engine: compile the (fuel-instrumented)
+//                  program modules it hands over, instantiate them with an
+//                  import object whose every function calls back into the
+//                  kernel (skein_host_call), run them, trap → code, read and
+//                  write their memory and their fuel counter
+//   skein_store    stores by id: key→bytes + named pointers (MemoryStore here,
+//                  IdbStore in store.js), with begin/commit/rollback
+//   skein_peer     the host: request(op, v) answered synchronously (wallet:
+//                  the signer — a Worker blocks on a SharedArrayBuffer while
+//                  the page answers: worker.js), notify(op, v) (emit: a
+//                  message or an event to carry out; say, panic)
+//
+// and wraps the kernel's exports as methods (Kernel below). Values cross as
+// dag-cbor bytes; decoding them is the caller's (the page bundles
+// @ipld/dag-cbor; this file needs nothing).
+
+const enc = new TextEncoder();
+const dec = new TextDecoder();
+
+/** Thrown through a program's frames when the kernel aborts it (exit, a park, a fatal host error). */
+class Abort extends Error {}
+/** The kernel itself failed inside a host call: rethrown out of `run`, never reported as the program's trap. */
+class KernelFault extends Error {
+  constructor(cause) { super(`kernel fault: ${cause?.message ?? cause}`); this.cause = cause; }
+}
+
+const key = (b) => { let s = ""; for (let i = 0; i < b.length; i++) s += String.fromCharCode(b[i]); return s; };
+const unkey = (s) => { const b = new Uint8Array(s.length); for (let i = 0; i < s.length; i++) b[i] = s.charCodeAt(i); return b; };
+
+/**
+ * A store in memory: blocks by CID, named pointers, and a transaction buffer
+ * (reads see it; commit applies it, rollback drops it). `onCommit(batch)` is
+ * told every applied batch in order — IdbStore makes it durable there.
+ */
+export class MemoryStore {
+  constructor({ readOnly = false } = {}) {
+    this.blocks = new Map();
+    this.pointers = new Map();
+    this.readOnly = readOnly;
+    this.tx = null;
+  }
+  /** Every block (cid bytes, bytes) and pointer, e.g. to write the store out. */
+  *entries() { for (const [k, v] of this.blocks) yield [unkey(k), v]; }
+  pointer(name) { return this.pointers.get(name); }
+  getBlock(cid) {
+    const k = key(cid);
+    if (this.tx?.blocks.has(k)) return this.tx.blocks.get(k);
+    return this.blocks.get(k);
+  }
+  hasBlock(cid) { return this.getBlock(cid) !== undefined; }
+  putBlock(cid, bytes) {
+    if (this.readOnly) return false;
+    const k = key(cid);
+    if (this.hasBlock(cid)) return true;
+    if (this.tx) this.tx.blocks.set(k, bytes);
+    else this.apply({ blocks: new Map([[k, bytes]]), pointers: new Map() });
+    return true;
+  }
+  getPointer(name) { return this.tx?.pointers.has(name) ? this.tx.pointers.get(name) : this.pointers.get(name); }
+  setPointer(name, cid) {
+    if (this.readOnly) return false;
+    if (this.tx) this.tx.pointers.set(name, cid);
+    else this.apply({ blocks: new Map(), pointers: new Map([[name, cid]]) });
+    return true;
+  }
+  begin() { this.tx = { blocks: new Map(), pointers: new Map() }; }
+  commit() { const t = this.tx; this.tx = null; if (t) this.apply(t); return true; }
+  rollback() { this.tx = null; }
+  apply(batch) {
+    for (const [k, v] of batch.blocks) this.blocks.set(k, v);
+    for (const [k, v] of batch.pointers) this.pointers.set(k, v);
+    this.onCommit?.(batch);
+  }
+}
+
+/** A codec of a binary CID (v1: version varint, codec varint), e.g. 0x55 raw. */
+export function codecOf(cid) {
+  let i = 0;
+  const varint = () => { let x = 0, s = 0; for (;;) { const b = cid[i++]; x += (b & 0x7f) * 2 ** s; if (!(b & 0x80)) return x; s += 7; } };
+  varint();
+  return varint();
+}
+
+/**
+ * The kernel: one wasm instance of skein-kernel.wasm, with its stores (by id)
+ * and its host (`peers`: request(op, bytes) → {ok: bytes} | {error: string},
+ * notify(op, bytes)). One runtime per instance (skein_open); replay uses two stores.
+ */
+export class Kernel {
+  static async load(source, o) {
+    const bytes = source instanceof Uint8Array || source instanceof ArrayBuffer ? source : new Uint8Array(await (await fetch(source)).arrayBuffer());
+    const module = source instanceof WebAssembly.Module ? source : await WebAssembly.compile(bytes);
+    return new Kernel(module, o);
+  }
+
+  constructor(module, { stores = {}, peers = {} } = {}) {
+    this.stores = stores;
+    this.peers = peers;
+    this.modules = [];
+    this.instances = new Map();
+    this.nextInstance = 1;
+    this.engineError = "";
+    this.held = new Uint8Array();
+    this.stats = { compiled: 0, instances: 0, hostCalls: 0 };
+    this.instance = new WebAssembly.Instance(module, this.imports());
+    this.x = this.instance.exports;
+  }
+
+  // ---------------------------------------------------------------- kernel memory
+
+  get mem() { return new Uint8Array(this.x.memory.buffer); }
+  // A wasm32 address arrives in JS as a signed i32: above 2 GiB it is negative (#83: a store with the
+  // shell app's modules takes the kernel past it). `>>> 0` reads every address and length unsigned.
+  bytesAt(ptr, len) { return new Uint8Array(this.x.memory.buffer, ptr >>> 0, len >>> 0); }
+  str(ptr, len) { return dec.decode(this.bytesAt(ptr, len)); }
+  /** Copy bytes into a fresh kernel buffer: [ptr, len]; free with release. */
+  push(bytes) {
+    const b = typeof bytes === "string" ? enc.encode(bytes) : bytes;
+    const p = b.length ? this.x.skein_alloc(b.length) : 0;
+    if (b.length && !p) throw new Error("kernel: out of memory");
+    if (b.length) this.bytesAt(p, b.length).set(b);
+    return [p, b.length];
+  }
+  release([p, n]) { if (n) this.x.skein_free(p, n); }
+  /** The kernel's result buffer, copied out. */
+  result(n) { return n < 0 ? new Uint8Array() : this.bytesAt(this.x.skein_result(), n).slice(); }
+  hold(b) { this.held = b; return b.length; }
+
+  imports() {
+    const k = this;
+    const store = (id) => { const s = k.stores[id]; if (!s) throw new Error(`kernel: no store ${id}`); return s; };
+    const guest = (h) => { const g = k.instances.get(h); if (!g) throw new Error(`kernel: no instance ${h}`); return g; };
+    return {
+      skein_store: {
+        get(id, c, n) { const b = store(id).getBlock(k.bytesAt(c, n)); if (b === undefined) return -1; return k.hold(b); },
+        take(p) { k.bytesAt(p, k.held.length).set(k.held); },
+        has(id, c, n) { return store(id).hasBlock(k.bytesAt(c, n)) ? 1 : 0; },
+        put(id, c, cn, b, bn) { return store(id).putBlock(k.bytesAt(c, cn).slice(), k.bytesAt(b, bn).slice()) ? 0 : -1; },
+        begin(id) { store(id).begin(); },
+        commit(id) { return store(id).commit() ? 0 : -1; },
+        rollback(id) { store(id).rollback(); },
+        pointer_get(id, p, n) { const c = store(id).getPointer(k.str(p, n)); if (c === undefined) return -1; return k.hold(c); },
+        pointer_set(id, p, n, c, cn) { return store(id).setPointer(k.str(p, n), k.bytesAt(c, cn).slice()) ? 0 : -1; },
+      },
+      skein_engine: {
+        compile(p, n, d, dn) { return k.compile(k.bytesAt(p, n), k.bytesAt(d, dn).slice()); },
+        instantiate(h) { return k.instantiate(h); },
+        run(inst, hasStart, e, en) { return k.run(inst, hasStart !== 0, k.str(e, en)); },
+        release(inst) { k.instances.delete(inst); },
+        fuel_get(inst) { return guest(inst).exports.__skein_fuel.value; },
+        fuel_set(inst, v) { guest(inst).exports.__skein_fuel.value = v; },
+        mem_read(inst, at, len, p) { k.bytesAt(p, len).set(new Uint8Array(guest(inst).exports.memory.buffer, at >>> 0, len >>> 0)); },
+        mem_write(inst, at, len, p) { new Uint8Array(guest(inst).exports.memory.buffer, at >>> 0, len >>> 0).set(k.bytesAt(p, len)); },
+        error_len() { return enc.encode(k.engineError).length; },
+        error_take(p) { const b = enc.encode(k.engineError); k.bytesAt(p, b.length).set(b); },
+      },
+      skein_peer: {
+        request(o, on, v, vn) {
+          const op = k.str(o, on);
+          let r;
+          try { r = k.peers.request ? k.peers.request(op, k.bytesAt(v, vn).slice()) : { error: `this host answers no ${op}` }; } catch (e) { r = { error: e?.message ?? String(e) }; }
+          if (r.ok) return k.hold(r.ok);
+          return -k.hold(enc.encode(String(r.error ?? "no answer"))) - 1;
+        },
+        notify(o, on, v, vn) {
+          const op = k.str(o, on);
+          const b = k.bytesAt(v, vn).slice();
+          try { k.peers.notify?.(op, op === "say" || op === "panic" ? dec.decode(b) : b); } catch { /* the host's problem */ }
+        },
+        take(p) { k.bytesAt(p, k.held.length).set(k.held); },
+      },
+    };
+  }
+
+  // ---------------------------------------------------------------- the engine: programs on V8
+
+  compile(bytes, desc) {
+    try {
+      const module = new WebAssembly.Module(bytes);
+      const kinds = [];
+      for (let i = 0; i < desc.length; i += 5) kinds.push({ result: desc[i], first: desc[i + 1] | (desc[i + 2] << 8) | (desc[i + 3] << 16) | (desc[i + 4] << 24) });
+      this.modules.push({ module, kinds, names: WebAssembly.Module.imports(module).filter((x) => x.kind === "function") });
+      this.stats.compiled++;
+      return this.modules.length - 1;
+    } catch (e) {
+      this.engineError = e?.message ?? String(e);
+      return -1;
+    }
+  }
+
+  instantiate(h) {
+    const m = this.modules[h];
+    const id = this.nextInstance++;
+    const imports = {};
+    const fns = [];
+    const k = this;
+    m.names.forEach((imp, i) => {
+      const kind = m.kinds[i] ?? { result: 0, first: i };
+      if (kind.first !== i) { (imports[imp.module] ??= {})[imp.name] = fns[kind.first]; return; }
+      const index = i, result = kind.result;
+      const f = function (...args) {
+        const x = k.x;
+        const a = new BigInt64Array(x.memory.buffer, x.skein_args() >>> 0, 16);
+        const n = Math.min(args.length, 16);
+        for (let j = 0; j < n; j++) a[j] = typeof args[j] === "bigint" ? args[j] : BigInt(Math.trunc(args[j]));
+        const g = k.instances.get(id);
+        const memLen = g?.exports.memory ? g.exports.memory.buffer.byteLength : 0;
+        let r;
+        k.stats.hostCalls++;
+        try { r = x.skein_host_call(id, index, n, memLen); } catch (e) { throw new KernelFault(e); }
+        if (r !== 0) throw new Abort("skein: abort");
+        const v = new BigInt64Array(x.memory.buffer, x.skein_args() >>> 0, 1)[0];
+        return result === 2 ? v : result === 1 ? Number(BigInt.asIntN(32, v)) : undefined;
+      };
+      fns[i] = f;
+      (imports[imp.module] ??= {})[imp.name] = f;
+    });
+    try {
+      const inst = new WebAssembly.Instance(m.module, imports);
+      this.instances.set(id, inst);
+      this.stats.instances++;
+      return id;
+    } catch (e) {
+      this.engineError = e?.message ?? String(e);
+      return -1;
+    }
+  }
+
+  run(id, hasStart, entry) {
+    const inst = this.instances.get(id);
+    try {
+      if (hasStart) inst.exports.__skein_start();
+      const f = inst.exports[entry];
+      if (typeof f !== "function") { this.engineError = `no ${entry}`; return -2; }
+      f();
+      return 0;
+    } catch (e) {
+      if (e instanceof KernelFault) throw e;
+      if (e instanceof Abort) return 1;
+      if (inst.exports.__skein_oog?.value) return 3;
+      if (e instanceof WebAssembly.RuntimeError || e instanceof RangeError) { this.engineError = e.message; return 2; }
+      this.engineError = e?.message ?? String(e);
+      return -1;
+    }
+  }
+
+  // ---------------------------------------------------------------- the kernel's exports
+
+  /** Open store `id` and a runtime over it. */
+  open(id) { this.check(this.x.skein_open(id)); }
+  /** A call's return value: a failure (< 0) throws with the kernel's message. */
+  check(r) { if (r < 0) throw new Error(`kernel: ${dec.decode(this.result(-r - 1))}`); return r; }
+  /** The pinned modules and files: dag-cbor [{name, file, cid}]. */
+  modulesList() { return this.result(this.x.skein_modules()); }
+  putBlock(cid, bytes) {
+    const c = this.push(cid), b = this.push(bytes);
+    try { this.check(this.x.skein_put_block(c[0], c[1], b[0], b[1])); } finally { this.release(c); this.release(b); }
+  }
+  getBlock(cid) {
+    const c = this.push(cid);
+    try { const n = this.x.skein_get_block(c[0], c[1]); return n === -1 ? undefined : this.result(this.check(n)); } finally { this.release(c); }
+  }
+  /**
+   * A serve op as a frame {op, v} (dag-cbor) → the reply frame (dag-cbor {ok} | {error, rejected}).
+   * Among them the kernel's `call` (#40): {op: "call", v: {program, fn, arg, caller?, now?}} → ok {ok, result | error, fuel}.
+   */
+  call(frame) { const f = this.push(frame); try { return this.result(this.x.skein_call(f[0], f[1])); } finally { this.release(f); } }
+  /** serve's admit ({entry, envelope?, body?}, dag-cbor) → the reply frame; not processed until drain. */
+  admit(frame) { const f = this.push(frame); try { return this.result(this.x.skein_admit(f[0], f[1])); } finally { this.release(f); } }
+  start() { return this.result(this.x.skein_start()); }
+  drain() { return this.result(this.x.skein_drain()); }
+  state() { return this.result(this.x.skein_state()); }
+  /** `skein-kernel replay`: store `src`'s log into store `dst` (its raw blocks put there first: replayInto). The JSON report. */
+  replay(src, dst) {
+    return dec.decode(this.result(this.check(this.x.skein_replay(src, dst))));
+  }
+}
+
+/**
+ * replay.zig's order: the destination gets every raw block of the source
+ * (the modules it ran), then the kernel copies the log and runs it.
+ */
+export function replayInto(kernel, srcId, dstId) {
+  const src = kernel.stores[srcId], dst = kernel.stores[dstId];
+  for (const [cid, bytes] of src.entries()) if (codecOf(cid) === 0x55) dst.putBlock(cid, bytes);
+  return kernel.replay(srcId, dstId);
+}
+
+/** Blocks as one binary stream: [u32 cid length][cid][u32 length][bytes]…, then the pointers as [u32 name length][name][u32 cid length][cid]… after a zero u32. */
+export function readBundle(buf, store) {
+  const d = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+  let i = 0;
+  const u32 = () => { const v = d.getUint32(i, true); i += 4; return v; };
+  for (;;) {
+    const cn = u32();
+    if (cn === 0) break;
+    const cid = buf.subarray(i, i + cn); i += cn;
+    const bn = u32();
+    const bytes = buf.subarray(i, i + bn); i += bn;
+    store.blocks.set(key(cid), bytes.slice());
+  }
+  while (i < buf.length) {
+    const nn = u32();
+    const name = dec.decode(buf.subarray(i, i + nn)); i += nn;
+    const cn = u32();
+    store.pointers.set(name, buf.slice(i, i + cn)); i += cn;
+  }
+  return store;
+}
+
+export function writeBundle(store) {
+  const parts = [];
+  let size = 4;
+  for (const [cid, bytes] of store.entries()) { parts.push(cid, bytes); size += 8 + cid.length + bytes.length; }
+  const ptrs = [...store.pointers].map(([n, c]) => [enc.encode(n), c]);
+  for (const [n, c] of ptrs) size += 8 + n.length + c.length;
+  const out = new Uint8Array(size);
+  const d = new DataView(out.buffer);
+  let i = 0;
+  const put = (b) => { d.setUint32(i, b.length, true); i += 4; out.set(b, i); i += b.length; };
+  for (let j = 0; j < parts.length; j += 2) { put(parts[j]); put(parts[j + 1]); }
+  d.setUint32(i, 0, true); i += 4;
+  for (const [n, c] of ptrs) { put(n); put(c); }
+  return out;
+}

package/kernel-zig/web/store.js

@@ -0,0 +1,67 @@
+// The instance store over IndexedDB (issue #35): the kernel's key→bytes map
+// and its `state` pointer (issue #30), one database per instance with two
+// object stores, `blocks` (CID bytes → bytes) and `pointers` (name → CID
+// bytes). The kernel reads synchronously, so the whole store is loaded into
+// memory at open (a MemoryStore) and every committed batch is written behind,
+// one readwrite transaction per batch, created at the commit — IndexedDB runs
+// transactions over the same stores in creation order, so what is durable is
+// always a prefix of what was committed, and the pointer never names a state
+// whose blocks are not written. `flushed()` resolves once everything committed
+// so far is durable: the host acknowledges an admission (to the messagebox it
+// came from) only after that.
+
+import { MemoryStore } from "./kernel.js";
+
+const req = (r) => new Promise((resolve, reject) => { r.onsuccess = () => resolve(r.result); r.onerror = () => reject(r.error); });
+
+export class IdbStore extends MemoryStore {
+  /** Open (or create) the database `name` and load it. */
+  static async open(name, { idb = globalThis.indexedDB } = {}) {
+    const open = idb.open(name, 1);
+    open.onupgradeneeded = () => {
+      const db = open.result;
+      if (!db.objectStoreNames.contains("blocks")) db.createObjectStore("blocks");
+      if (!db.objectStoreNames.contains("pointers")) db.createObjectStore("pointers");
+    };
+    const db = await req(open);
+    const s = new IdbStore();
+    s.db = db;
+    s.name = name;
+    const t = db.transaction(["blocks", "pointers"], "readonly");
+    const [keys, values, pkeys, pvalues] = await Promise.all([
+      req(t.objectStore("blocks").getAllKeys()), req(t.objectStore("blocks").getAll()),
+      req(t.objectStore("pointers").getAllKeys()), req(t.objectStore("pointers").getAll()),
+    ]);
+    for (let i = 0; i < keys.length; i++) s.blocks.set(keyOf(new Uint8Array(keys[i])), new Uint8Array(values[i]));
+    for (let i = 0; i < pkeys.length; i++) s.pointers.set(pkeys[i], new Uint8Array(pvalues[i]));
+    s.last = Promise.resolve();
+    s.failed = null;
+    s.onCommit = (batch) => s.writeBehind(batch);
+    return s;
+  }
+
+  writeBehind(batch) {
+    const t = this.db.transaction(["blocks", "pointers"], "readwrite");
+    const blocks = t.objectStore("blocks"), pointers = t.objectStore("pointers");
+    for (const [k, v] of batch.blocks) blocks.put(v, unkeyOf(k));
+    for (const [k, v] of batch.pointers) pointers.put(v, k);
+    const done = new Promise((resolve, reject) => {
+      t.oncomplete = () => resolve();
+      t.onerror = t.onabort = () => { this.failed ??= t.error ?? new Error("IndexedDB write failed"); reject(this.failed); };
+    });
+    done.catch(() => {});
+    this.last = this.last.then(() => done);
+  }
+
+  /** Everything committed so far is durable (or the first write failure). */
+  async flushed() { await this.last; if (this.failed) throw this.failed; }
+
+  close() { this.db.close(); }
+
+  /** Delete the database `name`. */
+  static async remove(name, { idb = globalThis.indexedDB } = {}) { await req(idb.deleteDatabase(name)); }
+}
+
+// MemoryStore's map key: the CID's bytes as a latin1 string (kernel.js).
+function keyOf(b) { let s = ""; for (let i = 0; i < b.length; i++) s += String.fromCharCode(b[i]); return s; }
+function unkeyOf(s) { const b = new Uint8Array(s.length); for (let i = 0; i < s.length; i++) b[i] = s.charCodeAt(i); return b; }

package/kernel-zig/web/worker.js

@@ -0,0 +1,79 @@
+// The kernel's thread in the browser (issue #35): a module Worker holding the
+// wasm kernel (kernel.js) and its stores. A Worker, because the kernel runs
+// programs synchronously — `new WebAssembly.Module` of a program, and its
+// host calls — which a page's main thread may not do for large modules, and
+// because the kernel's requests to its host (wallet: the signer) must be
+// answered while it waits: it posts the request and blocks on a
+// SharedArrayBuffer (Atomics.wait) until the page has written the answer
+// (client.js). That needs a cross-origin isolated page (COOP/COEP headers).
+//
+// Messages in: {id, method, args} → {id, result} | {id, error}.
+// Messages out: {notify: op, v} (emit, say, panic) and
+// {request: op, v} (answered through the shared buffer).
+
+import { codecOf, Kernel, MemoryStore, readBundle, replayInto, writeBundle } from "./kernel.js";
+import { IdbStore } from "./store.js";
+
+const dec = new TextDecoder();
+let kernel = null;
+const stores = {};
+let ctrl = null; // Int32Array over the control buffer: [0] ready flag, [1] status (0 ok, 1 error), [2] length
+let data = null; // the answer's bytes (a growable SharedArrayBuffer)
+
+function request(op, v) {
+  Atomics.store(ctrl, 0, 0);
+  postMessage({ request: op, v });
+  Atomics.wait(ctrl, 0, 0);
+  const bytes = new Uint8Array(data, 0, ctrl[2]).slice();
+  return ctrl[1] === 0 ? { ok: bytes } : { error: dec.decode(bytes) };
+}
+
+const flushAll = async () => { for (const s of Object.values(stores)) await s.flushed?.(); };
+
+const methods = {
+  async init(wasm, control, answer) {
+    ctrl = new Int32Array(control);
+    data = answer;
+    const bytes = typeof wasm === "string" ? new Uint8Array(await (await fetch(wasm)).arrayBuffer()) : wasm;
+    kernel = new Kernel(await WebAssembly.compile(bytes), { stores, peers: { request, notify: (op, v) => postMessage({ notify: op, v }) } });
+    return true;
+  },
+  /** Store `id` over the IndexedDB database `name` (loaded). */
+  async openIdb(id, name) { stores[id] = await IdbStore.open(name); return stores[id].blocks.size; },
+  /** Store `id` in memory, from a bundle (kernel.js readBundle) or empty. */
+  openMemory(id, bundle, readOnly = false) { stores[id] = new MemoryStore({ readOnly }); if (bundle) readBundle(new Uint8Array(bundle), stores[id]); return stores[id].blocks.size; },
+  async removeIdb(name) { await IdbStore.remove(name); return true; },
+  closeStore(id) { stores[id]?.close?.(); delete stores[id]; return true; },
+  /** The store as a bundle (to write it out: equiv); `records` leaves out the raw blocks (the modules, which a replay installs). */
+  async bundle(id, records = false) {
+    await stores[id].flushed?.();
+    if (!records) return writeBundle(stores[id]);
+    const s = new MemoryStore();
+    for (const [cid, bytes] of stores[id].entries()) if (codecOf(cid) !== 0x55) s.blocks.set(String.fromCharCode(...cid), bytes);
+    for (const [n, c] of stores[id].pointers) s.pointers.set(n, c);
+    return writeBundle(s);
+  },
+  open(id) { kernel.open(id); return true; },
+  modules() { return kernel.modulesList(); },
+  hasBlock(id, cid) { return stores[id].hasBlock(cid); },
+  putBlock(cid, bytes) { kernel.putBlock(cid, bytes); return true; },
+  getBlock(cid) { return kernel.getBlock(cid); },
+  call(frame) { return kernel.call(frame); },
+  /** The one call in: admitted and durable before the answer (the host then acknowledges its source). */
+  async admit(frame) { const r = kernel.admit(frame); await flushAll(); return r; },
+  async start() { const r = kernel.start(); await flushAll(); return r; },
+  async drain() { const r = kernel.drain(); await flushAll(); return r; },
+  state() { return kernel.state(); },
+  async replay(src, dst) { const t = performance.now(); const out = replayInto(kernel, src, dst); await flushAll(); return { report: out, ms: performance.now() - t, stats: kernel.stats }; },
+};
+
+onmessage = async (e) => {
+  const { id, method, args } = e.data;
+  try {
+    const f = methods[method];
+    if (!f) throw new Error(`no method ${method}`);
+    postMessage({ id, result: await f(...(args ?? [])) });
+  } catch (err) {
+    postMessage({ id, error: err?.stack ?? String(err) });
+  }
+};