@revoengine/cli 1.0.9 → 1.0.11

package/dist/src/metadata-backfill.js

@@ -0,0 +1,1176 @@
+import { randomBytes } from 'node:crypto';
+import { isDatabaseBackupArtifact } from "./database-schema-artifacts.js";
+import { buildStableKey, buildResourceIdentityStableKeyValue, normalizeStableKeyValue, readConfiguredResourceMetadataStableKey, sanitizeUserMetadata, } from "./resource-metadata.js";
+import { shouldTrackResource } from "./tracked-resources.js";
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function unwrapResource(value) {
+    if (isRecord(value) && isRecord(value.data)) {
+        return value.data;
+    }
+    return value;
+}
+function resourceIdOf(resource) {
+    return String(('databaseId' in resource && resource.databaseId)
+        || ('databaseViewId' in resource && resource.databaseViewId)
+        || ('jobTemplateId' in resource && resource.jobTemplateId)
+        || ('endpointId' in resource && resource.endpointId)
+        || ('scheduleId' in resource && resource.scheduleId)
+        || ('jobEventId' in resource && resource.jobEventId)
+        || ('eventId' in resource && resource.eventId)
+        || ('groupId' in resource && resource.groupId)
+        || resource.componentId
+        || resource.roleGroupId
+        || resource.id
+        || '');
+}
+function normalizeValue(value, fallback = null) {
+    return value ?? fallback;
+}
+function rawConfiguredStableKey(resource, stableKeyName) {
+    for (const metadata of [resource.metadata, resource.metaData, resource.resourceMetadata]) {
+        if (isRecord(metadata) && Object.prototype.hasOwnProperty.call(metadata, stableKeyName)) {
+            return { present: true, value: metadata[stableKeyName] };
+        }
+    }
+    return { present: false, value: undefined };
+}
+function metadataStableKeyIdentity(resourceType, stableKey) {
+    // TODO(APP-918): Align Role Groups with the exact Stable Key contract used by
+    // Components and Job Templates. Update role-group pull, plan, push and
+    // filesystem-path collision handling together before changing this branch.
+    const identityValue = resourceType === 'role-group'
+        ? normalizeStableKeyValue(stableKey)
+        : stableKey;
+    return `${resourceType}:${identityValue}`;
+}
+export function generateStableKeySuffix(bytes = 4) {
+    return randomBytes(bytes).toString('hex');
+}
+export function buildGeneratedStableKey(resource) {
+    return `${buildResourceIdentityStableKeyValue(resource)}#${generateStableKeySuffix()}`;
+}
+function buildNamedResourceGeneratedStableKey(resource) {
+    const category = typeof resource.category === 'string' && resource.category.trim()
+        ? resource.category.trim()
+        : 'Uncategorized';
+    const name = typeof resource.name === 'string' ? resource.name.trim() : '';
+    return `${category}/${name}#${generateStableKeySuffix()}`;
+}
+function isDatabaseSchemaPartition(database) {
+    return Boolean(database.parentId || database.parent);
+}
+function databaseDefinitions(database) {
+    return Array.isArray(database.definition)
+        ? database.definition.filter(isRecord)
+        : [];
+}
+function columnStableKeyValue(definition, stableKeyName) {
+    const metadata = definition.metadata;
+    if (!isRecord(metadata) || !Object.hasOwn(metadata, stableKeyName)) {
+        return { present: false, value: undefined };
+    }
+    return { present: true, value: metadata[stableKeyName] };
+}
+function buildGeneratedDatabaseColumnStableKey(database, columnName) {
+    const category = typeof database.category === 'string' && database.category.trim()
+        ? database.category.trim()
+        : 'Uncategorized';
+    const databaseName = typeof database.name === 'string' ? database.name.trim() : '';
+    return `${category}/${databaseName}/${columnName}#${generateStableKeySuffix()}`;
+}
+function buildColumnStableKeyMetadata(definition, stableKeyName, stableKey) {
+    return {
+        ...sanitizeUserMetadata(definition.metadata),
+        [stableKeyName]: stableKey,
+    };
+}
+function buildDatabaseColumnMetadataUpdatePayload(input) {
+    if (!Number.isInteger(input.database.version)) {
+        throw new Error('database schema version is required to update column metadata');
+    }
+    if (input.assignments.length === 0) {
+        throw new Error('at least one database schema column metadata assignment is required');
+    }
+    const definitions = databaseDefinitions(input.database);
+    const assignmentsByDefinition = new Map(input.assignments.map((assignment) => [
+        assignment.definition,
+        assignment.stableKey,
+    ]));
+    for (const assignment of input.assignments) {
+        const name = typeof assignment.definition.name === 'string' ? assignment.definition.name : 'unknown';
+        if (!definitions.includes(assignment.definition)) {
+            throw new Error(`database schema column "${name}" no longer exists`);
+        }
+    }
+    for (const definition of definitions) {
+        const name = typeof definition.name === 'string' ? definition.name : 'unknown';
+        if (typeof definition.databaseDefinitionId !== 'string' || !definition.databaseDefinitionId) {
+            throw new Error(`database schema column "${name}" is missing databaseDefinitionId; refusing to rewrite the full definition for metadata backfill`);
+        }
+    }
+    return {
+        version: input.database.version,
+        definition: definitions.map((definition) => {
+            const { metadata: _metadata, ...withoutMetadata } = definition;
+            const stableKey = assignmentsByDefinition.get(definition);
+            if (!stableKey) {
+                const metadata = sanitizeUserMetadata(definition.metadata);
+                return Object.keys(metadata).length > 0
+                    ? { ...withoutMetadata, metadata }
+                    : withoutMetadata;
+            }
+            return {
+                ...withoutMetadata,
+                metadata: buildColumnStableKeyMetadata(definition, input.stableKeyName, stableKey),
+            };
+        }),
+    };
+}
+function groupMetadataBackfillReason(group, existingStableKey, force) {
+    const baseReason = existingStableKey
+        ? (force ? 'stable key will be regenerated' : 'stable key already exists')
+        : 'stable key missing';
+    const reservedKeys = new Set();
+    for (const metadata of [group.resourceMetadata, group.metaData, group.metadata]) {
+        if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) {
+            continue;
+        }
+        for (const key of Object.keys(metadata)) {
+            if (key.startsWith('__')) {
+                reservedKeys.add(key);
+            }
+        }
+    }
+    if (reservedKeys.size === 0) {
+        return baseReason;
+    }
+    return `${baseReason}; backend-reserved metadata keys excluded: ${[...reservedKeys].sort((left, right) => left.localeCompare(right)).join(', ')}`;
+}
+function waitForMutationSlot() {
+    return new Promise((resolve) => setTimeout(resolve, 100));
+}
+function scheduleExclusionReason(schedule) {
+    if (schedule.systemManaged === true) {
+        return 'system-managed schedule is excluded';
+    }
+    const materializedViewRefresh = schedule.targetType === 'PLATFORM_OPERATION'
+        && isRecord(schedule.targetConfig)
+        && schedule.targetConfig.kind === 'refresh_materialized_view';
+    if (schedule.targetType !== 'JOB_TEMPLATE' && !materializedViewRefresh) {
+        return `target type ${String(schedule.targetType || 'unknown')} is outside Schedule migration scope`;
+    }
+    return null;
+}
+function eventExclusionReason(event) {
+    if (event.deletedAt || event.deletedBy) {
+        return 'deleted event is excluded';
+    }
+    if (event.targetType !== 'JOB_TEMPLATE') {
+        return `target type ${String(event.targetType || 'unknown')} is outside Event migration scope`;
+    }
+    return null;
+}
+function endpointExclusionReason(endpoint) {
+    return endpoint.deletedAt || endpoint.deletedBy ? 'deleted endpoint is excluded' : null;
+}
+function buildMetadataUpdatePayload(resource, stableKeyName, stableKey, resourceType) {
+    if (!Number.isInteger(resource.version)) {
+        throw new Error(`${resourceType} version is required to update metadata`);
+    }
+    return {
+        version: resource.version,
+        metadata: {
+            ...sanitizeUserMetadata(resource.resourceMetadata),
+            ...sanitizeUserMetadata(resource.metaData),
+            ...sanitizeUserMetadata(resource.metadata),
+            [stableKeyName]: stableKey,
+        },
+    };
+}
+function databaseViewPrincipalIds(entries, property) {
+    if (!Array.isArray(entries)) {
+        throw new Error(`database view ${property === 'userId' ? 'users' : 'groups'} are required to preserve its access policy`);
+    }
+    return entries.map((entry) => {
+        const value = typeof entry === 'string'
+            ? entry
+            : isRecord(entry) && typeof entry[property] === 'string'
+                ? entry[property]
+                : undefined;
+        if (typeof value !== 'string' || !value.trim()) {
+            throw new Error(`database view ${property === 'userId' ? 'user' : 'group'} access policy contains an invalid principal`);
+        }
+        return value;
+    });
+}
+function databaseViewIndexesForUpdate(view) {
+    if (view.indexes === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(view.indexes)) {
+        throw new Error('materialized database view indexes are invalid and cannot be preserved safely');
+    }
+    return JSON.parse(JSON.stringify(view.indexes));
+}
+function buildDatabaseViewMetadataUpdatePayload(view, stableKeyName, stableKey) {
+    if (typeof view.name !== 'string' || !view.name.trim()) {
+        throw new Error('database view name is required for a full update');
+    }
+    if (view.type !== 'VIEW' && view.type !== 'MATERIALIZED_VIEW') {
+        throw new Error(`database view type ${String(view.type || 'unknown')} cannot be updated`);
+    }
+    if (view.definitionMode !== 'STRUCTURED' && view.definitionMode !== 'RAW_SQL') {
+        throw new Error(`database view definitionMode ${String(view.definitionMode || 'unknown')} cannot be updated`);
+    }
+    if (typeof view.restricted !== 'boolean') {
+        throw new Error('database view restricted access policy is required to preserve it');
+    }
+    if (!Number.isInteger(view.version) || view.version < 0) {
+        throw new Error('database view version is required for a full update');
+    }
+    if (view.type === 'MATERIALIZED_VIEW' && !Array.isArray(view.uniqueKey)) {
+        throw new Error('materialized database view uniqueKey is required to preserve its definition');
+    }
+    const payload = {
+        name: view.name,
+        ...(typeof view.category === 'string' ? { category: view.category } : {}),
+        ...(typeof view.desc === 'string'
+            ? { desc: view.desc }
+            : typeof view.description === 'string'
+                ? { desc: view.description }
+                : {}),
+        ...buildMetadataUpdatePayload(view, stableKeyName, stableKey, 'database-view'),
+        type: view.type,
+        definitionMode: view.definitionMode,
+        restricted: view.restricted,
+        users: databaseViewPrincipalIds(view.users, 'userId'),
+        groups: databaseViewPrincipalIds(view.groups, 'groupId'),
+    };
+    const indexes = view.type === 'MATERIALIZED_VIEW'
+        ? databaseViewIndexesForUpdate(view)
+        : undefined;
+    const materialized = view.type === 'MATERIALIZED_VIEW'
+        ? {
+            uniqueKey: view.uniqueKey,
+            ...(indexes === undefined ? {} : { indexes }),
+        }
+        : {};
+    if (view.definitionMode === 'STRUCTURED') {
+        if (!isRecord(view.request)) {
+            throw new Error('structured database view request is required for a full update');
+        }
+        return { ...payload, ...materialized, request: view.request };
+    }
+    if (typeof view.rawQuery !== 'string' || !view.rawQuery.trim()) {
+        throw new Error('raw SQL database view query is required for a full update');
+    }
+    return {
+        ...payload,
+        ...materialized,
+        rawQuery: view.rawQuery,
+    };
+}
+function buildJobTemplateMetadataUpdatePayload(jobTemplate, stableKeyName, stableKey) {
+    if (!Object.hasOwn(jobTemplate, 'options') || jobTemplate.options === undefined || jobTemplate.options === null) {
+        throw new Error(`Job-template ${resourceIdOf(jobTemplate) || 'unknown'} is missing options in the API response; refusing metadata update to preserve its configuration.`);
+    }
+    return {
+        ...buildMetadataUpdatePayload(jobTemplate, stableKeyName, stableKey, 'job-template'),
+        options: jobTemplate.options,
+    };
+}
+export async function buildMetadataBackfillPlan(input) {
+    const { client, envName, stableKeyName, trackedResources, force = false, skipPartitions = false } = input;
+    const items = [];
+    if (shouldTrackResource(trackedResources, 'component')) {
+        const { components } = await client.listAllComponents();
+        for (const summary of components) {
+            const summaryId = resourceIdOf(summary);
+            if (!summaryId) {
+                continue;
+            }
+            const component = unwrapResource(await client.getComponent(summaryId));
+            const resourceId = resourceIdOf(component) || summaryId;
+            const existingStableKey = readConfiguredResourceMetadataStableKey(component, stableKeyName);
+            const stableKey = existingStableKey && !force
+                ? undefined
+                : buildGeneratedStableKey(component);
+            const plannedStableKey = stableKey || existingStableKey || undefined;
+            items.push({
+                resourceType: 'component',
+                resourceId,
+                name: String(component.name || ''),
+                category: normalizeValue(component.category),
+                action: existingStableKey && !force ? 'skip' : 'update',
+                metadataField: 'metadata',
+                stableKeyName,
+                ...(plannedStableKey ? { stableKey: plannedStableKey } : {}),
+                reason: existingStableKey
+                    ? (force ? 'stable key will be regenerated' : 'stable key already exists')
+                    : 'stable key missing',
+            });
+        }
+    }
+    if (shouldTrackResource(trackedResources, 'database-schema') && typeof client.listAllDatabaseSchemas === 'function') {
+        const { databases } = await client.listAllDatabaseSchemas({ projection: 'pull', skipPartitions });
+        for (const database of databases) {
+            if (isDatabaseBackupArtifact(database)) {
+                continue;
+            }
+            const resourceId = resourceIdOf(database);
+            if (!resourceId) {
+                continue;
+            }
+            const category = normalizeValue(database.category);
+            const name = String(database.name || '');
+            const rawStableKey = rawConfiguredStableKey(database, stableKeyName);
+            const invalidDatabaseStableKey = rawStableKey.present && (typeof rawStableKey.value !== 'string' || !rawStableKey.value.trim());
+            if (invalidDatabaseStableKey) {
+                const reason = `Invalid database-schema stableKey on ${resourceId}: metadata.${stableKeyName} must be a non-empty string.`;
+                items.push({
+                    resourceType: 'database-schema', resourceId, name, category, action: 'blocked',
+                    metadataField: 'metadata', stableKeyName, reason,
+                });
+            }
+            else {
+                const existingStableKey = readConfiguredResourceMetadataStableKey(database, stableKeyName);
+                const stableKey = existingStableKey || buildNamedResourceGeneratedStableKey(database);
+                items.push({
+                    resourceType: 'database-schema', resourceId, name, category,
+                    action: existingStableKey ? 'skip' : 'update', metadataField: 'metadata', stableKeyName,
+                    stableKey,
+                    reason: existingStableKey ? 'stable key already exists' : 'assign-stable-key',
+                });
+            }
+            if (isDatabaseSchemaPartition(database)) {
+                continue;
+            }
+            const definitions = databaseDefinitions(database);
+            const columnsByStableKey = new Map();
+            const columnsByName = new Map();
+            const columnsByDefinitionId = new Map();
+            for (const definition of definitions) {
+                const columnName = typeof definition.name === 'string' ? definition.name.trim() : '';
+                if (columnName) {
+                    columnsByName.set(columnName, [...(columnsByName.get(columnName) || []), definition]);
+                }
+                const columnDefinitionId = typeof definition.databaseDefinitionId === 'string'
+                    ? definition.databaseDefinitionId.trim()
+                    : '';
+                if (columnDefinitionId) {
+                    columnsByDefinitionId.set(columnDefinitionId, [
+                        ...(columnsByDefinitionId.get(columnDefinitionId) || []),
+                        definition,
+                    ]);
+                }
+                const rawColumnStableKey = columnStableKeyValue(definition, stableKeyName);
+                if (typeof rawColumnStableKey.value === 'string' && rawColumnStableKey.value.trim()) {
+                    columnsByStableKey.set(rawColumnStableKey.value, [
+                        ...(columnsByStableKey.get(rawColumnStableKey.value) || []),
+                        { definition, name: columnName },
+                    ]);
+                }
+            }
+            const duplicateColumnStableKeys = new Set([...columnsByStableKey]
+                .filter(([, columns]) => columns.length > 1)
+                .map(([stableKeyValue]) => stableKeyValue));
+            const duplicateColumnNames = new Set([...columnsByName]
+                .filter(([, columns]) => columns.length > 1)
+                .map(([columnName]) => columnName));
+            const duplicateColumnDefinitionIds = new Set([...columnsByDefinitionId]
+                .filter(([, columns]) => columns.length > 1)
+                .map(([columnDefinitionId]) => columnDefinitionId));
+            for (const definition of definitions) {
+                const columnName = typeof definition.name === 'string' ? definition.name.trim() : '';
+                const columnDefinitionId = typeof definition.databaseDefinitionId === 'string'
+                    ? definition.databaseDefinitionId.trim()
+                    : '';
+                const rawColumnStableKey = columnStableKeyValue(definition, stableKeyName);
+                const existingColumnStableKey = typeof rawColumnStableKey.value === 'string' && rawColumnStableKey.value.trim()
+                    ? rawColumnStableKey.value
+                    : undefined;
+                const duplicate = existingColumnStableKey && duplicateColumnStableKeys.has(existingColumnStableKey);
+                const duplicateName = columnName && duplicateColumnNames.has(columnName);
+                const duplicateDefinitionId = columnDefinitionId && duplicateColumnDefinitionIds.has(columnDefinitionId);
+                const invalid = rawColumnStableKey.present && !existingColumnStableKey;
+                const columnReason = !columnName
+                    ? `Database column on ${resourceId} is missing a non-empty name; refusing to generate a Stable Key.`
+                    : !columnDefinitionId
+                        ? `Database column "${columnName}" on ${resourceId} is missing databaseDefinitionId; refusing to rewrite the full definition.`
+                        : duplicateName
+                            ? `Duplicate database column name "${columnName}" on root database schema ${resourceId}.`
+                            : duplicateDefinitionId
+                                ? `Duplicate database column databaseDefinitionId "${columnDefinitionId}" on root database schema ${resourceId}.`
+                                : invalid
+                                    ? `Invalid database column stableKey on ${resourceId}.${columnName}: definition[].metadata.${stableKeyName} must be a non-empty string.`
+                                    : duplicate
+                                        ? `Duplicate database column stableKey "${existingColumnStableKey}" on root database schema ${resourceId}.`
+                                        : existingColumnStableKey
+                                            ? 'column stable key already exists'
+                                            : 'assign-column-stable-key';
+                items.push({
+                    resourceType: 'database-schema',
+                    resourceId,
+                    name: `${name}.${columnName || '<unnamed>'}`,
+                    category,
+                    action: !columnName || !columnDefinitionId || duplicateName || duplicateDefinitionId || invalid || duplicate
+                        ? 'blocked'
+                        : existingColumnStableKey ? 'skip' : 'update',
+                    metadataField: 'definition[].metadata',
+                    stableKeyName,
+                    ...(columnName && existingColumnStableKey ? { stableKey: existingColumnStableKey } : columnName ? {
+                        stableKey: buildGeneratedDatabaseColumnStableKey(database, columnName),
+                    } : {}),
+                    ...(columnName ? { columnName } : {}),
+                    ...(columnDefinitionId ? { columnDefinitionId } : {}),
+                    reason: columnReason,
+                });
+            }
+        }
+    }
+    if (shouldTrackResource(trackedResources, 'database-view') && typeof client.listAllDatabaseViewsForSync === 'function') {
+        const views = await client.listAllDatabaseViewsForSync();
+        for (const view of views) {
+            const resourceId = resourceIdOf(view);
+            if (!resourceId) {
+                continue;
+            }
+            const category = normalizeValue(view.category);
+            const name = String(view.name || '');
+            const rawStableKey = rawConfiguredStableKey(view, stableKeyName);
+            if (rawStableKey.present && (typeof rawStableKey.value !== 'string' || !rawStableKey.value.trim())) {
+                const reason = `Invalid database-view stableKey on ${resourceId}: metadata.${stableKeyName} must be a non-empty string.`;
+                items.push({ resourceType: 'database-view', resourceId, name, category, action: 'blocked', metadataField: 'metadata', stableKeyName, reason });
+                continue;
+            }
+            const existingStableKey = readConfiguredResourceMetadataStableKey(view, stableKeyName);
+            const stableKey = existingStableKey || buildNamedResourceGeneratedStableKey(view);
+            items.push({
+                resourceType: 'database-view',
+                resourceId,
+                name,
+                category,
+                action: existingStableKey ? 'skip' : 'update',
+                metadataField: 'metadata',
+                stableKeyName,
+                stableKey,
+                reason: existingStableKey ? 'stable key already exists' : 'assign-stable-key',
+            });
+        }
+    }
+    if (shouldTrackResource(trackedResources, 'endpoint') && typeof client.listAllEndpoints === 'function') {
+        const { endpoints } = await client.listAllEndpoints();
+        for (const summary of endpoints) {
+            const summaryId = resourceIdOf(summary);
+            if (!summaryId) {
+                continue;
+            }
+            const endpoint = unwrapResource(await client.getEndpoint(summaryId));
+            const resourceId = resourceIdOf(endpoint) || summaryId;
+            const category = normalizeValue(endpoint.category);
+            const name = String(endpoint.name || '');
+            const exclusionReason = endpointExclusionReason(endpoint);
+            if (exclusionReason) {
+                items.push({
+                    resourceType: 'endpoint', resourceId, name, category, action: 'skip', metadataField: 'metadata', stableKeyName,
+                    reason: exclusionReason,
+                });
+                continue;
+            }
+            const rawStableKey = rawConfiguredStableKey(endpoint, stableKeyName);
+            if (rawStableKey.present && (typeof rawStableKey.value !== 'string' || !rawStableKey.value.trim())) {
+                const reason = `Invalid endpoint stableKey on ${resourceId}: metadata.${stableKeyName} must be a non-empty string.`;
+                items.push({ resourceType: 'endpoint', resourceId, name, category, action: 'blocked', metadataField: 'metadata', stableKeyName, reason });
+                continue;
+            }
+            const existingStableKey = readConfiguredResourceMetadataStableKey(endpoint, stableKeyName);
+            const stableKey = existingStableKey && !force ? undefined : buildNamedResourceGeneratedStableKey(endpoint);
+            const plannedStableKey = stableKey || existingStableKey || undefined;
+            items.push({
+                resourceType: 'endpoint', resourceId, name, category,
+                action: existingStableKey && !force ? 'skip' : 'update', metadataField: 'metadata', stableKeyName,
+                ...(plannedStableKey ? { stableKey: plannedStableKey } : {}),
+                reason: existingStableKey
+                    ? (force ? 'stable key will be regenerated' : 'stable key already exists')
+                    : 'stable key missing',
+            });
+        }
+    }
+    if (shouldTrackResource(trackedResources, 'role-group') && typeof client.listAllRoleGroups === 'function') {
+        const { roleGroups } = await client.listAllRoleGroups();
+        for (const summary of roleGroups) {
+            const summaryId = resourceIdOf(summary);
+            if (!summaryId) {
+                continue;
+            }
+            const roleGroup = unwrapResource(await client.getRoleGroup(summaryId));
+            const resourceId = resourceIdOf(roleGroup) || summaryId;
+            const existingStableKey = readConfiguredResourceMetadataStableKey(roleGroup, stableKeyName);
+            const stableKey = existingStableKey && !force
+                ? undefined
+                : buildGeneratedStableKey(roleGroup);
+            const plannedStableKey = stableKey || existingStableKey || undefined;
+            items.push({
+                resourceType: 'role-group',
+                resourceId,
+                name: String(roleGroup.name || ''),
+                category: normalizeValue(roleGroup.category),
+                action: existingStableKey && !force ? 'skip' : 'update',
+                metadataField: 'metadata',
+                stableKeyName,
+                ...(plannedStableKey ? { stableKey: plannedStableKey } : {}),
+                reason: existingStableKey
+                    ? (force ? 'stable key will be regenerated' : 'stable key already exists')
+                    : 'stable key missing',
+            });
+        }
+    }
+    if (shouldTrackResource(trackedResources, 'group') && typeof client.listAllGroups === 'function') {
+        const { groups } = await client.listAllGroups();
+        for (const summary of groups) {
+            const summaryId = resourceIdOf(summary);
+            if (!summaryId) {
+                continue;
+            }
+            const group = unwrapResource(await client.getGroup(summaryId));
+            const resourceId = resourceIdOf(group) || summaryId;
+            const existingStableKey = readConfiguredResourceMetadataStableKey(group, stableKeyName);
+            const stableKey = existingStableKey && !force
+                ? undefined
+                : buildNamedResourceGeneratedStableKey(group);
+            const plannedStableKey = stableKey || existingStableKey || undefined;
+            items.push({
+                resourceType: 'group',
+                resourceId,
+                name: String(group.name || ''),
+                category: normalizeValue(group.category),
+                action: existingStableKey && !force ? 'skip' : 'update',
+                metadataField: 'metadata',
+                stableKeyName,
+                ...(plannedStableKey ? { stableKey: plannedStableKey } : {}),
+                reason: groupMetadataBackfillReason(group, existingStableKey, force),
+            });
+        }
+    }
+    if (shouldTrackResource(trackedResources, 'job-template') && typeof client.listAllJobTemplates === 'function') {
+        const { jobTemplates } = await client.listAllJobTemplates();
+        for (const summary of jobTemplates) {
+            const summaryId = resourceIdOf(summary);
+            if (!summaryId)
+                continue;
+            const jobTemplate = unwrapResource(await client.getJobTemplate(summaryId));
+            const resourceId = resourceIdOf(jobTemplate) || summaryId;
+            const rawStableKey = rawConfiguredStableKey(jobTemplate, stableKeyName);
+            if (rawStableKey.present && (typeof rawStableKey.value !== 'string' || !rawStableKey.value.trim())) {
+                const reason = `Invalid job-template stableKey on ${resourceId}: metadata.${stableKeyName} must be a non-empty string.`;
+                items.push({
+                    resourceType: 'job-template', resourceId, name: String(jobTemplate.name || ''), category: normalizeValue(jobTemplate.category),
+                    action: 'blocked', metadataField: 'metadata', stableKeyName, reason,
+                });
+                continue;
+            }
+            const existingStableKey = readConfiguredResourceMetadataStableKey(jobTemplate, stableKeyName);
+            const stableKey = existingStableKey && !force ? undefined : buildNamedResourceGeneratedStableKey(jobTemplate);
+            const plannedStableKey = stableKey || existingStableKey || undefined;
+            items.push({
+                resourceType: 'job-template',
+                resourceId,
+                name: String(jobTemplate.name || ''),
+                category: normalizeValue(jobTemplate.category),
+                action: existingStableKey && !force ? 'skip' : 'update',
+                metadataField: 'metadata',
+                stableKeyName,
+                ...(plannedStableKey ? { stableKey: plannedStableKey } : {}),
+                reason: existingStableKey
+                    ? (force ? 'stable key will be regenerated' : 'stable key already exists')
+                    : 'stable key missing',
+            });
+        }
+    }
+    if (shouldTrackResource(trackedResources, 'schedule') && typeof client.listAllSchedules === 'function') {
+        const { schedules } = await client.listAllSchedules();
+        for (const summary of schedules) {
+            const summaryId = resourceIdOf(summary);
+            if (!summaryId) {
+                continue;
+            }
+            const schedule = unwrapResource(await client.getSchedule(summaryId));
+            const resourceId = resourceIdOf(schedule) || summaryId;
+            const category = normalizeValue(schedule.category);
+            const name = String(schedule.name || '');
+            const exclusionReason = scheduleExclusionReason(schedule);
+            if (exclusionReason) {
+                items.push({
+                    resourceType: 'schedule', resourceId, name, category, action: 'skip', metadataField: 'metadata', stableKeyName,
+                    reason: exclusionReason,
+                });
+                continue;
+            }
+            const rawStableKey = rawConfiguredStableKey(schedule, stableKeyName);
+            if (rawStableKey.present && (typeof rawStableKey.value !== 'string' || !rawStableKey.value.trim())) {
+                const reason = `Invalid schedule stableKey on ${resourceId}: metadata.${stableKeyName} must be a non-empty string.`;
+                items.push({ resourceType: 'schedule', resourceId, name, category, action: 'blocked', metadataField: 'metadata', stableKeyName, reason });
+                continue;
+            }
+            const existingStableKey = readConfiguredResourceMetadataStableKey(schedule, stableKeyName);
+            const stableKey = existingStableKey && !force ? undefined : buildNamedResourceGeneratedStableKey(schedule);
+            const plannedStableKey = stableKey || existingStableKey || undefined;
+            items.push({
+                resourceType: 'schedule', resourceId, name, category,
+                action: existingStableKey && !force ? 'skip' : 'update', metadataField: 'metadata', stableKeyName,
+                ...(plannedStableKey ? { stableKey: plannedStableKey } : {}),
+                reason: existingStableKey
+                    ? (force ? 'stable key will be regenerated' : 'stable key already exists')
+                    : 'stable key missing',
+            });
+        }
+    }
+    if (shouldTrackResource(trackedResources, 'event') && typeof client.listAllEvents === 'function') {
+        const { events } = await client.listAllEvents({ includeDeleted: true });
+        for (const summary of events) {
+            const summaryId = resourceIdOf(summary);
+            if (!summaryId) {
+                continue;
+            }
+            const event = unwrapResource(await client.getEvent(summaryId));
+            const resourceId = resourceIdOf(event) || summaryId;
+            const category = normalizeValue(event.category);
+            const name = String(event.name || '');
+            const exclusionReason = eventExclusionReason(event);
+            if (exclusionReason) {
+                items.push({
+                    resourceType: 'event', resourceId, name, category, action: 'skip', metadataField: 'metadata', stableKeyName,
+                    reason: exclusionReason,
+                });
+                continue;
+            }
+            const rawStableKey = rawConfiguredStableKey(event, stableKeyName);
+            if (rawStableKey.present && (typeof rawStableKey.value !== 'string' || !rawStableKey.value.trim())) {
+                const reason = `Invalid event stableKey on ${resourceId}: metadata.${stableKeyName} must be a non-empty string.`;
+                items.push({ resourceType: 'event', resourceId, name, category, action: 'blocked', metadataField: 'metadata', stableKeyName, reason });
+                continue;
+            }
+            const existingStableKey = readConfiguredResourceMetadataStableKey(event, stableKeyName);
+            const stableKey = existingStableKey && !force ? undefined : buildNamedResourceGeneratedStableKey(event);
+            const plannedStableKey = stableKey || existingStableKey || undefined;
+            items.push({
+                resourceType: 'event', resourceId, name, category,
+                action: existingStableKey && !force ? 'skip' : 'update', metadataField: 'metadata', stableKeyName,
+                ...(plannedStableKey ? { stableKey: plannedStableKey } : {}),
+                reason: existingStableKey
+                    ? (force ? 'stable key will be regenerated' : 'stable key already exists')
+                    : 'stable key missing',
+            });
+        }
+    }
+    const blockers = items.filter((item) => item.action === 'blocked').map((item) => item.reason);
+    const itemsByStableKey = new Map();
+    for (const item of items) {
+        if (item.metadataField !== 'metadata'
+            || !item.stableKey
+            || ((item.resourceType === 'schedule' || item.resourceType === 'event') && item.action === 'skip' && item.reason !== 'stable key already exists')) {
+            continue;
+        }
+        const identity = metadataStableKeyIdentity(item.resourceType, item.stableKey);
+        itemsByStableKey.set(identity, [...(itemsByStableKey.get(identity) || []), item]);
+    }
+    for (const duplicates of itemsByStableKey.values()) {
+        if (duplicates.length < 2) {
+            continue;
+        }
+        const stableKey = duplicates[0].stableKey;
+        const resourceType = duplicates[0].resourceType;
+        const reason = `Duplicate ${resourceType} stableKey "${stableKey}" on ${envName}.`;
+        blockers.push(reason);
+        for (const item of duplicates) {
+            item.action = 'blocked';
+            item.reason = reason;
+        }
+    }
+    items.sort((left, right) => left.resourceType.localeCompare(right.resourceType)
+        || buildStableKey({ name: left.name, category: left.category }).localeCompare(buildStableKey({ name: right.name, category: right.category }))
+        || left.resourceId.localeCompare(right.resourceId));
+    const counts = {
+        update: items.filter((item) => item.action === 'update').length,
+        skip: items.filter((item) => item.action === 'skip').length,
+        blocked: items.filter((item) => item.action === 'blocked').length,
+    };
+    return {
+        schemaVersion: 1,
+        generatedAt: new Date().toISOString(),
+        env: envName,
+        baseUrl: client.baseUrl,
+        instance: client.instance,
+        stableKeyName,
+        trackedResources,
+        force,
+        ...(skipPartitions ? { skipPartitions: true } : {}),
+        counts,
+        blockers: [...new Set(blockers)].sort((left, right) => left.localeCompare(right)),
+        items,
+    };
+}
+export async function applyMetadataBackfillPlan(input) {
+    const { client, plan } = input;
+    if (client.baseUrl !== plan.baseUrl || client.instance !== plan.instance) {
+        throw new Error(`Metadata plan target ${plan.baseUrl} (${plan.instance}) does not match selected target ${client.baseUrl} (${client.instance || 'unknown'}).`);
+    }
+    if (plan.blockers.length > 0) {
+        throw new Error(`Metadata plan has ${plan.blockers.length} blocking validation error(s): ${plan.blockers.join(' ')}`);
+    }
+    if (plan.items.some((item) => item.action === 'blocked')) {
+        throw new Error('Metadata plan contains blocked items and cannot be applied.');
+    }
+    const currentResources = new Map();
+    const resourceTypes = new Set(plan.items.map((item) => item.resourceType));
+    if (resourceTypes.has('component')) {
+        const { components } = await client.listAllComponents();
+        for (const summary of components) {
+            const id = resourceIdOf(summary);
+            if (id)
+                currentResources.set(`component:${id}`, unwrapResource(await client.getComponent(id)));
+        }
+    }
+    if (resourceTypes.has('database-schema')) {
+        const { databases } = await client.listAllDatabaseSchemas({
+            projection: 'pull',
+            skipPartitions: plan.skipPartitions,
+        });
+        for (const database of databases) {
+            if (isDatabaseBackupArtifact(database)) {
+                continue;
+            }
+            const id = resourceIdOf(database);
+            if (id) {
+                currentResources.set(`database-schema:${id}`, database);
+            }
+        }
+    }
+    if (resourceTypes.has('database-view')) {
+        const views = await client.listAllDatabaseViewsForSync();
+        for (const view of views) {
+            const id = resourceIdOf(view);
+            if (id) {
+                currentResources.set(`database-view:${id}`, view);
+            }
+        }
+    }
+    if (resourceTypes.has('endpoint')) {
+        const { endpoints } = await client.listAllEndpoints();
+        for (const summary of endpoints) {
+            const id = resourceIdOf(summary);
+            if (id) {
+                currentResources.set(`endpoint:${id}`, unwrapResource(await client.getEndpoint(id)));
+            }
+        }
+    }
+    if (resourceTypes.has('role-group')) {
+        const { roleGroups } = await client.listAllRoleGroups();
+        for (const summary of roleGroups) {
+            const id = resourceIdOf(summary);
+            if (id)
+                currentResources.set(`role-group:${id}`, unwrapResource(await client.getRoleGroup(id)));
+        }
+    }
+    if (resourceTypes.has('group')) {
+        const { groups } = await client.listAllGroups();
+        for (const summary of groups) {
+            const id = resourceIdOf(summary);
+            if (id) {
+                currentResources.set(`group:${id}`, unwrapResource(await client.getGroup(id)));
+            }
+        }
+    }
+    if (resourceTypes.has('job-template')) {
+        const { jobTemplates } = await client.listAllJobTemplates();
+        for (const summary of jobTemplates) {
+            const id = resourceIdOf(summary);
+            if (id)
+                currentResources.set(`job-template:${id}`, unwrapResource(await client.getJobTemplate(id)));
+        }
+    }
+    if (resourceTypes.has('schedule')) {
+        const { schedules } = await client.listAllSchedules();
+        for (const summary of schedules) {
+            const id = resourceIdOf(summary);
+            if (id) {
+                currentResources.set(`schedule:${id}`, unwrapResource(await client.getSchedule(id)));
+            }
+        }
+    }
+    if (resourceTypes.has('event')) {
+        const { events } = await client.listAllEvents({ includeDeleted: true });
+        for (const summary of events) {
+            const id = resourceIdOf(summary);
+            if (id) {
+                currentResources.set(`event:${id}`, unwrapResource(await client.getEvent(id)));
+            }
+        }
+    }
+    const stableKeyOwners = new Map();
+    for (const [identity, resource] of currentResources) {
+        const resourceType = identity.slice(0, identity.indexOf(':'));
+        if (resourceType === 'schedule' && scheduleExclusionReason(resource)) {
+            continue;
+        }
+        if (resourceType === 'event' && eventExclusionReason(resource)) {
+            continue;
+        }
+        if (resourceType === 'endpoint' && endpointExclusionReason(resource)) {
+            continue;
+        }
+        const stableKey = readConfiguredResourceMetadataStableKey(resource, plan.stableKeyName);
+        if (!stableKey)
+            continue;
+        const key = metadataStableKeyIdentity(resourceType, stableKey);
+        if (stableKeyOwners.has(key))
+            throw new Error(`Duplicate ${resourceType} stableKey "${stableKey}" detected before apply.`);
+        stableKeyOwners.set(key, identity);
+    }
+    for (const item of plan.items.filter((candidate) => candidate.action === 'update' && candidate.stableKey)) {
+        if (item.metadataField !== 'metadata') {
+            continue;
+        }
+        const owner = stableKeyOwners.get(metadataStableKeyIdentity(item.resourceType, item.stableKey));
+        if (owner && owner !== `${item.resourceType}:${item.resourceId}`) {
+            throw new Error(`Planned ${item.resourceType} stableKey "${item.stableKey}" is already assigned to another resource.`);
+        }
+    }
+    if (!plan.force) {
+        for (const item of plan.items.filter((candidate) => (candidate.resourceType === 'endpoint'
+            || candidate.resourceType === 'job-template'
+            || candidate.resourceType === 'schedule'
+            || candidate.resourceType === 'event') && candidate.action === 'update')) {
+            const resource = currentResources.get(`${item.resourceType}:${item.resourceId}`);
+            if (!resource) {
+                continue;
+            }
+            const rawStableKey = rawConfiguredStableKey(resource, plan.stableKeyName);
+            if (rawStableKey.present && (typeof rawStableKey.value !== 'string' || !rawStableKey.value.trim())) {
+                throw new Error(`Invalid ${item.resourceType} stableKey appeared before apply on ${item.resourceId}; refusing to overwrite it without --force.`);
+            }
+        }
+    }
+    const results = [];
+    let databaseMutationStarted = false;
+    const columnUpdatesByDatabase = new Map();
+    for (const item of plan.items) {
+        if (item.resourceType === 'database-schema' && item.metadataField === 'definition[].metadata' && item.action === 'update') {
+            columnUpdatesByDatabase.set(item.resourceId, [
+                ...(columnUpdatesByDatabase.get(item.resourceId) || []),
+                item,
+            ]);
+        }
+    }
+    const processedColumnUpdateDatabases = new Set();
+    for (const item of plan.items) {
+        if (item.action === 'skip') {
+            results.push({
+                resourceType: item.resourceType,
+                resourceId: item.resourceId,
+                ...(item.columnName ? { columnName: item.columnName } : {}),
+                ...(item.stableKey ? { stableKey: item.stableKey } : {}),
+                action: 'skip',
+            });
+            continue;
+        }
+        if (item.action !== 'update') {
+            throw new Error(`Unsupported metadata plan action: ${item.action}.`);
+        }
+        try {
+            if (item.resourceType === 'component') {
+                const component = currentResources.get(`component:${item.resourceId}`);
+                if (!component)
+                    throw new Error('component no longer exists');
+                const currentStableKey = readConfiguredResourceMetadataStableKey(component, plan.stableKeyName);
+                if (currentStableKey && !plan.force) {
+                    results.push({ resourceType: item.resourceType, resourceId: item.resourceId, stableKey: currentStableKey, action: 'skip' });
+                    continue;
+                }
+                const stableKey = item.stableKey || buildGeneratedStableKey(component);
+                await client.updateComponent(item.resourceId, buildMetadataUpdatePayload(component, plan.stableKeyName, stableKey, item.resourceType));
+                results.push({
+                    resourceType: item.resourceType,
+                    resourceId: item.resourceId,
+                    stableKey,
+                    action: 'update',
+                });
+                continue;
+            }
+            if (item.resourceType === 'database-schema') {
+                const listed = currentResources.get(`database-schema:${item.resourceId}`);
+                if (!listed) {
+                    throw new Error('database schema no longer exists');
+                }
+                if (item.metadataField === 'definition[].metadata' && processedColumnUpdateDatabases.has(item.resourceId)) {
+                    continue;
+                }
+                const live = unwrapResource(await client.getDatabaseSchema(item.resourceId));
+                if (item.metadataField === 'definition[].metadata') {
+                    if (isDatabaseSchemaPartition(live)) {
+                        throw new Error('database schema became a partition; column stable keys are inherited from the root');
+                    }
+                    const assignments = [];
+                    for (const columnItem of columnUpdatesByDatabase.get(item.resourceId) || []) {
+                        const columnName = columnItem.columnName;
+                        const columnDefinitionId = columnItem.columnDefinitionId;
+                        if (!columnName || !columnDefinitionId) {
+                            throw new Error(`database schema column metadata plan for ${item.resourceId} is missing its live identity`);
+                        }
+                        const definitions = databaseDefinitions(live).filter((candidate) => candidate.databaseDefinitionId === columnDefinitionId);
+                        if (definitions.length !== 1 || definitions[0].name !== columnName) {
+                            throw new Error(`database schema column "${columnName}" no longer matches databaseDefinitionId "${columnDefinitionId}"`);
+                        }
+                        const definition = definitions[0];
+                        const rawColumnStableKey = columnStableKeyValue(definition, plan.stableKeyName);
+                        if (typeof rawColumnStableKey.value === 'string' && rawColumnStableKey.value.trim()) {
+                            results.push({
+                                resourceType: columnItem.resourceType,
+                                resourceId: columnItem.resourceId,
+                                columnName,
+                                stableKey: rawColumnStableKey.value,
+                                action: 'skip',
+                            });
+                            continue;
+                        }
+                        if (rawColumnStableKey.present) {
+                            throw new Error(`Invalid database column stableKey appeared before apply on ${item.resourceId}.${columnName}; refusing to overwrite it.`);
+                        }
+                        assignments.push({
+                            item: columnItem,
+                            definition,
+                            stableKey: columnItem.stableKey || buildGeneratedDatabaseColumnStableKey(live, columnName),
+                        });
+                    }
+                    processedColumnUpdateDatabases.add(item.resourceId);
+                    if (assignments.length === 0) {
+                        continue;
+                    }
+                    if (databaseMutationStarted) {
+                        await waitForMutationSlot();
+                    }
+                    databaseMutationStarted = true;
+                    await client.updateDatabaseSchema(item.resourceId, buildDatabaseColumnMetadataUpdatePayload({
+                        database: live,
+                        assignments,
+                        stableKeyName: plan.stableKeyName,
+                    }));
+                    for (const assignment of assignments) {
+                        results.push({
+                            resourceType: assignment.item.resourceType,
+                            resourceId: assignment.item.resourceId,
+                            columnName: assignment.item.columnName,
+                            stableKey: assignment.stableKey,
+                            action: 'update',
+                        });
+                    }
+                    continue;
+                }
+                const currentStableKey = readConfiguredResourceMetadataStableKey(live, plan.stableKeyName);
+                if (currentStableKey) {
+                    results.push({ resourceType: item.resourceType, resourceId: item.resourceId, stableKey: currentStableKey, action: 'skip' });
+                    continue;
+                }
+                const rawStableKey = rawConfiguredStableKey(live, plan.stableKeyName);
+                if (rawStableKey.present) {
+                    throw new Error(`Invalid database-schema stableKey appeared before apply on ${item.resourceId}; refusing to overwrite it.`);
+                }
+                if (databaseMutationStarted) {
+                    await waitForMutationSlot();
+                }
+                databaseMutationStarted = true;
+                const stableKey = item.stableKey || buildNamedResourceGeneratedStableKey(live);
+                await client.updateDatabaseSchemaMetadata(item.resourceId, buildMetadataUpdatePayload(live, plan.stableKeyName, stableKey, item.resourceType));
+                results.push({ resourceType: item.resourceType, resourceId: item.resourceId, stableKey, action: 'update' });
+                continue;
+            }
+            if (item.resourceType === 'database-view') {
+                const view = currentResources.get(`database-view:${item.resourceId}`);
+                if (!view) {
+                    throw new Error('database view no longer exists');
+                }
+                const currentStableKey = readConfiguredResourceMetadataStableKey(view, plan.stableKeyName);
+                if (currentStableKey) {
+                    results.push({ resourceType: item.resourceType, resourceId: item.resourceId, stableKey: currentStableKey, action: 'skip' });
+                    continue;
+                }
+                const rawStableKey = rawConfiguredStableKey(view, plan.stableKeyName);
+                if (rawStableKey.present) {
+                    throw new Error(`Invalid database-view stableKey appeared before apply on ${item.resourceId}; refusing to overwrite it.`);
+                }
+                const stableKey = item.stableKey || buildNamedResourceGeneratedStableKey(view);
+                await client.updateDatabaseView(item.resourceId, buildDatabaseViewMetadataUpdatePayload(view, plan.stableKeyName, stableKey));
+                const verified = unwrapResource(await client.getDatabaseView(item.resourceId));
+                const verifiedStableKey = readConfiguredResourceMetadataStableKey(verified, plan.stableKeyName);
+                if (verifiedStableKey !== stableKey) {
+                    throw new Error('updated database view did not retain the planned stable key');
+                }
+                results.push({ resourceType: item.resourceType, resourceId: item.resourceId, stableKey, action: 'update' });
+                continue;
+            }
+            if (item.resourceType === 'endpoint') {
+                const endpoint = currentResources.get(`endpoint:${item.resourceId}`);
+                if (!endpoint) {
+                    throw new Error('endpoint no longer exists');
+                }
+                const exclusionReason = endpointExclusionReason(endpoint);
+                if (exclusionReason) {
+                    throw new Error(`endpoint moved outside migration scope: ${exclusionReason}`);
+                }
+                const currentStableKey = readConfiguredResourceMetadataStableKey(endpoint, plan.stableKeyName);
+                if (currentStableKey && !plan.force) {
+                    results.push({ resourceType: item.resourceType, resourceId: item.resourceId, stableKey: currentStableKey, action: 'skip' });
+                    continue;
+                }
+                const stableKey = item.stableKey || buildNamedResourceGeneratedStableKey(endpoint);
+                await client.updateEndpoint(item.resourceId, buildMetadataUpdatePayload(endpoint, plan.stableKeyName, stableKey, item.resourceType));
+                const verifiedEndpoint = unwrapResource(await client.getEndpoint(item.resourceId));
+                const verifiedStableKey = readConfiguredResourceMetadataStableKey(verifiedEndpoint, plan.stableKeyName);
+                if (verifiedStableKey !== stableKey) {
+                    throw new Error('updated endpoint did not retain the planned stable key');
+                }
+                results.push({ resourceType: item.resourceType, resourceId: item.resourceId, stableKey, action: 'update' });
+                continue;
+            }
+            if (item.resourceType === 'role-group') {
+                const roleGroup = currentResources.get(`role-group:${item.resourceId}`);
+                if (!roleGroup)
+                    throw new Error('role-group no longer exists');
+                const currentStableKey = readConfiguredResourceMetadataStableKey(roleGroup, plan.stableKeyName);
+                if (currentStableKey && !plan.force) {
+                    results.push({ resourceType: item.resourceType, resourceId: item.resourceId, stableKey: currentStableKey, action: 'skip' });
+                    continue;
+                }
+                const stableKey = item.stableKey || buildGeneratedStableKey(roleGroup);
+                await client.updateRoleGroup(item.resourceId, buildMetadataUpdatePayload(roleGroup, plan.stableKeyName, stableKey, item.resourceType));
+                results.push({
+                    resourceType: item.resourceType,
+                    resourceId: item.resourceId,
+                    stableKey,
+                    action: 'update',
+                });
+                continue;
+            }
+            if (item.resourceType === 'group') {
+                const group = currentResources.get(`group:${item.resourceId}`);
+                if (!group) {
+                    throw new Error('group no longer exists');
+                }
+                const currentStableKey = readConfiguredResourceMetadataStableKey(group, plan.stableKeyName);
+                if (currentStableKey && !plan.force) {
+                    results.push({ resourceType: item.resourceType, resourceId: item.resourceId, stableKey: currentStableKey, action: 'skip' });
+                    continue;
+                }
+                const stableKey = item.stableKey || buildNamedResourceGeneratedStableKey(group);
+                await client.updateGroup(item.resourceId, buildMetadataUpdatePayload(group, plan.stableKeyName, stableKey, item.resourceType));
+                results.push({
+                    resourceType: item.resourceType,
+                    resourceId: item.resourceId,
+                    stableKey,
+                    action: 'update',
+                });
+                continue;
+            }
+            if (item.resourceType === 'job-template') {
+                const jobTemplate = currentResources.get(`job-template:${item.resourceId}`);
+                if (!jobTemplate)
+                    throw new Error('job-template no longer exists');
+                const currentStableKey = readConfiguredResourceMetadataStableKey(jobTemplate, plan.stableKeyName);
+                if (currentStableKey && !plan.force) {
+                    results.push({ resourceType: item.resourceType, resourceId: item.resourceId, stableKey: currentStableKey, action: 'skip' });
+                    continue;
+                }
+                const stableKey = item.stableKey || buildNamedResourceGeneratedStableKey(jobTemplate);
+                await client.updateJobTemplate(item.resourceId, buildJobTemplateMetadataUpdatePayload(jobTemplate, plan.stableKeyName, stableKey));
+                results.push({ resourceType: item.resourceType, resourceId: item.resourceId, stableKey, action: 'update' });
+                continue;
+            }
+            if (item.resourceType === 'schedule') {
+                const schedule = currentResources.get(`schedule:${item.resourceId}`);
+                if (!schedule) {
+                    throw new Error('schedule no longer exists');
+                }
+                const exclusionReason = scheduleExclusionReason(schedule);
+                if (exclusionReason) {
+                    throw new Error(`schedule moved outside migration scope: ${exclusionReason}`);
+                }
+                const currentStableKey = readConfiguredResourceMetadataStableKey(schedule, plan.stableKeyName);
+                if (currentStableKey && !plan.force) {
+                    results.push({ resourceType: item.resourceType, resourceId: item.resourceId, stableKey: currentStableKey, action: 'skip' });
+                    continue;
+                }
+                const stableKey = item.stableKey || buildNamedResourceGeneratedStableKey(schedule);
+                await client.updateSchedule(item.resourceId, buildMetadataUpdatePayload(schedule, plan.stableKeyName, stableKey, item.resourceType));
+                results.push({ resourceType: item.resourceType, resourceId: item.resourceId, stableKey, action: 'update' });
+                continue;
+            }
+            if (item.resourceType === 'event') {
+                const event = currentResources.get(`event:${item.resourceId}`);
+                if (!event) {
+                    throw new Error('event no longer exists');
+                }
+                const exclusionReason = eventExclusionReason(event);
+                if (exclusionReason) {
+                    throw new Error(`event moved outside migration scope: ${exclusionReason}`);
+                }
+                const currentStableKey = readConfiguredResourceMetadataStableKey(event, plan.stableKeyName);
+                if (currentStableKey && !plan.force) {
+                    results.push({ resourceType: item.resourceType, resourceId: item.resourceId, stableKey: currentStableKey, action: 'skip' });
+                    continue;
+                }
+                const stableKey = item.stableKey || buildNamedResourceGeneratedStableKey(event);
+                await client.updateEvent(item.resourceId, buildMetadataUpdatePayload(event, plan.stableKeyName, stableKey, item.resourceType));
+                results.push({ resourceType: item.resourceType, resourceId: item.resourceId, stableKey, action: 'update' });
+                continue;
+            }
+            throw new Error(`unsupported resource type: ${item.resourceType}`);
+        }
+        catch (error) {
+            results.push({
+                resourceType: item.resourceType,
+                resourceId: item.resourceId,
+                stableKey: item.stableKey,
+                ...(item.columnName ? { columnName: item.columnName } : {}),
+                action: 'failed',
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    if (resourceTypes.has('database-schema')) {
+        try {
+            const { databases } = await client.listAllDatabaseSchemas({
+                projection: 'pull',
+                skipPartitions: plan.skipPartitions,
+            });
+            const verified = new Map(databases
+                .filter((database) => !isDatabaseBackupArtifact(database))
+                .map((database) => [resourceIdOf(database), database]));
+            for (const result of results.filter((candidate) => candidate.resourceType === 'database-schema' && candidate.action === 'update')) {
+                const database = verified.get(result.resourceId);
+                const definition = result.columnName && database
+                    ? databaseDefinitions(database).find((candidate) => candidate.name === result.columnName)
+                    : undefined;
+                const stableKey = result.columnName
+                    ? (definition
+                        ? columnStableKeyValue(definition, plan.stableKeyName).value
+                        : null)
+                    : (database
+                        ? readConfiguredResourceMetadataStableKey(database, plan.stableKeyName)
+                        : null);
+                if (stableKey !== result.stableKey) {
+                    result.action = 'failed';
+                    result.error = 'final verification did not find the assigned stable key';
+                }
+            }
+        }
+        catch (error) {
+            for (const result of results.filter((candidate) => candidate.resourceType === 'database-schema' && candidate.action === 'update')) {
+                result.action = 'failed';
+                result.error = `final verification failed: ${error instanceof Error ? error.message : String(error)}`;
+            }
+        }
+    }
+    return results;
+}