@syntax-syllogism/warden-core 0.2.0

package/lib/provisioning/provisionUserUseCase.js

@@ -0,0 +1,200 @@
+import { runBatches } from '../shared/sfUtils.js';
+import { resolveExistingUsers, usableMatchValue } from '../matching/index.js';
+import { describeUserFields } from '../shared/userFields.js';
+import { assertValidRelatedCatalog } from '../relatedRecords/catalog.js';
+import { applyRelatedPhase } from '../relatedRecords/apply.js';
+import { buildRelatedPlans } from '../relatedRecords/plan.js';
+import { emptyPreflightResult, runRelatedPreflight } from '../relatedRecords/preflight.js';
+import { deriveMyDomain, validateAndCanonicalizeUsers, validateExternalIdFieldForFlag, validatePersonaModes, } from './planner.js';
+import { loadValidatedDefinitions, } from './definitionReader.js';
+import { calculateUserLicenseUsage } from './licenseUsage.js';
+import { resolveReferences } from './referenceResolution.js';
+import { provisioningMessage } from './messages.js';
+import { appendCrossReferenceCandidates, buildUserPlans, identityFromTarget, summarize, toUserResult, } from './userPlan.js';
+import { applySavedPlan, executeBulkUserSaves, markRelatedUnapplied, planDryRunResult } from './userSave.js';
+const provisionDefinitionMessages = {
+    invalidPersonaDefinition: () => provisioningMessage('errorInvalidPersonaDefinition'),
+    personasWithoutDefinition: (userKey) => provisioningMessage('errorPersonasWithoutDefinition', [userKey]),
+    invalidJson: (path, error) => provisioningMessage('errorInvalidJson', [path, error]),
+};
+const addSourceContext = (source, errors) => source ? errors.map((error) => `${source.path}:${source.line} — ${error}`) : errors;
+const USER_PROCESS_CONCURRENCY = 10;
+export const getExistingUsers = async (conn, users, options) => {
+    const requests = users.flatMap((user) => {
+        const field = user.matchField ?? options.defaultExternalIdField;
+        const value = field ? usableMatchValue(user.fields[field]) : null;
+        return field && value !== null
+            ? [{ field, value, fuzzy: field === 'Username' && (user.fuzzyUsername ?? options.defaultFuzzyUsername ?? false) }]
+            : [];
+    });
+    const { existingByField, duplicates } = await resolveExistingUsers(conn, requests, options.fieldMap);
+    return { existingByField, duplicates };
+};
+const message = provisioningMessage;
+const loadAndValidate = async (request, describeCache) => {
+    if (request.usersDoc) {
+        const definitions = await loadValidatedDefinitions(request, new Map(), provisionDefinitionMessages);
+        return { fieldMap: await describeUserFields(request.connection, describeCache), definitions };
+    }
+    const fieldMap = await describeUserFields(request.connection, describeCache);
+    const definitions = await loadValidatedDefinitions(request, fieldMap, provisionDefinitionMessages);
+    return { fieldMap, definitions };
+};
+const validationResultsFor = (validationFailureUsers) => validationFailureUsers.map(({ user, order }) => {
+    const matchedBy = user.matchField ?? null;
+    const matchValue = matchedBy ? usableMatchValue(user.fields[matchedBy]) : null;
+    return {
+        planId: `${order}:${user.inputKey}:${user.personas.join('+')}:validation`,
+        order,
+        key: user.inputKey,
+        ...identityFromTarget(user.fields),
+        personas: user.personas,
+        matchedBy,
+        matchValue,
+        // These users never reached matching, so nothing was matched.
+        matched: false,
+        status: 'failed',
+        actions: [],
+        errors: (user.validationErrors ?? []).map((error) => message(error.code, error.messageArgs)),
+        source: user.source,
+    };
+});
+const assembleResult = (resultsWithOrder, refs, licenseUsage, dryRun) => {
+    const results = resultsWithOrder
+        .sort((a, b) => a.order - b.order)
+        .map((result) => ({
+        key: result.key,
+        id: result.id,
+        userName: result.userName,
+        username: result.username,
+        personas: result.personas,
+        matchedBy: result.matchedBy ?? null,
+        matchValue: result.matchValue,
+        matched: result.matched,
+        status: result.status,
+        actions: result.actions,
+        errors: addSourceContext(result.source, result.errors),
+        ...(result.relatedRecords ? { relatedRecords: result.relatedRecords } : {}),
+    }));
+    const result = {
+        summary: summarize(results, refs.warnings.length + (licenseUsage?.filter((license) => license.shortfall > 0).length ?? 0)),
+        users: results,
+    };
+    if (dryRun) {
+        result.licenses = licenseUsage;
+        result.permissionSetLicenses = { evaluated: false, note: 'not evaluated' };
+    }
+    return result;
+};
+const selectedRelationships = (validUsers) => [
+    ...new Set(validUsers.flatMap(({ user }) => user.related ?? [])),
+];
+const loadRelatedCatalog = (definitions, fieldMap) => definitions.relatedDoc ? assertValidRelatedCatalog(definitions.relatedDoc, fieldMap, message) : undefined;
+export class ProvisionUserUseCase {
+    userProcessConcurrency = USER_PROCESS_CONCURRENCY;
+    async runDryRun(conn, plans, refs, validationResults) {
+        const plannedResults = await runBatches(plans, this.userProcessConcurrency, (plan) => planDryRunResult({ conn, plan, refs }));
+        return validationResults.concat(plannedResults);
+    }
+    async runLive(conn, plans, refs, validationResults) {
+        const invalidResults = plans
+            .filter((plan) => plan.errors.length > 0)
+            .map((plan) => toUserResult(markRelatedUnapplied(plan), 'failed', { includeExistingId: false }));
+        const outcomes = await executeBulkUserSaves(conn, plans);
+        const saveFailures = outcomes
+            .filter((outcome) => !outcome.success)
+            .map((outcome) => toUserResult(markRelatedUnapplied(outcome.plan), 'failed', {
+            errors: appendCrossReferenceCandidates(outcome.errors, outcome.plan.target),
+            includeExistingId: false,
+        }));
+        const savedOutcomes = outcomes.filter((outcome) => outcome.success);
+        // Related records are written between the User save and the per-user post-save work,
+        // as one bulk stage per sObject. `executeBulkUserSaves` above is untouched.
+        const relatedByPlanId = await applyRelatedPhase(conn, savedOutcomes
+            .filter((outcome) => outcome.plan.relatedPlans && outcome.id)
+            .map((outcome) => ({
+            planId: outcome.plan.planId,
+            relatedPlans: outcome.plan.relatedPlans,
+            savedUserId: outcome.id,
+        })), 'after');
+        for (const outcome of savedOutcomes) {
+            const related = relatedByPlanId.get(outcome.plan.planId);
+            if (related) {
+                outcome.plan.relatedResults = related;
+                outcome.plan.errors.push(...related
+                    .filter((result) => result.status === 'failed' && result.error)
+                    .map((result) => result.error));
+            }
+        }
+        const postSaveResults = await runBatches(savedOutcomes, this.userProcessConcurrency, (outcome) => applySavedPlan({ conn, outcome, refs, message }));
+        return validationResults.concat(invalidResults, saveFailures, postSaveResults);
+    }
+    // eslint-disable-next-line @typescript-eslint/member-ordering
+    async execute(request) {
+        const conn = request.connection;
+        // Per-run describe cache: shared by User and every relationship sObject, never module-level.
+        const describeCache = new Map();
+        const { fieldMap, definitions } = await loadAndValidate(request, describeCache);
+        const { usersDoc, personasDoc } = definitions;
+        const personasSupplied = request.personasSupplied ?? definitions.personasSupplied;
+        const personas = personasDoc.personas;
+        validatePersonaModes(personas);
+        validateExternalIdFieldForFlag(request.externalId, fieldMap);
+        const catalog = loadRelatedCatalog(definitions, fieldMap);
+        const users = validateAndCanonicalizeUsers(usersDoc.users, personas, fieldMap, personasSupplied, {
+            catalogSupplied: Boolean(catalog),
+            names: new Set(Object.keys(catalog?.relationships ?? {})),
+        });
+        const myDomain = deriveMyDomain(conn.instanceUrl);
+        const defaultExternalIdField = request.externalId
+            ? fieldMap.get(request.externalId.toLowerCase())?.name
+            : undefined;
+        const userEntries = users.map((user, order) => ({ user, order }));
+        const validationFailureUsers = userEntries.filter(({ user }) => user.validationErrors && user.validationErrors.length > 0);
+        const validUsers = userEntries.filter(({ user }) => !user.validationErrors || user.validationErrors.length === 0);
+        const [refs, existingResolution, preflight] = await Promise.all([
+            resolveReferences(conn, personas, validUsers.map(({ user }) => user)),
+            getExistingUsers(conn, validUsers.map(({ user }) => user), {
+                defaultExternalIdField,
+                defaultFuzzyUsername: request.fuzzyUsername,
+                fieldMap,
+            }),
+            catalog
+                ? runRelatedPreflight({
+                    conn,
+                    catalog,
+                    selected: selectedRelationships(validUsers),
+                    cache: describeCache,
+                    message,
+                })
+                : Promise.resolve(emptyPreflightResult()),
+        ]);
+        // Ineligible relationships join the same warning list, so operators still see exactly
+        // one confirmation and declining exits before any DML.
+        refs.warnings.push(...preflight.warnings);
+        // TODO(wdc-command-use-cases): replace this prompt-shaped callback with plan/apply.
+        if (refs.warnings.length > 0)
+            await request.acknowledgeWarnings?.(refs.warnings);
+        const relatedPlansByOrder = catalog
+            ? await buildRelatedPlans({ conn, users: validUsers, catalog, preflight, userFieldMap: fieldMap, message })
+            : undefined;
+        const plans = buildUserPlans({
+            validUsers,
+            refs,
+            existing: existingResolution,
+            fieldMap,
+            defaultExternalIdField,
+            myDomain,
+            dryRun: request.dryRun,
+            message,
+            relatedPlansByOrder,
+        });
+        const licenseUsage = request.dryRun ? await calculateUserLicenseUsage(conn, plans) : undefined;
+        const validationResults = validationResultsFor(validationFailureUsers);
+        const results = request.dryRun
+            ? await this.runDryRun(conn, plans, refs, validationResults)
+            : await this.runLive(conn, plans, refs, validationResults);
+        return assembleResult(results, refs, licenseUsage, request.dryRun);
+    }
+}
+//# sourceMappingURL=provisionUserUseCase.js.map

