in2-agent-server 0.20260821.185429

package/dist/direct/waveAssembly.js

@@ -0,0 +1,556 @@
+// Wave assembly — gather the files analyzers authored into the one tree a wave deploys.
+//
+// This is `assemble_wave`'s machinery (tools/assemble.ts) as a module, so that direct_lint and
+// direct_apply can each run it as an internal step instead of the supervisor calling a separate
+// tool and hoping the tree it assembled is still the tree that gets deployed. Everything that made
+// the tool safe moves with identical codes and identical detection — COMPONENT_NOT_OWNED,
+// COMPONENT_STILL_PROVISIONAL, NOTHING_TO_ASSEMBLE, the two `missing` reasons, recovery-from-disk,
+// path safety, the content-file sibling copy, prune-on-rebuild.
+//
+// TWO THINGS ARE DELIBERATELY DIFFERENT, and both come from the component revision model:
+//
+//   1. A component may have MORE THAN ONE state in a batch. `OWNERSHIP_CONFLICT` and
+//      `COMPONENT_AUTHORED_TWICE` used to read every second file for a key as an error, because
+//      nothing could say which file belonged in which wave. The wave request now carries that
+//      knowledge as a `path` discriminator, so the refusals narrow to what is still genuinely
+//      wrong: two requirements CREATING one component, and one wave that would take two files.
+//
+//   2. The wave tree is a BUILD ARTIFACT. Every call rebuilds `<session>/authored/<wave>` from the
+//      authored files, so `WAVE_EXISTS` is gone: there is no edit in there worth protecting,
+//      because a wave-specific fix belongs in the revision's own authored file — which is the
+//      thing that lints, the thing plan.json binds, and the thing the next call would copy over
+//      anyway. Rebuilding is also what closes the lint-to-apply window: apply lints exactly what
+//      it just assembled, in the same call.
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import { fileExists, readJson, sessionDir } from "../core/workspace.js";
+import { parsePlanFile } from "../core/planFile.js";
+import { resolveSourcePath } from "./applyLoop.js";
+import { resolveComponentFromRelPath } from "./sourceTree.js";
+const WAVE_RE = /^[A-Za-z0-9_-]{1,40}$/;
+export const componentKey = (typeName, fullName) => `${typeName}:${fullName}`;
+/**
+ * Resolve an analyzer-declared relative path inside its own requirement directory.
+ *
+ * `authoredFile` is written by a subagent into a JSON file, so it is untrusted input reaching a
+ * filesystem API. Without this, `"../../../../.ssh/authorized_keys"` would resolve happily and then
+ * be COPIED somewhere by the assembler. Absolute paths are rejected for the same reason. This is the
+ * one place the value crosses into a path, so it is the one place that has to check.
+ */
+export function resolveAuthored(requirementDir, authoredFile) {
+    if (!authoredFile || path.isAbsolute(authoredFile))
+        return null;
+    const root = path.resolve(requirementDir, "authored");
+    const resolved = path.resolve(root, authoredFile);
+    return resolved === root || resolved.startsWith(`${root}${path.sep}`) ? resolved : null;
+}
+const normRel = (value) => value.split(/[\\/]/).filter(Boolean).join("/");
+// `direct/` holds no `tools/` imports, so this is the same two-line read as tools/session.ts's
+// `loadRequirementsIndex`, narrowed to the one field assembly uses.
+async function requirementExtIds(sessionId) {
+    const file = path.join(sessionDir(sessionId), "requirements", "index.json");
+    if (!fileExists(file))
+        return [];
+    const index = await readJson(file);
+    return index.map((entry) => entry.extId).filter((extId) => typeof extId === "string");
+}
+// Reads through U1's canonical parser — the one reader of this schema (`core/planFile.ts`).
+// `null` — no readable plan.json, an unparseable one, or one with no components[] key — is
+// distinct from an EMPTY components[]: an empty list still means a requirement was analyzed and
+// claims nothing, which is exactly the state the orphan-file refusal exists to catch. parsePlanFile
+// treats a missing components key as a legal empty plan, so the key's absence is checked on the
+// parsed document to keep that distinction. A malformed plan maps to null exactly as the old
+// direct JSON.parse did — assembly cannot fix a broken plan, only decline to read ownership from
+// it (resolve_blocker is where a broken plan gets repaired).
+async function readPlanEntries(requirementDir) {
+    const text = await fs.readFile(path.join(requirementDir, "plan.json"), "utf8").catch(() => null);
+    if (text === null)
+        return null;
+    const parsed = parsePlanFile(text, path.basename(requirementDir));
+    if (!parsed.ok || parsed.plan.document.components === undefined)
+        return null;
+    return parsed.plan.entries.map((e) => ({
+        typeName: e.typeName,
+        fullName: e.fullName,
+        ...(e.authoredFile !== null ? { authoredFile: e.authoredFile } : {}),
+        ...(e.intent !== null ? { intent: e.intent } : {}),
+        deployable: e.deployable,
+        provisional: e.provisional,
+        ...(e.blockedBy !== null ? { blockedBy: e.blockedBy } : {})
+    }));
+}
+/**
+ * Where a bound file lands in the wave tree.
+ *
+ * Derived from the RESOLVED COMPONENT — the registry's type directory plus the conventional
+ * filename — never copied from the source path. Two shapes make that load-bearing:
+ *
+ *   - A second revision's authored file has to sit somewhere its sibling revision does not, and the
+ *     natural move is a subdirectory (the EV run's `ci05-update/objects/…`). Copied verbatim that
+ *     prefix survives into the wave tree, where the walker does not recognise it — `sourceTree.ts`
+ *     reads the FIRST segment as a type directory (sourceTree.ts:25-31) — so the revision assembles,
+ *     lints as nothing, and deploys nothing, reporting success the whole way.
+ *   - An `authoredFile` whose basename disagrees with `fullName` makes the wave tree name a
+ *     DIFFERENT component than the plan owns, because identity in that tree comes from the path.
+ *
+ * Deriving forward makes the destination a function of identity, so both shapes land where the
+ * walker will find them, under the name plan.json claims. A type the forward resolver cannot place
+ * (bundles, unknown types) keeps its source-relative path — today's behaviour, unchanged.
+ */
+function destinationFor(typeName, fullName, srcRel) {
+    const resolved = resolveSourcePath({ typeName, fullName, xml: "", content: "" });
+    if ("files" in resolved) {
+        const meta = resolved.files.find((f) => f.from === "xml");
+        if (meta)
+            return meta.relPath;
+    }
+    // A decomposed child that deploys inside its parent's container file (Workflow's WorkflowAlert,
+    // SharingRules' rules): the authored file IS the container, and that is where it belongs.
+    if ("container" in resolved)
+        return resolved.container.containerPath;
+    return normRel(srcRel);
+}
+// Index every authored component across all plans. Built from plan.json rather than by walking the
+// authored directories, because ownership is what plan.json exists to state — a stray file nobody
+// claims must not silently make it into a deploy.
+async function indexOwnership(sessionId, extIds) {
+    const root = sessionDir(sessionId);
+    const out = {
+        bound: new Map(),
+        notAuthored: new Map(),
+        diskAll: new Map(),
+        provisional: new Map(),
+        recovered: [],
+        badPaths: []
+    };
+    for (const extId of extIds) {
+        const reqDir = path.join(root, "requirements", extId);
+        const entries = await readPlanEntries(reqDir);
+        if (!entries)
+            continue;
+        // Everything on disk under this requirement's authored/ tree, indexed by the component it
+        // resolves to. This is the recovery path for a plan.json that names a component but never
+        // recorded its `authoredFile` — which is what the SUPERVISOR produces when it authors the
+        // components analyzers withheld, and it made assembly report "no analyzer authored it" about
+        // files sitting at the exact expected path (CF77). Built from the same reverse mapping
+        // direct_lint uses, so it needs no per-type forward path table to drift out of date.
+        const authoredRoot = path.join(reqDir, "authored");
+        const onDisk = new Map();
+        const indexDisk = async (dir) => {
+            for (const e of await fs.readdir(dir, { withFileTypes: true }).catch(() => [])) {
+                const full = path.join(dir, e.name);
+                if (e.isDirectory()) {
+                    await indexDisk(full);
+                    continue;
+                }
+                const rel = path.relative(authoredRoot, full);
+                const resolved = resolveComponentFromRelPath(rel);
+                if (!resolved)
+                    continue;
+                const key = componentKey(resolved.typeName, resolved.fullName);
+                onDisk.set(key, rel);
+                out.diskAll.set(key, { extId, rel });
+            }
+        };
+        await indexDisk(authoredRoot);
+        for (const entry of entries) {
+            if (!entry.typeName || !entry.fullName)
+                continue;
+            // A DELETION OWNS NO FILE, so it takes no part in assembly. `core/planFile.ts` already refuses
+            // an `intent: "delete"` entry that BINDS a file, but the recovery path below would otherwise
+            // find one anyway: a delete entry has no `authoredFile`, which sends it to the on-disk lookup,
+            // and a stray file for that key under the same requirement would be adopted as its state and
+            // COPIED INTO THE WAVE — deploying the component the entry exists to remove. The deletion is
+            // ordered by plan_waves and executed through direct_apply's `deletes`; it never has a wave slot.
+            if (entry.intent === "delete")
+                continue;
+            const key = componentKey(entry.typeName, entry.fullName);
+            let rel = entry.authoredFile;
+            if (!rel) {
+                const found = onDisk.get(key);
+                if (!found) {
+                    out.notAuthored.set(key, extId);
+                    continue;
+                }
+                // Recovered. Say so — plan.json is what Configuration Item ownership is derived from, so a
+                // silent recovery would leave the writeback attributing it to nobody.
+                out.recovered.push(`${key} (${extId}) found at authored/${found} — record it as authoredFile in plan.json`);
+                rel = found;
+            }
+            const src = resolveAuthored(reqDir, rel);
+            if (!src) {
+                out.badPaths.push(`${extId} -> ${rel}`);
+                continue;
+            }
+            // PROVISIONAL: authored against a blocker the operator has not answered yet.
+            //
+            // This gate is what makes authoring-while-blocked safe, and it replaces the old rule that
+            // forbade authoring at all. That rule pushed a component's whole design into draftNotes PROSE,
+            // which the lint ladder cannot reach — live near-miss: a flow formula written as
+            // `{!$Record.CF78_Category__c}='Process'` with no TEXT() wrapper would have failed at deploy,
+            // and was caught only because the supervisor happened to know the rule. A provisional FILE is
+            // linted like any other; it just cannot be deployed until resolve_blocker promotes it.
+            if (entry.provisional) {
+                const held = out.provisional.get(key) ?? [];
+                held.push({ rel, note: `${extId} (blocker ${String(entry.blockedBy ?? "?")})` });
+                out.provisional.set(key, held);
+                continue;
+            }
+            const files = out.bound.get(key) ?? [];
+            // The same file listed twice is an idempotent restatement, not a second revision.
+            if (files.some((f) => f.extId === extId && normRel(f.rel) === normRel(rel)))
+                continue;
+            files.push({ key, typeName: entry.typeName, fullName: entry.fullName, extId, intent: entry.intent, rel, src });
+            out.bound.set(key, files);
+        }
+    }
+    return out;
+}
+const describeFile = (f) => `${f.extId}: ${f.rel}${f.intent ? ` (intent: ${f.intent})` : ""}`;
+/**
+ * Two requirements claiming one key.
+ *
+ * Under the revision model this is only an ownership ERROR when they both CREATE the component —
+ * a create in one requirement and an update in another is the shape the model exists to express,
+ * and refusing it is what forced the EV run to hand-copy files past every guard. Intent has to be
+ * DECLARED for that: an undeclared pair is indistinguishable from a double create, and resolving it
+ * silently is how a duplicated Configuration Item reaches the writeback. So unknown intent still
+ * contests, exactly as today, and the refusal says which case it is.
+ */
+function ownershipConflicts(keys, bound) {
+    const out = [];
+    for (const key of keys) {
+        const files = bound.get(key) ?? [];
+        const claimants = [...new Set(files.map((f) => f.extId))];
+        if (claimants.length < 2)
+            continue;
+        const creates = files.filter((f) => f.intent === "create");
+        if (creates.length > 1) {
+            out.push(`${key} — CREATED by ${[...new Set(creates.map((c) => c.extId))].join(" and ")}; a component is created once`);
+            continue;
+        }
+        if (files.some((f) => !f.intent)) {
+            out.push(`${key} — claimed by ${claimants.join(" and ")}, and no entry declares an intent, so this cannot be told apart from two creates`);
+        }
+    }
+    return out;
+}
+/**
+ * Rebuild `<session>/authored/<wave>` from the files the requirements authored, and report what
+ * landed there.
+ *
+ * Refusals come back as data — `{ok: false, code, message}` with the codes the tool used — so the
+ * calling tool renders them through its own `fail()`. A malformed sessionId still throws
+ * `WorkspaceError`, exactly as every other workspace read does.
+ *
+ * Partial success is deliberate: a wave whose components are only partly authored assembles what it
+ * has and NAMES the rest in `missing`. The refusals are reserved for the states where continuing
+ * would deploy something nobody chose.
+ */
+export async function assembleWave(input) {
+    const { sessionId, wave, components } = input;
+    if (!WAVE_RE.test(wave)) {
+        return { ok: false, code: "INVALID_WAVE", message: `wave must match ${WAVE_RE} (it becomes a directory name).` };
+    }
+    const root = sessionDir(sessionId);
+    const extIds = await requirementExtIds(sessionId);
+    if (extIds.length === 0) {
+        return { ok: false, code: "NO_REQUIREMENTS", message: `Session ${sessionId} has no imported requirements.` };
+    }
+    const index = await indexOwnership(sessionId, extIds);
+    const wanted = components.map((c) => ({ ...c, key: componentKey(c.typeName, c.fullName) }));
+    const wantedKeys = [...new Set(wanted.map((w) => w.key))];
+    // Ownership first: a cross-requirement double claim is wrong regardless of which file this
+    // particular wave would have taken, and saying so beats reporting the ambiguity it causes.
+    const conflicting = ownershipConflicts(wantedKeys, index.bound);
+    if (conflicting.length > 0) {
+        return {
+            ok: false,
+            code: "OWNERSHIP_CONFLICT",
+            message: [
+                "Two requirements claim the same component, and this is not a create-then-update pair:",
+                ...conflicting.map((c) => `  ${c}`),
+                "",
+                "A component is CREATED once. If the second requirement CHANGES what the first creates, say so:",
+                'give that entry intent: "update" and its own authoredFile, and the two become ordered revisions',
+                "of one component. Otherwise fix the ownership in plan.json — one requirement owns it, the other",
+                "lists it under dependsOn."
+            ].join("\n")
+        };
+    }
+    // Then the per-wave binding. Each requested component must resolve to exactly ONE file: the wave
+    // tree is walked by component key and walkSourceTree merges two files for one key silently
+    // (sourceTree.ts:100-115), so a second file here does not become a second component — it becomes
+    // whichever half the walker happened to read last.
+    const planned = [];
+    const doubled = [];
+    const missing = [];
+    const blockedByAnswer = [];
+    const orphanFiles = [];
+    for (const w of wanted) {
+        const files = index.bound.get(w.key) ?? [];
+        const candidates = w.path ? files.filter((f) => normRel(f.rel) === normRel(w.path)) : files;
+        if (candidates.length > 1) {
+            doubled.push(`${w.key} — ${candidates.map(describeFile).join(", ")}`);
+            continue;
+        }
+        const hit = candidates[0];
+        if (!hit) {
+            // The blocker gate reads the same discriminator: a wave naming one revision is told about
+            // THAT revision's blocker, not about whichever entry for the key happened to be provisional.
+            const held = index.provisional.get(w.key) ?? [];
+            const heldHere = w.path ? held.filter((h) => normRel(h.rel) === normRel(w.path)) : held;
+            if (heldHere.length > 0) {
+                blockedByAnswer.push(`${w.key} — authored by ${heldHere.map((h) => h.note).join(", ")}, still awaiting the operator's answer`);
+                continue;
+            }
+            if (w.path) {
+                missing.push({
+                    key: w.key,
+                    reason: files.length > 0
+                        ? `no plan entry binds ${normRel(w.path)} — this key's authored files are ${files.map(describeFile).join(", ")}`
+                        : `this wave asks for the revision at ${normRel(w.path)}, but no plan.json entry for this component records an authoredFile`
+                });
+                continue;
+            }
+            const orphan = index.diskAll.get(w.key);
+            if (orphan) {
+                // A FILE EXISTS and no plan.json claims the component. Assembling it would deploy fine and
+                // then strand the writeback: Configuration Item ownership is derived from plan.json, and
+                // campfire_write_config_items refuses the WHOLE batch on an unmapped row — so the cost lands
+                // after every wave is live in the org, where the fix is archaeology. Refusing here costs one
+                // edit to a plan file.
+                orphanFiles.push(`${w.key} — file at requirements/${orphan.extId}/authored/${orphan.rel}, but ${orphan.extId}'s plan.json does not list it in components[]`);
+                continue;
+            }
+            const plannedBy = index.notAuthored.get(w.key);
+            missing.push({
+                key: w.key,
+                reason: plannedBy
+                    ? `${plannedBy}'s plan.json lists this component but no file for it exists under requirements/${plannedBy}/authored/ — the analyzer left it unauthored (blocked or not deployable), or it still has to be written`
+                    : "no plan.json in this session claims this component — check the typeName/fullName spelling, or that the analyzer for its requirement has run"
+            });
+            continue;
+        }
+        // CONTENT-FILE SIBLING: in source format a content-file type is a PAIR — Name.email-meta.xml
+        // beside Name.email (same for .resource, Document bodies). The plan records only the -meta.xml
+        // as authoredFile, and copying just that half made direct_apply refuse the wave with "provide a
+        // content value" while the analyzer's correctly-authored body sat one directory away
+        // (live-caught SM301 w2; the supervisor hand-copied the bodies, which the next re-assemble would
+        // then have dropped again).
+        const destRel = destinationFor(hit.typeName, hit.fullName, hit.rel);
+        const copy = { ...hit, destRel };
+        if (hit.src.endsWith("-meta.xml") && destRel.endsWith("-meta.xml")) {
+            const sibling = hit.src.slice(0, -"-meta.xml".length);
+            if (fileExists(sibling)) {
+                copy.contentSrc = sibling;
+                copy.destContentRel = destRel.slice(0, -"-meta.xml".length);
+            }
+        }
+        planned.push(copy);
+    }
+    if (doubled.length > 0) {
+        return {
+            ok: false,
+            code: "COMPONENT_AUTHORED_TWICE",
+            message: [
+                "More than one authored file is bound to the same component in ONE wave. A wave carries at most",
+                "one revision of a component — the wave tree is read back by component key, and two files for one",
+                "key merge silently rather than becoming two components.",
+                ...doubled.map((d) => `  ${d}`),
+                "",
+                "If these are two states of the component (an object re-emitted to carry a compactLayoutAssignment,",
+                'a field whose values a later requirement adjusts), declare them as two revisions: one entry per',
+                'file in plan.json, each with its own authoredFile and an intent of "create" then "update".',
+                "plan_waves then orders them into different waves and names the bound path on each wave entry.",
+                "If they are the same state, keep one entry."
+            ].join("\n")
+        };
+    }
+    const dest = path.join(root, "authored", wave);
+    // REFUSE BEFORE WRITING. These two refusals used to sit below the prune-and-copy, faithfully
+    // ported from the old assemble tool — where the tree was advisory. Under direct_apply the tree
+    // IS what a `{sessionId, wave}` call deploys, so a refusal that has already rebuilt the tree
+    // hands the next shortcut a wave minus its refused component. Everything below this line may
+    // mutate the tree; everything that can say no has already said it.
+    if (blockedByAnswer.length > 0) {
+        return {
+            ok: false,
+            code: "COMPONENT_STILL_PROVISIONAL",
+            message: [
+                `${blockedByAnswer.length} component(s) in this wave are authored but PROVISIONAL — the operator has not answered the blocker they depend on:`,
+                ...blockedByAnswer.map((b) => `  ${b}`),
+                "",
+                "Refusing to assemble. The file exists and has been linted, which is the point — but deploying",
+                "it would ship a design nobody approved.",
+                "",
+                "Once the operator answers: resolve_blocker {sessionId, extId, blockerId, answer, promote: [\"<key>\"]}",
+                "to confirm the authored variant, or edit the file first if they chose differently, or",
+                "drop: [\"<key>\"] if the answer eliminated the component."
+            ].join("\n")
+        };
+    }
+    if (orphanFiles.length > 0) {
+        return {
+            ok: false,
+            code: "COMPONENT_NOT_OWNED",
+            message: [
+                `${orphanFiles.length} component(s) in this wave have an authored file that NO requirement's plan.json claims:`,
+                ...orphanFiles.map((o) => `  ${o}`),
+                "",
+                "Refusing to assemble. These would deploy correctly and then fail the Campfire writeback,",
+                "which derives Configuration Item ownership from plan.json and rejects the whole batch on an",
+                "unmapped row — so the error would surface only after every wave is already live in the org.",
+                "",
+                "Add each component to the owning requirement's plan.json components[] (with its",
+                "authoredFile), then assemble again."
+            ].join("\n")
+        };
+    }
+    // RECONCILE, don't merely add. The wave directory is exactly what direct_apply deploys, so a file
+    // left behind from a previous assemble is a component nobody approved going to the org.
+    // Live-caught CF75: the operator dropped a FlexiPage, the wave was re-assembled, and the stale
+    // flexipages/ directory survived — direct_lint still linted 7 components and still flagged it. It
+    // was noticed only because a count looked wrong.
+    //
+    // The keep-set is keyed per BOUND FILE, not one path per key: with revisions, the same key can be
+    // assembled from a different file next call, and a keep-set that remembered only "this key's
+    // path" would happily delete the file the wave actually binds.
+    //
+    // This now runs on EVERY call, where it used to run only under `overwrite`. The tree is a build
+    // artifact — nothing in it is authored, so there is nothing in it to protect. A wave-specific fix
+    // belongs in the revision's own authored file, which is what lints and what plan.json binds.
+    const keep = new Set();
+    for (const p of planned) {
+        keep.add(p.destRel);
+        if (p.destContentRel)
+            keep.add(p.destContentRel);
+    }
+    const pruned = [];
+    const walk = async (dir) => {
+        const out = [];
+        for (const e of await fs.readdir(dir, { withFileTypes: true }).catch(() => [])) {
+            const full = path.join(dir, e.name);
+            if (e.isDirectory())
+                out.push(...(await walk(full)));
+            else
+                out.push(normRel(path.relative(dest, full)));
+        }
+        return out;
+    };
+    if (fileExists(dest)) {
+        for (const rel of await walk(dest)) {
+            if (keep.has(rel))
+                continue;
+            await fs.rm(path.join(dest, ...rel.split("/")), { force: true }).catch(() => { });
+            pruned.push(rel);
+        }
+    }
+    const copied = [];
+    const unreadable = [];
+    for (const p of planned) {
+        const target = path.join(dest, ...p.destRel.split("/"));
+        try {
+            await fs.mkdir(path.dirname(target), { recursive: true });
+            // Copy, not move: the analyzer's output stays intact, so a re-assemble after a botched edit is
+            // always possible.
+            await fs.copyFile(p.src, target);
+            copied.push(`${p.destRel}  (${p.extId})`);
+            if (p.contentSrc && p.destContentRel) {
+                await fs.copyFile(p.contentSrc, path.join(dest, ...p.destContentRel.split("/")));
+                copied.push(`${p.destContentRel}  (${p.extId}, content body)`);
+            }
+        }
+        catch (error) {
+            unreadable.push(`${p.key}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    if (copied.length === 0) {
+        return {
+            ok: false,
+            code: "NOTHING_TO_ASSEMBLE",
+            message: [
+                `None of the ${wanted.length} requested component(s) had authored files.`,
+                "Either the analyzers have not run, or every component in this wave is blocked and you",
+                "must author it yourself. Nothing was written.",
+                ...missing.slice(0, 10).map((m) => `  ${m.key} — ${m.reason}`)
+            ].join("\n")
+        };
+    }
+    // An approved wave is a SCOPE the operator consented to, and "assembled N of M" used to return
+    // as a success — direct_apply then linted, checked and DEPLOYED the subset in the same call, so
+    // the report's "author these yourself" advice arrived after the deploy it was advising about,
+    // and the org held part of a wave the operator approved whole. Partial delivery is a decision,
+    // not a default: it needs the caller to say so.
+    if ((missing.length > 0 || unreadable.length > 0) && !input.ackIncomplete) {
+        await fs.rm(dest, { recursive: true, force: true });
+        // Sliced the same way NOTHING_TO_ASSEMBLE's list above is, for the same reason: a wave missing
+        // hundreds of components should not paste hundreds of lines into a refusal. The headline already
+        // states both counts, so nothing is silently hidden — `(first 10 shown)` just says the list below
+        // is not the whole story when it isn't.
+        const sliced = missing.length > 10 || unreadable.length > 10;
+        return {
+            ok: false,
+            code: "WAVE_INCOMPLETE",
+            message: [
+                `${copied.length} of ${wanted.length} requested component(s) have authored files — the wave the operator approved is not all here${sliced ? " (first 10 shown)" : ""}:`,
+                ...missing.slice(0, 10).map((m) => `  MISSING ${m.key} — ${m.reason}`),
+                ...unreadable.slice(0, 10).map((u) => `  UNREADABLE ${u}`),
+                "",
+                "Nothing was written, linted or deployed. Author the missing components and call again — or,",
+                "if the operator has agreed to deliver this wave in parts, pass `ackIncompleteWave: true` to",
+                "deploy only the assembled subset."
+            ].join("\n")
+        };
+    }
+    // Scoped to THIS wave. The recovery scan walks every requirement in the session, so reporting all
+    // of it repeated the same nags on every call regardless of what each wave contained — noise that
+    // trains the reader to skip the block that matters.
+    const recoveredHere = index.recovered.filter((r) => wantedKeys.some((k) => r.startsWith(`${k} (`)));
+    // No trailing "now run direct_lint": assembly is a step INSIDE lint and apply, so the caller is
+    // already the next step. The caller frames this block in its own report.
+    const report = [
+        `assembled ${copied.length} file(s) into ${dest}`,
+        ...copied.map((c) => `  ${c}`),
+        ...(missing.length > 0
+            ? [
+                "",
+                `${missing.length} component(s) in this wave have NO authored file — author these yourself before linting:`,
+                ...missing.map((m) => `  ${m.key} — ${m.reason}`)
+            ]
+            : []),
+        ...(recoveredHere.length > 0
+            ? [
+                "",
+                `${recoveredHere.length} component(s) in THIS wave had a file on disk that plan.json did not record. Assembled`,
+                "from the file, but plan.json is what Configuration Item OWNERSHIP is derived from, so",
+                "record authoredFile on each or the writeback will attribute them to no requirement:",
+                ...recoveredHere.map((r) => `  ${r}`)
+            ]
+            : []),
+        ...(pruned.length > 0
+            ? [
+                "",
+                `REMOVED ${pruned.length} file(s) that are not in this wave's component list — a leftover`,
+                "here would have deployed a component you did not approve:",
+                ...pruned.map((p) => `  ${p}`)
+            ]
+            : []),
+        ...(unreadable.length > 0 ? ["", "COULD NOT COPY:", ...unreadable.map((u) => `  ${u}`)] : []),
+        ...(index.badPaths.length > 0
+            ? ["", "IGNORED unsafe authoredFile path(s) — a plan may be malformed:", ...index.badPaths.map((b) => `  ${b}`)]
+            : [])
+    ].join("\n");
+    return {
+        ok: true,
+        wave,
+        dir: dest,
+        copied,
+        missing,
+        pruned,
+        recoveredFromDisk: recoveredHere,
+        unreadable,
+        rejectedPaths: index.badPaths,
+        report
+    };
+}

package/dist/direct/waveCounts.js

@@ -0,0 +1,19 @@
+/**
+ * Matched means: something was actually compared (`matched > 0`) and nothing disagreed.
+ *
+ * Two failures shaped this, in opposite directions:
+ *
+ *   - Summing `item.matched` counts FACETS, not components — a field with nine compared facets
+ *     contributes nine — while the denominator counts components. Six clean waves reported
+ *     "1800.0% — 432 of 24 components verified".
+ *   - Filtering on `item.found` breaks DELETES, where success IS absence. applyLoop records a
+ *     removed component as `matched: 1, mismatches: [], found: false`, so three cleanly deleted
+ *     components scored "0.0% — 0 of 3 verified" beside a green DIFF_VERIFIED.
+ *
+ * `matched > 0 && mismatches.length === 0` is true for a clean edit and a clean delete alike, and
+ * false for a component that failed to land: compareIntent returns `matched: 0` with an "(absent)"
+ * mismatch when an edit is missing from the post-image.
+ */
+export function matchedComponentCount(intent) {
+    return intent.filter((item) => item.matched > 0 && item.mismatches.length === 0).length;
+}