@githolon/testing 0.3.0

package/LICENSE.md

@@ -0,0 +1,45 @@
+# 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-githolon` / `githolon 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.
+
+## Data retention
+
+This is a pre-release we are actively evaluating. Workspaces you retire stop
+counting toward your quota but are NOT deleted: **we retain all workspace data
+(ledgers, law, intents) and may examine it to evaluate how the product is
+used.** Don't put anything in a pre-release workspace you wouldn't want the
+builders to read. If you need something truly expunged, ask:
+jack@captainapp.co.uk.
+
+## 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/README.md

@@ -0,0 +1,159 @@
+# @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
+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
+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.
+
+```bash
+npm i -D @githolon/testing vitest
+npx nomos-compile    # your law → build/<name>.deploy.json
+```
+
+```ts
+import { describe, expect, it } from "vitest";
+import { testHolon } from "@githolon/testing";
+
+it("the law refuses an over-capacity booking", async () => {
+  const h = await testHolon({ deploy: "./build/seats.deploy.json", deterministic: true });
+  const b = await h.dispatch("seats", "openBooking", { label: "launch", capacity: 2 });
+  await h.dispatch("seats", "takeSeat", { bookingId: b.id, attendee: "ada", takenAt: T });
+  await h.dispatch("seats", "takeSeat", { bookingId: b.id, attendee: "bob", takenAt: T });
+
+  // THE HEADLINE — invariants are real law; the refusal carries the law's own reject code:
+  await expect(
+    h.dispatch("seats", "takeSeat", { bookingId: b.id, attendee: "eve", takenAt: T }),
+  ).rejects.toThrow(/seats-exceed-capacity/);
+});
+```
+
+## The surface
+
+```ts
+const h = await testHolon({
+  deploy: "./build/<name>.deploy.json", // the nomos-compile output (path, URL or object)
+  // or: law: usdaText, manifests: { readManifest, identityManifests }
+  deterministic: true,                  // pinned clock + seeded rng + fixed replica (below)
+});
+
+await h.dispatch(domain, directiveId, payload, { at?, rngDraws? });
+//   → { head, id, created, intent }   (id = the first minted aggregate id)
+//   → throws Refusal — message carries the gate's verdict VERBATIM, so
+//     expect(...).rejects.toThrow(/your-reject-code/) asserts the law
+
+h.byId(id);                 // [{ id, data }] — projected rows (partial folds are normal)
+h.query(queryId, params);   // a declared query — indexed probe, never a scan
+h.count(countId, group);    // maintained O(1) tally → number
+h.sum(sumId, group);        // maintained O(1) sum → number
+h.extremum(id, "min"|"max", group);
+
+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
+h.lawHash;                  // sha256(package bytes) — the content-addressed law id
+```
+
+`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):
+
+```ts
+// the shorthand: clock 2026-01-01 advancing +1s/intent, seed 42, replica 7
+const h = await testHolon({ deploy, deterministic: true });
+
+// or granular:
+const h = await testHolon({
+  deploy,
+  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 h.dispatch(d, id, p, { at: "2026-03-01T09:00:00.000Z" }); // pin ONE intent's clock
+```
+
+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):
+
+```ts
+await expect(h.dispatch("seats", "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:
+
+```ts
+await h.dispatch("guestbook", "tagEntry", { entryId, tags: ["kind"] });
+await h.dispatch("guestbook", "tagEntry", { entryId, tags: ["warm", "kind"] });
+expect(h.byId(entryId)[0].data.tags).toEqual(["kind", "warm"]); // AddWins unions
+
+await h.dispatch("guestbook", "reactToEntry", { entryId, reactor: "bob", reaction: "👏", reactedAt });
+await h.dispatch("guestbook", "reactToEntry", { entryId, reactor: "bob", reaction: "💚", reactedAt: later });
+expect(h.byId(entryId)[0].data.reactions).toEqual({ bob: "💚" }); // MapOf(Lww): per-key last write
+```
+
+**Test a derived field** — engine-projected, never in the ledger:
+
+```ts
+const { id } = await h.dispatch("guestbook", "signGuestbook", { mood: "grumpy", ... });
+expect(h.byId(id)[0].data.moodEmoji).toBe("😠");                       // projected
+expect(JSON.stringify(h.intents().at(-1))).not.toContain("moodEmoji"); // never sealed
+```
+
+**What-if on a fork** — consequence-free branches:
+
+```ts
+const f = await h.fork();
+await expect(f.dispatch(...breachingWrite)).rejects.toThrow(/your-code/);
+await f.dispatch(...somethingElse);     // lands on the fork
+expect(h.byId(thatId)).toHaveLength(0); // the parent never saw it
+```
+
+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 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
+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
+   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`
+   run, or any prior `testHolon()` run, already warmed it.
+4. **The cloud** — one fetch of `/v1/runtime/{holon.wasm,manifests,packages}`
+   from `https://nomos.captainapp.co.uk` (`cloud` option / `NOMOS_CLOUD`
+   override), written into the cache. Every run after is offline.
+
+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. The wasm in
+the cache is the cloud's own deployed artifact: byte-identical machinery,
+which is the point.

package/build.mjs

@@ -0,0 +1,23 @@
+// Vendor THE ENGINE PLANE (cloud/holon-host/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
+// published package ships the vendored copies and skips the sync when the
+// monorepo source is absent.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+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 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");
+  }
+} else if (!existsSync(join(VENDOR, "engine.mjs"))) {
+  throw new Error("engine plane not found: neither ../cloud/holon-host/src nor vendor/engine exists");
+}

package/index.d.ts

@@ -0,0 +1,142 @@
+// @githolon/testing — the typed surface (see README.md for the vitest recipes).
+
+/** A projected read-model row. Every field is partial — partial folds are normal. */
+export interface Row<T = Record<string, unknown>> {
+  type?: string;
+  id: string;
+  data: Partial<T>;
+}
+
+/** What a successful dispatch resolves with. */
+export interface DispatchResult {
+  /** The new chain head (a git commit oid). */
+  head: string;
+  /** The FIRST aggregate id this intent minted, or null (callers never supply ids). */
+  id: string | null;
+  /** Every aggregate id this intent minted (batch-creating plans mint many). */
+  created: string[];
+  /** The sealed chain entry, parsed. */
+  intent: Record<string, unknown>;
+}
+
+export interface DispatchOptions {
+  /** Pin THIS intent's captured clock (ISO string or epoch ms). */
+  at?: string | number;
+  /**
+   * The captured-entropy budget the plan may consume (19 draws per minted id;
+   * default 64 covers 3 mints). Raise it for batch-creating directives —
+   * commit-only-consumed: only the consumed prefix is sealed.
+   */
+  rngDraws?: number;
+}
+
+/**
+ * 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 declare class Refusal extends Error {
+  name: "Refusal";
+  domain: string;
+  directiveId: string;
+  /** The gate's verdict, verbatim. */
+  refusal: string;
+}
+
+/** The wasm verify_chain verdict — the same gate the cloud runs on an upload birth. */
+export interface Verdict {
+  valid: boolean;
+  head?: string;
+  intents?: number;
+  plansRerun?: number;
+  controllerHash?: string;
+  installedDomains?: string[];
+  /** On an invalid chain: the refusing check + index + error. */
+  check?: string;
+  atIndex?: number;
+  error?: string;
+  [k: string]: unknown;
+}
+
+export interface DeployBody {
+  packageUsda: string;
+  readManifest?: Record<string, unknown>;
+  identityManifests?: Record<string, string>;
+}
+
+export type ClockOption =
+  | string
+  | number
+  | { start?: string | number; stepMs?: number }
+  | (() => string | number);
+
+export interface TestHolonOptions {
+  /** Path / URL / parsed object of the nomos-compile `<name>.deploy.json`. */
+  deploy?: string | URL | DeployBody;
+  /** Alternative to `deploy`: the raw package USDA text… */
+  law?: string;
+  /** …plus its manifests (omit and declared queries/derived fields won't route). */
+  manifests?: { readManifest?: Record<string, unknown>; identityManifests?: Record<string, string> };
+  /** true ⇒ pinned clock (2026-01-01, +1s per intent), seed 42, replica 7 — full reproducibility. */
+  deterministic?: boolean;
+  /** Pin the captured clock: a start (ISO/ms, advancing +1s per intent), {start, stepMs}, or a function. */
+  clock?: ClockOption;
+  /** Seed the captured rng — minted ids reproduce run-to-run. */
+  seed?: number;
+  /** Pin the 63-bit replica id (defaults: 7 under `deterministic`, seed-derived under `seed`, else random). */
+  replica?: number | bigint;
+  /** The principal stamped on the genesis installs (default "law-test"). */
+  installedBy?: string;
+  /** Runtime acquisition (see README): a dir holding {holon.wasm, manifests.json, packages.json}. */
+  runtimeDir?: string;
+  /** The cloud to fetch runtime artifacts from on first use (default https://nomos.captainapp.co.uk). */
+  cloud?: string;
+  /** Forbid the network fallback — fail with the offline story instead of fetching. */
+  offline?: boolean;
+}
+
+export interface TestHolon {
+  /** sha256(package bytes) of the installed law — the content-addressed law id. */
+  readonly lawHash: string;
+  /** This holon's 63-bit replica id (rides every intent's captured clock). */
+  readonly replica: bigint;
+  /** The in-engine workspace name reads/authors bind to. */
+  readonly workspace: string;
+  /** The raw engine handle (the vendored engine plane) — the escape hatch. */
+  readonly engine: unknown;
+
+  /**
+   * Author ONE intent through the real gate (payload zod → plan re-run →
+   * invariant oracle → kernel fold → sealed onto the chain). Resolves with the
+   * result or REJECTS with a typed {@link Refusal}.
+   */
+  dispatch(domain: string, directiveId: string, payload: unknown, opts?: DispatchOptions): Promise<DispatchResult>;
+
+  /** All projected rows for one aggregate id. */
+  byId<T = Record<string, unknown>>(aggregateId: string): Row<T>[];
+  /** A declared query — an indexed probe, never a scan. */
+  query<T = Record<string, unknown>>(queryId: string, params?: Record<string, unknown>): Row<T>[];
+  /** A maintained count tally (O(1)). */
+  count(countId: string, group?: string): number;
+  /** A maintained sum tally (O(1)). */
+  sum(sumId: string, group?: string): number;
+  /** A maintained min/max read; absent group ⇒ null. */
+  extremum(extremumId: string, kind: "min" | "max", group?: string): number | null;
+
+  /** The chain so far, parsed — genesis installs first, then every dispatch. */
+  intents(): Record<string, unknown>[];
+  /** The wasm verify_chain verdict over this holon's chain (the cloud's gate). */
+  verify(): Verdict;
+  /**
+   * A cheap what-if branch: a fresh engine cold-mounting this holon's exact
+   * tree bytes. Dispatches on the fork never touch the parent.
+   */
+  fork(opts?: { replica?: number | bigint }): Promise<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
+ * installed at genesis, fully offline after the one-time runtime acquisition.
+ */
+export declare function testHolon(opts?: TestHolonOptions): Promise<TestHolon>;

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@githolon/testing",
+  "version": "0.3.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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Captain-App/nomos2.git",
+    "directory": "testing"
+  },
+  "main": "./src/index.mjs",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./src/index.mjs"
+    }
+  },
+  "files": [
+    "src",
+    "vendor",
+    "index.d.ts",
+    "README.md",
+    "LICENSE.md",
+    "build.mjs"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "prepare": "npm run build",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@bjorn3/browser_wasi_shim": "0.4.2",
+    "isomorphic-git": "^1.38.4"
+  },
+  "devDependencies": {
+    "vitest": "^2.1.8"
+  }
+}