package/lib/provisioning/provisionUserUseCase.js.map

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

package/lib/provisioning/referenceResolution.d.ts

@@ -0,0 +1,4 @@
+import type { Connection } from '@salesforce/core';
+import type { ResolvedRefs } from './assignmentPlan.js';
+import { type CanonicalizedUser, type PersonaDefinition } from './planner.js';
+export declare const resolveReferences: (conn: Connection, personas: Record<string, PersonaDefinition>, users: CanonicalizedUser[]) => Promise<ResolvedRefs>;

package/lib/provisioning/referenceResolution.js

@@ -0,0 +1,173 @@
+import { soqlIn } from '../shared/sfUtils.js';
+import { isSalesforceId } from './planner.js';
+import { provisioningMessage } from './messages.js';
+const collectPersonaRefs = (personas) => {
+    const refs = {
+        profiles: new Set(),
+        roles: new Set(),
+        permissionSets: new Set(),
+        permissionSetGroups: new Set(),
+        publicGroups: new Set(),
+        queues: new Set(),
+    };
+    for (const persona of Object.values(personas)) {
+        if (persona.profile)
+            refs.profiles.add(persona.profile);
+        if (persona.role)
+            refs.roles.add(persona.role);
+        for (const value of persona.permissionSets ?? [])
+            refs.permissionSets.add(value);
+        for (const value of persona.permissionSetGroups ?? [])
+            refs.permissionSetGroups.add(value);
+        for (const value of persona.publicGroups ?? [])
+            refs.publicGroups.add(value);
+        for (const value of persona.queues ?? [])
+            refs.queues.add(value);
+    }
+    return refs;
+};
+const addReferenceLabel = (labels, row, apiNameField, labelField, type) => {
+    const apiName = row[apiNameField];
+    const label = labelField ? row[labelField] : apiName;
+    labels[row.Id] = {
+        id: row.Id,
+        ...(apiName ? { apiName } : {}),
+        ...(label ? { label } : {}),
+        type,
+    };
+};
+const resolveByIdOrName = async ({ conn, table, idOrNameRefs, nameField, whereClause, warnings, idPrefixes, labelField, type, labels, }) => {
+    const resolved = new Map();
+    const fields = ['Id', nameField, labelField].filter((field) => Boolean(field));
+    const ids = [...idOrNameRefs].filter((ref) => isSalesforceId(ref) && (!idPrefixes || idPrefixes.includes(ref.slice(0, 3))));
+    const names = [...idOrNameRefs].filter((ref) => !isSalesforceId(ref));
+    if (ids.length > 0) {
+        const where = [`Id IN (${soqlIn(ids)})`, whereClause].filter(Boolean).join(' AND ');
+        const rows = (await conn.query(`SELECT ${fields.join(', ')} FROM ${table} WHERE ${where}`)).records;
+        for (const row of rows) {
+            resolved.set(row.Id, row.Id);
+            addReferenceLabel(labels, row, nameField, labelField, type);
+        }
+    }
+    if (names.length > 0) {
+        const where = [`${nameField} IN (${soqlIn(names)})`, whereClause].filter(Boolean).join(' AND ');
+        const rows = (await conn.query(`SELECT ${fields.join(', ')} FROM ${table} WHERE ${where}`)).records;
+        for (const row of rows) {
+            resolved.set(row[nameField], row.Id);
+            addReferenceLabel(labels, row, nameField, labelField, type);
+        }
+    }
+    for (const ref of idOrNameRefs) {
+        if (!resolved.has(ref))
+            warnings.push(provisioningMessage('warningReferenceMissing', [table, ref]));
+    }
+    return resolved;
+};
+const resolveByRoleRef = async (conn, refs, warnings, labels) => {
+    const resolved = new Map();
+    const ids = [...refs].filter((ref) => isSalesforceId(ref) && ref.startsWith('00E'));
+    const names = [...refs].filter((ref) => !isSalesforceId(ref));
+    if (ids.length > 0) {
+        const rows = (await conn.query(`SELECT Id, DeveloperName, Name FROM UserRole WHERE Id IN (${soqlIn(ids)})`)).records;
+        for (const row of rows) {
+            resolved.set(row.Id, row.Id);
+            addReferenceLabel(labels, row, 'DeveloperName', 'Name', 'UserRole');
+        }
+    }
+    if (names.length > 0) {
+        const rows = (await conn.query(`SELECT Id, DeveloperName, Name FROM UserRole WHERE DeveloperName IN (${soqlIn(names)}) OR Name IN (${soqlIn(names)})`)).records;
+        for (const row of rows) {
+            if (row.DeveloperName && names.includes(row.DeveloperName))
+                resolved.set(row.DeveloperName, row.Id);
+            if (row.Name && names.includes(row.Name))
+                resolved.set(row.Name, row.Id);
+            addReferenceLabel(labels, row, 'DeveloperName', 'Name', 'UserRole');
+        }
+    }
+    for (const ref of refs) {
+        if (!resolved.has(ref))
+            warnings.push(provisioningMessage('warningReferenceMissing', ['UserRole', ref]));
+    }
+    return resolved;
+};
+export const resolveReferences = async (conn, personas, users) => {
+    const warnings = [];
+    const labels = {};
+    const refs = collectPersonaRefs(personas);
+    for (const user of users) {
+        if (user.profileRef)
+            refs.profiles.add(user.profileRef);
+        if (user.roleRef)
+            refs.roles.add(user.roleRef);
+    }
+    const [profilesByRef, rolesByRef, permissionSetIdsByRef, permissionSetGroupIdsByRef, publicGroupIdsByRef, queueIdsByRef,] = await Promise.all([
+        resolveByIdOrName({
+            conn,
+            table: 'Profile',
+            idOrNameRefs: refs.profiles,
+            nameField: 'Name',
+            warnings,
+            idPrefixes: ['00e'],
+            type: 'Profile',
+            labels,
+        }),
+        resolveByRoleRef(conn, refs.roles, warnings, labels),
+        resolveByIdOrName({
+            conn,
+            table: 'PermissionSet',
+            idOrNameRefs: refs.permissionSets,
+            nameField: 'Name',
+            warnings,
+            idPrefixes: ['0PS'],
+            labelField: 'Label',
+            type: 'PermissionSet',
+            labels,
+        }),
+        resolveByIdOrName({
+            conn,
+            table: 'PermissionSetGroup',
+            idOrNameRefs: refs.permissionSetGroups,
+            nameField: 'DeveloperName',
+            warnings,
+            idPrefixes: ['0PG'],
+            labelField: 'MasterLabel',
+            type: 'PermissionSetGroup',
+            labels,
+        }),
+        resolveByIdOrName({
+            conn,
+            table: 'Group',
+            idOrNameRefs: refs.publicGroups,
+            nameField: 'DeveloperName',
+            whereClause: "Type = 'Regular'",
+            warnings,
+            idPrefixes: ['00G'],
+            labelField: 'Name',
+            type: 'PublicGroup',
+            labels,
+        }),
+        resolveByIdOrName({
+            conn,
+            table: 'Group',
+            idOrNameRefs: refs.queues,
+            nameField: 'DeveloperName',
+            whereClause: "Type = 'Queue'",
+            warnings,
+            idPrefixes: ['00G'],
+            labelField: 'Name',
+            type: 'Queue',
+            labels,
+        }),
+    ]);
+    return {
+        profilesByRef,
+        rolesByRef,
+        permissionSetIdsByRef,
+        permissionSetGroupIdsByRef,
+        publicGroupIdsByRef,
+        queueIdsByRef,
+        labels,
+        warnings,
+    };
+};
+//# sourceMappingURL=referenceResolution.js.map

