in2-agent-server 0.20260821.185429

package/dist/campfire/deriveFromBundle.js

@@ -0,0 +1,1013 @@
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import { isDeepStrictEqual } from "node:util";
+import { readPlanFile } from "../core/planFile.js";
+import { expandComponent, expandObservedComponent } from "../direct/containers.js";
+import { deriveConfigItem, isConfigItemError } from "./configItem.js";
+async function readJsonIfPresent(file) {
+    try {
+        return JSON.parse(await fs.readFile(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+const CONFIG_IDENTITY_KEYS = ["fullName", "name", "label", "field", "relatedList", "apiName", "tab", "application"];
+const isRecord = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+/**
+ * Keep only the facets the submitted configuration stated; take a facet's VALUE from the org's
+ * post-image when the org has one, and keep the SUBMITTED value when it does not. This is the
+ * mismatch path's load-bearing rule, in both directions: repeating the requested blue value after
+ * Salesforce actually stored grey would make the Configuration Item repeat the wish rather than
+ * record the fact — but nulling a facet the org merely OMITS repeats the opposite lie. The intent
+ * comparator deliberately reads `externalId=false` against an org that dropped the element as
+ * AGREEMENT (absent means false), and a facet the comparator did not flag was confirmed as
+ * submitted; a genuinely-flagged facet is already named, with the org's word, in the delivery's
+ * `differences` list, which stays the authoritative account per path.
+ */
+function observedConfiguration(wanted, observed) {
+    if (Array.isArray(wanted)) {
+        const have = Array.isArray(observed) ? observed : observed === undefined || observed === null ? [] : [observed];
+        // Identity matching mirrors the comparator's (applyLoop's INTENT_IDENTITY_KEYS): an identity
+        // key only counts if its values are UNIQUE on the observed side — duplicate values would make
+        // the Map keep the last silently, pairing entries the comparator never paired.
+        const identity = CONFIG_IDENTITY_KEYS.find((key) => wanted.every((entry) => isRecord(entry) && typeof entry[key] === "string") &&
+            have.every((entry) => isRecord(entry) && typeof entry[key] === "string") &&
+            new Set(have.map((entry) => entry[key])).size === have.length);
+        if (identity) {
+            const byIdentity = new Map(have.map((entry) => [entry[identity], entry]));
+            return wanted.map((entry) => {
+                const id = entry[identity];
+                return observedConfiguration(entry, byIdentity.get(id));
+            });
+        }
+        // Positional pairing is only meaningful when the two sides are the same length — pairing a
+        // 3-entry submission against a 2-entry read matches unrelated entries. Different lengths keep
+        // the submitted entries; the differences list carries what actually changed.
+        if (have.length !== wanted.length)
+            return wanted;
+        return wanted.map((entry, index) => observedConfiguration(entry, have[index]));
+    }
+    if (isRecord(wanted)) {
+        // Metadata XML collapses a one-element collection to an object while the org reader commonly
+        // materializes it as an array. The intent comparator treats those as the same shape; the value
+        // we record in Campfire has to make the same comparison or a real mismatched Profile entry
+        // would be rendered as a set of nulls.
+        const singleton = Array.isArray(observed) && observed.length === 1 ? observed[0] : observed;
+        const have = isRecord(singleton) ? singleton : {};
+        return Object.fromEntries(Object.keys(wanted).map((key) => [key, observedConfiguration(wanted[key], have[key])]));
+    }
+    // A facet the org read does not carry keeps its submitted value — the comparator counted that
+    // absence as agreement (see the function doc). `undefined` would silently disappear from the
+    // Campfire body either way; `null` earned its place only when the WHOLE component was absent,
+    // and that case now grades unconfirmed long before this function runs.
+    return observed === undefined ? wanted : observed;
+}
+async function projectionMetadata(bundleDir, side, typeName, fullName) {
+    const manifest = await readJsonIfPresent(path.join(bundleDir, side, "projection.json"));
+    const entry = manifest?.components?.find((component) => component.typeName === typeName && component.fullName === fullName);
+    if (!entry?.found)
+        return null;
+    const snapshot = await readJsonIfPresent(path.join(bundleDir, side, entry.file));
+    return snapshot?.state?.metadata ?? null;
+}
+async function expandedAction(args) {
+    if (!args.metadataKey || args.metadataKey === args.sourceComponent)
+        return args.fallback;
+    const [pre, post] = await Promise.all([
+        projectionMetadata(args.bundleDir, "pre", args.typeName, args.fullName),
+        projectionMetadata(args.bundleDir, "post", args.typeName, args.fullName)
+    ]);
+    // A post image that does not carry the component AT ALL cannot testify to any action — "the
+    // child is gone" and "the read did not cover the container" would both render as `deleted`, and
+    // only one of them happened. The diff-based fallback answers from evidence that does exist.
+    if (post === null)
+        return args.fallback;
+    const find = (metadata) => expandObservedComponent(args.typeName, args.fullName, metadata).find((component) => `${component.typeName}:${component.fullName}` === args.metadataKey)?.configuration;
+    const before = find(pre);
+    const after = find(post);
+    if (!before && after)
+        return "created";
+    if (before && !after)
+        return "deleted";
+    if (before && after)
+        return isDeepStrictEqual(before, after) ? "no-net-change" : "updated";
+    return args.fallback;
+}
+function actionFor(diff, component, destructive) {
+    if (destructive)
+        return diff?.removed?.includes(component) ? "deleted" : "unknown";
+    if (diff?.added?.includes(component))
+        return "created";
+    if (diff?.changed?.some((entry) => entry.key === component))
+        return "updated";
+    if (diff)
+        return "no-net-change";
+    return "unknown";
+}
+async function deliveryObservation(args) {
+    const reportKey = args.facetReport ?? args.sourceComponent;
+    const report = args.verdict?.intent?.find((entry) => entry.component === reportKey);
+    // THE REPORT COVERS THE DEPLOYED COMPONENT; a container's children share it. Scope the
+    // mismatches to the child this observation is about before grading, or every innocent sibling
+    // inherits one child's drift — graded differed, its description carrying a difference in a
+    // component it does not contain, and its requirement disclosed for work that landed exactly.
+    // A child's mismatch paths carry its identity bracket (`metadata.alerts[fullName=A].template`);
+    // a path with no bracket speaks about the container as a whole and applies to every child.
+    const childLeaf = args.metadataKey && args.metadataKey !== args.sourceComponent
+        ? (args.metadataKey.split(":")[1] ?? "").split(".").pop()
+        : undefined;
+    const allMismatches = report?.mismatches ?? [];
+    const mismatches = childLeaf
+        ? allMismatches.filter((m) => !/\[[^\]]+\]/.test(m.path) || m.path.includes(`=${childLeaf}]`))
+        : allMismatches;
+    // "(absent)" is the intent check's word for "the post-image did not carry this component at
+    // all" — a read that DID NOT COVER the component, not an org that disagreed with it. Grading it
+    // "differed" was live-measured to be wrong in the worst direction: on pre-2026-07-29 evidence
+    // (before the post-image coverage fix) it stamped "the observed value below is authoritative"
+    // over a configuration projected from the same absent read — every value null. An uncovered
+    // read is UNCONFIRMED, same as a missing report or a report whose own `found` is false; only a
+    // mismatch with an actually-observed org value is a difference.
+    const observedMismatches = mismatches.filter((m) => m.observed !== "(absent)");
+    // "(still present)" is the comparator's word for a DELETE the org refused. That is a FAILED
+    // delivery, not a difference — recording it as differed wrote "DESTRUCTIVE — this component was
+    // deleted" over a component demonstrably still in the org. The action says what actually
+    // happened (nothing), the differences carry the org's word, and heldForDeliveryTruth holds the
+    // row until the operator retries the delete or drops it and re-runs.
+    const deleteStillPresent = args.destructive && mismatches.some((m) => m.observed === "(still present)");
+    let readBack = !report || report.found === false || args.verdict?.verdict === "AMBIGUOUS_DELIVERY" || (mismatches.length > 0 && observedMismatches.length === 0)
+        ? "unconfirmed"
+        : mismatches.length > 0
+            ? "differed"
+            : "matched";
+    let deliveredConfiguration = deleteStillPresent ? undefined : args.configuration;
+    if (!args.destructive && readBack === "differed" && args.configuration) {
+        const observed = await projectionMetadata(args.bundleDir, "post", args.typeName, args.fullName);
+        const observedPart = args.metadataKey
+            ? expandObservedComponent(args.typeName, args.fullName, observed).find((component) => `${component.typeName}:${component.fullName}` === args.metadataKey)?.configuration
+            : observed;
+        if (observedPart === undefined || observedPart === null) {
+            // The post image does not carry this component (or this child of it). Falling back to the
+            // PARENT body matched the child's keys against the container and nulled all of them under
+            // the authoritative banner — an uncovered read is uncovered, and the row holds.
+            readBack = "unconfirmed";
+            deliveredConfiguration = undefined;
+        }
+        else {
+            deliveredConfiguration = observedConfiguration(args.configuration, observedPart);
+        }
+    }
+    return {
+        bundle: args.bundle,
+        action: deleteStillPresent
+            ? "no-net-change"
+            : await expandedAction({
+                bundleDir: args.bundleDir,
+                sourceComponent: args.sourceComponent,
+                typeName: args.typeName,
+                fullName: args.fullName,
+                metadataKey: args.metadataKey,
+                fallback: actionFor(args.diff, args.sourceComponent, args.destructive)
+            }),
+        readBack,
+        ...(deliveredConfiguration && Object.keys(deliveredConfiguration).length > 0 ? { deliveredConfiguration } : {}),
+        ...(mismatches.length > 0 ? { differences: mismatches } : {})
+    };
+}
+// Derive every Configuration Item a set of direct_apply bundles produced. Pure computation over
+// local evidence — no org contact, no model judgement.
+/**
+ * What the org actually says about a deployed Flow, read from this bundle's post projection and
+ * returned as DATA for the description generator to project.
+ *
+ * The type table used to print "Flows deploy INACTIVE — raise a Deployment Task to activate" on
+ * every Flow row. Usually true, and on CF76 simply false: both flows landed Active, and the manifest
+ * asserted otherwise. A Configuration Item is a record of what happened, so a claim on it has to be
+ * observed rather than assumed — the evidence was sitting in the same bundle the row came from.
+ *
+ * WHY DATA AND NOT PROSE. This was once a sentence on `row.note`. But `note` is a SHARED channel —
+ * `applyAttribution` appends the amendment sentence to whatever is already there — so the status and
+ * an amendment ended up in one string, and the description generator reading the status out of the
+ * observed body would print it twice. As observed facets the status travels in the body the
+ * generator already projects, and `note` carries amendments alone.
+ *
+ * WHY IT CANNOT COME FROM THE SUBMITTED BODY. On a MATCHED read `deliveredConfiguration` is the
+ * submitted metadata. A flow submitted `<status>Draft</status>` that the org activated would then
+ * describe itself as Draft — the request reprinted as though the org had confirmed it, which is CF76
+ * through a new door. These facets are read from the post image and win over the submitted values.
+ *
+ * NARROW ON PURPOSE: only the facets the generator consumes — `label` for the identity line,
+ * `status` and `start.object` for the projection. Merging the whole Flow body would pour a metadata
+ * blob into a bounded Campfire field and balloon every preview row.
+ *
+ * SILENCE IS NOT THE SAME AS DECLINING TO OVERWRITE. When the snapshot is unreadable this returns
+ * nothing, and the CALLER must then strip these keys from the submitted body — see
+ * FLOW_OBSERVED_FACETS. Merely skipping the merge leaves the submitted status standing and the
+ * description presents the request as an observation, which is the failure this path exists to
+ * prevent.
+ */
+const FLOW_OBSERVED_FACETS = ["label", "status", "start"];
+async function observedFlowFacets(bundleDir, fullName) {
+    const metadata = await projectionMetadata(bundleDir, "post", "Flow", fullName);
+    if (!metadata)
+        return undefined;
+    const facets = {};
+    for (const key of ["label", "status"]) {
+        const value = metadata[key];
+        if (typeof value === "string" && value.trim() !== "")
+            facets[key] = value;
+    }
+    // `start.object` is where a record-triggered flow names its object. Narrowed to that one key so
+    // an observed start block cannot smuggle the rest of a flow's trigger definition into the field.
+    const start = metadata.start;
+    if (isRecord(start) && typeof start.object === "string" && start.object.trim() !== "") {
+        facets.start = { object: start.object };
+    }
+    return Object.keys(facets).length > 0 ? facets : undefined;
+}
+/**
+ * Replace every post-owned Flow facet with the org's word, or with nothing at all.
+ *
+ * The post projection is AUTHORITATIVE for these keys, which cuts both ways: an observed value wins
+ * over the submitted one, and an unreadable read means the org said nothing — so the submitted value
+ * must go too rather than sitting there looking observed. Keys outside the owned set are untouched;
+ * they are the submitted body a matched read genuinely proved.
+ *
+ * Returns `undefined` when nothing survives, so the delivery carries no body rather than an empty
+ * object (the derivation already omits empty configurations).
+ */
+function withObservedFlowFacets(submitted, observed) {
+    const merged = {};
+    for (const [key, value] of Object.entries(submitted ?? {})) {
+        if (!FLOW_OBSERVED_FACETS.includes(key))
+            merged[key] = value;
+    }
+    Object.assign(merged, observed ?? {});
+    return Object.keys(merged).length > 0 ? merged : undefined;
+}
+export async function configItemsFromBundles(bundleDirs) {
+    const byKey = new Map();
+    const unmapped = [];
+    const notes = [];
+    // Delivery ORDER is evidence: a later wave's action/destructive overwrite an earlier one's on
+    // the merged row. The session-discovery path sorts; explicit bundleDirs must sort identically,
+    // or the plan preview (which accepts bundleDirs) and the write (which discovers) can disagree
+    // about the same wave — live shape: destructive true forward, false reversed.
+    for (const dir of [...bundleDirs].sort((a, b) => path.basename(a).localeCompare(path.basename(b)))) {
+        const bundle = path.basename(dir);
+        const request = await readJsonIfPresent(path.join(dir, "request.json"));
+        if (!request) {
+            unmapped.push({ component: "(bundle)", bundle, reason: `No request.json under ${dir} — not a direct_apply evidence bundle.` });
+            continue;
+        }
+        if (request.dryRunOnly) {
+            notes.push(`${bundle}: dryRunOnly — nothing was deployed, so it contributes no Configuration Items.`);
+            continue;
+        }
+        const verdict = await readJsonIfPresent(path.join(dir, "verdict.json"));
+        const diff = await readJsonIfPresent(path.join(dir, "diff.json"));
+        // A REJECTED_BY_ORG or LINT_BLOCKED bundle deployed NOTHING — the org rolls the whole deploy
+        // back, so it is exactly as empty as a dry run and must contribute no Configuration Items.
+        //
+        // Live-caught: a wave failed on one bad component, was fixed and re-deployed as "<label>-v2",
+        // and BOTH bundles were on disk. The failed one sorts first, so its rows shadowed the
+        // successful ones and four genuinely-verified components were written back as
+        // `verified: false`. That understates delivery on a paid accuracy metric, and it is the worst
+        // kind of wrong: quiet, plausible, and pointing at real components.
+        const deployedNothing = verdict?.verdict === "REJECTED_BY_ORG" || verdict?.verdict === "LINT_BLOCKED";
+        if (deployedNothing) {
+            notes.push(`${bundle}: verdict ${verdict?.verdict} — the org rolled the whole deploy back, so it contributes no Configuration Items. If a later bundle re-deployed these components, that one is authoritative.`);
+            continue;
+        }
+        if (verdict && verdict.verdict !== "DIFF_VERIFIED" && verdict.verdict !== "DELIVERED_WITH_DRIFT") {
+            notes.push(`${bundle}: verdict ${verdict.verdict ?? "(none)"} — components below are NOT confirmed delivered; confirm before writing back.`);
+        }
+        const submitted = [
+            ...(request.edits ?? []).map((e) => ({ ...e, destructive: false })),
+            ...(request.deletes ?? []).map((d) => ({ ...d, xml: undefined, destructive: true }))
+        ];
+        for (const item of submitted) {
+            const expanded = item.destructive
+                ? expandObservedComponent(item.typeName, item.fullName, await projectionMetadata(dir, "pre", item.typeName, item.fullName))
+                : expandComponent(item.typeName, item.fullName, item.xml);
+            for (const comp of expanded) {
+                const derived = deriveConfigItem(comp.typeName, comp.fullName);
+                const source = `${item.typeName}:${item.fullName}`;
+                const metadataKey = `${comp.typeName}:${comp.fullName}`;
+                if (isConfigItemError(derived)) {
+                    unmapped.push({ component: metadataKey, bundle, reason: derived.error });
+                    continue;
+                }
+                const delivery = await deliveryObservation({
+                    bundleDir: dir,
+                    bundle,
+                    sourceComponent: source,
+                    typeName: item.typeName,
+                    fullName: item.fullName,
+                    metadataKey,
+                    configuration: comp.configuration,
+                    destructive: item.destructive,
+                    verdict,
+                    diff
+                });
+                // The org's own word about a Flow REPLACES the submitted one for the facets the post
+                // projection owns. On a matched read the delivered body is the SUBMITTED metadata, so a flow
+                // submitted Draft that the org activated would otherwise describe itself as Draft — and an
+                // unreadable read would leave that submitted Draft standing, which is the same lie with no
+                // evidence behind it at all. Both cases go through `withObservedFlowFacets`, which strips
+                // the owned keys before adding back whatever the org actually said.
+                //
+                // Destructive rows are skipped: their body is the pre-image by definition — the last state
+                // the org showed before the removal — and the post projection describes the org AFTER the
+                // delete, so merging it would overwrite that with what a refused or partial delete left.
+                if (comp.typeName === "Flow" && !item.destructive) {
+                    delivery.deliveredConfiguration = withObservedFlowFacets(delivery.deliveredConfiguration, await observedFlowFacets(dir, comp.fullName));
+                }
+                const key = `${derived.type}|${derived.apiName}|${derived.objectApiName ?? ""}|${derived.folderApiName ?? ""}`;
+                const already = byKey.get(key);
+                if (already) {
+                    // One CI, every revision. Keeping only the first wave discarded the exact update that
+                    // finished a create-then-update component; keeping only the deletion discarded the build
+                    // that preceded it. Delivery order is evidence and survives intact here.
+                    already.deliveries = [...(already.deliveries ?? []), delivery];
+                    already.sourceBundle = bundle;
+                    already.destructive = item.destructive;
+                    already.verified = (already.deliveries ?? []).every((entry) => entry.readBack === "matched");
+                    continue;
+                }
+                byKey.set(key, {
+                    ...derived,
+                    sourceComponent: source,
+                    metadataKey,
+                    sourceBundle: bundle,
+                    destructive: item.destructive,
+                    origin: "deployed",
+                    // Expanded children inherit the container's read-back — the intent check runs per
+                    // DEPLOYED component, so a child has no verdict row of its own.
+                    verified: delivery.readBack === "matched",
+                    deliveries: [delivery],
+                    ...(comp.expandedFrom ? { expandedFrom: comp.expandedFrom } : {})
+                });
+            }
+        }
+        for (const facet of request.facetUpdates ?? []) {
+            const source = `CustomObject:${facet.objectApiName}`;
+            const derived = deriveConfigItem("CustomObject", facet.objectApiName);
+            if (isConfigItemError(derived)) {
+                unmapped.push({ component: source, bundle, reason: derived.error });
+                continue;
+            }
+            const delivery = await deliveryObservation({
+                bundleDir: dir,
+                bundle,
+                sourceComponent: source,
+                typeName: "CustomObject",
+                fullName: facet.objectApiName,
+                configuration: facet.facets,
+                destructive: false,
+                verdict,
+                diff,
+                facetReport: `${source} (facets)`
+            });
+            const key = `${derived.type}|${derived.apiName}|${derived.objectApiName ?? ""}|${derived.folderApiName ?? ""}`;
+            const already = byKey.get(key);
+            if (already) {
+                already.deliveries = [...(already.deliveries ?? []), delivery];
+                already.sourceBundle = bundle;
+                already.verified = (already.deliveries ?? []).every((entry) => entry.readBack === "matched");
+            }
+            else {
+                byKey.set(key, {
+                    ...derived,
+                    sourceComponent: source,
+                    metadataKey: source,
+                    sourceBundle: bundle,
+                    destructive: false,
+                    verified: delivery.readBack === "matched",
+                    origin: "deployed",
+                    deliveries: [delivery]
+                });
+            }
+        }
+    }
+    return { rows: [...byKey.values()].sort((a, b) => `${a.type}${a.apiName}`.localeCompare(`${b.type}${b.apiName}`)), unmapped, notes };
+}
+/**
+ * A claim whose ONLY declared revisions of the component are deletions.
+ *
+ * It is not a claim to OWN the Configuration Item — the requirement built nothing — and it is
+ * deliberately kept out of every attribution decision below: it does not amend the row, it does not
+ * contest one, and it never synthesizes one. What it CAN still do is name the requirement a landed
+ * destructive row belongs to, which is the one case where a deletion has a Campfire footprint.
+ *
+ * The `!undeclared` half matters: a requirement with one delete entry and one entry declaring
+ * nothing has not established that removal is all it does, so it stays an ordinary claimant and
+ * contests exactly as it would have before deletions were expressible.
+ */
+const isRemover = (c) => !c.undeclared && c.intents.has("delete") && !c.intents.has("create") && !c.intents.has("update");
+/**
+ * Settle one component's claims, or say why they cannot be settled (R11).
+ *
+ * THE RULE: a Configuration Item is the ITEM, not the change. A dual claim where one requirement
+ * declares `intent: "create"` and the others declare `"update"` resolves to the CREATOR — one row,
+ * filed against the requirement that brought the component into existence, with the updates recorded
+ * as amendments on it. That is the class 004 §5 deliberately left UNATTRIBUTED, now well-defined.
+ *
+ * Everything else contests exactly as it did before the revision model: two creators is a genuine
+ * disagreement about who owns the component, all-updates leaves no creator to file it against, and
+ * an undeclared intent is an absence of evidence (see `PlanClaim.undeclared`).
+ *
+ * A DELETE CLAIM IS NOT A CLAIM ON THE ROW. Removers are set aside before any of that runs
+ * (`isRemover`), so a requirement retiring what another built neither contests the creator's
+ * ownership nor annotates it. That is the writeback caveat the live workaround had to state in
+ * prose and could not enforce: with `intent: "update"` as the only legal way to say "delete", the
+ * deleting requirement registered as an `amendedBy` annotation on the creating requirement's
+ * Configuration Item — an amendment for a change that had not landed and might never land. Nothing
+ * is recorded here until the deletion actually lands, at which point the destructive bundle
+ * produces the row and `remover` is who it is filed against.
+ */
+function resolveClaims(claims) {
+    const removers = claims.filter(isRemover);
+    const builders = claims.filter((c) => !isRemover(c));
+    const creators = builders.filter((c) => c.intents.has("create"));
+    const attribution = {
+        ...(creators.length === 1 ? { createdBy: creators[0].extId } : {}),
+        // An amender declares an update and no create of its own. A requirement declaring both halves
+        // authored the chain itself: it is the owner, not an annotation on someone else's row.
+        amendedBy: builders.filter((c) => !c.undeclared && c.intents.has("update") && !c.intents.has("create")).map((c) => c.extId)
+    };
+    if (builders.length === 0) {
+        // Nothing in this batch builds it — every claimant only wants it gone. One remover is who a
+        // landed destructive row is filed against; two is a genuine disagreement about who owns the
+        // removal, and read order is not entitled to settle that either.
+        const remover = removers.length === 1 ? removers[0] : undefined;
+        if (remover) {
+            return {
+                attribution,
+                settled: {
+                    extId: remover.extId,
+                    deployable: remover.deployable,
+                    approvedDetails: remover.approvedDetails,
+                    deleteOnly: true
+                }
+            };
+        }
+        return { attribution, contest: "no-creator" };
+    }
+    const only = builders.length === 1 ? builders[0] : undefined;
+    if (only) {
+        return {
+            attribution,
+            settled: { extId: only.extId, deployable: only.deployable, approvedDetails: only.approvedDetails }
+        };
+    }
+    if (builders.some((c) => c.undeclared))
+        return { attribution, contest: "intent-unknown" };
+    if (creators.length === 0)
+        return { attribution, contest: "no-creator" };
+    if (creators.length > 1)
+        return { attribution, contest: "double-create" };
+    return {
+        attribution,
+        settled: {
+            extId: creators[0].extId,
+            deployable: creators[0].deployable,
+            approvedDetails: creators[0].approvedDetails
+        }
+    };
+}
+/**
+ * The amendment sentence for one row, or undefined when there is nothing to record.
+ *
+ * WHERE IT LANDS, AND WHY THERE: `note`, which `campfire/configItemDescription.ts`'s `describeConfigItem`
+ * composes into `Description__c`. That is the whole of a Configuration Item's free text in Campfire, so it is
+ * the only surface an amendment can reach WITHOUT an org schema change. It is recomposed from the
+ * derivation on every pass, so a re-writeback upserts an identical body under the same external id:
+ * idempotent by construction, and still one row per component.
+ *
+ * `note` CARRIES AMENDMENTS, NOT OBSERVED FACTS. A Flow's status was once seeded here too, and
+ * because this function APPENDS, the two shared one string — the generator also reads the status
+ * out of the observed body, so the row stated it twice. Observed facts travel as data on the
+ * delivery instead; see observedFlowFacets.
+ *
+ * A deployment task was the alternative (006 §8). Rejected: a task is a TODO for a human, and an
+ * amendment that already landed is neither outstanding nor manual — filing one would inflate
+ * `Number_of_Deployment_Tasks__c` with work that is done.
+ */
+function amendmentNote(owner, { createdBy, amendedBy }) {
+    const others = amendedBy.filter((extId) => extId !== owner);
+    if (others.length > 0) {
+        return `Amended by ${others.join(", ")}${createdBy ? ` after ${createdBy} created it` : ""} — a Configuration Item is the component, not the change, so the later revision is recorded here rather than as a second row.`;
+    }
+    if (!amendedBy.includes(owner))
+        return undefined;
+    return createdBy && createdBy !== owner
+        ? `Filed against ${owner}, whose revision UPDATES this component; ${createdBy} declared the create revision.`
+        : `${owner}'s revision UPDATES this component; nothing in this batch created it, so the Configuration Item is filed against the requirement that changed it.`;
+}
+/** Stamp the revision facts onto a row that has just been attributed to `owner`. */
+function applyAttribution(row, owner, attribution) {
+    if (attribution.amendedBy.length === 0)
+        return;
+    row.amendedBy = [...attribution.amendedBy];
+    const sentence = amendmentNote(owner, attribution);
+    if (sentence)
+        row.note = row.note ? `${row.note} ${sentence}` : sentence;
+}
+/** A `waves` label that matches no evidence bundle. A caller mistake, not an internal fault. */
+export class UnknownWaveError extends Error {
+    code = "UNKNOWN_WAVE";
+    constructor(message) {
+        super(message);
+        this.name = "UnknownWaveError";
+    }
+}
+export async function configItemsForSession(opts) {
+    // Bundles now live under the session, so they are DISCOVERABLE rather than dictated. Passing
+    // absolute paths by hand was only ever necessary because evidence was filed by org alias
+    // somewhere else entirely — one more thing the model had to carry correctly between calls.
+    let bundleDirs = opts.bundleDirs ?? [];
+    if (bundleDirs.length === 0 && opts.sessionDir) {
+        const root = path.join(opts.sessionDir, "direct");
+        if (opts.waves?.length) {
+            // Named waves resolve to bundle dirs by label. A label that does not exist is an ERROR
+            // rather than an empty contribution: silently deriving nothing from a misspelled wave would
+            // publish a manifest that is missing components and looks complete.
+            const missing = [];
+            for (const label of opts.waves) {
+                const dir = path.join(root, label);
+                try {
+                    if ((await fs.stat(dir)).isDirectory())
+                        bundleDirs.push(dir);
+                    else
+                        missing.push(label);
+                }
+                catch {
+                    missing.push(label);
+                }
+            }
+            if (missing.length > 0) {
+                throw new UnknownWaveError(`no evidence bundle for wave(s): ${missing.join(", ")}. Bundle labels are the \`label\` passed to direct_apply; omit \`waves\` to derive from every bundle in the session.`);
+            }
+            bundleDirs.sort();
+        }
+        else {
+            try {
+                const entries = (await fs.readdir(root, { withFileTypes: true })).filter((e) => e.isDirectory());
+                // Sorted by name: the default label is an ISO timestamp, so this is delivery order.
+                bundleDirs = entries.map((e) => path.join(root, e.name)).sort();
+            }
+            catch {
+                // No bundles yet is a normal state (nothing deployed), not an error.
+            }
+        }
+    }
+    const base = await configItemsFromBundles(bundleDirs);
+    const rows = [...base.rows];
+    const unmapped = [...base.unmapped];
+    const notes = [...base.notes];
+    const ownershipGaps = [];
+    const ownershipConflicts = [];
+    const owner = new Map();
+    // Every plan.json claim per component, not just the winning one. `owner` can only hold one
+    // requirement per key, so it cannot tell "one claimant" from "the last of three" — and that
+    // difference is exactly what has to be reported or resolved rather than settled by read order.
+    const planClaims = new Map();
+    let plansFound = 0;
+    const reqDir = opts.sessionDir ? path.join(opts.sessionDir, "requirements") : undefined;
+    if (!opts.sessionDir) {
+        notes.push("No sessionDir given — rows cover only what these bundles deployed. A requirement that OWNS an already-existing component will be UNDER-COUNTED. Pass sessionDir so the plan.json ownership join runs.");
+    }
+    else if (reqDir) {
+        let extIds = [];
+        try {
+            extIds = (await fs.readdir(reqDir, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name);
+        }
+        catch {
+            notes.push(`No requirements/ under ${opts.sessionDir} — ownership join skipped.`);
+        }
+        for (const extId of extIds) {
+            // Through `core/planFile.ts` rather than a local shape: `intent` is what decides a dual claim
+            // now, and four readers each defaulting their own subset of this file is how they came to
+            // disagree about what one entry means.
+            const parsed = await readPlanFile(path.join(reqDir, extId, "plan.json"), extId);
+            if (!parsed.ok) {
+                // A missing plan.json is the normal "analyzer has not run" state, reported in aggregate
+                // below. A plan that EXISTS and cannot be read is a different fact: it drops a requirement's
+                // every ownership claim, which reads downstream as components nobody owns.
+                if (parsed.error.code !== "PLAN_NOT_FOUND")
+                    notes.push(parsed.error.message);
+                continue;
+            }
+            plansFound += 1;
+            // The DOCUMENT's extId still wins over the directory name — two dirs carrying one
+            // requirement's plan are one claimant, not a dual claim.
+            const owning = parsed.plan.declaredExtId ?? extId;
+            for (const refusal of parsed.plan.refusals) {
+                // Only the intent refusal changes what this join can settle: an entry whose `intent` was
+                // rejected reads as UNDECLARED, so a dual claim it belongs to contests. Say so, or the
+                // contest looks like plans that simply never declared anything.
+                if (refusal.code === "INVALID_INTENT")
+                    notes.push(refusal.message);
+            }
+            for (const entry of parsed.plan.entries) {
+                let claims = planClaims.get(entry.key);
+                if (!claims) {
+                    claims = [];
+                    planClaims.set(entry.key, claims);
+                }
+                let claim = claims.find((c) => c.extId === owning);
+                if (!claim) {
+                    claim = { extId: owning, intents: new Set(), undeclared: false, deployable: true, approvedDetails: [] };
+                    claims.push(claim);
+                }
+                if (entry.intent)
+                    claim.intents.add(entry.intent);
+                else
+                    claim.undeclared = true;
+                claim.deployable = entry.deployable;
+                const details = Array.isArray(entry.raw.operatorDecidedFacets)
+                    ? entry.raw.operatorDecidedFacets.filter((value) => typeof value === "string" && value.trim() !== "")
+                    : [];
+                claim.approvedDetails = [...new Set([...claim.approvedDetails, ...details])];
+            }
+        }
+        if (plansFound === 0 && !(opts.ownership?.length)) {
+            notes.push(`No plan.json found under ${reqDir} (${extIds.length} requirement dir(s)) and no ownership override supplied — the analyzers did not run, so no row can be mapped to a requirement.`);
+        }
+    }
+    // Settle every claimed key BEFORE the override runs, so `owner` holds the revision model's answer
+    // rather than whichever entry `readdir` yielded last. A key that cannot be settled goes to
+    // `planContests` and stays OUT of `owner` — an unattributed row is what makes the tools refuse.
+    const planContests = new Map();
+    const attributions = new Map();
+    for (const [key, claims] of planClaims) {
+        const { attribution, settled, contest } = resolveClaims(claims);
+        attributions.set(key, attribution);
+        if (settled) {
+            owner.set(key, {
+                extId: settled.extId,
+                deployable: settled.deployable,
+                source: "plan",
+                attribution,
+                approvedDetails: settled.approvedDetails,
+                ...(settled.deleteOnly ? { deleteOnly: true } : {})
+            });
+        }
+        else if (contest)
+            planContests.set(key, contest);
+    }
+    // The override goes on TOP of plan.json, and it is the one place a contested component CAN be
+    // settled — the supervisor is consolidating the batch and is entitled to make the call, on the
+    // record. So an override that names one of the claiming requirements RESOLVES the contest
+    // (noted as asserted); an override that names a requirement no claiming plan mentions is a
+    // disagreement with all of them, and is reported rather than obeyed.
+    const overridden = new Map();
+    const overrideConflicts = new Map();
+    for (const claim of opts.ownership ?? []) {
+        if (!claim.typeName || !claim.fullName || !claim.extId)
+            continue;
+        const key = `${claim.typeName}:${claim.fullName}`;
+        const claimants = (planClaims.get(key) ?? []).map((c) => c.extId).sort();
+        const priorOverride = overridden.get(key);
+        if (priorOverride && priorOverride !== claim.extId) {
+            // The override contradicting ITSELF. Same defect as the one this function exists to close —
+            // array order is not an opinion about who owns a component either.
+            overrideConflicts.set(key, {
+                claimants: [...new Set([...claimants, priorOverride, claim.extId])],
+                override: claim.extId
+            });
+        }
+        else if (claimants.length > 0 && !claimants.includes(claim.extId)) {
+            overrideConflicts.set(key, {
+                claimants: [...claimants, claim.extId],
+                plan: claimants.length === 1 ? claimants[0] : undefined,
+                override: claim.extId
+            });
+        }
+        else if (claimants.length > 1) {
+            // A key the revision model already settled is not a disagreement — saying "the plans still
+            // disagree" about a declared create-then-update pair would report the model's own answer as a
+            // defect, and send the operator to fix plans that are correct.
+            const settled = owner.get(key);
+            notes.push(settled?.source === "plan"
+                ? `${key}: the revision model files this under ${settled.extId}, the requirement that CREATED it; your ownership override files it under ${claim.extId} instead. ASSERTED, not computed.`
+                : `${key}: claimed by ${claimants.join(" and ")}; your ownership override files it under ${claim.extId}. ASSERTED, not computed — the plans still disagree.`);
+        }
+        overridden.set(key, claim.extId);
+        owner.set(key, {
+            extId: claim.extId,
+            deployable: true,
+            source: "supervisor",
+            attribution: attributions.get(key) ?? { amendedBy: [] },
+            approvedDetails: (planClaims.get(key) ?? []).find((candidate) => candidate.extId === claim.extId)?.approvedDetails ?? []
+        });
+    }
+    // Contested components stay OUT of `owner`: an unattributed row is what makes the tools refuse,
+    // and refusing is the whole point. Sorted so the report does not depend on readdir order either.
+    for (const [key, reason] of planContests) {
+        if (overridden.has(key))
+            continue;
+        ownershipConflicts.push({
+            component: key,
+            kind: "plan",
+            claimants: (planClaims.get(key) ?? []).map((c) => c.extId).sort(),
+            reason
+        });
+    }
+    for (const [key, c] of overrideConflicts) {
+        ownershipConflicts.push({ component: key, kind: "override", claimants: c.claimants, plan: c.plan, override: c.override });
+    }
+    ownershipConflicts.sort((a, b) => a.component.localeCompare(b.component));
+    const contested = new Set(ownershipConflicts.map((c) => c.component));
+    for (const key of contested)
+        owner.delete(key);
+    if (owner.size === 0) {
+        return {
+            rows,
+            unmapped,
+            notes,
+            ownershipGaps,
+            ownershipSource: "none",
+            ownershipConflicts,
+            bundlesRead: bundleDirs,
+            requirementDisclosures: []
+        };
+    }
+    // 1. Attach the owning requirement to each deployed row; flag deployed-but-unowned.
+    const seen = new Set();
+    for (const row of rows) {
+        // metadataKey first — it is the post-expansion component in the SAME vocabulary plan.json
+        // uses, so a container child (WorkflowAlert:Obj.Alert) matches even though the row's
+        // Campfire `type` is WorkflowEmailAlert.
+        const resolved = owner.get(row.metadataKey) ??
+            owner.get(row.sourceComponent) ??
+            (row.expandedFrom ? owner.get(row.expandedFrom) : undefined);
+        if (resolved) {
+            row.requirement = resolved.extId;
+            if (resolved.approvedDetails.length > 0)
+                row.approvedDetails = [...resolved.approvedDetails];
+            applyAttribution(row, resolved.extId, resolved.attribution);
+        }
+        // A contested row is NOT a gap. "Nobody claims it" and "two requirements claim it" have
+        // different fixes, and reporting the second as the first sends the operator to write an
+        // ownership override for a component that already has too many owners.
+        else if (!contested.has(row.metadataKey) && !contested.has(row.sourceComponent) && !(row.expandedFrom && contested.has(row.expandedFrom))) {
+            ownershipGaps.push({
+                component: row.metadataKey,
+                reason: "Deployed but no plan.json claims ownership — this Configuration Item cannot be mapped to a requirement."
+            });
+        }
+        seen.add(row.metadataKey);
+        seen.add(row.sourceComponent);
+        if (row.expandedFrom)
+            seen.add(row.expandedFrom);
+    }
+    // Index deployed rows by the Campfire identity (Type + API Name). A plan can name a component
+    // differently from how it was finally delivered — live-caught: EXT-654E planned an
+    // object-specific QuickAction and the operator approved shipping it GLOBAL, so the plan key and
+    // the deployed key differ while both mean the SAME Configuration Item. Adding the plan's
+    // version would double-count, which is precisely the accuracy failure this tool exists to stop.
+    const deployedByIdentity = new Map();
+    for (const r of rows)
+        deployedByIdentity.set(`${r.type}|${r.apiName}`, r);
+    // 2. Add OWNED components no bundle touched — the under-count this join exists to fix.
+    //
+    // SKIPPED when `waves` scoped the derivation. Step 1 above still ATTACHES the owning requirement
+    // to every delivered row (that is what makes a row writable at all), but adding the
+    // owned-but-not-delivered components back would defeat the scoping entirely: the caller asked
+    // for one wave and would get the whole requirement's manifest again, merely relabelled
+    // PRE-EXISTING. Live-caught while wiring this — scoping to a single wave still produced all 19
+    // rows, so per-wave writeback would have re-saved every row and inflated exactly the counters
+    // the scoping exists to protect.
+    const scopedToWaves = Boolean(opts.waves?.length);
+    if (scopedToWaves) {
+        notes.push(`scoped to wave(s) ${opts.waves?.join(", ")}: rows are what these bundles DELIVERED. Owned-but-already-existing components are omitted — derive without \`waves\` at end of run for each requirement's complete manifest.`);
+    }
+    for (const [compKey, { extId, deployable, attribution, deleteOnly }] of scopedToWaves ? [] : owner) {
+        if (seen.has(compKey))
+            continue;
+        if (deleteOnly) {
+            // A DELETION THAT HAS NOT LANDED RECORDS NOTHING. `seen` covers every component this run's
+            // bundles touched, so reaching here means no destructive package carried this member — the
+            // removal was planned, ordered, and not executed. Synthesizing a `pre-existing` row for it
+            // would put a component on the manifest that the requirement's whole work is to remove, and
+            // mark it delivered. Nothing until landed is the honest record; once it lands, the destructive
+            // bundle produces the row above and step 1 files it against this same requirement.
+            notes.push(`${extId}: plans the DELETION of ${compKey}, and no bundle in this derivation carried it — so it contributes no Configuration Item. Nothing is recorded for a deletion until it lands.`);
+            continue;
+        }
+        const sep = compKey.indexOf(":");
+        const typeName = compKey.slice(0, sep);
+        const fullName = compKey.slice(sep + 1);
+        const derived = deriveConfigItem(typeName, fullName);
+        if (isConfigItemError(derived)) {
+            unmapped.push({ component: compKey, bundle: `plan:${extId}`, reason: derived.error });
+            continue;
+        }
+        const identity = `${derived.type}|${derived.apiName}`;
+        const already = deployedByIdentity.get(identity);
+        if (already) {
+            // Same Configuration Item, named differently by plan vs delivery. Keep the DELIVERED row
+            // (it reflects the org) and attach ownership rather than emitting a second row.
+            if (!already.requirement) {
+                already.requirement = extId;
+                applyAttribution(already, extId, attribution);
+            }
+            const gapIdx = ownershipGaps.findIndex((g) => g.component === already.metadataKey);
+            if (gapIdx >= 0)
+                ownershipGaps.splice(gapIdx, 1);
+            if (already.metadataKey !== compKey) {
+                const disclosure = `The plan owns ${compKey}, but it was delivered as ${already.metadataKey}; ` +
+                    `the delivered Configuration Item shape is authoritative.`;
+                notes.push(`${extId}: ${disclosure}`);
+                already.disclosureNotes = [...(already.disclosureNotes ?? []), disclosure];
+            }
+            continue;
+        }
+        const row = {
+            ...derived,
+            sourceComponent: compKey,
+            metadataKey: compKey,
+            destructive: false,
+            // Not in this run's evidence, so this run did not verify it. Its presence in the org is
+            // what the analyzer asserted from the projection, not something we re-proved here.
+            verified: false,
+            requirement: extId,
+            origin: deployable ? "pre-existing" : "routed",
+            ...(owner.get(compKey)?.approvedDetails.length ? { approvedDetails: owner.get(compKey).approvedDetails } : {})
+        };
+        applyAttribution(row, extId, attribution);
+        rows.push(row);
+    }
+    rows.sort((a, b) => `${a.requirement ?? "zz"}${a.type}${a.apiName}`.localeCompare(`${b.requirement ?? "zz"}${b.type}${b.apiName}`));
+    // Report where the attributions actually came from, so a reviewer can tell a computed manifest
+    // from an asserted one at a glance — they carry different confidence.
+    const sources = new Set(rows.filter((r) => r.requirement).map((r) => owner.get(r.metadataKey)?.source ?? "plan"));
+    const ownershipSource = rows.every((r) => !r.requirement) ? "none" : sources.size > 1 ? "mixed" : sources.has("supervisor") ? "supervisor" : "plan";
+    const disclosuresByRequirement = new Map();
+    const disclose = (requirement, component, note) => {
+        const current = disclosuresByRequirement.get(requirement) ?? { components: new Set(), notes: [] };
+        current.components.add(component);
+        if (!current.notes.includes(note))
+            current.notes.push(note);
+        disclosuresByRequirement.set(requirement, current);
+    };
+    // A held row writes NOTHING — its disclosure would tell the operator to paste "The
+    // Configuration Item records the observed org value" about a Campfire record that does not
+    // exist. The row discloses when it writes, after the operator reconciles it.
+    const heldKeys = new Set(heldForDeliveryTruth(rows).map(({ row }) => row.metadataKey));
+    for (const row of rows) {
+        if (!row.requirement || heldKeys.has(row.metadataKey))
+            continue;
+        for (const note of row.disclosureNotes ?? [])
+            disclose(row.requirement, row.metadataKey, note);
+        // Scoped to the FINAL delivery only, mirroring `deviations()` in configItemDescription.ts —
+        // this sentence asserts what the Configuration Item row records, and that row describes the
+        // final delivery (see finalConfiguration/deviations there). A component that differed in an
+        // earlier wave and matched in a later, corrective wave has no deviation text on its CI row;
+        // disclosing from the earlier delivery would tell the operator the record says something it
+        // does not. Keep this rule identical to deviations()'s so the two cannot drift apart.
+        const finalDelivery = (row.deliveries ?? []).at(-1);
+        if (finalDelivery && finalDelivery.readBack === "differed") {
+            const differences = (finalDelivery.differences ?? [])
+                .map((difference) => `${difference.path}: org stored ${difference.observed} (approved ${difference.intended})`)
+                .join("; ");
+            disclose(row.requirement, row.metadataKey, `${row.metadataKey} differed from the approved configuration after delivery${differences ? ` — ${differences}` : ""}. ` +
+                `The Configuration Item records the observed org value.`);
+        }
+    }
+    const requirementDisclosures = [...disclosuresByRequirement]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([requirement, disclosure]) => ({
+        requirement,
+        components: [...disclosure.components].sort(),
+        text: disclosure.notes.join(" ")
+    }));
+    return {
+        rows,
+        unmapped,
+        notes,
+        ownershipGaps,
+        ownershipSource,
+        ownershipConflicts,
+        bundlesRead: bundleDirs,
+        requirementDisclosures
+    };
+}
+/** Why a dual claim survived the revision model, in the operator's terms. */
+function contestReason(reason) {
+    switch (reason) {
+        case "double-create":
+            return 'both declare `intent: "create"`, so they genuinely disagree about who creates it';
+        case "no-creator":
+            return 'no claim is an `intent: "create"` — nothing in this batch created it, so there is no creator to file it against (two requirements each declaring only its DELETION reaches here too: they disagree about who owns the removal)';
+        case "intent-unknown":
+            return "at least one of them declares no `intent`, so create-vs-update cannot be told apart (this derivation reads no org projection and will not guess)";
+        default:
+            return "two or more plan.json";
+    }
+}
+/**
+ * The refusal a derivation demands before ANY of it is written back, or null when it is writable.
+ *
+ * Shared by the preview (`campfire_config_item_plan`) and the write (`campfire_write_config_items`)
+ * so the two cannot disagree about what is writable — a preview that passes while the write refuses
+ * sends the operator to Campfire with a manifest that will not land.
+ *
+ * CONTESTED IS CHECKED BEFORE UNOWNED. A contested component is deliberately left unattributed, so
+ * checking "unowned" first would report OWNERSHIP_UNRESOLVED — "no requirement claims this" — for a
+ * component two requirements are fighting over, and point the fix at the wrong end.
+ */
+export function ownershipRefusal(d) {
+    if (d.ownershipConflicts.length > 0) {
+        return {
+            code: "OWNERSHIP_CONFLICT",
+            message: [
+                `${d.ownershipConflicts.length} component(s) are claimed by more than one requirement. Which requirement a`,
+                "Configuration Item is filed against is not something read order can decide, so NOTHING was written:",
+                ...d.ownershipConflicts.map((c) => c.kind === "override"
+                    ? c.plan
+                        ? `  - ${c.component}: plan.json says ${c.plan}, your ownership override says ${c.override}`
+                        : `  - ${c.component}: named for ${c.claimants.join(", ")} — your ownership override did not settle it`
+                    : `  - ${c.component}: claimed by ${c.claimants.join(" and ")} — ${contestReason(c.reason)}`),
+                "",
+                "Resolve it, do not let an ordering resolve it:",
+                "  1. Fix plan.json — exactly one requirement OWNS a component; the others list it under dependsOn.",
+                "  2. Or pass `ownership: [{typeName, fullName, extId}, ...]` naming one of the claiming requirements.",
+                "     That is recorded as ASSERTED by you rather than computed, and it resolves the contest.",
+                "",
+                "A create-then-update pair does NOT reach this refusal. When one claimant's plan.json declares",
+                '`intent: "create"` and the others declare `"update"`, the Configuration Item is filed against the',
+                "CREATOR automatically — a CI is the component, not the change — and each update is recorded as an",
+                "amendment on that one row, so the component still counts once. The claims above could not be read",
+                "that way; declaring the missing intents is the fix that makes them computable."
+            ].join("\n")
+        };
+    }
+    const unowned = d.rows.filter((r) => !r.requirement);
+    if (unowned.length === 0)
+        return null;
+    return {
+        code: "OWNERSHIP_UNRESOLVED",
+        message: [
+            `${unowned.length} of ${d.rows.length} Configuration Item(s) map to no requirement, so NOTHING was written:`,
+            ...unowned.map((r) => `  - ${r.metadataKey}`),
+            "",
+            "Two ways to resolve, both legitimate:",
+            "  1. Run the requirement analyzers so each writes its plan.json (the normal path — ownership is then COMPUTED).",
+            "  2. Pass `ownership: [{typeName, fullName, extId}, ...]` with the mapping you already worked out reading the batch (ASSERTED — use when a small batch did not warrant analyzers).",
+            ...(d.ownershipSource === "none" ? [] : [`Current attribution source: ${d.ownershipSource}.`])
+        ].join("\n")
+    };
+}
+/**
+ * How to make a held Configuration Item writable. Single-sourced so the plan preview, the write
+ * report and the playbook cannot drift apart in what they tell the operator to do — a hold
+ * without a printed remedy is a dead end for a non-technical operator.
+ */
+export const DELIVERY_TRUTH_REMEDY = "To make a held row writable: re-read the component from the target org so an authoritative post-delivery image exists " +
+    "(re-project it — for an AMBIGUOUS_DELIVERY wave, reconcile the wave first so the verdict covers it), " +
+    "then re-run campfire_config_item_plan and campfire_write_config_items. The row writes as soon as its delivery truth is observed.";
+/**
+ * The deployed rows whose post-deploy org read never established what happened. A deploy response
+ * is a claim; the independent post-image is the evidence — a row on this list must not be
+ * published as delivered, because the Campfire record would repeat the request as fact.
+ *
+ * PER ROW, deliberately: the write holds exactly these and writes the rest, mirroring the write
+ * loop's own doctrine that one bad row must not strand the manifest. A batch-wide refusal was the
+ * first shape here and it inverted that doctrine — one ambiguous wave blocked every confirmed row
+ * in the session, with nothing the operator could do but fix ALL of it before writing ANY of it.
+ */
+export function heldForDeliveryTruth(rows) {
+    const held = [];
+    for (const row of rows) {
+        if (row.origin !== "deployed")
+            continue;
+        if (!row.deliveries?.length) {
+            held.push({ row, reason: "no delivery observation — nothing on disk says what this deploy did to the org" });
+            continue;
+        }
+        // A delete the org refused: the row's request says destroy, the org still holds the component.
+        // Writing it would record a deletion that did not happen; the fix is the operator's call
+        // (retry the delete, or drop it from the request), not a description's.
+        const refusedDelete = row.destructive
+            ? row.deliveries.filter((delivery) => delivery.differences?.some((d) => d.observed === "(still present)"))
+            : [];
+        if (refusedDelete.length > 0) {
+            held.push({
+                row,
+                reason: `the delete did not land — the org still holds this component (${refusedDelete.map((d) => `[${d.bundle}]`).join(", ")}); retry the delete or drop it from the request, then re-run`
+            });
+            continue;
+        }
+        const unconfirmed = row.deliveries.filter((delivery) => delivery.readBack === "unconfirmed");
+        if (unconfirmed.length > 0) {
+            held.push({
+                row,
+                reason: `no authoritative org read-back for ${unconfirmed.map((d) => `[${d.bundle}]`).join(", ")} — the post-deploy read did not cover this component`
+            });
+        }
+    }
+    return held;
+}