in2-agent-server 0.20260821.185429

package/dist/orgread/genericSnapshot.js

@@ -0,0 +1,61 @@
+// Generic metadata snapshot — the read path for every type without a dedicated reader.
+// Ported from sf-config-verifier (src/snapshots/customObjectSnapshot.ts).
+import { normalizeCustomFieldMetadata } from "./fieldMetadata.js";
+import { snapshot } from "./snapshotTypes.js";
+// Known boolean keys per typeName (live-caught, EXT-966 customTab gate 2026-06-10): the raw metadata
+// read returns XML leaves as STRINGS ('true'/'false'), so a boolean comparison false-FAILs against
+// an observed "true". Every DEDICATED snapshot coerces its known boolean keys at the read boundary
+// (customFieldSnapshot.asBoolean and friends); this is the generic-family analog.
+//
+// Keyed allowlist — NEVER blanket-coerce. A free-text key (a description, a formula body) can
+// legitimately hold the string 'true', and turning that into a boolean would corrupt a correct
+// read. Extend per typeName as live runs prove new families.
+//
+// The CustomObject row is the same platform quirk that bit buildObjectFacetPayload from the other
+// direction: these facets round-trip as strings, so both the read and the write path have to know.
+const GENERIC_BOOLEAN_KEYS = {
+    CustomTab: ["customObject", "hasSidebar", "mobileReady"],
+    CustomObject: [
+        "enableActivities",
+        "enableBulkApi",
+        "enableFeeds",
+        "enableHistory",
+        "enableReports",
+        "enableSearch",
+        "enableSharing",
+        "enableStreamingApi"
+    ],
+    PermissionSet: ["hasActivationRequired"],
+    ApprovalProcess: ["active", "showApprovalHistory"],
+    // ReportType: `deployed` is a required boolean per the WSDL schema (jsforce
+    // lib/api/metadata/schema.d.ts). DOC-DERIVED, never confirmed against a live org — the family's
+    // first live run must confirm the read shape before this row is trusted.
+    ReportType: ["deployed"]
+};
+function coerceKnownBooleans(typeName, raw) {
+    if (!raw)
+        return raw;
+    const keys = GENERIC_BOOLEAN_KEYS[typeName];
+    if (!keys)
+        return raw;
+    const out = { ...raw };
+    for (const k of keys) {
+        if (out[k] === "true")
+            out[k] = true;
+        else if (out[k] === "false")
+            out[k] = false;
+    }
+    return out;
+}
+export async function readGenericMetadataSnapshot(org, family, typeName, fullName) {
+    // See customFieldSnapshot: an empty reader response is not-found, not a crash.
+    const rows = await org.metadataRead(typeName, [fullName]);
+    const result = rows[0] ?? { typeName, fullName, found: false, errors: ["metadataRead returned no rows"] };
+    const raw = result.found ? result.metadata ?? null : null;
+    // F11: CustomField-backed generic families (picklistDependency / formula / rollupSummary /
+    // lookupRelationship / masterDetailRelationship) must get the same valueSet normalization as the
+    // dedicated customField snapshot, or a correct raw value set false-fails on
+    // `$.metadata.valueSet.values`.
+    const metadata = typeName === "CustomField" ? normalizeCustomFieldMetadata(raw) : coerceKnownBooleans(typeName, raw);
+    return snapshot(family, typeName, fullName, "metadata.read", { metadata }, result.errors);
+}

package/dist/orgread/layoutSnapshot.js