package/lib/provisioning/referenceResolution.js.map

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

package/lib/provisioning/userPlan.d.ts

@@ -0,0 +1,85 @@
+import { type ExistingUser } from '../matching/index.js';
+import type { RelatedRecordPlan, RelatedRecordResult } from '../relatedRecords/types.js';
+import type { CsvRowInfo } from '../shared/csv.js';
+import { type CanonicalizedUser, type PersonaDefinition, type UserFieldMeta } from './planner.js';
+import type { ResolvedRefs } from './assignmentPlan.js';
+type JsonRecord = Record<string, unknown>;
+export type UserPlan = {
+    planId: string;
+    order: number;
+    key: string;
+    personas: string[];
+    effectivePersona: PersonaDefinition;
+    matchedBy: string | null;
+    /** The value looked up under `matchedBy`; null when no lookup was issued under it. */
+    matchValue: string | null;
+    target: JsonRecord;
+    existing?: ExistingUser;
+    actions: string[];
+    errors: string[];
+    source?: CsvRowInfo;
+    /** `after`-phase related-record plans for this user, when `--related-def` is in play. */
+    relatedPlans?: RelatedRecordPlan[];
+    /** Reported related-record outcomes, filled in by the dry-run or live related stage. */
+    relatedResults?: RelatedRecordResult[];
+};
+export type UserResult = {
+    key: string;
+    id?: string;
+    userName?: string;
+    username?: string;
+    personas: string[];
+    matchedBy: string | null;
+    /** The value looked up under `matchedBy`; null when no lookup was issued under it. */
+    matchValue: string | null;
+    /**
+     * Whether an existing user was actually found. `matchedBy` only reports that a match
+     * field was configured, so it cannot stand in for this on a net-new user.
+     */
+    matched: boolean;
+    status: 'created' | 'updated' | 'failed' | 'planned';
+    actions: string[];
+    errors: string[];
+    relatedRecords?: RelatedRecordResult[];
+};
+export type OrderedUserResult = UserResult & {
+    order: number;
+    planId: string;
+    source?: CsvRowInfo;
+};
+export declare const identityFromTarget: (target: JsonRecord, existing?: ExistingUser) => {
+    userName?: string;
+    username?: string;
+};
+export declare const buildTarget: (user: CanonicalizedUser, refs: ResolvedRefs, errors: string[]) => JsonRecord;
+export declare const appendCrossReferenceCandidates: (errors: string[], target: JsonRecord) => string[];
+export declare const buildUserPlans: (options: {
+    validUsers: Array<{
+        user: CanonicalizedUser;
+        order: number;
+    }>;
+    refs: ResolvedRefs;
+    existing: {
+        existingByField: Map<string, Map<string, ExistingUser>>;
+        duplicates: Set<string>;
+    };
+    fieldMap: Map<string, UserFieldMeta>;
+    defaultExternalIdField?: string;
+    myDomain?: string;
+    dryRun: boolean;
+    message?: (key: string, args?: string[]) => string;
+    relatedPlansByOrder?: Map<number, RelatedRecordPlan[]>;
+}) => UserPlan[];
+export declare const toUserResult: (plan: UserPlan, status: UserResult["status"], overrides?: {
+    id?: string;
+    errors?: string[];
+    includeExistingId?: boolean;
+}) => OrderedUserResult;
+export declare const summarize: (results: UserResult[], globalWarningCount: number) => {
+    total: number;
+    created: number;
+    updated: number;
+    failed: number;
+    warnings: number;
+};
+export {};

