pi-mega-compact 0.20.2 → 0.20.4

package/dist/src/vector-cortex/prompt-dag/builder.js

@@ -0,0 +1,171 @@
+/**
+ * vector-cortex/prompt-dag/builder.ts — single-session PromptDagV1 construction
+ * (VC5A, task 2).
+ *
+ * The builder is the STRUCTURAL gate: it rejects a graph that could never be
+ * planned safely, before any ordering or selection is attempted. Rejections are
+ * hard and total (the sprint bar: "cycles/incompatibilities rejected 100%"):
+ *
+ *   - `DAG_MIXED_SESSION`        — a span whose sessionId differs from the DAG's.
+ *                                  Cross-session evidence MUST be a synthetic
+ *                                  node citing a separately validated manifest,
+ *                                  never a foreign span (CONTRACTS §PromptDagV1).
+ *   - `DAG_DUPLICATE_ID`         — two nodes sharing an id.
+ *   - `DAG_MISSING_ENDPOINT`     — an edge naming an absent node.
+ *   - `DAG_INVALID_SPAN`         — reversed/negative range, or a synthetic node
+ *                                  carrying a span (synthetics have no source
+ *                                  position by definition).
+ *   - `DAG_SPAN_DIGEST_CONFLICT` — two overlapping spans pinning DIFFERENT
+ *                                  digests for the same bytes: a corrupted or
+ *                                  forged source claim, not a legal overlap.
+ *   - `DAG_UNKNOWN_INCOMPATIBLE` — `incompatibleWith` naming an absent node.
+ *   - `DAG_TOOL_PAIR_SPLIT`      — a tool-pair edge whose endpoints are not both
+ *                                  present (PREVENT-PI-002).
+ *
+ * Cycle and reversed-`precedes` detection belong to the VALIDATOR, which owns
+ * the topological order; the builder only guarantees the graph is structurally
+ * well-formed and single-session.
+ *
+ * Determinism: nodes and edges are emitted in a canonical sorted order so the
+ * same inputs always produce byte-identical DAG bytes, whatever order the caller
+ * supplied them in. Pure: no storage, no console, no network (PREVENT-PI-004).
+ */
+/** Bytewise string comparison — the universal deterministic tie-break. */
+function byBytes(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+ * Canonical node order: source position first (`startSeq`, then `startByte`),
+ * synthetics last (they have no span), then `syntheticOrdinal`, then id bytes.
+ * This mirrors the validator's queue key so the emitted DAG and its topological
+ * order agree on what "earlier" means.
+ */
+export function compareNodes(a, b) {
+    const aSeq = a.span?.startSeq;
+    const bSeq = b.span?.startSeq;
+    if (aSeq !== undefined && bSeq !== undefined) {
+        if (aSeq !== bSeq)
+            return aSeq < bSeq ? -1 : 1;
+    }
+    else if (aSeq !== undefined) {
+        return -1; // spanned nodes precede synthetics
+    }
+    else if (bSeq !== undefined) {
+        return 1;
+    }
+    // Contract key: (startSeq, syntheticOrdinal, id bytes) — byte offset is NOT a
+    // tie-break, so the emitted DAG and its topological order agree exactly.
+    const aOrd = a.syntheticOrdinal ?? 0;
+    const bOrd = b.syntheticOrdinal ?? 0;
+    if (aOrd !== bOrd)
+        return aOrd < bOrd ? -1 : 1;
+    return byBytes(a.id, b.id);
+}
+/** Canonical edge order: from, then to, then kind — a total order. */
+export function compareEdges(a, b) {
+    const f = byBytes(a.from, b.from);
+    if (f !== 0)
+        return f;
+    const t = byBytes(a.to, b.to);
+    if (t !== 0)
+        return t;
+    return byBytes(a.kind, b.kind);
+}
+/** Whether two half-open byte ranges in the same session intersect. */
+function spansOverlap(a, b) {
+    if (a.sessionId !== b.sessionId)
+        return false;
+    return a.startByte < b.endByte && b.startByte < a.endByte;
+}
+/** A span is well-formed when both its seq and byte ranges are non-decreasing. */
+function spanIsValid(span) {
+    if (span.startSeq > span.endSeq)
+        return false;
+    if (span.startByte < 0 || span.endByte < 0)
+        return false;
+    return span.startByte <= span.endByte;
+}
+/** Push a failure code once (codes are a SET, reported in discovery order). */
+function pushCode(codes, code) {
+    if (!codes.includes(code))
+        codes.push(code);
+}
+/**
+ * Build a canonical single-session `PromptDagV1`, or reject with the exact
+ * structural failure codes (task 2).
+ *
+ * Every check runs before returning so a caller sees ALL structural problems at
+ * once rather than fixing them one round-trip at a time; the codes array is
+ * deduplicated and ordered by discovery.
+ */
+export function buildPromptDag(input) {
+    const codes = [];
+    // ── Node identity + span validity + single-session enforcement ─────────────
+    const byId = new Map();
+    for (const n of input.nodes) {
+        if (byId.has(n.id))
+            pushCode(codes, "DAG_DUPLICATE_ID");
+        else
+            byId.set(n.id, n);
+        if (n.kind === "synthetic") {
+            // A synthetic node has no source position by definition; carrying a span
+            // would make its ordering ambiguous against real source nodes.
+            if (n.span !== undefined)
+                pushCode(codes, "DAG_INVALID_SPAN");
+            continue;
+        }
+        if (n.span === undefined)
+            continue; // a spanless non-synthetic orders last
+        if (!spanIsValid(n.span))
+            pushCode(codes, "DAG_INVALID_SPAN");
+        // Single-session: cross-session evidence must be a synthetic citation.
+        if (n.span.sessionId !== input.sessionId)
+            pushCode(codes, "DAG_MIXED_SESSION");
+    }
+    // ── Overlapping spans must agree on the digest of the shared bytes ─────────
+    const spanned = input.nodes.filter((n) => n.span !== undefined);
+    for (let i = 0; i < spanned.length; i++) {
+        for (let j = i + 1; j < spanned.length; j++) {
+            const a = spanned[i];
+            const b = spanned[j];
+            if (!spansOverlap(a.span, b.span))
+                continue;
+            if (a.span.digest !== b.span.digest) {
+                pushCode(codes, "DAG_SPAN_DIGEST_CONFLICT");
+            }
+        }
+    }
+    // ── Incompatibility targets must exist ────────────────────────────────────
+    for (const n of input.nodes) {
+        for (const other of n.incompatibleWith) {
+            if (!byId.has(other))
+                pushCode(codes, "DAG_UNKNOWN_INCOMPATIBLE");
+        }
+    }
+    // ── Edge endpoints must exist; tool pairs must be whole ───────────────────
+    for (const e of input.edges) {
+        const hasFrom = byId.has(e.from);
+        const hasTo = byId.has(e.to);
+        if (!hasFrom || !hasTo) {
+            pushCode(codes, "DAG_MISSING_ENDPOINT");
+            // A tool pair missing an endpoint is ALSO a split pair (PREVENT-PI-002):
+            // the atomic unit cannot be represented, let alone selected whole.
+            if (e.kind === "tool-pair")
+                pushCode(codes, "DAG_TOOL_PAIR_SPLIT");
+        }
+    }
+    if (codes.length > 0)
+        return { ok: false, codes };
+    const nodes = [...input.nodes].sort(compareNodes);
+    const edges = [...input.edges].sort(compareEdges);
+    return {
+        ok: true,
+        dag: {
+            schema: "prompt-dag-v1",
+            sessionId: input.sessionId,
+            sourceHighWater: input.sourceHighWater,
+            nodes,
+            edges,
+        },
+    };
+}

package/dist/src/vector-cortex/prompt-dag/types.js

@@ -0,0 +1,33 @@
+/**
+ * vector-cortex/prompt-dag/types.ts — the exact single-session `PromptDagV1`
+ * schema (VC5A, task 1).
+ *
+ * A PromptDagV1 is the STRUCTURE a plan is selected over: nodes are prompt
+ * candidates (events, exact spans, semantic renderings, synthetic citations) and
+ * edges are the ordering/atomicity/exclusivity constraints among them. It is
+ * strictly SINGLE-SESSION (CONTRACTS §PromptDagV1): every node span MUST carry
+ * `dag.sessionId`; cross-session evidence is represented by a SYNTHETIC node
+ * whose payload cites a separately validated source manifest, never by a foreign
+ * span.
+ *
+ * Ordering is a total order by construction so the same DAG always yields the
+ * same Kahn sequence:
+ *
+ *   - event/exact/semantic nodes order by their source span (`startSeq`, then
+ *     `startByte`);
+ *   - synthetic nodes have NO span and sort after every prerequisite, then by
+ *     `syntheticOrdinal`, then by node-ID bytes;
+ *   - the zero-indegree queue key is `(span.startSeq ?? MAX, syntheticOrdinal ??
+ *     0, id bytes)` — never object/map iteration order.
+ *
+ * Pure types + registered conformance IDs: no storage, no console, no network
+ * (PREVENT-PI-004 / PREVENT-011).
+ */
+/**
+ * Registered DAG conformance ID range (DAG-001..030). The acceptance aggregator
+ * reads these rows from the v2 manifest and asserts each returns its manifest
+ * `ok`/`code`.
+ */
+export const DAG_IDS = Array.from({ length: 30 }, (_v, i) => `DAG-${String(i + 1).padStart(3, "0")}`);
+/** Named VC5A DAG conformance assertion (the sprint's headline DAG row). */
+export const DAG_NAMED_IDS = ["DAG-CYCLE-001"];

package/dist/vector-cortex/planner/manifest.js

@@ -0,0 +1,66 @@
+/**
+ * vector-cortex/planner/manifest.ts — plan manifest identity + pre-provider
+ * revalidation (VC5A).
+ *
+ * Split from `portfolio.ts` (which owns SELECTION) so each file keeps one
+ * concern and stays under the 300-line soft limit: this module owns the plan's
+ * IDENTITY and the last gate before a provider call.
+ *
+ * The manifest digest deliberately covers PER-NODE TOKEN COUNTS, which the DAG
+ * digest does not: token counts are a planner input rather than DAG structure.
+ * That is exactly what makes the sprint's unique failure injection detectable —
+ * mutating a node's token count after planning but before validation changes the
+ * recomputed manifest digest, so `validatePlanManifest` returns
+ * `PLN_MANIFEST_DIGEST_MISMATCH` and the plan never reaches the provider.
+ *
+ * Pure/deterministic: no storage, no console, no network (PREVENT-PI-004).
+ */
+import { createHash } from "node:crypto";
+/**
+ * Deterministic digest over a plan AND the token counts/utilities it was
+ * selected with. Hashing walks `selectedNodeIds` in its stored (sorted) order,
+ * so the digest is a pure function of the plan and the candidate facts.
+ *
+ * A node missing from `candidates` hashes as `-1`, so dropping a candidate is
+ * itself a detectable mutation rather than a silently-skipped field.
+ */
+export function planManifestDigest(plan, candidates) {
+    const h = createHash("sha256");
+    h.update(plan.schema);
+    h.update(" ");
+    h.update(plan.dagDigest);
+    h.update(" ");
+    h.update(String(plan.tokenBudget));
+    h.update(" ");
+    h.update(String(plan.tokenTotal));
+    h.update(" ");
+    h.update(String(plan.dependencyHighWater));
+    const byId = new Map(candidates.map((c) => [c.nodeId, c]));
+    for (const id of plan.selectedNodeIds) {
+        const c = byId.get(id);
+        h.update("");
+        h.update(id);
+        h.update(" ");
+        // Token count is part of the identity — a post-plan mutation breaks it.
+        h.update(String(c?.tokenEstimate ?? -1));
+        h.update(" ");
+        h.update(String(c?.utility ?? -1));
+    }
+    return h.digest("hex");
+}
+/**
+ * Re-validate a plan against the candidates AS THEY STAND NOW, immediately
+ * before a provider call. Returns `PLN_MANIFEST_DIGEST_MISMATCH` when the
+ * recomputed manifest digest disagrees with the digest pinned at planning time.
+ *
+ * This is the sprint's unique failure injection: a node token count mutated
+ * after planning but before validation is caught here, BEFORE the provider is
+ * invoked, rather than producing a prompt whose real cost differs from the
+ * admitted budget.
+ */
+export function validatePlanManifest(plan, candidates, pinnedDigest) {
+    if (planManifestDigest(plan, candidates) !== pinnedDigest) {
+        return { ok: false, code: "PLN_MANIFEST_DIGEST_MISMATCH" };
+    }
+    return { ok: true };
+}

package/dist/vector-cortex/planner/types.js

@@ -0,0 +1,41 @@
+/**
+ * vector-cortex/planner/types.ts — `PlanV1` + the budget admission contract
+ * (VC5A, task 1).
+ *
+ * VC5A EXCLUSIVELY OWNS FRAMING + BUDGET ADMISSION (CONTRACTS §plan and
+ * closure). VC4C hands over `ClosureResult.mandatoryTokenEstimate`, a
+ * CONTENT-ONLY count with no prompt framing, no role tags and no separators, and
+ * VC4C never truncates a mandatory node nor reasons about a budget. This module
+ * adds the framing cost on top of that content estimate and decides admission:
+ *
+ *   framed(node)   = tokenEstimate + framingPerNode
+ *   mandatoryCost  = mandatoryTokenEstimate + framingPerNode * |mandatory|
+ *                    + framingOverhead
+ *
+ * If `mandatoryCost > tokenBudget` the planner returns
+ * `MANDATORY_CLOSURE_OVER_BUDGET` and the adapter demotes to C. Crucially it
+ * does so WITHOUT DROPPING EVIDENCE: the mandatory set is returned intact on the
+ * failure so the caller can report exactly what did not fit (the sprint bar:
+ * "over-budget mandatory closure never drops evidence and always demotes").
+ *
+ * The framing constants are CONFIGURABLE, never invented magic numbers: a caller
+ * supplies the profile it is actually rendering with, and the defaults below are
+ * documented as a conservative baseline rather than a measured provider fact.
+ *
+ * Pure types + registered conformance IDs: no storage, no console, no network
+ * (PREVENT-PI-004 / PREVENT-011).
+ */
+/**
+ * Conservative default framing baseline. Documented as a BASELINE, not a
+ * measured provider constant: a real provider profile (VC5B) overrides it. Kept
+ * small and explicit so a default-driven plan is never silently over-optimistic.
+ */
+export const DEFAULT_FRAMING = { perNode: 4, overhead: 8 };
+/**
+ * Registered PLN conformance ID range (PLN-001..020). The acceptance aggregator
+ * reads these rows from the v2 manifest and asserts each returns its manifest
+ * `ok`/`code`.
+ */
+export const PLN_IDS = Array.from({ length: 20 }, (_v, i) => `PLN-${String(i + 1).padStart(3, "0")}`);
+/** Named VC5A planner conformance assertions (the sprint's headline rows). */
+export const PLAN_NAMED_IDS = ["PLN-MANDATORY-002", "PLN-TIE-003"];

package/dist/vector-cortex/prompt-dag/_acceptance-dag.js

@@ -0,0 +1,347 @@
+/**
+ * prompt-dag/_acceptance-dag.ts — declarative DAG materialization + scenario
+ * driver for VC5A acceptance rows.
+ *
+ * Turns named graph scenarios into real `PromptDagV1` values and drives them
+ * through the REAL build/validate logic. Deterministic helpers (eq/shuffle)
+ * live in `_acceptance-shuffle.ts`.
+ */
+import assert from "node:assert/strict";
+import { buildPromptDag, compareNodes, compareEdges } from "./builder.js";
+import { validatePromptDag, dagDigest } from "./validator.js";
+import { eq, shuffle } from "./_acceptance-shuffle.js";
+function span(sessionId, startSeq, endSeq, startByte, endByte, digest) {
+    return { sessionId, startSeq, endSeq, startByte, endByte, digest: `sha256:${digest}` };
+}
+function node(id, kind, opts = {}) {
+    return {
+        id,
+        kind,
+        payloadDigest: opts.payloadDigest ?? `pd:${id}`,
+        incompatibleWith: opts.incompatibleWith ?? [],
+        ...(opts.span !== undefined ? { span: opts.span } : {}),
+        ...(opts.syntheticOrdinal !== undefined ? { syntheticOrdinal: opts.syntheticOrdinal } : {}),
+    };
+}
+function edge(from, to, kind) {
+    return { from, to, kind };
+}
+const D0 = "a".repeat(64);
+const D1 = "b".repeat(64);
+/** Materialize a named graph into a built PromptDagV1 + a validator order. */
+export function materializeDag(name) {
+    const cases = {
+        linear: {
+            sessionId: "s",
+            nodes: [
+                node("a", "event", { span: span("s", 1n, 1n, 0, 3, D0) }),
+                node("b", "exact", { span: span("s", 2n, 2n, 3, 6, D0) }),
+                node("c", "semantic", { span: span("s", 3n, 3n, 6, 9, D0) }),
+            ],
+            edges: [edge("a", "b", "depends"), edge("b", "c", "depends")],
+        },
+        "mixed-session": {
+            sessionId: "s",
+            nodes: [
+                node("a", "event", { span: span("s", 1n, 1n, 0, 3, D0) }),
+                // A span claiming a foreign session — single-session violation.
+                node("b", "exact", { span: span("OTHER", 2n, 2n, 0, 3, D0) }),
+            ],
+            edges: [],
+        },
+        "duplicate-id": {
+            sessionId: "s",
+            nodes: [
+                node("a", "event", { span: span("s", 1n, 1n, 0, 3, D0) }),
+                node("a", "exact", { span: span("s", 2n, 2n, 0, 3, D1) }),
+            ],
+            edges: [],
+        },
+        "missing-endpoint": {
+            sessionId: "s",
+            nodes: [node("a", "event", { span: span("s", 1n, 1n, 0, 3, D0) })],
+            edges: [edge("a", "ghost", "depends")],
+        },
+        "invalid-span": {
+            sessionId: "s",
+            nodes: [node("a", "event", { span: span("s", 3n, 1n, 9, 0, D0) })],
+            edges: [],
+        },
+        "synthetic-span": {
+            sessionId: "s",
+            nodes: [
+                node("a", "synthetic", { syntheticOrdinal: 0, span: span("s", 1n, 1n, 0, 3, D0) }),
+            ],
+            edges: [],
+        },
+        "digest-conflict": {
+            sessionId: "s",
+            nodes: [
+                node("a", "exact", { span: span("s", 1n, 1n, 0, 6, D0) }),
+                node("b", "exact", { span: span("s", 2n, 2n, 3, 9, D1) }),
+            ],
+            edges: [],
+        },
+        "digest-agree": {
+            sessionId: "s",
+            nodes: [
+                node("a", "exact", { span: span("s", 1n, 1n, 0, 6, D0) }),
+                node("b", "exact", { span: span("s", 2n, 2n, 3, 9, D0) }),
+            ],
+            edges: [],
+        },
+        "unknown-incompatible": {
+            sessionId: "s",
+            nodes: [
+                node("a", "event", { span: span("s", 1n, 1n, 0, 3, D0), incompatibleWith: ["ghost"] }),
+                node("b", "event", { span: span("s", 2n, 2n, 0, 3, D1) }),
+            ],
+            edges: [],
+        },
+        "tool-pair-split": {
+            sessionId: "s",
+            nodes: [node("toolcall", "event", { span: span("s", 1n, 1n, 0, 3, D0) })],
+            edges: [edge("toolcall", "toolresult", "tool-pair")],
+        },
+        cycle: {
+            sessionId: "s",
+            nodes: [
+                node("a", "event", { span: span("s", 1n, 1n, 0, 3, D0) }),
+                node("b", "event", { span: span("s", 2n, 2n, 0, 3, D1) }),
+                node("c", "event", { span: span("s", 3n, 3n, 0, 3, D0) }),
+            ],
+            edges: [edge("b", "a", "depends"), edge("c", "b", "depends"), edge("a", "c", "depends")],
+        },
+        selfloop: {
+            sessionId: "s",
+            nodes: [node("a", "event", { span: span("s", 1n, 1n, 0, 3, D0) })],
+            edges: [edge("a", "a", "depends")],
+        },
+        "id-tie": {
+            sessionId: "s",
+            nodes: [
+                node("aa", "event", { span: span("s", 1n, 1n, 0, 3, D0) }),
+                node("bb", "event", { span: span("s", 1n, 1n, 3, 6, D1) }),
+                node("cc", "event", { span: span("s", 1n, 1n, 6, 9, D0) }),
+            ],
+            edges: [],
+        },
+        "seq-before-id": {
+            sessionId: "s",
+            // Earlier seq sorts first even though IDs sort the other way.
+            nodes: [
+                node("z", "event", { span: span("s", 1n, 1n, 0, 3, D0) }),
+                node("y", "event", { span: span("s", 2n, 2n, 0, 3, D1) }),
+                node("x", "event", { span: span("s", 3n, 3n, 0, 3, D0) }),
+            ],
+            edges: [],
+        },
+        "synthetic-last": {
+            sessionId: "s",
+            nodes: [
+                node("a", "event", { span: span("s", 1n, 1n, 0, 3, D0) }),
+                node("b", "event", { span: span("s", 2n, 2n, 0, 3, D1) }),
+                node("syn", "synthetic", { syntheticOrdinal: 0 }),
+            ],
+            edges: [],
+        },
+        "synthetic-ordinal": {
+            sessionId: "s",
+            nodes: [
+                node("a", "event", { span: span("s", 1n, 1n, 0, 3, D0) }),
+                node("s1", "synthetic", { syntheticOrdinal: 1 }),
+                node("s2", "synthetic", { syntheticOrdinal: 2 }),
+            ],
+            edges: [],
+        },
+        diamond: {
+            sessionId: "s",
+            nodes: [
+                node("top", "event", { span: span("s", 1n, 1n, 0, 3, D0) }),
+                node("l", "event", { span: span("s", 2n, 2n, 0, 3, D1) }),
+                node("r", "event", { span: span("s", 3n, 3n, 0, 3, D0) }),
+                node("bottom", "event", { span: span("s", 4n, 4n, 0, 3, D1) }),
+            ],
+            edges: [
+                edge("top", "l", "depends"),
+                edge("top", "r", "depends"),
+                edge("l", "bottom", "depends"),
+                edge("r", "bottom", "depends"),
+            ],
+        },
+        contradicts: {
+            sessionId: "s",
+            nodes: [
+                node("a", "exact", { span: span("s", 1n, 1n, 0, 3, D0) }),
+                node("b", "exact", { span: span("s", 2n, 2n, 0, 3, D1) }),
+            ],
+            edges: [edge("a", "b", "contradicts")],
+        },
+        "contradicts-cycle": {
+            sessionId: "s",
+            nodes: [
+                node("a", "exact", { span: span("s", 1n, 1n, 0, 3, D0) }),
+                node("b", "exact", { span: span("s", 2n, 2n, 0, 3, D1) }),
+            ],
+            // A contradicts edge plus a depends edge: a real cycle would need the
+            // depends to form a loop, but here only `a->b` depends, so no cycle.
+            edges: [edge("a", "b", "contradicts"), edge("a", "b", "depends")],
+        },
+        "reversed-precedes": {
+            sessionId: "s",
+            nodes: [
+                node("a", "event", { span: span("s", 2n, 2n, 0, 3, D0) }),
+                node("b", "event", { span: span("s", 1n, 1n, 0, 3, D1) }),
+            ],
+            // b's source position is EARLIER than a's, so a->b precedes is backward.
+            edges: [edge("a", "b", "precedes")],
+        },
+        scrambled: {
+            sessionId: "s",
+            nodes: [
+                node("c", "event", { span: span("s", 3n, 3n, 6, 9, D0) }),
+                node("a", "event", { span: span("s", 1n, 1n, 0, 3, D0) }),
+                node("b", "event", { span: span("s", 2n, 2n, 3, 6, D1) }),
+            ],
+            edges: [edge("a", "b", "depends"), edge("b", "c", "depends")],
+        },
+        empty: { sessionId: "s", nodes: [], edges: [] },
+        single: {
+            sessionId: "s",
+            nodes: [node("a", "event", { span: span("s", 1n, 1n, 0, 3, D0) })],
+            edges: [],
+        },
+        disconnected: {
+            sessionId: "s",
+            nodes: [
+                node("a", "event", { span: span("s", 1n, 1n, 0, 3, D0) }),
+                node("b", "event", { span: span("s", 2n, 2n, 0, 3, D1) }),
+                node("x", "event", { span: span("s", 1n, 1n, 3, 6, D0) }),
+                node("y", "event", { span: span("s", 2n, 2n, 3, 6, D1) }),
+            ],
+            edges: [],
+        },
+        toolpair: {
+            sessionId: "s",
+            nodes: [
+                node("toolcall", "event", { span: span("s", 1n, 1n, 0, 3, D0) }),
+                node("toolresult", "event", { span: span("s", 2n, 2n, 0, 3, D1) }),
+            ],
+            edges: [edge("toolcall", "toolresult", "tool-pair")],
+        },
+        chain8: {
+            sessionId: "s",
+            nodes: [0, 1, 2, 3, 4, 5, 6, 7, 8].map((i) => node(`n${i}`, "event", { span: span("s", BigInt(i + 1), BigInt(i + 1), 0, 3, D0) })),
+            edges: [0, 1, 2, 3, 4, 5, 6, 7].map((i) => edge(`n${i + 1}`, `n${i}`, "depends")),
+        },
+    };
+    const g = cases[name];
+    assert.ok(g, `dag materializer missing for "${name}"`);
+    // Give every node a DISTINCT, non-overlapping byte window so the builder's
+    // digest-conflict rule (which only fires on genuinely shared bytes) does not
+    // misfire on adjacent ordering-test nodes. The two digest-* graphs intentionally
+    // KEEP overlapping spans to exercise that rule, so they are excluded here.
+    const overlapIntentional = name === "digest-conflict" || name === "digest-agree";
+    const nodes = overlapIntentional
+        ? g.nodes
+        : g.nodes.map((n, i) => n.span === undefined
+            ? n
+            : { ...n, span: { ...n.span, startByte: i * 4, endByte: i * 4 + 4 } });
+    const built = buildPromptDag({
+        sessionId: g.sessionId,
+        sourceHighWater: 100n,
+        nodes,
+        edges: g.edges,
+    });
+    return {
+        buildOk: built.ok,
+        buildCodes: built.ok ? [] : built.codes,
+        dag: built.ok
+            ? built.dag
+            : {
+                schema: "prompt-dag-v1",
+                sessionId: g.sessionId,
+                sourceHighWater: 100n,
+                nodes: [...g.nodes].sort(compareNodes),
+                edges: [...g.edges].sort(compareEdges),
+            },
+    };
+}
+/** Validate a materialized DAG, returning order / failure codes / digest. */
+export function runDagScenario(fx) {
+    const { scenario, graph, mutateDigest } = fx.input;
+    const base = materializeDag(graph ?? "linear");
+    // Structural REJECTION scenarios stop at the builder (no validation). Build
+    // ACCEPTANCE scenarios (build-linear / build-digest-agree) succeed and must
+    // still be validated for their topological order.
+    const structuralReject = [
+        "build-mixed-session",
+        "build-duplicate-id",
+        "build-missing-endpoint",
+        "build-invalid-span",
+        "build-synthetic-with-span",
+        "build-digest-conflict",
+        "build-unknown-incompatible",
+        "build-tool-pair-split",
+    ];
+    if (structuralReject.includes(scenario)) {
+        // Prefer the more specific tool-pair rejection when both it and a generic
+        // missing-endpoint code are present (a split tool pair is also missing an
+        // endpoint, but the tool-pair split is the precise failure).
+        const codes = base.buildCodes;
+        const code = codes.includes("DAG_TOOL_PAIR_SPLIT")
+            ? "DAG_TOOL_PAIR_SPLIT"
+            : codes[0];
+        return { ok: base.buildOk, code };
+    }
+    // A built DAG is required for validation scenarios.
+    assert.ok(base.buildOk, `${fx.id}: builder must succeed before validation`);
+    const dag = base.dag;
+    const v = validatePromptDag(dag);
+    const digest = dagDigest(dag);
+    if (fx.expected.permutationInvariant) {
+        // Re-run with a shuffled node/edge array; order + digest must be identical.
+        const permNodes = shuffle([...dag.nodes]);
+        const permEdges = shuffle([...dag.edges]);
+        const perm = buildPromptDag({
+            sessionId: dag.sessionId,
+            sourceHighWater: dag.sourceHighWater,
+            nodes: permNodes,
+            edges: permEdges,
+        });
+        assert.ok(perm.ok, `${fx.id}: permuted build must succeed`);
+        const vPerm = validatePromptDag(perm.dag);
+        const orderSame = v.ok && vPerm.ok && eq(v.order, vPerm.order);
+        const digestSame = dagDigest(perm.dag) === digest;
+        return { ok: true, permutationInvariant: orderSame, digestStable: digestSame };
+    }
+    if (fx.expected.digestStable) {
+        const perm = buildPromptDag({
+            sessionId: dag.sessionId,
+            sourceHighWater: dag.sourceHighWater,
+            nodes: shuffle([...dag.nodes]),
+            edges: shuffle([...dag.edges]),
+        });
+        assert.ok(perm.ok);
+        return { ok: true, digestStable: dagDigest(perm.dag) === digest };
+    }
+    if (fx.expected.digestSensitive) {
+        const mutated = {
+            ...dag,
+            nodes: dag.nodes.map((n, i) => i === 0 ? { ...n, payloadDigest: `pd:mutated-${n.id}` } : n),
+        };
+        return { ok: true, digestSensitive: dagDigest(mutated) !== digest };
+    }
+    if (fx.expected.orderIsTotal) {
+        const ok = v.ok && v.order.length === dag.nodes.length && new Set(v.order).size === dag.nodes.length;
+        return { ok, orderIsTotal: ok };
+    }
+    if (fx.expected.orderLength !== undefined) {
+        return { ok: v.ok, orderLength: v.ok ? v.order.length : 0 };
+    }
+    // Plain order / failure-code scenarios.
+    if (!v.ok)
+        return { ok: false, code: v.codes[0] };
+    void mutateDigest;
+    return { ok: true, order: [...v.order] };
+}