pi-mega-compact 0.20.2 → 0.20.3

package/dist/config/vector-cortex.js

@@ -159,6 +159,19 @@ export const VC4B_ENABLED = () => sprintFlag("MEGACOMPACT_VC4B");
  * never in EXCLUDED_SETTINGS), mirroring VC4A/VC4B.
  */
 export const VC4C_ENABLED = () => sprintFlag("MEGACOMPACT_VC4C");
+/**
+ * VC5A — PromptDagV1 + budgeted portfolio planner. Default ON.
+ * `MEGACOMPACT_VC5A=0` disables and is byte-identical to the predecessor
+ * (VC4C): no prompt DAG is built or validated, no budgeted plan is selected,
+ * the `vector_cortex_plan_selected` / `vector_cortex_plan_mandatory_overflow`
+ * events are never emitted, and the prompt continues to be built by the
+ * predecessor VC4C closure/reconstruction path (its goldens are unchanged).
+ * The builder/validator/portfolio functions are PURE — flag OFF gates the
+ * reporter + dashboard seam, never the arithmetic. This flag MUST also be a
+ * dashboard SETTINGS toggle (visible in config UI, never in EXCLUDED_SETTINGS),
+ * mirroring VC4A/VC4B/VC4C.
+ */
+export const VC5A_ENABLED = () => sprintFlag("MEGACOMPACT_VC5A");
 // ---------------------------------------------------------------------------
 // Breaker state machine constants (TRIAD_RESILIENCE.md §breaker).
 // Rolled numbers for one 60s window; VC0C consumes these at its breaker seam.

package/dist/config.js

@@ -114,4 +114,4 @@ export const NEW_UI = () => ragEnabled("MEGACOMPACT_NEW_UI");
 // default ON, `=0`/`_DISABLED` off. Re-exported from src/config/vector-cortex.ts
 // so root consumers share one source of truth.
 // ---------------------------------------------------------------------------
-export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, VC2B_ENABLED, VC2C_ENABLED, VC3A_ENABLED, VC3B_ENABLED, VC3C_ENABLED, VC4A_ENABLED, VC4B_ENABLED, VC4C_ENABLED, BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./config/vector-cortex.js";
+export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, VC2B_ENABLED, VC2C_ENABLED, VC3A_ENABLED, VC3B_ENABLED, VC3C_ENABLED, VC4A_ENABLED, VC4B_ENABLED, VC4C_ENABLED, VC5A_ENABLED, BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./config/vector-cortex.js";

package/dist/extensions/dashboard-server/routes-rag-settings-helpers.js