@@ -0,0 +1,151 @@
+// Dedicated Layout snapshot.
+//
+// WHY LAYOUT NEEDS ITS OWN READER
+//
+// SOAP `readMetadata` OMITS related lists from the Layout it returns, and jsforce materializes the
+// absent repeated element as `[]`. So a facet the platform declined to show is indistinguishable
+// from a facet the layout genuinely does not have — and Layout is a MEASURED full-file-replace type
+// (applyLoop PROVEN_REPLACE_TYPES: a 2-field file against a clone of a 99-field layout left ZERO of
+// its 16 related lists). An author reading `relatedLists: []` off the snapshot writes a file that
+// omits them, the deploy deletes them, and Salesforce reports success.
+//
+// LIVE-CAUGHT 2026-08-02, PV corpus Arm A, org 00Dfn00000BFjbBEAT: the projection recorded
+// `metadata.relatedLists: []` for Account-Account Layout while the layout carried
+// TPI_Rail_Inspection__c.Account__c. The supervisor caught it by an independent read and restored
+// it by hand. Nothing in the toolchain would have.
+//
+// MEASURED, same org, same day, all 436 layouts, readMetadata vs `sf project retrieve` (the
+// deploy-symmetric source):
+//   - 12 layouts disagree; 56 related list items silently missing.
+//   - It is NOT all-or-nothing. Account-Account Layout - CSM read 17 of 20, Account-Account Layout
+//     MDO read 23 of 34, Opportunity-Simple Opportunity Layout read 18 of 26. A populated-looking
+//     array is no evidence of a complete one.
+//   - The omissions are not a namespace or an object class: standard lists (RelatedFileList,
+//     RelatedHistoryList, RelatedProcessHistoryList, RelatedContentNoteList,
+//     RelatedEntityHistoryList) were dropped too, and the same list type came back fine on other
+//     layouts. There is no predicate to filter on — which is exactly why the read cannot be trusted
+//     and a second source is the only honest answer.
+//
+// THE SECOND SOURCE, measured the same way: Tooling `SELECT Metadata FROM Layout` matched retrieve
+// on 420/436 layouts with ZERO mismatches. The 16 that did not resolve were an artifact of the
+// census addressing layouts by SDR filename (percent-encoded); by fullName only the three
+// pseudo-object layouts (CaseClose, CaseInteraction, CommunityMemberLayout — no EntityDefinition)
+// fail to resolve, and those fail CLOSED here.
+//
+// The precedent for a Tooling side-probe filling a Metadata API blind spot is already in this
+// codebase: field history tracking is probed the same way on both sides of a deploy, because the
+// Metadata API never returns the facet at all.
+import { readGenericMetadataSnapshot } from "./genericSnapshot.js";
+import { snapshot } from "./snapshotTypes.js";
+/**
+ * Marker prefix for a facet this snapshot could NOT read completely.
+ *
+ * It rides the existing `errors: string[]` rather than adding a field, so every consumer that
+ * already treats a snapshot with errors as untrustworthy (the manifest error count, the direct
+ * tier's fail-closed checks) gets the new case for free, and the persisted snapshot schema does not
+ * move. `incompleteFacetsOf` is the reader.
+ */
+export const INCOMPLETE_FACET_PREFIX = "INCOMPLETE_FACET ";
+/** The facet names an errors array marks as incompletely read. */
+export function incompleteFacetsOf(errors) {
+    const out = [];
+    for (const e of errors ?? []) {
+        if (!e.startsWith(INCOMPLETE_FACET_PREFIX))
+            continue;
+        const rest = e.slice(INCOMPLETE_FACET_PREFIX.length);
+        const facet = rest.slice(0, rest.indexOf(":") === -1 ? rest.length : rest.indexOf(":")).trim();
+        if (facet)
+            out.push(facet);
+    }
+    return out;
+}
+export async function readLayoutSnapshot(org, fullName, rowCache) {
+    const base = await readGenericMetadataSnapshot(org, "layout", "Layout", fullName);
+    const metadata = base.state.metadata;
+    // A layout that does not exist has no facet to be incomplete about, and probing for one would
+    // turn a clean absence into a spurious error.
+    if (!metadata)
+        return base;
+    const errors = [...(base.errors ?? [])];
+    const probe = await readRelatedLists(org, fullName, rowCache);
+    if (probe.ok) {
+        return snapshot("layout", "Layout", fullName, "metadata.read + tooling:Layout.Metadata.relatedLists", { metadata: { ...metadata, relatedLists: probe.relatedLists } }, errors.length > 0 ? errors : undefined);
+    }
+    // DROP the value rather than leave a known-unreliable one in place. Keeping `[]` would let a
+    // reader who ignores the errors array author straight into the deletion this module exists to
+    // prevent; removing the key means the facet is visibly unanswered, which is the truth.
+    const { relatedLists: _unreliable, ...rest } = metadata;
+    errors.push(`${INCOMPLETE_FACET_PREFIX}relatedLists: ${probe.reason}. SOAP readMetadata omits Layout related lists without saying so, ` +
+        `so the value it returned is not evidence of anything and has been dropped from this snapshot. ` +
+        `Read the layout's related lists from retrieved source XML before authoring a replacement.`);
+    return snapshot("layout", "Layout", fullName, "metadata.read", { metadata: rest }, errors);
+}
+async function readRelatedLists(org, fullName, rowCache) {
+    const resolved = await resolveLayoutId(org, fullName, rowCache);
+    if (!resolved.ok)
+        return resolved;
+    try {
+        const res = await org.toolingQuery(`SELECT Metadata FROM Layout WHERE Id = '${resolved.id}'`);
+        const md = res.records[0]?.Metadata;
+        if (!md || typeof md !== "object")
+            return { ok: false, reason: `Tooling returned no Metadata for Layout ${resolved.id}` };
+        const rl = md.relatedLists;
+        // Null is the shape a layout with genuinely no related lists comes back as (observed on every
+        // such layout in the census); a single item collapses to a bare object, as everywhere else in
+        // this API.
+        return { ok: true, relatedLists: Array.isArray(rl) ? rl : rl === null || rl === undefined ? [] : [rl] };
+    }
+    catch (error) {
+        return { ok: false, reason: `Tooling Metadata read failed: ${error instanceof Error ? error.message : String(error)}` };
+    }
+}
+/**
+ * `<Object>-<Label>` to exactly one Tooling Layout Id, or a refusal.
+ *
+ * Matching happens in JS against every layout row for the object rather than in a WHERE clause,
+ * for two reasons: labels carry quotes, ampersands, em dashes and colons that would need SOQL
+ * escaping, and `TableEnumOrId` holds an object Id for custom objects but an API name for standard
+ * ones. `EntityDefinition.QualifiedApiName` addresses both uniformly.
+ *
+ * Ambiguity FAILS rather than picks. Three layouts on Account answer to "Account Layout" in the
+ * reference org (two managed, one ours); returning a managed package's related lists for our layout
+ * would be a worse lie than returning none.
+ */
+async function resolveLayoutId(org, fullName, rowCache) {
+    const dash = fullName.indexOf("-");
+    if (dash <= 0 || dash === fullName.length - 1) {
+        return { ok: false, reason: `"${fullName}" is not <Object>-<Label>, so the layout cannot be addressed` };
+    }
+    const object = fullName.slice(0, dash);
+    const label = fullName.slice(dash + 1);
+    if (!/^[A-Za-z0-9_]+$/.test(object)) {
+        return { ok: false, reason: `"${object}" is not an object API name` };
+    }
+    if (typeof org.toolingQuery !== "function") {
+        return { ok: false, reason: "this reader cannot run Tooling queries" };
+    }
+    let rows = rowCache?.get(object);
+    if (!rows) {
+        try {
+            const res = await org.toolingQuery(`SELECT Id, Name, NamespacePrefix FROM Layout WHERE EntityDefinition.QualifiedApiName = '${object}'`);
+            rows = res.records;
+        }
+        catch (error) {
+            // Not cached: a failure is this call's answer, not a fact about the object, and caching it
+            // would turn one transient error into a whole run's worth of INCOMPLETE facets.
+            return { ok: false, reason: `Tooling layout enumeration for ${object} failed: ${error instanceof Error ? error.message : String(error)}` };
+        }
+        rowCache?.set(object, rows);
+    }
+    // A managed layout's fullName carries its namespace in the LABEL segment (Account-ffbc__Account
+    // Layout), which is exactly how the row reconstructs.
+    const matches = rows.filter((r) => `${r.NamespacePrefix ? `${r.NamespacePrefix}__` : ""}${r.Name}` === label);
+    const id = matches.length === 1 ? matches[0]?.Id : undefined;
+    if (!id) {
+        return {
+            ok: false,
+            reason: `${matches.length} of the ${rows.length} Tooling Layout row(s) on ${object} answer to "${label}"`
+        };
+    }
+    return { ok: true, id };
+}

