@githolon/testing 0.15.0 → 0.16.0

package/README.md

@@ -1,7 +1,7 @@
 # @githolon/testing — law TDD for Nomos domains
 
 Test your law the way the cloud judges it. `testHolon()` boots **the real engine
-plane** in-process — the vendored `cloud/holon-host` engine over the one
+plane** in-process — the vendored `cloud/cloudflare-shell` engine over the one
 wasm32-wasip1 artifact, the exact machinery every cloud DO, heavy container and
 web client runs — installs your compiled law at genesis, and hands you a holon
 you drive from vitest. Nothing is simulated: every `dispatch` runs the real
@@ -136,14 +136,14 @@ fixture) and the guestbook example's law tests
 ## How the runtime arrives (the wasm story, honestly)
 
 The engine JS is **vendored into this package at build** (synced verbatim from
-`cloud/holon-host/src` — the cli/deploy.sh pattern, so it can't fork). The wasm
+`cloud/cloudflare-shell/src` — the cli/deploy.sh pattern, so it can't fork). The wasm
 artifact + the baked bootstrap/nomos packages and manifests are **not** in the
 npm package (the wasm alone is tens of MB); they resolve, first hit wins:
 
 1. **`runtimeDir`** option / `GITHOLON_RUNTIME_DIR` — a directory you control
    holding `{holon.wasm, manifests.json, packages.json}` (the cache shape).
    Pin this in CI for fully hermetic runs.
-2. **The monorepo** — inside the nomos2 repo, `cloud/holon-host`'s vendored
+2. **The monorepo** — inside the nomos2 repo, `cloud/cloudflare-shell`'s vendored
    wasm + domain artifacts are used directly. Never any network.
 3. **The shared cache** — `~/.holon/runtime` (`HOLON_CONFIG_DIR` overrides),
    the SAME cache the `githolon` cli populates: any prior `githolon ledger`

package/build.mjs

@@ -1,4 +1,4 @@
-// Vendor THE ENGINE PLANE (cloud/holon-host/src/{engine,git-fs,tree}.mjs — the
+// Vendor THE ENGINE PLANE (cloud/cloudflare-shell/src/{engine,git-fs,tree}.mjs — the
 // exact machinery the edge DO and the heavy container run) into this package so
 // `testHolon()` boots holons in-process with the same code path the cloud uses.
 // Sync-at-build keeps it un-forked (the cli/build.mjs / deploy.sh pattern); the
@@ -9,15 +9,23 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
-const ENGINE_SRC = join(HERE, "..", "cloud", "holon-host", "src");
+const ENGINE_SRC = join(HERE, "..", "cloud", "cloudflare-shell", "src");
+const ADAPTER_SRC = join(HERE, "..", "adapter"); // git-fs.mjs + tree.mjs are the SHARED adapter now
 const VENDOR = join(HERE, "vendor", "engine");
 
 if (existsSync(ENGINE_SRC)) {
   mkdirSync(VENDOR, { recursive: true });
-  for (const f of ["engine.mjs", "git-fs.mjs", "tree.mjs"]) {
-    const body = readFileSync(join(ENGINE_SRC, f), "utf8");
-    writeFileSync(join(VENDOR, f), `// AUTO-SYNCED from cloud/holon-host/src/${f} by testing/build.mjs — DO NOT EDIT HERE.\n${body}`, "utf8");
+  // The shell's engine plane (engine.mjs + its custody-transport sibling). Rewrite the repo-relative adapter
+  // import (../../../adapter/) to local so the vendored copies resolve side-by-side (the deploy.sh pattern).
+  for (const f of ["engine.mjs", "custody-transport.mjs"]) {
+    const body = readFileSync(join(ENGINE_SRC, f), "utf8").replace(/\.\.\/\.\.\/\.\.\/adapter\//g, "./");
+    writeFileSync(join(VENDOR, f), `// AUTO-SYNCED from cloud/cloudflare-shell/src/${f} by testing/build.mjs — DO NOT EDIT HERE.\n${body}`, "utf8");
+  }
+  // The shared adapter primitives the engine imports.
+  for (const f of ["git-fs.mjs", "tree.mjs"]) {
+    const body = readFileSync(join(ADAPTER_SRC, f), "utf8");
+    writeFileSync(join(VENDOR, f), `// AUTO-SYNCED from adapter/${f} by testing/build.mjs — DO NOT EDIT HERE.\n${body}`, "utf8");
   }
 } else if (!existsSync(join(VENDOR, "engine.mjs"))) {
-  throw new Error("engine plane not found: neither ../cloud/holon-host/src nor vendor/engine exists");
+  throw new Error("engine plane not found: neither ../cloud/cloudflare-shell/src nor vendor/engine exists");
 }

package/index.d.ts

@@ -136,7 +136,7 @@ export interface TestHolon {
 
 /**
  * Boot a law-under-test holon: the REAL engine plane (the vendored
- * cloud/holon-host engine over the one wasm artifact), your compiled law
+ * cloud/cloudflare-shell engine over the one wasm artifact), your compiled law
  * installed at genesis, fully offline after the one-time runtime acquisition.
  */
 export declare function testHolon(opts?: TestHolonOptions): Promise<TestHolon>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/testing",
-  "version": "0.15.0",
+  "version": "0.16.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/src/index.mjs

@@ -1,7 +1,7 @@
 // @githolon/testing — LAW TDD for Nomos domains.
 //
 // `testHolon({ deploy })` boots THE ENGINE PLANE in-process (the vendored
-// cloud/holon-host/src/engine.mjs — the exact machinery every cloud DO, heavy
+// cloud/cloudflare-shell/src/engine.mjs — the exact machinery every cloud DO, heavy
 // container and web client runs) over the one wasm32-wasip1 artifact, installs
 // your compiled law at genesis, and hands back a holon you drive from a test:
 // dispatch directives, read rows/queries/counts/sums, assert TYPED REFUSALS
@@ -33,7 +33,7 @@ import {
 import { deserializeTree } from "../vendor/engine/tree.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
-const HOLON_HOST = join(HERE, "..", "..", "cloud", "holon-host"); // the monorepo sibling
+const HOLON_HOST = join(HERE, "..", "..", "cloud", "cloudflare-shell"); // the monorepo sibling
 const DEFAULT_CLOUD = "https://nomos.captainapp.co.uk";
 const WS = "test"; // the in-engine mount name — a chain binds to no workspace name
 const UNBORN = { remote: "https://unborn.invalid/", headers: {} }; // degrades to a fresh in-memory tree
@@ -63,7 +63,7 @@ export class Refusal extends Error {
 // Resolution order (first hit wins):
 //   1. opts.runtimeDir / GITHOLON_RUNTIME_DIR — a cache-shaped dir you control
 //      ({holon.wasm, manifests.json, packages.json});
-//   2. the monorepo sibling cloud/holon-host (vendored wasm + baked domains) —
+//   2. the monorepo sibling cloud/cloudflare-shell (vendored wasm + baked domains) —
 //      fully offline for anyone working inside the nomos2 repo;
 //   3. the shared on-disk cache ~/.holon/runtime (HOLON_CONFIG_DIR overrides) —
 //      the SAME cache the githolon cli populates, so any prior `githolon ledger`
@@ -148,7 +148,7 @@ async function resolveRuntime(opts) {
   if (offline) {
     throw new Error(
       `offline and no runtime artifacts found. Provide one of: (a) runtimeDir pointing at {holon.wasm, manifests.json, packages.json}; ` +
-      `(b) run inside the nomos2 monorepo (cloud/holon-host vendors the wasm); ` +
+      `(b) run inside the nomos2 monorepo (cloud/cloudflare-shell vendors the wasm); ` +
       `(c) warm the shared cache once while online (any testHolon() run, or \`githolon ledger verify\`, populates ${cacheRoot()}).`,
     );
   }

package/vendor/engine/custody-transport.mjs

@@ -0,0 +1,167 @@
+// AUTO-SYNCED from cloud/cloudflare-shell/src/custody-transport.mjs by testing/build.mjs — DO NOT EDIT HERE.
+// THE CLOUD SHELL'S DUMB-PIPE CUSTODY TRANSPORT — raw git smart-HTTP over fetch(), ZERO isomorphic-git.
+//
+// Custody (Cloudflare Artifacts) is a git smart-HTTP remote. The KERNEL owns all git semantics (gix builds
+// + ingests conformant packs); this module is the platform-specific BYTE PIPE that shuttles those packs to
+// and from the remote. It frames pkt-lines, POSTs/GETs bytes, and parses the ref advertisement — nothing
+// more. It NEVER touches the object store, never decides admission, never manufactures a verdict: bytes +
+// shell IO only (the offer-kernel doctrine, OFFER_KERNEL_ARCHITECTURE.dot).
+//
+//   lsRefs        ← replaces git.getRemoteInfo / git.listServerRefs   (GET info/refs, parse advertisement)
+//   fetchPack     ← replaces git.fetch                                 (POST git-upload-pack → raw pack bytes)
+//   pushPack      ← replaces git.push   (generalises the proven dumbPush: many updates, deletes, empty pack)
+//
+// No sha1 anywhere: kernel-built packs carry their own trailer; the empty pack (delete-only push) is a
+// well-known constant. So this file is identical-behaviour on workerd (edge DO) and node (heavy container).
+
+const enc = new TextEncoder();
+const dec = new TextDecoder();
+const ZERO_OID = "0".repeat(40);
+
+// The canonical EMPTY packfile: `PACK` + version 2 + 0 objects, then its sha1 trailer (a constant).
+// Used for a delete-only receive-pack (a ref update that introduces no objects).
+const EMPTY_PACK = new Uint8Array([
+  0x50, 0x41, 0x43, 0x4b, 0x00, 0x00, 0x00, 0x02, 0x00, 0x00, 0x00, 0x00, // "PACK", ver 2, 0 objects
+  0x02, 0x9d, 0x08, 0x82, 0x3b, 0xd8, 0xa8, 0xea, 0xb5, 0x10, 0xad, 0x6a, // sha1(the 12 header bytes)
+  0xc7, 0x5c, 0x82, 0x3c, 0xfd, 0x3e, 0xd3, 0x1e,
+]);
+
+function concatBytes(chunks) {
+  let n = 0;
+  for (const c of chunks) n += c.length;
+  const out = new Uint8Array(n);
+  let o = 0;
+  for (const c of chunks) { out.set(c, o); o += c.length; }
+  return out;
+}
+
+// pkt-line: 4 hex length (incl. the 4 bytes) + payload. 0000 = flush.
+function pkt(payload) {
+  const body = typeof payload === "string" ? enc.encode(payload) : payload;
+  const len = (body.length + 4).toString(16).padStart(4, "0");
+  return concatBytes([enc.encode(len), body]);
+}
+const FLUSH = enc.encode("0000");
+
+// Walk pkt-lines from `buf` starting at `off`. Returns { lines:[Uint8Array payloads], rest:offset }.
+// Stops at a flush (0000) OR at the first non-pkt-line bytes (a raw packfile begins with "PACK", whose
+// first 4 bytes are not valid length-hex) — `rest` then points at the raw remainder (the pack).
+function readPktLines(buf, off = 0) {
+  const lines = [];
+  while (off + 4 <= buf.length) {
+    const hex = dec.decode(buf.subarray(off, off + 4));
+    if (!/^[0-9a-f]{4}$/.test(hex)) break; // raw data (pack) starts here
+    const len = parseInt(hex, 16);
+    if (len === 0) { off += 4; break; }    // flush-pkt
+    if (len < 4 || off + len > buf.length) break;
+    lines.push(buf.subarray(off + 4, off + len));
+    off += len;
+  }
+  return { lines, rest: off };
+}
+
+// ── lsRefs: the remote's ref advertisement (oid → name), optionally filtered by prefix. ──
+// GET info/refs?service=git-upload-pack returns: a `# service=...` pkt + flush, then `<oid> <name>\0caps`
+// for HEAD and `<oid> <name>` for the rest, then a flush. Pure v0 parse (the proxy speaks it; the prior
+// dumbPush already relied on this advertisement shape).
+export async function lsRefs(remote, headers = {}, { service = "git-upload-pack", prefix = null } = {}) {
+  const r = await fetch(`${remote}/info/refs?service=${service}`, { headers });
+  if (!r.ok) {
+    if (r.status === 404) return {}; // unborn remote — no refs
+    throw new Error(`info/refs ${r.status}: ${(await r.text()).slice(0, 180)}`);
+  }
+  const buf = new Uint8Array(await r.arrayBuffer());
+  // The advertisement is TWO pkt sections: `# service=...\n` + flush, THEN the ref lines + flush.
+  // Read the banner (stops at its flush), then the refs from where it left off.
+  const banner = readPktLines(buf, 0);
+  const { lines } = readPktLines(buf, banner.rest);
+  const refs = {};
+  for (const line of lines) {
+    let s = dec.decode(line).replace(/\n$/, "");
+    if (s.startsWith("#")) continue;          // `# service=...`
+    const nul = s.indexOf("\0");
+    if (nul >= 0) s = s.slice(0, nul);         // strip caps off the first ref
+    const sp = s.indexOf(" ");
+    if (sp !== 40) continue;                   // `<40-hex-oid> <name>`
+    const oid = s.slice(0, 40), name = s.slice(41);
+    if (!/^[0-9a-f]{40}$/.test(oid)) continue;
+    if (prefix && !name.startsWith(prefix)) continue;
+    refs[name] = oid;
+  }
+  return refs;
+}
+
+// ── fetchPack: pull a packfile for `wants` (minus anything reachable from `haves`). ──
+// POST git-upload-pack with a v0 want/have/done request, NO side-band (so the response is the ack
+// section as pkt-lines followed by the RAW packfile — simplest conformant parse). Returns the pack bytes
+// (the caller hands them to the kernel's apply_pack). `wants` empty ⇒ null (nothing to fetch).
+export async function fetchPack(remote, headers = {}, { wants = [], haves = [] } = {}) {
+  wants = wants.filter((w) => /^[0-9a-f]{40}$/.test(w) && w !== ZERO_OID);
+  if (!wants.length) return null;
+  const caps = "thin-pack ofs-delta agent=nomos-cloud";
+  const parts = [];
+  wants.forEach((w, i) => parts.push(pkt(`want ${w}${i === 0 ? " " + caps : ""}\n`)));
+  parts.push(FLUSH);
+  for (const h of haves) if (/^[0-9a-f]{40}$/.test(h) && h !== ZERO_OID) parts.push(pkt(`have ${h}\n`));
+  parts.push(pkt("done\n"));
+  const r = await fetch(`${remote}/git-upload-pack`, {
+    method: "POST",
+    headers: { "content-type": "application/x-git-upload-pack-request", "accept": "application/x-git-upload-pack-result", ...headers },
+    body: concatBytes(parts),
+  });
+  if (!r.ok) throw new Error(`upload-pack ${r.status}: ${(await r.text()).slice(0, 180)}`);
+  const buf = new Uint8Array(await r.arrayBuffer());
+  // Response = an ack section (NAK / ACK ... pkt-lines) then the pack. The pack is EITHER raw (if the
+  // server honoured no-side-band) OR side-band-64k multiplexed (gitty defaults to it): pkt-lines whose
+  // first payload byte is the band (1 = pack data, 2 = progress, 3 = fatal). De-mux band 1; fall back to
+  // the raw remainder when there's no side-band.
+  const { lines, rest } = readPktLines(buf, 0);
+  const packChunks = [];
+  let sideband = false;
+  for (const line of lines) {
+    if (line.length === 0) continue;
+    const head = dec.decode(line.subarray(0, Math.min(line.length, 3)));
+    if (head === "NAK" || head === "ACK" || head === "ERR" || head.startsWith("sha")) continue; // control
+    const band = line[0];
+    if (band === 1) { packChunks.push(line.subarray(1)); sideband = true; }
+    else if (band === 2) { /* progress — ignore */ }
+    else if (band === 3) { throw new Error("upload-pack fatal: " + dec.decode(line.subarray(1)).slice(0, 180)); }
+  }
+  const pack = sideband ? concatBytes(packChunks) : buf.subarray(rest);
+  if (pack.length < 12 || dec.decode(pack.subarray(0, 4)) !== "PACK") {
+    throw new Error(`upload-pack: no pack in response (${pack.length}B, sideband=${sideband})`);
+  }
+  return pack;
+}
+
+// ── pushPack: advance/delete refs on the remote with a kernel-built pack. ──
+// Generalises the proven dumbPush: many ref updates in one receive-pack, deletes (newOid = zero), and an
+// empty pack when the push introduces no objects (delete-only). `updates`: [{ ref, oldOid, newOid }].
+// `pack`: kernel-built bytes (self-trailered) or null/empty for delete-only. Throws unless EVERY ref
+// update reports `ok` AND the pack unpacked — a silent `ng` (objects accepted, ref refused) is non-durable.
+export async function pushPack(remote, headers = {}, { updates = [], pack = null } = {}) {
+  if (!updates.length) return { ok: true, noop: true };
+  const cmds = [];
+  updates.forEach((u, i) => {
+    const old = u.oldOid || ZERO_OID;
+    const neu = u.newOid || ZERO_OID;
+    const caps = i === 0 ? "\0report-status" : "";
+    cmds.push(pkt(`${old} ${neu} ${u.ref}${caps}\n`));
+  });
+  cmds.push(FLUSH);
+  const body = concatBytes([...cmds, pack && pack.length ? pack : EMPTY_PACK]);
+  const r = await fetch(`${remote}/git-receive-pack`, {
+    method: "POST",
+    headers: { "content-type": "application/x-git-receive-pack-request", ...headers },
+    body,
+  });
+  const txt = dec.decode(new Uint8Array(await r.arrayBuffer()));
+  const unpacked = /unpack ok/.test(txt);
+  const everyRefOk = updates.every((u) => new RegExp(`ok ${u.ref.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`).test(txt));
+  if (!(r.ok && unpacked && everyRefOk && !/\bng /.test(txt))) {
+    throw new Error(`receive-pack ${r.status}: ${txt.replace(/[^\x20-\x7e]/g, " ").trim().slice(0, 200)}`);
+  }
+  return { ok: true };
+}
+
+export { ZERO_OID };