@@ -149,6 +149,7 @@ export const SETTINGS = [
             boolDirect("MEGACOMPACT_VC4A", "VC4A Dual-Tier Shards", "SemanticShardV1/ExactShardV1/ShardManifestV1: partition a session ONLY at complete EventV2 boundaries; exact shards preserve every tool call/result pair, anchor and invalid UTF-8 event as original bytes (pairs never split across exact shards); manifest enforces disjoint sorted ranges + complete protected-span coverage. OFF = mode C, exact anchors/current transcript only, byte-identical predecessor.", true),
             boolDirect("MEGACOMPACT_VC4B", "VC4B Residual Basis Parity", "Residual codec: orthonormal DCT-II basis + int16 block quantization + block-scoped exact correction stream + (9,6) Reed-Solomon parity shards with SHA-256 corruption detection; admission gates on encodedSize <= 95% of exact-compressed size. OFF = mode C, no residual artifact produced, byte-identical predecessor.", true),
             boolDirect("MEGACOMPACT_VC4C", "VC4C Reconstruction Fidelity", "Conservative closure + source-order assembly + reconstruction validator: recursively closes dependencies and whole tool pairs to a fixed point, resolves contradictions by retaining the later exact source resolution, assembles spans solely by source range, and rejects missing anchors / split pairs / digest mismatch / unresolved contradiction. Mandatory token estimate is content-only and handed unchanged to VC5A. OFF = mode C, no closure/validator, byte-identical predecessor (VC4B).", true),
+            boolDirect("MEGACOMPACT_VC5A", "VC5A PromptDagV1 + Budgeted Planner", "Single-session DAG (PromptDagV1) + budgeted 0/1 portfolio planner: builds a stable Kahn-ordered DAG, computes the mandatory dependency/tool/anchor closure before optional selection, returns MANDATORY_CLOSURE_OVER_BUDGET with evidence preserved on overflow, and runs a utility-per-token portfolio that never exceeds the remaining budget. Framing is owned here, not in VC4C. OFF = byte-identical predecessor (VC4C).", true),
         ],
     },
     {

package/dist/extensions/dashboard-server/routes-vector-cortex-plans.js

@@ -0,0 +1,49 @@
+/**
+ * dashboard-server/routes-vector-cortex-plans.ts — VC5A PromptDagV1 + budgeted
+ * planner dashboard route.
+ *
+ * Reader-only GET /api/vector-cortex/plans returning ONLY plan manifests — the
+ * registered PromptDagV1 (DAG-001..030) and budgeted-planner (PLN-001..020)
+ * identifier counts, plus a reader-only plans array. NEVER exposes session
+ * payloads, prompt text, byte spans, or source bytes (reader-only,
+ * SECURITY_PRIVACY). Flag-gated on MEGACOMPACT_VC5A: `enabled:false` when off
+ * (byte-identical to the pre-VC5A predecessor).
+ *
+ * The VC5A planner is PURE IN-MEMORY logic in this sprint (it has no durable plan
+ * store yet), so the per-run plan outputs are not persisted. The route reports
+ * the registered manifest layout truthfully: `enabled` reflects the flag, the
+ * dag/planner counts come from the registered conformance ID range, and `plans`
+ * is empty until a future sprint persists selected plans. Non-fatal: an internal
+ * error degrades to `enabled:false` with empty arrays.
+ *
+ * Guardrails: PREVENT-PI-004 (local filesystem / in-process state only),
+ * PREVENT-011 (no `any`), reader-only aggregate (counts + manifests only).
+ */
+import { VC5A_ENABLED } from "../../src/config.js";
+import { DAG_IDS } from "../../src/vector-cortex/prompt-dag/types.js";
+import { PLN_IDS } from "../../src/vector-cortex/planner/types.js";
+import { sendJson } from "./routes-vector-cortex-shared.js";
+/**
+ * Reader-only GET /api/vector-cortex/plans (VC5A).
+ */
+export function handleVectorCortexPlans(req, res, _ctx) {
+    const url = req.url ?? "";
+    const path = url.split("?")[0] ?? url;
+    if (path !== "/api/vector-cortex/plans")
+        return false;
+    if (req.method !== "GET") {
+        // Reader-only path: cannot be "off" without a GET; it is genuinely read-only.
+        sendJson(res, 405, { error: "method_not_allowed" });
+        return true;
+    }
+    const enabled = VC5A_ENABLED();
+    const body = {
+        enabled,
+        dagCount: enabled ? DAG_IDS.length : 0,
+        plannerCount: enabled ? PLN_IDS.length : 0,
+        plans: [],
+        updatedAt: new Date().toISOString(),
+    };
+    sendJson(res, 200, body);
+    return true;
+}

package/dist/extensions/dashboard-server/routes-vector-cortex.js

@@ -21,3 +21,4 @@ export { handleVectorCortexQuery } from "./routes-vector-cortex-query.js";
 export { handleVectorCortexShards } from "./routes-vector-cortex-shards.js";
 export { handleVectorCortexResidual } from "./routes-vector-cortex-residual.js";
 export { handleVectorCortexReconstruct } from "./routes-vector-cortex-reconstruct.js";
+export { handleVectorCortexPlans } from "./routes-vector-cortex-plans.js";

package/dist/extensions/dashboard-server/routes.js

@@ -23,4 +23,4 @@ export { handleRagSettings } from "./routes-rag-settings.js";
 export { handleRagMetrics } from "./routes-rag-metrics.js";
 export { handleModelThresholds } from "./routes-model-thresholds.js";
 export { handleWiki } from "./routes-wiki.js";
-export { handleVectorCortexEvaluation, handleVectorCortexHealth, handleVectorCortexBreakersReset, handleVectorCortexLedger, handleVectorCortexTopology, handleVectorCortexQuery, handleVectorCortexShards, handleVectorCortexResidual, handleVectorCortexReconstruct, } from "./routes-vector-cortex.js";
+export { handleVectorCortexEvaluation, handleVectorCortexHealth, handleVectorCortexBreakersReset, handleVectorCortexLedger, handleVectorCortexTopology, handleVectorCortexQuery, handleVectorCortexShards, handleVectorCortexResidual, handleVectorCortexReconstruct, handleVectorCortexPlans, } from "./routes-vector-cortex.js";

package/dist/extensions/dashboard-server/server.js

@@ -14,7 +14,7 @@ import { createRequire } from "node:module";
 import { NEW_UI } from "../../src/config.js";
 import { log, setLogPath, setDashboardServerVersion } from "./state.js";
 import { detectTailscaleIP } from "./tailscale.js";
-import { buildRouteContext, handleIndex, handleRepoIndex, handleEvents, handleGameState, handleGameScores, handlePerf, handlePerfSamples, handleAchievements, handleSessions, handleTopics, handleTurns, handleMaintenance, handleProviderCache, handleCacheStripes, handleMemoryStatus, handleSetupStatus, handleSetupDetect, handleSetupConfigure, handleMemoryMap, handleRaptorTree, handleRaptorBuildHistory, handleContextHealth, handleCachePoison, handleHealthSettings, handleEmbedderHealth, handleRagSettings, handleRagMetrics, handleModelThresholds, handleWiki, handleVectorCortexEvaluation, handleVectorCortexHealth, handleVectorCortexBreakersReset, handleVectorCortexLedger, handleVectorCortexTopology, handleVectorCortexQuery, handleVectorCortexShards, handleVectorCortexResidual, handleVectorCortexReconstruct, handleStatic, } from "./routes.js";
+import { buildRouteContext, handleIndex, handleRepoIndex, handleEvents, handleGameState, handleGameScores, handlePerf, handlePerfSamples, handleAchievements, handleSessions, handleTopics, handleTurns, handleMaintenance, handleProviderCache, handleCacheStripes, handleMemoryStatus, handleSetupStatus, handleSetupDetect, handleSetupConfigure, handleMemoryMap, handleRaptorTree, handleRaptorBuildHistory, handleContextHealth, handleCachePoison, handleHealthSettings, handleEmbedderHealth, handleRagSettings, handleRagMetrics, handleModelThresholds, handleWiki, handleVectorCortexEvaluation, handleVectorCortexHealth, handleVectorCortexBreakersReset, handleVectorCortexLedger, handleVectorCortexTopology, handleVectorCortexQuery, handleVectorCortexShards, handleVectorCortexResidual, handleVectorCortexReconstruct, handleVectorCortexPlans, handleStatic, } from "./routes.js";
 export async function launchDashboardServer(stateDir) {
     // Our own package version — exposed at /api/version so the launcher can
     // detect a stale server (started by an older build) and replace it on
@@ -273,6 +273,8 @@ export async function launchDashboardServer(stateDir) {
             return;
         if (handleVectorCortexReconstruct(req, res, ctx))
             return;
+        if (handleVectorCortexPlans(req, res, ctx))
+            return;
         handleStatic(req, res, ctx);
     });
     // Bind base + range are env-configurable so tests can use a private,

package/dist/src/config/vector-cortex.js

@@ -159,6 +159,19 @@ export const VC4B_ENABLED = () => sprintFlag("MEGACOMPACT_VC4B");
  * never in EXCLUDED_SETTINGS), mirroring VC4A/VC4B.
  */
 export const VC4C_ENABLED = () => sprintFlag("MEGACOMPACT_VC4C");
