@githolon/testing 0.7.1 → 0.8.0

package/package.json

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

@@ -53,7 +53,11 @@ function seedManifests(m, strings) {
   m.set("identity-manifests.json", new File(enc.encode(strings.identity)));
 }
 
-export const installPayload = (hash, usda, installedBy, dispositions) => ({ domainHash: hash, packageUsda: usda, installedBy, authorityScope: "workspace/root", dependencies: [], finalizers: [], ...(dispositions ? { dispositions } : {}) });
+// (#39 BAILIFF: no host-chosen `authorityScope` literal. It was a dead, hardcoded "workspace/root" stamped
+//  onto EVERY install — incl. non-root tenants — that NOTHING in the kernel ever reads for a decision
+//  (domain_lifecycle.rs folds it to an Option<String> and never branches on it). The host carries the
+//  package bytes; it does not author an authority-scoping fact the law never declared. Absent ⇒ folded None.)
+export const installPayload = (hash, usda, installedBy, dispositions) => ({ domainHash: hash, packageUsda: usda, installedBy, dependencies: [], finalizers: [], ...(dispositions ? { dispositions } : {}) });
 
 /**
  * Boot the resident wasm + /work tree. `wasmModule` is a PRECOMPILED WebAssembly.Module
@@ -1190,7 +1194,10 @@ export function author(eng, ws, domain, directiveId, payload, controllerHash, op
   // (`warmEngine`, which every host already calls) flushes it eagerly. Pass
   // `opts.deferProjection: false` to keep the pre-#47 synchronous refresh.
   const defer = opts.deferProjection !== false;
-  const res = JSON.parse(call(eng.ex, "author", { 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, ...(defer ? { deferProjection: true } : {}) }, eng.STDERR));
+  // authorSecret (warrant-flip): the author's client-held ed25519 device secret (b64), injected for THIS
+  // local author ONLY so the wasm author door mints the signed-author attestation + self-verifies. Absent
+  // on a legacy/unwarranted author (the door's legacy fast path); a warranted workspace REQUIRES it.
+  const res = JSON.parse(call(eng.ex, "author", { 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 } : {}), ...(defer ? { deferProjection: true } : {}) }, eng.STDERR));
   if (defer && res.ok) (eng.pendingProjection ??= new Set()).add(ws);
   return res;
 }
@@ -1227,6 +1234,115 @@ export function importCheckpoint(eng, ws, blobB64) {
   return JSON.parse(call(eng.ex, "checkpoint_import", { repoArg: repoArgOf(ws), workspace: ws, branch: BRANCH, blob: blobB64 }, eng.STDERR));
 }
 
+// ── CHECKPOINT IN CUSTODY (the host-agnostic cold-mount; compute placement is beneath the contract) ──
+// The folded projection is a fact ABOUT the chain — so carry it IN custody (a git ref), not in some
+// host's private storage the NEXT host can't reach. The ephemeral heavy container has no ctx.storage;
+// a DO checkpoint is invisible to it; so root (heavy) re-folds O(chain) on every cold start. Put the
+// checkpoint where every peer already looks — the ledger — and ANY host restores it O(delta): the git
+// carries its own folded state. Keyed by the CURRENT law hash (schema parity): a law upgrade orphans
+// the old checkpoint (the next reader cold-folds once, re-publishes under the new hash). Best-effort &
+// post-ack — a missing/stale checkpoint costs at most one cold fold, never a wrong read; main is truth.
+const CKPT_REF = (lawHash) => `refs/meta/checkpoint/${lawHash}`;
+const CKPT_AUTHOR = { name: "nomos", email: "nomos@holon", timestamp: 0, timezoneOffset: 0 };
+
+// A serialized SQLite projection is mostly FREE PAGES (the fold DELETEs+reinserts per commit) — it
+// gzips ~30×. We compress the b64 export host-side before it enters custody: the ledger meters pushed
+// bytes against the workspace quota, and a cold peer fetches less. Runtime-neutral (CompressionStream
+// is in Node 18+ and workerd). The `meta` blob records the codec so a future format stays readable.
+async function streamAll(stream) {
+  const chunks = []; const reader = stream.getReader();
+  for (;;) { const { done, value } = await reader.read(); if (done) break; chunks.push(value); }
+  let len = 0; for (const c of chunks) len += c.length;
+  const out = new Uint8Array(len); let at = 0; for (const c of chunks) { out.set(c, at); at += c.length; }
+  return out;
+}
+async function gzip(bytes) {
+  const cs = new CompressionStream("gzip");
+  return streamAll(new Response(bytes).body.pipeThrough(cs));
+}
+async function gunzip(bytes) {
+  const ds = new DecompressionStream("gzip");
+  return streamAll(new Response(bytes).body.pipeThrough(ds));
+}
+
+/** Wrap an exported checkpoint into git objects under `refs/meta/checkpoint/<lawHash>` (LOCAL only —
+ *  no network). The ref points at a parentless commit whose tree carries `checkpoint` (the b64 blob)
+ *  and `meta` ({cursor,bytes,lawHash}). Returns {ref, commitOid}. Separated from the push so the
+ *  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));
+  const blobOid = await git.writeBlob({ fs: eng.fs, gitdir, blob: gz });
+  const metaOid = await git.writeBlob({ fs: eng.fs, gitdir, blob: enc.encode(JSON.stringify({ cursor: ex.cursor, bytes: ex.bytes ?? 0, lawHash, codec: "gzip", raw: ex.blob.length, stored: gz.length })) });
+  const tree = await git.writeTree({ fs: eng.fs, gitdir, tree: [
+    { mode: "100644", path: "checkpoint", oid: blobOid, type: "blob" },
+    { mode: "100644", path: "meta", oid: metaOid, type: "blob" },
+  ] });
+  const commitOid = await git.writeCommit({ fs: eng.fs, gitdir, commit: { tree, parent: [], author: CKPT_AUTHOR, committer: CKPT_AUTHOR, message: `checkpoint ${ws} @${String(ex.cursor).slice(0, 16)}` } });
+  const ref = CKPT_REF(lawHash);
+  await git.writeRef({ fs: eng.fs, gitdir, ref, value: commitOid, force: true });
+  return { ref, commitOid };
+}
+
+/** Read a checkpoint blob back out of a commit oid (LOCAL only — the objects must already be present,
+ *  via a prior write or a shallow fetch). Returns the b64 string importCheckpoint accepts. */
+export async function readCheckpointBlob(eng, ws, commitOid) {
+  const gitdir = gitdirOf(ws);
+  const { blob } = await git.readBlob({ fs: eng.fs, gitdir, oid: commitOid, filepath: "checkpoint" });
+  let codec = "gzip";
+  try { codec = JSON.parse(dec.decode((await git.readBlob({ fs: eng.fs, gitdir, oid: commitOid, filepath: "meta" })).blob)).codec ?? "gzip"; } catch {}
+  return dec.decode(codec === "gzip" ? await gunzip(blob) : blob);
+}
+
+/** The checkpoint's schema-parity key: a hash of the workspace's CURRENT law map (every installed
+ *  domain). The HOST passes nothing — the engine derives it from the chain (bailiff). A law upgrade
+ *  changes the map → a new key → the old checkpoint is orphaned (the next reader cold-folds once and
+ *  re-publishes). An explicit `lawHash` (the DO's existing govHash callers, tests) overrides. */
+export async function lawParity(eng, ws, lawHash) {
+  if (lawHash) return lawHash;
+  try {
+    const map = currentLaw(eng, ws) || {};
+    return await sha256hex(JSON.stringify(Object.entries(map).sort()));
+  } catch { return null; }
+}
+
+/** Export ws's folded projection-at-head and PUBLISH it to custody (`refs/meta/checkpoint/<lawHash>`).
+ *  Skips an unchanged head (dedups dup acks). Best-effort; returns {pushed, cursor?, bytes?, reason?}. */
+export async function pushCheckpoint(eng, ws, ledger, lawHash) {
+  try {
+    lawHash = await lawParity(eng, ws, lawHash);
+    if (!lawHash) return { pushed: false, reason: "no-law" };
+    const ex = exportCheckpoint(eng, ws);
+    if (!ex || ex.empty || !ex.ok || !ex.blob) return { pushed: false, reason: ex && ex.empty ? "empty" : "no-blob" };
+    eng._ckptPushed ??= new Map();
+    const tag = `${lawHash}:${ex.cursor}`;
+    if (eng._ckptPushed.get(ws) === tag) return { pushed: false, reason: "unchanged" };
+    const { ref } = await writeCheckpointObjects(eng, ws, ex, lawHash);
+    await git.push({ fs: eng.fs, http, gitdir: gitdirOf(ws), url: ledger.remote, ref, remoteRef: ref, force: true, headers: ledger.headers });
+    eng._ckptPushed.set(ws, tag);
+    return { pushed: true, cursor: ex.cursor, bytes: ex.bytes ?? 0 };
+  } catch (e) { return { pushed: false, reason: String((e && e.message) || e).slice(0, 160) }; }
+}
+
+/** Restore ws's projection from custody BEFORE the first read on a cold mount: ls-remote the law's
+ *  checkpoint ref, shallow-fetch ONLY that commit (O(checkpoint), never O(chain)), import it. No-op if
+ *  absent or the law drifted. Returns {restored, cursor?, reason?}. */
+export async function restoreCheckpointFromCustody(eng, ws, ledger, lawHash) {
+  try {
+    lawHash = await lawParity(eng, ws, lawHash);
+    if (!lawHash) return { restored: false, reason: "no-law" };
+    const ref = CKPT_REF(lawHash);
+    const serverRefs = await git.listServerRefs({ http, url: ledger.remote, headers: ledger.headers, prefix: ref, protocolVersion: 2 });
+    const found = (serverRefs || []).find((r) => r.ref === ref);
+    if (!found || !found.oid) return { restored: false, reason: "absent" };
+    const gitdir = gitdirOf(ws);
+    await git.fetch({ fs: eng.fs, http, gitdir, url: ledger.remote, ref, singleBranch: true, depth: 1, headers: ledger.headers });
+    const b64 = await readCheckpointBlob(eng, ws, found.oid);
+    const r = importCheckpoint(eng, ws, b64);
+    return { restored: r && r.restored === true, cursor: r && r.cursor, reason: r && r.reason };
+  } catch (e) { return { restored: false, reason: String((e && e.message) || e).slice(0, 160) }; }
+}
+
 // DURABILITY-BEFORE-ACK: only acked once the write LANDED in the ledger; a failed push
 // unmounts (drops local state) so the next access re-restores from custody.
 export async function commitAndPush(eng, ws, ledger) {
@@ -1238,6 +1354,47 @@ export async function commitAndPush(eng, ws, ledger) {
   }
 }
 
