@githolon/client 0.1.0

package/LICENSE.md

@@ -0,0 +1,36 @@
+# Nomos Pre-Release License (v1)
+
+Copyright © 2026 Captain App Ltd. All rights reserved.
+
+This is a pre-release of Nomos. This license gives you what you need to BUILD
+with it; we keep the rest for now.
+
+## You may
+
+- install and use these packages to author Nomos domains, compile them, and
+  deploy them to Nomos Cloud or any Nomos instance Captain App operates or
+  authorizes;
+- build, run, and ship applications on top of them — including commercial ones;
+- keep everything that's yours: code you write, and everything these tools
+  generate FOR you (scaffolds from `create-holon` / `holon generate`, generated
+  clients, compiled domain packages) carries NO restriction from us — it is
+  yours outright.
+
+## You may not
+
+- redistribute these packages or their source, in whole or in part, outside
+  your team;
+- modify them or build derivative tools, SDKs, or runtimes from their source;
+- offer the Nomos runtime, or anything materially similar, as a hosted service;
+- reverse-engineer the holon wasm runtime.
+
+## The rest
+
+Provided **as is**, with no warranty of any kind; to the maximum extent
+permitted by law, Captain App Ltd accepts no liability arising from your use.
+This license terminates automatically if you breach it.
+
+Want the kernel source, broader rights, or to do something this doesn't cover?
+**Ask: jack@captainapp.co.uk.** The plan is to open Nomos up gradually, with
+the people actually using it — telling us what you're building is how that
+happens faster.

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@githolon/client",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Nomos Cloud web client — a LOCAL holon for offline-first apps: pulls the workspace ledger (git) from Nomos Cloud, replays it into the in-memory SQLite projection inside the wasm32-wasip1 GitHolon, and exposes dispatch / watch / sync. The browser runs the SAME byte-identical holon artifact the edge runs.",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Captain-App/nomos2.git",
+    "directory": "cloud/web-client"
+  },
+  "exports": { ".": "./src/index.mjs" },
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "e2e": "node test/e2e.mjs",
+    "e2e:convergence": "node test/convergence.e2e.mjs"
+  },
+  "dependencies": {
+    "@bjorn3/browser_wasi_shim": "0.4.2",
+    "isomorphic-git": "^1.38.4"
+  }
+}

package/src/git-fs.mjs

@@ -0,0 +1,92 @@
+// An isomorphic-git fs adapter over a @bjorn3/browser_wasi_shim PreopenDirectory tree.
+//
+// This is what lets the DO push/fetch the EXACT same in-memory git repo that the holon's gix
+// writes (loose objects under /work/workspaces/<ws>/nomos.git) — no copy, no second store. The
+// holon commits via gix; isomorphic-git reads those loose objects off this same tree and pushes
+// them to the Artifacts remote (and writes fetched objects back for the holon to read).
+//
+// isomorphic-git uses the Node-style fs.promises surface and is sensitive to error `.code`
+// (ENOENT/EEXIST/ENOTDIR/EISDIR), so we set those exactly.
+
+function fsErr(code, p) { const e = new Error(`${code}: ${p}`); e.code = code; return e; }
+
+// Build an fs ({promises:{...}}) rooted at `mount` (e.g. "/work") over `preopen.dir`.
+export function makeGitFs(preopen, mount, { File, Directory }) {
+  const root = preopen.dir; // Directory: { contents: Map }
+  const isDir = (n) => n && n.contents instanceof Map;
+
+  function parts(p) {
+    if (p === mount) return [];
+    if (!p.startsWith(mount + "/")) throw fsErr("ENOENT", p);
+    const rel = p.slice(mount.length + 1).replace(/\/+$/, "");
+    return rel === "" ? [] : rel.split("/");
+  }
+  function resolve(ps) {
+    let cur = root;
+    for (const part of ps) {
+      if (!isDir(cur)) return null;
+      const next = cur.contents.get(part);
+      if (next === undefined) return null;
+      cur = next;
+    }
+    return cur;
+  }
+  const parent = (ps) => resolve(ps.slice(0, -1));
+  const leaf = (ps) => ps[ps.length - 1];
+
+  const promises = {
+    async readFile(p, opts) {
+      const n = resolve(parts(p));
+      if (n === null) throw fsErr("ENOENT", p);
+      if (isDir(n)) throw fsErr("EISDIR", p);
+      const data = n.data ?? new Uint8Array(0);
+      const encoding = typeof opts === "string" ? opts : opts && opts.encoding;
+      return encoding ? new TextDecoder().decode(data) : new Uint8Array(data);
+    },
+    async writeFile(p, data) {
+      const ps = parts(p);
+      const par = parent(ps);
+      if (!isDir(par)) throw fsErr("ENOENT", p);
+      const bytes = typeof data === "string" ? new TextEncoder().encode(data) : new Uint8Array(data);
+      par.contents.set(leaf(ps), new File(bytes));
+    },
+    async unlink(p) {
+      const ps = parts(p), par = parent(ps);
+      if (!isDir(par) || !par.contents.delete(leaf(ps))) throw fsErr("ENOENT", p);
+    },
+    async readdir(p) {
+      const n = resolve(parts(p));
+      if (n === null) throw fsErr("ENOENT", p);
+      if (!isDir(n)) throw fsErr("ENOTDIR", p);
+      return [...n.contents.keys()];
+    },
+    async mkdir(p) {
+      const ps = parts(p), par = parent(ps);
+      if (!isDir(par)) throw fsErr("ENOENT", p);
+      if (par.contents.has(leaf(ps))) throw fsErr("EEXIST", p);
+      par.contents.set(leaf(ps), new Directory(new Map()));
+    },
+    async rmdir(p) {
+      const ps = parts(p), par = parent(ps);
+      if (!isDir(par)) throw fsErr("ENOENT", p);
+      par.contents.delete(leaf(ps));
+    },
+    async stat(p) { return promises.lstat(p); },
+    async lstat(p) {
+      const n = resolve(parts(p));
+      if (n === null) throw fsErr("ENOENT", p);
+      const dir = isDir(n);
+      return {
+        type: dir ? "dir" : "file",
+        mode: dir ? 0o040000 : 0o100644,
+        size: dir ? 0 : (n.data ? n.data.length : 0),
+        ino: 0, mtimeMs: 0, ctimeMs: 0, uid: 1, gid: 1, dev: 1,
+        isFile: () => !dir, isDirectory: () => dir, isSymbolicLink: () => false,
+      };
+    },
+    async readlink(p) { throw fsErr("EINVAL", p); },
+    async symlink() { throw fsErr("EPERM", "symlink unsupported"); },
+    async chmod() {},
+  };
+  return { promises };
+}

