@githolon/testing 0.3.0 → 0.4.0

package/package.json

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

@@ -289,6 +289,15 @@ export function scopedReads(eng) {
     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;
@@ -358,7 +367,15 @@ const groupOf = (read, data) => {
   return v === undefined || v === null ? undefined : String(v);
 };
 const tallyOf = (eng, ws, read, group) =>
-  read.kind === "count" ? count(eng, ws, read.id, group).count : sum(eng, ws, read.id, group).sum;
+  read.kind === "count" ? count(eng, ws, read.id, group).count
+  : read.kind === "sum" ? sum(eng, ws, read.id, group).sum
+  : extremum(eng, ws, read.id, read.kind, group).value; // min|max — null = empty group, never 0
+/** Is a scoped read an extremum kind (the slice-8 non-additive lane)? */
+const isExtremumRead = (read) => read.kind === "min" || read.kind === "max";
+/** Does `next` extremize-improve (or equal) `prev` for the read's kind? null = empty. */
+const extremumMonotone = (read, prev, next) =>
+  (next === null && prev === null) ||
+  (next !== null && (prev === null || (read.kind === "min" ? next <= prev : next >= prev)));
 
 /**
  * Begin one admitted intent's summary capture: snapshot the touched aggregates +
@@ -405,21 +422,44 @@ function finishSummaryCapture(eng, ws, ctx, cap, oid, intentId) {
     const [readId, group] = splitSummaryKey(key);
     const read = ctx.reads.find((r) => r.id === readId);
     const after = tallyOf(eng, ws, read, group);
-    const before = cap.preTallies.get(key) ?? 0;
-    if (after !== before) deltas.push({ readId, group, delta: after - before });
+    if (isExtremumRead(read)) {
+      // SLICE 8 — extremum kinds: the event carries the POST-INTENT ABSOLUTE
+      // (null = the group emptied — never a fabricated 0); a non-monotone step
+      // is a RETRACTION the subtotal must declare (`rederived` — the value IS
+      // the projection's maintained re-derivation, the suffix oracle).
+      const before = cap.preTallies.has(key) ? cap.preTallies.get(key) : null;
+      if (after !== before) {
+        deltas.push({ readId, group, delta: after });
+        if (!extremumMonotone(read, before, after)) ctx.rederived.add(key);
+      }
+    } else {
+      const before = cap.preTallies.get(key) ?? 0;
+      if (after !== before) deltas.push({ readId, group, delta: after - before });
+    }
     ctx.values.set(key, { read, group, value: after });
   }
   // The synthetic row-count read: existence flips, with the projection as oracle.
   // The ABSOLUTE rides relative to the coordinator-held value (the HOST closes it
   // at emit time — a shard never enumerates its own whole projection per batch).
+  // SLICE 8 — EXACT PER-HOME SUBTOTALS: each flip is also attributed to its HOME
+  // (the row id's route tag, or the row id itself for an axis root) so the split
+  // packer can move precisely-sized home sets instead of a uniform estimate.
   let rowsDelta = 0;
   for (const [aggregateId, before] of cap.pre) {
     const rows = qById(eng, ws, aggregateId);
     const type = rows.length ? rows[0].type : before ? before.type : undefined;
     if (type === undefined || !tenantTypes(eng).has(type)) continue; // tenant rows only
     const existsAfter = rows.length > 0;
-    if (!before && existsAfter) rowsDelta += 1;
-    else if (before && !existsAfter) rowsDelta -= 1;
+    const flip = !before && existsAfter ? 1 : before && !existsAfter ? -1 : 0;
+    if (flip === 0) continue;
+    rowsDelta += flip;
+    const homeKey = ctx.homeKeySet && ctx.homeKeySet.has(aggregateId)
+      ? aggregateId
+      : ctx.homeTags ? ctx.homeTags.get(routeTagHexOfMintedId(aggregateId) ?? "") : undefined;
+    if (homeKey !== undefined) {
+      deltas.push({ readId: NOMOS_SHARD_ROWS_READ, group: homeKey, delta: flip });
+      ctx.rowsByHome.set(homeKey, (ctx.rowsByHome.get(homeKey) ?? 0) + flip);
+    }
   }
   if (rowsDelta !== 0) {
     deltas.push({ readId: NOMOS_SHARD_ROWS_READ, group: "", delta: rowsDelta });
@@ -438,26 +478,36 @@ function finishSummaryCapture(eng, ws, ctx, cap, oid, intentId) {
  */
 function summaryOfCapture(ctx, fromOid, toOid) {
   if (ctx.events.length === 0 || !toOid || fromOid === toOid) return null;
+  // Buckets the EVIDENCE touched must carry their claim even when the net change
+  // is zero (the gate refuses an event delta no subtotal claims — and a same-value
+  // extremum claim may still ride a declared retraction, e.g. add-then-retract).
+  const touched = new Set();
+  for (const ev of ctx.events) for (const d of ev.deltas) touched.add(summaryKey(d.readId, d.group));
   const subtotals = [];
   for (const [key, cur] of ctx.values) {
+    const extremum = isExtremumRead(cur.read);
     const prev = ctx.prevs.get(key);
-    const prevValue = prev ? prev.value : 0;
-    if (cur.value === prevValue) continue; // untouched-in-net — carries nothing
+    const prevValue = prev ? prev.value : extremum ? null : 0;
+    if (cur.value === prevValue && !touched.has(key)) continue; // untouched-in-net — carries nothing
     subtotals.push({
       readId: cur.read.id,
       group: cur.group,
       kind: cur.read.kind,
       prev: prevValue,
       value: cur.value,
+      ...(extremum && ctx.rederived.has(key) ? { rederived: true } : {}),
     });
   }
-  if (subtotals.length === 0 && ctx.rowsDelta === 0) return null;
+  if (subtotals.length === 0 && ctx.rowsDelta === 0 && ctx.rowsByHome.size === 0) return null;
   return {
     fromOid: fromOid || "",
     toOid,
     subtotals: subtotals.sort((a, b) => (summaryKey(a.readId, a.group) < summaryKey(b.readId, b.group) ? -1 : 1)),
     events: ctx.events,
     rowsDelta: ctx.rowsDelta,
+    // SLICE 8: the exact per-home row deltas — the host closes each against the
+    // coordinator-held per-home subtotal exactly like the "" grand total.
+    rowsByHome: Object.fromEntries([...ctx.rowsByHome.entries()].sort((a, b) => (a[0] < b[0] ? -1 : 1))),
   };
 }
 
@@ -477,12 +527,31 @@ export async function deriveSummarySuffix(eng, ws, fromOid) {
   const commits = await git.log({ fs: eng.fs, gitdir, ref: BRANCH });
   commits.reverse(); // genesis → head
   const state = new Map(); // aggregateId -> { type, fields: Map }
-  const running = new Map(); // summaryKey -> value
+  const running = new Map(); // summaryKey -> value (ADDITIVE kinds)
   const bump = (key, d) => running.set(key, (running.get(key) ?? 0) + d);
-  let prevs = null; // snapshot at fromOid
+  // SLICE 8 — the EXTREMUM fold state: per bucket, the contributing rows' values
+  // (aggregateId -> value) + the running extremum (null = no contributing member).
+  // A monotone step extremizes O(1); a retraction recomputes the bucket (the
+  // suffix lane IS the re-derivation oracle — explicit, O(bucket)).
+  const extRows = new Map(); // summaryKey -> Map(aggregateId -> value)
+  const extRunning = new Map(); // summaryKey -> number | null
+  const extRederived = new Set(); // buckets retracted INSIDE the suffix
+  const extBucketRows = (key) => { let m = extRows.get(key); if (!m) { m = new Map(); extRows.set(key, m); } return m; };
+  const recomputeExt = (read, key) => {
+    let v = null;
+    const m = extRows.get(key);
+    if (m) for (const x of m.values()) v = v === null ? x : read.kind === "min" ? Math.min(v, x) : Math.max(v, x);
+    return v;
+  };
+  // SLICE 8 — the per-home attribution table, folded from the chain's OWN receipt
+  // rows (the receipt leg rides ahead of the first homed write by construction).
+  const homeKeySet = new Set();
+  const homeTags = new Map(); // route tag hex -> homeKey
+  let prevs = null; // snapshot at fromOid (additive)
+  let extPrevs = null; // snapshot at fromOid (extremum)
   let events = [];
   let inSuffix = fromOid === "" || fromOid === undefined;
-  if (inSuffix) prevs = new Map();
+  if (inSuffix) { prevs = new Map(); extPrevs = new Map(); }
   let sawFrom = inSuffix;
   for (const c of commits) {
     let blob = null;
@@ -515,44 +584,111 @@ export async function deriveSummarySuffix(eng, ws, fromOid) {
         cur.exists = true;
         state.set(ev.aggregate, cur);
         const effType = cur.type ?? newType;
+        // The per-home attribution table (slice 8): receipts register their home.
+        if (effType === "NomosHomeReceipt") {
+          const hk = cur.fields.get("homeKey");
+          if (typeof hk === "string" && hk && !homeKeySet.has(hk)) {
+            homeKeySet.add(hk);
+            homeTags.set(await routeTagHexOfHomeKey(hk), hk);
+          }
+        }
         if (!existedBefore && effType !== undefined && tenantTypes(eng).has(effType)) {
           bump(summaryKey(NOMOS_SHARD_ROWS_READ, ""), 1);
           deltas.push({ readId: NOMOS_SHARD_ROWS_READ, group: "", delta: 1 });
+          // SLICE 8 — the EXACT per-home row subtotal: the same flip, attributed
+          // to its home (the id's route-tag slot, or the id itself for an axis root).
+          const homeKey = homeKeySet.has(ev.aggregate)
+            ? ev.aggregate
+            : homeTags.get(routeTagHexOfMintedId(ev.aggregate) ?? "");
+          if (homeKey !== undefined) {
+            bump(summaryKey(NOMOS_SHARD_ROWS_READ, homeKey), 1);
+            deltas.push({ readId: NOMOS_SHARD_ROWS_READ, group: homeKey, delta: 1 });
+          }
         }
         for (const read of reads) {
           if (read.of !== cur.type) continue;
           const before = tallyBefore.get(read.id) ?? null;
           const after = contribution(read, cur);
-          for (const d of contributionDiff(read, before, after)) {
-            bump(summaryKey(d.readId, d.group), d.delta);
-            deltas.push(d);
+          if (isExtremumRead(read)) {
+            // Update the bucket row-sets, then re-extremize each touched bucket.
+            const touchedBuckets = new Set();
+            if (before) {
+              const bk = summaryKey(read.id, before.group);
+              if (!after || after.group !== before.group) extBucketRows(bk).delete(ev.aggregate);
+              touchedBuckets.add(bk);
+            }
+            if (after) {
+              const ak = summaryKey(read.id, after.group);
+              extBucketRows(ak).set(ev.aggregate, after.value);
+              touchedBuckets.add(ak);
+            }
+            for (const bk of touchedBuckets) {
+              const ov = extRunning.has(bk) ? extRunning.get(bk) : null;
+              const nv = recomputeExt(read, bk);
+              if (nv === ov) continue;
+              extRunning.set(bk, nv);
+              if (inSuffix) {
+                if (!extremumMonotone(read, ov, nv)) extRederived.add(bk);
+                const [, group] = splitSummaryKey(bk);
+                deltas.push({ readId: read.id, group, delta: nv, __extremum: true });
+              }
+            }
+          } else {
+            for (const d of contributionDiff(read, before, after)) {
+              bump(summaryKey(d.readId, d.group), d.delta);
+              deltas.push(d);
+            }
           }
         }
       }
     }
     if (inSuffix && deltas.length) {
-      // Coalesce same-(read,group) deltas within one intent.
+      // Coalesce same-(read,group) deltas within one intent: ADDITIVE entries sum
+      // (zero-nets drop); EXTREMUM entries carry absolutes — the LAST one stands.
       const byKey = new Map();
-      for (const d of deltas) byKey.set(summaryKey(d.readId, d.group), (byKey.get(summaryKey(d.readId, d.group)) ?? 0) + d.delta);
+      const extLast = new Map();
+      for (const d of deltas) {
+        const k = summaryKey(d.readId, d.group);
+        if (d.__extremum) extLast.set(k, d.delta);
+        else byKey.set(k, (byKey.get(k) ?? 0) + d.delta);
+      }
       const merged = [...byKey.entries()].filter(([, d]) => d !== 0).map(([k, d]) => {
         const [readId, group] = splitSummaryKey(k);
         return { readId, group, delta: d };
       });
+      for (const [k, v] of extLast) {
+        const [readId, group] = splitSummaryKey(k);
+        merged.push({ readId, group, delta: v });
+      }
       if (merged.length) events.push({ oid: c.oid, intentId, deltas: merged });
     }
-    if (!inSuffix && c.oid === fromOid) { inSuffix = true; sawFrom = true; prevs = new Map(running); }
+    if (!inSuffix && c.oid === fromOid) { inSuffix = true; sawFrom = true; prevs = new Map(running); extPrevs = new Map(extRunning); }
   }
   if (!sawFrom) return { ok: false, error: `fromOid ${String(fromOid).slice(0, 12)} is not on this shard's main — cannot derive the suffix` };
+  // Buckets the suffix EVIDENCE touched must carry their claim even when net-zero
+  // (the gate refuses an event delta no subtotal claims).
+  const touched = new Set();
+  for (const ev of events) for (const d of ev.deltas) touched.add(summaryKey(d.readId, d.group));
   const subtotals = [];
   const keys = new Set([...running.keys(), ...prevs.keys()]);
   for (const key of keys) {
     const value = running.get(key) ?? 0;
     const prev = prevs.get(key) ?? 0;
-    if (value === prev) continue;
+    if (value === prev && !touched.has(key)) continue;
     const [readId, group] = splitSummaryKey(key);
     const read = reads.find((r) => r.id === readId);
     subtotals.push({ readId, group, kind: readId === NOMOS_SHARD_ROWS_READ ? "rows" : read ? read.kind : "count", prev, value });
   }
+  const extKeys = new Set([...extRunning.keys(), ...(extPrevs ? extPrevs.keys() : [])]);
+  for (const key of extKeys) {
+    const value = extRunning.has(key) ? extRunning.get(key) : null;
+    const prev = extPrevs && extPrevs.has(key) ? extPrevs.get(key) : null;
+    if (value === prev && !touched.has(key)) continue;
+    const [readId, group] = splitSummaryKey(key);
+    const read = reads.find((r) => r.id === readId);
+    if (!read) continue;
+    subtotals.push({ readId, group, kind: read.kind, prev, value, ...(extRederived.has(key) ? { rederived: true } : {}) });
+  }
   if (subtotals.length === 0) return { ok: true, upToDate: true, head };
   return {
     ok: true,
@@ -577,6 +713,9 @@ function contribution(read, cur) {
   if (group === undefined) return null;
   if (read.kind === "count") return { group, value: 1 };
   const raw = cur.fields.get(read.field);
+  // EXTREMUM kinds (slice 8): a row whose value field is unfolded CONTRIBUTES
+  // NOTHING — fabricating a 0 would forge a fake minimum (the extremum.ts law).
+  if (isExtremumRead(read) && typeof raw !== "number") return null;
   return { group, value: typeof raw === "number" ? raw : 0 };
 }
 function contributionDiff(read, before, after) {
@@ -612,6 +751,26 @@ export function countTenantRows(eng, ws) {
   return total;
 }
 
+/** The EXACT per-home recount (slice 8 — the explicit O(rows) audit walk, per-home
+ *  edition): projected TENANT rows attributed to each named home by the row id's
+ *  route-tag slot (or the id itself for an axis root). Shared by the strike-bearing
+ *  summary close and deep-verify — the same one definition as the capture/suffix. */
+export async function countTenantRowsByHome(eng, ws, homeKeys) {
+  const keySet = new Set(homeKeys);
+  const tagOf = new Map();
+  for (const hk of homeKeys) tagOf.set(await routeTagHexOfHomeKey(hk), hk);
+  const out = new Map();
+  for (const hk of homeKeys) out.set(hk, 0);
+  for (const type of tenantTypes(eng)) {
+    for (const r of query(eng, ws, "aggregatesByType", JSON.stringify({ __type: type }))) {
+      const id = String(r.id || "");
+      const hk = keySet.has(id) ? id : tagOf.get(routeTagHexOfMintedId(id) ?? "");
+      if (hk !== undefined) out.set(hk, (out.get(hk) ?? 0) + 1);
+    }
+  }
+  return out;
+}
+
 /**
  * Walk a mounted workspace's main (genesis → head) and collect every NON-STRUCK
  * intent homed on one of `homeKeys` — judged by the SAME hash-bearing `routes`
@@ -731,13 +890,30 @@ export async function summaryCloseAgainstHeld(eng, ws, heldRows, heldFrontier) {
   if (head === heldFrontier) return { ok: true, upToDate: true, head };
   const subtotals = [];
   const deltas = [];
+  // SLICE 8: the per-home rows recount, computed ONCE over all held per-home rows.
+  const heldHomes = heldRows
+    .map((row) => row.data || row)
+    .filter((d) => d.readId === NOMOS_SHARD_ROWS_READ && typeof d.group === "string" && d.group !== "")
+    .map((d) => d.group);
+  const byHome = heldHomes.length ? await countTenantRowsByHome(eng, ws, heldHomes) : new Map();
   for (const row of heldRows) {
     const d = row.data || row;
     if (typeof d.readId !== "string") continue;
     const group = typeof d.group === "string" ? d.group : "";
+    if (d.kind === "min" || d.kind === "max") {
+      // EXTREMUM kinds: the close IS a re-derivation (a §6 seal re-shaped the
+      // fold — non-monotone by construction); the projection's maintained
+      // extremum is the oracle; the claim rides DECLARED (`rederived: true`).
+      const heldVal = d.empty === 1 || typeof d.value !== "number" ? null : d.value;
+      const nowVal = extremum(eng, ws, d.readId, d.kind, group).value;
+      if (nowVal === heldVal) continue;
+      subtotals.push({ readId: d.readId, group, kind: d.kind, prev: heldVal, value: nowVal, rederived: true });
+      deltas.push({ readId: d.readId, group, delta: nowVal }); // the post-close ABSOLUTE
+      continue;
+    }
     const held = typeof d.value === "number" ? d.value : 0;
     let now;
-    if (d.readId === NOMOS_SHARD_ROWS_READ) now = countTenantRows(eng, ws);
+    if (d.readId === NOMOS_SHARD_ROWS_READ) now = group === "" ? countTenantRows(eng, ws) : (byHome.get(group) ?? 0);
     else if (d.kind === "sum") now = sum(eng, ws, d.readId, group).sum;
     else now = count(eng, ws, d.readId, group).count;
     if (now === held) continue;
@@ -893,22 +1069,40 @@ export async function deepVerifyShard(eng, shardWs, shardLedger, coordinatorRows
   await mountWorkspace(eng, shardWs, shardLedger);
   const checks = [];
   let allMatch = true;
+  // SLICE 8: the per-home rows recount, computed ONCE over all held per-home rows.
+  const heldHomes = coordinatorRows
+    .map((row) => row.data || row)
+    .filter((d) => d.readId === NOMOS_SHARD_ROWS_READ && typeof d.group === "string" && d.group !== "")
+    .map((d) => d.group);
+  const byHome = heldHomes.length ? await countTenantRowsByHome(eng, shardWs, heldHomes) : new Map();
   for (const row of coordinatorRows) {
     const d = row.data || row;
     if (typeof d.readId !== "string") continue;
+    const group = d.group ?? "";
+    if (d.kind === "min" || d.kind === "max") {
+      // EXTREMUM rows (slice 8): recompute off the replayed projection's maintained
+      // extrema lane; the coordinator's `empty:1` flag means NULL, never 0.
+      const heldVal = d.empty === 1 || typeof d.value !== "number" ? null : d.value;
+      const recomputed = extremum(eng, shardWs, d.readId, d.kind, group).value;
+      const match = recomputed === heldVal;
+      if (!match) allMatch = false;
+      checks.push({ readId: d.readId, group, kind: d.kind, coordinator: heldVal, shard: recomputed, match });
+      continue;
+    }
     let recomputed;
     if (d.readId === NOMOS_SHARD_ROWS_READ) {
-      // Total projected rows: enumerate the manifest's aggregate types (an explicit
-      // O(rows) audit walk — never an implicit read cost).
-      recomputed = countTenantRows(eng, shardWs);
+      // Projected rows: enumerate the manifest's aggregate types (an explicit
+      // O(rows) audit walk — never an implicit read cost); a per-home row (group
+      // = the home key) recounts only that home's attributed rows.
+      recomputed = group === "" ? countTenantRows(eng, shardWs) : (byHome.get(group) ?? 0);
     } else if (d.kind === "sum") {
-      recomputed = sum(eng, shardWs, d.readId, d.group ?? "").sum;
+      recomputed = sum(eng, shardWs, d.readId, group).sum;
     } else {
-      recomputed = count(eng, shardWs, d.readId, d.group ?? "").count;
+      recomputed = count(eng, shardWs, d.readId, group).count;
     }
     const match = recomputed === d.value;
     if (!match) allMatch = false;
-    checks.push({ readId: d.readId, group: d.group ?? "", coordinator: d.value, shard: recomputed, match });
+    checks.push({ readId: d.readId, group, coordinator: d.value, shard: recomputed, match });
   }
   const head = await git.resolveRef({ fs: eng.fs, gitdir: gitdirOf(shardWs), ref: BRANCH }).catch(() => null);
   return {
@@ -1061,8 +1255,22 @@ export async function admitAll(eng, ws, ledger, { refuseDomains = [], shardRouti
   // O(touched)); the HOST authors the coalesced `nomosPropagateSummary` Order into
   // the coordinator afterwards. The coordinator's gate re-verifies everything.
   const summaryCtx = shardRouting && shardRouting.selfLabel && scopedReads(eng).length > 0
-    ? { reads: scopedReads(eng), prevs: new Map(), values: new Map(), events: [], rowsDelta: 0 }
+    ? { reads: scopedReads(eng), prevs: new Map(), values: new Map(), events: [], rowsDelta: 0, rederived: new Set(), rowsByHome: new Map(), homeTags: new Map(), homeKeySet: new Set() }
     : null;
+  if (summaryCtx) {
+    // SLICE 8 — the per-home attribution table, off the shard's OWN receipts
+    // (law-state: which homes this chain owns). A row id whose route-tag slot
+    // matches a home's tag — or which IS a home key (an axis root) — attributes
+    // its existence flip to that home's exact row subtotal.
+    try {
+      for (const r of query(eng, ws, "aggregatesByType", JSON.stringify({ __type: "NomosHomeReceipt" }))) {
+        const hk = r.data && typeof r.data.homeKey === "string" ? r.data.homeKey : null;
+        if (!hk) continue;
+        summaryCtx.homeKeySet.add(hk);
+        summaryCtx.homeTags.set(await routeTagHexOfHomeKey(hk), hk);
+      }
+    } catch (e) { log("home-tag-table-error", { ws, error: String(e).slice(0, 200) }); }
+  }
   const headBefore = summaryCtx ? await git.resolveRef({ fs: eng.fs, gitdir, ref: BRANCH }).catch(() => null) : null;
   for (const [cid, head] of Object.entries(sessions)) {
     const ref = `refs/heads/session/${cid}`;