@syntax-syllogism/warden-core 0.2.0

package/lib/relatedRecords/plan.js

@@ -0,0 +1,271 @@
+import { esc, soqlIn } from '../shared/sfUtils.js';
+import { resolveSource } from './sources.js';
+import { relatedRecordsMessage } from './messages.js';
+/** Salesforce accepts at most 200 records per create/update request. */
+export const RELATED_DML_CHUNK_SIZE = 200;
+const MATCH_QUERY_CHUNK_SIZE = 200;
+const MATCH_QUERY_MAX_LENGTH = 18_000;
+const matchGroupKey = (sobject, matchField) => `${sobject.toLowerCase()}|${matchField.toLowerCase()}`;
+const matchValueKey = (value, def, preflight) => {
+    const matchField = preflight.fieldsBySobject.get(def.sobject.toLowerCase())?.get(def.match.field.toLowerCase());
+    return matchField?.caseSensitive === false ? value.toLowerCase() : value;
+};
+/**
+ * A value is "empty" only when it is literally null or the empty string. A
+ * whitespace-only value counts as populated and is preserved by `setIfEmpty`.
+ */
+const isEmptyExistingValue = (value) => value === null || value === '';
+const canonicalFieldName = (field, fieldMap) => fieldMap?.get(field.toLowerCase())?.name ?? field;
+/** Split IN-list values at Salesforce's count and query-text limits. */
+const matchQueryBatches = (values, prefix) => {
+    const batches = [];
+    let current = [];
+    let currentLength = prefix.length + 1; // Closing parenthesis.
+    for (const value of values) {
+        const renderedLength = `'${esc(value)}'`.length;
+        const nextLength = currentLength + (current.length > 0 ? 1 : 0) + renderedLength;
+        if (current.length > 0 && (current.length === MATCH_QUERY_CHUNK_SIZE || nextLength > MATCH_QUERY_MAX_LENGTH)) {
+            batches.push(current);
+            current = [];
+            currentLength = prefix.length + 1;
+        }
+        current.push(value);
+        currentLength += (current.length > 1 ? 1 : 0) + renderedLength;
+    }
+    if (current.length > 0)
+        batches.push(current);
+    return batches;
+};
+const toErrorMessage = (message, error) => message(error.code, error.messageArgs);
+const selectFieldsFor = (defs, fieldMap) => {
+    const names = new Set(['Id']);
+    if (fieldMap?.has('recordtypeid'))
+        names.add('RecordTypeId');
+    for (const def of defs) {
+        names.add(canonicalFieldName(def.match.field, fieldMap));
+        for (const field of Object.keys(def.fields))
+            names.add(canonicalFieldName(field, fieldMap));
+    }
+    return [...names];
+};
+const skippedPlan = (relationship, def) => ({
+    relationship,
+    phase: 'after',
+    sobject: def.sobject,
+    matchField: def.match.field,
+    fields: {},
+    pendingUserIdFields: [],
+    mode: def.mode ?? 'setIfEmpty',
+    status: 'skipped',
+    errors: [],
+});
+const failedPlan = (relationship, def, errors) => ({
+    ...skippedPlan(relationship, def),
+    status: 'failed',
+    errors,
+});
+/** Resolve each user's match value; a resolution failure fails that user's plan only. */
+const resolveMatchValues = (options) => {
+    const { users, catalog, preflight, userFieldMap, message } = options;
+    const pending = [];
+    const plansByOrder = new Map();
+    for (const { user, order } of users) {
+        const plans = [];
+        for (const relationship of user.related ?? []) {
+            const def = catalog.relationships[relationship];
+            if (!def)
+                continue;
+            if (!preflight.eligible.has(relationship)) {
+                plans.push(skippedPlan(relationship, def));
+                continue;
+            }
+            const resolved = resolveSource({ from: def.match.from }, { relationship, fieldName: 'match.from', userFields: user.fields, userFieldMap });
+            if (resolved.error) {
+                plans.push(failedPlan(relationship, def, [toErrorMessage(message, resolved.error)]));
+                continue;
+            }
+            const matchValue = String(resolved.value);
+            plans.push({
+                ...skippedPlan(relationship, def),
+                matchField: canonicalFieldName(def.match.field, preflight.fieldsBySobject.get(def.sobject.toLowerCase())),
+                status: 'planned',
+                matchValue,
+            });
+            pending.push({ order, relationship, def, matchValue });
+        }
+        if (plans.length > 0)
+            plansByOrder.set(order, plans);
+    }
+    return { pending, plansByOrder };
+};
+/** One bulk query per (sObject, match field) across the whole batch, never per user. */
+const queryExistingRecords = async (conn, pending, preflight) => {
+    const groups = new Map();
+    for (const entry of pending) {
+        const key = matchGroupKey(entry.def.sobject, entry.def.match.field);
+        const group = groups.get(key) ?? { defs: [], values: new Set() };
+        if (!group.defs.includes(entry.def))
+            group.defs.push(entry.def);
+        group.values.add(entry.matchValue);
+        groups.set(key, group);
+    }
+    // Reads go through conn.query so dry runs never touch conn.sobject(...).
+    const grouped = await Promise.all([...groups].map(async ([key, group]) => {
+        const primaryDef = group.defs[0];
+        const fieldMap = preflight.fieldsBySobject.get(primaryDef.sobject.toLowerCase());
+        const select = selectFieldsFor(group.defs, fieldMap).join(', ');
+        const matchField = canonicalFieldName(primaryDef.match.field, fieldMap);
+        const prefix = `SELECT ${select} FROM ${primaryDef.sobject} WHERE ${matchField} IN (`;
+        const rows = (await Promise.all(matchQueryBatches([...group.values], prefix).map(async (chunk) => (await conn.query(`${prefix}${soqlIn(chunk)})`)).records))).flat();
+        const byValue = new Map();
+        for (const row of rows) {
+            const rowValue = row[matchField];
+            if (rowValue === undefined || rowValue === null)
+                continue;
+            const valueKey = matchValueKey(String(rowValue), primaryDef, preflight);
+            byValue.set(valueKey, (byValue.get(valueKey) ?? []).concat(row));
+        }
+        return [key, byValue];
+    }));
+    return new Map(grouped);
+};
+const applyModeFilter = (fields, existing, mode) => {
+    if (!existing || mode === 'sync')
+        return fields;
+    return Object.fromEntries(Object.entries(fields).filter(([name]) => isEmptyExistingValue(existing[name])));
+};
+/** Check only fields that this individual create or update will actually send. */
+const assertPlannedFieldsWritable = (plan, fieldMap, message) => {
+    const requiredPermission = plan.existingId ? 'updateable' : 'createable';
+    const unavailable = [...Object.keys(plan.fields), ...plan.pendingUserIdFields].filter((field) => {
+        const meta = fieldMap.get(field.toLowerCase());
+        return meta ? !meta[requiredPermission] : false;
+    });
+    if (unavailable.length > 0) {
+        plan.status = 'failed';
+        plan.errors.push(message('errorRelatedFieldsNotWritableForOperation', [plan.sobject, unavailable.join(', '), requiredPermission]));
+    }
+};
+const resolveConfiguredFields = (options) => {
+    const { relationship, def, user, userFieldMap, targetFieldMap, message } = options;
+    const fields = {};
+    const pendingUserIdFields = [];
+    const errors = [];
+    for (const [fieldName, expr] of Object.entries(def.fields)) {
+        const resolved = resolveSource(expr, { relationship, fieldName, userFields: user.fields, userFieldMap });
+        if (resolved.error)
+            errors.push(toErrorMessage(message, resolved.error));
+        else if (resolved.pending)
+            pendingUserIdFields.push(canonicalFieldName(fieldName, targetFieldMap));
+        else
+            fields[canonicalFieldName(fieldName, targetFieldMap)] = resolved.value;
+    }
+    return { fields, pendingUserIdFields, errors };
+};
+const finalizePlan = (options) => {
+    const { plan, def, user, userFieldMap, targetFieldMap, matches, recordTypeId, message } = options;
+    const matchValue = plan.matchValue;
+    if (matches.length > 1) {
+        plan.status = 'failed';
+        plan.errors.push(message('errorAmbiguousRelatedMatch', [plan.relationship, def.sobject, def.match.field, matchValue]));
+        return;
+    }
+    const existing = matches[0];
+    const resolved = resolveConfiguredFields({
+        relationship: plan.relationship,
+        def,
+        user,
+        userFieldMap,
+        targetFieldMap,
+        message,
+    });
+    if (resolved.errors.length > 0) {
+        plan.status = 'failed';
+        plan.errors.push(...resolved.errors);
+        return;
+    }
+    if (existing) {
+        plan.existingId = existing.Id;
+        plan.existingValues = { ...existing };
+        if (recordTypeId && existing.RecordTypeId !== recordTypeId) {
+            plan.status = 'failed';
+            plan.errors.push(message('errorRelatedRecordTypeMismatch', [plan.relationship, def.sobject, def.recordType?.developerName ?? '']));
+            return;
+        }
+    }
+    else if (recordTypeId) {
+        // RecordTypeId is written on create only; warden never retags an existing record.
+        plan.recordTypeId = recordTypeId;
+    }
+    const filtered = applyModeFilter(resolved.fields, existing, plan.mode);
+    // A create always writes the match field, so a re-run can match what this run created.
+    plan.fields = existing
+        ? filtered
+        : { ...filtered, [canonicalFieldName(def.match.field, targetFieldMap)]: matchValue };
+    // `user.Id` fields are filled in after the User save, so they carry the same mode
+    // filtering the resolved fields already went through.
+    plan.pendingUserIdFields =
+        existing && plan.mode === 'setIfEmpty'
+            ? resolved.pendingUserIdFields.filter((name) => isEmptyExistingValue(existing[name]))
+            : resolved.pendingUserIdFields;
+    assertPlannedFieldsWritable(plan, targetFieldMap, message);
+};
+/** Fail every plan that shares a `(relationship, match value)` with another plan. */
+const applyCollisionCheck = (plansByOrder, catalog, preflight, message) => {
+    const byKey = new Map();
+    for (const plans of plansByOrder.values()) {
+        for (const plan of plans) {
+            if (plan.status !== 'planned' || plan.matchValue === undefined)
+                continue;
+            const def = catalog.relationships[plan.relationship];
+            const key = `${plan.relationship} ${matchValueKey(plan.matchValue, def, preflight)}`;
+            byKey.set(key, (byKey.get(key) ?? []).concat(plan));
+        }
+    }
+    for (const colliding of byKey.values()) {
+        if (colliding.length < 2)
+            continue;
+        for (const plan of colliding) {
+            plan.status = 'failed';
+            plan.errors.push(message('errorRelatedMatchCollision', [plan.relationship, plan.matchField, plan.matchValue]));
+        }
+    }
+};
+/**
+ * Build every user's `after`-phase related-record plans for the batch.
+ *
+ * Matching is a read, so this is safe in a dry run; the returned plans carry no DML.
+ */
+export const buildRelatedPlans = async (options) => {
+    const { conn, users, catalog, preflight, userFieldMap, message = relatedRecordsMessage } = options;
+    const { pending, plansByOrder } = resolveMatchValues({ users, catalog, preflight, userFieldMap, message });
+    if (plansByOrder.size === 0)
+        return plansByOrder;
+    const index = await queryExistingRecords(conn, pending, preflight);
+    const usersByOrder = new Map(users.map(({ user, order }) => [order, user]));
+    for (const [order, plans] of plansByOrder) {
+        const user = usersByOrder.get(order);
+        if (!user)
+            continue;
+        for (const plan of plans) {
+            if (plan.status !== 'planned' || plan.matchValue === undefined)
+                continue;
+            const def = catalog.relationships[plan.relationship];
+            const matches = index.get(matchGroupKey(def.sobject, def.match.field))?.get(matchValueKey(plan.matchValue, def, preflight)) ??
+                [];
+            finalizePlan({
+                plan,
+                def,
+                user,
+                userFieldMap,
+                targetFieldMap: preflight.fieldsBySobject.get(def.sobject.toLowerCase()) ?? new Map(),
+                matches,
+                recordTypeId: preflight.recordTypeIdByRelationship.get(plan.relationship),
+                message,
+            });
+        }
+    }
+    applyCollisionCheck(plansByOrder, catalog, preflight, message);
+    return plansByOrder;
+};
+//# sourceMappingURL=plan.js.map

