in2-agent-server 0.20260821.185429

package/dist/projection/mapmd.js

@@ -0,0 +1,213 @@
+function asStr(v) {
+    return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+function truncate(v, n) {
+    return v.length > n ? `${v.slice(0, n)}…` : v;
+}
+function fieldFacets(md) {
+    const type = asStr(md.type) ?? "?";
+    const parts = [type];
+    const label = asStr(md.label);
+    if (label)
+        parts[0] = `${type} "${label}"`;
+    if (md.required === true)
+        parts.push("required");
+    if (typeof md.length === "number")
+        parts.push(`length ${md.length}`);
+    if (typeof md.precision === "number" || typeof md.scale === "number") {
+        parts.push(`precision ${md.precision ?? "?"}, scale ${md.scale ?? "?"}`);
+    }
+    const valueSet = md.valueSet;
+    if (valueSet && typeof valueSet === "object") {
+        const values = Array.isArray(valueSet.values) ? valueSet.values.filter((v) => typeof v === "string") : [];
+        if (values.length > 0)
+            parts.push(`values: ${values.join(" | ")}`);
+        if (asStr(valueSet.valueSetName))
+            parts.push(`globalValueSet ${valueSet.valueSetName}`);
+        parts.push(valueSet.restricted === true ? "restricted" : "unrestricted");
+        const controlling = asStr(valueSet.controllingField);
+        if (controlling) {
+            const matrix = Array.isArray(valueSet.valueSettings) ? valueSet.valueSettings.length : 0;
+            parts.push(`DEPENDENT on ${controlling} (${matrix} matrix entries)`);
+        }
+    }
+    if (md.type === "Picklist" || md.type === "MultiselectPicklist") {
+        parts.push(asStr(md.defaultValue) ? `default ${md.defaultValue}` : "no default");
+    }
+    else if (asStr(md.defaultValue)) {
+        parts.push(`default ${md.defaultValue}`);
+    }
+    const formula = asStr(md.formula);
+    if (formula)
+        parts.push(`formula: ${truncate(formula.replace(/\s+/g, " "), 80)}`);
+    if (asStr(md.inlineHelpText))
+        parts.push("help✓");
+    if (asStr(md.referenceTo))
+        parts.push(`→ ${md.referenceTo}`);
+    return parts.join(" — ");
+}
+function objectFacets(md) {
+    const parts = [];
+    if (asStr(md.sharingModel))
+        parts.push(`sharing ${md.sharingModel}`);
+    const flags = [];
+    if (md.enableActivities === true)
+        flags.push("activities");
+    if (md.enableReports === true)
+        flags.push("reports");
+    if (md.enableSearch === true)
+        flags.push("search");
+    if (md.enableHistory === true)
+        flags.push("history");
+    if (flags.length)
+        parts.push(`enabled: ${flags.join(", ")}`);
+    const nameField = md.nameField;
+    if (nameField && typeof nameField === "object") {
+        parts.push(`nameField ${asStr(nameField.type) ?? "?"}${asStr(nameField.label) ? ` "${nameField.label}"` : ""}`);
+    }
+    return parts.join(" | ");
+}
+export function renderMap(manifest, byFile) {
+    const lines = [];
+    lines.push(`# Org Projection — ${manifest.orgAlias} (${manifest.orgId})`);
+    lines.push("");
+    lines.push(`Captured ${manifest.createdAt} · API ${manifest.apiVersion} · ${manifest.counts.components} components · ${manifest.counts.errors} errors · scope ${JSON.stringify(manifest.scope)}`);
+    lines.push("");
+    lines.push("Every line links the canonical JSON snapshot (the same normalized shape the verifier gate reads).");
+    // ORG TRAITS FIRST, because they change what a CORRECT file looks like and nothing in the
+    // component list reveals them. On a multi-currency org every layout carries CurrencyIsoCode, so
+    // an authored Layout that omits it silently drops a field — measured as real loss, and caught on
+    // CF78 only at wave 4's pre-flight, long after the analyzer that wrote the file could act on it.
+    const t = manifest.orgTraits;
+    if (t) {
+        lines.push("");
+        lines.push("## Org traits — these change what correct authoring looks like");
+        lines.push("");
+        lines.push(`- multi-currency: **${t.multiCurrency ? "YES" : "no"}**${t.multiCurrency ? " — every layout carries CurrencyIsoCode; omitting it from an authored Layout DROPS it" : ""}`);
+        lines.push(`- person accounts: **${t.personAccounts ? "YES" : "no"}**`);
+        lines.push(`- call center / CTI: **${t.callCenter ? "YES" : "no"}**${t.callCenter ? "" : " — an 'if available' softphone requirement is NOT available"}`);
+        // Probe caveats and evidence overrides. Without these a reader cannot tell a measured "no"
+        // from a probe that never ran — the distinction that made CF79's trait line untrustworthy.
+        for (const n of t.notes.filter((n) => n.includes("unavailable") || n.includes("evidence"))) {
+            lines.push(`- note: ${n}`);
+        }
+    }
+    // AMBIGUOUS SCOPE NAMES, immediately after the traits and before any component list — because a
+    // reader who takes the snapshot below at face value is reading a component that may not be the one
+    // the scope meant. Live-caught (EV-31…40): `Profile: Admin` in an org holding two profiles that
+    // answer to "Admin", captured silently as though there had been only one.
+    const ambiguities = manifest.scopeAmbiguities ?? [];
+    if (ambiguities.length > 0) {
+        lines.push("");
+        lines.push("## Scope names that did NOT resolve to one component");
+        lines.push("");
+        for (const a of ambiguities) {
+            lines.push(`- \`${a.typeName}: ${a.requestedName}\` — ${a.note}`);
+        }
+    }
+    // Values the org has already accepted for elements no schema can validate. This is what the
+    // UNPROVEN_ORG_TOKEN tier compares against, and printing it here means an analyzer can read the
+    // answer instead of querying for it — the hunt that cost 10 minutes on CF77 and 13 on CF78.
+    const precedentValues = new Map();
+    const harvest = (node, typeName) => {
+        if (Array.isArray(node))
+            return void node.forEach((n) => harvest(n, typeName));
+        if (!node || typeof node !== "object")
+            return;
+        for (const [k, v] of Object.entries(node)) {
+            if ((k === "componentName" || k === "motif") && typeof v === "string" && v) {
+                const key = `${typeName}.${k}`;
+                if (!precedentValues.has(key))
+                    precedentValues.set(key, new Set());
+                precedentValues.get(key).add(v);
+            }
+            else
+                harvest(v, typeName);
+        }
+    };
+    for (const c of manifest.components) {
+        if (!c.found)
+            continue;
+        const snap = byFile.get(c.file);
+        if (snap?.state?.metadata)
+            harvest(snap.state.metadata, c.typeName);
+    }
+    if (precedentValues.size > 0) {
+        lines.push("");
+        lines.push("## Proven in this org — values already accepted for elements no schema can validate");
+        lines.push("");
+        for (const [key, set] of [...precedentValues].sort()) {
+            lines.push(`- \`${key}\`: ${[...set].sort().map((v) => `\`${v}\``).join(", ")}`);
+        }
+        lines.push("");
+        lines.push("A value NOT listed here is unproven — author it only with a stated fallback, and expect `UNPROVEN_ORG_TOKEN`.");
+    }
+    const byKey = new Map(manifest.components.map((c) => [`${c.typeName}:${c.fullName}`, c]));
+    for (const obj of manifest.objects) {
+        const entry = byKey.get(`CustomObject:${obj.objectApiName}`);
+        const snap = entry ? byFile.get(entry.file) : undefined;
+        const md = (snap?.state.metadata ?? null);
+        lines.push("");
+        lines.push(`## ${obj.objectApiName}${md && asStr(md.label) ? ` — "${md.label}"` : ""}`);
+        if (entry)
+            lines.push(`Snapshot: ${entry.file}${entry.found ? "" : " — NOT FOUND"}`);
+        if (md) {
+            const facets = objectFacets(md);
+            if (facets)
+                lines.push(facets);
+        }
+        const fields = manifest.components.filter((c) => c.typeName === "CustomField" && c.fullName.startsWith(`${obj.objectApiName}.`));
+        if (fields.length) {
+            lines.push("");
+            lines.push(`### Custom fields (${fields.length})`);
+            for (const f of fields) {
+                const fieldName = f.fullName.slice(obj.objectApiName.length + 1);
+                const fsnap = byFile.get(f.file);
+                const fmd = (fsnap?.state.metadata ?? null);
+                const facets = fmd ? fieldFacets(fmd) : "READ FAILED";
+                lines.push(`- ${fieldName} — ${facets} → ${f.file}${f.found ? "" : " (NOT FOUND)"}`);
+            }
+        }
+        if (obj.standardFields.length) {
+            lines.push("");
+            lines.push(`### Standard fields (${obj.standardFields.length}, names only)`);
+            lines.push(obj.standardFields.map((s) => `${s.name} (${s.dataType})`).join(", "));
+        }
+        const rules = manifest.components.filter((c) => c.typeName === "ValidationRule" && c.fullName.startsWith(`${obj.objectApiName}.`));
+        if (rules.length) {
+            lines.push("");
+            lines.push(`### Validation rules (${rules.length})`);
+            for (const r of rules) {
+                lines.push(`- ${r.fullName.slice(obj.objectApiName.length + 1)} → ${r.file}${r.found ? "" : " (NOT FOUND)"}`);
+            }
+        }
+        if (obj.layouts.length) {
+            lines.push("");
+            lines.push(`### Layouts (${obj.layouts.length}, names only — project explicitly via components scope when needed)`);
+            for (const l of obj.layouts)
+                lines.push(`- ${l}`);
+        }
+        if (obj.errors.length) {
+            lines.push("");
+            lines.push("### Enumeration errors (fail-closed — these lists may be incomplete)");
+            for (const e of obj.errors)
+                lines.push(`- ${e}`);
+        }
+    }
+    const loose = manifest.components.filter((c) => c.file.startsWith("components/") || c.file.startsWith("components\\"));
+    if (loose.length) {
+        lines.push("");
+        lines.push(`## Other components (${loose.length})`);
+        for (const c of loose) {
+            lines.push(`- ${c.typeName} ${c.fullName} → ${c.file}${c.found ? "" : " (NOT FOUND)"}`);
+        }
+    }
+    if (manifest.enumerationErrors.length) {
+        lines.push("");
+        lines.push("## Scope errors (fail-closed — the projection may be incomplete)");
+        for (const e of manifest.enumerationErrors)
+            lines.push(`- ${e}`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}

package/dist/projection/nameAmbiguity.js

@@ -0,0 +1,106 @@
+// Scope names that resolve to more than one component — the projection's silent choice, made loud.
+//
+// A projection reads what the caller NAMED. For nearly every type that is unambiguous, because the
+// name the caller writes is the name the Metadata API resolves. Profile is the exception, and it
+// cost a run.
+//
+// A Profile has TWO names. Its Metadata API fullName is its API name; `SELECT Name FROM Profile` —
+// which is what `list_components` hands the supervisor — returns its LABEL, and for standard
+// profiles the two differ ("System Administrator" is read as `Admin`). So a CUSTOM profile whose
+// label is "Admin" and the standard profile whose API name is `Admin` are two different components
+// that a scope of `Profile: Admin` cannot tell apart. `metadata.read()` answers with one of them and
+// says nothing about the other, and the projection recorded that answer as though it were the only
+// candidate.
+//
+// Live-caught (EV-31…40, papercut §6): three admin-ish profiles in the org, two answering to
+// "Admin", and the projection carried no hint that a choice had been made at all.
+//
+// PROFILE ONLY, deliberately. Other types have label/API-name splits too (RecordType, Layout), but
+// no run has yet shown one silently mis-resolving here, and inventing candidate enumeration for a
+// type the org has not complained about is how a check like this grows into a liability. A second
+// type earns its place when a run proves it needs one.
+/**
+ * The (API name, label) pair for every profile in the org.
+ *
+ * There is no SOQL route to a profile's API name through the `Profile` object itself — `Profile.Name`
+ * is the label. The profile-owned PermissionSet rows are the documented way round it: for a set with
+ * `IsOwnedByProfile = true`, `PermissionSet.Name` is the owning profile's API name while
+ * `Profile.Name` is its label. (`list_components` already knows the other half of this quirk — it
+ * filters PermissionSet to `IsOwnedByProfile = false` so profile-owned sets do not read as real ones.)
+ *
+ * DOC-DERIVED shape, not yet confirmed against a live org — which is exactly why the whole check is
+ * best-effort. If this query is wrong somewhere, the projection is precisely what it was before.
+ */
+const PROFILE_CANDIDATES_SOQL = "SELECT Name, Profile.Name FROM PermissionSet WHERE IsOwnedByProfile = true";
+const describe = (c) => `\`${c.apiName}\`${c.label ? ` (labelled "${c.label}")` : ""}`;
+async function profileCandidates(reader) {
+    // Regular-API SOQL, like the trait probes: PermissionSet is not a Tooling object, and a reader
+    // without soqlQuery degrades to "not checked" rather than to a fabricated all-clear.
+    const soql = reader.soqlQuery?.bind(reader);
+    if (!soql)
+        return [];
+    const rows = await soql(PROFILE_CANDIDATES_SOQL);
+    return rows.records
+        .map((r) => ({ apiName: String(r.Name ?? ""), label: String(r.Profile?.Name ?? "") }))
+        .filter((c) => c.apiName.length > 0);
+}
+/**
+ * Scope names the org answers to more than once, or answers to by the wrong name.
+ *
+ * Best-effort throughout — an ambiguity note is an improvement on silence, never a precondition for
+ * projecting. A failed enumeration returns nothing and the projection is unchanged.
+ */
+export async function checkScopeNameAmbiguity(reader, components) {
+    const wanted = [...new Set(components.filter((c) => c.typeName === "Profile").map((c) => c.fullName))].sort();
+    if (wanted.length === 0)
+        return [];
+    let candidates;
+    try {
+        candidates = await profileCandidates(reader);
+    }
+    catch {
+        return [];
+    }
+    if (candidates.length === 0)
+        return [];
+    const out = [];
+    for (const requestedName of wanted) {
+        const matched = candidates.filter((c) => c.apiName === requestedName || c.label === requestedName);
+        // Nothing matched: that is plain absence, and the manifest's `found: false` already says it
+        // better than a note could.
+        if (matched.length === 0)
+            continue;
+        const byApiName = matched.filter((c) => c.apiName === requestedName);
+        // Exactly one candidate, matched by the name the read actually resolves on. Nothing to say.
+        if (matched.length === 1 && byApiName.length === 1)
+            continue;
+        const all = matched.map(describe).join(", ");
+        let matchedBy;
+        let note;
+        if (byApiName.length === 1) {
+            const other = matched.filter((c) => c.apiName !== requestedName).map(describe).join(", ");
+            matchedBy = "multiple";
+            note =
+                `${matched.length} profiles in this org answer to "${requestedName}": ${all}. ` +
+                    `A Profile is read by API NAME, so the snapshot is ${describe(byApiName[0])} — ${other} was NOT captured. ` +
+                    `Scope the API name explicitly to project the other one.`;
+        }
+        else if (byApiName.length === 0) {
+            matchedBy = "label";
+            note =
+                `No profile in this org has the API name "${requestedName}" — it is the LABEL of ${all}. ` +
+                    `A Profile is read by API name, so this component reads as absent (or as some unrelated profile). ` +
+                    `Scope it as ${matched.map((c) => `\`${c.apiName}\``).join(" or ")} instead.`;
+        }
+        else {
+            // Two rows carrying the same API name. Which one the org handed back is not recoverable from
+            // the projection, and guessing would be worse than saying so.
+            matchedBy = "multiple";
+            note =
+                `${byApiName.length} profiles in this org share the API name "${requestedName}": ${all}. ` +
+                    `Which one the read returned is NOT determinable from the projection — treat this snapshot as unattributed.`;
+        }
+        out.push({ typeName: "Profile", requestedName, matchedBy, candidates: matched, note });
+    }
+    return out;
+}

package/dist/projection/precedent.js

@@ -0,0 +1,136 @@
+// Precedent and org traits — the two things every analyzer needs and no scope ever contains.
+//
+// WHY THIS IS STRUCTURAL AND NOT A SCOPE OPTION
+//
+// A projection is scoped to what the batch is BUILDING. On greenfield that set is empty by
+// construction, which is exactly when precedent matters most: CF77's baseline held 2 components,
+// both not-found, and CF78's held only the Admin profile. So the org-precedent lint tier
+// (UNPROVEN_ORG_TOKEN) reported "no precedent to compare against" and the analyzers went and did
+// the tool's job by hand — 21 tool calls over 10 minutes on CF77, 37 over 13 minutes on CF78,
+// both hunting for utility-bar component tokens that were sitting in FlexiPages deployed to that
+// same org.
+//
+// It cannot be a `precedentFor` parameter either. That works only when the supervisor remembers to
+// pass it, and scoping to the objects under construction is the natural — and wrong — thing to do.
+// The types that carry org-enforced free-string elements are a CLOSED SET the server already knows,
+// so it collects them unconditionally and the tier cannot be scoped into silence.
+//
+// Cost is bounded and small: a capped sample per type, read through the same batched prefetch as
+// everything else. We only need the VOCABULARY these components use, and a dozen instances carry
+// essentially all of it.
+/** Types carrying elements the ORG validates but no schema can — see ORG_ENFORCED_ELEMENTS. */
+const PRECEDENT_TYPES = [
+    // Utility bars first: componentName is the element that has actually cost time, twice.
+    { typeName: "FlexiPage", soql: "SELECT DeveloperName FROM FlexiPage WHERE Type = 'UtilityBar'", nameField: "DeveloperName" },
+    // Tooling CustomTab, NOT TabDefinition: TabDefinition is (a) a regular-API object, so the
+    // tooling query it used to run here failed on every org and this sweep silently collected
+    // nothing (live-caught CF79 — the only motif precedent in the projection was one the
+    // supervisor scoped by hand), and (b) a context-scoped UI-API view that returns empty for
+    // tabs that demonstrably exist. Tooling CustomTab hides DeveloperName for OBJECT tabs
+    // (returns null), so the filter keeps only named tabs — web/VF/Lightning tabs — which carry
+    // motifs just the same, and motif vocabulary is all this sweep is for.
+    { typeName: "CustomTab", soql: "SELECT DeveloperName FROM CustomTab WHERE DeveloperName != null", nameField: "DeveloperName" }
+];
+// Enough to carry the vocabulary, few enough to stay cheap. CF78's org holds 80 utility bars; the
+// distinct componentName set across the first dozen is the same as across all of them.
+const SAMPLE_PER_TYPE = 12;
+/**
+ * The types this sweep can sample — i.e. the only types whose org-enforced values precedent can ever
+ * prove.
+ *
+ * Exported because "cheap and bounded" turned out to be true per read and false in aggregate: a
+ * `direct_apply` reads its scope TWICE (pre and post), and across the recorded corpus these samples
+ * were 1,296 of 1,977 pre-projection component reads — 66% — against a median of 3 touched
+ * components per wave. A caller that reads its scope twice and knows its wave touches none of these
+ * types can skip the sweep entirely; `runProjection`'s `skipPrecedent` is how, and the lint tier the
+ * sweep feeds keys its lookup on the EDIT'S typeName (`<typeName>.<element>`), so a wave touching no
+ * type in this set could never have found a match here anyway.
+ *
+ * NOT a licence to scope it per-object — see the file header. The closed set is the point.
+ */
+export const PRECEDENT_TYPE_NAMES = new Set(PRECEDENT_TYPES.map((t) => t.typeName));
+/**
+ * Facts about the ORG ITSELF that change what correct authoring looks like, and that no component
+ * read reveals.
+ *
+ * Live cost of not having them: on a multi-currency org every layout carries CurrencyIsoCode, and
+ * an authored Layout that omits it silently drops it — measured as real content loss. CF78 caught
+ * that at wave 4's pre-flight, which is late; the analyzer that wrote the file never knew. Each
+ * probe is a query that FAILS when the feature is off, so failure is the answer, not an error.
+ */
+export async function probeOrgTraits(reader) {
+    const notes = [];
+    // CurrencyType, RecordType and CallCenter are REGULAR-API objects. Routed through toolingQuery
+    // (the original shape) every probe failed on every org, so every trait read "no" forever —
+    // live-caught on CF79, where multi-currency reported "no" beside a field list carrying
+    // CurrencyIsoCode. A reader without soqlQuery gets "unavailable", never a fabricated negative.
+    const soql = reader.soqlQuery?.bind(reader);
+    if (!soql) {
+        notes.push("trait probes unavailable: reader has no regular-API SOQL — traits below are UNKNOWN, not measured; trust concrete evidence (e.g. CurrencyIsoCode in a field list) over these flags");
+        return { multiCurrency: false, personAccounts: false, callCenter: false, notes };
+    }
+    const probe = async (label, q) => {
+        try {
+            await soql(q);
+            return true;
+        }
+        catch {
+            // The sObject does not exist unless the feature is enabled, so this is a NEGATIVE result and
+            // not a failure. Recorded either way so a reader can tell "off" from "never asked".
+            notes.push(`${label}: not enabled (probe query rejected)`);
+            return false;
+        }
+    };
+    const [multiCurrency, personAccounts, callCenter] = await Promise.all([
+        probe("multi-currency", "SELECT Id FROM CurrencyType LIMIT 1"),
+        probe("person accounts", "SELECT Id FROM RecordType WHERE IsPersonType = true LIMIT 1"),
+        probe("call center", "SELECT Id FROM CallCenter LIMIT 1")
+    ]);
+    return { multiCurrency, personAccounts, callCenter, notes };
+}
+/**
+ * Existing components whose values prove what the org accepts.
+ *
+ * Best-effort throughout: precedent is an optimization, so a failed enumeration must never turn a
+ * projection that would have succeeded into one that fails. Anything not collected simply leaves
+ * the tier saying it has no precedent, which is the behaviour we already had.
+ */
+export async function collectPrecedentComponents(reader, alreadyScoped) {
+    const have = new Set(alreadyScoped.map((c) => `${c.typeName}:${c.fullName}`));
+    // Prefer instances from the same NAMING FAMILY as the scoped work before alphabetical fill.
+    // A purely alphabetical sample of CF79's org spent all 12 FlexiPage slots on Accounting/BTS
+    // bars and never picked up CF71–CF78_Operations_Console_UtilityBar — the direct ancestors of
+    // the bar being authored, deployed by prior runs of this very loop. Family = the leading
+    // alpha token of a prefixed name (CF79_… -> CF), so successive batches find their lineage.
+    const families = new Set();
+    for (const c of alreadyScoped) {
+        const m = /^([A-Za-z]+)\d/.exec(c.fullName);
+        if (m)
+            families.add(m[1].toUpperCase());
+    }
+    const inFamily = (n) => {
+        const m = /^([A-Za-z]+)\d/.exec(n);
+        return m ? families.has(m[1].toUpperCase()) : false;
+    };
+    const out = [];
+    for (const { typeName, soql, nameField } of PRECEDENT_TYPES) {
+        try {
+            const rows = await reader.toolingQuery(soql);
+            const names = rows.records
+                .map((r) => String(r[nameField] ?? ""))
+                .filter(Boolean)
+                // Deterministic sample: family instances first, alphabetical inside each half, so two
+                // runs of the same org with the same scope pick the same instances and the manifest
+                // stays comparable across projections.
+                .sort((a, b) => Number(inFamily(b)) - Number(inFamily(a)) || a.localeCompare(b))
+                .filter((n) => !have.has(`${typeName}:${n}`))
+                .slice(0, SAMPLE_PER_TYPE);
+            for (const fullName of names)
+                out.push({ typeName, fullName });
+        }
+        catch {
+            /* enumeration unavailable — no precedent for this type, same as before */
+        }
+    }
+    return out;
+}