@open-captable-protocol/canton 0.2.230 → 0.2.232

package/dist/utils/deprecatedFieldNormalization.js

@@ -1,1462 +0,0 @@
-"use strict";
-/**
- * Utilities for normalizing deprecated OCF fields to their current equivalents.
- *
- * OCF schema evolves over time, and some fields are deprecated in favor of new ones.
- * These utilities provide type-safe normalization and verification helpers.
- *
- * @example
- *   ```typescript
- *   import { normalizeSingularToArray, normalizeDeprecatedStockPlanFields } from './deprecatedFieldNormalization';
- *
- *   // Generic singular → array normalization
- *   const stockClassIds = normalizeSingularToArray({
- *     singularValue: data.stock_class_id,
- *     arrayValue: data.stock_class_ids,
- *   });
- *
- *   // Stock plan specific helper
- *   const normalized = normalizeDeprecatedStockPlanFields(inputData);
- *   ```
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.REQUIRED_ARRAY_FIELDS = exports.DEFAULT_INTERNAL_FIELDS = exports.DEFAULT_DEPRECATED_FIELDS = exports.OCF_DEPRECATED_FIELDS = exports.OPTION_GRANT_TYPE_TO_COMPENSATION_TYPE = exports.deprecationWarningConfig = void 0;
-exports.emitDeprecationWarning = emitDeprecationWarning;
-exports.normalizeSingularToArray = normalizeSingularToArray;
-exports.normalizeDeprecatedStockPlanFields = normalizeDeprecatedStockPlanFields;
-exports.normalizeDeprecatedStakeholderFields = normalizeDeprecatedStakeholderFields;
-exports.checkStakeholderDeprecatedFieldUsage = checkStakeholderDeprecatedFieldUsage;
-exports.migrateStakeholderFields = migrateStakeholderFields;
-exports.migrateStakeholderFieldsBatch = migrateStakeholderFieldsBatch;
-exports.convertOptionGrantTypeToCompensationType = convertOptionGrantTypeToCompensationType;
-exports.normalizeDeprecatedEquityCompensationIssuanceFields = normalizeDeprecatedEquityCompensationIssuanceFields;
-exports.checkEquityCompensationIssuanceDeprecatedFieldUsage = checkEquityCompensationIssuanceDeprecatedFieldUsage;
-exports.migrateEquityCompensationIssuanceFields = migrateEquityCompensationIssuanceFields;
-exports.migrateEquityCompensationIssuanceFieldsBatch = migrateEquityCompensationIssuanceFieldsBatch;
-exports.checkStockPlanDeprecatedFieldUsage = checkStockPlanDeprecatedFieldUsage;
-exports.getDeprecatedFieldMappings = getDeprecatedFieldMappings;
-exports.getFieldDeprecation = getFieldDeprecation;
-exports.checkDeprecatedFields = checkDeprecatedFields;
-exports.checkDeprecatedFieldsBatch = checkDeprecatedFieldsBatch;
-exports.checkDeprecatedFieldsForType = checkDeprecatedFieldsForType;
-exports.migrateStockPlanFields = migrateStockPlanFields;
-exports.migrateStockPlanFieldsBatch = migrateStockPlanFieldsBatch;
-exports.generateDeprecationReport = generateDeprecationReport;
-exports.validateDeprecatedFields = validateDeprecatedFields;
-exports.createDeprecatedFieldsValidator = createDeprecatedFieldsValidator;
-exports.assertNoDeprecatedFields = assertNoDeprecatedFields;
-exports.registerDeprecatedFieldMapping = registerDeprecatedFieldMapping;
-exports.getRegisteredObjectTypes = getRegisteredObjectTypes;
-exports.getAllDeprecatedFieldMappings = getAllDeprecatedFieldMappings;
-exports.normalizeDeprecatedOcfFields = normalizeDeprecatedOcfFields;
-exports.hasDeprecationsForEntityType = hasDeprecationsForEntityType;
-exports.registerEntityTypeMapping = registerEntityTypeMapping;
-exports.normalizeOcfObject = normalizeOcfObject;
-exports.areOcfObjectsEquivalent = areOcfObjectsEquivalent;
-exports.compareOcfObjects = compareOcfObjects;
-exports.normalizeRequiredArrayFields = normalizeRequiredArrayFields;
-exports.registerRequiredArrayFields = registerRequiredArrayFields;
-exports.getRequiredArrayFields = getRequiredArrayFields;
-const ocfComparison_1 = require("./ocfComparison");
-Object.defineProperty(exports, "DEFAULT_DEPRECATED_FIELDS", { enumerable: true, get: function () { return ocfComparison_1.DEFAULT_DEPRECATED_FIELDS; } });
-Object.defineProperty(exports, "DEFAULT_INTERNAL_FIELDS", { enumerable: true, get: function () { return ocfComparison_1.DEFAULT_INTERNAL_FIELDS; } });
-const planSecurityAliases_1 = require("./planSecurityAliases");
-/**
- * Global deprecation warning configuration.
- * Can be modified for testing or to customize warning behavior.
- */
-exports.deprecationWarningConfig = {
-    enabled: process.env.NODE_ENV !== 'test',
-    handler: undefined,
-};
-/**
- * Emit a deprecation warning.
- *
- * @param details - Details about the deprecated field usage
- */
-function emitDeprecationWarning(details) {
-    if (!exports.deprecationWarningConfig.enabled) {
-        return;
-    }
-    const message = `[OCF Deprecation] Field '${details.deprecatedField}' is deprecated and was auto-converted to '${details.replacementField}'.` +
-        `${details.context ? ` Context: ${details.context}` : ''}`;
-    if (exports.deprecationWarningConfig.handler) {
-        exports.deprecationWarningConfig.handler(message, details);
-    }
-    else {
-        // eslint-disable-next-line no-console -- Intentional deprecation warning to help developers migrate to current API
-        console.warn(message);
-    }
-}
-/**
- * Normalize a deprecated singular field to an array field.
- *
- * When both singular and array values are provided, the array takes precedence.
- * If the array is empty/undefined but singular has a value, wraps it in an array.
- *
- * @param params - Parameters for the normalization
- * @returns The normalized array value (empty array if both inputs are empty/undefined)
- *
- * @example
- *   ```typescript
- *   // Only deprecated field provided
- *   normalizeSingularToArray({
- *     singularValue: 'class-1',
- *     arrayValue: undefined,
- *   }); // Returns ['class-1']
- *
- *   // Both provided - array takes precedence
- *   normalizeSingularToArray({
- *     singularValue: 'class-1',
- *     arrayValue: ['class-2', 'class-3'],
- *   }); // Returns ['class-2', 'class-3']
- *
- *   // Neither provided
- *   normalizeSingularToArray({
- *     singularValue: undefined,
- *     arrayValue: undefined,
- *   }); // Returns []
- *   ```
- */
-function normalizeSingularToArray(params) {
-    const { singularValue, arrayValue, deprecatedFieldName, replacementFieldName, context } = params;
-    // If array has values, use it (ignoring deprecated singular)
-    if (Array.isArray(arrayValue) && arrayValue.length > 0) {
-        return arrayValue;
-    }
-    // If singular value exists, convert to array and emit warning
-    // Also exclude empty strings to match original truthy-check behavior
-    if (singularValue !== undefined && singularValue !== null && singularValue !== '') {
-        if (deprecatedFieldName && replacementFieldName) {
-            emitDeprecationWarning({
-                deprecatedField: deprecatedFieldName,
-                replacementField: replacementFieldName,
-                deprecatedValue: singularValue,
-                context,
-            });
-        }
-        return [singularValue];
-    }
-    // Neither provided - return empty array
-    return [];
-}
-/**
- * Normalize deprecated stock plan fields.
- *
- * Handles the OCF deprecation of `stock_class_id` (singular) → `stock_class_ids` (array).
- *
- * @param data - Stock plan data that may contain deprecated fields
- * @param context - Optional context for deprecation warnings (e.g., "stockPlan.create")
- * @returns Object containing normalized stock_class_ids and deprecation usage flag
- *
- * @example
- *   ```typescript
- *   // Old format (deprecated)
- *   const result = normalizeDeprecatedStockPlanFields({
- *     stock_class_id: 'sc-1',
- *   });
- *   // Returns { stock_class_ids: ['sc-1'], usedDeprecatedField: true }
- *
- *   // New format
- *   const result = normalizeDeprecatedStockPlanFields({
- *     stock_class_ids: ['sc-1', 'sc-2'],
- *   });
- *   // Returns { stock_class_ids: ['sc-1', 'sc-2'], usedDeprecatedField: false }
- *   ```
- */
-function normalizeDeprecatedStockPlanFields(data, context) {
-    // Also exclude empty strings to match original truthy-check behavior
-    const hasDeprecatedField = data.stock_class_id !== undefined && data.stock_class_id !== null && data.stock_class_id !== '';
-    const hasCurrentField = Array.isArray(data.stock_class_ids) && data.stock_class_ids.length > 0;
-    // Only count as using deprecated field if deprecated is present and current is not
-    const usedDeprecatedField = hasDeprecatedField && !hasCurrentField;
-    // Normalize null to undefined for the generic function, then filter results
-    const singularValue = data.stock_class_id ?? undefined;
-    const arrayValue = data.stock_class_ids ?? undefined;
-    const stock_class_ids = normalizeSingularToArray({
-        singularValue,
-        arrayValue,
-        deprecatedFieldName: 'stock_class_id',
-        replacementFieldName: 'stock_class_ids',
-        context: context ?? 'StockPlan',
-    });
-    return {
-        stock_class_ids,
-        usedDeprecatedField,
-    };
-}
-/**
- * Normalize deprecated stakeholder relationship fields to their canonical form.
- *
- * This helper accepts stakeholder data that may use the legacy singular
- * `current_relationship` field or the newer array-based `current_relationships`
- * field and returns a normalized representation plus metadata about deprecation use.
- *
- * Behavior:
- * - If only `current_relationship` is provided, it is converted to a single-element
- *   `current_relationships` array and `usedDeprecatedField` is set to `true`.
- * - If `current_relationships` is provided and non-empty, it is used as-is and
- *   `usedDeprecatedField` is set to `false`, even if `current_relationship` is
- *   also present.
- * - If neither field is provided, `current_relationships` will be an empty array
- *   and `usedDeprecatedField` will be `false`.
- *
- * The input object is not mutated.
- *
- * @param data - Stakeholder data that may contain either the deprecated
- *   `current_relationship` field, the newer `current_relationships` field, or both.
- * @param context - Optional human-readable context used when emitting deprecation
- *   warnings. Defaults to `"Stakeholder"` when not provided.
- * @returns Normalized stakeholder relationship fields, including
- *   `current_relationships` (always an array) and a `usedDeprecatedField` flag
- *   indicating whether only the deprecated field was relied upon.
- *
- * @example
- * ```typescript
- * const normalized = normalizeDeprecatedStakeholderFields({
- *   current_relationship: 'EMPLOYEE',
- * });
- * normalized.current_relationships; // ['EMPLOYEE']
- * normalized.usedDeprecatedField;   // true
- * ```
- *
- * @example
- * ```typescript
- * const normalized = normalizeDeprecatedStakeholderFields({
- *   current_relationship: 'ADVISOR',
- *   current_relationships: ['FOUNDER', 'DIRECTOR'],
- * });
- * // The array field takes precedence when both are present.
- * normalized.current_relationships; // ['FOUNDER', 'DIRECTOR']
- * normalized.usedDeprecatedField;   // false
- * ```
- */
-function normalizeDeprecatedStakeholderFields(data, context) {
-    const hasDeprecatedField = data.current_relationship !== undefined && data.current_relationship !== null && data.current_relationship !== '';
-    const hasCurrentField = Array.isArray(data.current_relationships) && data.current_relationships.length > 0;
-    const usedDeprecatedField = hasDeprecatedField && !hasCurrentField;
-    const singularValue = data.current_relationship ?? undefined;
-    const arrayValue = data.current_relationships ?? undefined;
-    const current_relationships = normalizeSingularToArray({
-        singularValue,
-        arrayValue,
-        deprecatedFieldName: 'current_relationship',
-        replacementFieldName: 'current_relationships',
-        context: context ?? 'Stakeholder',
-    });
-    return { current_relationships, usedDeprecatedField };
-}
-/**
- * Check stakeholder data for deprecated field usage without modifying the data.
- */
-function checkStakeholderDeprecatedFieldUsage(data) {
-    const deprecatedFieldsUsed = [];
-    if (data.current_relationship !== undefined &&
-        data.current_relationship !== null &&
-        data.current_relationship !== '') {
-        deprecatedFieldsUsed.push('current_relationship');
-    }
-    return { hasDeprecatedFields: deprecatedFieldsUsed.length > 0, deprecatedFieldsUsed };
-}
-/**
- * Migrate deprecated stakeholder fields to their current equivalents.
- */
-function migrateStakeholderFields(data) {
-    const warnings = [];
-    const migratedFields = [];
-    const hasDeprecatedField = data.current_relationship !== undefined && data.current_relationship !== null && data.current_relationship !== '';
-    const hasCurrentField = Array.isArray(data.current_relationships) && data.current_relationships.length > 0;
-    if (hasDeprecatedField && hasCurrentField) {
-        warnings.push(`Both 'current_relationship' (deprecated) and 'current_relationships' are present. Using 'current_relationships' value.`);
-    }
-    const { current_relationships, usedDeprecatedField } = normalizeDeprecatedStakeholderFields(data);
-    if (usedDeprecatedField)
-        migratedFields.push('current_relationship');
-    const { current_relationship: _removed, ...rest } = data;
-    return {
-        data: { ...rest, current_relationships },
-        migrated: migratedFields.length > 0,
-        migratedFields,
-        warnings,
-    };
-}
-/**
- * Migrate deprecated fields in multiple stakeholder objects.
- */
-function migrateStakeholderFieldsBatch(items) {
-    const migratedFieldsSummary = {};
-    let itemsMigrated = 0;
-    let itemsWithWarnings = 0;
-    const migratedItems = items.map((item) => {
-        const result = migrateStakeholderFields(item);
-        if (result.migrated) {
-            itemsMigrated++;
-            for (const field of result.migratedFields) {
-                migratedFieldsSummary[field] = (migratedFieldsSummary[field] ?? 0) + 1;
-            }
-        }
-        if (result.warnings.length > 0)
-            itemsWithWarnings++;
-        return result;
-    });
-    return {
-        items: migratedItems,
-        totalProcessed: items.length,
-        itemsMigrated,
-        itemsWithWarnings,
-        migratedFieldsSummary,
-    };
-}
-/**
- * Convert deprecated option_grant_type value to current compensation_type value.
- */
-function convertOptionGrantTypeToCompensationType(optionGrantType) {
-    return exports.OPTION_GRANT_TYPE_TO_COMPENSATION_TYPE[optionGrantType] ?? optionGrantType;
-}
-/**
- * Normalize deprecated equity compensation issuance fields to their canonical form.
- *
- * This helper converts the legacy `option_grant_type` field to the current
- * `compensation_type` field, applying value mappings as needed:
- * - `NSO` → `OPTION_NSO`
- * - `ISO` → `OPTION_ISO`
- * - `INTL` → `OPTION`
- * - Unknown values are passed through unchanged
- *
- * Behavior:
- * - If only `option_grant_type` is provided, it is converted to `compensation_type`
- *   with the appropriate value mapping and `usedDeprecatedField` is set to `true`.
- * - If `compensation_type` is provided and non-empty, it is used as-is and
- *   `usedDeprecatedField` is set to `false`, even if `option_grant_type` is
- *   also present.
- * - If neither field is provided, `compensation_type` will be `null`.
- *
- * The input object is not mutated.
- *
- * @param data - Equity compensation issuance data that may contain either the deprecated
- *   `option_grant_type` field, the newer `compensation_type` field, or both.
- * @param context - Optional human-readable context used when emitting deprecation
- *   warnings. Defaults to `"EquityCompensationIssuance"` when not provided.
- * @returns Normalized fields including `compensation_type`, a `usedDeprecatedField` flag,
- *   and optionally the `originalDeprecatedValue` if conversion occurred.
- *
- * @example
- * ```typescript
- * const normalized = normalizeDeprecatedEquityCompensationIssuanceFields({
- *   option_grant_type: 'NSO',
- * });
- * normalized.compensation_type;      // 'OPTION_NSO'
- * normalized.usedDeprecatedField;    // true
- * normalized.originalDeprecatedValue; // 'NSO'
- * ```
- *
- * @example
- * ```typescript
- * const normalized = normalizeDeprecatedEquityCompensationIssuanceFields({
- *   option_grant_type: 'ISO',
- *   compensation_type: 'RSU',
- * });
- * // The current field takes precedence when both are present.
- * normalized.compensation_type;   // 'RSU'
- * normalized.usedDeprecatedField; // false
- * ```
- */
-function normalizeDeprecatedEquityCompensationIssuanceFields(data, context) {
-    const hasDeprecatedField = data.option_grant_type !== undefined && data.option_grant_type !== null && data.option_grant_type !== '';
-    const hasCurrentField = data.compensation_type !== undefined && data.compensation_type !== null && data.compensation_type !== '';
-    const usedDeprecatedField = hasDeprecatedField && !hasCurrentField;
-    let compensation_type = null;
-    let originalDeprecatedValue;
-    if (hasCurrentField) {
-        compensation_type = data.compensation_type ?? null;
-    }
-    else if (hasDeprecatedField && data.option_grant_type) {
-        // Re-check in condition to narrow type for TypeScript
-        originalDeprecatedValue = data.option_grant_type;
-        compensation_type = convertOptionGrantTypeToCompensationType(data.option_grant_type);
-        emitDeprecationWarning({
-            deprecatedField: 'option_grant_type',
-            replacementField: 'compensation_type',
-            deprecatedValue: data.option_grant_type,
-            context: context ?? 'EquityCompensationIssuance',
-        });
-    }
-    return { compensation_type, usedDeprecatedField, originalDeprecatedValue };
-}
-/**
- * Check equity compensation issuance data for deprecated field usage.
- */
-function checkEquityCompensationIssuanceDeprecatedFieldUsage(data) {
-    const deprecatedFieldsUsed = [];
-    if (data.option_grant_type !== undefined && data.option_grant_type !== null && data.option_grant_type !== '') {
-        deprecatedFieldsUsed.push('option_grant_type');
-    }
-    return { hasDeprecatedFields: deprecatedFieldsUsed.length > 0, deprecatedFieldsUsed };
-}
-/**
- * Migrate deprecated equity compensation issuance fields.
- */
-function migrateEquityCompensationIssuanceFields(data) {
-    const warnings = [];
-    const migratedFields = [];
-    const hasDeprecatedField = data.option_grant_type !== undefined && data.option_grant_type !== null && data.option_grant_type !== '';
-    const hasCurrentField = data.compensation_type !== undefined && data.compensation_type !== null && data.compensation_type !== '';
-    if (hasDeprecatedField && hasCurrentField) {
-        warnings.push(`Both 'option_grant_type' (deprecated) and 'compensation_type' are present. Using 'compensation_type' value.`);
-    }
-    const { compensation_type, usedDeprecatedField } = normalizeDeprecatedEquityCompensationIssuanceFields(data);
-    if (usedDeprecatedField)
-        migratedFields.push('option_grant_type');
-    const { option_grant_type: _removed, ...rest } = data;
-    return {
-        data: { ...rest, compensation_type },
-        migrated: migratedFields.length > 0,
-        migratedFields,
-        warnings,
-    };
-}
-/**
- * Migrate deprecated fields in multiple equity compensation issuance objects.
- */
-function migrateEquityCompensationIssuanceFieldsBatch(items) {
-    const migratedFieldsSummary = {};
-    let itemsMigrated = 0;
-    let itemsWithWarnings = 0;
-    const migratedItems = items.map((item) => {
-        const result = migrateEquityCompensationIssuanceFields(item);
-        if (result.migrated) {
-            itemsMigrated++;
-            for (const field of result.migratedFields) {
-                migratedFieldsSummary[field] = (migratedFieldsSummary[field] ?? 0) + 1;
-            }
-        }
-        if (result.warnings.length > 0)
-            itemsWithWarnings++;
-        return result;
-    });
-    return {
-        items: migratedItems,
-        totalProcessed: items.length,
-        itemsMigrated,
-        itemsWithWarnings,
-        migratedFieldsSummary,
-    };
-}
-/**
- * Check stock plan data for deprecated field usage without modifying the data.
- *
- * @param data - Stock plan data to check
- * @returns Result indicating whether deprecated fields were used
- *
- * @example
- *   ```typescript
- *   const result = checkStockPlanDeprecatedFieldUsage({
- *     stock_class_id: 'sc-1', // deprecated
- *   });
- *   // Returns { hasDeprecatedFields: true, deprecatedFieldsUsed: ['stock_class_id'] }
- *   ```
- */
-function checkStockPlanDeprecatedFieldUsage(data) {
-    const deprecatedFieldsUsed = [];
-    // Check for deprecated stock_class_id field (exclude empty strings to match original truthy-check behavior)
-    if (data.stock_class_id !== undefined && data.stock_class_id !== null && data.stock_class_id !== '') {
-        deprecatedFieldsUsed.push('stock_class_id');
-    }
-    return {
-        hasDeprecatedFields: deprecatedFieldsUsed.length > 0,
-        deprecatedFieldsUsed,
-    };
-}
-/**
- * Value mapping for option_grant_type -> compensation_type conversion.
- */
-exports.OPTION_GRANT_TYPE_TO_COMPENSATION_TYPE = {
-    NSO: 'OPTION_NSO',
-    ISO: 'OPTION_ISO',
-    INTL: 'OPTION',
-};
-/**
- * Known OCF deprecated field mappings.
- * Add new deprecations here as they are discovered.
- */
-exports.OCF_DEPRECATED_FIELDS = {
-    StockPlan: [
-        {
-            deprecatedField: 'stock_class_id',
-            replacementField: 'stock_class_ids',
-            deprecationType: 'singular_to_array',
-        },
-    ],
-    Stakeholder: [
-        {
-            deprecatedField: 'current_relationship',
-            replacementField: 'current_relationships',
-            deprecationType: 'singular_to_array',
-        },
-    ],
-    EquityCompensationIssuance: [
-        {
-            deprecatedField: 'option_grant_type',
-            replacementField: 'compensation_type',
-            deprecationType: 'value_mapped',
-            valueMap: exports.OPTION_GRANT_TYPE_TO_COMPENSATION_TYPE,
-        },
-    ],
-};
-/**
- * Get the list of deprecated field mappings for an OCF object type.
- *
- * @param objectType - The OCF object type name (e.g., 'StockPlan')
- * @returns Array of deprecated field mappings for the object type
- */
-function getDeprecatedFieldMappings(objectType) {
-    return exports.OCF_DEPRECATED_FIELDS[objectType] ?? [];
-}
-/**
- * Check if a specific field is deprecated for an OCF object type.
- *
- * @param objectType - The OCF object type name
- * @param fieldName - The field name to check
- * @returns The deprecation mapping if the field is deprecated, undefined otherwise
- */
-function getFieldDeprecation(objectType, fieldName) {
-    const mappings = getDeprecatedFieldMappings(objectType);
-    return mappings.find((m) => m.deprecatedField === fieldName);
-}
-/**
- * Check an object for any deprecated field usage based on known deprecations.
- *
- * @param objectType - The OCF object type name
- * @param data - The object data to check
- * @returns Result indicating which deprecated fields were used
- *
- * @example
- *   ```typescript
- *   const result = checkDeprecatedFields('StockPlan', {
- *     stock_class_id: 'sc-1', // deprecated
- *     plan_name: 'Equity Plan',
- *   });
- *   // Returns { hasDeprecatedFields: true, deprecatedFieldsUsed: ['stock_class_id'] }
- *   ```
- */
-function checkDeprecatedFields(objectType, data) {
-    const mappings = getDeprecatedFieldMappings(objectType);
-    const deprecatedFieldsUsed = [];
-    for (const mapping of mappings) {
-        const value = data[mapping.deprecatedField];
-        // Also exclude empty strings to match original truthy-check behavior
-        if (value !== undefined && value !== null && value !== '') {
-            deprecatedFieldsUsed.push(mapping.deprecatedField);
-        }
-    }
-    return {
-        hasDeprecatedFields: deprecatedFieldsUsed.length > 0,
-        deprecatedFieldsUsed,
-    };
-}
-/**
- * Check multiple objects for deprecated field usage in a single batch operation.
- *
- * @param items - Array of items to check, each with objectType and data
- * @returns Aggregated result with summary statistics and per-item details
- *
- * @example
- *   ```typescript
- *   const result = checkDeprecatedFieldsBatch([
- *     { objectType: 'StockPlan', data: { stock_class_id: 'sc-1', plan_name: 'Plan A' }, id: 'plan-1' },
- *     { objectType: 'StockPlan', data: { stock_class_ids: ['sc-2'], plan_name: 'Plan B' }, id: 'plan-2' },
- *   ]);
- *   // result.objectsWithDeprecatedFields === 1
- *   // result.deprecatedFieldSummary === { stock_class_id: 1 }
- *   ```
- */
-function checkDeprecatedFieldsBatch(items) {
-    var _a;
-    const itemsWithDeprecatedFields = [];
-    const deprecatedFieldSummary = {};
-    const objectTypeSummary = {};
-    for (let i = 0; i < items.length; i++) {
-        const item = items[i];
-        const itemId = item.id ?? `index:${i}`;
-        const result = checkDeprecatedFields(item.objectType, item.data);
-        // Update object type summary
-        objectTypeSummary[_a = item.objectType] ?? (objectTypeSummary[_a] = { total: 0, withDeprecated: 0 });
-        objectTypeSummary[item.objectType].total++;
-        if (result.hasDeprecatedFields) {
-            objectTypeSummary[item.objectType].withDeprecated++;
-            itemsWithDeprecatedFields.push({
-                itemId,
-                objectType: item.objectType,
-                ...result,
-            });
-            // Update field summary
-            for (const field of result.deprecatedFieldsUsed) {
-                deprecatedFieldSummary[field] = (deprecatedFieldSummary[field] ?? 0) + 1;
-            }
-        }
-    }
-    return {
-        totalChecked: items.length,
-        objectsWithDeprecatedFields: itemsWithDeprecatedFields.length,
-        objectsWithoutDeprecatedFields: items.length - itemsWithDeprecatedFields.length,
-        hasDeprecatedFields: itemsWithDeprecatedFields.length > 0,
-        itemsWithDeprecatedFields,
-        deprecatedFieldSummary,
-        objectTypeSummary,
-    };
-}
-/**
- * Check an array of objects of the same type for deprecated field usage.
- *
- * @param objectType - The OCF object type for all items
- * @param items - Array of data objects to check
- * @returns Aggregated result with summary statistics
- *
- * @example
- *   ```typescript
- *   const stockPlans = [
- *     { id: 'plan-1', stock_class_id: 'sc-1', plan_name: 'Plan A' },
- *     { id: 'plan-2', stock_class_ids: ['sc-2'], plan_name: 'Plan B' },
- *   ];
- *   const result = checkDeprecatedFieldsForType('StockPlan', stockPlans);
- *   ```
- */
-function checkDeprecatedFieldsForType(objectType, items) {
-    const batchItems = items.map((data, index) => ({
-        objectType,
-        data,
-        id: typeof data.id === 'string' ? data.id : `index:${index}`,
-    }));
-    return checkDeprecatedFieldsBatch(batchItems);
-}
-/**
- * Migrate deprecated stock plan fields to their current equivalents.
- *
- * This function creates a new object with deprecated fields converted to current format.
- * The original object is not modified.
- *
- * @param data - Stock plan data that may contain deprecated fields
- * @returns Migration result with normalized data and migration details
- *
- * @example
- *   ```typescript
- *   const result = migrateStockPlanFields({
- *     id: 'plan-1',
- *     stock_class_id: 'sc-1', // deprecated
- *     plan_name: 'Equity Plan',
- *   });
- *   // result.data.stock_class_ids === ['sc-1']
- *   // result.migrated === true
- *   // result.migratedFields === ['stock_class_id']
- *   ```
- */
-function migrateStockPlanFields(data) {
-    const warnings = [];
-    const migratedFields = [];
-    const hasDeprecatedField = data.stock_class_id !== undefined && data.stock_class_id !== null && data.stock_class_id !== '';
-    const hasCurrentField = Array.isArray(data.stock_class_ids) && data.stock_class_ids.length > 0;
-    // Check for both fields present
-    if (hasDeprecatedField && hasCurrentField) {
-        warnings.push(`Both 'stock_class_id' (deprecated) and 'stock_class_ids' are present. Using 'stock_class_ids' value.`);
-    }
-    // Normalize using existing helper
-    const { stock_class_ids, usedDeprecatedField } = normalizeDeprecatedStockPlanFields(data);
-    if (usedDeprecatedField) {
-        migratedFields.push('stock_class_id');
-    }
-    // Create new object without the deprecated field
-    const { stock_class_id: _removed, ...rest } = data;
-    return {
-        data: {
-            ...rest,
-            stock_class_ids,
-        },
-        migrated: migratedFields.length > 0,
-        migratedFields,
-        warnings,
-    };
-}
-/**
- * Migrate deprecated fields in multiple stock plan objects.
- *
- * @param items - Array of stock plan data objects
- * @returns Batch migration result with all migrated items
- *
- * @example
- *   ```typescript
- *   const plans = [
- *     { id: 'plan-1', stock_class_id: 'sc-1' },
- *     { id: 'plan-2', stock_class_ids: ['sc-2'] },
- *   ];
- *   const result = migrateStockPlanFieldsBatch(plans);
- *   // result.itemsMigrated === 1
- *   ```
- */
-function migrateStockPlanFieldsBatch(items) {
-    const migratedFieldsSummary = {};
-    let itemsMigrated = 0;
-    let itemsWithWarnings = 0;
-    const migratedItems = items.map((item) => {
-        const result = migrateStockPlanFields(item);
-        if (result.migrated) {
-            itemsMigrated++;
-            for (const field of result.migratedFields) {
-                migratedFieldsSummary[field] = (migratedFieldsSummary[field] ?? 0) + 1;
-            }
-        }
-        if (result.warnings.length > 0) {
-            itemsWithWarnings++;
-        }
-        return result;
-    });
-    return {
-        items: migratedItems,
-        totalProcessed: items.length,
-        itemsMigrated,
-        itemsWithWarnings,
-        migratedFieldsSummary,
-    };
-}
-/**
- * Generate a detailed deprecation report from batch verification results.
- *
- * @param batchResult - Result from checkDeprecatedFieldsBatch or checkDeprecatedFieldsForType
- * @param options - Options for report generation
- * @returns Detailed deprecation report
- *
- * @example
- *   ```typescript
- *   const items = [
- *     { objectType: 'StockPlan', data: { stock_class_id: 'sc-1' }, id: 'plan-1' },
- *   ];
- *   const batchResult = checkDeprecatedFieldsBatch(items);
- *   const report = generateDeprecationReport(batchResult);
- *   console.log(`${report.summary.deprecationPercentage}% of objects use deprecated fields`);
- *   ```
- */
-function generateDeprecationReport(batchResult, options = {}) {
-    const { includeAffectedItems = false, maxAffectedItems = 100 } = options;
-    // Calculate summary
-    const deprecationPercentage = batchResult.totalChecked > 0
-        ? Math.round((batchResult.objectsWithDeprecatedFields / batchResult.totalChecked) * 10000) / 100
-        : 0;
-    const totalDeprecatedFieldUsages = Object.values(batchResult.deprecatedFieldSummary).reduce((sum, count) => sum + count, 0);
-    // Build by-object-type breakdown
-    const byObjectType = {};
-    for (const [objectType, stats] of Object.entries(batchResult.objectTypeSummary)) {
-        const fieldsUsed = {};
-        // Count field usages for this object type
-        for (const item of batchResult.itemsWithDeprecatedFields) {
-            if (item.objectType === objectType) {
-                for (const field of item.deprecatedFieldsUsed) {
-                    fieldsUsed[field] = (fieldsUsed[field] ?? 0) + 1;
-                }
-            }
-        }
-        byObjectType[objectType] = {
-            total: stats.total,
-            withDeprecatedFields: stats.withDeprecated,
-            deprecationPercentage: stats.total > 0 ? Math.round((stats.withDeprecated / stats.total) * 10000) / 100 : 0,
-            fieldsUsed,
-        };
-    }
-    // Build by-field breakdown
-    const byField = {};
-    for (const [field, count] of Object.entries(batchResult.deprecatedFieldSummary)) {
-        const objectTypesAffected = new Set();
-        for (const item of batchResult.itemsWithDeprecatedFields) {
-            if (item.deprecatedFieldsUsed.includes(field)) {
-                objectTypesAffected.add(item.objectType);
-            }
-        }
-        // Find the mapping for this field to get replacement info
-        let foundMapping;
-        for (const objectType of objectTypesAffected) {
-            const mapping = getFieldDeprecation(objectType, field);
-            if (mapping) {
-                foundMapping = mapping;
-                break;
-            }
-        }
-        const { replacementField = 'unknown', deprecationType = 'unknown' } = foundMapping ?? {};
-        byField[field] = {
-            totalUsages: count,
-            objectTypesAffected: Array.from(objectTypesAffected),
-            replacementField,
-            deprecationType,
-        };
-    }
-    // Build affected items list if requested
-    let affectedItems;
-    if (includeAffectedItems) {
-        affectedItems = batchResult.itemsWithDeprecatedFields.slice(0, maxAffectedItems).map((item) => ({
-            itemId: item.itemId,
-            objectType: item.objectType,
-            deprecatedFieldsUsed: item.deprecatedFieldsUsed,
-        }));
-    }
-    return {
-        generatedAt: new Date().toISOString(),
-        summary: {
-            totalObjects: batchResult.totalChecked,
-            objectsWithDeprecatedFields: batchResult.objectsWithDeprecatedFields,
-            deprecationPercentage,
-            totalDeprecatedFieldUsages,
-        },
-        byObjectType,
-        byField,
-        affectedItems,
-    };
-}
-/**
- * Validate an object for deprecated field usage.
- *
- * This is useful for validation pipelines where you want to:
- * - Warn users about deprecated field usage
- * - Optionally fail validation on deprecated fields
- * - Generate clear validation messages
- *
- * @param objectType - The OCF object type
- * @param data - The data to validate
- * @param options - Validation options
- * @returns Validation result
- *
- * @example
- *   ```typescript
- *   const result = validateDeprecatedFields('StockPlan', {
- *     stock_class_id: 'sc-1',
- *   }, { treatAsError: false });
- *
- *   if (!result.valid) {
- *     console.error(result.errors.join('\n'));
- *   } else if (result.warnings.length > 0) {
- *     console.warn(result.warnings.join('\n'));
- *   }
- *   ```
- */
-function validateDeprecatedFields(objectType, data, options = {}) {
-    const { treatAsError = false, ignoreFields = [], errorMessagePrefix = '' } = options;
-    const checkResult = checkDeprecatedFields(objectType, data);
-    const errors = [];
-    const warnings = [];
-    // Filter out ignored fields
-    const relevantFields = checkResult.deprecatedFieldsUsed.filter((field) => !ignoreFields.includes(field));
-    if (relevantFields.length > 0) {
-        const messages = relevantFields.map((field) => {
-            const mapping = getFieldDeprecation(objectType, field);
-            const replacement = mapping?.replacementField ?? 'unknown';
-            const prefix = errorMessagePrefix ? `${errorMessagePrefix}: ` : '';
-            return `${prefix}Field '${field}' is deprecated. Use '${replacement}' instead.`;
-        });
-        if (treatAsError) {
-            errors.push(...messages);
-        }
-        else {
-            warnings.push(...messages);
-        }
-    }
-    return {
-        valid: errors.length === 0,
-        errors,
-        warnings,
-        checkResult: {
-            hasDeprecatedFields: relevantFields.length > 0,
-            deprecatedFieldsUsed: relevantFields,
-        },
-    };
-}
-/**
- * Create a validator function for use in validation pipelines.
- *
- * @param objectType - The OCF object type to validate
- * @param options - Validation options
- * @returns A validator function that returns DeprecationValidationResult
- *
- * @example
- *   ```typescript
- *   const validateStockPlan = createDeprecatedFieldsValidator('StockPlan', {
- *     treatAsError: false,
- *   });
- *
- *   // Use in a validation pipeline
- *   const result = validateStockPlan(stockPlanData);
- *   ```
- */
-function createDeprecatedFieldsValidator(objectType, options = {}) {
-    return (data) => validateDeprecatedFields(objectType, data, options);
-}
-/**
- * Assert that an object does not use deprecated fields.
- * Throws an error if deprecated fields are detected.
- *
- * @param objectType - The OCF object type
- * @param data - The data to check
- * @param options - Validation options (ignoreFields only)
- * @throws Error if deprecated fields are detected
- *
- * @example
- *   ```typescript
- *   try {
- *     assertNoDeprecatedFields('StockPlan', stockPlanData);
- *     // Proceed with operation
- *   } catch (error) {
- *     // Handle deprecated field usage
- *   }
- *   ```
- */
-function assertNoDeprecatedFields(objectType, data, options = {}) {
-    const result = validateDeprecatedFields(objectType, data, {
-        ...options,
-        treatAsError: true,
-    });
-    if (!result.valid) {
-        throw new Error(`Deprecated field usage detected: ${result.errors.join('; ')}`);
-    }
-}
-// ===== Helper to Register New Deprecations =====
-/**
- * Register a new deprecated field mapping.
- *
- * This is useful for extending the built-in deprecation registry with
- * custom or newly discovered deprecations.
- *
- * @param objectType - The OCF object type
- * @param mapping - The deprecation mapping to register
- *
- * @example
- *   ```typescript
- *   // Register a new deprecation
- *   registerDeprecatedFieldMapping('SomeOcfType', {
- *     deprecatedField: 'old_field',
- *     replacementField: 'new_fields',
- *     deprecationType: 'singular_to_array',
- *   });
- *   ```
- */
-function registerDeprecatedFieldMapping(objectType, mapping) {
-    exports.OCF_DEPRECATED_FIELDS[objectType] ?? (exports.OCF_DEPRECATED_FIELDS[objectType] = []);
-    // Check if mapping already exists
-    const existing = exports.OCF_DEPRECATED_FIELDS[objectType].find((m) => m.deprecatedField === mapping.deprecatedField);
-    if (!existing) {
-        exports.OCF_DEPRECATED_FIELDS[objectType].push(mapping);
-    }
-}
-/**
- * Get all registered object types that have deprecated field mappings.
- *
- * @returns Array of object type names
- */
-function getRegisteredObjectTypes() {
-    return Object.keys(exports.OCF_DEPRECATED_FIELDS);
-}
-/**
- * Get all registered deprecated field mappings.
- *
- * @returns Copy of the deprecated fields registry
- */
-function getAllDeprecatedFieldMappings() {
-    // Return a deep copy to prevent external modification
-    const result = {};
-    for (const [key, value] of Object.entries(exports.OCF_DEPRECATED_FIELDS)) {
-        result[key] = value.map((m) => ({ ...m }));
-    }
-    return result;
-}
-// ===== Automatic Normalization for SDK Integration =====
-/**
- * Map from OcfEntityType (used in batch API) to the object type name used in deprecation registry.
- * This allows the SDK to automatically look up deprecations based on entity type.
- */
-const ENTITY_TYPE_TO_OBJECT_TYPE = {
-    stockPlan: 'StockPlan',
-    stakeholder: 'Stakeholder',
-    equityCompensationIssuance: 'EquityCompensationIssuance',
-    // Add more mappings as deprecations are discovered for other types
-};
-/**
- * Automatically normalize deprecated fields in OCF data based on entity type.
- *
- * This function is designed to be called by the SDK internally when processing
- * OCF data, making deprecated field handling transparent to end-users.
- *
- * @param entityType - The OCF entity type (e.g., 'stockPlan')
- * @param data - The OCF data that may contain deprecated fields
- * @param options - Optional configuration
- * @returns The normalized data with deprecated fields converted to current format
- *
- * @example
- *   ```typescript
- *   // SDK automatically normalizes deprecated fields
- *   const result = normalizeDeprecatedOcfFields('stockPlan', {
- *     id: 'plan-1',
- *     stock_class_id: 'sc-1', // deprecated, automatically converted
- *     plan_name: 'Equity Plan',
- *   });
- *   // result.data.stock_class_ids === ['sc-1']
- *   ```
- */
-function normalizeDeprecatedOcfFields(entityType, data, options = {}) {
-    const { emitWarnings = true, context } = options;
-    const normalizedFields = [];
-    const warnings = [];
-    // Step 1: Normalize required array fields to empty arrays if null/undefined
-    // This uses lazy cloning internally - only clones if normalization is needed
-    const arrayNormResult = normalizeRequiredArrayFields(entityType, data);
-    let result = arrayNormResult.data;
-    normalizedFields.push(...arrayNormResult.normalizedFields);
-    // Track whether we've cloned the result (arrayNormResult.data may be the original or a clone)
-    let hasCloned = arrayNormResult.normalizedFields.length > 0;
-    // Step 2: Look up the object type for deprecated field mappings
-    const objectType = ENTITY_TYPE_TO_OBJECT_TYPE[entityType];
-    // If no deprecation mappings exist for this type, return with just array normalization
-    if (!objectType) {
-        return {
-            data: result,
-            normalized: normalizedFields.length > 0,
-            normalizedFields,
-            warnings: [],
-        };
-    }
-    const mappings = getDeprecatedFieldMappings(objectType);
-    if (mappings.length === 0) {
-        return {
-            data: result,
-            normalized: normalizedFields.length > 0,
-            normalizedFields,
-            warnings: [],
-        };
-    }
-    // Helper to ensure we have a mutable clone
-    const ensureCloned = () => {
-        if (!hasCloned) {
-            result = { ...result };
-            hasCloned = true;
-        }
-    };
-    // Track which deprecated fields we normalized (for removal at the end)
-    const deprecatedFieldsToRemove = [];
-    for (const mapping of mappings) {
-        const deprecatedValue = result[mapping.deprecatedField];
-        const hasDeprecated = deprecatedValue !== undefined && deprecatedValue !== null && deprecatedValue !== '';
-        if (!hasDeprecated) {
-            continue;
-        }
-        switch (mapping.deprecationType) {
-            case 'singular_to_array': {
-                const currentValue = result[mapping.replacementField];
-                const hasCurrentArray = Array.isArray(currentValue) && currentValue.length > 0;
-                if (!hasCurrentArray) {
-                    // Convert singular to array
-                    ensureCloned();
-                    result[mapping.replacementField] = [deprecatedValue];
-                    normalizedFields.push(mapping.deprecatedField);
-                    deprecatedFieldsToRemove.push(mapping.deprecatedField);
-                    if (emitWarnings) {
-                        emitDeprecationWarning({
-                            deprecatedField: mapping.deprecatedField,
-                            replacementField: mapping.replacementField,
-                            deprecatedValue,
-                            context: context ?? `${entityType}.create`,
-                        });
-                    }
-                }
-                else {
-                    // Both present - current takes precedence, emit warning
-                    warnings.push(`Both '${mapping.deprecatedField}' (deprecated) and '${mapping.replacementField}' are present. ` +
-                        `Using '${mapping.replacementField}' value.`);
-                }
-                break;
-            }
-            case 'renamed': {
-                const currentValue = result[mapping.replacementField];
-                const hasCurrent = currentValue !== undefined && currentValue !== null;
-                if (!hasCurrent) {
-                    // Copy deprecated value to new field
-                    ensureCloned();
-                    result[mapping.replacementField] = deprecatedValue;
-                    normalizedFields.push(mapping.deprecatedField);
-                    deprecatedFieldsToRemove.push(mapping.deprecatedField);
-                    if (emitWarnings) {
-                        emitDeprecationWarning({
-                            deprecatedField: mapping.deprecatedField,
-                            replacementField: mapping.replacementField,
-                            deprecatedValue,
-                            context: context ?? `${entityType}.create`,
-                        });
-                    }
-                }
-                else {
-                    warnings.push(`Both '${mapping.deprecatedField}' (deprecated) and '${mapping.replacementField}' are present. ` +
-                        `Using '${mapping.replacementField}' value.`);
-                }
-                break;
-            }
-            case 'value_mapped': {
-                const currentValue = result[mapping.replacementField];
-                const hasCurrent = currentValue !== undefined && currentValue !== null && currentValue !== '';
-                if (!hasCurrent) {
-                    // value_mapped requires string values; skip non-string types
-                    if (typeof deprecatedValue !== 'string') {
-                        warnings.push(`Expected string value for '${mapping.deprecatedField}', got ${typeof deprecatedValue}`);
-                        break;
-                    }
-                    const valueMap = mapping.valueMap ?? {};
-                    const mappedValue = valueMap[deprecatedValue] ?? deprecatedValue;
-                    ensureCloned();
-                    result[mapping.replacementField] = mappedValue;
-                    normalizedFields.push(mapping.deprecatedField);
-                    deprecatedFieldsToRemove.push(mapping.deprecatedField);
-                    if (emitWarnings) {
-                        emitDeprecationWarning({
-                            deprecatedField: mapping.deprecatedField,
-                            replacementField: mapping.replacementField,
-                            deprecatedValue,
-                            context: context ?? `${entityType}.create`,
-                        });
-                    }
-                }
-                else {
-                    warnings.push(`Both '${mapping.deprecatedField}' (deprecated) and '${mapping.replacementField}' are present. ` +
-                        `Using '${mapping.replacementField}' value.`);
-                }
-                break;
-            }
-            case 'removed': {
-                // Field is removed, just warn
-                warnings.push(`Field '${mapping.deprecatedField}' is deprecated and will be ignored. ` +
-                    `It has been removed in the current schema.`);
-                normalizedFields.push(mapping.deprecatedField);
-                deprecatedFieldsToRemove.push(mapping.deprecatedField);
-                break;
-            }
-        }
-    }
-    // Remove deprecated fields from the result to keep data clean
-    // (They've been migrated to their replacements, or removed entirely for 'removed' type)
-    if (deprecatedFieldsToRemove.length > 0) {
-        ensureCloned();
-        for (const field of deprecatedFieldsToRemove) {
-            delete result[field];
-        }
-    }
-    return {
-        data: result,
-        normalized: normalizedFields.length > 0,
-        normalizedFields,
-        warnings,
-    };
-}
-/**
- * Check if an entity type has registered deprecations.
- *
- * @param entityType - The OCF entity type (e.g., 'stockPlan')
- * @returns true if the entity type has deprecation mappings
- */
-function hasDeprecationsForEntityType(entityType) {
-    const objectType = ENTITY_TYPE_TO_OBJECT_TYPE[entityType];
-    if (!objectType) {
-        return false;
-    }
-    return getDeprecatedFieldMappings(objectType).length > 0;
-}
-/**
- * Register a mapping from entity type to object type for automatic normalization.
- *
- * @param entityType - The OcfEntityType used in batch API (e.g., 'stockPlan')
- * @param objectType - The object type name used in deprecation registry (e.g., 'StockPlan')
- */
-function registerEntityTypeMapping(entityType, objectType) {
-    ENTITY_TYPE_TO_OBJECT_TYPE[entityType] = objectType;
-}
-// ===== Unified OCF Object Normalization =====
-/**
- * Map from OCF object_type to the object type name used in deprecation registry.
- */
-const OBJECT_TYPE_TO_REGISTRY_TYPE = {
-    STOCK_PLAN: 'StockPlan',
-    STAKEHOLDER: 'Stakeholder',
-    TX_EQUITY_COMPENSATION_ISSUANCE: 'EquityCompensationIssuance',
-    TX_PLAN_SECURITY_ISSUANCE: 'EquityCompensationIssuance',
-};
-/**
- * Normalize quantity_source field for OCF objects.
- *
- * Handles two scenarios to ensure consistent comparison:
- *
- * 1. When quantity is NOT present (null/undefined): quantity_source is meaningless
- *    and should be stripped. This ensures:
- *    - DB with { quantity_source: 'UNSPECIFIED' } (no quantity)
- *    - Canton readback with {} (no quantity, no quantity_source)
- *    are treated as semantically equivalent.
- *
- * 2. When quantity IS present but quantity_source is missing: quantity_source should
- *    be set to 'UNSPECIFIED' because the OCF-to-DAML converter defaults to 'UNSPECIFIED'
- *    when quantity is present without quantity_source. This ensures:
- *    - DB with { quantity: '1000' } (no quantity_source)
- *    - Canton readback with { quantity: '1000', quantity_source: 'UNSPECIFIED' }
- *    are treated as semantically equivalent.
- *
- * @param data - OCF object that may have quantity and quantity_source fields
- * @returns Object with quantity_source normalized based on quantity presence
- */
-function normalizeQuantitySource(data) {
-    const { quantity, quantity_source: quantitySource } = data;
-    // Case 1: Strip quantity_source if quantity is not present (null/undefined)
-    // and quantity_source is 'UNSPECIFIED' (which is equivalent to "don't know")
-    if ((quantity === null || quantity === undefined) && quantitySource === 'UNSPECIFIED') {
-        const { quantity_source: _, ...rest } = data;
-        return rest;
-    }
-    // Case 2: Add quantity_source: 'UNSPECIFIED' if quantity IS present but quantity_source is missing
-    // This matches the OCF-to-DAML converter behavior that defaults to 'UNSPECIFIED'
-    if (quantity !== null && quantity !== undefined && quantitySource === undefined) {
-        return { ...data, quantity_source: 'UNSPECIFIED' };
-    }
-    return data;
-}
-/**
- * Normalize an OCF object by applying all deprecation normalizations.
- *
- * This function auto-detects the object type from the `object_type` field and applies:
- * 1. PlanSecurity -> EquityCompensation object_type normalization
- * 2. Deprecated field normalizations (singular->array, value mappings, etc.)
- * 3. Semantic normalizations (e.g., quantity_source: 'UNSPECIFIED' when quantity is absent)
- */
-function normalizeOcfObject(data, options = {}) {
-    const { emitWarnings = true, context } = options;
-    const normalizedFields = [];
-    const warnings = [];
-    // Step 0: Normalize quantity_source (strip if UNSPECIFIED and no quantity)
-    // This must happen before other normalizations to ensure consistent comparison
-    let result = normalizeQuantitySource(data);
-    // Step 1: Normalize PlanSecurity object_type to EquityCompensation
-    result = (0, planSecurityAliases_1.normalizeOcfData)(result);
-    const originalObjectType = data.object_type;
-    const normalizedObjectType = result.object_type;
-    if (originalObjectType !== normalizedObjectType && typeof originalObjectType === 'string') {
-        normalizedFields.push('object_type');
-        if (emitWarnings) {
-            emitDeprecationWarning({
-                deprecatedField: 'object_type',
-                replacementField: 'object_type',
-                deprecatedValue: originalObjectType,
-                context: context ?? 'normalizeOcfObject',
-            });
-        }
-    }
-    // Step 2: Determine the registry type from object_type
-    const objectType = typeof normalizedObjectType === 'string' ? normalizedObjectType : undefined;
-    const registryType = objectType ? OBJECT_TYPE_TO_REGISTRY_TYPE[objectType] : undefined;
-    if (!registryType) {
-        return { data: result, normalized: normalizedFields.length > 0, normalizedFields, warnings };
-    }
-    // Step 3: Apply deprecated field normalizations
-    const mappings = getDeprecatedFieldMappings(registryType);
-    for (const mapping of mappings) {
-        const deprecatedValue = result[mapping.deprecatedField];
-        const hasDeprecated = deprecatedValue !== undefined && deprecatedValue !== null && deprecatedValue !== '';
-        if (!hasDeprecated)
-            continue;
-        switch (mapping.deprecationType) {
-            case 'singular_to_array': {
-                const currentValue = result[mapping.replacementField];
-                const hasCurrentArray = Array.isArray(currentValue) && currentValue.length > 0;
-                if (!hasCurrentArray) {
-                    result = { ...result, [mapping.replacementField]: [deprecatedValue] };
-                    normalizedFields.push(mapping.deprecatedField);
-                    if (emitWarnings) {
-                        emitDeprecationWarning({
-                            deprecatedField: mapping.deprecatedField,
-                            replacementField: mapping.replacementField,
-                            deprecatedValue,
-                            context: context ?? registryType,
-                        });
-                    }
-                }
-                else {
-                    warnings.push(`Both '${mapping.deprecatedField}' (deprecated) and '${mapping.replacementField}' are present. Using '${mapping.replacementField}' value.`);
-                }
-                break;
-            }
-            case 'value_mapped': {
-                const currentValue = result[mapping.replacementField];
-                const hasCurrent = currentValue !== undefined && currentValue !== null && currentValue !== '';
-                if (!hasCurrent) {
-                    // value_mapped requires string values; skip non-string types
-                    if (typeof deprecatedValue !== 'string') {
-                        warnings.push(`Expected string value for '${mapping.deprecatedField}', got ${typeof deprecatedValue}`);
-                        break;
-                    }
-                    const valueMap = mapping.valueMap ?? {};
-                    const mappedValue = valueMap[deprecatedValue] ?? deprecatedValue;
-                    result = { ...result, [mapping.replacementField]: mappedValue };
-                    normalizedFields.push(mapping.deprecatedField);
-                    if (emitWarnings) {
-                        emitDeprecationWarning({
-                            deprecatedField: mapping.deprecatedField,
-                            replacementField: mapping.replacementField,
-                            deprecatedValue,
-                            context: context ?? registryType,
-                        });
-                    }
-                }
-                else {
-                    warnings.push(`Both '${mapping.deprecatedField}' (deprecated) and '${mapping.replacementField}' are present. Using '${mapping.replacementField}' value.`);
-                }
-                break;
-            }
-            case 'renamed': {
-                const currentValue = result[mapping.replacementField];
-                const hasCurrent = currentValue !== undefined && currentValue !== null;
-                if (!hasCurrent) {
-                    result = { ...result, [mapping.replacementField]: deprecatedValue };
-                    normalizedFields.push(mapping.deprecatedField);
-                    if (emitWarnings) {
-                        emitDeprecationWarning({
-                            deprecatedField: mapping.deprecatedField,
-                            replacementField: mapping.replacementField,
-                            deprecatedValue,
-                            context: context ?? registryType,
-                        });
-                    }
-                }
-                else {
-                    warnings.push(`Both '${mapping.deprecatedField}' (deprecated) and '${mapping.replacementField}' are present. Using '${mapping.replacementField}' value.`);
-                }
-                break;
-            }
-            case 'removed': {
-                warnings.push(`Field '${mapping.deprecatedField}' is deprecated and will be ignored.`);
-                normalizedFields.push(mapping.deprecatedField);
-                break;
-            }
-        }
-    }
-    // Step 4: Remove deprecated fields from the result
-    // Note: The `as T` assertion is intentional - TypeScript cannot track field removal through
-    // computed property spread. The result type may differ from T (deprecated fields removed),
-    // but this is the expected behavior and callers handle it via Record<string, unknown>.
-    for (const mapping of mappings) {
-        if (normalizedFields.includes(mapping.deprecatedField) && mapping.deprecatedField !== 'object_type') {
-            const { [mapping.deprecatedField]: _removed, ...rest } = result;
-            result = rest;
-        }
-    }
-    return { data: result, normalized: normalizedFields.length > 0, normalizedFields, warnings };
-}
-/**
- * Compare two OCF objects for semantic equivalence after normalizing deprecated fields.
- */
-function areOcfObjectsEquivalent(dbObject, chainObject, options = {}) {
-    const result = compareOcfObjects(dbObject, chainObject, options);
-    return result.equivalent;
-}
-/**
- * Compare two OCF objects with detailed results.
- */
-function compareOcfObjects(dbObject, chainObject, options = {}) {
-    const { normalizeBeforeCompare = true, emitNormalizationWarnings = false, ignoredFields = [...ocfComparison_1.DEFAULT_INTERNAL_FIELDS], deprecatedFields = [...ocfComparison_1.DEFAULT_DEPRECATED_FIELDS], reportDifferences, } = options;
-    let normalizedA = dbObject;
-    let normalizedB = chainObject;
-    let normResultA = { normalized: false, normalizedFields: [], warnings: [] };
-    let normResultB = { normalized: false, normalizedFields: [], warnings: [] };
-    if (normalizeBeforeCompare) {
-        const resultA = normalizeOcfObject(dbObject, { emitWarnings: emitNormalizationWarnings });
-        normalizedA = resultA.data;
-        normResultA = {
-            normalized: resultA.normalized,
-            normalizedFields: resultA.normalizedFields,
-            warnings: resultA.warnings,
-        };
-        const resultB = normalizeOcfObject(chainObject, { emitWarnings: emitNormalizationWarnings });
-        normalizedB = resultB.data;
-        normResultB = {
-            normalized: resultB.normalized,
-            normalizedFields: resultB.normalizedFields,
-            warnings: resultB.warnings,
-        };
-    }
-    const equivalent = (0, ocfComparison_1.ocfDeepEqual)(normalizedA, normalizedB, { ignoredFields, deprecatedFields, reportDifferences });
-    return {
-        equivalent,
-        normalizationA: {
-            wasNormalized: normResultA.normalized,
-            normalizedFields: normResultA.normalizedFields,
-            warnings: normResultA.warnings,
-        },
-        normalizationB: {
-            wasNormalized: normResultB.normalized,
-            normalizedFields: normResultB.normalizedFields,
-            warnings: normResultB.warnings,
-        },
-    };
-}
-// ===== Required Array Field Normalization =====
-/**
- * Configuration for required array fields by entity type.
- * These fields must be arrays (empty or populated), but raw data might have them as null/undefined.
- * The SDK normalizes these to empty arrays automatically.
- */
-exports.REQUIRED_ARRAY_FIELDS = {
-    // issuer is handled separately in createIssuer.ts
-    stockPlan: ['stock_class_ids'],
-    convertibleIssuance: ['conversion_triggers', 'security_law_exemptions'],
-    warrantIssuance: ['exercise_triggers', 'security_law_exemptions'],
-    stakeholderRelationshipChangeEvent: ['new_relationships'],
-    // vestingTerms.vesting_conditions requires at least one condition, so we don't auto-normalize to empty
-    // resulting_security_ids must be explicitly provided, not auto-normalized
-};
-/**
- * Normalize required array fields in OCF data.
- * This ensures array fields that are null/undefined become empty arrays.
- *
- * Uses lazy cloning - only creates a copy when modification is actually needed,
- * and clones once then mutates the clone for efficiency.
- *
- * @param entityType - The OCF entity type
- * @param data - The OCF data that may have null/undefined array fields
- * @returns The normalized data with array fields as arrays
- */
-function normalizeRequiredArrayFields(entityType, data) {
-    const requiredArrays = exports.REQUIRED_ARRAY_FIELDS[entityType];
-    if (!requiredArrays || requiredArrays.length === 0) {
-        return { data, normalizedFields: [] };
-    }
-    // First pass: identify which fields need normalization
-    const fieldsToNormalize = [];
-    for (const field of requiredArrays) {
-        const value = data[field];
-        if (value === null || value === undefined) {
-            fieldsToNormalize.push(field);
-        }
-    }
-    // If no fields need normalization, return original data (no clone)
-    if (fieldsToNormalize.length === 0) {
-        return { data, normalizedFields: [] };
-    }
-    // Clone once, then mutate the clone for all fields
-    const result = { ...data };
-    for (const field of fieldsToNormalize) {
-        result[field] = [];
-    }
-    return { data: result, normalizedFields: fieldsToNormalize };
-}
-/**
- * Register required array fields for an entity type.
- *
- * @param entityType - The OCF entity type (e.g., 'stockPlan')
- * @param fields - Array of field names that must be arrays
- */
-function registerRequiredArrayFields(entityType, fields) {
-    exports.REQUIRED_ARRAY_FIELDS[entityType] = fields;
-}
-/**
- * Get required array fields for an entity type.
- *
- * @param entityType - The OCF entity type
- * @returns Array of field names that must be arrays
- */
-function getRequiredArrayFields(entityType) {
-    return exports.REQUIRED_ARRAY_FIELDS[entityType] ?? [];
-}
-//# sourceMappingURL=deprecatedFieldNormalization.js.map