@githolon/testing 0.34.1 → 0.36.0

package/package.json

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

@@ -44,7 +44,7 @@ function osEntropyBuffer(n) { const bytes = new Uint8Array(n * 8); for (let o =
 function stringifyBig(o) { return JSON.stringify(o, (_k, v) => (typeof v === "bigint" ? `@@B:${v}@@` : v)).replace(/"@@B:(\d+)@@"/g, "$1"); }
 const log = (evt, fields = {}) => console.log(JSON.stringify({ evt, t: Date.now(), ...fields }));
 
-function call(ex, mode, fields, STDERR) {
+export function call(ex, mode, fields, STDERR) {
   const req = enc.encode(JSON.stringify({ mode, ...fields }));
   const reqPtr = ex.git_holon_alloc(req.length);
   try {
@@ -1411,9 +1411,31 @@ export function author(eng, ws, domain, directiveId, payload, controllerHash, op
     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 };
+  // ATTESTED READS (slice B stage 1 — attested_reads_design.md §4.1): the PRE-FETCHED foreign
+  // envelopes injected on the author request (`[{queryId, result, attestation}]`). The wasm author
+  // door serves a plan's `read(q, args, {from})` from these AFTER verifying each (never mid-plan
+  // I/O); unconsumed entries are dropped (COMMIT-ONLY-CONSUMED). Absent ⇒ byte-identical envelope
+  // (the era rule). The DO→DO/HTTPS pre-fetch that POPULATES this is stage 2 — this is the seam.
+  if (opts.attestations !== undefined) envelope.attestations = opts.attestations;
   writeWork(eng, `payload-${seq}.json`, enc.encode(JSON.stringify(payload)));
   writeWork(eng, `envelope-${seq}.json`, enc.encode(stringifyBig(envelope)));
   const genesis = !controllerHash;
+  // THE COLOCATION SHORT-CIRCUIT (stage 2): when the declared foreign SOURCE is already MOUNTED in
+  // THIS engine (the container pool colocates workspaces; the engine plane is multi-workspace — the
+  // birth-effect precedent), a missing attested read never leaves the kernel: the gate's typed
+  // `attested-read-unreachable` refusal names {queryId, from, args}; we serve + sign it via the SAME
+  // `attestedRead` op (secret injected per call from `opts.attestorSecrets[from]` — operator config
+  // the host passes through blindly), inject the envelope, and retry. Zero HTTP, zero host decision.
+  // The envelope is BYTE-IDENTICAL to one fetched over ?attest=1 (same signed bytes, same verify arm).
+  // A CARRIED attestation always wins — the refusal only fires for a read no injected entry answers,
+  // so nothing is ever silently replaced. Non-colocated / secret-less sources fall through to the
+  // caller with the kernel's own instruction (the client-carried ?attest=1 dance).
+  const attestorSecretFor = (from) => {
+    const s = opts.attestorSecrets;
+    if (!s) return null;
+    if (typeof s === "string") return s;
+    return typeof s[from] === "string" ? s[from] : null;
+  };
   // THE DEFERRED-PROJECTION ACK (#47, sharding slice 7): the read-projection
   // catch-up (incl. the derive/combine materialize) moves OFF the author ack path
   // by default — every read op self-heals to head, and the post-ack warm lane
@@ -1430,7 +1452,28 @@ 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 ?? "", ...(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));
+  const offerOnce = () =>
+    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));
+  let v = offerOnce();
+  // COLOCATED foreign reads: bounded loop (a plan may declare several) — each pass answers exactly the
+  // read the kernel named, so it terminates in ≤ #declared-foreign-reads passes (cap 8, defensive).
+  for (let pass = 0; pass < 8 && v.outcome === "refused"; pass++) {
+    const need = parseAttestedReadNeed(v.verdict?.reason ?? v.error);
+    if (!need || !eng.mounted.has(need.from)) break;
+    const secret = attestorSecretFor(need.from);
+    if (!secret) break;
+    const served = attestedRead(eng, need.from, {
+      queryId: need.queryId, paramsJson: JSON.stringify(need.args), attestorSecret: secret,
+      nowMs: opts.attestNowMs ?? Date.now(),
+      // K3 (§1.5.3): colocated custody is in-memory — always ask for the carried enrollment
+      // proof; the kernel produces-or-omits under its own bounds (the adapter decides nothing).
+      includeRosterProof: true,
+    });
+    if (!served || served.ok !== true) break; // the kernel's original instruction stands for the caller
+    envelope.attestations = [...(envelope.attestations ?? []), { queryId: need.queryId, result: served.rows, attestation: served.attestation }];
+    writeWork(eng, `envelope-${seq}.json`, enc.encode(stringifyBig(envelope)));
+    v = offerOnce();
+  }
   // 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 } : {}) }
@@ -1861,6 +1904,36 @@ export function describe(eng, ws) {
 // (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 ATTESTED READ (slice B stage 2 — attested_reads_design.md §4.1, the source side). Serve + SIGN a
+// DECLARED query read over this workspace's own certified fold: the KERNEL derives the rows, pins
+// {genesis, head, fold_root, signer epoch, time} and signs with the PER-CALL-INJECTED read-attestor
+// secret (the `attestationSign` pattern — never persisted). The adapter/host transports the secret and
+// relays the returned `{rows, attestation, leafCount}` OPAQUE — it never constructs, inspects, or
+// modifies the envelope (the bailiff line). `nowMs` = the source clock at serve, injected by the caller.
+export const attestedRead = (eng, ws, { queryId, paramsJson, attestorSecret, nowMs, includeRosterProof }) =>
+  JSON.parse(call(eng.ex, "query", {
+    repoArg: repoArgOf(ws), workspace: ws, branch: BRANCH,
+    queryBytes: b64Json({ op: "attestedRead", queryId, paramsJson: paramsJson || "{}", attestorSecret, nowMs: nowMs ?? Date.now(), sourceWorkspace: ws, ...(includeRosterProof ? { includeRosterProof: true } : {}) }),
+  }, eng.STDERR));
+
+// THE KERNEL-INSTRUCTED MISSING-EVIDENCE PARSE (stage 2 §4.1): the one gate's typed
+// `attested-read-unreachable` refusal NAMES the exact fetch — queryId + source + args. This parses it so
+// a caller (the colocation short-circuit below; the web client's pre-fetch convenience) can fulfil the
+// instruction and retry. Returns { queryId, from, args } or null. The kernel instructs; nobody guesses.
+export function parseAttestedReadNeed(error) {
+  const m = /attested-read-unreachable: read\('([^']+)', \{from: '([^']+)'\}\) args=(.*?) has no injected attestation/
+    .exec(String(error || ""));
+  if (!m) return null;
+  // The refusal may surface through a JSON-quoting layer (the engine's Threw detail) — the args
+  // blob's quotes then arrive backslash-escaped. Unescape a level at a time until it parses.
+  let blob = m[3];
+  for (let i = 0; i < 4; i++) {
+    try { return { queryId: m[1], from: m[2], args: JSON.parse(blob) }; }
+    catch { blob = blob.replace(/\\(["\\])/g, "$1"); }
+  }
+  return null;
+}
 // 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
@@ -2746,3 +2819,48 @@ export function warmEngine(eng) {
   // not a top-level adapter verb. Still post-ack (the adapter calls warmEngine off the write critical path).
   return JSON.parse(call(eng.ex, "query", { repoArg: "/work", workspace: "root", queryBytes: b64Json({ op: "warm" }), branch: BRANCH }, eng.STDERR));
 }
+
+/**
+ * ATTESTED READS §5.2 (stage 3) — THE BATCH-SEAL DRIVER. The adapter's ONLY roles here are
+ * SCHEDULING (when to ask) and TRANSPORT (carrying the kernel's own snapshot back as an offer)
+ * — the debounced-admission-alarm precedent: the kernel decides WHAT a seal is (the
+ * `attestationOpenBatch` snapshot + `shouldSeal` verdict + the gate's Merkle-root demand);
+ * this function decides nothing. Call it on a timer / after serves / on unmount
+ * (`{unmounting: true}` forces pending batches to seal — a batch never dies silently).
+ * A failed seal offer LEAVES the accumulator intact (retry next tick, never a silent drop);
+ * only an ADMITTED seal clears the sealed snapshot (`attestationBatchClear`).
+ *
+ * `domain` names the installed law that exports `recordAttestationBatch` (the framework
+ * directive rides the composing law); `controllerHash` is that law's content hash. The offer
+ * is authored AS `workspace:read-attestor` (the enrolled signer — §1.2's "one key, two
+ * duties"); on a warranted workspace pass `opts.authorOpts` with the signing material.
+ */
+export function sealAttestationBatches(eng, ws, domain, controllerHash, opts = {}) {
+  const snap = JSON.parse(call(eng.ex, "query", {
+    repoArg: repoArgOf(ws), workspace: ws, branch: BRANCH,
+    queryBytes: b64Json({ op: "attestationOpenBatch", repoArg: repoArgOf(ws), nowMs: opts.nowMs ?? Date.now(), unmounting: !!opts.unmounting }),
+  }, eng.STDERR));
+  const outcomes = [];
+  for (const b of snap.batches ?? []) {
+    if (b.leafCount === 0) continue;
+    if (!(b.shouldSeal || opts.force)) continue;
+    const payload = {
+      batchId: b.batchId, batchRoot: b.batchRoot, leafCount: b.leafCount, leaves: b.leaves,
+      firstAt: b.firstAt, lastAt: b.lastAt, headAtSeal: b.headAtSeal,
+      foldRootAtSeal: b.foldRootAtSeal, signerKeyHash: b.signerKeyHash,
+    };
+    const r = author(eng, ws, domain, "recordAttestationBatch", payload, controllerHash, {
+      actor: "workspace:read-attestor", ...(opts.authorOpts ?? {}),
+    });
+    if (!r.ok) {
+      outcomes.push({ batchId: b.batchId, ok: false, error: r.error }); // retained — retries next call
+      continue;
+    }
+    JSON.parse(call(eng.ex, "query", {
+      repoArg: repoArgOf(ws), workspace: ws, branch: BRANCH,
+      queryBytes: b64Json({ op: "attestationBatchClear", batchId: b.batchId, leafCount: b.leafCount }),
+    }, eng.STDERR));
+    outcomes.push({ batchId: b.batchId, ok: true, leafCount: b.leafCount, intent: r.intentOut });
+  }
+  return outcomes;
+}