@githolon/testing 0.3.0

package/src/index.mjs

@@ -0,0 +1,449 @@
+// @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
+// 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
+// (invariants are real law — a violating dispatch REJECTS with the invariant's
+// own reject code), fork() for what-ifs, verify() the chain.
+//
+// Nothing here is a simulator: every dispatch runs the real author gate
+// (payload zod, plan re-run, invariant oracle, kernel fold) and every fork /
+// verify replays the same bytes the cloud would replay on a push.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  author,
+  count as engineCount,
+  createEngine,
+  extremum as engineExtremum,
+  installPayload,
+  mountWorkspace,
+  qById,
+  query as engineQuery,
+  sha256hex,
+  snapshot,
+  sum as engineSum,
+  verifyChainLocal,
+  warmEngine,
+} from "../vendor/engine/engine.mjs";
+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 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
+
+const dec = new TextDecoder();
+
+// ── the typed refusal ─────────────────────────────────────────────────────────
+
+/**
+ * A dispatch the gate REFUSED — payload validation, a missing instance, or a
+ * declared invariant (the law's own reject code rides `message` verbatim, so
+ * `expect(...).rejects.toThrow(/seats-exceed-capacity/)` asserts the law).
+ */
+export class Refusal extends Error {
+  constructor(refusal, { domain, directiveId }) {
+    super(`${domain}/${directiveId} refused: ${refusal}`);
+    this.name = "Refusal";
+    this.domain = domain;
+    this.directiveId = directiveId;
+    /** The gate's verdict, verbatim. */
+    this.refusal = refusal;
+  }
+}
+
+// ── runtime acquisition (the wasm + baked packages/manifests) ─────────────────
+//
+// 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) —
+//      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`
+//      run already warmed it;
+//   4. the cloud's /v1/runtime endpoints (one fetch, then cached → offline after).
+// `opts.offline` / GITHOLON_TESTING_OFFLINE=1 forbids step 4 (fail with the story
+// instead of a surprise network call).
+
+const cacheRoot = () => join(process.env.HOLON_CONFIG_DIR ?? join(homedir(), ".holon"), "runtime");
+const cloudBase = (flag) => (flag ?? process.env.NOMOS_CLOUD ?? DEFAULT_CLOUD).replace(/\/+$/, "");
+
+function fromRuntimeDir(dir) {
+  const wasm = join(dir, "holon.wasm");
+  const manifests = join(dir, "manifests.json");
+  const packages = join(dir, "packages.json");
+  if (!existsSync(wasm) || !existsSync(manifests) || !existsSync(packages)) return null;
+  const m = JSON.parse(readFileSync(manifests, "utf8"));
+  const p = JSON.parse(readFileSync(packages, "utf8"));
+  return {
+    wasmBytes: readFileSync(wasm),
+    bootstrapPkg: p.bootstrap,
+    nomosPkg: p.nomos,
+    baked: { read: m.domainManifests, identity: m.identityManifests },
+    source: dir,
+  };
+}
+
+function fromHolonHost() {
+  const wasm = process.env.GITHOLON_TESTING_WASM ?? join(HOLON_HOST, "vendor", "wasm_git_holon.wasm");
+  const domains = join(HOLON_HOST, "domains");
+  if (!existsSync(wasm) || !existsSync(join(domains, "domain_nomos.package.usda"))) return null;
+  return {
+    wasmBytes: readFileSync(wasm),
+    bootstrapPkg: readFileSync(join(domains, "domain_bootstrap.package.usda"), "utf8"),
+    nomosPkg: readFileSync(join(domains, "domain_nomos.package.usda"), "utf8"),
+    baked: {
+      read: readFileSync(join(domains, "domain_manifests.txt"), "utf8"),
+      identity: readFileSync(join(domains, "identity_manifests.txt"), "utf8"),
+    },
+    source: wasm,
+  };
+}
+
+async function fromCloud(cloud, cache) {
+  const get = async (path) => {
+    const r = await fetch(`${cloud}${path}`);
+    if (!r.ok) throw new Error(`${cloud}${path} → ${r.status}`);
+    return r;
+  };
+  const wasmBytes = new Uint8Array(await (await get("/v1/runtime/holon.wasm")).arrayBuffer());
+  const manifests = await (await get("/v1/runtime/manifests")).text();
+  const packages = await (await get("/v1/runtime/packages")).text();
+  mkdirSync(cache, { recursive: true });
+  writeFileSync(join(cache, "holon.wasm"), wasmBytes);
+  writeFileSync(join(cache, "manifests.json"), manifests, "utf8");
+  writeFileSync(join(cache, "packages.json"), packages, "utf8");
+  const m = JSON.parse(manifests);
+  const p = JSON.parse(packages);
+  return {
+    wasmBytes,
+    bootstrapPkg: p.bootstrap,
+    nomosPkg: p.nomos,
+    baked: { read: m.domainManifests, identity: m.identityManifests },
+    source: cloud,
+  };
+}
+
+const runtimeMemo = new Map(); // key → Promise<runtime+compiled module>
+
+async function resolveRuntime(opts) {
+  const explicit = opts.runtimeDir ?? process.env.GITHOLON_RUNTIME_DIR;
+  if (explicit !== undefined) {
+    const r = fromRuntimeDir(resolve(explicit));
+    if (r === null) throw new Error(`runtimeDir ${explicit} must contain holon.wasm, manifests.json and packages.json (the ~/.holon/runtime cache shape)`);
+    return r;
+  }
+  const repo = fromHolonHost();
+  if (repo !== null) return repo;
+  const cached = fromRuntimeDir(cacheRoot());
+  if (cached !== null) return cached;
+  const offline = opts.offline === true || process.env.GITHOLON_TESTING_OFFLINE !== undefined;
+  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); ` +
+      `(c) warm the shared cache once while online (any testHolon() run, or \`githolon ledger verify\`, populates ${cacheRoot()}).`,
+    );
+  }
+  return fromCloud(cloudBase(opts.cloud), cacheRoot());
+}
+
+function loadRuntime(opts) {
+  const key = JSON.stringify([opts.runtimeDir ?? process.env.GITHOLON_RUNTIME_DIR ?? null, opts.cloud ?? null, opts.offline === true]);
+  let p = runtimeMemo.get(key);
+  if (p === undefined) {
+    p = (async () => {
+      const r = await resolveRuntime(opts);
+      return { ...r, wasmModule: await WebAssembly.compile(r.wasmBytes) };
+    })();
+    runtimeMemo.set(key, p);
+  }
+  return p;
+}
+
+// ── the law (a nomos-compile deploy body) ─────────────────────────────────────
+
+function loadBody(opts) {
+  if (opts.deploy !== undefined) {
+    const d = opts.deploy;
+    if (typeof d === "string") return JSON.parse(readFileSync(resolve(d), "utf8"));
+    if (d instanceof URL) return JSON.parse(readFileSync(d, "utf8"));
+    return d;
+  }
+  if (opts.law !== undefined) {
+    return {
+      packageUsda: opts.law,
+      readManifest: opts.manifests?.readManifest,
+      identityManifests: opts.manifests?.identityManifests,
+    };
+  }
+  throw new Error("testHolon needs law: pass { deploy: './build/<name>.deploy.json' } (the nomos-compile output) or { law: usdaText, manifests }");
+}
+
+/** Baked ∪ overlay manifest strings — the lean twin of the worker's `_mergeManifests`
+ *  (LAST DEPLOY WINS per read-declaration id — the law-upgrade overlay rule). */
+function mergeManifests(baked, deployBody) {
+  const read = JSON.parse(baked.read);
+  const identity = JSON.parse(baked.identity);
+  for (const [k, v] of Object.entries(deployBody?.identityManifests ?? {})) identity[k] = v;
+  const r = deployBody?.readManifest;
+  if (r !== undefined) {
+    for (const [t, schema] of Object.entries(r.aggregateFieldKinds ?? {})) read.aggregateFieldKinds[t] = schema;
+    for (const key of ["queries", "counts", "sums", "mins", "maxes", "spatials", "deriveds", "combineds"]) {
+      for (const d of r[key] ?? []) {
+        const list = (read[key] = read[key] ?? []);
+        const scoped = key === "deriveds" || key === "combineds";
+        const at = list.findIndex((x) => x.id === d.id && (!scoped || x.of === d.of));
+        if (at >= 0) list[at] = d;
+        else list.push(d);
+      }
+    }
+  }
+  return { read: JSON.stringify(read), identity: JSON.stringify(identity) };
+}
+
+// ── deterministic ports (clock + rng) ─────────────────────────────────────────
+//
+// A plan is a pure function of (payload, ports); the HOST stamps the captured
+// clock (Date.now()) and rng (crypto.getRandomValues) onto the intent envelope.
+// For reproducible tests we pin BOTH at the host boundary, scoped to the
+// synchronous author call — the engine itself is untouched.
+
+const toMs = (v) => (typeof v === "number" ? v : Date.parse(v));
+
+function normalizeClock(c) {
+  if (c === undefined || c === null) return null;
+  if (typeof c === "function") return { fn: c };
+  if (typeof c === "object") return { cursor: toMs(c.start ?? "2026-01-01T00:00:00.000Z"), step: c.stepMs ?? 1000 };
+  return { cursor: toMs(c), step: 1000 };
+}
+
+const cloneClock = (c) => (c === null ? null : c.fn !== undefined ? { fn: c.fn } : { cursor: c.cursor, step: c.step });
+
+function nextNow(clock) {
+  if (clock.fn !== undefined) return toMs(clock.fn());
+  const t = clock.cursor;
+  clock.cursor += clock.step;
+  return t;
+}
+
+// mulberry32 — a tiny, well-distributed seeded PRNG; state is a plain number so
+// fork() clones it and a forked holon stays reproducible.
+function nextFloat(rng) {
+  rng.state = (rng.state + 0x6d2b79f5) | 0;
+  let t = Math.imul(rng.state ^ (rng.state >>> 15), 1 | rng.state);
+  t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+  return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+}
+
+function withPorts({ nowMs, rng }, fn) {
+  if (nowMs === null && rng === null) return fn();
+  const realNow = Date.now;
+  const realCrypto = globalThis.crypto;
+  if (nowMs !== null) Date.now = () => nowMs;
+  if (rng !== null) {
+    const fake = {
+      getRandomValues(arr) {
+        const bytes = new Uint8Array(arr.buffer, arr.byteOffset, arr.byteLength);
+        for (let i = 0; i < bytes.length; i++) bytes[i] = (nextFloat(rng) * 256) | 0;
+        return arr;
+      },
+      subtle: realCrypto.subtle,
+      randomUUID: realCrypto.randomUUID?.bind(realCrypto),
+    };
+    Object.defineProperty(globalThis, "crypto", { value: fake, configurable: true, enumerable: true });
+  }
+  try {
+    return fn();
+  } finally {
+    Date.now = realNow;
+    Object.defineProperty(globalThis, "crypto", { value: realCrypto, configurable: true, enumerable: true });
+  }
+}
+
+const MASK63 = (1n << 63n) - 1n;
+const randomReplica = () => {
+  const b = new Uint8Array(8);
+  globalThis.crypto.getRandomValues(b);
+  let v = 0n;
+  for (const x of b) v = (v << 8n) | BigInt(x);
+  return v & MASK63;
+};
+
+// ── the holon ─────────────────────────────────────────────────────────────────
+
+class TestHolon {
+  /** @internal */
+  constructor(internal) {
+    this._eng = internal.eng;
+    this._bootCfg = internal.bootCfg; // {wasmModule, bootstrapPkg, nomosPkg, manifestStrings, installedBy}
+    this._chain = internal.chain;
+    this._clock = internal.clock;
+    this._rng = internal.rng;
+    this._forkSeq = 0;
+    /** This holon's replica id (rides every intent's captured clock). */
+    this.replica = internal.replica;
+    /** sha256 of the installed law package — the content-addressed law id. */
+    this.lawHash = internal.lawHash;
+  }
+
+  /** The raw engine handle (the vendored engine plane) — the escape hatch. */
+  get engine() {
+    return this._eng;
+  }
+
+  /** The in-engine workspace name reads/authors bind to. */
+  get workspace() {
+    return WS;
+  }
+
+  _author(domain, directiveId, payload, controllerHash, o = {}) {
+    const nowMs = o.at !== undefined ? toMs(o.at) : this._clock !== null ? nextNow(this._clock) : null;
+    const res = withPorts({ nowMs, rng: this._rng }, () =>
+      author(this._eng, WS, domain, directiveId, payload, controllerHash, o.rngDraws !== undefined ? { rngDraws: o.rngDraws } : {}),
+    );
+    if (res.ok !== true) throw new Refusal(res.error ?? JSON.stringify(res), { domain, directiveId });
+    const bytes = dec.decode(this._eng.preopen.dir.contents.get("ws").contents.get(WS).contents.get(res.intentOut).data);
+    this._chain.push(bytes);
+    warmEngine(this._eng);
+    const intent = JSON.parse(bytes);
+    const created = (intent.events ?? []).filter((e) => e.marker === "Create").map((e) => e.aggregate);
+    return { head: res.head, id: created[0] ?? null, created, intent };
+  }
+
+  /**
+   * Author ONE intent through the real gate (payload zod → plan re-run →
+   * invariant oracle → kernel fold → sealed onto the chain). Resolves with
+   * `{ head, id, created, intent }` (`id` = the first minted aggregate id —
+   * callers never supply ids) or REJECTS with a typed {@link Refusal}.
+   *
+   * opts: `{ at }` pins this intent's captured clock (ISO or ms);
+   * `{ rngDraws }` raises the captured-entropy budget for BATCH-creating plans
+   * (19 draws per minted id; the default 64 covers 3 mints).
+   */
+  async dispatch(domain, directiveId, payload, opts = {}) {
+    return this._author(domain, directiveId, payload, this.lawHash, opts);
+  }
+
+  /** All projected rows for one aggregate id (`[{ id, data }]`; partial folds are normal). */
+  byId(aggregateId) {
+    return qById(this._eng, WS, aggregateId);
+  }
+
+  /** A declared query (`query("…").key(…)`) — an indexed probe, never a scan. */
+  query(queryId, params = {}) {
+    return engineQuery(this._eng, WS, queryId, JSON.stringify(params));
+  }
+
+  /** A maintained count tally (O(1)); returns the number. */
+  count(countId, group = "") {
+    const r = engineCount(this._eng, WS, countId, group);
+    return r.count ?? r;
+  }
+
+  /** A maintained sum tally (O(1)); returns the number. */
+  sum(sumId, group = "") {
+    const r = engineSum(this._eng, WS, sumId, group);
+    return r.sum ?? r;
+  }
+
+  /** A maintained min/max read; `kind` = "min" | "max". Absent group ⇒ null. */
+  extremum(extremumId, kind, group = "") {
+    const r = engineExtremum(this._eng, WS, extremumId, kind, group);
+    return r.value ?? r;
+  }
+
+  /** The chain so far, parsed — genesis installs first, then every dispatch. */
+  intents() {
+    return this._chain.map((s) => JSON.parse(s));
+  }
+
+  /**
+   * The verdict of the SAME wasm `verify_chain` gate the cloud runs on an
+   * upload birth: contiguity → every intent re-admitted against the state
+   * folded from the chain prefix, every resolvable plan re-run and
+   * byte-compared. `{ valid: true, … }` or the refusing check + index.
+   */
+  verify() {
+    return verifyChainLocal(this._eng, WS);
+  }
+
+  /**
+   * A cheap what-if branch: a FRESH engine cold-mounting this holon's exact
+   * tree bytes (the same cold-fold path a restoring peer runs). Dispatches on
+   * the fork never touch the parent. The fork inherits law hash, chain, and a
+   * CLONE of the deterministic clock/rng state; its replica is derived
+   * (parent + fork ordinal) unless `opts.replica` pins it.
+   */
+  async fork(opts = {}) {
+    const bytes = snapshot(this._eng, WS);
+    const replica = (opts.replica !== undefined ? BigInt(opts.replica) : this.replica + BigInt(++this._forkSeq)) & MASK63;
+    const eng = await createEngine({ ...this._bootCfg, replica });
+    await mountWorkspace(eng, WS, UNBORN);
+    const wsRoot = eng.preopen.dir.contents.get("ws");
+    const template = wsRoot.contents.get(WS);
+    const Directory = template.constructor;
+    const File = template.contents.get("domain_manifests.json").constructor;
+    wsRoot.contents.set(WS, new Directory(deserializeTree(bytes, { File, Directory })));
+    return new TestHolon({
+      eng,
+      bootCfg: this._bootCfg,
+      replica,
+      lawHash: this.lawHash,
+      chain: [...this._chain],
+      clock: cloneClock(this._clock),
+      rng: this._rng === null ? null : { state: this._rng.state },
+    });
+  }
+}
+
+/**
+ * Boot a law-under-test holon: the real engine plane, your compiled law
+ * installed at genesis, fully offline (see the runtime resolution order above).
+ *
+ * @param {object} opts
+ *   deploy        path/URL/object of the nomos-compile `<name>.deploy.json`
+ *   law,manifests alternative: raw package USDA text (+ optional manifests)
+ *   deterministic true ⇒ pinned clock (2026-01-01, +1s/intent), seed 42, replica 7
+ *   clock         ISO/ms (start, +1s per intent) | {start, stepMs} | () => now
+ *   seed          number ⇒ seeded captured rng (minted ids reproduce run-to-run)
+ *   replica       pin the 63-bit replica id (defaults: seed-derived, else random)
+ *   installedBy   the principal stamped on the genesis installs (default "law-test")
+ *   runtimeDir / cloud / offline   runtime acquisition (see module docs)
+ */
+export async function testHolon(opts = {}) {
+  const body = loadBody(opts);
+  const runtime = await loadRuntime(opts);
+  const det = opts.deterministic === true;
+  const clock = normalizeClock(opts.clock ?? (det ? { start: "2026-01-01T00:00:00.000Z", stepMs: 1000 } : null));
+  const seed = opts.seed ?? (det ? 42 : undefined);
+  const rng = seed === undefined ? null : { state: seed >>> 0 };
+  const replica =
+    opts.replica !== undefined ? BigInt(opts.replica) & MASK63
+    : det ? 7n
+    : seed !== undefined ? (1000n + BigInt(seed >>> 0)) & MASK63
+    : randomReplica();
+  const installedBy = opts.installedBy ?? "law-test";
+  const bootCfg = {
+    wasmModule: runtime.wasmModule,
+    bootstrapPkg: runtime.bootstrapPkg,
+    nomosPkg: runtime.nomosPkg,
+    manifestStrings: mergeManifests(runtime.baked, body),
+    installedBy,
+  };
+  const eng = await createEngine({ ...bootCfg, replica });
+  await mountWorkspace(eng, WS, UNBORN);
+  const h = new TestHolon({ eng, bootCfg, replica, lawHash: null, chain: [], clock, rng });
+  // Genesis: bootstrap installs the nomos controller; then YOUR law under it.
+  h._author("bootstrap", "installDomain", installPayload(eng.hashes.nomos, runtime.nomosPkg, installedBy), "");
+  h.lawHash = await sha256hex(body.packageUsda);
+  h._author("nomos", "installDomain", installPayload(h.lawHash, body.packageUsda, installedBy), eng.hashes.nomos);
+  return h;
+}