@githolon/testing — law TDD for Nomos domains

Test your law the way any peer judges it. testHolon() boots the canonical Peer Office in-process with the Node local-development Platform Shell over the one wasm32-wasip1 kernel artifact — the same lifecycle used by every platform — installs your compiled law at genesis, and hands you a holon you drive from vitest through the compiler-generated Reception (build/<name>.reception.mjs). Nothing is simulated: every generated call runs the real author gate (payload zod → plan re-run → invariant oracle → kernel fold → sealed onto the chain), and verify() is the same wasm verify_chain the cloud runs on an upload birth.

npm i -D @githolon/testing vitest
npx nomos-compile    # your canonical law → build/<name>.law.usdz

import { describe, expect, it } from "vitest";
import { testHolon } from "@githolon/testing";
import { seatsClient } from "./build/seats.reception.mjs";

it("the law refuses an over-capacity booking", async () => {
  const h = await testHolon({ law: "./build/seats.law.usdz", deterministic: true });
  const app = h.app(seatsClient, { actor: "person:alice" });
  const b = await app.openBooking({ label: "launch", capacity: 2 });
  await app.takeSeat({ bookingId: b.booking, attendee: "ada", takenAt: T });
  await app.takeSeat({ bookingId: b.booking, attendee: "bob", takenAt: T });

  // THE HEADLINE — invariants are real law; the refusal carries the law's own reject code:
  await expect(
    app.takeSeat({ bookingId: b.booking, attendee: "eve", takenAt: T }),
  ).rejects.toThrow(/seats-exceed-capacity/);
});

The surface

const h = await testHolon({
  law: "./build/<name>.law.usdz", // opaque canonical archive; the kernel composes and identifies it
  deterministic: true,                  // pinned clock + seeded rng + fixed replica (below)
});
const app = h.app(generatedClient, { actor: "person:alice" });

await app.someBusinessAction(typedPayload); // compiler-generated payload, result and USDA codec
await app.someDeclaredQuestion(typedParams); // compiler-generated nominal query + typed decoder

h.intents();                // the chain, parsed — genesis installs first, then every dispatch
h.verify();                 // the wasm verify_chain verdict (the cloud's upload-birth gate)
await h.fork();             // a cheap what-if branch — a fresh engine cold-mounting the
                            // exact tree bytes; fork dispatches never touch the parent
await h.device();           // another offline device starting from this exact state
await h.sync(peer);         // idempotent exchange; conflicts remain typed domain data
await h.restart();          // cold rebuild from ledger history, never a trusted snapshot
h.lawHash;                  // sha256(package bytes) — the content-addressed law id
h.kernelSha256;             // exact provider-selected kernel fetched, verified and cached by digest

Refusal is typed: { name: "Refusal", domain, directiveId, refusal } with the verdict verbatim in message — payload-schema refusals, missing instances and declared invariants all arrive through the same lane, exactly as on the edge.

Deterministic clock & rng

A plan is a pure function of (payload, ports); the HOST stamps the captured clock and rng onto each intent's envelope. The harness pins both at that host boundary (scoped to the synchronous author call — the engine is untouched):

// the shorthand: clock 2026-01-01 advancing +1s/intent, seed 42, replica 7
const h = await testHolon({ law, deterministic: true });

// or granular:
const h = await testHolon({
  law,
  clock: { start: "2026-01-01T00:00:00.000Z", stepMs: 1000 }, // or an ISO/ms start, or () => now
  seed: 7,        // minted ids reproduce run-to-run
  replica: 99,    // the 63-bit replica id on every captured clock
});

await app.someBusinessAction(payload);

Same seed + clock + replica ⇒ byte-identical history: the same minted ids, the same chain head, run after run. (Remember: domain timestamps still ride IN your payloads as ISO strings — the captured clock is the envelope's, not your law's.)

Recipes

Test an invariant (real since the invariant gate landed — declared invariants execute at author, admission AND verify):

await expect(app.takeSeat(overCapacityPayload))
  .rejects.toThrow(/seats-exceed-capacity/);
expect(h.intents().length).toBe(before);   // a refusal commits NOTHING
expect(h.verify().valid).toBe(true);       // the chain stays green

Test a merge driver — the merge IS the law:

