@githolon/testing

中文文档
0.122.2发布于 2026/11/11SEE LICENSE IN LICENSE.mdTypeScriptES Module近 30 天下载 2726

@githolon/testing — law TDD through the same Runtime v2 Peer Office used by every Nomos platform shell.

原始使用文档
文档目录4 节
  1. The surface
  2. Deterministic clock & rng
  3. Recipes
  4. How the runtime arrives (the wasm story, honestly)

@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.

版本与发布记录

@githolon/testing 共发布 266 个版本,首次发布于 2026/06/12;过去 12 个月发布了 266 个版本。

版本发布日期距今
0.122.2latest2026/11/115 天前
0.119.392026/10/2323 天前
0.119.382026/10/2323 天前
0.119.372026/10/2324 天前
0.119.362026/10/2324 天前
0.119.352026/10/2324 天前

关于 @githolon/testing 的常见问题

@githolon/testing 是什么?

@githolon/testing — law TDD through the same Runtime v2 Peer Office used by every Nomos platform shell.

如何安装 @githolon/testing?

在项目目录运行 npm install @githolon/testing,或使用 pnpm add / yarn add / bun add。

@githolon/testing 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@githolon/testing 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@githolon/testing 可以商用吗?

@githolon/testing 使用 SEE LICENSE IN LICENSE.md 许可。许可条款写在包内的独立文件中,请阅读该文件确认可否商用。以上为概括,不构成法律意见,请以许可原文为准。

@githolon/testing 的下载量有多少?

根据 npm 官方下载统计,@githolon/testing 在 2026/10/17 – 2026/11/15 这 30 天内被下载 2,726 次,日均约 91 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@githolon/testing 还在维护吗?

最新版本 0.122.2 发布于 2026/11/11(5 天前);至今共发布 266 个版本,其中过去 12 个月发布了 266 个;首次发布于 2026/06/12。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。