@githolon/testing 0.13.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/testing",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "type": "module",
   "description": "@githolon/testing — law TDD for Nomos domains: boot the REAL engine plane in-process (the exact machinery every cloud DO, heavy container and web client runs), dispatch directives, assert rows, assert TYPED REFUSALS, fork for what-ifs — fully offline inside vitest.",
   "license": "SEE LICENSE IN LICENSE.md",

package/vendor/engine/engine.mjs

@@ -39,7 +39,14 @@ function call(ex, mode, fields, STDERR) {
   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));
+    let packed;
+    try {
+      packed = ex.git_holon_call(reqPtr, req.length);
+    } catch (e) {
+      const tail = STDERR.length ? ` | stderr: ${STDERR.slice(-8).join(" / ")}` : "";
+      throw new Error(`${String((e && e.stack) || e)}${tail}`);
+    }
+    const { ptr, len } = unpack(packed);
     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(" / ")}` : ""));
@@ -1018,6 +1025,93 @@ export async function replicateIntents(eng, ws, ledger, intents, { push = true }
   return { replicated, skipped, refused };
 }
 
+/**
+ * Open browser/session lane without a client-side Artifacts receive-pack: the
+ * client offers the exact intent bytes it authored locally; the host applies the
+ * same structural fences as session admission, folds accepted bytes, and seals
+ * main once. This is still untrusted work: owner-only/control-plane/receipt
+ * writes are refused or dead-lettered exactly like session refs.
+ */
+export async function admitIntentOffers(eng, ws, ledger, offers, { refuseDomains = [], receiptFence = null } = {}) {
+  const refuse = new Set(refuseDomains);
+  const main = await mainIntentIds(eng, ws);
+  const sessions = new Map();
+  const deadLetters = [];
+  let admittedTotal = 0;
+  const timings = { spans: [], intents: 0, sessions: 0 };
+  const t0 = Date.now(); let seq = 0;
+  const span = (name, kind, depth = 1, extra = {}) => {
+    const s0 = Date.now();
+    return (end = {}) => timings.spans.push({ id: `intent-offer-${t0}-${seq++}`, track: "cloud", name, kind, depth, t0: s0, t1: Date.now(), ...extra, ...end });
+  };
+  for (const offer of Array.isArray(offers) ? offers : []) {
+    const cid = typeof offer?.session === "string" && offer.session ? offer.session : "direct";
+    const rec = sessions.get(cid) || { session: cid, admitted: [], rejected: [], skipped: [] };
+    sessions.set(cid, rec);
+    const done = span(`intent offer ${cid.slice(0, 14)}`, "cadmit", 1, { client: cid });
+    let blob = offer?.blob instanceof Uint8Array ? offer.blob : null;
+    try {
+      if (!blob && typeof offer?.intentB64 === "string") blob = Uint8Array.from(atob(offer.intentB64), (c) => c.charCodeAt(0));
+      if (!blob || blob.byteLength === 0 || blob.byteLength > 256 * 1024) {
+        rec.rejected.push({ oid: String(offer?.oid || "").slice(0, 10), error: "intent offer must carry intentB64 <= 256 KiB" });
+        continue;
+      }
+      let doc = null;
+      try { doc = JSON.parse(dec.decode(blob)); } catch {}
+      const intentId = typeof doc?.id === "string" ? doc.id : null;
+      const dom = typeof doc?.payload?.domain === "string" ? doc.payload.domain : null;
+      const dirId = typeof doc?.payload?.directiveId === "string" ? doc.payload.directiveId : null;
+      const oid = String(offer?.oid || intentId || "").slice(0, 10);
+      if (!dom || dom === "nomos" || dom === "bootstrap" || refuse.has(dom)) {
+        rec.rejected.push({ oid, error: `session lane refuses ${dom ? `'${dom}'` : "non-authored"} intents — law deploys go through POST /v1/workspaces/${ws}/domains with the workspace secret` });
+        continue;
+      }
+      if (!knownDomains(eng).has(dom)) {
+        const error = `domain '${dom}' is not deployed to this workspace — deploy its law (POST /v1/workspaces/${ws}/domains with the workspace secret), then POST /v1/workspaces/${ws}/dead-letters/retry`;
+        rec.rejected.push({ oid, error, deadLettered: true });
+        deadLetters.push({ intentId, oid, session: cid, error, blob, domain: dom, directiveId: dirId });
+        continue;
+      }
+      if (receiptFence && dirId && Array.isArray(receiptFence[dom]) && receiptFence[dom].includes(dirId)) {
+        const error = `'${dom}/${dirId}' is a capability RECEIPT — receipts are executor/owner writes, never open-session writes. Author it via POST /v1/workspaces/${ws}/author (owner Bearer), or — if this parked receipt is sanctioned — the owner unjams it: POST /v1/workspaces/${ws}/dead-letters/retry`;
+        rec.rejected.push({ oid, error, deadLettered: true });
+        deadLetters.push({ intentId, oid, session: cid, error, blob, domain: dom, directiveId: dirId });
+        continue;
+      }
+      if (intentId && main.ids.has(intentId)) {
+        rec.skipped.push({ oid, intent: intentId.slice(0, 12), alreadyOnMain: true });
+        continue;
+      }
+      const res = applyIntentBytes(eng, ws, blob);
+      if (res.ok) {
+        if (intentId) main.ids.add(intentId);
+        main.oids.add(res.head); main.head = res.head;
+        rec.admitted.push({ oid, head: res.head });
+        admittedTotal += 1;
+      } else {
+        const error = `${String(res.error || "").slice(0, 300)} — dead-lettered; fix the law (or the payload), then POST /v1/workspaces/${ws}/dead-letters/retry`;
+        rec.rejected.push({ oid, error, deadLettered: true });
+        deadLetters.push({ intentId, oid, session: cid, error, blob, domain: dom, directiveId: dirId });
+      }
+    } catch (e) {
+      rec.rejected.push({ oid: String(offer?.oid || "").slice(0, 10), error: String(e).slice(0, 200) });
+    } finally {
+      done();
+    }
+  }
+  timings.sessions = sessions.size;
+  timings.intents = admittedTotal;
+  if (admittedTotal) {
+    const sealDone = span("seal offered intents", "cseal", 1, { admitted: admittedTotal });
+    await commitAndPush(eng, ws, ledger);
+    sealDone();
+  }
+  const gitdir = gitdirOf(ws);
+  const head = await git.resolveRef({ fs: eng.fs, gitdir, ref: BRANCH }).catch(() => main.head);
+  log("admit-intent-offers", { ws, sessions: sessions.size, admitted: admittedTotal, rejected: [...sessions.values()].reduce((n, s) => n + s.rejected.length, 0) });
+  return { sessions: [...sessions.values()].map((s) => ({ ...s, ...(s.skipped.length ? {} : { skipped: undefined }) })), main: head, deadLetters, timings };
+}
+
 /**
  * §5.5 (slice 4) — the CONTENT HASH of the coordinator's committed subtotal state:
  * sha256 over the canonical (row-id-sorted) projection of every
@@ -1118,31 +1212,93 @@ export async function deepVerifyShard(eng, shardWs, shardLedger, coordinatorRows
   };
 }
 
-/** Mount a workspace, restoring its repo from the Artifacts ledger ({remote, headers}). */
-export async function mountWorkspace(eng, ws, ledger) {
-  if (eng.mounted.has(ws)) return eng.mounted.get(ws);
+function stageWorkspaceDir(eng, ws) {
   const wsContents = new Map();
   seedManifests(wsContents, eng.manifestStrings);
   eng.preopen.dir.contents.get("ws").contents.set(ws, new Directory(wsContents));
+}
+
+/** Mount a workspace, restoring its repo from the Artifacts ledger ({remote, headers}). */
+export async function mountWorkspace(eng, ws, ledger) {
+  if (eng.mounted.has(ws)) return eng.mounted.get(ws);
+  stageWorkspaceDir(eng, ws);
   const gitdir = gitdirOf(ws);
-  let restored = false, remoteMain = null, restoreError = null;
+  let restored = false, remoteMain = null, restoreError = null, checkpoint = null;
   try {
     const info = await git.getRemoteInfo({ http, url: ledger.remote, headers: ledger.headers });
     remoteMain = (info.refs && info.refs.heads && info.refs.heads.main) || null;
     if (remoteMain) {
       await git.init({ fs: eng.fs, gitdir, bare: true, defaultBranch: "main" });
       await git.addRemote({ fs: eng.fs, gitdir, remote: "origin", url: ledger.remote, force: true });
-      await git.fetch({ fs: eng.fs, http, gitdir, remote: "origin", ref: "main", singleBranch: true, headers: ledger.headers });
+      const ckpt = await discoverCheckpointFromCustody(ledger).catch(() => null);
+      let shallowOk = false;
+      if (ckpt?.cursor && ckpt.frontier) {
+        const steps = [32, 96, 256, 1024];
+        for (let i = 0; i < steps.length; i++) {
+          const depth = steps[i], relative = i > 0;
+          await git.fetch({ fs: eng.fs, http, gitdir, remote: "origin", ref: "main", singleBranch: true, depth, relative, headers: ledger.headers });
+          if (await git.readCommit({ fs: eng.fs, gitdir, oid: ckpt.cursor }).then(() => true, () => false)) { shallowOk = true; break; }
+        }
+      }
+      if (!shallowOk) await git.fetch({ fs: eng.fs, http, gitdir, remote: "origin", ref: "main", singleBranch: true, headers: ledger.headers });
       await git.writeRef({ fs: eng.fs, gitdir, ref: "refs/heads/main", value: remoteMain, force: true });
       await git.writeRef({ fs: eng.fs, gitdir, ref: "HEAD", value: "ref: refs/heads/main", force: true, symbolic: true });
+      if (shallowOk && ckpt?.blob) {
+        const r = importCheckpoint(eng, ws, ckpt.blob, ckpt.frontier);
+        checkpoint = { restored: !!(r && r.restored), frontierSeeded: !!(r && r.frontierSeeded), cursor: r && r.cursor ? r.cursor : ckpt.cursor, ref: ckpt.ref };
+      }
       restored = true;
     }
   } catch (e) { restoreError = String((e && e.stack) || e).split("\n").slice(0, 5).join(" | "); }
-  const m = { restored, remoteMain, restoreError };
+  const m = { restored, remoteMain, restoreError, checkpoint };
   eng.mounted.set(ws, m);
   return m;
 }
 
+function assertAuthored(res, what) {
+  if (!res || res.ok === false) throw new Error(`${what}: ${String((res && res.error) || "law refused the intent").slice(0, 500)}`);
+  return res;
+}
+
+/**
+ * Mount a host-ephemeral workspace. It is still a normal WASI GitHolon under
+ * `/work/ws/<name>`; the host behavior is what differs: no custody restore, no
+ * Artifacts push, and the whole chain dies with the resident host.
+ */
+export async function mountEphemeralWorkspace(eng, ws, { domainHash = "", packageUsda = "" } = {}) {
+  let m = eng.mounted.get(ws);
+  if (!m) {
+    stageWorkspaceDir(eng, ws);
+    m = { restored: false, remoteMain: null, restoreError: null, ephemeral: true };
+    eng.mounted.set(ws, m);
+  }
+  if (!nomosActive(eng, ws)) {
+    assertAuthored(
+      author(eng, ws, "bootstrap", "installDomain", installPayload(eng.hashes.nomos, eng.nomosPkg, eng.installedBy), "", { deferProjection: false, rngDraws: 8 }),
+      `ephemeral workspace '${ws}' bootstrap`,
+    );
+  }
+  if (domainHash && packageUsda && qById(eng, ws, `domain-installation:${domainHash}`).length === 0) {
+    assertAuthored(
+      author(eng, ws, "nomos", "installDomain", installPayload(domainHash, packageUsda, eng.installedBy), eng.hashes.nomos, { deferProjection: false, rngDraws: 8 }),
+      `ephemeral workspace '${ws}' installDomain(${domainHash.slice(0, 12)})`,
+    );
+  }
+  return m;
+}
+
+/** Author into a host-ephemeral workspace and leave the resulting head in memory only. */
+export async function authorEphemeral(eng, ws, mountOpts, domain, directiveId, payload, lawHash, opts = {}) {
+  await mountEphemeralWorkspace(eng, ws, mountOpts);
+  return author(eng, ws, domain, directiveId, payload, lawHash, { deferProjection: false, ...opts });
+}
+
+/** Query a host-ephemeral workspace, mounting/installing its package first if needed. */
+export async function queryEphemeral(eng, ws, mountOpts, queryId, paramsJson, principal = "", keys = []) {
+  await mountEphemeralWorkspace(eng, ws, mountOpts);
+  return query(eng, ws, queryId, paramsJson, principal, keys);
+}
+
 /** Drop a workspace's in-memory state so the next access re-restores from the ledger. */
 export function unmount(eng, ws) {
   eng.mounted.delete(ws);
@@ -1230,8 +1386,8 @@ export function exportCheckpoint(eng, ws) {
 /** Restore a checkpoint blob into the pool BEFORE the first read on a cold mount (no-op if the pool
  *  is already warm). The HOST restores ONLY a blob whose stored lawHash matches the workspace's
  *  CURRENT law (schema parity); a mismatched/absent blob costs at most a cold fold, never a wrong read. */
-export function importCheckpoint(eng, ws, blobB64) {
-  return JSON.parse(call(eng.ex, "checkpoint_import", { repoArg: repoArgOf(ws), workspace: ws, branch: BRANCH, blob: blobB64 }, eng.STDERR));
+export function importCheckpoint(eng, ws, blobB64, frontierB64) {
+  return JSON.parse(call(eng.ex, "checkpoint_import", { repoArg: repoArgOf(ws), workspace: ws, branch: BRANCH, blob: blobB64, ...(frontierB64 ? { frontier: frontierB64 } : {}) }, eng.STDERR));
 }
 
 // ── CHECKPOINT IN CUSTODY (the host-agnostic cold-mount; compute placement is beneath the contract) ──
@@ -1265,6 +1421,36 @@ async function gunzip(bytes) {
   return streamAll(new Response(bytes).body.pipeThrough(ds));
 }
 
+async function discoverCheckpointFromCustody(ledger) {
+  const freshHeaders = () => ({ ...(ledger.headers || {}) });
+  const refs = ((await git.listServerRefs({ http, url: ledger.remote, headers: freshHeaders(), prefix: "refs/meta/checkpoint/", protocolVersion: 2 })) || [])
+    .filter((r) => r.ref && r.ref.startsWith("refs/meta/checkpoint/") && r.oid);
+  if (!refs.length) return null;
+  const root = new Map();
+  root.set("ckpt", new Directory(new Map()));
+  const preopen = new PreopenDirectory("/work", root);
+  const fs = makeGitFs(preopen, "/work", { File, Directory });
+  const gitdir = "/work/ckpt/nomos.git";
+  await git.init({ fs, gitdir, bare: true, defaultBranch: BRANCH });
+  await git.addRemote({ fs, gitdir, remote: "origin", url: ledger.remote, force: true });
+  const readFile = async (oid, filepath) => { try { return (await git.readBlob({ fs, gitdir, oid, filepath })).blob; } catch { return null; } };
+  for (let i = refs.length - 1; i >= 0 && i >= refs.length - 3; i--) {
+    const { ref, oid } = refs[i];
+    try {
+      await git.fetch({ fs, http, gitdir, remote: "origin", ref, singleBranch: true, depth: 1, headers: freshHeaders() });
+      const gz = await readFile(oid, "checkpoint");
+      if (!gz) continue;
+      let meta = {}; try { const mb = await readFile(oid, "meta"); if (mb) meta = JSON.parse(dec.decode(mb)); } catch {}
+      const codec = meta.codec ?? "gzip";
+      const blob = dec.decode(codec === "gzip" ? await gunzip(gz) : gz);
+      const fgz = await readFile(oid, "frontier");
+      const frontier = fgz ? dec.decode(codec === "gzip" ? await gunzip(fgz) : fgz) : null;
+      return { ref, oid, cursor: meta.cursor || null, blob, frontier };
+    } catch { /* try an older checkpoint */ }
+  }
+  return null;
+}
+
 /** Wrap an exported checkpoint into git objects under `refs/meta/checkpoint/<lawHash>` (LOCAL only —
  *  no network). The ref points at a parentless commit whose tree carries `checkpoint` (the b64 blob)
  *  and `meta` ({cursor,bytes,lawHash}). Returns {ref, commitOid}. Separated from the push so the
@@ -1273,25 +1459,41 @@ export async function writeCheckpointObjects(eng, ws, ex, lawHash) {
   const gitdir = gitdirOf(ws);
   const gz = await gzip(enc.encode(ex.blob));
   const blobOid = await git.writeBlob({ fs: eng.fs, gitdir, blob: gz });
-  const metaOid = await git.writeBlob({ fs: eng.fs, gitdir, blob: enc.encode(JSON.stringify({ cursor: ex.cursor, bytes: ex.bytes ?? 0, lawHash, codec: "gzip", raw: ex.blob.length, stored: gz.length })) });
-  const tree = await git.writeTree({ fs: eng.fs, gitdir, tree: [
+  // THE FOLD FRONTIER (the gate's Workspace state @cursor) rides ALONGSIDE the projection so a cold mount
+  // can AUTHOR on a shallow clone (the projection alone is a read-collapsed view the gate can't fold from).
+  // Era-safe: pre-this-era exports carry no `ex.frontier`, so the `frontier` file is simply absent and a
+  // reader falls back to a full clone (writes need full history). Gzipped like the projection blob.
+  const tree = [
     { mode: "100644", path: "checkpoint", oid: blobOid, type: "blob" },
-    { mode: "100644", path: "meta", oid: metaOid, type: "blob" },
-  ] });
-  const commitOid = await git.writeCommit({ fs: eng.fs, gitdir, commit: { tree, parent: [], author: CKPT_AUTHOR, committer: CKPT_AUTHOR, message: `checkpoint ${ws} @${String(ex.cursor).slice(0, 16)}` } });
+  ];
+  let fgzLen = 0;
+  if (ex.frontier) {
+    const fgz = await gzip(enc.encode(ex.frontier));
+    fgzLen = fgz.length;
+    tree.push({ mode: "100644", path: "frontier", oid: await git.writeBlob({ fs: eng.fs, gitdir, blob: fgz }), type: "blob" });
+  }
+  const metaOid = await git.writeBlob({ fs: eng.fs, gitdir, blob: enc.encode(JSON.stringify({ cursor: ex.cursor, bytes: ex.bytes ?? 0, lawHash, codec: "gzip", raw: ex.blob.length, stored: gz.length, frontierStored: fgzLen })) });
+  tree.push({ mode: "100644", path: "meta", oid: metaOid, type: "blob" });
+  const tree_ = await git.writeTree({ fs: eng.fs, gitdir, tree });
+  const commitOid = await git.writeCommit({ fs: eng.fs, gitdir, commit: { tree: tree_, parent: [], author: CKPT_AUTHOR, committer: CKPT_AUTHOR, message: `checkpoint ${ws} @${String(ex.cursor).slice(0, 16)}` } });
   const ref = CKPT_REF(lawHash);
   await git.writeRef({ fs: eng.fs, gitdir, ref, value: commitOid, force: true });
   return { ref, commitOid };
 }
 
-/** Read a checkpoint blob back out of a commit oid (LOCAL only — the objects must already be present,
- *  via a prior write or a shallow fetch). Returns the b64 string importCheckpoint accepts. */
+/** Read a checkpoint's projection blob (and its fold frontier, if present) back out of a commit oid
+ *  (LOCAL only — the objects must already be present, via a prior write or a shallow fetch). Returns
+ *  `{ blob, frontier }` — both the b64 strings importCheckpoint accepts; `frontier` is null for a
+ *  pre-this-era checkpoint (no `frontier` file). */
 export async function readCheckpointBlob(eng, ws, commitOid) {
   const gitdir = gitdirOf(ws);
   const { blob } = await git.readBlob({ fs: eng.fs, gitdir, oid: commitOid, filepath: "checkpoint" });
   let codec = "gzip";
   try { codec = JSON.parse(dec.decode((await git.readBlob({ fs: eng.fs, gitdir, oid: commitOid, filepath: "meta" })).blob)).codec ?? "gzip"; } catch {}
-  return dec.decode(codec === "gzip" ? await gunzip(blob) : blob);
+  const dezip = async (b) => dec.decode(codec === "gzip" ? await gunzip(b) : b);
+  let frontier = null;
+  try { frontier = await dezip((await git.readBlob({ fs: eng.fs, gitdir, oid: commitOid, filepath: "frontier" })).blob); } catch { /* pre-this-era: no frontier */ }
+  return { blob: await dezip(blob), frontier };
 }
 
 /** The checkpoint's schema-parity key: a hash of the workspace's CURRENT law map (every installed
@@ -1312,13 +1514,18 @@ export async function pushCheckpoint(eng, ws, ledger, lawHash) {
   try {
     lawHash = await lawParity(eng, ws, lawHash);
     if (!lawHash) return { pushed: false, reason: "no-law" };
+    const gitdir = gitdirOf(ws);
+    const head = await git.resolveRef({ fs: eng.fs, gitdir, ref: "refs/heads/main" }).catch(() => null);
+    eng._ckptPushed ??= new Map();
+    if (head && eng._ckptPushed.get(ws) === `${lawHash}:${head}`) {
+      return { pushed: false, reason: "unchanged" };
+    }
     const ex = exportCheckpoint(eng, ws);
     if (!ex || ex.empty || !ex.ok || !ex.blob) return { pushed: false, reason: ex && ex.empty ? "empty" : "no-blob" };
-    eng._ckptPushed ??= new Map();
     const tag = `${lawHash}:${ex.cursor}`;
     if (eng._ckptPushed.get(ws) === tag) return { pushed: false, reason: "unchanged" };
     const { ref } = await writeCheckpointObjects(eng, ws, ex, lawHash);
-    await git.push({ fs: eng.fs, http, gitdir: gitdirOf(ws), url: ledger.remote, ref, remoteRef: ref, force: true, headers: ledger.headers });
+    await pushVia(ledger, () => git.push({ fs: eng.fs, http, gitdir, url: ledger.remote, ref, remoteRef: ref, force: true, headers: ledger.headers }));
     eng._ckptPushed.set(ws, tag);
     return { pushed: true, cursor: ex.cursor, bytes: ex.bytes ?? 0 };
   } catch (e) { return { pushed: false, reason: String((e && e.message) || e).slice(0, 160) }; }
@@ -1329,25 +1536,40 @@ export async function pushCheckpoint(eng, ws, ledger, lawHash) {
  *  absent or the law drifted. Returns {restored, cursor?, reason?}. */
 export async function restoreCheckpointFromCustody(eng, ws, ledger, lawHash) {
   try {
+    const mounted = eng.mounted.get(ws);
+    if (mounted?.checkpoint?.restored) {
+      return { restored: false, reason: "already-mounted-checkpoint" };
+    }
     lawHash = await lawParity(eng, ws, lawHash);
     if (!lawHash) return { restored: false, reason: "no-law" };
     const ref = CKPT_REF(lawHash);
-    const serverRefs = await git.listServerRefs({ http, url: ledger.remote, headers: ledger.headers, prefix: ref, protocolVersion: 2 });
+    const freshHeaders = () => ({ ...(ledger.headers || {}) });
+    const serverRefs = await git.listServerRefs({ http, url: ledger.remote, headers: freshHeaders(), prefix: ref, protocolVersion: 2 });
     const found = (serverRefs || []).find((r) => r.ref === ref);
     if (!found || !found.oid) return { restored: false, reason: "absent" };
     const gitdir = gitdirOf(ws);
-    await git.fetch({ fs: eng.fs, http, gitdir, url: ledger.remote, ref, singleBranch: true, depth: 1, headers: ledger.headers });
-    const b64 = await readCheckpointBlob(eng, ws, found.oid);
-    const r = importCheckpoint(eng, ws, b64);
-    return { restored: r && r.restored === true, cursor: r && r.cursor, reason: r && r.reason };
+    await git.fetch({ fs: eng.fs, http, gitdir, url: ledger.remote, ref, singleBranch: true, depth: 1, headers: freshHeaders() });
+    const { blob, frontier } = await readCheckpointBlob(eng, ws, found.oid);
+    const r = importCheckpoint(eng, ws, blob, frontier);
+    if (r && r.restored === true && r.cursor) {
+      eng._ckptPushed ??= new Map();
+      eng._ckptPushed.set(ws, `${lawHash}:${r.cursor}`);
+    }
+    return { restored: r && r.restored === true, frontierSeeded: r && r.frontierSeeded === true, cursor: r && r.cursor, reason: r && r.reason };
   } catch (e) { return { restored: false, reason: String((e && e.message) || e).slice(0, 160) }; }
 }
 
+// Serialize a push through the host's per-repo lane when present (the DO threads `ledger.pushLane`); the
+// container has none and serializes on its own chain. The point: ONE receive-pack to a given Artifacts repo
+// at a time — a detached checkpoint/shape push can never race the admit's main push (concurrent receive-packs
+// were corrupting/500ing the custody store). All same-repo pushes below funnel through here.
+const pushVia = (ledger, fn) => (ledger && ledger.pushLane ? ledger.pushLane(fn) : fn());
+
 // DURABILITY-BEFORE-ACK: only acked once the write LANDED in the ledger; a failed push
 // unmounts (drops local state) so the next access re-restores from custody.
 export async function commitAndPush(eng, ws, ledger) {
   try {
-    await git.push({ fs: eng.fs, http, gitdir: gitdirOf(ws), url: ledger.remote, ref: "main", remoteRef: "main", force: false, headers: ledger.headers });
+    await pushVia(ledger, () => git.push({ fs: eng.fs, http, gitdir: gitdirOf(ws), url: ledger.remote, ref: "main", remoteRef: "main", force: false, headers: ledger.headers }));
   } catch (e) {
     unmount(eng, ws);
     throw new Error(`ledger push failed — write NOT durable, rolled back to ledger: ${e}`);
@@ -1374,9 +1596,9 @@ export async function pushShape(eng, ws, ledger) {
     eng._lastShapeRef ??= new Map();
     if (eng._lastShapeRef.get(ws) === newRef) return;
     await git.writeRef({ fs: eng.fs, gitdir, ref: newRef, value: head, force: true });
-    await git.push({ fs: eng.fs, http, gitdir, url: ledger.remote, ref: newRef, remoteRef: newRef, force: true, headers: ledger.headers });
+    await pushVia(ledger, () => git.push({ fs: eng.fs, http, gitdir, url: ledger.remote, ref: newRef, remoteRef: newRef, force: true, headers: ledger.headers }));
     const prev = eng._lastShapeRef.get(ws);
-    if (prev && prev !== newRef) { try { await git.push({ fs: eng.fs, http, gitdir, url: ledger.remote, ref: prev, remoteRef: prev, delete: true, headers: ledger.headers }); } catch { /* leftover refs are harmless: the reader takes max(bytes) */ } }
+    if (prev && prev !== newRef) { try { await pushVia(ledger, () => git.push({ fs: eng.fs, http, gitdir, url: ledger.remote, ref: prev, remoteRef: prev, delete: true, headers: ledger.headers })); } catch { /* leftover refs are harmless: the reader takes max(bytes) */ } }
     eng._lastShapeRef.set(ws, newRef);
   } catch { /* best-effort; placement self-heals */ }
 }
@@ -1385,7 +1607,7 @@ export async function pushShape(eng, ws, ledger) {
 // Returns {bytes} (the max, in case a restart left a stale ref) or null (no shape yet).
 export async function readShape(ledger) {
   try {
-    const refs = await git.listServerRefs({ http, url: ledger.remote, headers: ledger.headers, prefix: "refs/meta/shape/", protocolVersion: 2 });
+    const refs = await git.listServerRefs({ http, url: ledger.remote, headers: { ...(ledger.headers || {}) }, prefix: "refs/meta/shape/", protocolVersion: 2 });
     let best = null;
     for (const r of refs || []) {
       const m = /refs\/meta\/shape\/b(\d+)$/.exec(r.ref || "");
@@ -1482,13 +1704,53 @@ async function mainIntentIds(eng, ws) {
  * engine has no durable store), obvious attacks drop. Admitted intents merge to main,
  * durably push, the branch is consumed.
  */
-export async function admitAll(eng, ws, ledger, { refuseDomains = [], receiptFence = null, shardRouting = null } = {}) {
+export async function admitAll(eng, ws, ledger, { refuseDomains = [], receiptFence = null, shardRouting = null, sessionRefs = null } = {}) {
   const refuse = new Set(refuseDomains);
   const routes = shardRouting ? directiveRoutes(eng) : null;
   const gitdir = gitdirOf(ws);
-  const info = await git.getRemoteInfo({ http, url: ledger.remote, headers: ledger.headers });
-  const sessions = (info.refs && info.refs.heads && info.refs.heads.session) || {};
+  // FLAME-GRAPH EDGE TIMINGS — coarse per-stage wall-clock the client stitches into the cross-tier trace.
+  const _t0 = Date.now(); let _fetchMs = 0, _sealMs = 0, _intents = 0;
+  const _spans = []; let _traceSeq = 0;
+  const _span = (name, kind, depth = 1, extra = {}) => {
+    const t0 = Date.now();
+    return (end = {}) => {
+      const t1 = Date.now();
+      _spans.push({ id: `admit-${_t0}-${_traceSeq++}`, track: "cloud", name, kind, depth, t0, t1, ...extra, ...end });
+    };
+  };
+  const sessionRefPrefix = "refs/heads/session/";
+  const sessions = {};
+  const indexedRefs = sessionRefs && typeof sessionRefs === "object" ? sessionRefs : null;
+  const _scanDone = _span(indexedRefs ? "scan session index" : "scan session refs", "cscan", 1);
+  if (indexedRefs) {
+    const entries = Array.isArray(indexedRefs)
+      ? indexedRefs.map((r) => [String(r?.session || r?.cid || r?.client || ""), String(r?.head || r?.oid || "")])
+      : Object.entries(indexedRefs).map(([cid, head]) => [cid, String(head || "")]);
+    for (const [cid, head] of entries) {
+      if (/^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/.test(cid) && /^[0-9a-f]{40}$/.test(head)) sessions[cid] = head;
+    }
+  } else {
+    const refs = await git.listServerRefs({
+      http,
+      url: ledger.remote,
+      headers: ledger.headers,
+      prefix: sessionRefPrefix,
+      protocolVersion: 2,
+    });
+    for (const r of refs || []) {
+      const ref = typeof r?.ref === "string" ? r.ref : "";
+      const oid = typeof r?.oid === "string" ? r.oid : "";
+      if (!ref.startsWith(sessionRefPrefix) || !oid) continue;
+      sessions[ref.slice(sessionRefPrefix.length)] = oid;
+    }
+  }
+  _scanDone({ sessions: Object.keys(sessions).length });
+  const _scanMs = Date.now() - _t0;
   const results = [], deadLetters = [], placements = [], splits = [], globalsOut = [];
+  // BATCH THE MAIN PUSH: every session folds onto local main in the loop, then ONE commitAndPush seals the
+  // whole cycle (instead of one receive-pack per session). `consumed` are the session branches we processed
+  // and may delete AFTER the batch push lands — a failed batch leaves them for re-admit (idempotent by id).
+  const consumed = []; let totalAdmitted = 0;
   // §5.4 (slice 4): on the COORDINATOR of a taxonomy that declares `.global(...)`
   // reference data, every admitted intent touching a global aggregate is surfaced
   // to the HOST, which replicates the SAME sealed bytes into each shard chain.
@@ -1518,9 +1780,27 @@ export async function admitAll(eng, ws, ledger, { refuseDomains = [], receiptFen
   const headBefore = summaryCtx ? await git.resolveRef({ fs: eng.fs, gitdir, ref: BRANCH }).catch(() => null) : null;
   for (const [cid, head] of Object.entries(sessions)) {
     const ref = `refs/heads/session/${cid}`;
+    const shortCid = cid.length > 14 ? `${cid.slice(0, 14)}...` : cid;
+    const _sessionDone = _span(`session ${shortCid}`, "csession", 1, { client: cid });
     try {
       await git.addRemote({ fs: eng.fs, gitdir, remote: "origin", url: ledger.remote, force: true });
-      await git.fetch({ fs: eng.fs, http, gitdir, remote: "origin", ref, singleBranch: true, headers: ledger.headers });
+      const _fetchDone = _span(`fetch ${shortCid}`, "cfetch", 2, { client: cid });
+      const _f = Date.now();
+      try {
+        // THIN-FETCH (the 40s→0.5s fix): a `singleBranch` fetch sets isomorphic-git's have-set to
+        // [the fetched ref] ONLY. The edge holds no local session ref yet ⇒ it offers ZERO haves ⇒ the
+        // server re-ships the ENTIRE history (O(chain): measured ~10MB/40s for a 1-commit delta).
+        // Pre-seed the local session ref to OUR main head so the negotiation offers main as a have and the
+        // server sends only the delta above the common ancestor (~1KB/0.5s). main is append-only, so the
+        // client's fork point is always an ancestor of our head — the thin pack is always sound.
+        const localMain = await git.resolveRef({ fs: eng.fs, gitdir, ref: BRANCH }).catch(() => null);
+        if (localMain) { try { await git.writeRef({ fs: eng.fs, gitdir, ref, value: localMain, force: true }); } catch {} }
+        await git.fetch({ fs: eng.fs, http, gitdir, remote: "origin", ref, singleBranch: true, headers: ledger.headers });
+      } finally {
+        _fetchMs += Date.now() - _f;
+        _fetchDone();
+      }
+      const _walkDone = _span(`walk ${shortCid}`, "cwalk", 2, { client: cid });
       const main = await mainIntentIds(eng, ws);
       const chain = [];
       for (const c of await git.log({ fs: eng.fs, gitdir, ref: head, depth: 100 })) {
@@ -1528,7 +1808,9 @@ export async function admitAll(eng, ws, ledger, { refuseDomains = [], receiptFen
         chain.push(c.oid);
       }
       chain.reverse(); // oldest → newest
+      _walkDone({ intents: chain.length });
       const admitted = [], rejected = [], skipped = [];
+      const _gateDone = _span(`gate+fold ${shortCid}`, "cgate", 2, { client: cid, intents: chain.length });
       for (const oid of chain) {
         try {
           const { blob } = await git.readBlob({ fs: eng.fs, gitdir, oid, filepath: "intent.json" });
@@ -1685,11 +1967,40 @@ export async function admitAll(eng, ws, ledger, { refuseDomains = [], receiptFen
           rejected.push({ oid: oid.slice(0, 10), error: String(e).slice(0, 200) });
         }
       }
-      if (admitted.length) await commitAndPush(eng, ws, ledger);
-      try { await git.push({ fs: eng.fs, http, gitdir, url: ledger.remote, ref: BRANCH, remoteRef: ref, delete: true, headers: ledger.headers }); } catch {}
+      _gateDone({ admitted: admitted.length, rejected: rejected.length, skipped: skipped.length });
+      // FOLDED onto local main; the receive-pack is BATCHED below (one per cycle, not one per session).
+      // Record the branch as consumed so it's deleted only AFTER the batch push lands.
+      _intents += admitted.length;
+      totalAdmitted += admitted.length;
+      consumed.push({ cid, ref });
       results.push({ session: cid, admitted, rejected, ...(skipped.length ? { skipped } : {}) });
     } catch (e) {
       results.push({ session: cid, error: String(e).slice(0, 200) });
+    } finally {
+      _sessionDone();
+    }
+  }
+  // THE BATCH SEAL — one receive-pack for the whole admit cycle. A failed push unmounts (engine.unmount drops
+  // the ws fs); we then SKIP the branch deletes so every offered intent re-admits next cycle (idempotent by
+  // id). On success, delete the consumed session branches (best-effort cleanup; a stale branch is a harmless
+  // re-fetch). Single-client workspaces were already one push/cycle; this collapses collaborative bursts.
+  let _sealed = true;
+  if (totalAdmitted) {
+    const _sealDone = _span(`seal (batch)`, "cseal", 1, { sessions: consumed.length, admitted: totalAdmitted });
+    const _s = Date.now();
+    try {
+      await commitAndPush(eng, ws, ledger);
+    } catch (e) {
+      _sealed = false;
+      log("admit-batch-push-failed", { ws, sessions: consumed.length, admitted: totalAdmitted, error: String(e).slice(0, 200) });
+    } finally {
+      _sealMs += Date.now() - _s;
+      _sealDone();
+    }
+  }
+  if (_sealed) {
+    for (const { ref } of consumed) {
+      try { await pushVia(ledger, () => git.push({ fs: eng.fs, http, gitdir, url: ledger.remote, ref: BRANCH, remoteRef: ref, delete: true, headers: ledger.headers })); } catch {}
     }
   }
   const newMain = await git.resolveRef({ fs: eng.fs, gitdir, ref: BRANCH }).catch(() => null);
@@ -1697,8 +2008,11 @@ export async function admitAll(eng, ws, ledger, { refuseDomains = [], receiptFen
   // The coalesced §5.2 delta of this batch (null when no scoped read moved): the HOST
   // closes it against the coordinator's recorded frontier and authors the Order.
   const summary = summaryCtx ? summaryOfCapture(summaryCtx, headBefore, newMain) : null;
+  const _total = Date.now() - _t0;
+  // EDGE FLAME SPANS: scan refs → fetch session branches → gate+fold each intent → seal to custody.
+  const timings = { totalMs: _total, scanMs: _scanMs, fetchMs: _fetchMs, sealMs: _sealMs, gateFoldMs: Math.max(0, _total - _scanMs - _fetchMs - _sealMs), intents: _intents, sessions: results.length, spans: _spans };
   return {
-    sessions: results, main: newMain, deadLetters,
+    sessions: results, main: newMain, deadLetters, timings,
     ...(summary ? { summary } : {}),
     ...(placements.length ? { placements } : {}),
     ...(splits.length ? { splits } : {}),
@@ -1755,8 +2069,8 @@ export async function archiveRefusedMain(eng, ws, ledger, label) {
   if (!m.restored) { unmount(eng, ws); return { archived: false, error: "no main to archive" }; }
   const gitdir = gitdirOf(ws);
   try {
-    await git.push({ fs: eng.fs, http, gitdir, url: ledger.remote, ref: BRANCH, remoteRef: `refs/heads/refused/${label}`, force: true, headers: ledger.headers });
-    await git.push({ fs: eng.fs, http, gitdir, url: ledger.remote, ref: BRANCH, remoteRef: `refs/heads/${BRANCH}`, delete: true, headers: ledger.headers });
+    await pushVia(ledger, () => git.push({ fs: eng.fs, http, gitdir, url: ledger.remote, ref: BRANCH, remoteRef: `refs/heads/refused/${label}`, force: true, headers: ledger.headers }));
+    await pushVia(ledger, () => git.push({ fs: eng.fs, http, gitdir, url: ledger.remote, ref: BRANCH, remoteRef: `refs/heads/${BRANCH}`, delete: true, headers: ledger.headers }));
     return { archived: true, ref: `refs/heads/refused/${label}` };
   } finally {
     unmount(eng, ws);
@@ -1823,6 +2137,55 @@ export function stats(eng) {
   };
 }
 
+export async function ledgerStats(eng, ws, ledger = null) {
+  const gitdir = gitdirOf(ws);
+  let head = await git.resolveRef({ fs: eng.fs, gitdir, ref: BRANCH }).catch(() => null);
+  if (!head && ledger?.remote) {
+    try {
+      const info = await git.getRemoteInfo({ http, url: ledger.remote, headers: ledger.headers });
+      const remoteMain = (info.refs && info.refs.heads && info.refs.heads[BRANCH]) || null;
+      if (!remoteMain) return { head: null, commits: 0 };
+      await git.init({ fs: eng.fs, gitdir, bare: true, defaultBranch: BRANCH }).catch(() => {});
+      await git.addRemote({ fs: eng.fs, gitdir, remote: "origin", url: ledger.remote, force: true });
+      await git.fetch({ fs: eng.fs, http, gitdir, remote: "origin", ref: BRANCH, singleBranch: true, headers: ledger.headers });
+      await git.writeRef({ fs: eng.fs, gitdir, ref: `refs/heads/${BRANCH}`, value: remoteMain, force: true });
+      await git.writeRef({ fs: eng.fs, gitdir, ref: "HEAD", value: `ref: refs/heads/${BRANCH}`, force: true, symbolic: true });
+      head = await git.resolveRef({ fs: eng.fs, gitdir, ref: BRANCH }).catch(() => null);
+      const mounted = eng.mounted.get(ws);
+      if (mounted) {
+        mounted.restored = true;
+        mounted.remoteMain = remoteMain;
+        mounted.restoreError = null;
+      }
+    } catch {}
+  }
+  if (!head) return { head: null, commits: 0 };
+  const mounted = eng.mounted.get(ws);
+  if (mounted?.ledgerStats?.head === head) return mounted.ledgerStats;
+  const commits = (await git.log({ fs: eng.fs, gitdir, ref: head, depth: 10000000 })).length;
+  const out = { head, commits };
+  if (mounted) mounted.ledgerStats = out;
+  return out;
+}
+
+export async function countRemoteCommits(ledger) {
+  const info = await git.getRemoteInfo({ http, url: ledger.remote, headers: ledger.headers });
+  const head = (info.refs && info.refs.heads && info.refs.heads[BRANCH]) || null;
+  if (!head) return { head: null, commits: 0 };
+  const root = new Map();
+  root.set("count", new Directory(new Map()));
+  const preopen = new PreopenDirectory("/work", root);
+  const fs = makeGitFs(preopen, "/work", { File, Directory });
+  const gitdir = "/work/count/nomos.git";
+  await git.init({ fs, gitdir, bare: true, defaultBranch: BRANCH });
+  await git.addRemote({ fs, gitdir, remote: "origin", url: ledger.remote, force: true });
+  await git.fetch({ fs, http, gitdir, remote: "origin", ref: BRANCH, singleBranch: true, headers: ledger.headers });
+  await git.writeRef({ fs, gitdir, ref: `refs/heads/${BRANCH}`, value: head, force: true });
+  await git.writeRef({ fs, gitdir, ref: "HEAD", value: `ref: refs/heads/${BRANCH}`, force: true, symbolic: true });
+  const commits = (await git.log({ fs, gitdir, ref: head, depth: 10000000 })).length;
+  return { head, commits };
+}
+
 /** Per-branch projection observables (cursor, projectCalls, sqliteBytes — see #37). */
 export const projectionStats = (eng, ws) => JSON.parse(call(eng.ex, "projection_stats", ws ? { repoArg: repoArgOf(ws), workspace: ws, branch: BRANCH } : {}, eng.STDERR));