+// ── COMPUTE-PLACEMENT SHAPE (the ledger carries its own shape; compute placement is beneath the contract) ──
+// A workspace's PROJECTION SIZE (sqliteBytes from projection_stats) decides its tier: a projection that
+// fits the 128 MB edge box stays edge; one that outgrows it goes to the 12 GB container. Fold TIME no
+// longer gates the tier — the custody checkpoint (above) makes a cold mount O(delta) at ANY chain length;
+// only the RAM to HOLD the folded projection does. The size is recorded IN CUSTODY as the ref NAME
+// `refs/meta/shape/b<bytes>` (the ref points at head → ships NO objects, a pure ref update); ANY peer
+// reads it fold-free via ls-remote (the number is in the name — no fetch, immune to a fat head intent).
+// Best-effort, post-ack: a stale/missing shape self-heals (wrong box → re-measure); main is truth.
+export async function pushShape(eng, ws, ledger) {
+  try {
+    const st = projectionStats(eng, ws);
+    const bytes = st && (st.sqliteBytes ?? st.bytes);
+    if (bytes == null) return;
+    const gitdir = gitdirOf(ws);
+    const head = await git.resolveRef({ fs: eng.fs, gitdir, ref: "refs/heads/main" }).catch(() => null);
+    if (!head) return;
+    const newRef = `refs/meta/shape/b${bytes}`;
+    eng._lastShapeRef ??= new Map();
+    if (eng._lastShapeRef.get(ws) === newRef) return;
+    await git.writeRef({ fs: eng.fs, gitdir, ref: newRef, value: head, force: true });
+    await git.push({ fs: eng.fs, http, gitdir, url: ledger.remote, ref: newRef, remoteRef: newRef, force: true, headers: ledger.headers });
+    const prev = eng._lastShapeRef.get(ws);
+    if (prev && prev !== newRef) { try { await git.push({ fs: eng.fs, http, gitdir, url: ledger.remote, ref: prev, remoteRef: prev, delete: true, headers: ledger.headers }); } catch { /* leftover refs are harmless: the reader takes max(bytes) */ } }
+    eng._lastShapeRef.set(ws, newRef);
+  } catch { /* best-effort; placement self-heals */ }
+}
+
+// Read the placement shape from custody, FOLD-FREE: ls-remote refs/meta/shape/b<bytes> and parse the name.
+// Returns {bytes} (the max, in case a restart left a stale ref) or null (no shape yet).
+export async function readShape(ledger) {
+  try {
+    const refs = await git.listServerRefs({ http, url: ledger.remote, headers: ledger.headers, prefix: "refs/meta/shape/", protocolVersion: 2 });
+    let best = null;
+    for (const r of refs || []) {
+      const m = /refs\/meta\/shape\/b(\d+)$/.exec(r.ref || "");
+      if (m) { const bytes = +m[1]; if (!best || bytes > best.bytes) best = { bytes }; }
+    }
+    return best;
+  } catch { return null; }
+}
+
 // READ VISIBILITY (slice 5.1): the host STAMPS the presented `principal` onto the
 // read RPC (an impure identity read — never a host DECISION); the githolon gates the
 // read against its OWN folded role-bindings and returns `{ok:false, error:"read-
