@githolon/testing 0.17.0 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/testing",
-  "version": "0.17.0",
+  "version": "0.18.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/vendor/engine/engine.mjs

@@ -1001,6 +1001,9 @@ export async function admitIntentOffers(eng, ws, ledger, offers, { refuseDomains
   const sessions = new Map();
   const deadLetters = [];
   let admittedTotal = 0;
+  // BORN: the G3 birth offer-effect's child heads any `.births()` offer in this batch produced (the kernel
+  // surfaced them on the admit verdict). Accumulated across the batch and relayed out for the host to persist.
+  const born = [];
   const timings = { spans: [], intents: 0, sessions: 0 };
   // THE §5.2 SUMMARY CAPTURE on the OFFER LANE (offers are the only source of intents — this lane is the one
   // admit, routed workspaces included). A shard (selfLabel set) with scoped reads captures the per-batch
@@ -1080,6 +1083,7 @@ export async function admitIntentOffers(eng, ws, ledger, offers, { refuseDomains
         main.oids.add(res.head); main.head = res.head;
         rec.admitted.push({ oid, head: res.head });
         admittedTotal += 1;
+        if (Array.isArray(res.born) && res.born.length) born.push(...res.born);
         if (cap) finishSummaryCapture(eng, ws, summaryCtx, cap, res.head, intentId);
       } else {
         const error = `${String(res.error || "").slice(0, 300)} — dead-lettered; fix the law (or the payload), then POST /v1/workspaces/${ws}/dead-letters/retry`;
@@ -1133,7 +1137,7 @@ export async function admitIntentOffers(eng, ws, ledger, offers, { refuseDomains
     } catch { /* fall back to the client's own GET /pack */ }
   }
   log("admit-intent-offers", { ws, sessions: sessions.size, admitted: admittedTotal, rejected: [...sessions.values()].reduce((n, s) => n + s.rejected.length, 0), resultPack: resultPackB64 ? "inline" : "none" });
-  return { sessions: [...sessions.values()].map((s) => ({ ...s, ...(s.skipped.length ? {} : { skipped: undefined }) })), main: head, deadLetters, timings, ...(summary ? { summary } : {}), ...(resultPackB64 ? { resultPackB64, resultBase: clientBase } : {}), ...(deferDurability && admittedTotal && head ? { deferred: true, head } : {}) };
+  return { sessions: [...sessions.values()].map((s) => ({ ...s, ...(s.skipped.length ? {} : { skipped: undefined }) })), main: head, deadLetters, timings, ...(summary ? { summary } : {}), ...(born.length ? { born } : {}), ...(resultPackB64 ? { resultPackB64, resultBase: clientBase } : {}), ...(deferDurability && admittedTotal && head ? { deferred: true, head } : {}) };
 }
 
 /**
@@ -1171,7 +1175,9 @@ export async function authorOn(eng, ws, ledger, domain, directiveId, payload, la
   }
   if (res && res.ok === false) return { ok: false, error: String(res.error || "the law refused this intent").slice(0, 500) };
   await commitAndPush(eng, ws, ledger);
-  return { ok: true, head: res.head };
+  // KEEP `born`: a `.births()` directive authored here ran the G3 birth offer-effect; surface the child
+  // heads so the container author case → worker out.born relays them (the host persists the child custody).
+  return { ok: true, head: res.head, ...(res.born ? { born: res.born } : {}) };
 }
 
 /**
@@ -1378,7 +1384,22 @@ export function author(eng, ws, domain, directiveId, payload, controllerHash, op
   // costs 19 draws — see NOMOS_API_SHIM). 64 is the per-write default (3 mints of slack);
   // a BATCH-creating directive needs 19×creates. COMMIT-ONLY-CONSUMED: only the consumed
   // prefix is sealed onto the intent, so a generous buffer is request weight, not ledger weight.
-  const envelope = { payload: { domain, directiveId, payload }, captured_ports: { clock: { physical: Date.now(), logical: 0, replica: eng.replica }, rng: osEntropyBuffer(opts.rngDraws ?? 64) }, policy_version: 1, policy_domain: "Nomos", policy_gas: 0, policy_memory: 0 };
+  // opts.validFromEpoch (VA Phase 4, TEST/ADVERSARIAL ONLY): force a CLAIMED signer epoch onto the
+  // captured ports. The author lane preserves a NON-ZERO carried value (it only auto-stamps the prefix
+  // epoch when 0) and signs over it (captured_ports ⊂ authored_core_bytes), so a smoke can mint a signed
+  // intent whose claim is a deliberate backdate/forward-date — the kernel's epoch arm must refuse it.
+  const capPorts = { clock: { physical: Date.now(), logical: 0, replica: eng.replica }, rng: osEntropyBuffer(opts.rngDraws ?? 64) };
+  if (opts.validFromEpoch !== undefined) capPorts.valid_from_epoch = opts.validFromEpoch;
+  // opts.principalVerified (VA — the verified-birth lane): stamp the offer's principal + verified verdict onto
+  // the captured ports, exactly as the cloud offer gate does from a verified AuthProvider token. The birthHome
+  // offer-effect reads `captured_ports.principal`/`principal_verified` as the GATE VERDICT and requires the
+  // device-signed homeCert's `verified` to MATCH it (CAS-as-law). A test driving the verified lane sets this
+  // so the kernel accepts a `verified:true` home cert; absent ⇒ the unverified lane (verified=false).
+  if (opts.principalVerified !== undefined) {
+    capPorts.principal = opts.actor ?? "";
+    capPorts.principal_verified = !!opts.principalVerified;
+  }
+  const envelope = { payload: { domain, directiveId, payload }, captured_ports: capPorts, policy_version: 1, policy_domain: "Nomos", policy_gas: 0, policy_memory: 0 };
   writeWork(eng, `payload-${seq}.json`, enc.encode(JSON.stringify(payload)));
   writeWork(eng, `envelope-${seq}.json`, enc.encode(stringifyBig(envelope)));
   const genesis = !controllerHash;
@@ -1398,14 +1419,36 @@ export function author(eng, ws, domain, directiveId, payload, controllerHash, op
   // DRY-RUN (offer-kernel): `offer` with the commit withheld — run the plan + full gate, get the verdict,
   // commit nothing. This is the home of the old `evolve_dryrun` verb (see `evolveDryRun`). Never defers
   // projection (no commit to flush).
-  const v = JSON.parse(call(eng.ex, "offer", { repoArg: repoArgOf(ws), workspace: ws, domain, directiveId, payloadFile: `/work/payload-${seq}.json`, envelopeFile: `/work/envelope-${seq}.json`, seq, actor: opts.actor ?? "", domainFile: genesis ? "/work/domain.package.usda" : "", domainHash: genesis ? "" : controllerHash, branch: BRANCH, ...(opts.authorSecret ? { authorSecret: opts.authorSecret } : {}), ...(opts.dryRun ? { dryRun: true } : (defer ? { deferProjection: true } : {})) }, eng.STDERR));
-  const res = v.outcome === "admitted" ? { ok: true, head: v.head, intentOut: v.intentOut }
+  const v = JSON.parse(call(eng.ex, "offer", { repoArg: repoArgOf(ws), workspace: ws, domain, directiveId, payloadFile: `/work/payload-${seq}.json`, envelopeFile: `/work/envelope-${seq}.json`, seq, actor: opts.actor ?? "", ...(opts.authToken ? { authToken: opts.authToken } : {}), domainFile: genesis ? "/work/domain.package.usda" : "", domainHash: genesis ? "" : controllerHash, branch: BRANCH, ...(opts.authorSecret ? { authorSecret: opts.authorSecret } : {}), ...(opts.dryRun ? { dryRun: true } : (defer ? { deferProjection: true } : {})) }, eng.STDERR));
+  // KEEP `born`: the wasm offer ran the G3 birth offer-effect and surfaced the child heads; thread them
+  // through the normalized shape so the relay (container author case → worker out.born) sees them.
+  const res = v.outcome === "admitted" ? { ok: true, head: v.head, intentOut: v.intentOut, ...(v.born ? { born: v.born } : {}) }
     : v.outcome === "refused" ? { ok: false, error: v.verdict?.reason ?? v.error }
     : v; // defensive: a non-verdict shape passes through unchanged
   if (defer && res.ok) (eng.pendingProjection ??= new Set()).add(ws);
   return res;
 }
 
+/** BIRTH SLICE 2 — the KERNEL produces the genesis. Fold a parent-authored genesis chain
+ *  (`[{domain,directiveId,payload,actor}]`) into `ws` in ONE atomic custody op (the kernel owns the fold;
+ *  the adapter delivered the opaque recipe + the impurity capability). `clockMs`/`rngSeed` are the
+ *  DETERMINISTIC injection — derive `rngSeed` per-birth-unique (e.g. from the child identity) so minted ids
+ *  never collide. Replaces the adapter's old per-step genesis-author loop. */
+export function materializeGenesis(eng, ws, genesisChain, opts = {}) {
+  return JSON.parse(call(eng.ex, "materialize_genesis", {
+    repoArg: repoArgOf(ws), workspace: ws, genesisChain,
+    clockMs: opts.clockMs ?? 1700000000000, replica: eng.replica, rngSeed: opts.rngSeed ?? 1,
+    branch: BRANCH,
+  }, eng.STDERR));
+}
+
+/** TEST/HARNESS-ONLY (the `test-mint` wasm): pin the root-of-trust anchor `K_root` to a public key the
+ *  harness controls, so a parent-attested-birth refusal can be driven THROUGH the real kernel verb against a
+ *  real test anchor. `kRootPublicB64` = base64 of the 32 raw ed25519 public-key bytes of the harness's S_root. */
+export function setTestKRoot(eng, kRootPublicB64) {
+  return JSON.parse(call(eng.ex, "set_test_k_root", { kRootPublicB64 }, eng.STDERR));
+}
+
 /** Catch one workspace's read projection up to head NOW (the deferred-ack flush). P3: rides the
  *  `query` verb (op:"refresh") — a non-effectful maintenance read, not a top-level adapter verb. */
 export function refreshProjection(eng, ws) {
@@ -1437,8 +1480,11 @@ export function exportCheckpoint(eng, ws) {
 /** Restore a checkpoint blob into the pool BEFORE the first read on a cold mount (no-op if the pool
  *  is already warm). The ADAPTER restores ONLY a blob whose stored lawHash matches the workspace's
  *  CURRENT law (schema parity); a mismatched/absent blob costs at most a cold fold, never a wrong read. */
-export function importCheckpoint(eng, ws, blobB64, frontierB64) {
-  return JSON.parse(call(eng.ex, "checkpoint_import", { repoArg: repoArgOf(ws), workspace: ws, branch: BRANCH, blob: blobB64, ...(frontierB64 ? { frontier: frontierB64 } : {}) }, eng.STDERR));
+export function importCheckpoint(eng, ws, blobB64, frontierB64, stateRoot) {
+  // `stateRoot` (the kernel's deterministic projection state-root stamped at export) is passed back so the
+  // kernel RE-DERIVES the restored blob's root and byte-compares — a corrupted/swapped blob is refused
+  // (restored:false), the caller cold-folds. Absent (a pre-this-era checkpoint) ⇒ no check, cold-fold fallback.
+  return JSON.parse(call(eng.ex, "checkpoint_import", { repoArg: repoArgOf(ws), workspace: ws, branch: BRANCH, blob: blobB64, ...(frontierB64 ? { frontier: frontierB64 } : {}), ...(stateRoot ? { stateRoot } : {}) }, eng.STDERR));
 }
 
 // ── CHECKPOINT IN CUSTODY (the adapter-agnostic cold-mount; compute placement is beneath the contract) ──
@@ -1478,19 +1524,27 @@ async function gunzip(bytes) {
  *  object layer is verifiable offline. */
 export async function writeCheckpointObjects(eng, ws, ex, lawHash) {
   const gitdir = gitdirOf(ws);
-  const gz = await gzip(enc.encode(ex.blob));
-  // THE FOLD FRONTIER (the gate's Workspace state @cursor) rides ALONGSIDE the projection so a cold mount
-  // can AUTHOR on a shallow clone (the projection alone is a read-collapsed view the gate can't fold from).
-  // Era-safe: pre-this-era exports carry no `ex.frontier`, so the `frontier` file is simply absent and a
-  // reader falls back to a full clone (writes need full history). Gzipped like the projection blob.
-  const files = [{ path: "checkpoint", bytes: gz }];
+  // THE CHECKPOINT IS THE VERIFIED FOLD: the kernel now emits ONLY `ex.frontier` (the fold), NOT a
+  // SQLite `ex.blob` (that image is non-deterministic). The host is a transparent byte-shuttle — it
+  // stores whatever the kernel returns; a legacy export still carrying `ex.blob` is shuttled too (the
+  // `checkpoint` file is absent when the kernel omits the blob). Gzipped.
+  const files = [];
+  let rawLen = 0, gzLen = 0;
+  if (ex.blob) {
+    const gz = await gzip(enc.encode(ex.blob));
+    rawLen = ex.blob.length; gzLen = gz.length;
+    files.push({ path: "checkpoint", bytes: gz });
+  }
+  // THE FOLD FRONTIER (the gate's Workspace state @cursor) IS the cold-mount artifact: a cold mount
+  // re-projects the read model from it (kernel-verified against the oid-pinned trailer) and AUTHORS
+  // forward on a shallow clone. Era-safe: an export without `ex.frontier` is shuttled as-is.
   let fgzLen = 0;
   if (ex.frontier) {
     const fgz = await gzip(enc.encode(ex.frontier));
     fgzLen = fgz.length;
     files.push({ path: "frontier", bytes: fgz });
   }
-  files.push({ path: "meta", bytes: enc.encode(JSON.stringify({ cursor: ex.cursor, bytes: ex.bytes ?? 0, lawHash, codec: "gzip", raw: ex.blob.length, stored: gz.length, frontierStored: fgzLen })) });
+  files.push({ path: "meta", bytes: enc.encode(JSON.stringify({ cursor: ex.cursor, bytes: ex.bytes ?? 0, lawHash, codec: "gzip", raw: rawLen, stored: gzLen, frontierStored: fgzLen, ...(ex.stateRoot ? { stateRoot: ex.stateRoot } : {}) })) });
   const ref = CKPT_REF(lawHash);
   // ONE kernel call: blobs→tree→parentless commit→force ref. Fixed timeSecs ⇒ deterministic (idempotent).
   const commitOid = kgit.writeMetaCommit(eng, gitdir, { parents: [], files, message: `checkpoint ${ws} @${String(ex.cursor).slice(0, 16)}`, timeSecs: 0, ref });
@@ -1503,13 +1557,17 @@ export async function writeCheckpointObjects(eng, ws, ex, lawHash) {
  *  pre-this-era checkpoint (no `frontier` file). */
 export async function readCheckpointBlob(eng, ws, commitOid) {
   const gitdir = gitdirOf(ws);
-  const blob = kgit.readBlob(eng, gitdir, commitOid, "checkpoint");
   let codec = "gzip";
-  try { codec = JSON.parse(dec.decode(kgit.readBlob(eng, gitdir, commitOid, "meta"))).codec ?? "gzip"; } catch {}
+  let stateRoot = null;
+  try { const m = JSON.parse(dec.decode(kgit.readBlob(eng, gitdir, commitOid, "meta"))); codec = m.codec ?? "gzip"; stateRoot = m.stateRoot ?? null; } catch {}
   const dezip = async (b) => dec.decode(codec === "gzip" ? await gunzip(b) : b);
+  // THE FOLD FRONTIER is the cold-mount artifact ("the checkpoint IS the verified fold"); the legacy
+  // SQLite `checkpoint` file is absent on current exports. Both reads are tolerant (a missing file ⇒ null).
+  let blob = null;
+  try { const b = kgit.readBlob(eng, gitdir, commitOid, "checkpoint"); if (b) blob = await dezip(b); } catch { /* current-era: no SQLite blob */ }
   let frontier = null;
   try { const f = kgit.readBlob(eng, gitdir, commitOid, "frontier"); if (f) frontier = await dezip(f); } catch { /* pre-this-era: no frontier */ }
-  return { blob: await dezip(blob), frontier };
+  return { blob, frontier, stateRoot };
 }
 
 /** The checkpoint's schema-parity key: a hash of the workspace's CURRENT law map (every installed
@@ -1618,8 +1676,8 @@ export async function restoreCheckpointFromCustody(eng, ws, ledger, lawHash) {
     if (!foundOid) return { restored: false, reason: "absent" };
     // Fetch ONLY the checkpoint commit (parentless → O(checkpoint), never O(chain)) into ws's repo + apply_pack.
     await custodyFetch(eng, ws, ledger, { remoteRef: ref });
-    const { blob, frontier } = await readCheckpointBlob(eng, ws, foundOid);
-    const r = importCheckpoint(eng, ws, blob, frontier);
+    const { blob, frontier, stateRoot } = await readCheckpointBlob(eng, ws, foundOid);
+    const r = importCheckpoint(eng, ws, blob, frontier, stateRoot);
     if (r && r.restored === true && r.cursor) {
       eng._ckptPushed ??= new Map();
       eng._ckptPushed.set(ws, `${lawHash}:${r.cursor}`);
@@ -1775,12 +1833,31 @@ export const cryptoKeygen = (eng) => JSON.parse(call(eng.ex, "query", { queryByt
 // on the author call). Returns { ok, secret, public } (both base64). `author_sign` is the lower-level
 // standalone signer; the author DOOR signs internally from the injected secret, so callers use `author`.
 export const authorKeygen = (eng) => JSON.parse(call(eng.ex, "query", { queryBytes: b64Json({ op: "authorKeygen" }) }, eng.STDERR));
+
+// DESCRIBE (#43) — the workspace's self-describing API, DERIVED BY THE KERNEL from the installed law at
+// the FRONTIER (not a from-genesis fold): rpc_describe reads the active-domain set off the projection at
+// head and runs each active package's GENERIC `describe` verb over its OWN registered modules, merging
+// them (byte-identical to the compiler's <name>.openapi.json for a single package) + tagging
+// `x-nomos-described` (the hashes covered, for the host's thin staged-overlay fallback on a pre-describe
+// lump). The kernel returns the merged JSON. MUST live HERE (the adapter source) — deploy.sh syncs this
+// into container/src, so editing only the synced copy gets clobbered (the "unknown container op describe").
+export function describe(eng, ws) {
+  return JSON.parse(call(eng.ex, "query", { repoArg: repoArgOf(ws), workspace: ws, queryBytes: b64Json({ op: "describe", workspace: ws }), branch: BRANCH }, eng.STDERR));
+}
 // THE CROSS-CUSTODY ATTESTATION SIGNER (home_holons §3/§5) — the asserter's client produces a SIGNED QUOTE
 // over the edge it is sharing (`attestation_sign`; the bytes are derived IN-wasm — the `author_sign` parity
 // contract). The device `secret` (base64) is injected for THIS call only. Returns { ok, signature, publicKey }
 // (base64) — the parts a `recordShare` payload carries; the subject's home gate verifies them (§3 gate-arm).
 export const attestationSign = (eng, { secret, asserterWorkspace, object, relation, subject, attestedAt }) =>
   JSON.parse(call(eng.ex, "query", { queryBytes: b64Json({ op: "attestationSign", secret, asserterWorkspace, object, relation, subject, attestedAt }) }, eng.STDERR));
+// THE BIRTH-CERT SIGNER (VA root-of-trust) — the SINGLE SOURCE OF TRUTH for the cert byte format. The
+// signer's client produces a SIGNED birth cert IN-wasm (`cert_sign` reuses `BirthCert::signed_bytes`/`sign`,
+// the SIBLING of `attestation_sign`) so no client re-implements the layout (drift-proof). The device
+// `secret` (base64) is injected for THIS call only; `parentKey` is the base64 ed25519 PUBLIC half matching
+// it (as the cert names it). Returns { ok, cert } where `cert` is the signed cert JSON (snake_case,
+// signature as a byte array) — the EXACT shape `verify_to_root` parses.
+export const certSign = (eng, { child, founder, verified, parentKey, parentId, epoch, secret }) =>
+  JSON.parse(call(eng.ex, "query", { queryBytes: b64Json({ op: "certSign", child, founder, verified, parentKey, parentId, epoch, secret }) }, eng.STDERR)).cert;
 export const cryptoWrapKey = (eng, { recipientPub, scopeKey }) => JSON.parse(call(eng.ex, "query", { queryBytes: b64Json({ op: "cryptoWrapKey", recipientPub, scopeKey }) }, eng.STDERR));
 export const cryptoUnwrapKey = (eng, { secret, hpkeEpk, ct }) => JSON.parse(call(eng.ex, "query", { queryBytes: b64Json({ op: "cryptoUnwrapKey", secret, hpkeEpk, ct }) }, eng.STDERR)).scopeKey;
 // THE READ-POSTURE PROBE (slice 5.1): the githolon's own verdict on whether the
@@ -1847,8 +1924,10 @@ export function offerIntent(eng, ws, bytes, opts) {
  */
 export function offerAdmit(eng, ws, bytes, opts) {
   const v = offerIntent(eng, ws, bytes, opts);
+  // KEEP `born`: a SEALED `.births()` offer ran the G3 birth offer-effect in admit_core and surfaced the
+  // child heads on the verdict; carry them through so the admit lane (admitIntentOffers) relays them.
   return v.outcome === "admitted"
-    ? { ok: true, head: v.head }
+    ? { ok: true, head: v.head, ...(v.born ? { born: v.born } : {}) }
     : { ok: false, error: v.verdict?.reason ?? v.error ?? "the offer was refused" };
 }