pi-mega-compact 0.20.1 → 0.20.3

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] };
+}

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

@@ -0,0 +1,59 @@
+/**
+ * prompt-dag/_acceptance-fixture.ts — conformance fixture I/O for VC5A DAG +
+ * planner acceptance rows.
+ *
+ * Reads the v2 conformance manifest + the per-sprint fixture files, and exposes
+ * the `DagFixture` / `PlnFixture` shapes the acceptance aggregator drives. No
+ * mocks/stubs: the fixtures are the committed canonical corpus.
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import assert from "node:assert/strict";
+const HERE = dirname(fileURLToPath(import.meta.url));
+function repoRoot(from) {
+    let dir = from;
+    for (let i = 0; i < 8; i++) {
+        if (existsSync(join(dir, "conformance", "vector-cortex")))
+            return dir;
+        const next = dirname(dir);
+        if (next === dir)
+            break;
+        dir = next;
+    }
+    throw new Error("conformance corpus not found above " + from);
+}
+export const REPO_ROOT = repoRoot(HERE);
+export const V2 = join(REPO_ROOT, "conformance", "vector-cortex", "v2");
+export function readManifest() {
+    return JSON.parse(readFileSync(join(V2, "manifest.json"), "utf8"));
+}
+/** Resolve a fixture row by ID, restricting to one of this sprint's two roots. */
+function readFixture(id, prefix) {
+    const m = readManifest();
+    const row = m.fixtures.find((f) => f.id === id && f.path.startsWith(`${prefix}/`));
+    assert.ok(row, `fixture ${id} registered under ${prefix}/ in manifest`);
+    return JSON.parse(readFileSync(join(V2, row.path), "utf8"));
+}
+export function dagFixture(id) {
+    return readFixture(id, "prompt-dag");
+}
+export function plnFixture(id) {
+    return readFixture(id, "planner");
+}
+/** Flag-pinned wrapper: VC5A gated by MEGACOMPACT_VC5A (defaults ON). */
+export function withFlagsOn(fn) {
+    return () => {
+        const saved = process.env.MEGACOMPACT_VC5A;
+        process.env.MEGACOMPACT_VC5A = "1";
+        try {
+            fn();
+        }
+        finally {
+            if (saved === undefined)
+                delete process.env.MEGACOMPACT_VC5A;
+            else
+                process.env.MEGACOMPACT_VC5A = saved;
+        }
+    };
+}

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

@@ -0,0 +1,17 @@
+/**
+ * prompt-dag/_acceptance-helpers.ts — barrel re-export for the VC5A DAG +
+ * planner acceptance rows.
+ *
+ * The implementation is split across focused sibling files to keep each under
+ * the src/ 500-line hard limit; this file is the single import surface the
+ * acceptance aggregator uses:
+ *   - `_acceptance-fixture.ts`  — manifest I/O + DagFixture/PlnFixture shapes + withFlagsOn
+ *   - `_acceptance-dag.ts`      — declarative DAG materialization + runDagScenario
+ *   - `_acceptance-planner.ts` — candidate-set materialization + runPlannerScenario
+ *   - `_acceptance-shuffle.ts` — deterministic eq/shuffle helpers
+ *
+ * Every function drives the REAL prompt-dag / planner logic — no mocks, no stubs.
+ */
+export { REPO_ROOT, V2, readManifest, dagFixture, plnFixture, withFlagsOn, } from "./_acceptance-fixture.js";
+export { materializeDag, runDagScenario } from "./_acceptance-dag.js";
+export { materializeCandidates, runPlannerScenario } from "./_acceptance-planner.js";

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