+/**
+ * VC5A — PromptDagV1 + budgeted portfolio planner. Default ON.
+ * `MEGACOMPACT_VC5A=0` disables and is byte-identical to the predecessor
+ * (VC4C): no prompt DAG is built or validated, no budgeted plan is selected,
+ * the `vector_cortex_plan_selected` / `vector_cortex_plan_mandatory_overflow`
+ * events are never emitted, and the prompt continues to be built by the
+ * predecessor VC4C closure/reconstruction path (its goldens are unchanged).
+ * The builder/validator/portfolio functions are PURE — flag OFF gates the
+ * reporter + dashboard seam, never the arithmetic. This flag MUST also be a
+ * dashboard SETTINGS toggle (visible in config UI, never in EXCLUDED_SETTINGS),
+ * mirroring VC4A/VC4B/VC4C.
+ */
+export const VC5A_ENABLED = () => sprintFlag("MEGACOMPACT_VC5A");
 // ---------------------------------------------------------------------------
 // Breaker state machine constants (TRIAD_RESILIENCE.md §breaker).
 // Rolled numbers for one 60s window; VC0C consumes these at its breaker seam.

package/dist/src/config.js

@@ -114,4 +114,4 @@ export const NEW_UI = () => ragEnabled("MEGACOMPACT_NEW_UI");
 // default ON, `=0`/`_DISABLED` off. Re-exported from src/config/vector-cortex.ts
 // so root consumers share one source of truth.
 // ---------------------------------------------------------------------------
-export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, VC2B_ENABLED, VC2C_ENABLED, VC3A_ENABLED, VC3B_ENABLED, VC3C_ENABLED, VC4A_ENABLED, VC4B_ENABLED, VC4C_ENABLED, BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./config/vector-cortex.js";
+export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, VC2B_ENABLED, VC2C_ENABLED, VC3A_ENABLED, VC3B_ENABLED, VC3C_ENABLED, VC4A_ENABLED, VC4B_ENABLED, VC4C_ENABLED, VC5A_ENABLED, BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./config/vector-cortex.js";

package/dist/src/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/src/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/src/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] };
+}