await app.tagEntry({ entry: entry.ref, tags: ["kind"] });
await app.tagEntry({ entry: entry.ref, tags: ["warm", "kind"] });
expect((await app.entries.find(entry.ref)).tags).toEqual(["kind", "warm"]); // AddWins unions

await app.reactToEntry({ entry: entry.ref, reactor: "bob", reaction: "👏", reactedAt });
await app.reactToEntry({ entry: entry.ref, reactor: "bob", reaction: "💚", reactedAt: later });
expect((await app.entries.find(entry.ref)).reactions).toEqual({ bob: "💚" }); // MapOf(Lww)

Test a derived field — engine-projected, never in the ledger:

const { entry } = await app.signGuestbook({ mood: "grumpy", ... });
expect((await app.entries.find(entry)).moodEmoji).toBe("😠");          // projected
expect(JSON.stringify(h.intents().at(-1))).not.toContain("moodEmoji"); // never sealed

What-if on a fork — consequence-free branches:

const f = await h.fork();
const forkApp = f.app(generatedClient);
await expect(forkApp.breachingWrite(payload)).rejects.toThrow(/your-code/);
await forkApp.somethingElse(payload); // lands on the fork; parent app remains unchanged

A generated facade across two offline devices — no kernel, intent or workspace plumbing in the tenant test:

import { co2Client } from "../build/co2.reception";

const alice = await testHolon({ law: "./build/co2.law.usdz", deterministic: true });
const aliceApp = alice.app(co2Client, { actor: "person:alice" });
await aliceApp.addSite({ estateId, name: "Trafford Depot" });

const bob = await alice.device();
const bobApp = bob.app(co2Client, { actor: "person:bob" });
await aliceApp.mergeAssetStatus({ assetId, operationalStatus: "operational" });
await bobApp.mergeAssetStatus({ assetId, operationalStatus: "inspection-due" });

await alice.sync(bob);
const [conflict] = await aliceApp.conflicts.asset.pending();
await conflict.merge(() => "operational-after-inspection");

const restarted = await alice.restart();
expect(restarted.verify().valid).toBe(true);

Worked examples: this package's own suite (test/harness.test.mjs, the seats fixture) and the guestbook example's law tests (examples/guestbook/test/law.test.mts).

How the runtime arrives (the wasm story, honestly)

The Node Platform Shell and canonical Peer Office are bundled into this package at build from their source modules. The release carries only the production kernel's SHA-256 descriptor—not the proprietary executable. The wasm and public bootstrap/nomos law packages resolve, first hit wins:

1. runtimeDir option / NOMOS_OFFLINE_RUNTIME (or the testing-only GITHOLON_RUNTIME_DIR) — a directory you control holding {holon.wasm, bootstrap.law.usdz, nomos.law.usdz}. The wasm must match this package's pinned release digest. Pin this directory in CI for fully hermetic runs.
2. The monorepo — inside the nomos2 repo, cloud/cloudflare-shell's vendored wasm + domain artifacts are used directly. Never any network.
3. The release cache — ~/.holon/runtime/kernels/<release-sha> (HOLON_CONFIG_DIR overrides).
4. The cloud — one fetch of the immutable /v1/runtime/kernels/<release-sha>/holon.wasm plus the public framework packages from https://nomos.cafe (cloud option / NOMOS_CLOUD override). Nomos verifies the bytes before caching them.

Every lane but the monorepo verifies the kernel's SIGNATURE before WebAssembly starts (CAP-813): the provider serves a DSSE attestation of the kernel (/v1/runtime/kernels/<sha>/attestation.dsse.json) and the release-key certificate set (/v1/runtime/kernel-release-key.certificate.dsse.json); they are verified against the trust root this package pins and cached beside the kernel as kernel.attestation.dsse.json and kernel-release-key.certificate.dsse.json. A runtimeDir must carry both files too. An unsigned, foreign or expired kernel is refused with a typed KernelAttestationRefused naming the failed link. A kernel you built yourself runs only under the explicit local-development opt-in NOMOS_LOCAL_DEV_KERNEL_TRUST_ROOT=<your local-dev root> (printed by the tools that sign one), which the harness announces on stderr every time.

So: the FIRST run on a fresh machine outside the monorepo needs the network once. offline: true (or GITHOLON_TESTING_OFFLINE=1) forbids lane 4 — you get a clear error naming your options instead of a surprise fetch. A stale or different kernel is refused before WebAssembly starts.