package/src/index.mjs

@@ -0,0 +1,464 @@
+// ─── @githolon/client — a LOCAL holon for offline-first apps ───────────────────────────────────
+//
+// Sovereignty in the browser: this client does NOT ask the cloud what the state is. It
+//   1. fetches the holon runtime from Nomos Cloud (`/v1/runtime/holon.wasm` — the byte-identical
+//      wasm32-wasip1 GitHolon the edge itself runs),
+//   2. git-PULLS the workspace ledger `main` from the branded remote (`/v1/workspaces/:ws/git`),
+//   3. REPLAYS it locally — the holon folds the commits into its in-memory SQLite projection,
+//      verifying as it goes (content-addressed law, signatures; custody is never trusted),
+//   4. exposes `dispatch` / `watch` / `query` / `sync` for the app.
+//
+// Writes are LOCAL-FIRST: `dispatch` commits to the local ledger under the workspace's installed
+// law (resolved from the pulled history, offline). `sync()` pushes the local commits to an
+// UNTRUSTED SESSION BRANCH (`session/<clientId>`) on the cloud — the edge holon validates and
+// merges to `main` (the admission gate), and `sync()` pulls an advanced `main` back down, folding
+// only the delta (the projection cursor).
+import { WASI, File, Directory, OpenFile, ConsoleStdout, PreopenDirectory } from "@bjorn3/browser_wasi_shim";
+import git from "isomorphic-git";
+import http from "isomorphic-git/http/web";
+import { makeGitFs } from "./git-fs.mjs";
+import { serializeTree, deserializeTree } from "./tree.mjs";
+
+const enc = new TextEncoder(), dec = new TextDecoder();
+const BRANCH = "main";
+
+const unpack = (p) => { const v = typeof p === "bigint" ? p : BigInt(p); return { ptr: Number(v >> 32n), len: Number(v & 0xffffffffn) }; };
+async function sha256hex(t) { const b = await crypto.subtle.digest("SHA-256", enc.encode(t)); return [...new Uint8Array(b)].map((x) => x.toString(16).padStart(2, "0")).join(""); }
+function osEntropyBuffer(n) { const bytes = new Uint8Array(n * 8); crypto.getRandomValues(bytes); const out = new Array(n), T = 2 ** 53; for (let i = 0; i < n; i++) { let z = 0n; for (let b = 7; b >= 0; b--) z = (z << 8n) | BigInt(bytes[i * 8 + b]); out[i] = Number(z >> 11n) / T; } return out; }
+function stringifyBig(o) { return JSON.stringify(o, (_k, v) => (typeof v === "bigint" ? `@@B:${v}@@` : v)).replace(/"@@B:(\d+)@@"/g, "$1"); }
+async function replicaIdFromValue(str) {
+  const b = new Uint8Array(await crypto.subtle.digest("SHA-256", enc.encode(str)));
+  let v = 0n; for (let i = 0; i < 8; i++) v = (v << 8n) | BigInt(b[i]);
+  return v & ((1n << 63n) - 1n);
+}
+function holonCall(ex, mode, fields, STDERR) {
+  const req = enc.encode(JSON.stringify({ mode, ...fields }));
+  const reqPtr = ex.git_holon_alloc(req.length);
+  try {
+    new Uint8Array(ex.memory.buffer, reqPtr, req.length).set(req);
+    const { ptr, len } = unpack(ex.git_holon_call(reqPtr, req.length));
+    try {
+      const e = JSON.parse(dec.decode(new Uint8Array(ex.memory.buffer, ptr, len).slice()));
+      if (!e.ok) throw new Error((e.error || "holon error") + (STDERR.length ? ` | ${STDERR.slice(-4).join(" / ")}` : ""));
+      return e.result;
+    } finally { ex.git_holon_dealloc(ptr, len); }
+  } finally { ex.git_holon_dealloc(reqPtr, req.length); }
+}
+
+/**
+ * Open a LOCAL holon for `workspace`, hydrated from Nomos Cloud.
+ *
+ * @param {object} opts
+ * @param {string} opts.cloud      Nomos Cloud base URL (e.g. https://nomos.captainapp.co.uk)
+ * @param {string} opts.workspace  workspace name (must already exist — POST /v1/workspaces/:ws)
+ * @param {string} [opts.clientId] stable client identity (drives the session branch + HLC replica);
+ *                                 defaults to a random id per connect
+ * @param {string} [opts.authToken] bearer for keyed clouds (needed for sync() push when the cloud
+ *                                 sets NOMOS_CLOUD_KEY)
+ * @param {Uint8Array} [opts.restoreFrom] a holon.export() snapshot — hydrate the workspace
+ *                                 directory from these bytes INSTEAD of cloning, then pull()
+ *                                 to catch up; pending un-synced local commits survive and
+ *                                 remain syncable
+ */
+export async function connect({ cloud, workspace, clientId, authToken, restoreFrom }) {
+  if (!cloud || !workspace) throw new Error("connect({ cloud, workspace }) required");
+  const base = cloud.replace(/\/+$/, "");
+  const remote = `${base}/v1/workspaces/${workspace}/git`;
+  const cid = clientId || [...crypto.getRandomValues(new Uint8Array(8))].map((b) => b.toString(16).padStart(2, "0")).join("");
+  const replica = await replicaIdFromValue(`client:${cid}`);
+  const authHeaders = authToken ? { Authorization: `Bearer ${authToken}` } : {};
+
+  // ── 1. the runtime: the SAME holon artifact the edge runs, plus the read-routing manifests.
+  // Manifests are WORKSPACE-SCOPED (baked ∪ the workspace's deploy overlays) so a domain
+  // deployed with nomos-compile routes its queries + gates its admission locally too;
+  // older clouds without /manifests fall back to the baked /v1/runtime/manifests. ──
+  const [wasmBytes, manifests] = await Promise.all([
+    fetch(`${base}/v1/runtime/holon.wasm`).then((r) => { if (!r.ok) throw new Error(`runtime fetch ${r.status}`); return r.arrayBuffer(); }),
+    fetch(`${base}/v1/workspaces/${workspace}/manifests`)
+      .then((r) => { if (!r.ok) throw new Error(`ws manifests ${r.status}`); return r.json(); })
+      .catch(() => fetch(`${base}/v1/runtime/manifests`).then((r) => { if (!r.ok) throw new Error(`manifests fetch ${r.status}`); return r.json(); })),
+  ]);
+  const module = await WebAssembly.compile(wasmBytes);
+
+  // ── 2. the /work tree + the ledger PULL (custody → local; verified on replay, never trusted) ──
+  const seed = (m) => {
+    m.set("domain_manifests.json", new File(enc.encode(manifests.domainManifests)));
+    m.set("identity-manifests.json", new File(enc.encode(manifests.identityManifests)));
+  };
+  const root = new Map(); seed(root);
+  // restoreFrom: hydrate the workspace directory from an export() snapshot instead of cloning
+  // (the bare nomos.git — including any pending un-synced local commits — rides the bytes);
+  // re-seed afterwards so the workspace-scoped manifests are the FRESH ones from the cloud.
+  const wsContents = restoreFrom ? deserializeTree(restoreFrom, { File, Directory }) : new Map();
+  seed(wsContents);
+  const wsDirNode = new Directory(wsContents);
+  root.set("ws", new Directory(new Map([[workspace, wsDirNode]])));
+  const preopen = new PreopenDirectory("/work", root);
+  const fs = makeGitFs(preopen, "/work", { File, Directory });
+  const repoArg = `/work/ws/${workspace}`;
+  const gitdir = `${repoArg}/nomos.git`;
+
+  const info = await git.getRemoteInfo({ http, url: remote });
+  const remoteMain = info.refs && info.refs.heads && info.refs.heads.main;
+  if (!remoteMain) throw new Error(`workspace '${workspace}' has no ledger main — create it first (POST /v1/workspaces/${workspace})`);
+  if (restoreFrom) {
+    // restored gitdir already carries the ledger — just (re)point origin at THIS cloud;
+    // the catch-up happens via pull() right after the holon boots (it needs apply_intent).
+    await git.addRemote({ fs, gitdir, remote: "origin", url: remote, force: true });
+  } else {
+    await git.init({ fs, gitdir, bare: true, defaultBranch: BRANCH });
+    await git.addRemote({ fs, gitdir, remote: "origin", url: remote, force: true });
+    await git.fetch({ fs, http, gitdir, remote: "origin", ref: BRANCH, singleBranch: true });
+    await git.writeRef({ fs, gitdir, ref: `refs/heads/${BRANCH}`, value: remoteMain, force: true });
+    await git.writeRef({ fs, gitdir, ref: "HEAD", value: `ref: refs/heads/${BRANCH}`, force: true, symbolic: true });
+  }
+
+  // ── 3. the resident holon (entropy gate runs at boot — refuses a degenerate battery) ──
+  const STDERR = [];
+  const fds = [new OpenFile(new File([])), ConsoleStdout.lineBuffered(() => {}), ConsoleStdout.lineBuffered((l) => STDERR.push(l)), preopen];
+  const wasi = new WASI(["wasm_git_holon", "reactor"], [], fds, { debug: false });
+  const inst = await WebAssembly.instantiate(module, { wasi_snapshot_preview1: wasi.wasiImport });
+  const code = wasi.start(inst);
+  if (code !== 0) throw new Error(`holon refused to start (exit ${code}): ${STDERR.join("\n")}`);
+  const ex = inst.exports;
+
+  // serialize all holon ops (one wasm instance + one /work tree; never re-enter concurrently)
+  let chain = Promise.resolve();
+  const serialize = (fn) => { const r = chain.then(fn, fn); chain = r.then(() => {}, () => {}); return r; };
+  let seq = 0;
+  let syncedBase = remoteMain; // the last remote main we replayed (the fork point of local work)
+
+  const writeWork = (name, bytes) => preopen.dir.contents.set(name, new File(bytes));
+  // ERROR CLARITY: a wasm TRAP ("RuntimeError: unreachable") is a Rust panic — the
+  // panic MESSAGE is sitting in the holon's stderr buffer. Surface it; a bare
+  // "unreachable" tells an app developer nothing.
+  const call = (mode, fields) => {
+    try {
+      return holonCall(ex, mode, { repoArg, workspace, branch: BRANCH, ...fields }, STDERR);
+    } catch (e) {
+      if (e instanceof WebAssembly.RuntimeError && STDERR.length) {
+        throw new Error(`the holon panicked during '${mode}': ${STDERR.slice(-6).join(" | ")}`);
+      }
+      throw e;
+    }
+  };
+
+  // ── INCREMENTAL-PULL CONVERGENCE (the client leg of edge admission) ──
+  // After admission, remote main carries EDGE-sealed copies of our intents (same intent.json
+  // bytes — same content-derived intent.id — different commit shas). Convergence is therefore
+  // id-based: adopt canonical main, then REBASE-REPLAY only the local intents whose ids the
+  // canon does not already carry (apply_intent — the same primitive the edge /admit runs).
+  let replaySeq = 0;
+  let remoteScan = { head: null, ids: null, oids: null }; // cached per remote head sha
+  async function scanRemote(remoteHead) {
+    if (remoteScan.head === remoteHead) return remoteScan;
+    const ids = new Set(), oids = new Set();
+    for (const c of await git.log({ fs, gitdir, ref: remoteHead, depth: 500 })) {
+      oids.add(c.oid);
+      try {
+        const { blob } = await git.readBlob({ fs, gitdir, oid: c.oid, filepath: "intent.json" });
+        const id = JSON.parse(dec.decode(blob)).id;
+        if (id) ids.add(id);
+      } catch { /* genesis/no-intent commits — custody only */ }
+    }
+    remoteScan = { head: remoteHead, ids, oids };
+    return remoteScan;
+  }
+  // ── DEAD-LETTER QUEUE — refused-but-LEGITIMATE work is never lost (Jack's law) ──
+  // A DOMAIN rejection (the law couldn't merge it: uncertified domain, referential
+  // violation, invariant) parks the FULL intent here, durably (the DLQ file lives in
+  // the workspace tree, so export()/restore carry it). The app/domain dev explicitly
+  // handles it: inspect via deadLetters(), push a law fix, retryDeadLetter() — the
+  // system unjams and the user's work lands. Obvious ATTACKS (session-lane law
+  // intents the edge structurally refuses) are DROPPED, not dead-lettered.
+  const DLQ_FILE = "dead-letters.json";
+  const b64 = (bytes) => { let s = ""; for (let i = 0; i < bytes.length; i += 0x8000) s += String.fromCharCode.apply(null, bytes.subarray(i, i + 0x8000)); return btoa(s); };
+  const unb64 = (s) => Uint8Array.from(atob(s), (c) => c.charCodeAt(0));
+  const readDlq = () => { const f = wsContents.get(DLQ_FILE); if (!f) return []; try { return JSON.parse(dec.decode(f.data)); } catch { return []; } };
+  const writeDlq = (list) => wsContents.set(DLQ_FILE, new File(enc.encode(JSON.stringify(list))));
+  function deadLetter(e, source, error) {
+    const list = readDlq();
+    if (e.id && list.some((x) => x.id === e.id)) return;
+    let domain = null, directiveId = null;
+    try { const doc = JSON.parse(dec.decode(e.blob)); domain = (doc.payload && doc.payload.domain) || null; directiveId = (doc.payload && doc.payload.directiveId) || null; } catch {}
+    list.push({ id: e.id, oid: e.oid.slice(0, 10), source, error: String(error || "").slice(0, 300), domain, directiveId, at: new Date().toISOString(), intentB64: b64(e.blob) });
+    writeDlq(list);
+  }
+
+  // Intent ids the EDGE has judged and REFUSED — never re-replayed (dead-lettered or
+  // dropped per the routing above; re-replaying would resurrect them every sync).
+  const edgeRefused = new Set();
+  // NOT serialized — sync() calls this from inside its own serialized turn; api.pull wraps it.
+  async function pullInner(edgeRejections = null) {
+    await git.addRemote({ fs, gitdir, remote: "origin", url: remote, force: true });
+    const inf = await git.getRemoteInfo({ http, url: remote });
+    const remoteHead = inf.refs && inf.refs.heads && inf.refs.heads.main;
+    if (!remoteHead) throw new Error(`pull: workspace '${workspace}' has no remote main`);
+    const localHead = await git.resolveRef({ fs, gitdir, ref: BRANCH });
+    if (remoteHead === localHead) { syncedBase = remoteHead; return { upToDate: true, remoteHead }; }
+    // fetch only if the remote head's objects aren't already in custody (e.g. local-ahead-only)
+    const have = await git.readCommit({ fs, gitdir, oid: remoteHead }).then(() => true, () => false);
+    if (!have) await git.fetch({ fs, http, gitdir, remote: "origin", ref: BRANCH, singleBranch: true });
+    const { ids: remoteIds, oids: remoteOids } = await scanRemote(remoteHead);
+    // local-only commits = local main lineage not in remote history; oldest → newest
+    const localOnly = [];
+    for (const c of await git.log({ fs, gitdir, ref: localHead, depth: 500 })) {
+      if (remoteOids.has(c.oid)) break;
+      let blob = null, id = null;
+      try {
+        blob = (await git.readBlob({ fs, gitdir, oid: c.oid, filepath: "intent.json" })).blob;
+        try { id = JSON.parse(dec.decode(blob)).id ?? null; } catch {}
+      } catch {}
+      localOnly.push({ oid: c.oid, blob, id });
+    }
+    localOnly.reverse();
+    // RESET onto the canonical remote main (the projection re-folds from it at next query)
+    await git.writeRef({ fs, gitdir, ref: `refs/heads/${BRANCH}`, value: remoteHead, force: true });
+    syncedBase = remoteHead;
+    // REBASE-REPLAY: re-admit (locally) every carried intent the canon doesn't already hold
+    const replayed = [], skipped = [], rejected = [], dropped = [], deadLettered = [];
+    for (const e of localOnly) {
+      if (e.id && remoteIds.has(e.id)) { skipped.push({ oid: e.oid.slice(0, 10), id: e.id }); continue; }
+      // EDGE-REFUSED: the admitting peer judged this intent and said no. Routing:
+      // a DOMAIN rejection (deadLettered flag from the admission report) parks the
+      // work in the DLQ — never lost, app-visible, retryable after a law fix; a
+      // structural ATTACK-LANE refusal is dropped. Either way it leaves the lineage.
+      const edgeRej = edgeRejections && edgeRejections.get(e.oid.slice(0, 10));
+      if ((e.id && edgeRefused.has(e.id)) || edgeRej) {
+        if (e.id) edgeRefused.add(e.id);
+        if (edgeRej && edgeRej.deadLettered && e.blob) {
+          deadLetter(e, "edge", edgeRej.error);
+          deadLettered.push({ oid: e.oid.slice(0, 10), id: e.id, error: edgeRej.error });
+        } else {
+          dropped.push({ oid: e.oid.slice(0, 10), id: e.id, edgeRejected: true });
+        }
+        continue;
+      }
+      if (!e.blob) { rejected.push({ oid: e.oid.slice(0, 10), error: "commit carries no intent.json" }); continue; }
+      const name = `replay-${replaySeq++}.json`;
+      writeWork(name, e.blob);
+      try {
+        const res = JSON.parse(call("apply_intent", { intentFile: `/work/${name}` }));
+        if (res.ok) replayed.push({ oid: e.oid.slice(0, 10), id: e.id, head: res.head });
+        else {
+          // The LOCAL law refused the replay (e.g. it changed underneath) — the work
+          // is still the user's: dead-letter it, never silently lose it.
+          deadLetter(e, "local", res.error);
+          deadLettered.push({ oid: e.oid.slice(0, 10), id: e.id, error: res.error });
+          rejected.push({ oid: e.oid.slice(0, 10), id: e.id, error: res.error });
+        }
+      } catch (err) {
+        rejected.push({ oid: e.oid.slice(0, 10), id: e.id, error: String(err && err.message || err).slice(0, 200) });
+      }
+    }
+    return { upToDate: false, remoteHead, replayed, skipped, rejected, ...(dropped.length ? { dropped } : {}), ...(deadLettered.length ? { deadLettered } : {}) };
+  }
+
+  // restore catch-up: adopt whatever canonical main became while we were away; pending
+  // un-synced local commits are rebase-replayed on top and stay syncable.
+  if (restoreFrom) await pullInner();
+
+  const api = {
+    clientId: cid,
+    replica: replica.toString(),
+
+    /** Local head (the client's own ledger tip). */
+    head: () => serialize(async () => git.resolveRef({ fs, gitdir, ref: BRANCH })),
+
+    /** Read an aggregate row from the LOCAL projection (folds any un-folded delta first). */
+    queryById: (aggregateId) => serialize(async () => JSON.parse(call("query_by_id", { aggregateId }))),
+
+    /** Run a domain query against the LOCAL projection. */
+    query: (queryId, params = {}) => serialize(async () => JSON.parse(call("query", { queryId, paramsJson: JSON.stringify(params) }))),
+
+    /**
+     * The DEAD-LETTER QUEUE: refused-but-legitimate intents, with full provenance
+     * (id, source edge|local, error, domain/directiveId, when). The intent BYTES stay
+     * in the queue (and ride export()/restore) — work is never lost; the app decides.
+     */
+    deadLetters: () => serialize(async () => readDlq().map(({ intentB64, ...meta }) => meta)),
+
+    /**
+     * Retry one dead-lettered intent — after the domain dev shipped a law fix, this is
+     * the UNJAM: pull canon first (it may already be admitted), else re-apply locally
+     * (it rides the next sync). Resolves the entry on success.
+     */
+    retryDeadLetter: (id) => serialize(async () => {
+      const list = readDlq();
+      const entry = list.find((x) => x.id === id || x.oid === id);
+      if (!entry) return { ok: false, error: `no dead letter '${id}'` };
+      await pullInner();
+      if (entry.id && remoteScan && remoteScan.ids.has(entry.id)) {
+        writeDlq(list.filter((x) => x !== entry));
+        return { ok: true, alreadyOnMain: true };
+      }
+      const name = `retry-${replaySeq++}.json`;
+      writeWork(name, unb64(entry.intentB64));
+      const res = JSON.parse(call("apply_intent", { intentFile: `/work/${name}` }));
+      if (res.ok) { writeDlq(list.filter((x) => x !== entry)); return { ok: true, head: res.head }; }
+      entry.error = String(res.error || "").slice(0, 300); entry.at = new Date().toISOString();
+      writeDlq(list);
+      return { ok: false, error: res.error };
+    }),
+
+    /** Discard one dead letter — the APP's explicit choice, never the runtime's. */
+    discardDeadLetter: (id) => serialize(async () => {
+      const list = readDlq();
+      const next = list.filter((x) => x.id !== id && x.oid !== id);
+      writeDlq(next);
+      return { ok: true, removed: list.length - next.length };
+    }),
+
+    /** A declared count's maintained O(1) value from the LOCAL projection. */
+    count: (countId, groupKey = "") => serialize(async () => JSON.parse(call("count", { countId, groupKey })).count),
+
+    /** A declared sum's maintained O(1) total from the LOCAL projection. */
+    sum: (sumId, groupKey = "") => serialize(async () => JSON.parse(call("sum", { sumId, groupKey })).sum),
+
+    /**
+     * LOCAL-FIRST dispatch: author an intent under the workspace's INSTALLED law (resolved from
+     * the pulled ledger — works fully offline). Returns the new local head. Durable on sync().
+     */
+    dispatch: (domain, directiveId, payload, { domainHash }) => serialize(async () => {
+      if (!domainHash) throw new Error("dispatch requires { domainHash } — the installed law to author under");
+      const s = seq++;
+      const envelope = {
+        payload: { domain, directiveId, payload },
+        captured_ports: { clock: { physical: Date.now(), logical: 0, replica }, rng: osEntropyBuffer(64) },
+        policy_version: 1, policy_domain: "Nomos", policy_gas: 0, policy_memory: 0,
+      };
+      writeWork(`payload-${s}.json`, enc.encode(JSON.stringify(payload)));
+      writeWork(`envelope-${s}.json`, enc.encode(stringifyBig(envelope)));
+      const raw = call("author", {
+        domain, directiveId, payloadFile: `/work/payload-${s}.json`, envelopeFile: `/work/envelope-${s}.json`,
+        seq: s, actor: "", domainFile: "", domainHash,
+      });
+      if (process.env.NOMOS_DEBUG_RAW) console.error("RAW AUTHOR:", String(raw).slice(0, 300));
+      const res = JSON.parse(raw);
+      // The author RPC is two-layered: the transport envelope (holonCall checks it) and
+      // THIS result. A law refusal arrives here as ok:false — it MUST throw, loudly and
+      // verbatim (it carries the human-first message). Swallowing it resolves undefined
+      // and the user's write silently never happens — the worst possible failure mode.
+      if (!res.ok) throw new Error(res.error || "the law refused this intent");
+      return res.head;
+    }),
+
+    /**
+     * Watch a query: polls the local projection and fires `cb(rows)` whenever the result changes.
+     * Returns a stop() function. (Sync separately — watch is purely local.)
+     */
+    watch(queryId, params, cb, { intervalMs = 1000 } = {}) {
+      let last, stopped = false;
+      const tick = async () => {
+        if (stopped) return;
+        try {
+          const rows = await api.query(queryId, params);
+          const key = JSON.stringify(rows);
+          if (key !== last) { last = key; cb(rows); }
+        } catch (e) { /* surface via onError later; keep polling */ }
+        if (!stopped) setTimeout(tick, intervalMs);
+      };
+      tick();
+      return () => { stopped = true; };
+    },
+
+    /** Watch a single aggregate id. */
+    watchById(aggregateId, cb, opts) {
+      let last, stopped = false;
+      const intervalMs = (opts && opts.intervalMs) || 1000;
+      const tick = async () => {
+        if (stopped) return;
+        try {
+          const rows = await api.queryById(aggregateId);
+          const key = JSON.stringify(rows);
+          if (key !== last) { last = key; cb(rows); }
+        } catch (e) { /* keep polling */ }
+        if (!stopped) setTimeout(tick, intervalMs);
+      };
+      tick();
+      return () => { stopped = true; };
+    },
+
+    /**
+     * PULL — incremental convergence onto canonical main:
+     *   fetch origin main; if unchanged → { upToDate: true }. Otherwise adopt the remote head
+     *   (reset local main — the projection re-folds from it at next query) and REBASE-REPLAY
+     *   the local-only intents whose content-derived ids the canon doesn't already carry
+     *   (apply_intent — the same re-admission primitive the edge runs). Returns
+     *   { upToDate, remoteHead, replayed, skipped, rejected }.
+     */
+    pull: () => serialize(pullInner),
+
+    /**
+     * EXPORT — serialize the workspace directory (/work/ws/<ws>: the bare nomos.git ledger
+     * + manifests) to bytes. Persist them anywhere (IndexedDB, a file); hand them back via
+     * connect({ restoreFrom }) to resume WITHOUT a clone — pending un-synced commits included.
+     */
+    export: () => serialize(async () => serializeTree(wsDirNode)),
+
+    /**
+     * SYNC — the offline-first exchange:
+     *   up:   push local commits to the untrusted session branch `session/<clientId>` (the edge
+     *         holon validates + merges to main — admission, not trust),
+     *   down: after an admission round, CONVERGE in the same call (pull(): adopt canonical main
+     *         + rebase-replay — result in `.converged`); otherwise fetch remote main and
+     *         fast-forward if we hold no un-merged local work.
+     */
+    sync: ({ admit = true } = {}) => serialize(async () => {
+      const localHead = await git.resolveRef({ fs, gitdir, ref: BRANCH });
+      const localAhead = localHead !== syncedBase;
+      let pushed = null, admission = null, converged = null;
+      if (localAhead) {
+        // The session branch is THIS client's own offer lane. After a converge (pull
+        // resets local main onto canon) the new lineage legitimately diverges from a
+        // not-yet-consumed previous offer — REPLACING it is the correct semantics
+        // (server-side idempotence skips anything already sealed), so retry with force.
+        try {
+          await git.push({ fs, http, gitdir, url: remote, ref: BRANCH, remoteRef: `refs/heads/session/${cid}`, force: false, headers: authHeaders });
+        } catch (e) {
+          if (!/fast-forward/i.test(String(e))) throw e;
+          await git.push({ fs, http, gitdir, url: remote, ref: BRANCH, remoteRef: `refs/heads/session/${cid}`, force: true, headers: authHeaders });
+        }
+        pushed = `session/${cid}`;
+        if (admit) {
+          // Ask the edge holon to JUDGE the session branch now (re-admit each carried intent under
+          // its own law and merge to main). Event/queue-driven admission can replace this trigger.
+          const r = await fetch(`${base}/v1/workspaces/${workspace}/admit`, { method: "POST", headers: authHeaders });
+          admission = await r.json();
+        }
+      }
+      if (admission && admission.ok) {
+        // Our work was judged: remote main now carries the EDGE-sealed versions of the admitted
+        // intents (same intent bytes, different shas). Converge NOW — no reconnect: adopt
+        // canonical main and rebase-replay whatever the canon didn't take. Refused commits
+        // route by kind (the admission report carries `deadLettered` on domain rejections):
+        // DLQ the legitimate work, drop the attack-lane refusals.
+        const refusals = new Map();
+        for (const s of admission.sessions || []) for (const r of s.rejected || []) if (r.oid) refusals.set(r.oid, { error: r.error, deadLettered: !!r.deadLettered });
+        converged = await pullInner(refusals.size ? refusals : null);
+        return {
+          pushed, admission, converged,
+          pulled: !converged.upToDate, diverged: false, reconnectRequired: false,
+          localHead, remoteMain: converged.remoteHead,
+        };
+      }
+      const inf = await git.getRemoteInfo({ http, url: remote });
+      const newMain = inf.refs && inf.refs.heads && inf.refs.heads.main;
+      let pulled = false, diverged = false, reconnectRequired = false;
+      if (newMain && newMain !== syncedBase) {
+        if (!localAhead) {
+          await git.fetch({ fs, http, gitdir, remote: "origin", ref: BRANCH, singleBranch: true });
+          await git.writeRef({ fs, gitdir, ref: `refs/heads/${BRANCH}`, value: newMain, force: true });
+          syncedBase = newMain;
+          pulled = true; // next query folds the delta from the projection cursor
+        } else {
+          diverged = true; // local work + remote advance: wait for edge admission
+        }
+      }
+      return { pushed, admission, converged, pulled, diverged, reconnectRequired, localHead, remoteMain: newMain };
+    }),
+
+    stats: () => ({ wasmLinearMemMB: +(ex.memory.buffer.byteLength / 1048576).toFixed(1) }),
+  };
+  return api;
+}