package/lib/relatedRecords/plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.js","sourceRoot":"","sources":["../../src/relatedRecords/plan.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAEnD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAEtD,wEAAwE;AACxE,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,CAAC;AAC1C,MAAM,sBAAsB,GAAG,GAAG,CAAC;AACnC,MAAM,sBAAsB,GAAG,MAAM,CAAC;AAKtC,MAAM,aAAa,GAAG,CAAC,OAAe,EAAE,UAAkB,EAAiB,EAAE,CAC3E,GAAG,OAAO,CAAC,WAAW,EAAE,IAAI,UAAU,CAAC,WAAW,EAAE,EAAE,CAAC;AAEzD,MAAM,aAAa,GAAG,CAAC,KAAa,EAAE,GAAoB,EAAE,SAAiC,EAAU,EAAE;IACvG,MAAM,UAAU,GAAG,SAAS,CAAC,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC;IAChH,OAAO,UAAU,EAAE,aAAa,KAAK,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;AAC3E,CAAC,CAAC;AASF;;;GAGG;AACH,MAAM,oBAAoB,GAAG,CAAC,KAAc,EAAW,EAAE,CAAC,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC;AAEzF,MAAM,kBAAkB,GAAG,CAAC,KAAa,EAAE,QAAgD,EAAU,EAAE,CACrG,QAAQ,EAAE,GAAG,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,EAAE,IAAI,IAAI,KAAK,CAAC;AAEpD,wEAAwE;AACxE,MAAM,iBAAiB,GAAG,CAAC,MAAgB,EAAE,MAAc,EAAc,EAAE;IACzE,MAAM,OAAO,GAAe,EAAE,CAAC;IAC/B,IAAI,OAAO,GAAa,EAAE,CAAC;IAC3B,IAAI,aAAa,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,uBAAuB;IAC9D,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC;QAChD,MAAM,UAAU,GAAG,aAAa,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC;QACjF,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,sBAAsB,IAAI,UAAU,GAAG,sBAAsB,CAAC,EAAE,CAAC;YAC7G,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACtB,OAAO,GAAG,EAAE,CAAC;YACb,aAAa,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;QACpC,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACpB,aAAa,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC;IACjE,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC9C,OAAO,OAAO,CAAC;AACjB,CAAC,CAAC;AAEF,MAAM,cAAc,GAAG,CAAC,OAAuB,EAAE,KAAsB,EAAU,EAAE,CACjF,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;AAEzC,MAAM,eAAe,GAAG,CAAC,IAAuB,EAAE,QAAgD,EAAY,EAAE;IAC9G,MAAM,KAAK,GAAG,IAAI,GAAG,CAAS,CAAC,IAAI,CAAC,CAAC,CAAC;IACtC,IAAI,QAAQ,EAAE,GAAG,CAAC,cAAc,CAAC;QAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAC7D,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,KAAK,CAAC,GAAG,CAAC,kBAAkB,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC;QACzD,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC;YAAE,KAAK,CAAC,GAAG,CAAC,kBAAkB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC;IAC9F,CAAC;IACD,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC;AACpB,CAAC,CAAC;AAEF,MAAM,WAAW,GAAG,CAAC,YAAoB,EAAE,GAAoB,EAAqB,EAAE,CAAC,CAAC;IACtF,YAAY;IACZ,KAAK,EAAE,OAAO;IACd,OAAO,EAAE,GAAG,CAAC,OAAO;IACpB,UAAU,EAAE,GAAG,CAAC,KAAK,CAAC,KAAK;IAC3B,MAAM,EAAE,EAAE;IACV,mBAAmB,EAAE,EAAE;IACvB,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,YAAY;IAC9B,MAAM,EAAE,SAAS;IACjB,MAAM,EAAE,EAAE;CACX,CAAC,CAAC;AAEH,MAAM,UAAU,GAAG,CAAC,YAAoB,EAAE,GAAoB,EAAE,MAAgB,EAAqB,EAAE,CAAC,CAAC;IACvG,GAAG,WAAW,CAAC,YAAY,EAAE,GAAG,CAAC;IACjC,MAAM,EAAE,QAAQ;IAChB,MAAM;CACP,CAAC,CAAC;AAEH,yFAAyF;AACzF,MAAM,kBAAkB,GAAG,CAAC,OAM3B,EAA+E,EAAE;IAChF,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IACrE,MAAM,OAAO,GAAmB,EAAE,CAAC;IACnC,MAAM,YAAY,GAAG,IAAI,GAAG,EAA+B,CAAC;IAC5D,KAAK,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,KAAK,EAAE,CAAC;QACpC,MAAM,KAAK,GAAwB,EAAE,CAAC;QACtC,KAAK,MAAM,YAAY,IAAI,IAAI,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC;YAC9C,MAAM,GAAG,GAAG,OAAO,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC;YAChD,IAAI,CAAC,GAAG;gBAAE,SAAS;YACnB,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC;gBAC1C,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC,CAAC;gBAC3C,SAAS;YACX,CAAC;YACD,MAAM,QAAQ,GAAG,aAAa,CAC5B,EAAE,IAAI,EAAE,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,EACxB,EAAE,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,IAAI,CAAC,MAAM,EAAE,YAAY,EAAE,CACjF,CAAC;YACF,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;gBACnB,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,YAAY,EAAE,GAAG,EAAE,CAAC,cAAc,CAAC,OAAO,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;gBACrF,SAAS;YACX,CAAC;YACD,MAAM,UAAU,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;YAC1C,KAAK,CAAC,IAAI,CAAC;gBACT,GAAG,WAAW,CAAC,YAAY,EAAE,GAAG,CAAC;gBACjC,UAAU,EAAE,kBAAkB,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,SAAS,CAAC,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;gBACzG,MAAM,EAAE,SAAS;gBACjB,UAAU;aACX,CAAC,CAAC;YACH,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,YAAY,EAAE,GAAG,EAAE,UAAU,EAAE,CAAC,CAAC;QACzD,CAAC;QACD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;YAAE,YAAY,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IACvD,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC;AACnC,CAAC,CAAC;AAEF,wFAAwF;AACxF,MAAM,oBAAoB,GAAG,KAAK,EAChC,IAAgB,EAChB,OAAuB,EACvB,SAAiC,EACkC,EAAE;IACrE,MAAM,MAAM,GAAG,IAAI,GAAG,EAAmE,CAAC;IAC1F,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,GAAG,GAAG,aAAa,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACpE,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,GAAG,EAAU,EAAE,CAAC;QACzE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAChE,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QACnC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACzB,CAAC;IACD,yEAAyE;IACzE,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAC/B,CAAC,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE;QACrC,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACjC,MAAM,QAAQ,GAAG,SAAS,CAAC,eAAe,CAAC,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;QACjF,MAAM,MAAM,GAAG,eAAe,CAAC,KAAK,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAChE,MAAM,UAAU,GAAG,kBAAkB,CAAC,UAAU,CAAC,KAAK,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QACxE,MAAM,MAAM,GAAG,UAAU,MAAM,SAAS,UAAU,CAAC,OAAO,UAAU,UAAU,OAAO,CAAC;QACtF,MAAM,IAAI,GAAG,CACX,MAAM,OAAO,CAAC,GAAG,CACf,iBAAiB,CAAC,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,GAAG,CAC9C,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,MAAM,IAAI,CAAC,KAAK,CAAwB,GAAG,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CACjG,CACF,CACF,CAAC,IAAI,EAAE,CAAC;QACT,MAAM,OAAO,GAAG,IAAI,GAAG,EAAmC,CAAC;QAC3D,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,MAAM,QAAQ,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC;YACjC,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,IAAI;gBAAE,SAAS;YAC1D,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC;YACxE,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;QACnE,CAAC;QACD,OAAO,CAAC,GAAG,EAAE,OAAO,CAAU,CAAC;IACjC,CAAC,CAAC,CACH,CAAC;IACF,OAAO,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;AAC1B,CAAC,CAAC;AAEF,MAAM,eAAe,GAAG,CACtB,MAA+B,EAC/B,QAA2C,EAC3C,IAA+B,EACN,EAAE;IAC3B,IAAI,CAAC,QAAQ,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO,MAAM,CAAC;IAChD,OAAO,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,oBAAoB,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AAC7G,CAAC,CAAC;AAEF,kFAAkF;AAClF,MAAM,2BAA2B,GAAG,CAClC,IAAuB,EACvB,QAAoC,EACpC,OAAuB,EACjB,EAAE;IACR,MAAM,kBAAkB,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,YAAY,CAAC;IACzE,MAAM,WAAW,GAAG,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,GAAG,IAAI,CAAC,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE;QAC9F,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC;QAC/C,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IAClD,CAAC,CAAC,CAAC;IACH,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3B,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC;QACvB,IAAI,CAAC,MAAM,CAAC,IAAI,CACd,OAAO,CAAC,2CAA2C,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,kBAAkB,CAAC,CAAC,CACjH,CAAC;IACJ,CAAC;AACH,CAAC,CAAC;AAEF,MAAM,uBAAuB,GAAG,CAAC,OAOhC,EAAwF,EAAE;IACzF,MAAM,EAAE,YAAY,EAAE,GAAG,EAAE,IAAI,EAAE,YAAY,EAAE,cAAc,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IACnF,MAAM,MAAM,GAA4B,EAAE,CAAC;IAC3C,MAAM,mBAAmB,GAAa,EAAE,CAAC;IACzC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3D,MAAM,QAAQ,GAAG,aAAa,CAAC,IAAI,EAAE,EAAE,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,IAAI,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC;QACzG,IAAI,QAAQ,CAAC,KAAK;YAAE,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;aACpE,IAAI,QAAQ,CAAC,OAAO;YAAE,mBAAmB,CAAC,IAAI,CAAC,kBAAkB,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC,CAAC;;YAC9F,MAAM,CAAC,kBAAkB,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC;IAC9E,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,mBAAmB,EAAE,MAAM,EAAE,CAAC;AACjD,CAAC,CAAC;AAEF,MAAM,YAAY,GAAG,CAAC,OASrB,EAAQ,EAAE;IACT,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,YAAY,EAAE,cAAc,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAClG,MAAM,UAAU,GAAG,IAAI,CAAC,UAAoB,CAAC;IAC7C,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC;QACvB,IAAI,CAAC,MAAM,CAAC,IAAI,CACd,OAAO,CAAC,4BAA4B,EAAE,CAAC,IAAI,CAAC,YAAY,EAAE,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC,CACrG,CAAC;QACF,OAAO;IACT,CAAC;IACD,MAAM,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC5B,MAAM,QAAQ,GAAG,uBAAuB,CAAC;QACvC,YAAY,EAAE,IAAI,CAAC,YAAY;QAC/B,GAAG;QACH,IAAI;QACJ,YAAY;QACZ,cAAc;QACd,OAAO;KACR,CAAC,CAAC;IACH,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC/B,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC;QACvB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;QACrC,OAAO;IACT,CAAC;IACD,IAAI,QAAQ,EAAE,CAAC;QACb,IAAI,CAAC,UAAU,GAAG,QAAQ,CAAC,EAAE,CAAC;QAC9B,IAAI,CAAC,cAAc,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAC;QACtC,IAAI,YAAY,IAAI,QAAQ,CAAC,YAAY,KAAK,YAAY,EAAE,CAAC;YAC3D,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC;YACvB,IAAI,CAAC,MAAM,CAAC,IAAI,CACd,OAAO,CAAC,gCAAgC,EAAE,CAAC,IAAI,CAAC,YAAY,EAAE,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,UAAU,EAAE,aAAa,IAAI,EAAE,CAAC,CAAC,CACjH,CAAC;YACF,OAAO;QACT,CAAC;IACH,CAAC;SAAM,IAAI,YAAY,EAAE,CAAC;QACxB,kFAAkF;QAClF,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;IACnC,CAAC;IACD,MAAM,QAAQ,GAAG,eAAe,CAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IACvE,uFAAuF;IACvF,IAAI,CAAC,MAAM,GAAG,QAAQ;QACpB,CAAC,CAAC,QAAQ;QACV,CAAC,CAAC,EAAE,GAAG,QAAQ,EAAE,CAAC,kBAAkB,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,cAAc,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC;IACvF,kFAAkF;IAClF,sDAAsD;IACtD,IAAI,CAAC,mBAAmB;QACtB,QAAQ,IAAI,IAAI,CAAC,IAAI,KAAK,YAAY;YACpC,CAAC,CAAC,QAAQ,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,oBAAoB,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;YACrF,CAAC,CAAC,QAAQ,CAAC,mBAAmB,CAAC;IACnC,2BAA2B,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,CAAC,CAAC;AAC7D,CAAC,CAAC;AAEF,qFAAqF;AACrF,MAAM,mBAAmB,GAAG,CAC1B,YAA8C,EAC9C,OAAuB,EACvB,SAAiC,EACjC,OAAuB,EACjB,EAAE;IACR,MAAM,KAAK,GAAG,IAAI,GAAG,EAA+B,CAAC;IACrD,KAAK,MAAM,KAAK,IAAI,YAAY,CAAC,MAAM,EAAE,EAAE,CAAC;QAC1C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS;gBAAE,SAAS;YACzE,MAAM,GAAG,GAAG,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YACrD,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,YAAY,IAAI,aAAa,CAAC,IAAI,CAAC,UAAU,EAAE,GAAG,EAAE,SAAS,CAAC,EAAE,CAAC;YACrF,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;QACtD,CAAC;IACH,CAAC;IACD,KAAK,MAAM,SAAS,IAAI,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;QACvC,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC;YAAE,SAAS;QACnC,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;YAC7B,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC;YACvB,IAAI,CAAC,MAAM,CAAC,IAAI,CACd,OAAO,CAAC,4BAA4B,EAAE,CAAC,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,UAAoB,CAAC,CAAC,CACvG,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,EAAE,OAOvC,EAA6C,EAAE;IAC9C,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,OAAO,GAAG,qBAAqB,EAAE,GAAG,OAAO,CAAC;IACnG,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,GAAG,kBAAkB,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC,CAAC;IAC3G,IAAI,YAAY,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,YAAY,CAAC;IACjD,MAAM,KAAK,GAAG,MAAM,oBAAoB,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;IACnE,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;IAE5E,KAAK,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,YAAY,EAAE,CAAC;QAC1C,MAAM,IAAI,GAAG,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACrC,IAAI,CAAC,IAAI;YAAE,SAAS;QACpB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS;gBAAE,SAAS;YACzE,MAAM,GAAG,GAAG,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YACrD,MAAM,OAAO,GACX,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,aAAa,CAAC,IAAI,CAAC,UAAU,EAAE,GAAG,EAAE,SAAS,CAAC,CAAC;gBAC3G,EAAE,CAAC;YACL,YAAY,CAAC;gBACX,IAAI;gBACJ,GAAG;gBACH,IAAI;gBACJ,YAAY;gBACZ,cAAc,EAAE,SAAS,CAAC,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,IAAI,IAAI,GAAG,EAAyB;gBAC5G,OAAO;gBACP,YAAY,EAAE,SAAS,CAAC,0BAA0B,CAAC,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC;gBACzE,OAAO;aACR,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,mBAAmB,CAAC,YAAY,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;IAC/D,OAAO,YAAY,CAAC;AACtB,CAAC,CAAC"}

