@githolon/testing 0.14.0 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/testing",
-  "version": "0.14.0",
+  "version": "0.15.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

@@ -12,7 +12,7 @@
 //     from the container instance base, ledgers ARRIVE on each op (containers have no
 //     Workers bindings — the control-plane DO mints tokens and sends them), runs in Node.
 //
-// CONTROL PLANE STAYS IN THE DO: ownership secrets, manifest overlays, the DLQ store,
+// CONTROL PLANE STAYS IN THE DO: ownership secrets, the DLQ store,
 // quotas/rates, alarms. The engine RETURNS data (e.g. dead-letter entries with intent
 // bytes) and the host persists. Runtime-neutral: workerd + Node 22 (globalThis.crypto,
 // fetch, TextEncoder are the only ambient dependencies).
@@ -55,9 +55,9 @@ function call(ex, mode, fields, STDERR) {
   } finally { ex.git_holon_dealloc(reqPtr, req.length); }
 }
 
-function seedManifests(m, strings) {
-  m.set("domain_manifests.json", new File(enc.encode(strings.read)));
-  m.set("identity-manifests.json", new File(enc.encode(strings.identity)));
+function seedManifests(_m, _strings) {
+  // Runtime manifests are committed inside USDA packages and derived by the holon
+  // from active installed law. Hosts must not seed admission/projection sidecars.
 }
 
 // (#39 BAILIFF: no host-chosen `authorityScope` literal. It was a dead, hardcoded "workspace/root" stamped
@@ -68,13 +68,14 @@ export const installPayload = (hash, usda, installedBy, dispositions) => ({ doma
 
 /**
  * Boot the resident wasm + /work tree. `wasmModule` is a PRECOMPILED WebAssembly.Module
- * (the host compiles its way); `manifestStrings` = {read, identity} (baked ∪ overlays —
- * the HOST owns overlay storage and recomputes); `replica` = the host's unique 63-bit id.
+ * (the host compiles its way); `replica` = the host's unique 63-bit id.
+ *
+ * Runtime read/admission metadata is sovereign holon state: committed USDA packages
+ * are folded by the githolon, and the host never stages manifest sidecars.
  */
-export async function createEngine({ wasmModule, bootstrapPkg, nomosPkg, manifestStrings, replica, installedBy = "nomos-cloud" }) {
+export async function createEngine({ wasmModule, bootstrapPkg, nomosPkg, replica, installedBy = "nomos-cloud" }) {
   const hashes = { bootstrap: await sha256hex(bootstrapPkg), nomos: await sha256hex(nomosPkg) };
   const root = new Map();
-  seedManifests(root, manifestStrings);
   root.set("domain.package.usda", new File(enc.encode(bootstrapPkg)));
   root.set("ws", new Directory(new Map()));
   const preopen = new PreopenDirectory("/work", root);
@@ -87,39 +88,19 @@ export async function createEngine({ wasmModule, bootstrapPkg, nomosPkg, manifes
   for (const n of ["memory", "git_holon_alloc", "git_holon_dealloc", "git_holon_call"]) if (!inst.exports[n]) throw new Error(`missing export ${n}`);
   const eng = {
     ex: inst.exports, preopen, STDERR, seq: 0, replica, hashes,
-    bootstrapPkg, nomosPkg, manifestStrings, installedBy,
+    bootstrapPkg, nomosPkg, installedBy,
     fs: makeGitFs(preopen, "/work", { File, Directory }),
     mounted: new Map(),       // ws -> { restored, remoteMain, restoreError }
     mainIntents: new Map(),   // ws -> { head, ids:Set, oids:Set } (admission idempotence)
-    knownDomainsCache: null,
   };
   return eng;
 }
 
-/** Swap the manifest strings (a deploy staged a new overlay) + restage every mount. */
-export function setManifests(eng, strings) {
-  eng.manifestStrings = strings;
-  eng.knownDomainsCache = null;
-  eng.directiveRoutesCache = null;
-  eng.scopedReadsCache = null;
-  eng.placementDirectivesCache = null;
-  eng.tenantTypesCache = null;
-  eng.globalAggregatesCache = null;
-  const root = eng.preopen.dir.contents;
-  seedManifests(root, strings);
-  const wsRoot = root.get("ws");
-  for (const ws of eng.mounted.keys()) {
-    const wsDir = wsRoot.contents.get(ws);
-    if (wsDir) seedManifests(wsDir.contents, strings);
-  }
-}
-
-/** The domains DEPLOYED to this workspace = the effective identity map's keys. */
-export function knownDomains(eng) {
-  if (eng.knownDomainsCache) return eng.knownDomainsCache;
-  eng.knownDomainsCache = new Set(Object.keys(JSON.parse(eng.manifestStrings.identity)));
-  return eng.knownDomainsCache;
-}
+// There is NO host→holon manifest channel. The wasm derives every read/identity
+// manifest from the FOLDED ledger (installed_read_manifest_bytes_from_state) and
+// refuses a package lacking nomosReadProjection. A host cannot provide a manifest:
+// the op does not exist (Read Confinement — the kernel's transition function, not a
+// host convention). `setManifests` is gone, not no-op'd, so the lie is unrepresentable.
 
 // ── TRANSPARENT SHARDING: the WRONG-HOME GATE (the edge bailiff — sharding slice 2) ──
 //
@@ -135,18 +116,10 @@ export function knownDomains(eng) {
 
 /** directive routes off the effective identity manifests: `${domain} ${directiveId}` → route. */
 export function directiveRoutes(eng) {
-  if (eng.directiveRoutesCache) return eng.directiveRoutesCache;
-  const routes = new Map();
-  let identity = {};
-  try { identity = JSON.parse(eng.manifestStrings.identity); } catch {}
-  for (const [domain, manifestJson] of Object.entries(identity)) {
-    try {
-      const m = typeof manifestJson === "string" ? JSON.parse(manifestJson) : manifestJson;
-      for (const r of (m && m.routes) || []) routes.set(`${domain} ${r.directive}`, r);
-    } catch {}
-  }
-  eng.directiveRoutesCache = routes;
-  return routes;
+  void eng;
+  // Host-side manifest taxonomy is retired. Shard routing needs a holon-owned
+  // taxonomy API before it can be re-enabled without leaking law into the host.
+  return new Map();
 }
 
 /** The 48-bit route tag of a home key (must agree byte-for-byte with the client mint). */
@@ -246,39 +219,15 @@ const FRAMEWORK_AGG_TYPES = new Set([
  *  the suffix re-derivation, deep-verify's recount): control-plane rows (PolicyBundle,
  *  DomainInstallation) and framework law-state never skew the capacity metric. */
 function tenantTypes(eng) {
-  if (eng.tenantTypesCache) return eng.tenantTypesCache;
-  let readManifest = {};
-  try { readManifest = JSON.parse(eng.manifestStrings.read); } catch {}
-  // §5.4 (slice 4): GLOBAL reference data is replicated custody on every shard —
-  // its rows arrive by the reverse lane (replicateIntents — a host leg the §5.2
-  // capture never sees), so counting them as tenant load would let the three
-  // row-count lanes drift (capture vs suffix vs deep-verify recount). Excluded
-  // from the capacity metric on EVERY lane, by the one shared definition here.
-  const globals = globalAggregates(eng);
-  const out = new Set(Object.keys(readManifest.aggregateFieldKinds || {}).filter((t) => !FRAMEWORK_AGG_TYPES.has(t) && !globals.has(t)));
-  eng.tenantTypesCache = out;
-  return out;
+  void eng;
+  return new Set();
 }
 
 /** The derived PLACEMENT directives off the effective identity manifests:
  *  packed type `site` ⇒ `birthSite` keyed by payload field `siteId` (the law's naming). */
 export function placementDirectives(eng) {
-  if (eng.placementDirectivesCache) return eng.placementDirectivesCache;
-  const out = new Map(); // directiveId -> { axis, keyField }
-  const pascal = (s) => s.replace(/[_\s-]+(\w)/g, (_m, c) => c.toUpperCase()).replace(/^./, (c) => c.toUpperCase());
-  let identity = {};
-  try { identity = JSON.parse(eng.manifestStrings.identity); } catch {}
-  for (const manifestJson of Object.values(identity)) {
-    let m;
-    try { m = typeof manifestJson === "string" ? JSON.parse(manifestJson) : manifestJson; } catch { continue; }
-    for (const t of (m && m.workspaceTypes) || []) {
-      if (!t || t.mode !== "packed") continue;
-      const p = pascal(String(t.id));
-      out.set(`birth${p}`, { axis: t.id, keyField: `${p.length ? p[0].toLowerCase() + p.slice(1) : p}Id` });
-    }
-  }
-  eng.placementDirectivesCache = out;
-  return out;
+  void eng;
+  return new Map();
 }
 
 /** The ESTATE-SCOPED maintained reads off the effective identity manifests.
@@ -287,31 +236,8 @@ export function placementDirectives(eng) {
  *  predicate-aware in the kernel); the SUFFIX re-derivation evaluates it host-side
  *  ({@link evalCanonicalPred}) so both lanes agree byte-for-byte. */
 export function scopedReads(eng) {
-  if (eng.scopedReadsCache) return eng.scopedReadsCache;
-  const out = [];
-  let identity = {};
-  try { identity = JSON.parse(eng.manifestStrings.identity); } catch {}
-  for (const manifestJson of Object.values(identity)) {
-    let m;
-    try { m = typeof manifestJson === "string" ? JSON.parse(manifestJson) : manifestJson; } catch { continue; }
-    for (const c of (m && m.counts) || []) {
-      if (c && typeof c.scope === "string") out.push({ id: c.id, kind: "count", of: c.of, by: c.by ?? null, ...(c.where ? { where: c.where } : {}) });
-    }
-    for (const s of (m && m.sums) || []) {
-      if (s && typeof s.scope === "string") out.push({ id: s.id, kind: "sum", of: s.of, by: s.by ?? null, field: s.sumField, ...(s.where ? { where: s.where } : {}) });
-    }
-    // SLICE 8 — scoped EXTREMUMS: per-shard min/max ride the same delta lane
-    // (events carry post-intent ABSOLUTES; the gate extremizes-on-monotone and
-    // requires declared re-derivation on retractions). The oracle is the
-    // projection's long-maintained extrema lane (#47's `extremum` RPC).
-    for (const [key, kind] of [["mins", "min"], ["maxes", "max"]]) {
-      for (const e of (m && m[key]) || []) {
-        if (e && typeof e.scope === "string") out.push({ id: e.id, kind, of: e.of, by: e.by ?? null, field: e.valueField, ...(e.where ? { where: e.where } : {}) });
-      }
-    }
-  }
-  eng.scopedReadsCache = out;
-  return out;
+  void eng;
+  return [];
 }
 
 /**
@@ -340,19 +266,8 @@ export function evalCanonicalPred(pred, get) {
  * DOWNWARD into every shard chain by re-admission (the reverse delta lane).
  */
 export function globalAggregates(eng) {
-  if (eng.globalAggregatesCache) return eng.globalAggregatesCache;
-  const out = new Set();
-  let identity = {};
-  try { identity = JSON.parse(eng.manifestStrings.identity); } catch {}
-  for (const manifestJson of Object.values(identity)) {
-    let m;
-    try { m = typeof manifestJson === "string" ? JSON.parse(manifestJson) : manifestJson; } catch { continue; }
-    for (const t of (m && m.workspaceTypes) || []) {
-      for (const g of (t && t.globals) || []) if (typeof g === "string") out.add(g);
-    }
-  }
-  eng.globalAggregatesCache = out;
-  return out;
+  void eng;
+  return new Set();
 }
 
 /** Parse an intent blob's sealed events: [{aggregate, ops: Map(field -> {Str|Int})}]. */
@@ -1066,12 +981,6 @@ export async function admitIntentOffers(eng, ws, ledger, offers, { refuseDomains
         rec.rejected.push({ oid, error: `session lane refuses ${dom ? `'${dom}'` : "non-authored"} intents — law deploys go through POST /v1/workspaces/${ws}/domains with the workspace secret` });
         continue;
       }
-      if (!knownDomains(eng).has(dom)) {
-        const error = `domain '${dom}' is not deployed to this workspace — deploy its law (POST /v1/workspaces/${ws}/domains with the workspace secret), then POST /v1/workspaces/${ws}/dead-letters/retry`;
-        rec.rejected.push({ oid, error, deadLettered: true });
-        deadLetters.push({ intentId, oid, session: cid, error, blob, domain: dom, directiveId: dirId });
-        continue;
-      }
       if (receiptFence && dirId && Array.isArray(receiptFence[dom]) && receiptFence[dom].includes(dirId)) {
         const error = `'${dom}/${dirId}' is a capability RECEIPT — receipts are executor/owner writes, never open-session writes. Author it via POST /v1/workspaces/${ws}/author (owner Bearer), or — if this parked receipt is sanctioned — the owner unjams it: POST /v1/workspaces/${ws}/dead-letters/retry`;
         rec.rejected.push({ oid, error, deadLettered: true });
@@ -1214,7 +1123,6 @@ export async function deepVerifyShard(eng, shardWs, shardLedger, coordinatorRows
 
 function stageWorkspaceDir(eng, ws) {
   const wsContents = new Map();
-  seedManifests(wsContents, eng.manifestStrings);
   eng.preopen.dir.contents.get("ws").contents.set(ws, new Directory(wsContents));
 }
 
@@ -1704,7 +1612,7 @@ async function mainIntentIds(eng, ws) {
  * engine has no durable store), obvious attacks drop. Admitted intents merge to main,
  * durably push, the branch is consumed.
  */
-export async function admitAll(eng, ws, ledger, { refuseDomains = [], receiptFence = null, shardRouting = null, sessionRefs = null } = {}) {
+export async function admitAll(eng, ws, ledger, { refuseDomains = [], receiptFence = null, shardRouting = null, sessionRefs = null, defer = false } = {}) {
   const refuse = new Set(refuseDomains);
   const routes = shardRouting ? directiveRoutes(eng) : null;
   const gitdir = gitdirOf(ws);
@@ -1823,14 +1731,6 @@ export async function admitAll(eng, ws, ledger, { refuseDomains = [], receiptFen
             rejected.push({ oid: oid.slice(0, 10), error: `session lane refuses ${dom ? `'${dom}'` : "non-authored"} intents — law deploys go through POST /v1/workspaces/${ws}/domains with the workspace secret` });
             continue;
           }
-          // LAW-FENCE part 2: the domain must be DEPLOYED to this workspace. An
-          // undeployed domain's write is the canonical LEGITIMATE JAM — dead-letter.
-          if (!knownDomains(eng).has(dom)) {
-            const error = `domain '${dom}' is not deployed to this workspace — deploy its law (POST /v1/workspaces/${ws}/domains with the workspace secret), then POST /v1/workspaces/${ws}/dead-letters/retry`;
-            rejected.push({ oid: oid.slice(0, 10), error, deadLettered: true });
-            deadLetters.push({ intentId, oid: oid.slice(0, 10), session: cid, error, blob, domain: dom, directiveId: dirId });
-            continue;
-          }
           // THE RECEIPT FENCE (capability_marketplace.md slice 1.5 — the ratified
           // authz condition): a capability RECEIPT (complete/fail/block/deadLetter)
           // is an EXECUTOR/OWNER write — the open session lane never folds one, so
@@ -1984,8 +1884,17 @@ export async function admitAll(eng, ws, ledger, { refuseDomains = [], receiptFen
   // the ws fs); we then SKIP the branch deletes so every offered intent re-admits next cycle (idempotent by
   // id). On success, delete the consumed session branches (best-effort cleanup; a stale branch is a harmless
   // re-fetch). Single-client workspaces were already one push/cycle; this collapses collaborative bursts.
+  // THE BAILIFF SEAM: when the HOST asked us to `defer` (the open session admit lane on a
+  // non-coordinator workspace), we DO NOT push or delete consumed branches inline — the fold
+  // is already on resident main (truth), and the host backs it up to custody off the critical
+  // path (engine.backupToCustody, debounced + coalesced). This is sound because the SESSION
+  // BRANCHES are themselves durable in custody (the durable inbox) and admit is idempotent by
+  // intent id: a crash before backup just re-derives the SAME sealed main from the same offers.
+  // Coordinator/sharded admits (any §5.2/§5.4/placement/split follow-up) stay durable-before-ack.
+  const hasCoordination = !!(summaryCtx || placements.length || splits.length || globalsOut.length);
+  const deferDurability = defer && !hasCoordination;
   let _sealed = true;
-  if (totalAdmitted) {
+  if (totalAdmitted && !deferDurability) {
     const _sealDone = _span(`seal (batch)`, "cseal", 1, { sessions: consumed.length, admitted: totalAdmitted });
     const _s = Date.now();
     try {
@@ -1998,7 +1907,7 @@ export async function admitAll(eng, ws, ledger, { refuseDomains = [], receiptFen
       _sealDone();
     }
   }
-  if (_sealed) {
+  if (_sealed && !deferDurability) {
     for (const { ref } of consumed) {
       try { await pushVia(ledger, () => git.push({ fs: eng.fs, http, gitdir, url: ledger.remote, ref: BRANCH, remoteRef: ref, delete: true, headers: ledger.headers })); } catch {}
     }
@@ -2017,9 +1926,33 @@ export async function admitAll(eng, ws, ledger, { refuseDomains = [], receiptFen
     ...(placements.length ? { placements } : {}),
     ...(splits.length ? { splits } : {}),
     ...(globalsOut.length ? { globals: globalsOut } : {}),
+    // The host's backup lane consumes these: `deferred` ⇒ resident main carries totalAdmitted
+    // un-backed-up commits and `consumed` are the session branches to delete AFTER the push lands.
+    ...(deferDurability && totalAdmitted ? { deferred: true, consumed, admitted: totalAdmitted } : {}),
   };
 }
 
+// THE BAILIFF'S BACKUP — push resident main to custody when quiet, NEVER on a write's critical
+// path and NEVER destructive. Unlike commitAndPush (durability-before-ack: unmounts on failure),
+// a failed backup leaves the resident holon mounted and the session branches intact, so the host
+// just retries on the next quiet tick. Append-only main means an off-lock push of an older head
+// concurrent with a fresh fold is always a sound fast-forward subset (the newer head backs up next).
+export async function backupToCustody(eng, ws, ledger, { consumed = [] } = {}) {
+  if (!eng.mounted.has(ws)) return { ok: false, error: "not mounted" };
+  const gitdir = gitdirOf(ws);
+  let head = null;
+  try { head = await git.resolveRef({ fs: eng.fs, gitdir, ref: BRANCH }); } catch { return { ok: false, error: "no local main" }; }
+  try {
+    await pushVia(ledger, () => git.push({ fs: eng.fs, http, gitdir, url: ledger.remote, ref: BRANCH, remoteRef: BRANCH, force: false, headers: ledger.headers }));
+  } catch (e) {
+    return { ok: false, error: String(e).slice(0, 200), head };
+  }
+  for (const { ref } of consumed) {
+    try { await pushVia(ledger, () => git.push({ fs: eng.fs, http, gitdir, url: ledger.remote, ref: BRANCH, remoteRef: ref, delete: true, headers: ledger.headers })); } catch {}
+  }
+  return { ok: true, head };
+}
+
 /**
  * VERIFY AN UPLOADED LEDGER — "the githolon executes and thus validates it". Fresh-mounts
  * the workspace from custody (never a cached mount — the bytes under judgment are the
@@ -2095,32 +2028,8 @@ export async function deploy(eng, ws, ledger, usda, domainHash, dispositions) {
   // adjudicates the stable-id diff against. Absent for the common (non-destructive)
   // upgrade; the gate's typed refusal names the remedy when one is needed.
   const result = author(eng, ws, "nomos", "installDomain", installPayload(domainHash, usda, eng.installedBy, dispositions), eng.hashes.nomos);
-  // THE SHARD-IDENTITY ENSURE (#41 — slice 3a): a taxonomy-bearing law carries the
-  // homing invariant, which judges against the workspace's OWN declared identity
-  // (`NomosShardIdentity`, law-state in the shard's own chain). The worker is the
-  // bailiff: it records the CUSTODY fact (this workspace's name ⇒ its shard label)
-  // through the chain's own gate right after the law lands — attributed, replayable,
-  // idempotent (an Ensure; re-deploys re-assert the same state). Coordinator ⇒ label ""
-  // (no homing claim — the invariant holds vacuously there).
-  try {
-    eng.directiveRoutesCache = null; // the just-staged overlay may add routes
-    const routed = new Set([...directiveRoutes(eng).keys()].map((k) => k.split(" ")[0]));
-    if (routed.size) {
-      const m = ws.match(/^(.*)--(s\d+)$/);
-      const label = m ? m[2] : "";
-      const coordinator = m ? m[1] : ws;
-      const existing = qById(eng, ws, "nomos-shard-identity:self");
-      const current = existing.length ? existing[0].data : null;
-      if (!current || current.label !== label || current.coordinator !== coordinator) {
-        for (const dom of routed) {
-          try {
-            const declared = author(eng, ws, dom, "nomosDeclareShardIdentity", { label, coordinator, declaredAt: new Date().toISOString() }, domainHash);
-            if (declared && declared.ok !== false) break; // one declaration IS the workspace's identity
-          } catch {} // a routed domain owned by an earlier law: its own deploy declared it
-        }
-      }
-    }
-  } catch {}
+  // Shard identity used to be inferred from host-side taxonomy. That is retired:
+  // if sharding needs declaration, the holon must derive and author it itself.
   await commitAndPush(eng, ws, ledger);
   return { head: result.head, installation: qById(eng, ws, `domain-installation:${domainHash}`) };
 }