onto-mcp 0.4.12 → 0.4.13

package/dist/core-runtime/reconstruct/comprehension-semantic-map.js

@@ -0,0 +1,771 @@
+import { createHash } from "node:crypto";
+import { reduceNodeGroundHash, reduceNodeKey, } from "./comprehension-reduce.js";
+// ── N1/N2 two-sided reconciliation ───────────────────────────────────────────
+const VALUE_SHAPE = "value_shape";
+/** ±1: a value-shape seam spans last_prev_format_row / first_new_format_row (2 rows); ±1 covers that
+ *  span without widening it (design §13.3). Exact-row match is preferred; tolerance is the fallback. */
+export const ANCHOR_ROW_TOLERANCE = 1;
+const cmpStr = (x, y) => (x < y ? -1 : x > y ? 1 : 0);
+/** Legal enum surfaces — the honesty validator is TOTAL over these (a value outside them is malformed
+ *  and fails closed; review F2 / onto issue-001/007/009/014). */
+const VALID_ANCHOR_STATUS = new Set(["anchored", "unanchored"]);
+const VALID_VERIFICATION = new Set([
+    "structural_location_only",
+    "unverified",
+    "adversarial_confirmed",
+    "adversarial_refuted",
+]);
+/** Single literal source for the adversarial-verdict vocabulary (wiring design 20260702 §15.1): BOTH
+ *  the exported verdict type and the runtime allowlist derive from this tuple, so the type and the
+ *  Set cannot drift apart (a separate union + Set pair stays compile-green when only one is edited;
+ *  R3 W1-01 / onto issue-001·003). Exported so the drift-guard test proves the same-source derivation. */
+export const ADVERSARIAL_RESULTS = ["adversarial_confirmed", "adversarial_refuted"];
+const _verdictExact = [true, true];
+void _verdictExact;
+// ReadonlySet<union> (not Set<string>): a member added to the SET literal that is not in the tuple
+// now fails the build too (the runtime .has() guard against JS-level bogus values is unchanged).
+const VALID_ADVERSARIAL_RESULT = new Set(ADVERSARIAL_RESULTS);
+/** Canonical TOTAL order over value-shape seams (full witness tuple so equal-row seams from different
+ *  provenance never tie by input order; review F7 — mirrors comprehension-reduce canonicalBoundaries). */
+function seamCmp(a, b) {
+    return (cmpStr(a.sheet, b.sheet) ||
+        a.column_index - b.column_index ||
+        a.first_new_format_row - b.first_new_format_row ||
+        a.last_prev_format_row - b.last_prev_format_row ||
+        cmpStr(a.boundary_kind, b.boundary_kind) ||
+        cmpStr(a.prev_shape, b.prev_shape) ||
+        cmpStr(a.new_shape, b.new_shape));
+}
+/** Two-sided deterministic reconciliation (design §13.3 / N1 / N2 / codex-F3). For a node's LLM
+ *  boundaries and its Layer-1 value-shape seams, assign each boundary anchored|unanchored and record a
+ *  covered|missed_by_llm status for EVERY seam. Matching is a 1:1 assignment (a seam anchors at most
+ *  one boundary), exact-row first then nearest-within-tolerance, canonical-order tie-break — so dense
+ *  seams cannot blanket-anchor every boundary (L2H-2) and the result is order-stable (codex-F3). */
+export function reconcileBoundaries(raw, reduceNode) {
+    const seams = reduceNode.boundaries.filter((b) => b.boundary_kind === VALUE_SHAPE).slice().sort(seamCmp);
+    const seamMatched = seams.map(() => false);
+    const matchedSeamOf = new Map(); // raw index -> seam index
+    // Canonical LLM-boundary order (row, then character tuple, then input index) so passes are stable.
+    const order = raw
+        .map((b, i) => ({ b, i }))
+        .sort((x, y) => x.b.row - y.b.row ||
+        cmpStr(x.b.character_before, y.b.character_before) ||
+        cmpStr(x.b.character_after, y.b.character_after) ||
+        x.i - y.i);
+    // Pass 1 — exact row (LLM row === seam.first_new_format_row). 1:1, canonical order.
+    for (const { b, i } of order) {
+        for (let si = 0; si < seams.length; si += 1) {
+            const s = seams[si];
+            if (!s || seamMatched[si])
+                continue;
+            if (s.first_new_format_row === b.row) {
+                seamMatched[si] = true;
+                matchedSeamOf.set(i, si);
+                break;
+            }
+        }
+    }
+    // Pass 2 — nearest unmatched seam within tolerance; strict-less keeps the canonically-first seam on a
+    // distance tie (seams are canonically sorted), so the outcome is order-stable.
+    for (const { b, i } of order) {
+        if (matchedSeamOf.has(i))
+            continue;
+        let bestSi = -1;
+        let bestDist = Number.POSITIVE_INFINITY;
+        for (let si = 0; si < seams.length; si += 1) {
+            const s = seams[si];
+            if (!s || seamMatched[si])
+                continue;
+            const dist = Math.abs(s.first_new_format_row - b.row);
+            if (dist <= ANCHOR_ROW_TOLERANCE && dist < bestDist) {
+                bestDist = dist;
+                bestSi = si;
+            }
+        }
+        if (bestSi >= 0) {
+            seamMatched[bestSi] = true;
+            matchedSeamOf.set(i, bestSi);
+        }
+    }
+    const boundaries = raw.map((b, i) => {
+        const anchored = matchedSeamOf.has(i);
+        return {
+            row: b.row,
+            character_before: b.character_before,
+            character_after: b.character_after,
+            anchor_status: anchored ? "anchored" : "unanchored",
+            verification: anchored ? "structural_location_only" : "unverified",
+        };
+    });
+    const coverage = seams.map((s, si) => ({
+        // Reconstruct from the DECLARED fields only (round-4): a bare spread would clone extra nested own
+        // props by reference (aliasing the source boundary); the explicit projection drops them and clones.
+        boundary_ref: {
+            sheet: s.sheet,
+            column_index: s.column_index,
+            boundary_kind: s.boundary_kind,
+            prev_shape: s.prev_shape,
+            new_shape: s.new_shape,
+            last_prev_format_row: s.last_prev_format_row,
+            first_new_format_row: s.first_new_format_row,
+        },
+        status: seamMatched[si] ? "covered" : "missed_by_llm",
+    }));
+    return { boundaries, coverage };
+}
+// ── N4 recursive epoch contribution (allowlisted, non-circular) ──────────────
+export const SEMANTIC_EPOCH_PREIMAGE_ALLOWLIST = [
+    "layer1_ground_hash",
+    "child_contributions",
+    "reduce_reader_model_identity",
+    "reduce_prompt_sha256",
+    "reduce_schema_tool_version",
+    "comprehension_version",
+    "over_context_gate_config_sha256",
+    "over_context_gate_logic_sha256",
+];
+const ALLOWLIST_SET = new Set(SEMANTIC_EPOCH_PREIMAGE_ALLOWLIST);
+/** Fail-closed ALLOWLIST guard (design §13.4 / N7 / C8). Unlike the sibling denylist
+ *  (assertGatingKeyExcludesInEpochOutput, which must enumerate every forbidden LLM field), an
+ *  allowlist rejects an UNKNOWN key by construction, so a newly-added LLM output cannot silently reach
+ *  the gating key. Also rejects a NESTED object smuggling a field in (codex residual): every value must
+ *  be a string, except child_contributions which must be a string[]. */
+export function assertPreImageKeysAllowlisted(pre) {
+    for (const k of Object.keys(pre)) {
+        if (!ALLOWLIST_SET.has(k)) {
+            throw new Error(`comprehension-semantic-map: epoch pre-image has non-allowlisted key '${k}' (§13.4 allowlist — a non-deterministic/LLM field could gate its own reuse). Permitted: ${SEMANTIC_EPOCH_PREIMAGE_ALLOWLIST.join(", ")}.`);
+        }
+    }
+    for (const k of SEMANTIC_EPOCH_PREIMAGE_ALLOWLIST) {
+        // OWN key only (review F3 / onto issue-002/005/006/…): `k in pre` accepts an INHERITED field, but
+        // the canonical spread/stableJson hashes OWN keys only — so a prototype-backed pre-image would pass
+        // validation while its required deterministic fields silently drop from the contribution key.
+        if (!Object.hasOwn(pre, k)) {
+            throw new Error(`comprehension-semantic-map: epoch pre-image missing OWN required key '${k}' (§13.4 — inherited keys are not hashed).`);
+        }
+        const v = pre[k];
+        if (k === "child_contributions") {
+            if (!Array.isArray(v) || v.some((x) => typeof x !== "string")) {
+                throw new Error("comprehension-semantic-map: child_contributions must be string[] (no nested objects — §13.4 nested-injection guard).");
+            }
+        }
+        else if (typeof v !== "string") {
+            throw new Error(`comprehension-semantic-map: epoch pre-image field '${k}' must be a string (no nested objects — §13.4 nested-injection guard).`);
+        }
+    }
+}
+function stableJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(",")}]`;
+    if (value && typeof value === "object") {
+        return `{${Object.keys(value)
+            .sort()
+            .map((k) => `${JSON.stringify(k)}:${stableJson(value[k])}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
+/** The recursive per-node epoch contribution (= subtree_epoch_contribution). NON-CIRCULAR by
+ *  construction (allowlist admits only deterministic fields). Folding child_contributions makes a
+ *  parent re-derive on ANY descendant structural change EVEN WHEN the parent's own reduceNodeGroundHash
+ *  is byte-identical (e.g. a non-lowest child's limiting_witness change — comprehension-reduce.ts keeps
+ *  only witnessCandidates[0], and parent edges are first/last only — so the parent ground is stable
+ *  while a child's ground hash rotates; codex tsx probe confirmed cardinality > 0). child_contributions
+ *  is sorted so SIBLING ORDER within a grouping does not perturb the key. NOTE (review F4): unlike the
+ *  Layer-1 GROUND (which is fanin/grouping-INVARIANT), this contribution is TOPOLOGY-DEPENDENT by
+ *  design — a node synthesizes ITS children, so a different fan-in gives genuinely different judgments,
+ *  and the contribution correctly rotates with it (a fan-in change is a re-derive, caught via
+ *  child_contributions, never silent). Production pins the topology with the deterministic over-context
+ *  frontier, whose config + logic sha are folded into the pre-image. */
+export function reduceNodeEpochContribution(pre) {
+    assertPreImageKeysAllowlisted(pre);
+    const canonical = { ...pre, child_contributions: [...pre.child_contributions].sort() };
+    return createHash("sha256").update(stableJson(canonical)).digest("hex");
+}
+// ── N3/N5/N6 fail-closed validators ──────────────────────────────────────────
+/** N5 / codex-F1: child-judgment completeness, subsumed-aware. A `subsumed` node (below the
+ *  accumulation frontier) has no synthesized judgment, so it MUST carry consumed=[]. An accumulating
+ *  node's consumed_child_judgment_keys MUST equal the frontier-direct child set the caller computed.
+ *  Symmetric with comprehension-reduce assertContiguousChildren. */
+export function assertChildJudgmentCoverage(node, expectedConsumedKeys) {
+    if (node.reduce_read_attempt === "subsumed") {
+        if (node.consumed_child_judgment_keys.length > 0) {
+            throw new Error(`comprehension-semantic-map: subsumed node ${reduceNodeKey(node.node_ref)} must consume no child judgments, has ${node.consumed_child_judgment_keys.length} (§13.5 codex-F1).`);
+        }
+        return;
+    }
+    // Reject duplicate consumed keys BEFORE the set comparison (review F8 / onto issue-004): a Set
+    // collapses ["k1","k1"] to {k1}, so a node consuming the same child twice would falsely satisfy
+    // coverage against {k1}. A node consumes each child at most once.
+    if (new Set(node.consumed_child_judgment_keys).size !== node.consumed_child_judgment_keys.length) {
+        throw new Error(`comprehension-semantic-map: duplicate consumed child-judgment key at ${reduceNodeKey(node.node_ref)} (§13.5 N5 — each child is consumed once).`);
+    }
+    const have = new Set(node.consumed_child_judgment_keys);
+    const want = new Set(expectedConsumedKeys);
+    const equal = have.size === want.size && [...want].every((k) => have.has(k));
+    if (!equal) {
+        throw new Error(`comprehension-semantic-map: child-judgment coverage mismatch at ${reduceNodeKey(node.node_ref)} — consumed {${[...have].sort().join(",")}} != expected {${[...want].sort().join(",")}} (§13.5 N5 completeness).`);
+    }
+}
+/** N3 / L2H-5 / codex-F2: the fail-closed verification state machine. Legal (anchor_status,
+ *  verification) combinations, plus the seed-projection rule. `seedBound` = these boundaries are about
+ *  to flow to the seed authoring input. Throws on the first illegal state. */
+export function assertSemanticBoundaryHonesty(node, seedBound) {
+    const at = (b) => `${reduceNodeKey(node.node_ref)}@row${b.row}`;
+    for (const b of node.semantic_boundaries) {
+        // TOTAL over the enum surface (review F2 / onto issue-001/007/009/014): an anchor_status or
+        // verification value OUTSIDE the known set is malformed and fails closed — otherwise a bogus
+        // caller-injected verifier output (e.g. "bogus_status") would slip through the combo checks below.
+        if (!VALID_ANCHOR_STATUS.has(b.anchor_status)) {
+            throw new Error(`comprehension-semantic-map: ${at(b)} unknown anchor_status '${b.anchor_status}' (§13.5 fail-closed enum).`);
+        }
+        if (!VALID_VERIFICATION.has(b.verification)) {
+            throw new Error(`comprehension-semantic-map: ${at(b)} unknown verification '${b.verification}' (§13.5 fail-closed enum).`);
+        }
+        if (b.anchor_status === "anchored" && b.verification !== "structural_location_only") {
+            throw new Error(`comprehension-semantic-map: ${at(b)} anchored boundary must be 'structural_location_only' (anchored corroborates LOCATION only, never content; got '${b.verification}') — §13.5 codex-F2.`);
+        }
+        if (b.anchor_status === "unanchored" && b.verification === "structural_location_only") {
+            throw new Error(`comprehension-semantic-map: ${at(b)} unanchored boundary cannot be 'structural_location_only' (no seam corroborates it) — §13.5 codex-F2.`);
+        }
+        if (seedBound && b.anchor_status === "unanchored" && b.verification === "unverified") {
+            throw new Error(`comprehension-semantic-map: ${at(b)} seed-bound unanchored boundary must be adversarially processed before seed (N3 all-unanchored) — §13.5.`);
+        }
+        if (seedBound && b.verification === "adversarial_refuted") {
+            throw new Error(`comprehension-semantic-map: ${at(b)} adversarial_refuted boundary must be EXCLUDED from seed boundaries (recorded as a refuted disclosure + counted in taint), not carried — §13.5 codex-F2.`);
+        }
+    }
+}
+/** This node's OWN unverified taint: unanchored boundaries not adversarially-confirmed (unverified or
+ *  refuted) + a failed/unread read outcome. */
+export function ownUnverifiedCount(node) {
+    const boundaryUnverified = node.semantic_boundaries.filter((b) => b.anchor_status === "unanchored" && b.verification !== "adversarial_confirmed").length;
+    const attemptUnverified = node.reduce_read_attempt === "failed" || node.reduce_read_attempt === "unread" ? 1 : 0;
+    return boundaryUnverified + attemptUnverified;
+}
+/** The canonical taint census value a node SHOULD carry (own + children). Callers set
+ *  unanchored_unverified_count from this; the validator enforces the fail-closed direction. */
+export function computeUnanchoredUnverifiedCount(node, children) {
+    return children.reduce((acc, c) => acc + c.unanchored_unverified_count, 0) + ownUnverifiedCount(node);
+}
+/** N6: taint monotone. A parent may never UNDERSTATE accumulated unverified taint (fail-closed,
+ *  symmetric with assertHonestyFold). Over-reporting is allowed; understating throws. */
+function assertSafeCount(label, n) {
+    // A non-finite / negative / non-integer count would defeat the monotone comparison (review F6: NaN <
+    // x is false, so a NaN taint would pass silently). Require a safe non-negative integer.
+    if (!Number.isSafeInteger(n) || n < 0) {
+        throw new Error(`comprehension-semantic-map: ${label} must be a non-negative safe integer, got ${n} (§13.5 N6 fail-closed).`);
+    }
+}
+export function assertTaintCensusMonotone(node, children) {
+    assertSafeCount(`taint count at ${reduceNodeKey(node.node_ref)}`, node.unanchored_unverified_count);
+    for (const c of children)
+        assertSafeCount(`child taint count at ${reduceNodeKey(c.node_ref)}`, c.unanchored_unverified_count);
+    const expectedMin = computeUnanchoredUnverifiedCount(node, children);
+    if (node.unanchored_unverified_count < expectedMin) {
+        throw new Error(`comprehension-semantic-map: taint census understated at ${reduceNodeKey(node.node_ref)} — ${node.unanchored_unverified_count} < ${expectedMin} (parent may not understate children + own unverified; §13.5 N6).`);
+    }
+}
+const VALUE_SHAPE_KIND = "value_shape";
+/** Deterministic subtree LEAF count per node (the single over-context metric — NOT row-span or ground
+ *  bytes; §13.6 codex-F5). Throws on a cyclic trace. */
+export function computeSubtreeLeafCounts(trace) {
+    const counts = new Map();
+    const compute = (key, visiting) => {
+        const cached = counts.get(key);
+        if (cached !== undefined)
+            return cached;
+        if (visiting.has(key))
+            throw new Error(`comprehension-semantic-map: cycle at ${key} while counting leaves (§13.6).`);
+        const tnode = trace.nodes.get(key);
+        if (!tnode)
+            throw new Error(`comprehension-semantic-map: trace node missing for ${key} (leaf count).`);
+        visiting.add(key);
+        const n = tnode.child_keys.length === 0 ? 1 : tnode.child_keys.reduce((s, c) => s + compute(c, visiting), 0);
+        visiting.delete(key);
+        counts.set(key, n);
+        return n;
+    };
+    for (const key of trace.nodes.keys())
+        compute(key, new Set());
+    return counts;
+}
+/** Tautological over-context gate LOGIC digest (design §13.4 L2R-2 / ultracode audit F — mirrors
+ *  leaf-reader structureLeafTriggerLogicSha256): hashes the SOURCE of the frontier predicate and its
+ *  metric, so editing either rotates every semantic-map fingerprint without a hand-bumped knob. */
+export function semanticMapGateLogicSha256() {
+    return createHash("sha256")
+        .update(classifyFrontier.toString())
+        .update(" ")
+        .update(computeSubtreeLeafCounts.toString())
+        .digest("hex");
+}
+/** Classify every REACHABLE node (from root) into its frontier role, top-down (§13.6). A leaf can never
+ *  accumulate (no children), so it is a frontier (or subsumed under one). Deterministic. */
+export function classifyFrontier(trace, overContextBudget) {
+    // A leaf-count budget must be a real non-negative integer (review F4 / onto issue-001/005/007/…):
+    // NaN/Infinity would silently collapse the frontier to the root instead of failing closed.
+    if (!Number.isSafeInteger(overContextBudget) || overContextBudget < 0) {
+        throw new Error(`comprehension-semantic-map: overContextBudget must be a non-negative safe integer (leaf count), got ${overContextBudget} (§13.6 fail-closed).`);
+    }
+    const leafCounts = computeSubtreeLeafCounts(trace);
+    const mode = new Map();
+    const shouldAccumulate = (key) => {
+        const tnode = trace.nodes.get(key);
+        if (!tnode || tnode.child_keys.length === 0)
+            return false; // a leaf never accumulates.
+        const count = leafCounts.get(key); // every node was counted above; a miss is an impossible state.
+        if (count === undefined)
+            throw new Error(`comprehension-semantic-map: no leaf count for ${key} (impossible; §13.6).`);
+        return count > overContextBudget;
+    };
+    const classify = (key, underFrontier) => {
+        const tnode = trace.nodes.get(key);
+        if (!tnode)
+            throw new Error(`comprehension-semantic-map: trace node missing for ${key} (classify).`);
+        const m = underFrontier ? "subsumed" : shouldAccumulate(key) ? "accumulating" : "frontier";
+        mode.set(key, m);
+        const childUnder = m !== "accumulating"; // frontier/subsumed → descendants subsumed.
+        for (const c of tnode.child_keys)
+            classify(c, childUnder);
+    };
+    classify(trace.root_key, false);
+    return mode;
+}
+/** Fail-closed: the trace MUST be a rooted TREE (review F2 / onto issue-002/004). A DAG / diamond /
+ *  duplicate child edge would double-count leaves, classify a shared node order-dependently, or let one
+ *  semantic node be reused through multiple parents. Checks: every child key exists; no duplicate child
+ *  edge within a node; every node has indegree ≤ 1; the root has indegree 0; every node is reachable
+ *  from the root (no orphans; no cycle, since a cycle leaves a node either unreachable or indegree > 1). */
+export function assertReduceTopologyIsTree(trace) {
+    // The declared root MUST name a real node (round-2: a missing root_key could pass when the node count
+    // coincidentally matched the empty reached set).
+    if (!trace.nodes.has(trace.root_key)) {
+        throw new Error(`comprehension-semantic-map: root_key '${trace.root_key}' is not in the trace (§13.6 tree).`);
+    }
+    const indegree = new Map();
+    for (const [key, tnode] of trace.nodes) {
+        // Each map key MUST equal reduceNodeKey(node_ref) (round-2: an alias key would let
+        // consumed_child_judgment_keys diverge from the canonical child-summary keys).
+        if (key !== reduceNodeKey(tnode.node_ref)) {
+            throw new Error(`comprehension-semantic-map: trace key '${key}' != reduceNodeKey(node_ref) '${reduceNodeKey(tnode.node_ref)}' (§13.6 tree — keys must be canonical).`);
+        }
+        const seenChild = new Set();
+        for (const c of tnode.child_keys) {
+            if (!trace.nodes.has(c))
+                throw new Error(`comprehension-semantic-map: child '${c}' of '${key}' is not in the trace (§13.6 tree).`);
+            if (seenChild.has(c))
+                throw new Error(`comprehension-semantic-map: duplicate child edge '${c}' under '${key}' (§13.6 tree).`);
+            seenChild.add(c);
+            const d = (indegree.get(c) ?? 0) + 1;
+            indegree.set(c, d);
+            if (d > 1)
+                throw new Error(`comprehension-semantic-map: node '${c}' has multiple parents — trace is a DAG, not a tree (§13.6).`);
+        }
+    }
+    if ((indegree.get(trace.root_key) ?? 0) !== 0) {
+        throw new Error(`comprehension-semantic-map: root '${trace.root_key}' has a parent (§13.6 tree).`);
+    }
+    const reached = new Set();
+    const stack = [trace.root_key];
+    while (stack.length > 0) {
+        const k = stack.pop();
+        if (k === undefined || reached.has(k))
+            continue;
+        reached.add(k);
+        for (const c of trace.nodes.get(k)?.child_keys ?? [])
+            stack.push(c);
+    }
+    if (reached.size !== trace.nodes.size) {
+        throw new Error(`comprehension-semantic-map: ${trace.nodes.size - reached.size} trace node(s) unreachable from root '${trace.root_key}' (§13.6 tree).`);
+    }
+}
+/** Fail-closed: a SUBSUMED node carries no judgment (its frontier ancestor absorbed it) and no taint
+ *  (review onto issue-009: a subsumed node has no unverified judgment to count). */
+export function assertSubsumedNodeEmpty(node) {
+    if (node.reduce_read_attempt !== "subsumed")
+        return;
+    if (node.semantic_summary !== "" ||
+        node.semantic_boundaries.length > 0 ||
+        node.structure_boundary_coverage.length > 0 ||
+        node.unanchored_unverified_count !== 0) {
+        throw new Error(`comprehension-semantic-map: subsumed node ${reduceNodeKey(node.node_ref)} must carry no judgment or taint (§13.6 — its frontier ancestor's read covers it).`);
+    }
+}
+/** SOURCE-SAFETY guard (§13.6 / C6): the synthesis input must carry only bounded deterministic facts +
+ *  child summary prose — never a raw cell value / formatCode / example. By construction the builder
+ *  only pulls safe fields; this asserts the shape so an accidental enrichment fails closed. */
+const SYNTHESIS_INPUT_KEYS = ["node_ref", "format_clusters", "value_shape_seams", "child_summaries"];
+const SEAM_KEYS = ["row", "prev_shape", "new_shape"];
+const CHILD_SUMMARY_KEYS = ["key", "summary"];
+const REGION_KEYS = ["sheet", "column_index", "row_start", "row_end"];
+const SYNTHESIS_OUTPUT_KEYS = ["semantic_summary", "boundaries"];
+const RAW_BOUNDARY_KEYS = ["row", "character_before", "character_after"];
+function assertExactKeys(label, obj, keys) {
+    if (!obj || typeof obj !== "object" || Array.isArray(obj)) {
+        throw new Error(`comprehension-semantic-map: ${label} must be a plain object (§13.6 source-safe envelope).`);
+    }
+    const own = Object.keys(obj);
+    const want = new Set(keys);
+    for (const k of own) {
+        if (!want.has(k)) {
+            throw new Error(`comprehension-semantic-map: ${label} has unexpected field '${k}' — only ${keys.join(", ")} allowed (§13.6 source-safe envelope; an extra field could smuggle a raw value into synthesis).`);
+        }
+    }
+    for (const k of keys) {
+        if (!Object.hasOwn(obj, k)) {
+            throw new Error(`comprehension-semantic-map: ${label} missing required field '${k}' (§13.6).`);
+        }
+    }
+}
+/** SOURCE-SAFETY guard (§13.6 / C6 / review F1 / onto issue-012/016) — an EXACT own-key schema, not a
+ *  partial type spot-check. The input may carry ONLY the bounded deterministic facts + child summary
+ *  prose; an extra field on the input, a non-string format cluster, a seam with extra keys, or a raw
+ *  child-summary value fails closed — so an accidental "enrichment" that smuggles a raw cell value /
+ *  formatCode / example into the synthesis prompt cannot pass. */
+export function assertSynthesisInputBounded(input) {
+    assertExactKeys("synthesis input", input, SYNTHESIS_INPUT_KEYS);
+    assertExactKeys("synthesis input.node_ref", input.node_ref, REGION_KEYS);
+    if (!Array.isArray(input.format_clusters) || input.format_clusters.some((c) => typeof c !== "string")) {
+        throw new Error("comprehension-semantic-map: synthesis format_clusters must be string[] — no raw values (§13.6).");
+    }
+    if (!Array.isArray(input.value_shape_seams)) {
+        throw new Error("comprehension-semantic-map: synthesis value_shape_seams must be an array (§13.6).");
+    }
+    for (const s of input.value_shape_seams) {
+        assertExactKeys("synthesis seam", s, SEAM_KEYS);
+        if (typeof s.row !== "number" || typeof s.prev_shape !== "string" || typeof s.new_shape !== "string") {
+            throw new Error("comprehension-semantic-map: synthesis seam must be {row:number, prev_shape:string, new_shape:string} — no raw values (§13.6).");
+        }
+    }
+    if (!Array.isArray(input.child_summaries)) {
+        throw new Error("comprehension-semantic-map: synthesis child_summaries must be an array (§13.6).");
+    }
+    for (const c of input.child_summaries) {
+        assertExactKeys("synthesis child summary", c, CHILD_SUMMARY_KEYS);
+        if (typeof c.key !== "string" || typeof c.summary !== "string") {
+            throw new Error("comprehension-semantic-map: synthesis child summary must be {key:string, summary:string} (§13.6 source-safe envelope).");
+        }
+    }
+}
+/** Fail-closed on the caller-injected synthesize's OUTPUT (round-2 review: the INPUT was validated but
+ *  the OUTPUT was not, so a malformed boundary — a string row that coerces in Math.abs, an object
+ *  character field — flowed through reconcile and anchored). Exact own-key schema; a boundary row must
+ *  be a safe integer and its character fields strings. */
+export function assertSynthesisOutputBounded(out) {
+    assertExactKeys("synthesis output", out, SYNTHESIS_OUTPUT_KEYS);
+    if (typeof out.semantic_summary !== "string") {
+        throw new Error("comprehension-semantic-map: synthesis output semantic_summary must be a string (§13.5 fail-closed).");
+    }
+    if (!Array.isArray(out.boundaries)) {
+        throw new Error("comprehension-semantic-map: synthesis output boundaries must be an array (§13.5 fail-closed).");
+    }
+    for (const b of out.boundaries) {
+        assertExactKeys("synthesis output boundary", b, RAW_BOUNDARY_KEYS);
+        if (!Number.isSafeInteger(b.row)) {
+            throw new Error(`comprehension-semantic-map: synthesis output boundary row must be a safe integer, got ${JSON.stringify(b.row)} (§13.5 fail-closed).`);
+        }
+        if (typeof b.character_before !== "string" || typeof b.character_after !== "string") {
+            throw new Error("comprehension-semantic-map: synthesis output boundary character fields must be strings (§13.5 fail-closed).");
+        }
+    }
+}
+/** Canonical value-shape seams for the synthesis input (round-4 / onto issue-001): the ground hash
+ *  canonicalizes (sorts + dedups) format_clusters/boundaries, but the synthesis input consumed RAW
+ *  order, so a ground-equivalent but raw-divergent reduce node could change the LLM input. Deriving the
+ *  synthesis facts canonically makes the input a pure function of the ground identity. For a real
+ *  reduceColumnLeavesWithTrace node (already canonical) this is a no-op. */
+function canonicalValueShapeSeams(boundaries) {
+    const seen = new Set();
+    const out = [];
+    for (const b of boundaries) {
+        if (b.boundary_kind !== VALUE_SHAPE_KIND)
+            continue;
+        const key = `${b.first_new_format_row}|${b.prev_shape}|${b.new_shape}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push({ row: b.first_new_format_row, prev_shape: b.prev_shape, new_shape: b.new_shape });
+    }
+    out.sort((x, y) => x.row - y.row || cmpStr(x.prev_shape, y.prev_shape) || cmpStr(x.new_shape, y.new_shape));
+    return out;
+}
+/** SINGLE-SOURCE synthesis-input builder (W2 §3(a) / X2): the module's internal walk AND the stage
+ *  bridge both construct the LLM-facing input through this function, so the input the LLM actually
+ *  saw cannot drift from the input the module validates (the bridge additionally compares stableJson
+ *  of both — §3(b)). Child summaries are MODULE-owned outputs (a produced child's semantic_summary),
+ *  unbuildable from topology alone (X2: codex-F2 ≡ onto-004) — the caller supplies them via
+ *  `childSummaryByKey` (available bottom-up). Fail-closed on an unknown/subsumed key or a missing
+ *  consumed-child summary. The returned node_ref is a clone (review F3 — a caller-injected
+ *  synthesize cannot mutate the trace). */
+export function buildSynthesisInputForNode(trace, nodesByKey, modes, key, childSummaryByKey) {
+    const tnode = trace.nodes.get(key);
+    const reduceNode = nodesByKey.get(key);
+    if (!tnode || !reduceNode) {
+        throw new Error(`comprehension-semantic-map: trace/node missing for key ${key} (synthesis input).`);
+    }
+    const mode = modes.get(key);
+    if (!mode) {
+        throw new Error(`comprehension-semantic-map: no frontier mode for ${key} (synthesis input).`);
+    }
+    if (mode === "subsumed") {
+        throw new Error(`comprehension-semantic-map: subsumed node ${key} takes no synthesis input (§13.6 — its frontier ancestor's read covers it).`);
+    }
+    const r = tnode.node_ref;
+    const isFrontier = mode === "frontier";
+    const consumedChildKeys = tnode.child_keys.filter((k) => modes.get(k) !== "subsumed");
+    return {
+        node_ref: { sheet: r.sheet, column_index: r.column_index, row_start: r.row_start, row_end: r.row_end },
+        format_clusters: [...reduceNode.format_clusters].sort(), // canonical (round-4): input = fn(ground identity), not raw order.
+        value_shape_seams: canonicalValueShapeSeams(reduceNode.boundaries),
+        child_summaries: isFrontier
+            ? []
+            : consumedChildKeys.map((k) => {
+                const summary = childSummaryByKey.get(k);
+                if (summary === undefined) {
+                    throw new Error(`comprehension-semantic-map: missing consumed-child summary for ${k} (synthesis input — children must be produced bottom-up first).`);
+                }
+                return { key: k, summary };
+            }),
+    };
+}
+/** Walk the trace bottom-up, producing one validated ComprehensionSemanticNode per skeleton node. Each
+ *  node: synthesize (caller LLM) → reconcileBoundaries (deterministic anchor/coverage) → verify EVERY
+ *  unanchored boundary (N3) → recursive epoch contribution → taint census → assemble, with all three
+ *  fail-closed validators enforced. Deterministic given a deterministic synthesize/verify (the mock). */
+export function accumulateSemanticMap(trace, nodesByKey, opts) {
+    const result = new Map();
+    const seedBound = opts.seedBound ?? false;
+    const visiting = new Set(); // cycle detection (review F5 / onto issue-003).
+    assertReduceTopologyIsTree(trace); // reject DAG / diamond / duplicate edges before counting (review F2).
+    const modes = classifyFrontier(trace, opts.overContextBudget); // S3 over-context partition (§13.6).
+    // Round-4: validate the config sha is a string BEFORE the template fold (a non-string would coerce to
+    // "[object Object]" and silently pass; the folded value is later allowlist-checked but by then the
+    // original is lost).
+    if (typeof opts.preImageBase.over_context_gate_config_sha256 !== "string") {
+        throw new Error("comprehension-semantic-map: preImageBase.over_context_gate_config_sha256 must be a string (§13.4 fail-closed).");
+    }
+    // Round-3 F2: the RUNTIME owns the budget→epoch binding (do not trust the caller to fold the budget
+    // into over_context_gate_config_sha256). A budget change reshapes the frontier partition and thus the
+    // judgments, so fold the actual budget into the config sha here — a budget change always rotates the key.
+    const preImageBase = {
+        ...opts.preImageBase,
+        over_context_gate_config_sha256: createHash("sha256")
+            .update(`${opts.preImageBase.over_context_gate_config_sha256}|over_context_budget=${opts.overContextBudget}`)
+            .digest("hex"),
+    };
+    const visit = (key) => {
+        const cached = result.get(key);
+        if (cached)
+            return cached;
+        if (visiting.has(key)) {
+            throw new Error(`comprehension-semantic-map: cycle in reduce topology at ${key} — a well-formed trace is a tree (§13.5 fail-closed; review F5).`);
+        }
+        const tnode = trace.nodes.get(key);
+        const reduceNode = nodesByKey.get(key);
+        if (!tnode || !reduceNode) {
+            throw new Error(`comprehension-semantic-map: trace/node missing for key ${key} (accumulate walk).`);
+        }
+        // Round-3 F1: nodesByKey MUST agree with the validated trace — a caller could pass a mismatched
+        // reduce node whose deterministic facts then feed synthesis/reconcile. reduceNodeGroundHash is the
+        // node's full canonical identity (region + sorted clusters + canonical boundaries + honesty), and
+        // the synthesis input is derived canonically (canonicalValueShapeSeams), so a ground-equivalent node
+        // yields an identical input. NOTE (round-4, deferred): a FULL structural re-derivation — proving each
+        // parent's ground == merge(children's reduce nodes) — is not re-run here (it would re-execute the
+        // Layer-1 fold per node). The module trusts the trace/nodesByKey to be produced by
+        // reduceColumnLeavesWithTrace (which guarantees that by construction); production wiring provides it.
+        if (reduceNodeKey(reduceNode.region) !== key || reduceNodeGroundHash(reduceNode) !== tnode.ground_hash) {
+            throw new Error(`comprehension-semantic-map: nodesByKey['${key}'] disagrees with the trace node (region/ground mismatch) (§13.6 fail-closed).`);
+        }
+        const mode = modes.get(key);
+        if (!mode)
+            throw new Error(`comprehension-semantic-map: no frontier mode for ${key} (unreachable from root?).`);
+        visiting.add(key);
+        const children = tnode.child_keys.map(visit); // recurse ALWAYS — a subsumed subtree still gets 1:1 placeholder nodes.
+        visiting.delete(key);
+        // Children whose judgment this node CONSUMES = the non-subsumed direct children. For an accumulating
+        // node that is all its children; for a frontier node that is none (children are subsumed).
+        const consumedChildKeys = tnode.child_keys.filter((k) => modes.get(k) !== "subsumed");
+        const consumedChildren = children.filter((c) => modes.get(reduceNodeKey(c.node_ref)) !== "subsumed");
+        // SUBSUMED: no judgment — a 1:1 placeholder (its frontier ancestor's flat read covers it). Its
+        // epoch contribution STILL folds its children's contributions (review F1 / onto issue-003/006/011):
+        // the epoch recursion is decoupled from judgment consumption, so a non-propagating descendant change
+        // (that leaves this node's ground byte-identical) still rotates the key up to the frontier ancestor.
+        if (mode === "subsumed") {
+            const preImage = {
+                ...preImageBase,
+                layer1_ground_hash: tnode.ground_hash,
+                child_contributions: children.map((c) => c.subtree_epoch_contribution),
+            };
+            const rr = tnode.node_ref;
+            const node = {
+                node_ref: { sheet: rr.sheet, column_index: rr.column_index, row_start: rr.row_start, row_end: rr.row_end },
+                layer1_ground_hash: tnode.ground_hash,
+                subtree_epoch_contribution: reduceNodeEpochContribution(preImage),
+                authority: "non_authoritative",
+                provisional: true,
+                reduce_read_attempt: "subsumed",
+                semantic_summary: "",
+                semantic_boundaries: [],
+                structure_boundary_coverage: [],
+                topology_child_keys: [...tnode.child_keys], // clone so the returned node does not alias the trace array (round-3 F3).
+                consumed_child_judgment_keys: [],
+                unanchored_unverified_count: 0,
+            };
+            assertSubsumedNodeEmpty(node);
+            assertChildJudgmentCoverage(node, []);
+            result.set(key, node);
+            return node;
+        }
+        // FRONTIER = one flat read over the whole subtree (child_summaries omitted; children are subsumed).
+        // ACCUMULATING = synthesize the (non-subsumed) children's judgments. Both are 'produced'.
+        // W2 §3(a): the input is constructed through the SAME exported single-source builder the stage
+        // bridge uses (node_ref cloned inside — review F3), so the LLM-facing input cannot drift from
+        // the module-validated input by construction.
+        const r = tnode.node_ref;
+        const input = buildSynthesisInputForNode(trace, nodesByKey, modes, key, new Map(consumedChildren.map((c) => [reduceNodeKey(c.node_ref), c.semantic_summary])));
+        assertSynthesisInputBounded(input);
+        const out = opts.synthesize(input);
+        assertSynthesisOutputBounded(out); // round-2: validate the caller's OUTPUT, not just the input.
+        const { boundaries: classified, coverage } = reconcileBoundaries(out.boundaries, reduceNode);
+        // N3: verify EVERY unanchored boundary (structure is blind there). Anchored stay location-only.
+        // The injected verifier's return is validated (review F2): a bogus status must fail closed here,
+        // not slip into a seed-bound node.
+        const verified = classified.map((b) => {
+            if (b.anchor_status !== "unanchored")
+                return b;
+            // Clone node_ref + boundary for the verifier too (round-2: F3 only cloned the synthesize input;
+            // the verifier could mutate the live trace node_ref and corrupt later child-summary keys).
+            const v = opts.verifyUnanchored({
+                node_ref: { sheet: r.sheet, column_index: r.column_index, row_start: r.row_start, row_end: r.row_end },
+                boundary: { ...b },
+                summary: out.semantic_summary,
+            });
+            if (!VALID_ADVERSARIAL_RESULT.has(v)) {
+                throw new Error(`comprehension-semantic-map: verifyUnanchored returned invalid result '${v}' at ${key} — must be adversarial_confirmed | adversarial_refuted (§13.5 fail-closed).`);
+            }
+            return { ...b, verification: v };
+        });
+        const refutedCount = verified.filter((b) => b.verification === "adversarial_refuted").length;
+        // Seed-bound: refuted boundaries are EXCLUDED from the seed boundary list (codex-F2) — counted in
+        // taint below. Non-seed: kept for inspection (still counted in taint via ownUnverifiedCount).
+        const keptBoundaries = seedBound ? verified.filter((b) => b.verification !== "adversarial_refuted") : verified;
+        const preImage = {
+            ...preImageBase,
+            layer1_ground_hash: tnode.ground_hash,
+            // EPOCH recursion is decoupled from judgment CONSUMPTION (review F1 / onto issue-003/006/011): a
+            // frontier consumes no child SUMMARIES (flat read) but STILL folds ALL children's contributions,
+            // so a non-propagating descendant change (parent ground byte-identical) rotates the frontier key —
+            // matching the accumulating path (fail-safe: over-rotate, never stale-reuse).
+            child_contributions: children.map((c) => c.subtree_epoch_contribution),
+        };
+        const node = {
+            node_ref: { sheet: r.sheet, column_index: r.column_index, row_start: r.row_start, row_end: r.row_end },
+            layer1_ground_hash: tnode.ground_hash,
+            subtree_epoch_contribution: reduceNodeEpochContribution(preImage),
+            authority: "non_authoritative",
+            provisional: true,
+            reduce_read_attempt: "produced",
+            semantic_summary: out.semantic_summary,
+            semantic_boundaries: keptBoundaries,
+            structure_boundary_coverage: coverage,
+            topology_child_keys: [...tnode.child_keys], // clone so the returned node does not alias the trace array (round-3 F3).
+            consumed_child_judgment_keys: consumedChildKeys, // [] for a frontier; all children for accumulating.
+            unanchored_unverified_count: 0,
+        };
+        // Taint = CONSUMED children + own remaining unverified boundaries + any refuted removed for seed.
+        node.unanchored_unverified_count =
+            computeUnanchoredUnverifiedCount(node, consumedChildren) + (seedBound ? refutedCount : 0);
+        // Fail-closed validators (§13.5). expectedConsumedKeys = the non-subsumed children.
+        assertChildJudgmentCoverage(node, consumedChildKeys);
+        assertSemanticBoundaryHonesty(node, seedBound);
+        assertTaintCensusMonotone(node, consumedChildren);
+        result.set(key, node);
+        return node;
+    };
+    visit(trace.root_key);
+    // Reachability (review F5 / onto issue-003): every trace node MUST be reached from the root, else an
+    // orphan node would be silently dropped from the accumulated map (a completeness violation).
+    if (result.size !== trace.nodes.size) {
+        throw new Error(`comprehension-semantic-map: ${trace.nodes.size - result.size} trace node(s) unreachable from root ${trace.root_key} — orphan nodes would be silently dropped (§13.5 fail-closed).`);
+    }
+    return result;
+}
+/** Project the accumulated semantic map into a bounded, honest seed input (§6). Pure / deterministic.
+ *  ★INPUT CONTRACT (S4 code review): the map MUST be accumulated with seedBound=FALSE — refuted
+ *  boundaries are RETAINED in semantic_boundaries so this projection is the sole place that excludes
+ *  them (into refuted_disclosure). A seedBound=true map would hide refuted from the disclosure. The
+ *  taint census is DERIVED from what the projection actually sees (refuted boundaries + failed/unread
+ *  regions) — self-consistent with the disclosure, never trusting the map's own
+ *  unanchored_unverified_count (which a caller could set to NaN / non-monotone). */
+export function projectSemanticMapToSeed(map, opts = {}) {
+    const checkBound = (name, v) => {
+        if (v !== undefined && (!Number.isSafeInteger(v) || v < 0)) {
+            throw new Error(`comprehension-semantic-map: seed projection ${name} must be a non-negative safe integer or absent (fail-closed; -1/NaN would silently show nothing).`);
+        }
+    };
+    checkBound("maxNodes", opts.maxNodes);
+    checkBound("maxDisclosure", opts.maxDisclosure);
+    const nodesAll = [];
+    const refuted = [];
+    let failedOrUnread = 0;
+    // Deterministic CANONICAL order — by reduceNodeKey(node_ref), NOT the caller's map key.
+    const nodes = [...map.values()].sort((a, b) => cmpStr(reduceNodeKey(a.node_ref), reduceNodeKey(b.node_ref)));
+    for (const node of nodes) {
+        // Honesty precondition (fail-closed): legal (anchor_status, verification) states only. seedBound=false
+        // (the map still carries refuted boundaries; THIS projection is what excludes them from seed).
+        assertSemanticBoundaryHonesty(node, false);
+        // The map key MUST be the canonical node key (else consumed/child keys diverge; S3 F4 class).
+        const canonicalKey = reduceNodeKey(node.node_ref);
+        if (map.get(canonicalKey) !== node) {
+            throw new Error(`comprehension-semantic-map: seed projection — a node is stored under a non-canonical map key (expected '${canonicalKey}') (§13.6 fail-closed).`);
+        }
+        if (node.reduce_read_attempt === "subsumed") {
+            assertSubsumedNodeEmpty(node); // a subsumed node must carry no judgment/taint (fail-closed).
+            continue; // no judgment (frontier ancestor covers it).
+        }
+        if (node.reduce_read_attempt === "failed" || node.reduce_read_attempt === "unread") {
+            failedOrUnread += 1; // an unverified region (the read failed) — counted in taint, no seed node.
+            continue;
+        }
+        const region = node.node_ref;
+        const boundaries = [];
+        for (const b of node.semantic_boundaries) {
+            if (b.anchor_status === "anchored") {
+                boundaries.push({ row: b.row, character_before: b.character_before, character_after: b.character_after, disposition: "structural_location_only" });
+            }
+            else if (b.verification === "adversarial_confirmed") {
+                boundaries.push({ row: b.row, character_before: b.character_before, character_after: b.character_after, disposition: "adversarial_confirmed" });
+            }
+            else if (b.verification === "adversarial_refuted") {
+                refuted.push({
+                    node_ref: { sheet: region.sheet, column_index: region.column_index, row_start: region.row_start, row_end: region.row_end },
+                    row: b.row,
+                    character_before: b.character_before,
+                    character_after: b.character_after,
+                });
+            }
+            else {
+                // unanchored + unverified: accumulate must have adversarially processed it before seed (N3).
+                throw new Error(`comprehension-semantic-map: unverified unanchored boundary at ${reduceNodeKey(region)}@row${b.row} reached seed projection — every unanchored boundary must be adversarially verified first (§13.5 N3 fail-closed).`);
+            }
+        }
+        nodesAll.push({
+            node_ref: { sheet: region.sheet, column_index: region.column_index, row_start: region.row_start, row_end: region.row_end },
+            semantic_summary: node.semantic_summary,
+            boundaries,
+        });
+    }
+    // Taint DERIVED from what the projection sees (refuted boundaries + failed/unread regions) — self-
+    // consistent with refuted_disclosure, never trusting the caller's count.
+    const taint = refuted.length + failedOrUnread;
+    return {
+        authority: "non_authoritative",
+        provisional: true,
+        nodes: nodesAll.slice(0, opts.maxNodes ?? nodesAll.length),
+        nodes_total: nodesAll.length,
+        refuted_disclosure: refuted.slice(0, opts.maxDisclosure ?? refuted.length),
+        refuted_disclosure_total: refuted.length,
+        unanchored_unverified_total: taint,
+    };
+}