package/dist/orgread/salesforceOrgReader.js

@@ -0,0 +1,184 @@
+// Live org reader — the read half of the direct tier.
+//
+// Replaces sf-config-verifier's SalesforceOrgReader, which implemented eight methods against the
+// full verifier OrgReader interface. cc-mcp calls three of them: identity() once, toolingQuery()
+// five times (scope enumeration), and metadataRead() via the snapshot readers.
+//
+// The five that are gone were not merely unused — metadataRetrieve() was the only reason
+// ComponentSet, RegistryAccess and SDR's metadataRegistry.json were pulled onto this path, and
+// runApex()/soqlQuery()/describeObject() are write-adjacent or persona-scoped surfaces the direct
+// tier deliberately does not have. describe_object is served by the read-only sf CLI passthrough
+// instead, so nothing regressed by dropping it here.
+//
+// Auth rides the sf CLI's stored auth (Org.create by alias). No tokens pass through this process.
+import { meteredApiCall } from "../core/orgCallMeter.js";
+// The Metadata API's readMetadata() accepts up to TEN fullNames per call. Every snapshot reader
+// asks for exactly one, which is correct but was costing one HTTP round-trip per component: a
+// projection scoped to Account + Contact resolved to ~490 custom fields and therefore ~490
+// sequential SOAP calls, which ran for over five minutes and looked indistinguishable from a hang.
+const READ_BATCH = 10;
+// Concurrent in-flight batches. Deliberately modest: the point is to stop paying full latency 490
+// times over, not to lean on the org. Salesforce applies concurrent-request limits per org, and a
+// projection is a read that runs alongside whatever else the consultant's org is doing.
+const READ_CONCURRENCY = 5;
+export class SalesforceOrgReader {
+    opts;
+    org;
+    conn;
+    // Populated by prefetch(); drained by metadataRead(). Keyed `typeName:fullName`.
+    //
+    // This said "constructed per projection run, so there is no staleness window to reason about".
+    // That was FALSE and it is what made the bug: direct_apply reuses one reader across a
+    // pre-projection, a deploy, and a post-projection. The staleness window was the deploy itself —
+    // the most important moment in the run. runProjection now calls invalidate() on entry, so the
+    // lifetime really is one projection.
+    cache = new Map();
+    constructor(opts) {
+        this.opts = opts;
+    }
+    async connection() {
+        if (!this.conn) {
+            // METERED as an org call, because it is one: `Org.create` reads the auth file, refreshes the
+            // access token if it is stale, and pulls in @salesforce/core's whole dependency chain. On a
+            // slow machine that is the single most expensive moment of a wave, and folding it silently
+            // into whichever read happened to be first would misattribute startup cost to a metadata
+            // read. See core/orgCallMeter.ts on why first-call cost is tracked separately at all.
+            //
+            // Imported lazily: @salesforce/core is heavy and only a live read needs it, so tests and
+            // server startup never pay for (or break on) that dependency chain.
+            await meteredApiCall(async () => {
+                const { Org } = await import("@salesforce/core");
+                if (!this.org)
+                    this.org = await Org.create({ aliasOrUsername: this.opts.alias });
+                this.conn = this.org.getConnection(this.opts.apiVersion);
+            });
+        }
+        return this.conn;
+    }
+    async identity() {
+        const conn = await this.connection();
+        const orgId = typeof conn.getAuthInfoFields === "function" ? conn.getAuthInfoFields().orgId ?? "" : "";
+        const username = typeof conn.getUsername === "function" ? conn.getUsername() : this.opts.alias;
+        return { orgId, username, apiVersion: this.opts.apiVersion };
+    }
+    /**
+     * Drop everything cached. A projection is a POINT-IN-TIME read of the org, so anything held from
+     * an earlier one is a different point in time.
+     *
+     * Without this the cache was actively lying. direct_apply runs a pre-projection and a
+     * post-projection through the SAME reader: the pre-projection cached "not found" for every
+     * component the deploy was about to create, the deploy created them, and the post-projection then
+     * served those cached misses straight back. Every create read back absent, so nearly every wave
+     * returned DELIVERED_WITH_DRIFT on work that had landed perfectly.
+     *
+     * It also explains why waiting longer never helped: the retry re-ran the projection against the
+     * same poisoned cache. The "settle times" that appeared to justify a 47s backoff were the operator
+     * re-running project_org, which builds a FRESH reader — they were never measuring Salesforce.
+     */
+    invalidate() {
+        this.cache.clear();
+    }
+    // Warm the cache for components the caller already knows it will ask for, batched and in parallel.
+    //
+    // Best-effort by design: anything this fails to fetch is simply absent from the cache, and
+    // metadataRead falls through to its normal single read. That keeps prefetch a pure optimization —
+    // it can never turn a projection that would have succeeded into one that fails.
+    //
+    // A poisoned component is the reason for the per-chunk fallback. Salesforce does not return
+    // found:false for orphaned metadata (a component whose parent object was removed by an
+    // uninstalled managed package); it throws a SOAP fault for the whole request. Batched naively,
+    // one such component would take out the nine good ones sharing its chunk and convert a
+    // recoverable per-component error into nine spurious ones. On a chunk failure we re-read its
+    // members individually so the blast radius stays exactly one component, which is the behaviour
+    // the caller's per-component try/catch was already written to expect.
+    async prefetch(requests) {
+        const chunks = [];
+        for (const { typeName, fullNames } of requests) {
+            const pending = fullNames.filter((n) => !this.cache.has(`${typeName}:${n}`));
+            for (let i = 0; i < pending.length; i += READ_BATCH) {
+                chunks.push({ typeName, names: pending.slice(i, i + READ_BATCH) });
+            }
+        }
+        let next = 0;
+        const worker = async () => {
+            for (;;) {
+                const chunk = chunks[next++];
+                if (!chunk)
+                    return;
+                try {
+                    await this.fetchInto(chunk.typeName, chunk.names);
+                }
+                catch {
+                    for (const name of chunk.names) {
+                        try {
+                            await this.fetchInto(chunk.typeName, [name]);
+                        }
+                        catch {
+                            // Leave it uncached. metadataRead will retry it alone and the caller's existing
+                            // error handling will record it as an unreadable component, with its real message.
+                        }
+                    }
+                }
+            }
+        };
+        await Promise.all(Array.from({ length: Math.min(READ_CONCURRENCY, chunks.length) }, worker));
+    }
+    async fetchInto(typeName, fullNames) {
+        for (const row of await this.readUncached(typeName, fullNames)) {
+            this.cache.set(`${typeName}:${row.fullName}`, row);
+        }
+    }
+    async metadataRead(typeName, fullNames) {
+        const misses = fullNames.filter((n) => !this.cache.has(`${typeName}:${n}`));
+        if (misses.length > 0) {
+            // Chunked even here: a caller is free to pass more than the API's per-call limit, and
+            // silently truncating to the first ten would report real components as not-found.
+            for (let i = 0; i < misses.length; i += READ_BATCH) {
+                await this.fetchInto(typeName, misses.slice(i, i + READ_BATCH));
+            }
+        }
+        return fullNames.map((fullName) => this.cache.get(`${typeName}:${fullName}`) ?? {
+            typeName,
+            fullName,
+            found: false,
+            metadata: null,
+            errors: [`${typeName}:${fullName} not found`]
+        });
+    }
+    async readUncached(typeName, fullNames) {
+        const conn = await this.connection();
+        // ONE round-trip per call, whatever the chunk size — this is the unit the meter counts, and it
+        // is where a projection's time actually goes (tens of these per wave against three sf spawns).
+        const result = await meteredApiCall(() => conn.metadata.read(typeName, fullNames));
+        // The Metadata API collapses a single-element response to a bare object rather than an array —
+        // the same shape hazard the snapshot normalizers exist to absorb.
+        const rows = Array.isArray(result) ? result : [result];
+        return fullNames.map((fullName, i) => {
+            const metadata = rows[i];
+            // A read for a missing component still returns an object; absence of fullName is what marks
+            // it as not-found. Treated as not-found rather than an error, so callers can distinguish
+            // "does not exist" from "could not look".
+            const found = Boolean(metadata && typeof metadata === "object" && metadata.fullName !== undefined);
+            return {
+                typeName,
+                fullName,
+                found,
+                metadata: metadata ?? null,
+                errors: found ? undefined : [`${typeName}:${fullName} not found`]
+            };
+        });
+    }
+    async toolingQuery(soql) {
+        const conn = await this.connection();
+        const result = await meteredApiCall(() => conn.tooling.query(soql));
+        return { records: (result.records ?? []) };
+    }
+    // Regular-API SOQL. Exists because the org-trait probes (CurrencyType, RecordType, CallCenter)
+    // and TabDefinition are NOT Tooling objects — routed through tooling.query they fail on every
+    // org and a probe failure is indistinguishable from "feature off".
+    async soqlQuery(soql) {
+        const conn = await this.connection();
+        const result = await meteredApiCall(() => conn.query(soql));
+        return { records: (result.records ?? []) };
+    }
+}