package/lib/relatedRecords/preflight.d.ts

@@ -0,0 +1,29 @@
+import type { Connection } from '@salesforce/core';
+import type { UserFieldMeta } from '../provisioning/planner.js';
+import { type SobjectDescribeCache } from '../shared/userFields.js';
+import type { RelatedCatalog, RelatedMessage } from './types.js';
+export type RelatedPreflightResult = {
+    eligible: Set<string>;
+    ineligible: Map<string, string>;
+    warnings: string[];
+    /** Field metadata for every relationship sObject that could be described. */
+    fieldsBySobject: Map<string, Map<string, UserFieldMeta>>;
+    /** Resolved `RecordTypeId` per relationship name, when the relationship declares one. */
+    recordTypeIdByRelationship: Map<string, string>;
+};
+export declare const emptyPreflightResult: () => RelatedPreflightResult;
+/**
+ * Validate every relationship at least one user selected, once per batch.
+ *
+ * Ineligible relationships become warning lines rather than errors: they flow into the
+ * single `acknowledgeWarnings` confirmation the command already issues, so confirming
+ * skips them, declining exits before any DML, and `--no-prompt`/JSON runs skip
+ * automatically.
+ */
+export declare const runRelatedPreflight: (options: {
+    conn: Connection;
+    catalog: RelatedCatalog;
+    selected: string[];
+    cache: SobjectDescribeCache;
+    message?: RelatedMessage;
+}) => Promise<RelatedPreflightResult>;