package/lib/provisioning/userPlan.js

@@ -0,0 +1,162 @@
+import { matchKey, usableMatchValue } from '../matching/index.js';
+import { buildDefaultAlias, buildDefaultUsername, missingRequiredFieldsForInsert, } from './planner.js';
+import { provisioningMessage } from './messages.js';
+export const identityFromTarget = (target, existing) => ({
+    userName: existing?.Name ??
+        (typeof target.Name === 'string'
+            ? target.Name
+            : [target.FirstName, target.LastName]
+                .filter((value) => typeof value === 'string' && value.length > 0)
+                .join(' ') || undefined),
+    username: existing?.Username ?? (typeof target.Username === 'string' ? target.Username : undefined),
+});
+const ensureWritableFields = (target, existing, fieldMap, errors) => {
+    for (const field of Object.keys(target)) {
+        if (field === 'Id')
+            continue;
+        const meta = fieldMap.get(field.toLowerCase());
+        if (!meta)
+            continue;
+        if (existing ? !meta.updateable : !meta.createable) {
+            errors.push(provisioningMessage('errorFieldNotWritable', [field, existing ? 'updateable' : 'createable']));
+        }
+    }
+};
+export const buildTarget = (user, refs, errors) => {
+    const persona = user.effectivePersona;
+    const target = { ...user.fields, IsActive: true };
+    // Profile: user profileRef > user raw ProfileId (already in target) > persona profile
+    if (user.profileRef) {
+        const profileId = refs.profilesByRef.get(user.profileRef);
+        if (!profileId)
+            errors.push(provisioningMessage('errorReferenceRequiredMissing', ['Profile', user.profileRef]));
+        else
+            target.ProfileId = profileId;
+    }
+    else if (!target.ProfileId && persona.profile) {
+        const profileId = refs.profilesByRef.get(persona.profile);
+        if (!profileId)
+            errors.push(provisioningMessage('errorReferenceRequiredMissing', ['Profile', persona.profile]));
+        else
+            target.ProfileId = profileId;
+    }
+    // Role: user roleRef > user raw UserRoleId (already in target) > persona role
+    if (user.roleRef) {
+        const roleId = refs.rolesByRef.get(user.roleRef);
+        if (!roleId)
+            errors.push(provisioningMessage('errorReferenceRequiredMissing', ['UserRole', user.roleRef]));
+        else
+            target.UserRoleId = roleId;
+    }
+    else if (!target.UserRoleId && persona.role) {
+        const roleId = refs.rolesByRef.get(persona.role);
+        if (!roleId)
+            errors.push(provisioningMessage('errorReferenceRequiredMissing', ['UserRole', persona.role]));
+        else
+            target.UserRoleId = roleId;
+    }
+    return target;
+};
+const applyInsertDefaults = (target, myDomain) => {
+    if (!target.Username && myDomain) {
+        const username = buildDefaultUsername(target.Email, myDomain);
+        if (username)
+            target.Username = username;
+    }
+    if (!target.Alias) {
+        const alias = buildDefaultAlias(target.FirstName, target.LastName);
+        if (alias)
+            target.Alias = alias;
+    }
+};
+export const appendCrossReferenceCandidates = (errors, target) => {
+    const hasCrossRefError = errors.some((error) => error.includes('INVALID_CROSS_REFERENCE_KEY'));
+    if (!hasCrossRefError)
+        return errors;
+    const candidateFields = Object.entries(target)
+        .filter(([field]) => field.endsWith('Id') && field !== 'Id')
+        .map(([field, value]) => `${field}=${String(value)}`);
+    if (candidateFields.length === 0)
+        return errors;
+    return errors.concat(provisioningMessage('errorCrossReferenceCandidates', [candidateFields.join(', ')]));
+};
+const resolveExistingUser = (matchedBy, target, existing) => {
+    const matchValue = matchedBy ? target[matchedBy] : undefined;
+    if (!matchedBy || typeof matchValue !== 'string')
+        return { matchValue };
+    return { matchValue, existingUser: existing.existingByField.get(matchedBy)?.get(matchValue) };
+};
+export const buildUserPlans = (options) => {
+    const { validUsers, refs, existing, fieldMap, defaultExternalIdField, myDomain, dryRun, message = provisioningMessage, } = options;
+    return validUsers.map(({ user, order }) => {
+        const effectivePersona = user.effectivePersona;
+        const errors = [];
+        const target = buildTarget(user, refs, errors);
+        const matchedBy = user.matchField ?? defaultExternalIdField ?? null;
+        const { matchValue, existingUser } = resolveExistingUser(matchedBy, target, existing);
+        if (matchedBy && typeof matchValue === 'string' && existing.duplicates.has(matchKey(matchedBy, matchValue))) {
+            errors.push(message('errorDuplicateExternalIdMatch', [matchedBy, matchValue]));
+        }
+        if (!existingUser) {
+            applyInsertDefaults(target, myDomain);
+            const profileIntended = Boolean(user.profileRef) || Boolean(effectivePersona.profile);
+            const missing = missingRequiredFieldsForInsert(target, profileIntended);
+            if (missing.length > 0)
+                errors.push(message('errorMissingRequiredFields', [missing.join(', ')]));
+        }
+        ensureWritableFields(target, existingUser, fieldMap, errors);
+        const actions = [existingUser ? (dryRun ? 'wouldUpdate' : 'updated') : dryRun ? 'wouldCreate' : 'created'];
+        if (!existingUser || existingUser.IsActive !== true)
+            actions.push(dryRun ? 'wouldActivate' : 'activated');
+        const relatedPlans = options.relatedPlansByOrder?.get(order);
+        // A related planning failure (ambiguity, collision, unresolvable source) fails the user
+        // before any DML, which is exactly what a non-empty `errors` list already means here.
+        for (const relatedPlan of relatedPlans ?? [])
+            errors.push(...relatedPlan.errors);
+        return {
+            planId: `${order}:${user.inputKey}:${user.personas.join('+')}`,
+            order,
+            key: user.inputKey,
+            personas: user.personas,
+            effectivePersona,
+            matchedBy,
+            matchValue: usableMatchValue(matchValue),
+            target,
+            existing: existingUser,
+            actions,
+            errors,
+            source: user.source,
+            ...(relatedPlans ? { relatedPlans } : {}),
+        };
+    });
+};
+export const toUserResult = (plan, status, overrides) => ({
+    planId: plan.planId,
+    order: plan.order,
+    key: plan.key,
+    ...identityFromTarget(plan.target, plan.existing),
+    ...(overrides?.id
+        ? { id: overrides.id }
+        : overrides?.includeExistingId === false
+            ? {}
+            : plan.existing
+                ? { id: plan.existing.Id }
+                : {}),
+    personas: plan.personas,
+    matchedBy: plan.matchedBy,
+    matchValue: plan.matchValue,
+    matched: Boolean(plan.existing),
+    status,
+    actions: plan.actions,
+    errors: overrides?.errors ?? plan.errors,
+    ...(plan.relatedResults && plan.relatedResults.length > 0 ? { relatedRecords: plan.relatedResults } : {}),
+    source: plan.source,
+});
+export const summarize = (results, globalWarningCount) => ({
+    total: results.length,
+    created: results.filter((result) => result.status === 'created').length,
+    updated: results.filter((result) => result.status === 'updated').length,
+    failed: results.filter((result) => result.status === 'failed').length,
+    warnings: globalWarningCount,
+});
+//# sourceMappingURL=userPlan.js.map