package/dist/orgread/snapshotTypes.js

@@ -0,0 +1,9 @@
+// Snapshot envelope for a single component read out of a live org.
+//
+// Ported from sf-config-verifier (src/snapshots/types.ts). Upstream typed `family` and `source`
+// against @in2/contracts' FamilyKind / EvidenceSurface unions; here they are plain strings, because
+// the direct tier does not consume the contract vocabulary and importing a 3,191-line schema
+// package to narrow two string fields is the trade this port exists to undo.
+export function snapshot(family, typeName, fullName, source, state, errors) {
+    return { family, typeName, fullName, source, state, errors, observedAt: new Date().toISOString() };
+}

package/dist/projection/bridge.js

@@ -0,0 +1,26 @@
+// The org read path. This used to bridge into sf-config-verifier; those modules now live in
+// ../orgread as first-class source (see orgread/fieldMetadata.ts for what that code encodes and
+// where each rule came from). The indirection is kept because call sites already import through it,
+// and it remains the single place the live reader is constructed.
+//
+// The snapshot readers are pure (types + normalization only) — safe to load statically everywhere,
+// including tests.
+export { readCustomFieldSnapshot } from "../orgread/customFieldSnapshot.js";
+export { readGenericMetadataSnapshot } from "../orgread/genericSnapshot.js";
+export { readLayoutSnapshot, incompleteFacetsOf, INCOMPLETE_FACET_PREFIX } from "../orgread/layoutSnapshot.js";
+export { normalizeCustomFieldMetadata, valueSetDefaultValue } from "../orgread/fieldMetadata.js";
+export class OrgReaderUnavailableError extends Error {
+}
+export async function createLiveOrgReader(alias, apiVersion) {
+    // The reader itself is pure; only its @salesforce/core import is heavy, and that is deferred
+    // inside the class so tests and server startup never pay for (or break on) that dependency
+    // chain. Construction stays wrapped so a runtime that cannot load the Salesforce stack (e.g. a
+    // Node too old for undici) produces a clear refusal, never an INTERNAL_ERROR.
+    try {
+        const { SalesforceOrgReader } = await import("../orgread/salesforceOrgReader.js");
+        return new SalesforceOrgReader({ alias, apiVersion });
+    }
+    catch (error) {
+        throw new OrgReaderUnavailableError(`live org reader failed to load (Node ${process.version}): ${error instanceof Error ? error.message : String(error)}`);
+    }
+}