package/src/tree.mjs

@@ -0,0 +1,75 @@
+// /work tree ⇄ flat manifest bytes — the client twin of cloud/holon-host/src/tree.mjs.
+// Used by holon.export() / connect({ restoreFrom }) to persist the workspace directory
+// (the bare nomos.git + manifests) across page loads / devices. Byte format is IDENTICAL
+// to the edge serializer, so a snapshot is portable between the browser holon and the
+// edge holon:
+//   [u32 count] then per entry: [u8 isDir][u32 pathLen][path][u32 byteLen][bytes]
+const enc = new TextEncoder();
+const dec = new TextDecoder();
+
+function flatten(dir, prefix, out) {
+  for (const [name, inode] of dir.contents) {
+    const path = prefix ? prefix + "/" + name : name;
+    if (inode.contents instanceof Map) {
+      out.push({ path, dir: true });
+      flatten(inode, path, out);
+    } else {
+      out.push({ path, dir: false, bytes: inode.data ?? new Uint8Array(0) });
+    }
+  }
+}
+
+export function serializeTree(workTree) {
+  const entries = [];
+  flatten(workTree, "", entries);
+  const chunks = [];
+  const header = new Uint8Array(4);
+  new DataView(header.buffer).setUint32(0, entries.length, true);
+  chunks.push(header);
+  for (const e of entries) {
+    const pathBytes = enc.encode(e.path);
+    const body = e.dir ? new Uint8Array(0) : (e.bytes ?? new Uint8Array(0));
+    const meta = new Uint8Array(9);
+    const dv = new DataView(meta.buffer);
+    dv.setUint8(0, e.dir ? 1 : 0);
+    dv.setUint32(1, pathBytes.length, true);
+    dv.setUint32(5, body.length, true);
+    chunks.push(meta, pathBytes, body);
+  }
+  let total = 0;
+  for (const c of chunks) total += c.length;
+  const out = new Uint8Array(total);
+  let off = 0;
+  for (const c of chunks) { out.set(c, off); off += c.length; }
+  return out;
+}
+
+/** Returns a `Map<name, File|Directory>` — the `contents` of the deserialized root. */
+export function deserializeTree(bytes, { File, Directory }) {
+  const u8 = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+  const dv = new DataView(u8.buffer, u8.byteOffset, u8.byteLength);
+  let off = 0;
+  const count = dv.getUint32(off, true); off += 4;
+  const root = new Directory(new Map());
+  for (let i = 0; i < count; i++) {
+    const isDir = dv.getUint8(off); off += 1;
+    const pathLen = dv.getUint32(off, true); off += 4;
+    const byteLen = dv.getUint32(off, true); off += 4;
+    const path = dec.decode(u8.subarray(off, off + pathLen)); off += pathLen;
+    const body = u8.subarray(off, off + byteLen); off += byteLen;
+    const parts = path.split("/");
+    let cur = root;
+    for (let p = 0; p < parts.length - 1; p++) {
+      let next = cur.contents.get(parts[p]);
+      if (!next) { next = new Directory(new Map()); cur.contents.set(parts[p], next); }
+      cur = next;
+    }
+    const leaf = parts[parts.length - 1];
+    if (isDir) {
+      if (!cur.contents.get(leaf)) cur.contents.set(leaf, new Directory(new Map()));
+    } else {
+      cur.contents.set(leaf, new File(body.slice()));
+    }
+  }
+  return root.contents;
+}