@revoengine/cli 1.0.9 → 1.0.11

package/dist/src/resource-syncs/event-sync.js

@@ -0,0 +1,949 @@
+import path from 'node:path';
+import { hashStable, readComponentLock, writeComponentLock } from "../component-lock.js";
+import { NULL_CATEGORY_KEY, normalizeStableKeyValue, readConfiguredResourceMetadataStableKey, sanitizeUserMetadata } from "../resource-metadata.js";
+import { readJsonFile, sanitizeSegment } from "../utils.js";
+import { findManifestFiles, isRecord, localTargetPath, requireProjectLayout, stableKeySuffix, toPortableRelativePath, unwrapData, writePulledManifest, } from "./util.js";
+export const EVENTS_DIRECTORY = 'Events';
+export const EVENT_MANIFEST_FILE = 'event.json';
+const EVENT_TRANSPORT_FIELDS = new Set([
+    'jobEventId', 'eventId', 'id', 'name', 'category', 'desc', 'description', 'active', 'type',
+    'targetType', 'targetId', 'targetVersion', 'targetConfig', 'filter', 'version', 'metadata',
+    'metaData', 'resourceMetadata', 'topic', 'deletedAt', 'deletedBy', 'createdAt', 'createdBy',
+    'lastUpdateAt', 'lastUpdateBy', 'updatedAt', 'updatedBy', 'history', 'jobEventHistory',
+]);
+function eventIdOf(record) {
+    return String(record.jobEventId || record.eventId || record.id || '');
+}
+function jobTemplateIdOf(record) {
+    return String(record.jobTemplateId || record.id || '');
+}
+function canonicalValue(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => canonicalValue(item));
+    }
+    if (!isRecord(value)) {
+        return value;
+    }
+    return Object.fromEntries(Object.keys(value).sort((left, right) => left.localeCompare(right))
+        .map((key) => [key, canonicalValue(value[key])]));
+}
+function canonicalMetadata(record, stableKeyName, stableKey) {
+    return canonicalValue({
+        ...sanitizeUserMetadata(record.resourceMetadata),
+        ...sanitizeUserMetadata(record.metaData),
+        ...sanitizeUserMetadata(record.metadata),
+        [stableKeyName]: stableKey,
+    });
+}
+function extensionFields(record) {
+    return canonicalValue(Object.fromEntries(Object.entries(record)
+        .filter(([key, value]) => !EVENT_TRANSPORT_FIELDS.has(key) && value !== undefined)));
+}
+function eventExclusionReason(record) {
+    if (record.deletedAt || record.deletedBy) {
+        return 'deleted event is excluded';
+    }
+    if (record.targetType !== 'JOB_TEMPLATE') {
+        return `target type ${String(record.targetType || 'unknown')} is unsupported; only JOB_TEMPLATE is migrated`;
+    }
+    return undefined;
+}
+function eventPresentationKey(value) {
+    const category = typeof value.category === 'string' && value.category.trim()
+        ? value.category
+        : NULL_CATEGORY_KEY;
+    return normalizeStableKeyValue(`${category}/${String(value.name || '')}`);
+}
+export function eventManifestPath(workspaceRoot, manifest) {
+    const category = typeof manifest.category === 'string' && manifest.category.trim()
+        ? sanitizeSegment(manifest.category)
+        : 'Uncategorized';
+    return path.join(workspaceRoot, EVENTS_DIRECTORY, category, `${sanitizeSegment(manifest.name)}-${stableKeySuffix(manifest.stableKey)}`, EVENT_MANIFEST_FILE);
+}
+function portablePathIdentity(filePath) {
+    return path.resolve(filePath)
+        .normalize('NFC')
+        .split(path.sep)
+        .map((segment) => segment.replace(/[. ]+$/g, '').toLowerCase())
+        .join(path.sep);
+}
+function disambiguateManifestPath(filePath, stableKey) {
+    const directory = path.dirname(filePath);
+    return path.join(path.dirname(directory), `${path.basename(directory)}-${hashStable(stableKey).slice(0, 8)}`, path.basename(filePath));
+}
+function readWorkspaceEvents(cwd) {
+    const { workspaceRoot } = requireProjectLayout(cwd, 'Event');
+    return findManifestFiles(path.join(workspaceRoot, EVENTS_DIRECTORY), EVENT_MANIFEST_FILE).map((manifestPath) => ({
+        manifestPath,
+        manifest: readJsonFile(manifestPath),
+    }));
+}
+function nonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function validManifest(value, stableKeyName) {
+    if (!isRecord(value) || value.kind !== 'event' || !nonEmptyString(value.stableKey) || !nonEmptyString(value.name)
+        || !nonEmptyString(value.type) || !isRecord(value.metadata) || !isRecord(value.target)) {
+        return false;
+    }
+    if (value.category !== undefined && value.category !== null && typeof value.category !== 'string') {
+        return false;
+    }
+    if (value.description !== undefined && typeof value.description !== 'string') {
+        return false;
+    }
+    if (typeof value.active !== 'boolean' || value.target.type !== 'JOB_TEMPLATE' || !nonEmptyString(value.target.jobTemplateStableKey)) {
+        return false;
+    }
+    if (value.filter !== undefined && value.filter !== null && !isRecord(value.filter)) {
+        return false;
+    }
+    if (value.extensions !== undefined && !isRecord(value.extensions)) {
+        return false;
+    }
+    if (value.extensions !== undefined && Object.keys(value.extensions).length > 0) {
+        return false;
+    }
+    return readConfiguredResourceMetadataStableKey(value, stableKeyName) === value.stableKey;
+}
+function manifestFromRecord(input) {
+    const { record, stableKey, jobTemplateStableKey, stableKeyName } = input;
+    const extensions = extensionFields(record);
+    return {
+        kind: 'event',
+        stableKey,
+        name: String(record.name || ''),
+        ...(record.category === undefined ? {} : { category: record.category }),
+        ...(typeof record.desc === 'string' ? { description: record.desc } : typeof record.description === 'string' ? { description: record.description } : {}),
+        metadata: canonicalMetadata(record, stableKeyName, stableKey),
+        active: record.active === true,
+        type: String(record.type || ''),
+        ...(record.filter === undefined ? {} : { filter: canonicalValue(record.filter) }),
+        target: { type: 'JOB_TEMPLATE', jobTemplateStableKey },
+        ...(Object.keys(extensions).length > 0 ? { extensions } : {}),
+    };
+}
+export function hashEventContent(manifest) {
+    return hashStable({
+        kind: 'event', stableKey: manifest.stableKey, name: manifest.name, category: manifest.category ?? null,
+        description: manifest.description ?? '', metadata: canonicalValue(manifest.metadata), type: manifest.type,
+        filter: canonicalValue(manifest.filter ?? null), target: manifest.target, extensions: canonicalValue(manifest.extensions || {}),
+    });
+}
+export function hashPortableEvent(manifest) {
+    return hashStable({ content: hashEventContent(manifest), active: manifest.active });
+}
+export function hashEventManifest(manifest) {
+    return hashStable(canonicalValue(manifest));
+}
+async function hydrate(records, idOf, get) {
+    return Promise.all(records.map(async (record) => {
+        const id = idOf(record);
+        return id ? unwrapData(await get(id)) : record;
+    }));
+}
+async function loadRemoteEventInventory(client, stableKeyName) {
+    const [{ events: eventSummaries }, { jobTemplates: templateSummaries }] = await Promise.all([
+        client.listAllEvents({ includeDeleted: true }), client.listAllJobTemplates(),
+    ]);
+    const [events, jobTemplates] = await Promise.all([
+        hydrate(eventSummaries, eventIdOf, (id) => client.getEvent(id)),
+        hydrate(templateSummaries, jobTemplateIdOf, (id) => client.getJobTemplate(id)),
+    ]);
+    const eventsByStableKey = new Map();
+    const jobTemplatesByStableKey = new Map();
+    const jobTemplatesById = new Map();
+    for (const event of events) {
+        const stableKey = readConfiguredResourceMetadataStableKey(event, stableKeyName);
+        if (stableKey) {
+            eventsByStableKey.set(stableKey, [...(eventsByStableKey.get(stableKey) || []), event]);
+        }
+    }
+    for (const jobTemplate of jobTemplates) {
+        const id = jobTemplateIdOf(jobTemplate);
+        const stableKey = readConfiguredResourceMetadataStableKey(jobTemplate, stableKeyName);
+        if (id) {
+            jobTemplatesById.set(id, jobTemplate);
+        }
+        if (stableKey) {
+            jobTemplatesByStableKey.set(stableKey, [...(jobTemplatesByStableKey.get(stableKey) || []), jobTemplate]);
+        }
+    }
+    return { events, eventsByStableKey, jobTemplatesById, jobTemplatesByStableKey };
+}
+function emptyPlanCounts() {
+    return {
+        clean: 0,
+        create: 0,
+        'safe-update': 0,
+        'remote-changed': 0,
+        conflict: 0,
+        'missing-lock': 0,
+        'activation-drift': 0,
+        orphan: 0,
+        collision: 0,
+        skipped: 0,
+    };
+}
+function diffEvents(desired, current) {
+    const fields = [
+        ['name', desired.name, current.name],
+        ['category', desired.category ?? null, current.category ?? null],
+        ['description', desired.description ?? '', current.description ?? ''],
+        ['metadata', desired.metadata, current.metadata],
+        ['type', desired.type, current.type],
+        ['filter', desired.filter ?? null, current.filter ?? null],
+        ['target.jobTemplateStableKey', desired.target.jobTemplateStableKey, current.target.jobTemplateStableKey],
+        ['extensions', desired.extensions || {}, current.extensions || {}],
+    ];
+    return fields
+        .filter(([, left, right]) => hashStable(left) !== hashStable(right))
+        .map(([field]) => field)
+        .sort();
+}
+function eventManifestFromTarget(record, templatesById, templatesByStableKey, stableKeyName) {
+    const stableKey = readConfiguredResourceMetadataStableKey(record, stableKeyName);
+    if (!stableKey) {
+        return { reason: `missing ${stableKeyName}; unmanaged` };
+    }
+    const exclusion = eventExclusionReason(record);
+    if (exclusion) {
+        return { stableKey, reason: exclusion };
+    }
+    const template = record.targetId ? templatesById.get(record.targetId) : undefined;
+    const jobTemplateStableKey = template
+        ? readConfiguredResourceMetadataStableKey(template, stableKeyName)
+        : undefined;
+    if (!jobTemplateStableKey) {
+        return { stableKey, reason: 'target Job Template dependency is missing stableKey or unavailable', dependencyBlocked: true };
+    }
+    const matchingTemplates = templatesByStableKey.get(jobTemplateStableKey) || [];
+    if (matchingTemplates.length !== 1) {
+        return {
+            stableKey,
+            reason: `target Job Template dependency "${jobTemplateStableKey}" is ambiguous`,
+            dependencyBlocked: true,
+        };
+    }
+    return { stableKey, manifest: manifestFromRecord({ record, stableKey, jobTemplateStableKey, stableKeyName }) };
+}
+export async function buildEventsPlan(input) {
+    const { projectRoot } = requireProjectLayout(input.cwd, 'Event');
+    const remote = await loadRemoteEventInventory(input.client, input.stableKeyName);
+    const targetEvents = remote.events;
+    const templatesById = remote.jobTemplatesById;
+    const templatesByStableKey = remote.jobTemplatesByStableKey;
+    const blockers = [];
+    const exclusions = [];
+    const items = [];
+    const localByStableKey = new Map();
+    for (const entry of readWorkspaceEvents(input.cwd)) {
+        const manifest = entry.manifest;
+        if (!validManifest(manifest, input.stableKeyName)) {
+            const unsupportedExtensions = isRecord(manifest) && isRecord(manifest.extensions)
+                ? Object.keys(manifest.extensions).sort()
+                : [];
+            const reason = unsupportedExtensions.length > 0
+                ? `unsupported extension fields: ${unsupportedExtensions.join(', ')}`
+                : 'invalid manifest';
+            blockers.push(`Invalid Event manifest ${path.relative(projectRoot, entry.manifestPath)}: ${reason}.`);
+            items.push({ status: 'conflict', name: isRecord(manifest) && nonEmptyString(manifest.name) ? manifest.name : path.basename(entry.manifestPath), reason });
+            continue;
+        }
+        localByStableKey.set(manifest.stableKey, [...(localByStableKey.get(manifest.stableKey) || []), { manifest }]);
+    }
+    for (const [stableKey, localEvents] of localByStableKey) {
+        if (localEvents.length > 1) {
+            blockers.push(`Duplicate local Event stableKey "${stableKey}".`);
+            for (const local of localEvents) {
+                items.push({ status: 'collision', stableKey, name: local.manifest.name, reason: 'duplicate workspace stableKey' });
+            }
+        }
+    }
+    const targetsByStableKey = new Map();
+    const targetIssuesByStableKey = new Map();
+    for (const record of targetEvents) {
+        const target = eventManifestFromTarget(record, templatesById, templatesByStableKey, input.stableKeyName);
+        if ('manifest' in target) {
+            const targetEvent = {
+                manifest: target.manifest,
+                hash: hashPortableEvent(target.manifest),
+                contentHash: hashEventContent(target.manifest),
+            };
+            targetsByStableKey.set(target.stableKey, [...(targetsByStableKey.get(target.stableKey) || []), targetEvent]);
+            continue;
+        }
+        const label = target.stableKey || String(record.name || eventIdOf(record) || 'unknown event');
+        if (target.dependencyBlocked) {
+            blockers.push(`Cannot plan Event "${label}": ${target.reason}.`);
+            items.push({ status: 'conflict', ...(target.stableKey ? { stableKey: target.stableKey } : {}), name: String(record.name || label), reason: target.reason });
+        }
+        else {
+            exclusions.push(`${label}: ${target.reason}`);
+            items.push({ status: 'skipped', ...(target.stableKey ? { stableKey: target.stableKey } : {}), name: String(record.name || label), reason: target.reason });
+        }
+        if (target.stableKey) {
+            targetIssuesByStableKey.set(target.stableKey, target.reason);
+        }
+    }
+    for (const [stableKey, targets] of targetsByStableKey) {
+        if (targets.length <= 1) {
+            continue;
+        }
+        blockers.push(`Duplicate target Event stableKey "${stableKey}".`);
+        for (const target of targets) {
+            items.push({
+                status: 'collision',
+                stableKey,
+                name: target.manifest.name,
+                currentHash: target.hash,
+                reason: 'duplicate target stableKey',
+            });
+        }
+    }
+    const lock = readComponentLock(projectRoot);
+    const consumedTargets = new Set();
+    for (const [stableKey, localEvents] of localByStableKey) {
+        if (localEvents.length !== 1) {
+            continue;
+        }
+        const desired = localEvents[0].manifest;
+        const templates = templatesByStableKey.get(desired.target.jobTemplateStableKey) || [];
+        if (templates.length !== 1) {
+            const reason = `target Job Template dependency "${desired.target.jobTemplateStableKey}" is ${templates.length === 0 ? 'missing' : 'ambiguous'}`;
+            blockers.push(`Cannot plan Event "${stableKey}": ${reason}.`);
+            items.push({ status: 'conflict', stableKey, name: desired.name, reason, jobTemplateStableKey: desired.target.jobTemplateStableKey });
+            continue;
+        }
+        const targets = targetsByStableKey.get(stableKey) || [];
+        const common = {
+            stableKey,
+            name: desired.name,
+            desiredHash: hashPortableEvent(desired),
+            jobTemplateStableKey: desired.target.jobTemplateStableKey,
+        };
+        if (targets.length > 1) {
+            consumedTargets.add(stableKey);
+            continue;
+        }
+        if (targets.length === 0) {
+            const targetIssue = targetIssuesByStableKey.get(stableKey);
+            if (targetIssue) {
+                blockers.push(`Cannot plan Event "${stableKey}": ${targetIssue}.`);
+                items.push({ status: 'conflict', ...common, reason: targetIssue });
+            }
+            else if (targetEvents.some((record) => !record.deletedAt
+                && !record.deletedBy
+                && !readConfiguredResourceMetadataStableKey(record, input.stableKeyName)
+                && eventPresentationKey(record) === eventPresentationKey(desired))) {
+                const reason = `target Event matching category/name is missing ${input.stableKeyName}`;
+                blockers.push(`Cannot plan Event "${stableKey}": ${reason}.`);
+                items.push({ status: 'conflict', ...common, reason });
+            }
+            else {
+                items.push({ status: 'create', ...common });
+            }
+            continue;
+        }
+        consumedTargets.add(stableKey);
+        const current = targets[0];
+        const currentHash = current.hash;
+        const baselineHash = lock.events[stableKey]?.environments[input.envName]?.remoteHash;
+        const currentContentHash = current.contentHash;
+        const desiredContentHash = hashEventContent(desired);
+        if (desiredContentHash === currentContentHash && desired.active !== current.manifest.active) {
+            items.push({ status: 'activation-drift', ...common, currentHash, baselineHash, reason: `source active=${desired.active}; target active=${current.manifest.active}` });
+        }
+        else if (common.desiredHash === currentHash) {
+            items.push({ status: 'clean', ...common, currentHash, ...(baselineHash ? { baselineHash } : {}) });
+        }
+        else if (!baselineHash) {
+            items.push({ status: 'missing-lock', ...common, currentHash, reason: `missing ${input.envName} lock baseline` });
+        }
+        else if (currentHash === baselineHash) {
+            items.push({ status: 'safe-update', ...common, currentHash, baselineHash, changedFields: diffEvents(desired, current.manifest), reason: 'local manifest changed; target matches lock baseline' });
+        }
+        else if (common.desiredHash === baselineHash) {
+            items.push({ status: 'remote-changed', ...common, currentHash, baselineHash, changedFields: diffEvents(desired, current.manifest), reason: 'target changed; local manifest matches lock baseline' });
+        }
+        else {
+            items.push({ status: 'conflict', ...common, currentHash, baselineHash, changedFields: diffEvents(desired, current.manifest), reason: 'local manifest and target both changed since lock baseline' });
+        }
+    }
+    for (const [stableKey, targets] of targetsByStableKey) {
+        if (consumedTargets.has(stableKey) || localByStableKey.has(stableKey)) {
+            continue;
+        }
+        if (targets.length === 1) {
+            items.push({ status: 'orphan', stableKey, name: targets[0].manifest.name, currentHash: targets[0].hash, reason: 'target-only Event' });
+        }
+    }
+    const rank = {
+        create: 0,
+        'safe-update': 1,
+        'remote-changed': 2,
+        conflict: 3,
+        'missing-lock': 4,
+        'activation-drift': 5,
+        clean: 6,
+        orphan: 7,
+        collision: 8,
+        skipped: 9,
+    };
+    items.sort((left, right) => rank[left.status] - rank[right.status] || (left.stableKey || left.name).localeCompare(right.stableKey || right.name));
+    const counts = emptyPlanCounts();
+    for (const item of items) {
+        counts[item.status] += 1;
+    }
+    return {
+        resourceType: 'event',
+        env: input.envName,
+        counts,
+        blockers: [...new Set(blockers)].sort(),
+        items,
+        exclusions: [...new Set(exclusions)].sort(),
+    };
+}
+function buildEventCreatePayload(manifest, targetId) {
+    const extensions = writableEventExtensions(manifest.extensions);
+    return {
+        ...extensions,
+        name: manifest.name,
+        ...(manifest.category === undefined || manifest.category === null ? {} : { category: manifest.category }),
+        active: false,
+        ...(manifest.description === undefined ? {} : { desc: manifest.description }),
+        metadata: canonicalValue(manifest.metadata),
+        type: manifest.type,
+        ...(manifest.filter === undefined ? {} : { filter: canonicalValue(manifest.filter) }),
+        targetType: 'JOB_TEMPLATE',
+        targetId,
+    };
+}
+function buildEventUpdatePayload(manifest, targetId, version) {
+    const extensions = writableEventExtensions(manifest.extensions);
+    return {
+        ...extensions,
+        name: manifest.name,
+        category: manifest.category ?? null,
+        desc: manifest.description ?? '',
+        metadata: canonicalValue(manifest.metadata),
+        type: manifest.type,
+        filter: canonicalValue(manifest.filter ?? null),
+        targetType: 'JOB_TEMPLATE',
+        targetId,
+        version,
+    };
+}
+function writableEventExtensions(extensions) {
+    return canonicalValue(Object.fromEntries(Object.entries(extensions || {})
+        .filter(([key]) => !EVENT_TRANSPORT_FIELDS.has(key))));
+}
+function workspaceEventsByStableKey(cwd, stableKeyName) {
+    const events = new Map();
+    for (const entry of readWorkspaceEvents(cwd)) {
+        if (!validManifest(entry.manifest, stableKeyName)) {
+            continue;
+        }
+        events.set(entry.manifest.stableKey, { manifestPath: entry.manifestPath, manifest: entry.manifest });
+    }
+    return events;
+}
+function updateEventEnvironmentBaseline(input) {
+    const { projectRoot } = requireProjectLayout(input.cwd, 'Event');
+    const lock = readComponentLock(projectRoot);
+    const stableKey = input.manifest.stableKey;
+    const existingPair = Object.entries(lock.events).find(([, entry]) => entry.stableKey === stableKey);
+    const existing = existingPair?.[1];
+    if (existingPair && existingPair[0] !== stableKey) {
+        delete lock.events[existingPair[0]];
+    }
+    const previousBaseline = existing?.environments[input.envName];
+    lock.events[stableKey] = {
+        stableKey,
+        path: toPortableRelativePath(projectRoot, input.manifestPath),
+        sourceHash: hashEventManifest(input.manifest),
+        environments: {
+            ...(existing?.environments || {}),
+            [input.envName]: previousBaseline?.remoteHash === input.remoteHash
+                ? previousBaseline
+                : { remoteHash: input.remoteHash, syncedAt: new Date().toISOString() },
+        },
+    };
+    writeComponentLock(projectRoot, lock);
+}
+function eventPushError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function assertEventsPushable(plan, force) {
+    if (plan.blockers.length > 0) {
+        throw new Error(`Event push blocked: ${plan.blockers.join(' ')}`);
+    }
+    const contentBlockers = plan.items.filter((item) => ['missing-lock', 'remote-changed', 'conflict'].includes(item.status));
+    if (contentBlockers.length > 0 && !force) {
+        const statuses = [...new Set(contentBlockers.map((item) => item.status))].sort().join(', ');
+        throw new Error(`Event push blocked by ${statuses}; review the plan and re-run with --force only to adopt or overwrite reviewed content drift.`);
+    }
+}
+async function resolveLiveEventWriteTarget(input) {
+    const remote = input.inventory || await loadRemoteEventInventory(input.client, input.stableKeyName);
+    const dependencies = remote.jobTemplatesByStableKey.get(input.manifest.target.jobTemplateStableKey) || [];
+    if (dependencies.length !== 1) {
+        const reason = dependencies.length === 0 ? 'is missing' : 'is ambiguous';
+        throw new Error(`target Job Template dependency "${input.manifest.target.jobTemplateStableKey}" ${reason}`);
+    }
+    const jobTemplateId = jobTemplateIdOf(dependencies[0]);
+    if (!jobTemplateId) {
+        throw new Error(`target Job Template dependency "${input.manifest.target.jobTemplateStableKey}" has no jobTemplateId`);
+    }
+    const matches = remote.eventsByStableKey.get(input.manifest.stableKey) || [];
+    if (input.action === 'create') {
+        if (matches.length > 0) {
+            throw new Error(`target Event "${input.manifest.stableKey}" appeared after planning`);
+        }
+        const nameMatches = remote.events.filter((event) => !event.deletedAt
+            && !event.deletedBy
+            && eventPresentationKey(event) === eventPresentationKey(input.manifest));
+        if (nameMatches.length > 0) {
+            throw new Error(`target Event matching category/name for "${input.manifest.stableKey}" appeared after planning`);
+        }
+        return { jobTemplateId };
+    }
+    if (matches.length !== 1) {
+        throw new Error(`expected one live target Event match, found ${matches.length}`);
+    }
+    const event = matches[0];
+    const exclusion = eventExclusionReason(event);
+    if (exclusion) {
+        throw new Error(`live target Event is excluded: ${exclusion}`);
+    }
+    const eventId = eventIdOf(event);
+    if (!eventId || typeof event.version !== 'number') {
+        throw new Error('live target Event did not include id and version');
+    }
+    const currentTemplate = event.targetId ? remote.jobTemplatesById.get(event.targetId) : undefined;
+    const currentTemplateStableKey = currentTemplate
+        ? readConfiguredResourceMetadataStableKey(currentTemplate, input.stableKeyName)
+        : undefined;
+    if (!currentTemplateStableKey) {
+        throw new Error('live target Event dependency is missing or unmanaged');
+    }
+    const currentManifest = manifestFromRecord({
+        record: event,
+        stableKey: input.manifest.stableKey,
+        jobTemplateStableKey: currentTemplateStableKey,
+        stableKeyName: input.stableKeyName,
+    });
+    return {
+        jobTemplateId,
+        event,
+        eventId,
+        currentHash: hashPortableEvent(currentManifest),
+        active: currentManifest.active,
+    };
+}
+async function verifyEventWrite(input) {
+    const event = unwrapData(await input.client.getEvent(input.eventId));
+    if (readConfiguredResourceMetadataStableKey(event, input.stableKeyName) !== input.manifest.stableKey) {
+        throw new Error(`verified Event is missing or changed ${input.stableKeyName}`);
+    }
+    if (event.targetType !== 'JOB_TEMPLATE' || event.targetId !== input.jobTemplateId) {
+        throw new Error('verified Event target does not match the live Job Template dependency');
+    }
+    let jobTemplate = input.jobTemplatesById?.get(input.jobTemplateId);
+    if (!jobTemplate) {
+        jobTemplate = unwrapData(await input.client.getJobTemplate(input.jobTemplateId));
+        input.jobTemplatesById?.set(input.jobTemplateId, jobTemplate);
+    }
+    if (readConfiguredResourceMetadataStableKey(jobTemplate, input.stableKeyName) !== input.manifest.target.jobTemplateStableKey) {
+        throw new Error('verified Event target Job Template does not match the desired stable key');
+    }
+    const verifiedManifest = manifestFromRecord({
+        record: event,
+        stableKey: input.manifest.stableKey,
+        jobTemplateStableKey: input.manifest.target.jobTemplateStableKey,
+        stableKeyName: input.stableKeyName,
+    });
+    if (hashEventContent(verifiedManifest) !== hashEventContent(input.manifest)) {
+        throw new Error('written Event did not match desired portable configuration');
+    }
+    if (verifiedManifest.active !== input.expectedActive) {
+        throw new Error('written Event did not preserve the expected target activation state');
+    }
+    return hashPortableEvent(verifiedManifest);
+}
+export async function pushEvents(input) {
+    const plan = await buildEventsPlan(input);
+    assertEventsPushable(plan, input.force === true);
+    const localByKey = workspaceEventsByStableKey(input.cwd, input.stableKeyName);
+    const results = [];
+    const verifiedActivationCandidates = [];
+    const writeCandidates = plan.items.filter((item) => (item.status === 'create'
+        || item.status === 'safe-update'
+        || item.status === 'activation-drift'
+        || (input.force === true && ['missing-lock', 'remote-changed', 'conflict'].includes(item.status))));
+    const liveInventory = writeCandidates.length > 0
+        ? await loadRemoteEventInventory(input.client, input.stableKeyName)
+        : undefined;
+    const processWrite = async (item, action) => {
+        const stableKey = item.stableKey || '';
+        const local = localByKey.get(stableKey);
+        const targetPath = local ? localTargetPath(input.cwd, local.manifestPath) : stableKey;
+        try {
+            if (!local) {
+                throw new Error('desired manifest disappeared after planning');
+            }
+            if (hashPortableEvent(local.manifest) !== item.desiredHash) {
+                throw new Error('desired manifest changed after planning');
+            }
+            const live = await resolveLiveEventWriteTarget({
+                client: input.client,
+                stableKeyName: input.stableKeyName,
+                manifest: local.manifest,
+                action,
+                inventory: liveInventory,
+            });
+            let eventId;
+            let expectedActive;
+            if (action === 'create') {
+                const created = unwrapData(await input.client.createEvent(buildEventCreatePayload(local.manifest, live.jobTemplateId)));
+                eventId = eventIdOf(created);
+                if (!eventId) {
+                    const freshInventory = await loadRemoteEventInventory(input.client, input.stableKeyName);
+                    const resolvedCreated = await resolveLiveEventWriteTarget({
+                        client: input.client,
+                        stableKeyName: input.stableKeyName,
+                        manifest: local.manifest,
+                        action: 'update',
+                        inventory: freshInventory,
+                    });
+                    if (!resolvedCreated.eventId) {
+                        throw new Error('created Event could not be resolved by stableKey');
+                    }
+                    eventId = resolvedCreated.eventId;
+                }
+                else if (liveInventory) {
+                    liveInventory.events.push(created);
+                    liveInventory.eventsByStableKey.set(local.manifest.stableKey, [created]);
+                }
+                expectedActive = false;
+            }
+            else {
+                if (!live.eventId || !live.event || typeof live.event.version !== 'number' || live.active === undefined) {
+                    throw new Error('live target Event did not include id, version, and activation state');
+                }
+                if (live.currentHash !== item.currentHash) {
+                    throw new Error('target Event changed after planning');
+                }
+                await input.client.updateEvent(live.eventId, buildEventUpdatePayload(local.manifest, live.jobTemplateId, live.event.version));
+                eventId = live.eventId;
+                expectedActive = live.active;
+            }
+            const remoteHash = await verifyEventWrite({
+                client: input.client,
+                stableKeyName: input.stableKeyName,
+                manifest: local.manifest,
+                eventId,
+                jobTemplateId: live.jobTemplateId,
+                expectedActive,
+                jobTemplatesById: liveInventory?.jobTemplatesById,
+            });
+            updateEventEnvironmentBaseline({
+                cwd: input.cwd,
+                envName: input.envName,
+                manifest: local.manifest,
+                manifestPath: local.manifestPath,
+                remoteHash,
+            });
+            results.push({ stableKey, action, status: 'deployed', targetPath });
+            if (local.manifest.active !== expectedActive) {
+                verifiedActivationCandidates.push({
+                    stableKey,
+                    eventId,
+                    targetPath,
+                    manifestPath: local.manifestPath,
+                    manifest: local.manifest,
+                    stableKeyName: input.stableKeyName,
+                    cwd: input.cwd,
+                    envName: input.envName,
+                });
+            }
+        }
+        catch (error) {
+            results.push({ stableKey, action, status: 'failed', targetPath, error: eventPushError(error) });
+        }
+    };
+    for (const item of plan.items.filter((candidate) => candidate.status === 'create')) {
+        await processWrite(item, 'create');
+    }
+    for (const item of plan.items.filter((candidate) => (candidate.status === 'safe-update'
+        || (input.force === true && ['missing-lock', 'remote-changed', 'conflict'].includes(candidate.status))))) {
+        await processWrite(item, 'update');
+    }
+    for (const item of plan.items.filter((candidate) => candidate.status === 'clean')) {
+        const local = item.stableKey ? localByKey.get(item.stableKey) : undefined;
+        if (local && item.currentHash) {
+            updateEventEnvironmentBaseline({
+                cwd: input.cwd,
+                envName: input.envName,
+                manifest: local.manifest,
+                manifestPath: local.manifestPath,
+                remoteHash: item.currentHash,
+            });
+        }
+        results.push({
+            stableKey: item.stableKey || item.name,
+            action: 'noop',
+            status: 'skipped',
+            targetPath: local ? localTargetPath(input.cwd, local.manifestPath) : item.stableKey || item.name,
+            reason: 'no local changes',
+        });
+    }
+    for (const item of plan.items.filter((candidate) => candidate.status === 'activation-drift')) {
+        const local = item.stableKey ? localByKey.get(item.stableKey) : undefined;
+        if (local) {
+            try {
+                const live = await resolveLiveEventWriteTarget({
+                    client: input.client,
+                    stableKeyName: input.stableKeyName,
+                    manifest: local.manifest,
+                    action: 'update',
+                    inventory: liveInventory,
+                });
+                if (!live.eventId || live.active === undefined) {
+                    throw new Error('live target Event did not include id and activation state');
+                }
+                if (live.currentHash !== item.currentHash) {
+                    throw new Error('target Event changed after planning');
+                }
+                if (live.active !== local.manifest.active) {
+                    verifiedActivationCandidates.push({
+                        stableKey: local.manifest.stableKey,
+                        eventId: live.eventId,
+                        targetPath: localTargetPath(input.cwd, local.manifestPath),
+                        manifestPath: local.manifestPath,
+                        manifest: local.manifest,
+                        stableKeyName: input.stableKeyName,
+                        cwd: input.cwd,
+                        envName: input.envName,
+                    });
+                }
+            }
+            catch (error) {
+                results.push({
+                    stableKey: item.stableKey || item.name,
+                    action: 'noop',
+                    status: 'failed',
+                    targetPath: localTargetPath(input.cwd, local.manifestPath),
+                    error: eventPushError(error),
+                });
+                continue;
+            }
+        }
+        results.push({
+            stableKey: item.stableKey || item.name,
+            action: 'noop',
+            status: 'skipped',
+            targetPath: local ? localTargetPath(input.cwd, local.manifestPath) : item.stableKey || item.name,
+            reason: 'activation differs; re-run with --activate to align it with source',
+        });
+    }
+    for (const item of plan.items.filter((candidate) => candidate.status === 'orphan')) {
+        results.push({ stableKey: item.stableKey || item.name, action: 'orphan', status: 'skipped', targetPath: item.stableKey || item.name, reason: 'target-only orphan' });
+    }
+    for (const item of plan.items.filter((candidate) => candidate.status === 'skipped')) {
+        results.push({ stableKey: item.stableKey || item.name, action: 'skipped', status: 'skipped', targetPath: item.stableKey || item.name, reason: item.reason || 'unmanaged' });
+    }
+    return { plan, results, verifiedActivationCandidates };
+}
+export async function activateVerifiedEvents(input) {
+    const results = [];
+    const jobTemplatesCache = new Map();
+    for (const candidate of input.candidates) {
+        const action = candidate.manifest.active ? 'activate' : 'disable';
+        try {
+            const current = unwrapData(await input.client.getEvent(candidate.eventId));
+            if (readConfiguredResourceMetadataStableKey(current, candidate.stableKeyName) !== candidate.stableKey) {
+                throw new Error('target Event stable key changed after activation preflight');
+            }
+            if (current.active === candidate.manifest.active) {
+                results.push({
+                    stableKey: candidate.stableKey,
+                    action,
+                    status: 'skipped',
+                    targetPath: candidate.targetPath,
+                    reason: 'already aligned',
+                });
+                continue;
+            }
+            if (candidate.manifest.active) {
+                await input.client.activateEvent(candidate.eventId);
+            }
+            else {
+                await input.client.disableEvent(candidate.eventId);
+            }
+            const remoteHash = await verifyEventWrite({
+                client: input.client,
+                stableKeyName: candidate.stableKeyName,
+                manifest: candidate.manifest,
+                eventId: candidate.eventId,
+                jobTemplateId: String(current.targetId || ''),
+                expectedActive: candidate.manifest.active,
+                jobTemplatesById: jobTemplatesCache,
+            });
+            updateEventEnvironmentBaseline({
+                cwd: candidate.cwd,
+                envName: candidate.envName,
+                manifest: candidate.manifest,
+                manifestPath: candidate.manifestPath,
+                remoteHash,
+            });
+            results.push({
+                stableKey: candidate.stableKey,
+                action,
+                status: 'deployed',
+                targetPath: candidate.targetPath,
+            });
+        }
+        catch (error) {
+            results.push({
+                stableKey: candidate.stableKey,
+                action,
+                status: 'failed',
+                targetPath: candidate.targetPath,
+                error: eventPushError(error),
+            });
+        }
+    }
+    return results;
+}
+export async function pullEventsToWorkspace(input) {
+    const { projectRoot, workspaceRoot } = requireProjectLayout(input.cwd, 'Event');
+    const [{ events: summaries }, { jobTemplates: templateSummaries }] = await Promise.all([
+        input.client.listAllEvents({ includeDeleted: true }), input.client.listAllJobTemplates(),
+    ]);
+    const [events, templates] = await Promise.all([
+        hydrate(summaries, eventIdOf, (id) => input.client.getEvent(id)),
+        hydrate(templateSummaries, jobTemplateIdOf, (id) => input.client.getJobTemplate(id)),
+    ]);
+    const templatesById = new Map(templates.map((template) => [jobTemplateIdOf(template), template]));
+    const manifests = [];
+    const warnings = [];
+    const seen = new Set();
+    for (const record of events) {
+        const stableKey = readConfiguredResourceMetadataStableKey(record, input.stableKeyName);
+        const label = stableKey || String(record.name || eventIdOf(record) || 'unknown event');
+        const exclusion = eventExclusionReason(record);
+        if (exclusion) {
+            warnings.push({ stableKey: label, reason: exclusion });
+            continue;
+        }
+        if (!stableKey) {
+            warnings.push({ stableKey: label, reason: `missing ${input.stableKeyName}; unmanaged` });
+            continue;
+        }
+        const target = record.targetId ? templatesById.get(record.targetId) : undefined;
+        const jobTemplateStableKey = target ? readConfiguredResourceMetadataStableKey(target, input.stableKeyName) : undefined;
+        if (!jobTemplateStableKey) {
+            warnings.push({ stableKey, reason: 'target Job Template dependency is missing stableKey' });
+            continue;
+        }
+        if (seen.has(stableKey)) {
+            throw new Error(`Duplicate Event stableKey "${stableKey}" on source; no files were changed.`);
+        }
+        seen.add(stableKey);
+        const manifest = manifestFromRecord({ record, stableKey, jobTemplateStableKey, stableKeyName: input.stableKeyName });
+        manifests.push(manifest);
+    }
+    manifests.sort((left, right) => left.stableKey.localeCompare(right.stableKey));
+    warnings.sort((left, right) => left.stableKey.localeCompare(right.stableKey) || left.reason.localeCompare(right.reason));
+    const lock = readComponentLock(projectRoot);
+    const existingByKey = new Map();
+    const existingByPath = new Map();
+    for (const entry of readWorkspaceEvents(input.cwd)) {
+        const manifest = entry.manifest;
+        if (!validManifest(manifest, input.stableKeyName)) {
+            throw new Error(`Cannot pull over invalid Event manifest ${path.relative(projectRoot, entry.manifestPath)}.`);
+        }
+        if (existingByKey.has(manifest.stableKey)) {
+            throw new Error(`Duplicate local Event stableKey "${manifest.stableKey}"; no files were changed.`);
+        }
+        const localEntry = { manifestPath: entry.manifestPath, manifest };
+        existingByKey.set(manifest.stableKey, localEntry);
+        const pathIdentity = portablePathIdentity(entry.manifestPath);
+        existingByPath.set(pathIdentity, [...(existingByPath.get(pathIdentity) || []), localEntry]);
+    }
+    const writes = manifests.map((manifest) => {
+        const sourceHash = hashEventManifest(manifest);
+        const remoteHash = hashPortableEvent(manifest);
+        const existing = existingByKey.get(manifest.stableKey);
+        if (existing && !input.force) {
+            const localHash = hashEventManifest(existing.manifest);
+            const baseline = lock.events[manifest.stableKey];
+            if (localHash !== sourceHash && (!baseline || localHash !== baseline.sourceHash)) {
+                throw new Error(`Cannot pull Event "${manifest.stableKey}": local manifest changed since the lock baseline. Re-run with --force to overwrite.`);
+            }
+        }
+        return {
+            manifest,
+            sourceHash,
+            remoteHash,
+            targetPath: eventManifestPath(workspaceRoot, manifest),
+            previousPath: existing?.manifestPath,
+        };
+    });
+    const candidatePathCounts = new Map();
+    for (const write of writes) {
+        const pathIdentity = portablePathIdentity(write.targetPath);
+        candidatePathCounts.set(pathIdentity, (candidatePathCounts.get(pathIdentity) || 0) + 1);
+    }
+    for (const write of writes) {
+        if ((candidatePathCounts.get(portablePathIdentity(write.targetPath)) || 0) > 1) {
+            write.targetPath = disambiguateManifestPath(write.targetPath, write.manifest.stableKey);
+        }
+    }
+    const paths = new Set();
+    for (const write of writes) {
+        const pathIdentity = portablePathIdentity(write.targetPath);
+        if (paths.has(pathIdentity)) {
+            throw new Error('Multiple Events resolve to the same workspace path; no files were changed.');
+        }
+        paths.add(pathIdentity);
+        const pathOwner = (existingByPath.get(pathIdentity) || [])
+            .find((entry) => entry.manifest.stableKey !== write.manifest.stableKey);
+        if (pathOwner) {
+            throw new Error(`Event workspace path "${path.relative(projectRoot, write.targetPath)}" is occupied by different stableKey "${pathOwner.manifest.stableKey}"; no files were changed.`);
+        }
+    }
+    const root = path.join(workspaceRoot, EVENTS_DIRECTORY);
+    let lockChanged = false;
+    for (const write of writes) {
+        writePulledManifest({
+            filePath: write.targetPath,
+            manifest: write.manifest,
+            previousPath: write.previousPath,
+            root: root,
+            force: input.force,
+        });
+        const previous = lock.events[write.manifest.stableKey];
+        const previousBaseline = previous?.environments[input.envName];
+        const entry = {
+            stableKey: write.manifest.stableKey,
+            path: toPortableRelativePath(projectRoot, write.targetPath),
+            sourceHash: write.sourceHash,
+            environments: {
+                ...(previous?.environments || {}),
+                [input.envName]: previousBaseline?.remoteHash === write.remoteHash
+                    ? previousBaseline
+                    : { remoteHash: write.remoteHash, syncedAt: new Date().toISOString() },
+            },
+        };
+        if (!previous || hashStable(previous) !== hashStable(entry)) {
+            lockChanged = true;
+        }
+        lock.events[write.manifest.stableKey] = entry;
+    }
+    if (lockChanged) {
+        writeComponentLock(projectRoot, lock);
+    }
+    return { pulled: writes.map((write) => ({ manifest: write.manifest, targetPath: localTargetPath(input.cwd, write.targetPath) })), warnings };
+}