package/dist/projection/diff.js

@@ -0,0 +1,141 @@
+import path from "node:path";
+import { promises as fs } from "node:fs";
+function show(value) {
+    const s = value === undefined ? "(absent)" : JSON.stringify(value);
+    return s.length > 160 ? `${s.slice(0, 160)}…` : s;
+}
+function isPlainObject(v) {
+    return Boolean(v) && typeof v === "object" && !Array.isArray(v);
+}
+// Object KEY ORDER is never semantic in Salesforce metadata: author XML yields one order,
+// the org read-back another (6.5.1 run: GVS customValue {fullName,label,default} vs
+// {fullName,default,label} — identical metadata, false-flagged as drift). Canonicalize keys
+// before serializing so equality and the reorder (orderOnly) check compare by CONTENT.
+export function sortKeysDeep(v) {
+    if (Array.isArray(v))
+        return v.map(sortKeysDeep);
+    if (v && typeof v === "object") {
+        const rec = v;
+        return Object.fromEntries(Object.keys(rec).sort().map((k) => [k, sortKeysDeep(rec[k])]));
+    }
+    return v;
+}
+export const canonJson = (v) => JSON.stringify(sortKeysDeep(v));
+export function diffMetadata(before, after, at = "metadata") {
+    if (isPlainObject(before) && isPlainObject(after)) {
+        const changes = [];
+        for (const key of [...new Set([...Object.keys(before), ...Object.keys(after)])].sort()) {
+            changes.push(...diffMetadata(before[key], after[key], `${at}.${key}`));
+        }
+        return changes;
+    }
+    const b = canonJson(before);
+    const a = canonJson(after);
+    if (b === a)
+        return [];
+    if (Array.isArray(before) && Array.isArray(after) && before.length === after.length) {
+        const multiset = (arr) => arr.map((v) => canonJson(v)).sort().join("\u0000");
+        if (multiset(before) === multiset(after)) {
+            return [{ path: at, before: show(before), after: show(after), orderOnly: true }];
+        }
+    }
+    return [{ path: at, before: show(before), after: show(after) }];
+}
+/**
+ * Child collections that project as separate components (their own diffs cover them).
+ *
+ * One list, two consumers. This module excludes them from the PARENT's diff; the org mirror needs
+ * the same set from the other direction — a wave that delivers only children never refreshes the
+ * parent's mirrored file, so these are exactly the keys whose disagreement the mirror may be able to
+ * attribute to its own recorded history rather than to an outside edit (`orgRepo.computeDrift`).
+ */
+export const CHILD_COLLECTION_NAMES = [
+    "fields",
+    "listViews",
+    "compactLayouts",
+    "validationRules",
+    "recordTypes",
+    "webLinks",
+    "businessProcesses",
+    "fieldSets",
+    "indexes",
+    "sharingReasons"
+];
+const CHILD_COLLECTION_PATH_RE = new RegExp(`^metadata\\.(${CHILD_COLLECTION_NAMES.join("|")})\\b`);
+/** Is this a CustomObject facet path that belongs to a child component's own diff? Shared with the
+ *  unstated-change check, which compares the same embedded read-back and needs the same exclusion —
+ *  otherwise a wave deploying an object plus its fields reports each field twice. */
+export const isChildCollectionPath = (path) => CHILD_COLLECTION_PATH_RE.test(path);
+async function loadManifest(dir) {
+    return JSON.parse(await fs.readFile(path.join(dir, "projection.json"), "utf8"));
+}
+async function loadSnapshot(dir, relFile) {
+    return JSON.parse(await fs.readFile(path.join(dir, relFile), "utf8"));
+}
+export async function diffProjections(baseDir, nextDir) {
+    const base = await loadManifest(baseDir);
+    const next = await loadManifest(nextDir);
+    const baseByKey = new Map(base.components.map((c) => [`${c.typeName}:${c.fullName}`, c]));
+    const nextByKey = new Map(next.components.map((c) => [`${c.typeName}:${c.fullName}`, c]));
+    const diff = {
+        base: `${base.label} (${baseDir})`,
+        next: `${next.label} (${nextDir})`,
+        added: [...nextByKey.keys()].filter((k) => !baseByKey.has(k)).sort(),
+        removed: [...baseByKey.keys()].filter((k) => !nextByKey.has(k)).sort(),
+        changed: []
+    };
+    for (const [key, nextEntry] of [...nextByKey.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+        const baseEntry = baseByKey.get(key);
+        if (!baseEntry)
+            continue;
+        const baseSnap = await loadSnapshot(baseDir, baseEntry.file);
+        const nextSnap = await loadSnapshot(nextDir, nextEntry.file);
+        let changes = diffMetadata(baseSnap.state.metadata, nextSnap.state.metadata);
+        // Stress-caught (case B, 2026-07-22): the CustomObject read-back EMBEDS child
+        // collections (fields, listViews, ...) that the projection also captures as their
+        // own components — a child edit would double-count as a parent-object change and
+        // false-flag a side change. The parent diff covers parent-level facets only.
+        if (key.startsWith("CustomObject:")) {
+            changes = changes.filter((c) => !CHILD_COLLECTION_PATH_RE.test(c.path));
+        }
+        if (changes.length > 0)
+            diff.changed.push({ key, file: nextEntry.file, changes });
+    }
+    return diff;
+}
+export function renderDiff(diff) {
+    const lines = [];
+    lines.push("# Projection Diff");
+    lines.push("");
+    lines.push(`Base: ${diff.base}`);
+    lines.push(`Next: ${diff.next}`);
+    lines.push("");
+    if (diff.added.length === 0 && diff.removed.length === 0 && diff.changed.length === 0) {
+        lines.push("No differences — the projected slice is identical (envelope timestamps ignored).");
+        lines.push("");
+        return lines.join("\n");
+    }
+    if (diff.added.length) {
+        lines.push(`## Added (${diff.added.length})`);
+        for (const k of diff.added)
+            lines.push(`- ${k}`);
+        lines.push("");
+    }
+    if (diff.removed.length) {
+        lines.push(`## Removed (${diff.removed.length})`);
+        for (const k of diff.removed)
+            lines.push(`- ${k}`);
+        lines.push("");
+    }
+    if (diff.changed.length) {
+        lines.push(`## Changed (${diff.changed.length})`);
+        for (const c of diff.changed) {
+            lines.push(`### ${c.key} (${c.file})`);
+            for (const ch of c.changes) {
+                lines.push(`- \`${ch.path}\`: ${ch.before} → ${ch.after}`);
+            }
+            lines.push("");
+        }
+    }
+    return lines.join("\n");
+}