in2-agent-server 0.20260821.185429

package/dist/tools/waves.js

@@ -0,0 +1,793 @@
+// plan_waves — derive the deploy order from the analyzers' own dependency data.
+//
+// WHY THIS IS NOT JUST A CONVENIENCE
+//
+// direct_apply is 44.6% of all time spent inside tools, and almost all of that is the ~45s checkOnly
+// every wave pays. CF76 ran SEVEN waves over 25 components. Wave count is therefore the single
+// biggest remaining lever on run time, and it was being set by hand each run, from a topo sort the
+// supervisor did in its head over fifteen separate plan.json files.
+//
+// Every input needed is already recorded: each analyzer writes the components it OWNS and, per
+// component, the `dependsOn` keys that must exist first. A dependency that is not owned by anyone in
+// this batch is already in the org, so it constrains nothing.
+//
+// CYCLES ARE REAL HERE AND MUST NOT SIMPLY REFUSE. Run against CF76's actual plans, the very first
+// thing this found was CustomObject:CF76_Intake_Request__c in a cycle: the object carries
+// compactLayoutAssignment so it depends on the compact layout, and the compact layout depends on the
+// object. That is not bad data. It is a genuine Salesforce shape, and it is resolved by deploying
+// the object TWICE — once plain, once carrying the assignment. CF76's supervisor worked that out
+// unaided and then hit the assembler's "authored twice" refusal for it.
+//
+// A COMPONENT MAY HAVE TWO STATES IN ONE BATCH, and that is what stops the false cycles.
+//
+// The remediation above used to end "build the late wave by hand", because nothing could say which
+// of a component's two files belonged in which wave. It can now: plan.json declares an ordered chain
+// of revisions per component (`intent` + `authoredFile`), `core/revisionChain.ts` derives and orders
+// it, and the predecessor edge is injected into THIS graph before leveling — so a create in one
+// requirement and an update in another is an ordinary two-wave edge. Measured cost of not having it
+// (EV-31…40, 2026-08-02): ten such pairs reported as ten "cycles", 23 of 53 components unplaceable,
+// and an operator hand-copying files into wave trees, which bypasses exactly the safety wave
+// assembly exists to provide.
+//
+// Late-facet stripping and cycle reporting SURVIVE as diagnostics — the shapes are still real, and
+// the planner still cannot tell which state of a component belongs where. What changed is the
+// remediation: declare the second state as a second entry, and ordering plus assembly follow from
+// the plan. REPORT-ONLY, deliberately: this tool never writes the split it names. Emitting plan.json
+// entries would make the planner an author, and the one thing it cannot know is what the second
+// state should CONTAIN.
+//
+// INTENT IS CROSS-CHECKED HERE, BEFORE ANYTHING TOUCHES THE ORG (R7). The check is grounded in this
+// session's own projection and NOTHING ELSE — local disk, no org round-trip — and it is three-valued
+// on purpose: see `projectionExistence`.
+//
+// DELETIONS ARE ORDERED HERE AND EXECUTED NOWHERE. A component's last state can be `intent: "delete"`,
+// which carries no authored file and so can never be a wave member. What it does carry is a POSITION,
+// and until this landed that position existed only in an analyzer's prose: the plan that forced this
+// change had to write "the destructive step's position relative to the other waves is the supervisor's
+// to sequence by hand" (REQ-15747). `placeDeletions` derives it from the same wave levels everything
+// else is ordered by. The report then hands back the members in direct_apply's `deletes` shape and
+// says plainly that nothing has been deleted — declaring a deletion orders it; executing it stays an
+// explicit tool call, because a destructive package rolls back whole and destruction is a decision.
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import { z } from "zod";
+import { fail, internalError, ok } from "../core/result.js";
+import { WorkspaceError, sessionDir } from "../core/workspace.js";
+import { checkRevisionBindings, readPlanFile } from "../core/planFile.js";
+import { auditPlanFragments, renderFragmentAudit } from "../core/planFragments.js";
+import { deriveRevisionChains } from "../core/revisionChain.js";
+import { collectSessionProjection, describeSources } from "../direct/sessionProjection.js";
+import { writeWaveDerivation } from "../direct/waveDerivation.js";
+import { plannedConfigurationItems, writePlannedScope } from "../direct/plannedScope.js";
+import { resolveAuthored } from "../direct/waveAssembly.js";
+import { resolveSessionOrg } from "../core/sessionOrg.js";
+import { loadRequirementsIndex, loadSession } from "./session.js";
+/**
+ * A parent depending on its own child — `CustomObject:X` needing `CompactLayout:X.Y`.
+ *
+ * On a component's FIRST state this is never a real ordering constraint, it is a LATE FACET: the
+ * parent deploys first without that element, the child follows, and the parent is re-deployed
+ * carrying it. Left in the graph it is a cycle, and one such edge stranded 22 of CF76's 26
+ * components as unorderable — technically correct and completely useless to act on.
+ *
+ * On a LATER REVISION the same edge is the whole point of the split and is honoured, not dropped —
+ * see the guard at the drop site for why that provably cannot cycle.
+ *
+ * Recognised structurally rather than by a type list: the dependency's fullName is the dependent's
+ * fullName plus a dot and more. That is precisely the source-format parent/child relationship, and
+ * it does not need maintaining as Salesforce adds types.
+ */
+function isLateFacetEdge(fromFullName, depKey) {
+    const depFullName = depKey.slice(depKey.indexOf(":") + 1);
+    return depFullName.startsWith(`${fromFullName}.`);
+}
+/**
+ * A fullName that is an analyzer's placeholder rather than a real API name.
+ *
+ * TYPE-AWARE, because "contains a space" is not the placeholder signal it looks like: a Layout
+ * fullName is `Object-Layout Label` and the label half legitimately carries spaces, and folder
+ * types carry `/` and `$` (unfiled$public/My_Template). The original blanket [A-Za-z0-9_.\-]
+ * check excluded every real Layout from ordering and told the supervisor to "resolve the
+ * placeholder" — an instruction that, followed, corrupts a correct plan.json (live-caught CF79;
+ * the layout was hand-placed into the last wave instead).
+ */
+export function isPlaceholderFullName(typeName, fullName) {
+    if (/[<>]/.test(fullName))
+        return true; // live: `IN78_Test_Console__c.<UNNAMED_PICKLIST — …>`
+    if (typeName === "Layout")
+        return !/^[A-Za-z0-9_]+-[^<>]+$/.test(fullName);
+    return !/^[A-Za-z0-9_.$/\-]+$/.test(fullName);
+}
+/**
+ * Longest-path level assignment, with cycles reported rather than thrown.
+ *
+ * A component's wave is one past the deepest thing it depends on, so the wave count equals the
+ * longest dependency chain — the fewest waves the batch can be delivered in. Components in a cycle
+ * get no level; they are returned separately for the caller to break.
+ */
+export function planWaves(owned) {
+    // Dedupe FIRST, and say so. A component listed twice in one plan is the double-authoring shape
+    // assembly refuses on, and counting the entries rather than the components made this report
+    // claim "25 of 26 ordered" — a phantom missing component that would send someone hunting for it.
+    //
+    // Deduped by NODE, not by key: two revisions of one component are two nodes and are not a
+    // duplicate. Rows that carry no `node` fall back to the key, so a caller that knows nothing about
+    // revisions gets exactly today's behavior.
+    const byNode = new Map();
+    const duplicates = [];
+    for (const o of owned) {
+        const id = o.node ?? o.key;
+        const seen = byNode.get(id);
+        if (seen) {
+            duplicates.push(`${o.key} listed twice by ${seen.extId === o.extId ? o.extId : `${seen.extId} and ${o.extId}`}`);
+            // Union the dependencies; either listing may carry an edge the other lacks.
+            seen.dependsOn = [...new Set([...seen.dependsOn, ...o.dependsOn])];
+            continue;
+        }
+        byNode.set(id, { ...o, dependsOn: [...o.dependsOn] });
+    }
+    const unique = [...byNode.values()];
+    const ownedKeys = new Set(unique.map((o) => o.key));
+    const nodeOf = (o) => o.node ?? o.key;
+    // A dependency names a COMPONENT, and it is satisfied by that component's FIRST state — "X must
+    // exist first" is answered by the create, not by every later state of it. Resolving dependents
+    // onto the last revision instead would both over-constrain the batch and, wherever the chain's own
+    // edges close the loop, manufacture the very cycle the revision model exists to dissolve.
+    const rootNode = new Map();
+    for (const o of unique)
+        if (!o.predecessor && !rootNode.has(o.key))
+            rootNode.set(o.key, nodeOf(o));
+    for (const o of unique)
+        if (!rootNode.has(o.key))
+            rootNode.set(o.key, nodeOf(o));
+    const lateFacets = [];
+    const inBatch = new Map();
+    for (const o of unique) {
+        const id = nodeOf(o);
+        const deps = new Set();
+        for (const d of o.dependsOn) {
+            const target = rootNode.get(d);
+            if (target === undefined)
+                continue; // nothing here owns it — it is already in the org
+            // An entry depending on its OWN key reads "after the previous state of me" (the same reading
+            // core/revisionChain.ts gives it). On a later revision that IS the chain edge and resolves to
+            // the predecessor; on the first state there is no previous state, and treating it as an edge
+            // is precisely how a one-node "cycle" gets manufactured — ten of them on the EV run.
+            if (target === id)
+                continue;
+            // The late-facet drop applies ONLY to a component's first state, where honouring the edge is
+            // the CF76 cycle. On a later revision it is honoured: dependencies resolve through rootNode
+            // to FIRST states, so nothing can ever depend on a non-root revision — the only edges into
+            // one are chain edges from still-later revisions, which point backwards — and an out-edge
+            // from a non-root node therefore cannot close a cycle. Before this guard the drop was
+            // unconditional (it predates the revision model), so the split produced a revision that
+            // DEPLOYED but never ORDERED: live-caught on CF81, where the object re-emitted to carry
+            // compactLayoutAssignment sat in wave 2 while its CompactLayout was built in wave 3, and the
+            // operator placed the revision in wave 4 by hand. This guard puts it there itself.
+            if (o.predecessor === undefined && isLateFacetEdge(o.fullName, d)) {
+                lateFacets.push({ component: o.key, waitsFor: d });
+                continue; // first state: ordered as if independent; the re-deploy is reported instead
+            }
+            deps.add(target);
+        }
+        // The chain edge, injected BEFORE leveling: a create and its update are two waves apart by
+        // construction. That also keeps the assembler's invariant — one revision per key per wave —
+        // true without the assembler having to enforce an ordering it cannot see.
+        if (o.predecessor !== undefined && byNode.has(o.predecessor))
+            deps.add(o.predecessor);
+        inBatch.set(id, [...deps]);
+    }
+    const level = new Map();
+    const cycles = [];
+    const state = new Map();
+    const labelOf = (id) => {
+        const o = byNode.get(id);
+        if (!o)
+            return id;
+        return o.path ? `${o.key} (${o.path})` : o.key;
+    };
+    const visit = (id, stack) => {
+        const known = level.get(id);
+        if (known !== undefined)
+            return known;
+        if (state.get(id) === "visiting") {
+            // Record the cycle exactly once, from where it closes.
+            const at = stack.indexOf(id);
+            if (at >= 0) {
+                const ring = stack.slice(at);
+                const seen = ring.slice().sort().join("|");
+                if (!cycles.some((c) => c.slice().sort().join("|") === seen))
+                    cycles.push(ring.map(labelOf));
+            }
+            return null;
+        }
+        state.set(id, "visiting");
+        let deepest = -1;
+        let broken = false;
+        for (const dep of inBatch.get(id) ?? []) {
+            const d = visit(dep, [...stack, id]);
+            if (d === null)
+                broken = true;
+            else
+                deepest = Math.max(deepest, d);
+        }
+        state.set(id, "done");
+        if (broken)
+            return null;
+        const assigned = deepest + 1;
+        level.set(id, assigned);
+        return assigned;
+    };
+    for (const o of unique)
+        visit(nodeOf(o), []);
+    const depth = level.size > 0 ? Math.max(...level.values()) + 1 : 0;
+    const waves = Array.from({ length: depth }, () => []);
+    for (const [id, lv] of level) {
+        const o = byNode.get(id);
+        waves[lv].push({ typeName: o.typeName, fullName: o.fullName, ...(o.path ? { path: o.path } : {}) });
+    }
+    // Stable order inside a wave so two runs of the same batch produce the same plan.
+    for (const w of waves)
+        w.sort((a, b) => `${a.typeName}:${a.fullName}`.localeCompare(`${b.typeName}:${b.fullName}`));
+    const unowned = [...new Set(unique.flatMap((o) => o.dependsOn.filter((d) => !ownedKeys.has(d))))].sort();
+    return { waves, cycles, lateFacets, duplicates, unowned, waveOf: level, rootNode };
+}
+/**
+ * Place each declared deletion AFTER the waves that touch its component.
+ *
+ * A deletion is not a wave member — it has no authored file and deploys through `direct_apply`'s
+ * `deletes` argument, an mdapi destructive package rather than a source deploy. What it does have is
+ * a POSITION, and until now that position lived only in an analyzer's prose: the live plan this
+ * model comes from had to write "the destructive step's position relative to the other waves is the
+ * supervisor's to sequence by hand" (REQ-15747, assumption A3). It is derivable, so it is derived.
+ *
+ * The constraint has two sources, and both are just wave levels the planner already computed:
+ * the chain predecessor (the batch's own create/update of the same component — a deletion never
+ * precedes the wave that builds what it deletes) and the deletion's `dependsOn` keys, resolved onto
+ * each component's FIRST state exactly as every other dependent is (`planWaves`' `rootNode`).
+ *
+ * ORDERING ONLY. Nothing here deletes anything, and nothing downstream reads this as permission to.
+ */
+export function placeDeletions(plan, deletions) {
+    return deletions.map((d) => {
+        const because = [];
+        let after = -1;
+        let unplaceable = false;
+        const consider = (node, label) => {
+            if (node === undefined)
+                return;
+            const level = plan.waveOf.get(node);
+            if (level === undefined) {
+                // The thing it waits on never got a wave — it is in a cycle. Placing the deletion anyway
+                // would order it against a wave that does not exist.
+                unplaceable = true;
+                return;
+            }
+            if (level + 1 > after) {
+                after = level + 1;
+                because.length = 0;
+            }
+            if (level + 1 === after)
+                because.push(label);
+        };
+        consider(d.predecessorNode, `this batch ${d.chainRoot === "create" ? "creates" : "changes"} ${d.key}`);
+        for (const dep of d.dependsOn) {
+            if (dep === d.key)
+                continue; // its own chain edge, already carried by predecessorNode
+            consider(plan.rootNode.get(dep), `depends on ${dep}`);
+        }
+        return {
+            key: d.key,
+            typeName: d.typeName,
+            fullName: d.fullName,
+            extId: d.extId,
+            afterWave: after > 0 ? after : null,
+            because,
+            createdInBatch: d.chainRoot === "create",
+            unplaceable
+        };
+    });
+}
+/**
+ * THE EXISTENCE PREDICATE, three-valued, from this session's own projection and nothing else.
+ *
+ * `present` and `absent` are both EVIDENCE and are read as such: they drive intent inference, the
+ * create-on-existing hazard, and the update-without-root refusal. `unknown` drives none of them.
+ *
+ * The line between `absent` and `unknown` is the whole point, and it is drawn where the projection
+ * can actually demonstrate coverage: a component the projection ASKED THE ORG ABOUT and got
+ * `found: false` for is absent; a component no projection in this session ever named is unknown.
+ * `collectSessionProjection` is narrower than the batch by construction
+ * (`direct/sessionProjection.ts:12-19`) — it is a point-in-time read of a scope the supervisor
+ * chose — so non-observation is not observation of absence, and manufacturing `absent` from it
+ * would ground a refusal (`UPDATE_WITHOUT_ROOT`) on components that demonstrably exist.
+ *
+ * The view's `objects` set is deliberately NOT read as coverage. It records which objects some
+ * projection enumerated, but the view drops each enumeration's `errors[]`, so "the object was in
+ * scope" cannot establish "and this field would have been seen if it existed". Inferring absence
+ * from it would be exactly the manufactured coverage this predicate exists to avoid.
+ */
+export function projectionExistence(view) {
+    return ({ key }) => {
+        const observed = view.components.get(key);
+        if (!observed)
+            return "unknown";
+        return observed.found ? "present" : "absent";
+    };
+}
+const revisionNode = (entry) => `${entry.key}#${entry.extId}#${entry.index}`;
+/**
+ * Plan entries → wave-graph rows, via the revision chains.
+ *
+ * Pure over the entries plus the predicate, so the EV corpus regression runs against the same
+ * transcription `core/revisionChain.test.ts` asserts on, with no session on disk.
+ *
+ * `priorRefusals` are the per-file findings `parsePlanFile` already made (an illegal `intent`, a
+ * within-file duplicate). They are merged rather than re-derived, and their keys are excluded from
+ * planning for the same reason the chain module's own refusals are: an entry whose declared intent
+ * is not a legal value has not told anyone where it belongs.
+ */
+export function planRevisions(entries, exists, priorRefusals = []) {
+    // R3 over the WHOLE BATCH. The shape this model exists for puts a component's two revisions in
+    // two different plan.json files, where each file's own check sees one entry per key and finds
+    // nothing wrong (`core/planFile.ts:311-320`).
+    const bindingRefusals = checkRevisionBindings(entries);
+    const refusals = [];
+    const seenRefusal = new Set();
+    const addRefusal = (r) => {
+        const at = `${r.code}|${r.key}`;
+        if (seenRefusal.has(at))
+            return;
+        seenRefusal.add(at);
+        refusals.push(r);
+    };
+    for (const r of bindingRefusals)
+        addRefusal({ code: r.code, key: r.key, message: r.message });
+    for (const r of priorRefusals)
+        addRefusal({ code: r.code, key: r.key, message: r.message });
+    const blocked = new Set(refusals.map((r) => r.key));
+    // Only the DEPLOYABLE entries of a blocked key are withheld; a route sharing that key still
+    // reports as a route, because dropping it would make the batch look smaller than it is.
+    const chainable = entries.filter((e) => !(e.deployable && blocked.has(e.key)));
+    const derived = deriveRevisionChains(chainable, exists);
+    for (const r of derived.refusals)
+        addRefusal({ code: r.code, key: r.key, message: r.message });
+    const owned = [];
+    const deletions = [];
+    const createOnExisting = [];
+    for (const chain of derived.chains) {
+        // The DEPLOYED states are the wave rows. A terminal delete is lifted out first, so a
+        // create-then-delete chain reads as a single-revision key here — one wave row with no `path`,
+        // exactly today's shape — and the deletion travels as an ordering constraint instead.
+        const states = chain.revisions.filter((rev) => rev.intent !== "delete");
+        // A single-revision key keeps `key` as its node and carries no `path`, so the wave entry shape
+        // is exactly today's for every batch that declares one state per component. Additive, per R12.
+        const multi = states.length > 1;
+        let previous;
+        for (const rev of states) {
+            const node = multi ? revisionNode(rev.entry) : chain.key;
+            owned.push({
+                key: chain.key,
+                typeName: chain.typeName,
+                fullName: chain.fullName,
+                extId: rev.entry.extId,
+                dependsOn: [...rev.entry.dependsOn],
+                node,
+                ...(multi && rev.entry.authoredFile ? { path: rev.entry.authoredFile } : {}),
+                ...(previous !== undefined ? { predecessor: previous } : {})
+            });
+            previous = node;
+        }
+        for (const rev of chain.revisions) {
+            if (rev.intent !== "delete")
+                continue;
+            deletions.push({
+                key: chain.key,
+                typeName: chain.typeName,
+                fullName: chain.fullName,
+                extId: rev.entry.extId,
+                index: rev.entry.index,
+                ...(previous !== undefined ? { predecessorNode: previous } : {}),
+                dependsOn: [...rev.entry.dependsOn],
+                chainRoot: chain.root
+            });
+        }
+        const root = states[0];
+        if (chain.root === "create" && chain.existence === "present" && root) {
+            createOnExisting.push({ key: chain.key, extId: root.entry.extId, index: root.entry.index, intentSource: root.intentSource });
+        }
+    }
+    // A key whose intent could not be VERIFIED still orders exactly as it does today, as long as it
+    // has one state. What `INTENT_UNVERIFIABLE` leaves open is create-vs-update, and with a single
+    // entry that question changes nothing about the graph — there is no second state to sequence it
+    // against. Withholding it instead would make an unprojected session plan zero waves, which is
+    // every session before its first project_org (R12: existing plans work on day one).
+    const chained = new Set(derived.chains.map((c) => c.key));
+    const refused = new Set(refusals.map((r) => r.key));
+    const byKey = new Map();
+    for (const e of chainable) {
+        // A delete is excluded from the fallback for the same reason it is excluded from the chains'
+        // wave rows: there is no file to deploy. A key whose ONLY entry is a delete therefore lands in
+        // neither `owned` nor here, which is correct — it is a deletion, not an unordered component.
+        if (!e.deployable || e.intent === "delete")
+            continue;
+        byKey.set(e.key, [...(byKey.get(e.key) ?? []), e]);
+    }
+    for (const [key, group] of byKey) {
+        if (chained.has(key) || refused.has(key))
+            continue;
+        const only = group.length === 1 ? group[0] : undefined;
+        if (!only)
+            continue;
+        owned.push({ key, typeName: only.typeName, fullName: only.fullName, extId: only.extId, dependsOn: [...only.dependsOn] });
+    }
+    const placed = new Set([...owned.map((o) => o.key), ...deletions.map((d) => d.key)]);
+    // A deletion is PLACED even though it is not in a wave — `placeDeletions` gives it a position.
+    // Counting it as unplaced would report the batch as failing to order a component whose whole
+    // point is that it stops existing, and send the supervisor to fix a plan that is correct.
+    const unplaced = [...new Set(entries.filter((e) => e.deployable && e.intent !== "delete" && !placed.has(e.key)).map((e) => e.key))].sort();
+    return { owned, inferences: derived.inferences, hazards: derived.hazards, refusals, createOnExisting, routes: derived.routes, deletions, unplaced };
+}
+const indent = (text, prefix = "  ") => text.split("\n").map((line) => `${prefix}${line}`);
+/**
+ * Plan entries plus the XML they were authored as — the input the planned COUNT is taken over.
+ *
+ * The XML is read for one reason: container expansion. A Workflow file is zero Workflow
+ * configurations and N WorkflowAlert ones, and the delivered count expands it that way from the
+ * evidence bundle. Counting the container here and its children there is precisely the unit drift
+ * QA round 1 item 24 was (205 components reported as 94 configurations), so the denominator reads
+ * the same bytes the numerator will.
+ *
+ * BEST-EFFORT PER FILE, never per batch: an entry whose file is missing or unreadable counts once
+ * at its own grain. That is the honest floor — an unread container may hide children, so the count
+ * can be low, and a low denominator makes the rate CONSERVATIVE rather than flattering. Refusing
+ * the whole scope over one unreadable file would throw away a good denominator to protect against
+ * a slightly small one.
+ */
+async function plannedInputs(sessionRoot, entries) {
+    return Promise.all(entries.map(async (entry) => {
+        const base = { typeName: entry.typeName, fullName: entry.fullName, extId: entry.extId };
+        if (!entry.authoredFile)
+            return base;
+        const file = resolveAuthored(path.join(sessionRoot, "requirements", entry.extId), entry.authoredFile);
+        if (!file)
+            return base;
+        try {
+            return { ...base, xml: await fs.readFile(file, "utf8") };
+        }
+        catch {
+            return base;
+        }
+    }));
+}
+/**
+ * The report. Extracted from the handler so its REMEDIATIONS are testable — they are the part of
+ * this tool a supervisor acts on, and the two that used to end "build the late wave by hand" are
+ * exactly the prose the revision model retires.
+ */
+export function renderWavePlan(input) {
+    const { plan, planning } = input;
+    const { waves, cycles, lateFacets, duplicates, unowned } = plan;
+    const placedCounts = new Map();
+    for (const c of waves.flat()) {
+        const at = `${c.typeName}:${c.fullName}`;
+        placedCounts.set(at, (placedCounts.get(at) ?? 0) + 1);
+    }
+    const multiState = [...placedCounts.values()].filter((n) => n > 1).length;
+    const lines = [
+        `${placedCounts.size} of ${input.distinct} component(s) ordered into ${waves.length} wave(s).`,
+        ...(multiState > 0
+            ? [`${multiState} of them deploy MORE THAN ONCE — each later state is an entry of its own in the plan, so no wave is built by hand.`]
+            : []),
+        ...waves.flatMap((w, i) => [
+            `  w${i + 1}  (${w.length})`,
+            ...w.map((c) => `      ${c.typeName}:${c.fullName}${c.path ? `   <- ${c.path}` : ""}`)
+        ]),
+        ...(planning.inferences.length > 0
+            ? [
+                "",
+                `${planning.inferences.length} entr(y/ies) declared no intent; inferred from this session's projection (${input.grounding}):`,
+                ...planning.inferences.map((i) => `  ${i.key} (${i.extId} entry ${i.index}) -> ${i.intent}, because the projection found it ${i.from}`)
+            ]
+            : []),
+        ...(input.deletions.length > 0
+            ? [
+                "",
+                `${input.deletions.length} DELETION(S) declared. These are NOT waves and this tool has not deleted anything —`,
+                "a deletion has no authored file, so it deploys as a destructive package rather than a source wave.",
+                "Where each one sits, derived from what this batch does to the same component:",
+                ...input.deletions.map((d) => {
+                    const where = d.unplaceable
+                        ? "position UNRESOLVED — the work it must follow is stuck in a cycle above; fix the cycle first"
+                        : d.afterWave === null
+                            ? "no ordering constraint from this batch — it may run at any point"
+                            : `run AFTER wave ${d.afterWave}${d.because.length > 0 ? ` (${d.because.join("; ")})` : ""}`;
+                    return `  ${d.key}   ${where}   [${d.extId}]`;
+                }),
+                ...(input.deletions.some((d) => d.createdInBatch)
+                    ? [
+                        "",
+                        "One or more of these deletes a component THIS BATCH CREATES. That is legal and ordered, but say it",
+                        "out loud on the approval card — two requirements building something a third removes is a plan the",
+                        "operator should get to reconsider, not a sequencing detail."
+                    ]
+                    : []),
+                "",
+                "To execute, pass them to direct_apply's `deletes` yourself, in the shape below. Deliberately NOT automatic:",
+                "destruction is a decision, and a destructive package ROLLS BACK WHOLE — one member the org refuses takes",
+                "every other member down with it, so validate first (`dryRunOnly: true`, which gives each member its own",
+                "verdict) and split the call rather than shipping a refused member beside a clean one.",
+                ...input.deletions.map((d) => `  {"typeName": "${d.typeName}", "fullName": "${d.fullName}"}`)
+            ]
+            : []),
+        ...(planning.createOnExisting.length > 0
+            ? [
+                "",
+                `${planning.createOnExisting.length} CREATE ON AN EXISTING COMPONENT — both facts, because only you can say which is stale:`,
+                ...planning.createOnExisting.map((h) => `  ${h.key}: ${h.extId} entry ${h.index} says intent "create" (${h.intentSource}), and this session's projection observed it PRESENT in the target org.`),
+                "",
+                "A create against a component that already exists deploys a full-file replacement over it, so",
+                "every element the authored file omits is lost. If it is meant to CHANGE rather than be born,",
+                "declare that entry `intent: \"update\"` and author its complete desired state. Not refused: a",
+                "projection is a point-in-time read, and the component may have been deleted since."
+            ]
+            : []),
+        ...(planning.hazards.length > 0
+            ? [
+                "",
+                `${planning.hazards.length} INTENT NOT VERIFIABLE — this session has not observed these components, so nothing here guessed:`,
+                ...planning.hazards.flatMap((h) => indent(h.message))
+            ]
+            : []),
+        ...(planning.refusals.length > 0
+            ? [
+                "",
+                `${planning.refusals.length} REFUSAL(S) in the plans themselves — these components are NOT in the waves above:`,
+                ...planning.refusals.flatMap((r) => [`  [${r.code}]`, ...indent(r.message, "    ")])
+            ]
+            : []),
+        ...(planning.unplaced.length > 0
+            ? ["", `${planning.unplaced.length} component(s) left unordered by the above — fix the plan, do not deploy around them:`, ...planning.unplaced.map((k) => `  ${k}`)]
+            : []),
+        ...(duplicates.length > 0
+            ? [
+                "",
+                `${duplicates.length} component(s) listed more than once with nothing to tell the listings apart:`,
+                ...duplicates.map((d) => `  ${d}`),
+                "",
+                "If these are one component in one state, delete the duplicate entry. If they are two STATES of",
+                "it, declare them as two revisions — `intent` and its own `authoredFile` on each — and they",
+                "order into two waves instead of colliding in one."
+            ]
+            : []),
+        ...(lateFacets.length > 0
+            ? [
+                "",
+                `${lateFacets.length} LATE FACET(S) — each parent is ordered as if independent, then needs a`,
+                "SECOND deploy once its child exists, carrying the element that references it:",
+                ...lateFacets.map((f) => `  ${f.component}  re-deploy after  ${f.waitsFor}`),
+                "",
+                "Declare that second deploy as a SECOND REVISION of the parent: a second `components[]` entry",
+                "for the same component with `intent: \"update\"`, its own `authoredFile` carrying the complete",
+                "desired state, and `dependsOn` naming the child ON THAT SECOND ENTRY. Re-run this and the",
+                "later revision orders AFTER the child — no wave is built by hand, and both files lint.",
+                "A late facet that PERSISTS after the split means the child edge still sits on the FIRST",
+                "state's entry, where it must be dropped (honouring it there is a cycle) — move the",
+                "`dependsOn` to the later revision's entry."
+            ]
+            : []),
+        ...(cycles.length > 0
+            ? [
+                "",
+                `${cycles.length} CYCLE(S) — these cannot be ordered as they stand, and are NOT in the waves above:`,
+                ...cycles.map((c) => `  ${c.join("  ->  ")}  ->  ${c[0]}`),
+                "",
+                "A cycle is usually one component that must be deployed twice: an early form without the facet",
+                "that creates the loop, then a re-deploy carrying it once the other side exists. CustomObject +",
+                "compactLayoutAssignment is the common one. Declare it as TWO REVISIONS — two `components[]`",
+                "entries for that component, `intent: \"create\"` then `intent: \"update\"`, each bound to its own",
+                "`authoredFile` — and re-run this. The split is yours to author; this tool names it and orders",
+                "it, and never writes it for you: what the second state must CONTAIN is the part it cannot know."
+            ]
+            : []),
+        ...(input.unorderable.length > 0
+            ? ["", `${input.unorderable.length} component(s) CANNOT be ordered and are excluded — fix the plan, do not deploy around them:`, ...input.unorderable.map((u) => `  ${u}`)]
+            : []),
+        ...(planning.routes.length > 0
+            ? [
+                "",
+                `${planning.routes.length} entr(y/ies) marked deployable:false — read as ROUTES, not owned components:`,
+                ...planning.routes.map((r) => `  ${r.key} (${r.extId}, deployable:false — treated as a route, not an owner)`)
+            ]
+            : []),
+        ...(input.skippedEntries.length > 0
+            ? ["", `${input.skippedEntries.length} plan entr(y/ies) could not be identified and were skipped:`, ...input.skippedEntries.map((s) => `  ${s}`)]
+            : []),
+        ...(input.unreadablePlans.length > 0
+            ? ["", `${input.unreadablePlans.length} plan.json could not be READ — that is not the same as a requirement owning nothing:`, ...input.unreadablePlans.map((u) => `  ${u}`)]
+            : []),
+        ...(input.requirementsWithoutPlan.length > 0 ? ["", `no plan.json yet: ${input.requirementsWithoutPlan.join(", ")}`] : []),
+        ...(unowned.length > 0
+            ? ["", `depends on ${unowned.length} component(s) nothing here owns — assumed already in the org:`, ...unowned.slice(0, 8).map((u) => `  ${u}`)]
+            : []),
+        "",
+        "Fewer waves is fewer checkOnly round-trips, but a deploy is all-or-nothing: one bad element",
+        "rolls back its whole wave. Split further if you have a reason this cannot see; never merge",
+        "across a dependency edge."
+    ];
+    return lines.join("\n");
+}
+/** The session's target org alias, for scoping the projection. Local read; never contacts the org. */
+async function sessionTargetOrg(sessionId) {
+    try {
+        return (await resolveSessionOrg(await loadSession(sessionId), "target", { verify: false })).alias;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function registerWaveTools(server) {
+    server.registerTool("plan_waves", {
+        title: "Derive the deploy order from plan.json dependencies",
+        description: "Topologically order every owned component into the FEWEST waves the batch allows, from the dependsOn each analyzer already recorded — every wave costs a ~45s checkOnly, so wave count is the biggest lever on run time. " +
+            "Feed each returned wave's components straight to direct_lint/direct_apply as `waveComponents`; an entry carrying a `path` names WHICH of that component's authored files this wave deploys. A component with two states in the batch orders as an ordinary two-wave edge, never a cycle. " +
+            "Cross-checks each declared intent against this session's projection before anything touches the org, and names each case: a create on a component already there, an update on one the projection found absent, a component this session never projected. " +
+            "A component whose last declared state is `intent: \"delete\"` is NOT a wave — it comes back as an ordering constraint plus the member list in direct_apply's `deletes` shape. Nothing is deleted by calling this; pass those members to direct_apply yourself after a `dryRunOnly` pass, because a destructive package rolls back whole. " +
+            "Reports cycles and late facets with the two-revision split they need rather than refusing, and lists dependencies nothing in the batch owns. " +
+            "REPORT-ONLY: it never edits plan.json and never mutates an org. Advisory: split a wave further if you have a reason this cannot see, but do not merge across a dependency edge.",
+        inputSchema: {
+            sessionId: z.string().describe("The session whose analyzer plans to order.")
+        }
+    }, async ({ sessionId }) => {
+        try {
+            const root = sessionDir(sessionId);
+            const index = await loadRequirementsIndex(sessionId);
+            if (index.length === 0)
+                return fail("NO_REQUIREMENTS", `Session ${sessionId} has no imported requirements.`);
+            // An unmerged fragment set must NOT fall through to the "no plan.json yet" advisory below:
+            // that line means "the analyzer has not run", which the supervisor knowingly waits out —
+            // whereas fragments without a canonical plan mean the merge was SKIPPED, and ordering the
+            // rest of the batch around it silently shrinks the batch by a whole requirement. Same
+            // gate verifies a completed merge (dropped or doubly-owned fragment components), which the
+            // contract has promised since the split shipped ("refuses a malformed or missing merge").
+            const fragmentAudit = await auditPlanFragments(root, index.map((entry) => entry.extId));
+            if (!fragmentAudit.clean)
+                return fail("PLAN_FRAGMENTS_UNRESOLVED", renderFragmentAudit(fragmentAudit));
+            const entries = [];
+            const parseRefusals = [];
+            const noPlan = [];
+            const unreadablePlans = [];
+            const unorderable = [];
+            const skippedEntries = [];
+            for (const entry of index) {
+                const result = await readPlanFile(path.join(root, "requirements", entry.extId, "plan.json"), entry.extId);
+                if (!result.ok) {
+                    // A plan that could not be READ is not a requirement that owns nothing. Reading the two
+                    // as one is how a malformed plan.json silently shrinks a batch — the previous
+                    // `.catch(() => null)` did exactly that.
+                    if (result.error.code === "PLAN_NOT_FOUND")
+                        noPlan.push(entry.extId);
+                    else
+                        unreadablePlans.push(`${entry.extId}: ${result.error.code} — ${result.error.message}`);
+                    continue;
+                }
+                parseRefusals.push(...result.plan.refusals);
+                for (const s of result.plan.skipped)
+                    skippedEntries.push(`${entry.extId} entry ${s.index}: ${s.reason}`);
+                for (const c of result.plan.entries) {
+                    // A placeholder an analyzer left behind was once ordered into a wave as though it were
+                    // real, so the plan looked complete and failed at assembly. Refuse to order it and say
+                    // which plan to fix — but see isPlaceholderFullName for why this must be type-aware.
+                    // Deployable entries only: a route's fullName is prose about work leaving by another
+                    // path, and it is reported as a route below rather than as a broken name. A DELETE is
+                    // checked whatever its `deployable` says: its fullName becomes a destructive package
+                    // member, where an unresolved placeholder is worse than it would be in a wave.
+                    if ((c.deployable || c.intent === "delete") && isPlaceholderFullName(c.typeName, c.fullName)) {
+                        unorderable.push(`${entry.extId}: ${c.key} — looks like an unresolved placeholder, not a real fullName; resolve it in that plan.json${c.typeName === "Layout" ? "" : " (note: Layout fullNames legitimately contain spaces and are ordered normally)"}`);
+                        continue;
+                    }
+                    entries.push(c);
+                }
+            }
+            if (!entries.some((e) => e.deployable)) {
+                return fail("NO_COMPONENTS", [
+                    `No plan.json in this session owns any components${noPlan.length ? ` (${noPlan.length} requirement(s) have no plan yet)` : ""}. Run the analyzers first.`,
+                    // Said separately, because "the analyzer has not run" and "the analyzer wrote
+                    // something this cannot read" need opposite responses from the reader.
+                    ...(unreadablePlans.length > 0 ? [`${unreadablePlans.length} plan.json could not be READ:`, ...unreadablePlans.map((u) => `  ${u}`)] : [])
+                ].join("\n"));
+            }
+            // LOCAL DISK ONLY — the session's own project_org runs plus every completed wave's
+            // post-image. No org round-trip: this step runs before the operator has approved anything,
+            // and a planner that reads the org is a planner that can fail on an expired session.
+            const view = await collectSessionProjection(root, await sessionTargetOrg(sessionId));
+            const grounding = view.sources.length === 0 ? "no projection yet — run project_org" : describeSources(view);
+            const planning = planRevisions(entries, projectionExistence(view), parseRefusals);
+            const plan = planWaves(planning.owned);
+            const deletions = placeDeletions(plan, planning.deletions);
+            // PERSIST THE DERIVATION. This tool is advisory and stays advisory — but until now nothing
+            // downstream could tell a deliberate hand-order from an accidental one, because the derived
+            // answer existed only in the conversation. Written to the session so `direct_apply` can WARN
+            // (never refuse) when the wave it is handed corresponds to no wave derived here. Fail-open:
+            // a derivation that cannot be written costs one later warning and never this plan.
+            await writeWaveDerivation(sessionId, plan.waves, grounding);
+            // PERSIST THE DENOMINATOR, at Configuration Item grain.
+            //
+            // This tool already KNEW what the batch was asked for — `distinct` below is printed to the
+            // operator mid-run as "N of M component(s) ordered" — and until now that was the only place
+            // it existed. QA round 2: a 2h45m run delivered 19/20 requirements and ~140 components, and
+            // the close report could state neither number, because nothing carried the planned count to
+            // the end. See `direct/plannedScope.ts` for why this is a separate artifact from the wave
+            // derivation written above: different grain, and a count cannot inherit a warning's
+            // fail-open posture. Fail-open on the WRITE only — a run never fails over bookkeeping.
+            await writePlannedScope(sessionId, {
+                components: plannedConfigurationItems(await plannedInputs(root, entries.filter((e) => e.deployable))),
+                // Routes a deploy COULD have satisfied belong in the denominator (the operator approved
+                // them) and never in the numerator. Routes NO deploy could ever satisfy — sObject rows
+                // (membership, assignment, custom setting values) and the no-API cases — are recorded
+                // apart and land in NEITHER half of the rate: counting them against automation makes
+                // the metric measure the requirement mix, not the tool (QA2-008 Class A).
+                manual: plannedConfigurationItems(planning.routes.filter((r) => r.routeCause === null).map((r) => ({ typeName: r.typeName, fullName: r.fullName, extId: r.extId }))),
+                unautomatable: plannedConfigurationItems(planning.routes.filter((r) => r.routeCause !== null).map((r) => ({ typeName: r.typeName, fullName: r.fullName, extId: r.extId }))),
+                groundedAgainst: grounding
+            });
+            const distinct = new Set([...planning.owned.map((o) => o.key), ...planning.unplaced]).size;
+            const text = renderWavePlan({
+                plan,
+                planning,
+                deletions,
+                distinct,
+                grounding,
+                requirementsWithoutPlan: noPlan,
+                unreadablePlans,
+                unorderable,
+                skippedEntries
+            });
+            const placedKeys = new Set(plan.waves.flat().map((c) => `${c.typeName}:${c.fullName}`));
+            return ok(text, {
+                // Structured data ONLY. This object previously spread the same PROSE ARRAYS used for the
+                // text rendering into an object literal, so every advisory line arrived as a numerically
+                // keyed field ("0", "1", "2"…) mixed in with waveCount and waves — unreadable as data and
+                // duplicating the text half for no gain.
+                waveCount: plan.waves.length,
+                ordered: placedKeys.size,
+                total: distinct,
+                waves: plan.waves,
+                groundedAgainst: grounding,
+                ...(planning.inferences.length > 0 ? { inferredIntents: planning.inferences.map((i) => ({ key: i.key, extId: i.extId, index: i.index, intent: i.intent, from: i.from })) } : {}),
+                // The `deletes` half is EXACTLY direct_apply's argument shape, so the supervisor lifts it
+                // rather than retyping it; `deletions` carries the ordering beside it. Neither is a
+                // trigger — this tool never deletes, and nothing downstream reads these as approval.
+                ...(deletions.length > 0
+                    ? {
+                        deletions: deletions.map((d) => ({
+                            typeName: d.typeName,
+                            fullName: d.fullName,
+                            requirement: d.extId,
+                            afterWave: d.afterWave,
+                            createdInBatch: d.createdInBatch,
+                            ...(d.unplaceable ? { unplaceable: true } : {})
+                        })),
+                        deletes: deletions.map((d) => ({ typeName: d.typeName, fullName: d.fullName }))
+                    }
+                    : {}),
+                ...(planning.createOnExisting.length > 0 ? { createOnExisting: planning.createOnExisting } : {}),
+                ...(planning.hazards.length > 0 ? { unverifiableIntents: planning.hazards.map((h) => ({ key: h.key, reason: h.reason, message: h.message })) } : {}),
+                ...(planning.refusals.length > 0 ? { revisionRefusals: planning.refusals } : {}),
+                ...(planning.unplaced.length > 0 ? { unplaced: planning.unplaced } : {}),
+                ...(plan.duplicates.length > 0 ? { duplicates: plan.duplicates } : {}),
+                ...(plan.lateFacets.length > 0 ? { lateFacets: plan.lateFacets } : {}),
+                ...(plan.cycles.length > 0 ? { cycles: plan.cycles } : {}),
+                ...(noPlan.length > 0 ? { requirementsWithoutPlan: noPlan } : {}),
+                ...(unreadablePlans.length > 0 ? { unreadablePlans } : {}),
+                ...(plan.unowned.length > 0 ? { externalDependencies: plan.unowned } : {}),
+                ...(unorderable.length > 0 ? { unorderable } : {})
+            });
+        }
+        catch (error) {
+            if (error instanceof WorkspaceError)
+                return fail(error.code, error.message);
+            return internalError(error);
+        }
+    });
+}