in2-agent-server 0.20260821.185429

package/dist/direct/lint.js

@@ -0,0 +1,382 @@
+import { XMLParser, XMLValidator } from "fast-xml-parser";
+import { checkAgainstSchema, schemaVersion } from "./metadataSchema.js";
+import { ORG_ENFORCED_ELEMENTS } from "./knownTokens.js";
+const PARSER = new XMLParser({ ignoreAttributes: true, parseTagValue: false, trimValues: true });
+export function parseMetadataXml(xml) {
+    if (XMLValidator.validate(xml) !== true)
+        return null;
+    const doc = PARSER.parse(xml);
+    const roots = Object.keys(doc).filter((k) => k !== "?xml");
+    if (roots.length !== 1)
+        return null;
+    const rootKey = roots[0];
+    if (!rootKey)
+        return null;
+    const body = doc[rootKey];
+    if (!body || typeof body !== "object")
+        return null;
+    return { root: rootKey, body: body };
+}
+const CUSTOM_TOKEN_RE = /\b[A-Za-z][A-Za-z0-9_]*__(?:c|mdt|r)\b/g;
+// Elements that hold NESTED metadata members, each of which needs its own <fullName>. Deliberately
+// a list rather than a schema lookup: these are container relationships, not value objects, and the
+// artifact does not mark the difference (`valueSet` and `nameField` are nested objects too, and
+// correctly have no fullName).
+const CHILD_CONTAINERS = new Set([
+    "compactLayouts",
+    "listViews",
+    "validationRules",
+    "webLinks",
+    "recordTypes",
+    "fields",
+    "fieldSets",
+    "businessProcesses",
+    "sharingReasons"
+    // NOT approvalStep: an approval step is identified by <name>, not <fullName>, and CF75 deployed
+    // one successfully in exactly that shape. Including it made this rule block a valid file — caught
+    // by the existing schema-tier test, which is the second time today a container list has been the
+    // wrong instinct. Add an entry only when a real deploy has rejected the nameless form.
+]);
+// Types that live UNDER an object in source format (objects/<Obj>/<plural>/<Name>.<ext>-meta.xml).
+// Their file path names the parent, not the component, so the body must carry its own <fullName>.
+// Verified against CF76's authored tree: every CustomField and CompactLayout file carries one;
+// CustomObject, CustomTab, Flow, Layout, Group, FlexiPage, ApprovalProcess and CustomApplication —
+// all top-level — carry none.
+const OBJECT_CHILD_TYPES = new Set([
+    "CustomField",
+    "CompactLayout",
+    "ListView",
+    "ValidationRule",
+    "WebLink",
+    "RecordType",
+    "FieldSet",
+    "BusinessProcess",
+    "SharingReason",
+    "Index"
+]);
+// A metadata element that holds either one child or many reads back as an object or an array of
+// them; the rules below want the same shape either way.
+const asList = (node) => (Array.isArray(node) ? node : [node]).filter((c) => Boolean(c) && typeof c === "object" && !Array.isArray(c));
+// Types whose <description> the org caps at 255 characters.
+//
+// TYPE-SCOPED, deliberately, never a blanket length rule: the cap differs per type — a CustomField
+// or CustomObject description takes 1000 — so a global check would refuse files the org accepts
+// daily. That is the "guessing a type list" mistake this file has already made twice. An entry
+// here means a real deploy REJECTED the over-long value, not that the reasoning looks the same.
+const DESCRIPTION_MAX = 255;
+const DESCRIPTION_CAPPED_TYPES = new Set(["ValidationRule", "PermissionSet"]);
+// The same components authored INSIDE a CustomObject file rather than as their own: container
+// element -> the capped child type it holds.
+const DESCRIPTION_CAPPED_CONTAINERS = { validationRules: "ValidationRule" };
+export function runLint(edits, knownCustomTokens, // from the pre-projection; null = referential tier skipped
+acks, provenValues, // org-proven values for elements no schema can validate
+plannedTokens // tokens the approved batch will CREATE (plan.json), for the referential split
+) {
+    const findings = [];
+    const acked = new Set(acks);
+    const editedTokens = new Set();
+    for (const e of edits) {
+        editedTokens.add(e.fullName);
+        for (const part of e.fullName.split("."))
+            editedTokens.add(part);
+    }
+    for (const edit of edits) {
+        const component = `${edit.typeName}:${edit.fullName}`;
+        const push = (rule, severity, message, ackable = true) => findings.push({ rule, severity, component, message, ackable });
+        const parsed = parseMetadataXml(edit.xml);
+        if (!parsed) {
+            push("XML_MALFORMED", "error", "XML does not parse or has no single metadata root element.", false);
+            continue;
+        }
+        if (parsed.root !== edit.typeName) {
+            push("ROOT_TYPE_MISMATCH", "error", `Root element <${parsed.root}> does not match declared typeName ${edit.typeName}.`, false);
+            continue;
+        }
+        const md = parsed.body;
+        // LEMMA (D2, live-caught batch 1 + checkOnly probes 2026-07-22): a Picklist's
+        // field-level <defaultValue> is FORMULA-parsed; a quoted literal validates green
+        // and is then silently ignored — defaults live on the value's <default>true</default>.
+        if ((md.type === "Picklist" || md.type === "MultiselectPicklist") && md.defaultValue !== undefined) {
+            push("LEMMA_D2_FIELD_LEVEL_DEFAULT", "error", `Field-level <defaultValue> on a ${md.type} is formula-parsed and silently ignored (lemma D2). Set <default>true</default> on the value inside valueSetDefinition instead.`);
+        }
+        // LEMMA (D3, live-caught batch 1; checkOnly rejects it with a precise error): the
+        // platform forbids required long text areas.
+        if ((md.type === "LongTextArea" || md.type === "Html") && String(md.required) === "true") {
+            push("LEMMA_D3_REQUIRED_LTA", "error", `<required>true</required> on a ${md.type} is rejected by the platform (lemma D3): "Can not specify 'required' for a CustomField of type LongTextArea".`);
+        }
+        // LEMMA (batch-2 step 6, live-caught): a top-level CustomObject deploy must carry
+        // the full definition; a partial file (e.g. only compactLayoutAssignment) fails
+        // "Must specify a non-empty label". What is illegal is the PARTIAL file, not the deploy —
+        // the fix is to complete it from the org's pre-image, which is also the safer brownfield
+        // path (CustomObject MERGES, so children are not collateral). The CRUD route this message
+        // used to recommend outright is a read-modify-write that REPLACES top-level properties, and
+        // it has now leaked data twice; it belongs to facets a source deploy cannot carry.
+        if (edit.typeName === "CustomObject" && md.label === undefined) {
+            push("LEMMA_PARTIAL_CUSTOMOBJECT", "error", "CustomObject deploy without <label> — top-level object deploys must carry the full definition (live-caught: bare compactLayoutAssignment file failed). Complete the file from the org's pre-image (direct_apply retrieves it to pre/source/): CustomObject merges, so a full definition changes the facet without touching children. direct_apply objectFacetUpdates is the fallback for facets a source deploy cannot carry.");
+        }
+        // LEMMA (CF63 w2, live-caught 2026-07-31): deploying a Flow with <status>Obsolete</status> does
+        // NOT deactivate the flow. Salesforce VERSIONS flows — the deploy lands a new, inactive version
+        // and the previously-active version keeps running. The deploy reports Succeeded, so the only
+        // signal is the read-back, and even that is subtle: the run saw "intended Obsolete, still reads
+        // Active" and had to go find the real mechanism.
+        //
+        // Worse, the tool surface TAUGHT this: the deployment-task writer's description asserted a Flow
+        // "deploys with the status its XML DECLARES", which is true for a CREATE and false for a
+        // deactivation. That sentence is corrected; this rule catches the attempt itself.
+        //
+        // Deactivation is a FlowDefinition deploy with <activeVersionNumber>0</activeVersionNumber>,
+        // which this tier already supports — the same run used it successfully twice, once it knew.
+        //
+        // A warning rather than an error: deploying a brand-new flow directly to Obsolete is legal, if
+        // unusual, and the point is to name the mechanism before a wave is spent discovering it.
+        if (edit.typeName === "Flow" && String(md.status) === "Obsolete") {
+            push("LEMMA_FLOW_OBSOLETE_IS_NOT_DEACTIVATION", "warning", `<status>Obsolete</status> on a Flow does not deactivate it. Salesforce versions flows: this deploy adds a new INACTIVE version and leaves the currently-active version running, while reporting Succeeded. ` +
+                `To deactivate ${edit.fullName}, deploy a FlowDefinition instead — fullName ${edit.fullName}, ` +
+                `<activeVersionNumber>0</activeVersionNumber> — and confirm with FlowDefinitionView/Flow IsActive rather than the Flow's own status. ` +
+                `Ignore this only if you genuinely mean to CREATE a new flow that is obsolete from birth.`);
+        }
+        // LEMMA (6.5.1 run, live-caught 2026-07-24): a Create QuickAction burned THREE
+        // checkOnly round-trips on missing required facets ("Required field is missing:
+        // optionsCreateFeedItem", then "[TargetField]"). Object Create/Update actions need
+        // BOTH <targetObject> (the object the action operates on) and <optionsCreateFeedItem>.
+        // Catch it locally so the model authors it right the first time instead of iterating
+        // against the org. Note: an object-SPECIFIC create action (fullName Object.Action)
+        // targeting that same object can still reject; a GLOBAL action (bare fullName) with
+        // <targetObject> is the reliable shape.
+        if (edit.typeName === "QuickAction" && (md.type === "Create" || md.type === "Update")) {
+            const missing = [];
+            if (md.targetObject === undefined)
+                missing.push("targetObject");
+            if (md.optionsCreateFeedItem === undefined)
+                missing.push("optionsCreateFeedItem");
+            // Third required facet, live-caught in the 6.5.4 run one wave AFTER the first two:
+            // "QuickActions of type Create must have a layout".
+            if (md.quickActionLayout === undefined)
+                missing.push("quickActionLayout");
+            if (missing.length > 0) {
+                push("LEMMA_QUICKACTION_CREATE_SHAPE", "error", `QuickAction type=${md.type} is missing required facet(s): ${missing.join(", ")} — checkOnly rejects each of these in turn ("Required field is missing" / "QuickActions of type Create must have a layout"). Needs targetObject (the object the action operates on), optionsCreateFeedItem (true|false), and a quickActionLayout naming the fields; if an object-specific action still rejects on [TargetField], author it as a global action (bare fullName) with targetObject.`);
+            }
+        }
+        // LEMMA (6.5.4 run, live-caught): "Element showRunAssignmentRulesButton invalid at this
+        // location in type Layout" — a family of Layout flags exists only for specific STANDARD
+        // objects (Case/Lead assignment rules, Case solutions/knowledge/submit-and-attach). On a
+        // custom object's layout the whole deploy is rejected. fullName is "Object-Layout Name".
+        if (edit.typeName === "Layout") {
+            const host = edit.fullName.split("-")[0] ?? "";
+            if (/__(c|mdt)$/.test(host)) {
+                const standardOnly = [
+                    "showRunAssignmentRulesButton",
+                    "showSubmitAndAttachButton",
+                    "showSolutionSection",
+                    "showKnowledgeComponent"
+                ].filter((flag) => md[flag] !== undefined);
+                if (standardOnly.length > 0) {
+                    push("LEMMA_LAYOUT_STANDARD_ONLY_FLAG", "error", `Layout on custom object ${host} carries standard-object-only element(s): ${standardOnly.join(", ")} — the platform rejects the whole layout ("invalid at this location in type Layout"). These are Case/Lead facets; drop them unless the requirement asked for one.`);
+                }
+            }
+        }
+        // LEMMA (batch-2 step 7, live-caught): agentic authoring invented design-time
+        // component tokens; runtime_sales:* does not exist in this org family.
+        if (/runtime_sales:/.test(edit.xml)) {
+            push("LEMMA_HALLUCINATED_TOKEN", "warning", "componentName namespace 'runtime_sales:' matches a live-caught hallucination (org truth was console:history / notes:utilityBarNoteList). Ground tokens from a projection of an existing page.");
+        }
+        // LEMMA (CF74/CF76/CF77/CF78, rejected by the org on FOUR consecutive runs before becoming a
+        // rule — the quirk corpus has no automatic feedback from REJECTED_BY_ORG, so this one is
+        // hand-carried): flexipage:recentItems deploys ONLY with an `entityNames`
+        // componentInstanceProperty. CF78's rejection finally named the missing property
+        // ("missing required property [entityNames]"); without it the checkOnly rejects the whole
+        // wave. The proven alternative every prior run shipped is omitting the utility entirely.
+        if (/flexipage:recentItems/.test(edit.xml) && !/entityNames/.test(edit.xml)) {
+            push("LEMMA_RECENTITEMS_ENTITYNAMES", "warning", "flexipage:recentItems without an `entityNames` componentInstanceProperty was REJECTED by the org on four consecutive runs (\"missing required property [entityNames]\"), taking its wave's checkOnly with it. Add <componentInstanceProperties> with name entityNames listing the object API name(s), or omit the utility — every delivered CF-series bar ships History + Notes only.");
+        }
+        // LEMMA (EV-31…40 run, live-caught 2026-08-02): a <description> over 255 characters.
+        //
+        // Three of that run's REJECTED_BY_ORG outcomes were this one class — two ValidationRules and a
+        // PermissionSet — and direct_lint returned CLEAN before every one, so each bought a ~45s
+        // checkOnly round trip and a retry cycle for a fact a string length already knew.
+        //
+        // The identical bound is enforced locally on Campfire's `Blocked_Reason__c`
+        // (MAX_LENGTHS in tools/campfire.ts) for the identical reason: an all-or-nothing write where
+        // one over-long string refuses every row. Same check, other side of the tool.
+        const cappedDescriptions = [];
+        if (DESCRIPTION_CAPPED_TYPES.has(edit.typeName))
+            cappedDescriptions.push({ label: edit.typeName, value: md.description });
+        for (const [container, childType] of Object.entries(DESCRIPTION_CAPPED_CONTAINERS)) {
+            for (const child of asList(md[container])) {
+                cappedDescriptions.push({ label: `${childType} ${String(child.fullName ?? "")}`.trim(), value: child.description });
+            }
+        }
+        for (const { label, value } of cappedDescriptions) {
+            if (typeof value !== "string" || value.length <= DESCRIPTION_MAX)
+                continue;
+            push("LEMMA_DESCRIPTION_TOO_LONG", "error", `<description> on ${label} is ${value.length} characters. The org caps it at ${DESCRIPTION_MAX} and rejects the deploy — a deploy is all-or-nothing, so it takes the whole wave with it. Trim it to ${DESCRIPTION_MAX} characters or fewer and let the requirement carry the long form.`);
+        }
+        // LEMMA (EV-31…40 run, live-caught 2026-08-02): a listView filter on a CHECKBOX field takes the
+        // literals `1` and `0`. `true`/`false` — the spelling every other boolean element in metadata
+        // uses, and so the one an author reaches for — is REJECTED. It cost four list views in one run.
+        //
+        // Nothing local knows whether the field IS a checkbox; that needs the org. So the rule keys on
+        // the LITERAL instead, which is what makes it statically decidable. The one false positive is a
+        // text or picklist field whose value genuinely is the word "true" — that is what the ack is for.
+        const filterSets = [];
+        if (edit.typeName === "ListView")
+            filterSets.push({ view: edit.fullName, filters: md.filters });
+        for (const view of asList(md.listViews))
+            filterSets.push({ view: String(view.fullName ?? edit.fullName), filters: view.filters });
+        for (const { view, filters } of filterSets) {
+            const literals = asList(filters).filter((f) => /^(true|false)$/i.test(String(f.value ?? "")));
+            if (literals.length === 0)
+                continue;
+            push("LEMMA_LISTVIEW_CHECKBOX_LITERAL", "error", `List view ${view} filters on ${literals.map((f) => `${String(f.field ?? "?")}=${String(f.value)}`).join(", ")}. A checkbox filter value must be 1 (checked) or 0 (unchecked) — Salesforce rejects true/false and the deploy is all-or-nothing, so one filter rolls back the wave. Replace true with 1 and false with 0. Ack only if the field is genuinely a text or picklist field whose value is the word itself.`);
+        }
+        // LEMMA (EV-31…40 run, live-caught 2026-08-02): "To mute Delete, first mute Modify All Records".
+        //
+        // In a MutingPermissionSet every <…>true</…> means MUTE this permission, so the platform's
+        // permission dependencies run BACKWARDS from the ones a normal permission set obeys. Modify All
+        // Records grants Delete, so muting Delete alone would leave the user still able to delete
+        // everything — the org refuses the whole deploy rather than land a contradiction.
+        //
+        // Only this ONE edge is a rule, because it is the one a deploy has actually rejected. The same
+        // lattice implies siblings (muting Read would need Edit, Delete, View All and Modify All muted
+        // too), but a guessed list has been the wrong instinct twice in this file already. Extend it
+        // when the org says so, not when the reasoning looks symmetric.
+        if (edit.typeName === "MutingPermissionSet") {
+            for (const op of asList(md.objectPermissions)) {
+                if (String(op.allowDelete) !== "true" || String(op.modifyAllRecords) === "true")
+                    continue;
+                push("LEMMA_MUTING_DELETE_NEEDS_MODIFY_ALL", "error", `<objectPermissions> for ${String(op.object ?? "?")} mutes Delete without muting Modify All Records — the org rejects the deploy: "To mute Delete, first mute Modify All Records". In a muting permission set true means MUTE, and Modify All Records grants Delete, so it has to be muted alongside. Add <modifyAllRecords>true</modifyAllRecords> to the same <objectPermissions>.`);
+            }
+        }
+        // LEMMA — an object-child component, in its own file, with no <fullName>.
+        //
+        // The path names the PARENT object, not the component, so nothing else identifies it. CF76 w4
+        // authored a standalone CompactLayout without one; checkOnly rejected the wave and — a deploy
+        // being all-or-nothing — took every other component in it down too. Its sibling ListView in the
+        // same directory carried one, so the asymmetry was locally visible the whole time.
+        //
+        // The schema tier cannot say this even now that inherited members resolve: @salesforce/types
+        // marks fullName OPTIONAL on all 750 types that declare it, which is correct for a top-level
+        // component (the path names it) and wrong for a child. Optionality cannot express "depends on
+        // where this file sits".
+        if (OBJECT_CHILD_TYPES.has(edit.typeName) && !("fullName" in md)) {
+            // ERROR only where a real deploy has actually rejected it. CompactLayout has that evidence
+            // (CF76 w4, checkOnly, whole wave rolled back). For the others the reasoning is identical —
+            // the path names the parent, not the component — and every field ever deployed from this tool
+            // carried one, but nothing has PROVEN the nameless form fails. Guessing a type list has been
+            // wrong twice already today, so those warn rather than block.
+            push("LEMMA_CHILD_MISSING_FULLNAME", edit.typeName === "CompactLayout" ? "error" : "warning", `${edit.typeName} is an object-child type: its file path names the parent object, not this component, so the body must carry its own <fullName>. Salesforce rejects the deploy, and a deploy is all-or-nothing — this one element takes the whole wave with it.`);
+        }
+        // LEMMA — a nested metadata member with no <fullName>.
+        //
+        // Lives here rather than in the schema tier because the schema CANNOT express it:
+        // @salesforce/types declares `Metadata = { fullName?: string }`, and that same optional marker
+        // flows to every child. Optional is correct for the ROOT, where fullName rides the file path in
+        // source format; it is wrong for a child, which nothing in the path identifies. The types have
+        // no way to distinguish the two, so asserting it there would be inventing a constraint the
+        // artifact does not carry.
+        //
+        // Live origin: CF75 w2 authored a CompactLayout with no <fullName> while its sibling listView
+        // and validationRule happened to carry theirs. Rejected at checkOnly, and because a deploy is
+        // all-or-nothing it rolled back the whole wave for that one element.
+        for (const [container, children] of Object.entries(md)) {
+            if (!CHILD_CONTAINERS.has(container))
+                continue;
+            const list = Array.isArray(children) ? children : [children];
+            const nameless = list.filter((c) => c && typeof c === "object" && !("fullName" in c));
+            if (nameless.length > 0) {
+                push("LEMMA_CHILD_MISSING_FULLNAME", "error", `${nameless.length} <${container}> child(ren) have no <fullName>. A nested member is identified by its own fullName — only the ROOT component takes its name from the file path. Salesforce rejects the whole file, so one nameless child rolls back every component in the wave.`);
+            }
+        }
+        // SCHEMA tier — the official Metadata API definitions, checked locally. Ordered BEFORE the
+        // referential tier because a structurally invalid file cannot have meaningful references.
+        // Enum values, missing-required elements, and MISPLACED elements — all three near-certain.
+        // An element-NAME check is still deliberately absent (a newer org may know elements this
+        // artifact does not), but an element the schema declares ELSEWHERE appearing where it is not
+        // declared is a different, safe claim: it is in the wrong place, and we can name the right one. Live origin: `<type>group</type>` on an approval approver cost a 45s checkOnly AND
+        // rolled back four correct components with it, because a deploy is all-or-nothing.
+        for (const f of checkAgainstSchema(edit.typeName, md)) {
+            push(f.kind === "enum" ? "SCHEMA_ENUM_VALUE" : f.kind === "placement" ? "SCHEMA_ELEMENT_MISPLACED" : "SCHEMA_REQUIRED_MISSING", "warning", `${f.message} (${schemaVersion()})`);
+        }
+        // ORG-ENFORCED tier: elements the schema types as a free string but the org validates against
+        // its own contents (CustomTab.motif, FlexiPage.componentName). Nothing static can check these,
+        // so the check is precedent: a component ALREADY IN THE ORG using this value proves the org
+        // accepts it. A warning, never an error — a value can be legitimately new to this org, and the
+        // point is to make the author confirm rather than to refuse.
+        if (provenValues) {
+            const used = new Map();
+            const scan = (node) => {
+                if (Array.isArray(node))
+                    return void node.forEach(scan);
+                if (!node || typeof node !== "object")
+                    return;
+                for (const [k, v] of Object.entries(node)) {
+                    if (ORG_ENFORCED_ELEMENTS.has(k) && typeof v === "string" && v !== "") {
+                        const set = used.get(k) ?? new Set();
+                        set.add(v);
+                        used.set(k, set);
+                    }
+                    else
+                        scan(v);
+                }
+            };
+            scan(md);
+            for (const [element, values] of used) {
+                const proven = provenValues.get(`${edit.typeName}.${element}`) ?? new Set();
+                const unproven = [...values].filter((v) => !proven.has(v));
+                if (unproven.length === 0)
+                    continue;
+                const precedent = proven.size > 0
+                    ? `Values already proven in this org: ${[...proven].sort().slice(0, 8).join(", ")}${proven.size > 8 ? ", …" : ""}.`
+                    : `No ${edit.typeName} in the projection uses <${element}>, so there is no precedent to compare against — widen the projection to include existing ${edit.typeName} components, or confirm the value another way.`;
+                push("UNPROVEN_ORG_TOKEN", "warning", `<${element}> value(s) not proven in this org: ${unproven.sort().join(", ")}. The Metadata API types this element as a free string, so NOTHING can validate it locally — the org decides, and it rejects an unknown value at deploy, taking the whole wave with it. ${precedent}`);
+            }
+        }
+        // Referential tier: every custom-API token referenced must exist in the projected
+        // slice or be introduced by this batch of edits.
+        //
+        // TWO CLASSIFICATIONS, because one name used to carry two opposite situations (QA round 1,
+        // item 10). A token the PLAN says this batch will create is a dependency that has not landed
+        // yet — real when the creator wave runs later, and exactly what a `dependsOn` edge should have
+        // ordered. Everything residual is a genuine unknown: a typo, a wrong relationship name, or a
+        // real component outside every projection's scope — and only the org can split those last two,
+        // which is the apply loop's verification step, not this function's. Lint stays synchronous and
+        // org-free; it CLASSIFIES, the caller verifies.
+        if (knownCustomTokens) {
+            const unknown = new Set();
+            const pending = new Set();
+            for (const match of edit.xml.match(CUSTOM_TOKEN_RE) ?? []) {
+                const token = match.endsWith("__r") ? `${match.slice(0, -3)}__c` : match;
+                if (knownCustomTokens.has(token) || editedTokens.has(token))
+                    continue;
+                if (plannedTokens?.has(token) || plannedTokens?.has(match))
+                    pending.add(match);
+                else
+                    unknown.add(match);
+            }
+            if (pending.size > 0) {
+                findings.push({
+                    rule: "REF_PENDING_DEPENDENCY",
+                    severity: "warning",
+                    component,
+                    message: `References this batch PLANS to create but the org does not hold yet: ${[...pending].sort().join(", ")}. ` +
+                        "Fine in a rehearsal or when the creator ships in this same wave; in a real deploy that runs first, the org rejects the reference. " +
+                        "Check the creator is in this wave or an earlier one — a later wave means plan.json is missing a dependsOn edge.",
+                    ackable: true,
+                    tokens: [...pending].sort()
+                });
+            }
+            if (unknown.size > 0) {
+                findings.push({
+                    rule: "REF_UNKNOWN",
+                    severity: "warning",
+                    component,
+                    message: `References not found in the projected slice, this edit batch, or the batch plan: ${[...unknown].sort().join(", ")} — widen the projection scope or verify the names.`,
+                    ackable: true,
+                    tokens: [...unknown].sort()
+                });
+            }
+        }
+    }
+    const blocked = findings.some((f) => f.severity === "error" && !(f.ackable && acked.has(f.rule)));
+    return { findings, blocked };
+}