@@ -0,0 +1,153 @@
+/**
+ * prompt-dag/_acceptance-planner.ts — declarative candidate-set materialization
+ * + scenario driver for VC5A planner acceptance rows.
+ *
+ * Turns named candidate-set scenarios into real `PlanCandidate[]` values and
+ * drives them through the REAL portfolio planner (planPortfolio). The
+ * `mandatoryTokenEstimate` is the VC4C content-only figure = sum of mandatory
+ * content tokens (zero-framing fixtures pin this exactly).
+ */
+import assert from "node:assert/strict";
+import { planPortfolio, planManifestDigest, validatePlanManifest, } from "../planner/portfolio.js";
+import { DEFAULT_FRAMING } from "../planner/types.js";
+import { shuffle } from "./_acceptance-shuffle.js";
+export function materializeCandidates(name) {
+    const sets = {
+        // m1=10, m2=20 mandatory → 30 content tokens (zero-framing fixtures pin this).
+        "mandatory-only": [
+            { nodeId: "m1", tokenEstimate: 10, utility: 100, sourceSeq: 1n, mandatory: true },
+            { nodeId: "m2", tokenEstimate: 20, utility: 200, sourceSeq: 2n, mandatory: true },
+        ],
+        // Two mandatory nodes totalling 101 content tokens → over budget at 100.
+        "mandatory-101": [
+            { nodeId: "m1", tokenEstimate: 50, utility: 100, sourceSeq: 1n, mandatory: true },
+            { nodeId: "m2", tokenEstimate: 51, utility: 200, sourceSeq: 2n, mandatory: true },
+        ],
+        // Optional candidates: hi=10t/20u (ratio 2.0), mid=10t/10u (ratio 1.0), lo=10t/5u.
+        ratio: [
+            { nodeId: "hi", tokenEstimate: 10, utility: 20, sourceSeq: 1n, mandatory: false },
+            { nodeId: "mid", tokenEstimate: 10, utility: 10, sourceSeq: 2n, mandatory: false },
+            { nodeId: "lo", tokenEstimate: 10, utility: 5, sourceSeq: 3n, mandatory: false },
+        ],
+        // Equal ratios (1.0) → source seq tie-break (early=seq1 wins).
+        "tie-seq": [
+            { nodeId: "early", tokenEstimate: 10, utility: 10, sourceSeq: 1n, mandatory: false },
+            { nodeId: "late", tokenEstimate: 10, utility: 10, sourceSeq: 2n, mandatory: false },
+        ],
+        // Equal ratios AND equal source seq → lower ID bytes wins.
+        "tie-id": [
+            { nodeId: "bbb", tokenEstimate: 10, utility: 10, sourceSeq: 1n, mandatory: false },
+            { nodeId: "aaa", tokenEstimate: 10, utility: 10, sourceSeq: 1n, mandatory: false },
+        ],
+        // One indivisible optional node of 10t/10u: 0/1 means it is taken whole.
+        indivisible: [
+            { nodeId: "one", tokenEstimate: 10, utility: 10, sourceSeq: 1n, mandatory: false },
+        ],
+        // A zero-utility optional node must be omitted.
+        "zero-utility": [
+            { nodeId: "zero", tokenEstimate: 5, utility: 0, sourceSeq: 1n, mandatory: false },
+        ],
+        // An optional node incompatible with a mandatory node is omitted (the planner
+        // enforces `incompatiblePairs`; here `bad` is mutually exclusive with `m1`).
+        incompatible: [
+            { nodeId: "m1", tokenEstimate: 10, utility: 100, sourceSeq: 1n, mandatory: true },
+            { nodeId: "bad", tokenEstimate: 5, utility: 50, sourceSeq: 2n, mandatory: false },
+        ],
+        // Mixed: 2 mandatory + optional candidates exercising closure + selection.
+        mixed: [
+            { nodeId: "m1", tokenEstimate: 10, utility: 100, sourceSeq: 1n, mandatory: true },
+            { nodeId: "m2", tokenEstimate: 20, utility: 200, sourceSeq: 2n, mandatory: true },
+            { nodeId: "opt", tokenEstimate: 30, utility: 90, sourceSeq: 3n, mandatory: false },
+        ],
+    };
+    const set = sets[name];
+    assert.ok(set, `candidate-set materializer missing for "${name}"`);
+    return set;
+}
+function framing(zero) {
+    return zero ? { perNode: 0, overhead: 0 } : DEFAULT_FRAMING;
+}
+/**
+ * Drive a planner fixture scenario through the REAL portfolio planner. The
+ * `mandatoryTokenEstimate` is the VC4C CONTENT-ONLY figure = sum of mandatory
+ * content tokens (zero-framing fixtures make that the exact candidate sum).
+ */
+export function runPlannerScenario(fx) {
+    const { candidates: setName, tokenBudget, zeroFraming, permute, mutateTokensAfterPlan } = fx.input;
+    const cands = materializeCandidates(setName);
+    // VC4C content-only mandatory estimate = sum of mandatory content tokens.
+    const mandatoryTokenEstimate = cands
+        .filter((c) => c.mandatory)
+        .reduce((s, c) => s + c.tokenEstimate, 0);
+    const dagDigest = "deadbeef".repeat(8);
+    // The `incompatible` set wires an explicit mutual-exclusion pair (bad ⊥ m1) so
+    // the planner's incompatibility gate is exercised end-to-end.
+    const incompatiblePairs = setName === "incompatible" ? [["bad", "m1"]] : undefined;
+    const input = {
+        dagDigest,
+        candidates: permute ? shuffle([...cands]) : cands,
+        mandatoryTokenEstimate,
+        tokenBudget,
+        dependencyHighWater: 100n,
+        framing: framing(zeroFraming),
+        ...(incompatiblePairs ? { incompatiblePairs } : {}),
+    };
+    const res = planPortfolio(input);
+    if (fx.expected.permutationInvariant) {
+        const a = planPortfolio(input);
+        const b = planPortfolio({ ...input, candidates: shuffle([...cands]) });
+        const ids = (ok) => (ok.ok ? [...ok.plan.selectedNodeIds] : []);
+        return { ok: true, permutationInvariant: JSON.stringify(ids(a)) === JSON.stringify(ids(b)) };
+    }
+    if (!res.ok) {
+        // Over-budget failure: mandatory set preserved intact, demotes to C.
+        const mandatoryIds = cands.filter((c) => c.mandatory).map((c) => c.nodeId).sort();
+        const preserved = res.mandatory.slice().sort().join(",") === mandatoryIds.join(",");
+        return {
+            ok: false,
+            code: res.code,
+            mandatoryPreserved: preserved,
+            demotesToC: res.code === "MANDATORY_CLOSURE_OVER_BUDGET",
+        };
+    }
+    // ── Accepted-plan assertions ──
+    const plan = res.plan;
+    const selected = [...plan.selectedNodeIds];
+    const out = { ok: true, selected, tokenTotal: plan.tokenTotal };
+    if (fx.expected.firstSelected !== undefined)
+        out.firstSelected = selected[0];
+    if (fx.expected.withinBudget)
+        out.withinBudget = plan.tokenTotal <= tokenBudget;
+    if (fx.expected.noPartialSelection) {
+        out.noPartialSelection = cands.every((c) => !c.mandatory || selected.includes(c.nodeId));
+    }
+    if (fx.expected.planIsClosed) {
+        const mandatoryIds = cands.filter((c) => c.mandatory).map((c) => c.nodeId).sort();
+        out.planIsClosed = mandatoryIds.every((id) => selected.includes(id));
+    }
+    if (fx.expected.omittedOverBudget) {
+        const omit = plan.omissions.some((o) => o.reason === "over-budget");
+        out.omittedOverBudget = omit;
+    }
+    if (fx.expected.omittedZeroUtility) {
+        out.omittedZeroUtility = plan.omissions.some((o) => o.reason === "zero-utility");
+    }
+    if (fx.expected.omittedIncompatible) {
+        out.omittedIncompatible = plan.omissions.some((o) => o.reason === "incompatible");
+    }
+    // Manifest identity: a post-plan token mutation must fail revalidation.
+    if (mutateTokensAfterPlan) {
+        const pinned = planManifestDigest(plan, cands);
+        const mutated = cands.map((c, i) => (i === 0 ? { ...c, tokenEstimate: c.tokenEstimate + 1 } : c));
+        const check = validatePlanManifest(plan, mutated, pinned);
+        out.ok = check.ok; // false → plan rejected, never reaches provider
+        out.code = check.ok ? undefined : check.code;
+        return out;
+    }
+    if (fx.expected.manifestStable) {
+        const pinned = planManifestDigest(plan, cands);
+        const check = validatePlanManifest(plan, cands, pinned);
+        out.manifestStable = check.ok;
+    }
+    return out;
+}

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

@@ -0,0 +1,24 @@
+/**
+ * prompt-dag/_acceptance-shuffle.ts — small deterministic helpers shared by the
+ * VC5A acceptance DAG/planner materializers.
+ */
+/** Array element equality (length + pairwise). */
+export function eq(a, b) {
+    return a.length === b.length && a.every((v, i) => v === b[i]);
+}
+/**
+ * Fisher–Yates with a FIXED seed so permutation tests are reproducible across
+ * runs and machines (no Math.random in tests).
+ */
+export function shuffle(arr) {
+    const a = [...arr];
+    let seed = 0x9e3779b9;
+    for (let i = a.length - 1; i > 0; i--) {
+        seed = (seed * 1664525 + 1013904223) >>> 0;
+        const j = seed % (i + 1);
+        const t = a[i];
+        a[i] = a[j];
+        a[j] = t;
+    }
+    return a;
+}