package/lib/relatedRecords/preflight.js

@@ -0,0 +1,164 @@
+import { soqlIn } from '../shared/sfUtils.js';
+import { describeSobject } from '../shared/userFields.js';
+import { relatedRecordsMessage } from './messages.js';
+export const emptyPreflightResult = () => ({
+    eligible: new Set(),
+    ineligible: new Map(),
+    warnings: [],
+    fieldsBySobject: new Map(),
+    recordTypeIdByRelationship: new Map(),
+});
+/**
+ * An `Account` relationship must accept either spelling of the record type's owning
+ * sObject.
+ *
+ * Confirmed against a person-accounts-enabled org: `RecordType.SobjectType` reads
+ * `Account` there, not `PersonAccount`, so the extra alias is currently unused. It is
+ * kept because it costs one IN value and guards the other spelling.
+ */
+const sobjectAliases = (sobject) => sobject.toLowerCase() === 'account' ? ['Account', 'PersonAccount'] : [sobject];
+/**
+ * `RecordType.IsPersonType` only exists when the org has person accounts enabled --
+ * selecting it elsewhere fails the whole query with `No such column 'IsPersonType'`,
+ * which would take down record-type resolution for every relationship. So it is only
+ * requested once the Account describe has shown person accounts to be on.
+ */
+const queryRecordTypes = async (conn, requests, personAccountsEnabled) => {
+    if (requests.length === 0)
+        return [];
+    const sobjects = [...new Set(requests.flatMap((request) => sobjectAliases(request.sobject)))];
+    const developerNames = [...new Set(requests.map((request) => request.developerName))];
+    const columns = [
+        'Id',
+        'DeveloperName',
+        'SobjectType',
+        'IsActive',
+        ...(personAccountsEnabled ? ['IsPersonType'] : []),
+    ];
+    const soql = `SELECT ${columns.join(', ')} FROM RecordType ` +
+        `WHERE SobjectType IN (${soqlIn(sobjects)}) AND DeveloperName IN (${soqlIn(developerNames)})`;
+    return (await conn.query(soql)).records;
+};
+/**
+ * `Account.IsPersonAccount` exists only when person accounts are enabled, which makes it
+ * the cheapest reliable signal -- the Account describe is already in hand.
+ */
+const hasPersonAccounts = (described) => described?.fields.has('ispersonaccount') === true;
+const missingFields = (def, fieldMap) => [def.match.field, ...Object.keys(def.fields)].filter((field) => !fieldMap.has(field.toLowerCase()));
+const unwritableFields = (def, fieldMap) => Object.keys(def.fields).filter((field) => {
+    const meta = fieldMap.get(field.toLowerCase());
+    return meta ? !meta.createable && !meta.updateable : false;
+});
+const unreadableFields = (def, fieldMap) => [def.match.field, ...Object.keys(def.fields)].filter((field) => fieldMap.get(field.toLowerCase())?.readable === false);
+const describeOrUndefined = async (conn, sobject, cache) => {
+    try {
+        return await describeSobject(conn, sobject, cache);
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * The REST describe omits `isPersonType` from `recordTypeInfos` -- verified absent at
+ * API v67.0 in a person-accounts-enabled org, for every Account record type including
+ * the person one. Reading it there silently rejects every Account relationship, so the
+ * SOQL `IsPersonType` is the primary source and the describe flag is only a fallback for
+ * describes that do carry it.
+ */
+const isEligiblePersonAccountRecordType = (def, described, id, row) => {
+    if (def.sobject.toLowerCase() !== 'account')
+        return true;
+    const recordType = described.recordTypeInfos.get(id);
+    if (recordType?.available !== true)
+        return false;
+    return row.IsPersonType === true || recordType.isPersonType === true;
+};
+const checkFieldMetadata = (def, fieldMap, message) => {
+    const missing = missingFields(def, fieldMap);
+    if (missing.length > 0)
+        return message('errorRelatedUnknownFields', [def.sobject, missing.join(', ')]);
+    const matchMeta = fieldMap.get(def.match.field.toLowerCase());
+    if (!matchMeta?.filterable || !(matchMeta.externalId === true || matchMeta.unique === true)) {
+        return message('errorRelatedMatchFieldNotUnique', [def.match.field, def.sobject]);
+    }
+    const unreadable = unreadableFields(def, fieldMap);
+    if (unreadable.length > 0)
+        return message('errorRelatedFieldsNotReadable', [def.sobject, unreadable.join(', ')]);
+    const unwritable = unwritableFields(def, fieldMap);
+    if (unwritable.length > 0)
+        return message('errorRelatedFieldsNotWritable', [def.sobject, unwritable.join(', ')]);
+    return undefined;
+};
+/**
+ * Validate every relationship at least one user selected, once per batch.
+ *
+ * Ineligible relationships become warning lines rather than errors: they flow into the
+ * single `acknowledgeWarnings` confirmation the command already issues, so confirming
+ * skips them, declining exits before any DML, and `--no-prompt`/JSON runs skip
+ * automatically.
+ */
+export const runRelatedPreflight = async (options) => {
+    const { conn, catalog, selected, cache, message = relatedRecordsMessage } = options;
+    const result = emptyPreflightResult();
+    const names = [...new Set(selected)].filter((name) => Boolean(catalog.relationships[name]));
+    if (names.length === 0)
+        return result;
+    const describedByName = new Map();
+    for (const name of names) {
+        const def = catalog.relationships[name];
+        // Sequential so the describe cache is shared between relationships on one sObject.
+        // eslint-disable-next-line no-await-in-loop
+        describedByName.set(name, await describeOrUndefined(conn, def.sobject, cache));
+    }
+    const recordTypeRequests = names
+        .filter((name) => catalog.relationships[name].recordType)
+        .map((name) => ({
+        sobject: catalog.relationships[name].sobject,
+        developerName: catalog.relationships[name].recordType.developerName,
+    }));
+    const recordTypeRows = await queryRecordTypes(conn, recordTypeRequests, names.some((name) => catalog.relationships[name].sobject.toLowerCase() === 'account' && hasPersonAccounts(describedByName.get(name))));
+    for (const name of names) {
+        const def = catalog.relationships[name];
+        const described = describedByName.get(name);
+        if (!described) {
+            result.ineligible.set(name, message('errorRelatedSobjectUnavailable', [def.sobject]));
+            continue;
+        }
+        result.fieldsBySobject.set(def.sobject.toLowerCase(), described.fields);
+        if (!described.queryable) {
+            result.ineligible.set(name, message('errorRelatedSobjectNotQueryable', [def.sobject]));
+            continue;
+        }
+        const fieldProblem = checkFieldMetadata(def, described.fields, message);
+        if (fieldProblem) {
+            result.ineligible.set(name, fieldProblem);
+            continue;
+        }
+        if (def.sobject.toLowerCase() === 'account' && !def.recordType) {
+            result.ineligible.set(name, message('errorRelatedPersonAccountRecordTypeRequired', [def.sobject]));
+            continue;
+        }
+        if (def.recordType) {
+            const allowed = new Set(sobjectAliases(def.sobject).map((alias) => alias.toLowerCase()));
+            const row = recordTypeRows.find((candidate) => candidate.DeveloperName === def.recordType.developerName &&
+                allowed.has(String(candidate.SobjectType).toLowerCase()) &&
+                candidate.IsActive !== false);
+            if (!row) {
+                result.ineligible.set(name, message('errorRelatedRecordTypeUnavailable', [def.recordType.developerName, def.sobject]));
+                continue;
+            }
+            if (!isEligiblePersonAccountRecordType(def, described, row.Id, row)) {
+                result.ineligible.set(name, message('errorRelatedRecordTypeUnavailable', [def.recordType.developerName, def.sobject]));
+                continue;
+            }
+            result.recordTypeIdByRelationship.set(name, row.Id);
+        }
+        result.eligible.add(name);
+    }
+    // One aggregated warning line per ineligible relationship, never one per user.
+    for (const [name, reason] of result.ineligible) {
+        result.warnings.push(message('warningRelationshipSkipped', [name, reason]));
+    }
+    return result;
+};
+//# sourceMappingURL=preflight.js.map

package/lib/relatedRecords/preflight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preflight.js","sourceRoot":"","sources":["../../src/relatedRecords/preflight.ts"],"names":[],"mappings":"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"}

package/lib/relatedRecords/sources.d.ts

@@ -0,0 +1,25 @@
+import type { UserFieldMeta, ValidationError } from '../provisioning/planner.js';
+import type { ParsedSource, SourceExpr } from './types.js';
+/** Split a source expression string into the shape the resolver dispatches on. */
+export declare const parseSource: (from: unknown) => ParsedSource;
+export declare const isSourceExpr: (value: unknown) => value is SourceExpr;
+export type SourceContext = {
+    relationship: string;
+    fieldName: string;
+    userFields: Record<string, unknown>;
+    userFieldMap: Map<string, UserFieldMeta>;
+    savedUserId?: string;
+};
+export type SourceResolution = {
+    value?: unknown;
+    /** True when the source is `user.Id` and the User has not been saved yet. */
+    pending?: boolean;
+    error?: ValidationError;
+};
+/**
+ * Resolve one configured field source against a canonicalized user.
+ *
+ * Syntax problems and unknown `User` fields are caught during catalog validation, so
+ * anything reported here is per-user: a known source whose effective value is absent.
+ */
+export declare const resolveSource: (expr: SourceExpr, ctx: SourceContext) => SourceResolution;

package/lib/relatedRecords/sources.js

@@ -0,0 +1,65 @@
+const USER_SOURCE_PREFIX = 'user.';
+const CONTEXT_SOURCE_PREFIX = 'context.';
+/** Split a source expression string into the shape the resolver dispatches on. */
+export const parseSource = (from) => {
+    if (typeof from !== 'string')
+        return { kind: 'invalid' };
+    const trimmed = from.trim();
+    if (trimmed.toLowerCase().startsWith(CONTEXT_SOURCE_PREFIX)) {
+        const name = trimmed.slice(CONTEXT_SOURCE_PREFIX.length);
+        return name.length > 0 ? { kind: 'context', name } : { kind: 'invalid' };
+    }
+    if (!trimmed.toLowerCase().startsWith(USER_SOURCE_PREFIX))
+        return { kind: 'invalid' };
+    const field = trimmed.slice(USER_SOURCE_PREFIX.length);
+    if (field.length === 0 || field.includes('.'))
+        return { kind: 'invalid' };
+    return field.toLowerCase() === 'id' ? { kind: 'userId' } : { kind: 'userField', field };
+};
+export const isSourceExpr = (value) => {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const entry = value;
+    const hasFrom = 'from' in entry;
+    const hasValue = 'value' in entry;
+    return Object.keys(entry).length === 1 && hasFrom !== hasValue;
+};
+/**
+ * A value is "absent" only when it is literally undefined, null, or the empty string.
+ * `0` and `false` are values, not absences, so this must never be written as a falsy test.
+ */
+const isAbsent = (value) => value === undefined || value === null || value === '';
+/**
+ * Resolve one configured field source against a canonicalized user.
+ *
+ * Syntax problems and unknown `User` fields are caught during catalog validation, so
+ * anything reported here is per-user: a known source whose effective value is absent.
+ */
+export const resolveSource = (expr, ctx) => {
+    if ('value' in expr)
+        return { value: expr.value };
+    const parsed = parseSource(expr.from);
+    if (parsed.kind === 'userId') {
+        return ctx.savedUserId ? { value: ctx.savedUserId } : { pending: true };
+    }
+    if (parsed.kind !== 'userField') {
+        return {
+            error: {
+                code: 'errorRelatedInvalidSourceValue',
+                messageArgs: [ctx.relationship, ctx.fieldName, String(expr.from)],
+            },
+        };
+    }
+    const canonical = ctx.userFieldMap.get(parsed.field.toLowerCase())?.name ?? parsed.field;
+    const value = ctx.userFields[canonical];
+    if (isAbsent(value)) {
+        return {
+            error: {
+                code: 'errorRelatedSourceEmpty',
+                messageArgs: [ctx.relationship, ctx.fieldName, canonical],
+            },
+        };
+    }
+    return { value };
+};
+//# sourceMappingURL=sources.js.map

package/lib/relatedRecords/sources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sources.js","sourceRoot":"","sources":["../../src/relatedRecords/sources.ts"],"names":[],"mappings":"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"}

package/lib/relatedRecords/types.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Catalog, plan, and result shapes for `--related-def` relationships.
+ *
+ * `phase` is typed as the full union even though v1 only accepts `'after'`, so
+ * adding `'before'` support later is a validator change rather than a type change.
+ */
+export type { RelatedCatalog, RelationshipDef, RelationshipMode, RelationshipPhase, SourceExpr, } from '../spec/relatedCatalog.js';
+import type { RelationshipMode } from '../spec/relatedCatalog.js';
+/** A source expression parsed into the shape the resolver dispatches on. */
+export type ParsedSource = {
+    kind: 'userId';
+} | {
+    kind: 'userField';
+    field: string;
+} | {
+    kind: 'context';
+    name: string;
+} | {
+    kind: 'invalid';
+};
+export type RelatedRecordPlan = {
+    relationship: string;
+    phase: 'after';
+    sobject: string;
+    matchField: string;
+    matchValue?: string;
+    existingId?: string;
+    existingValues?: Record<string, unknown>;
+    fields: Record<string, unknown>;
+    pendingUserIdFields: string[];
+    recordTypeId?: string;
+    mode: RelationshipMode;
+    status: 'planned' | 'skipped' | 'failed';
+    errors: string[];
+};
+export type RelatedRecordResult = {
+    relationship: string;
+    phase: 'after';
+    sobject: string;
+    recordId?: string;
+    action: 'created' | 'updated' | 'matched' | 'skipped' | 'wouldCreate' | 'wouldUpdate' | 'wouldSkip';
+    status: 'applied' | 'planned' | 'skipped' | 'failed';
+    detail?: string;
+    error?: string;
+};
+export type RelatedMessage = (key: string, args?: string[]) => string;

package/lib/relatedRecords/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map