@@ -1247,6 +1404,11 @@ export async function commitAndPush(eng, ws, ledger) {
 // host-side (X25519 unwrap). Threaded into the read RPC; the wasm AEAD-opens envelope fields.
 export const qById = (eng, ws, id, principal = "", keys = []) => JSON.parse(call(eng.ex, "query_by_id", { repoArg: repoArgOf(ws), workspace: ws, aggregateId: id, principal, keys, branch: BRANCH }, eng.STDERR));
 export const query = (eng, ws, queryId, paramsJson, principal = "", keys = []) => JSON.parse(call(eng.ex, "query", { repoArg: repoArgOf(ws), workspace: ws, queryId, paramsJson, principal, keys, branch: BRANCH }, eng.STDERR));
+// THE ZANZIBAR CHECK/EXPAND (governance authz spine): a pure, replay-deterministic authority probe
+// over the projected relations table. `check` → { ok, allowed:bool }; `expand` → { ok, subjects:[...] }.
+// No principal/keys: relation facts are public authority state (admin/creator/platformCreator/capability).
+export const check = (eng, ws, object, relation, subject) => JSON.parse(call(eng.ex, "check", { repoArg: repoArgOf(ws), workspace: ws, object, relation, subject, branch: BRANCH }, eng.STDERR));
+export const expand = (eng, ws, object, relation) => JSON.parse(call(eng.ex, "expand", { repoArg: repoArgOf(ws), workspace: ws, object, relation, branch: BRANCH }, eng.STDERR));
 // THE AUTHOR-SIDE SEAL (slice 6): encrypt a plaintext field value into the on-chain envelope
 // (XChaCha isn't in WebCrypto, so the client calls the wasm; the scope key is injected, never on chain).
 // The SLOT IDENTITY is the #58 STABLE SID (rename-safety): the caller resolves (type,field)→sid
@@ -1257,6 +1419,12 @@ export const cryptoSealField = (eng, { scopeKey, scope, epoch, aggSid, fieldSid,
 // The client X25519 crypto (slice 6): keygen (device identity), wrap (committer → recipient pubkey),
 // unwrap (reader's device secret → scope key). The secret stays client/host-side, never on chain.
 export const cryptoKeygen = (eng) => JSON.parse(call(eng.ex, "crypto_keygen", {}, eng.STDERR));
+
+// AUTHOR DEVICE KEY (warrant-flip, identity_keys.md) — mint an ed25519 signing keypair IN the holon
+// (`author_keygen`); the secret stays client-side (here: the test/host injects it back as `authorSecret`
+// 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, "author_keygen", {}, eng.STDERR));
 export const cryptoWrapKey = (eng, { recipientPub, scopeKey }) => JSON.parse(call(eng.ex, "crypto_wrap_key", { recipientPub, scopeKey }, eng.STDERR));
 export const cryptoUnwrapKey = (eng, { secret, hpkeEpk, ct }) => JSON.parse(call(eng.ex, "crypto_unwrap_key", { secret, hpkeEpk, ct }, eng.STDERR)).scopeKey;
 // THE READ-POSTURE PROBE (slice 5.1): the githolon's own verdict on whether the
@@ -1650,7 +1818,7 @@ export function stats(eng) {
 }
 
 /** Per-branch projection observables (cursor, projectCalls, sqliteBytes — see #37). */
-export const projectionStats = (eng) => JSON.parse(call(eng.ex, "projection_stats", {}, eng.STDERR));
+export const projectionStats = (eng, ws) => JSON.parse(call(eng.ex, "projection_stats", ws ? { repoArg: repoArgOf(ws), workspace: ws, branch: BRANCH } : {}, eng.STDERR));
 
 /**
  * THE POST-ACK WARM LANE (#34): replenish the wasm engine's pristine-sandbox pool