evolcore 0.0.6 → 0.0.8

package/dist/core/data-migration.js

@@ -1,4 +1,5 @@
 import crypto from 'crypto';
+import { execFileSync } from 'child_process';
 import fs from 'fs';
 import path from 'path';
 import { formatChannelSessionKey, scanLegacyChatDirs, scanMetaFiles, scanNestedAgentChatDirs, scanNonCanonicalAgentChatDirs, } from './session/session-fs-store.js';
@@ -18,6 +19,14 @@ function manifestPath(root, id) {
 function migrationStagingDir(root, id) {
     return path.join(migrationDir(root), `${id}.staging`);
 }
+function finalizationDir(root) {
+    // Keep receipts out of migrationDir's top level: readers there intentionally
+    // treat every *.json file as a migration manifest.
+    return path.join(migrationDir(root), 'finalized');
+}
+function finalizationPath(root, id) {
+    return path.join(finalizationDir(root), `${id}.json`);
+}
 function migrationPlanSignature(operations) {
     const topology = operations.map(operation => ({
         kind: operation.kind,
@@ -45,6 +54,32 @@ function operationTopologyKey(operation) {
         sessionChannelKey: operation.sessionChannelKey,
     });
 }
+/**
+ * Manifests written before allowExistingDestinationMerge was introduced still
+ * need safe recovery. Re-derive that narrow permission from their immutable
+ * source topology and the current owner-evidenced control identity; no other
+ * destination conflict is relaxed.
+ */
+function restoreLegacyControlMergeEligibility(manifest) {
+    const control = controlIdentity(manifest.root);
+    if (control.aids.size !== 1 || control.legacyAids.size === 0)
+        return;
+    const currentAid = control.aids.values().next().value;
+    const legacySessionsRoot = path.join(manifest.root, 'data', 'sessions', 'aun');
+    const expectedChannelKey = `aun#${currentAid}#main`;
+    const destinationRoot = path.join(manifest.root, 'agents', currentAid, 'sessions');
+    for (const operation of manifest.operations) {
+        if (operation.allowExistingDestinationMerge || operation.transform !== 'normalize-session-channel-key')
+            continue;
+        const relative = path.relative(legacySessionsRoot, operation.source);
+        const [legacyAid] = relative.split(path.sep);
+        if (!legacyAid || relative.startsWith(`..${path.sep}`) || !control.legacyAids.has(legacyAid))
+            continue;
+        if (operation.sessionChannelKey !== expectedChannelKey || !operation.destination || !isWithin(destinationRoot, operation.destination))
+            continue;
+        operation.allowExistingDestinationMerge = true;
+    }
+}
 function sessionDestination(root, aid, channelKey, channelId) {
     const channelType = channelKey === 'daemon' ? 'daemon' : channelKey.split('#', 1)[0]?.trim();
     if (!channelType)
@@ -201,7 +236,27 @@ function controlIdentity(root) {
                 owners.add(owner);
         }
     }
-    return { aids: new Set(aid ? [aid] : []), owners };
+    // A previous `ecNNNNN.<domain>` control identity has no Agent config, so
+    // its legacy AUN session root cannot be attributed through configuredAids.
+    // It is safe to recognize only when that root contains at least one current
+    // daemon owner: the whole root then belongs to the same process control
+    // plane, including sessions with its non-owner Agents.
+    const legacyAids = new Set();
+    if (aid && owners.size > 0) {
+        try {
+            for (const entry of fs.readdirSync(path.join(root, 'data', 'sessions', 'aun'), { withFileTypes: true })) {
+                if (!entry.isDirectory() || entry.name === aid || !/^ec\d{5}\.[^.]+(?:\..+)+$/i.test(entry.name))
+                    continue;
+                const sessionRoot = path.join(root, 'data', 'sessions', 'aun', entry.name);
+                const hasCurrentOwner = fs.readdirSync(sessionRoot, { withFileTypes: true })
+                    .some(child => child.isDirectory() && owners.has(child.name));
+                if (hasCurrentOwner)
+                    legacyAids.add(entry.name);
+            }
+        }
+        catch { }
+    }
+    return { aids: new Set(aid ? [aid] : []), owners, legacyAids };
 }
 function inferUnknownAunOwner(chat, control) {
     if (chat.channelType !== 'aun' || chat.selfAID !== '_unknown' || control.aids.size !== 1)
@@ -213,6 +268,11 @@ function inferUnknownAunOwner(chat, control) {
         return undefined;
     return control.aids.values().next().value;
 }
+function remapLegacyControlAunOwner(aid, control) {
+    if (control.aids.size !== 1 || !control.legacyAids.has(aid))
+        return undefined;
+    return control.aids.values().next().value;
+}
 function isOwnedTriggerDefinition(definition, aid, triggerId) {
     return !!definition
         && typeof definition === 'object'
@@ -416,6 +476,7 @@ function addMergeCopy(operations, id, source, destination, staging, exclude, tra
 export function planDataMigration(root) {
     const operations = [];
     const warnings = [];
+    const supersededSourceHashes = {};
     const id = `data-${Date.now().toString(36)}-${crypto.randomBytes(3).toString('hex')}`;
     const stagingDir = migrationStagingDir(root, id);
     const instances = listChannelInstances(root);
@@ -434,6 +495,12 @@ export function planDataMigration(root) {
         chats.add(channelId);
         legacyFeishuChats.set(channelKey, chats);
     };
+    const rememberSupersededSource = (source) => {
+        try {
+            supersededSourceHashes[source] = treeHash(source);
+        }
+        catch { }
+    };
     const addFeishuSeen = (source, channelKey, channelId, prefix) => {
         if (!fs.existsSync(source))
             return;
@@ -567,14 +634,21 @@ export function planDataMigration(root) {
                 const sessionId = nextId('trigger-session');
                 addSessionCopy(operations, sessionId, chat.dirPath, destination, stageFor(sessionId));
             }
+            else {
+                rememberSupersededSource(chat.dirPath);
+            }
             continue;
         }
         const fromChannel = parseChannelKey(record?.channel ?? record?.metadata?.channelKey);
-        const aid = chat.selfAID && chat.selfAID !== '_unknown'
+        const detectedAid = chat.selfAID && chat.selfAID !== '_unknown'
             ? chat.selfAID
             : (typeof record?.selfAID === 'string' && record.selfAID !== '_unknown'
                 ? record.selfAID
                 : fromChannel?.aid ?? inferUnknownAunOwner(chat, control));
+        const remappedControlAid = detectedAid && !aids.has(detectedAid) && !control.aids.has(detectedAid)
+            ? remapLegacyControlAunOwner(detectedAid, control)
+            : undefined;
+        const aid = remappedControlAid ?? detectedAid;
         if (!aid || aid === '_unknown') {
             warnings.push(`Unresolved session owner retained: ${chat.dirPath}`);
             continue;
@@ -599,6 +673,18 @@ export function planDataMigration(root) {
         if (!liveSessionDestinations.has(destination) && !nestedSessionDestinations.has(destination)) {
             const sessionId = nextId('session');
             addSessionCopy(operations, sessionId, chat.dirPath, destination, stageFor(sessionId), [SESSION_SEEN_FILE], 'normalize-session-channel-key', channelKey);
+            if (remappedControlAid) {
+                const operation = operations.find(item => item.destination === destination);
+                if (operation)
+                    operation.allowExistingDestinationMerge = true;
+            }
+        }
+        else {
+            // This retained data/sessions copy is older than an Agent-owned source
+            // selected for the same canonical destination. It must not be replayed,
+            // but --apply can archive and remove it as a verified
+            // superseded source instead of exposing it as a fresh migration again.
+            rememberSupersededSource(chat.dirPath);
         }
         if (chat.channelType === 'feishu') {
             rememberFeishuChat(channelKey, chat.channelId);
@@ -772,6 +858,7 @@ export function planDataMigration(root) {
         state: 'planned',
         operations,
         warnings,
+        ...(Object.keys(supersededSourceHashes).length ? { supersededSourceHashes } : {}),
         planSignature: migrationPlanSignature(operations),
     };
 }
@@ -866,6 +953,84 @@ function reconcileLiveTriggerDestination(operation) {
         atomicWriteText(targetPath, transformed);
     verifyLiveTriggerDestination(operation);
 }
+function sessionIdentity(directory) {
+    const active = readJson(path.join(directory, 'active.json'));
+    if (!active || typeof active !== 'object')
+        return undefined;
+    const record = active;
+    const metadata = record.metadata && typeof record.metadata === 'object'
+        ? record.metadata
+        : undefined;
+    return {
+        channelType: typeof record.channelType === 'string' ? record.channelType : undefined,
+        channelId: typeof record.channelId === 'string' ? record.channelId : undefined,
+        selfAID: typeof record.selfAID === 'string' ? record.selfAID : undefined,
+        peerId: typeof metadata?.peerId === 'string' ? metadata.peerId : undefined,
+    };
+}
+function relativeSessionFiles(directory, relative = '') {
+    const files = [];
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+        if (!entry.isDirectory() && !entry.isFile())
+            continue;
+        const child = relative ? path.join(relative, entry.name) : entry.name;
+        const fullPath = path.join(directory, entry.name);
+        if (entry.isDirectory())
+            files.push(...relativeSessionFiles(fullPath, child));
+        else
+            files.push(child);
+    }
+    return files;
+}
+/**
+ * An existing canonical session may have been written by a live runtime while
+ * the legacy copy still contains older metadata. Merge only when both active
+ * records identify the same session; unrelated destination collisions remain
+ * hard errors and require operator review.
+ */
+function canMergeSessionDestination(operation) {
+    if (operation.transform !== 'normalize-session-channel-key' || !operation.destination)
+        return false;
+    const source = sessionIdentity(operation.source);
+    const destination = sessionIdentity(operation.destination);
+    if (!source || !destination)
+        return false;
+    for (const key of ['channelType', 'channelId', 'selfAID', 'peerId']) {
+        if (source[key] !== undefined && destination[key] !== undefined && source[key] !== destination[key])
+            return false;
+    }
+    if (!(source.channelId || destination.channelId))
+        return false;
+    // Do not turn an arbitrary directory collision into a merge. Session logs
+    // are appendable, and active.json is metadata; an unknown destination-only
+    // payload still indicates that the target may belong to another layout.
+    const sourceFiles = new Set(relativeSessionFiles(operation.source));
+    const destinationFiles = new Set(relativeSessionFiles(operation.destination));
+    const excluded = new Set(operation.exclude ?? []);
+    for (const relative of new Set([...sourceFiles, ...destinationFiles])) {
+        if (excluded.has(relative))
+            continue;
+        const sourceExists = sourceFiles.has(relative);
+        const destinationExists = destinationFiles.has(relative);
+        if (!sourceExists)
+            return false;
+        if (!destinationExists) {
+            if (relative !== 'active.json' && !relative.endsWith('.jsonl'))
+                return false;
+            continue;
+        }
+        if (relative === 'active.json' || relative.endsWith('.jsonl'))
+            continue;
+        try {
+            if (!fs.readFileSync(path.join(operation.source, relative)).equals(fs.readFileSync(path.join(operation.destination, relative))))
+                return false;
+        }
+        catch {
+            return false;
+        }
+    }
+    return true;
+}
 function normalizeSessionRecordChannelKeys(record, channelKey, forceCurrentRoute = false) {
     if (!record || typeof record !== 'object')
         return false;
@@ -984,6 +1149,268 @@ function writeManifest(manifest) {
     fs.writeFileSync(temporary, JSON.stringify(manifest, null, 2) + '\n');
     fs.renameSync(temporary, target);
 }
+function writeFinalization(finalization) {
+    fs.mkdirSync(finalizationDir(finalization.root), { recursive: true });
+    const target = finalizationPath(finalization.root, finalization.migrationId);
+    const temporary = `${target}.tmp`;
+    fs.writeFileSync(temporary, JSON.stringify(finalization, null, 2) + '\n');
+    fs.renameSync(temporary, target);
+}
+function isWithin(parent, candidate) {
+    const relative = path.relative(parent, candidate);
+    return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
+function rootRelative(root, target) {
+    const relative = path.relative(root, target);
+    if (!relative || relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        throw new Error(`migration source is outside EvolCore root: ${target}`);
+    }
+    return relative;
+}
+function completedCopyProof(root, operation) {
+    try {
+        const manifests = fs.readdirSync(migrationDir(root), { withFileTypes: true })
+            .filter(entry => entry.isFile() && entry.name.endsWith('.json'))
+            .map(entry => ({
+            manifest: readJson(path.join(migrationDir(root), entry.name)),
+            mtime: fs.statSync(path.join(migrationDir(root), entry.name)).mtimeMs,
+        }))
+            .sort((left, right) => right.mtime - left.mtime);
+        for (const { manifest } of manifests) {
+            if (manifest?.state !== 'completed')
+                continue;
+            const proof = manifest.operations?.find(candidate => operationTopologyKey(candidate) === operationTopologyKey(operation)
+                && (candidate.status === 'committed' || candidate.status === 'skipped')
+                && typeof candidate.sourceHash === 'string');
+            if (proof)
+                return proof;
+        }
+    }
+    catch { }
+    return undefined;
+}
+function assertFinalizableOperation(root, operation) {
+    const checkSource = (source, expectedHash) => {
+        if (!expectedHash)
+            throw new Error(`migration source has no verified hash: ${source}`);
+        if (!fs.existsSync(source))
+            throw new Error(`migration source is missing: ${source}`);
+        if (treeHash(source, operation.exclude) !== expectedHash) {
+            throw new Error(`migration source changed after verification: ${source}`);
+        }
+    };
+    if (operation.status === 'acknowledged') {
+        // Acknowledged operations deliberately do not copy a live destination a
+        // second time. Resolve the earlier completed manifest that proved the
+        // identical source and topology before making that source removable.
+        if (operation.kind !== 'copy')
+            throw new Error(`unsupported acknowledged migration operation: ${operation.id}`);
+        const proof = completedCopyProof(root, operation);
+        checkSource(operation.source, proof?.sourceHash);
+        return;
+    }
+    if (operation.kind === 'merge-copy') {
+        for (const source of operationSources(operation)) {
+            checkSource(source, operation.sourceHashes?.[source]);
+        }
+        return;
+    }
+    checkSource(operation.source, operation.sourceHash);
+}
+function finalizationSourcePaths(root, manifest) {
+    if (manifest.state !== 'completed') {
+        throw new Error(`only a completed migration can be finalized: ${manifest.id}`);
+    }
+    const allSources = new Set();
+    for (const operation of manifest.operations) {
+        if (!['committed', 'skipped', 'acknowledged'].includes(operation.status)) {
+            throw new Error(`migration has an unfinished operation: ${operation.id}`);
+        }
+        assertFinalizableOperation(root, operation);
+        for (const source of operationSources(operation)) {
+            rootRelative(root, source);
+            allSources.add(path.resolve(source));
+        }
+    }
+    for (const [source, expectedHash] of Object.entries(manifest.supersededSourceHashes ?? {})) {
+        const absolute = path.resolve(source);
+        rootRelative(root, absolute);
+        if (!fs.existsSync(absolute))
+            throw new Error(`superseded migration source is missing: ${absolute}`);
+        if (treeHash(absolute) !== expectedHash) {
+            throw new Error(`superseded migration source changed after planning: ${absolute}`);
+        }
+        allSources.add(absolute);
+    }
+    // A parent copy may intentionally omit a payload (currently Feishu dedup).
+    // Do not let purging that parent remove an omitted file unless an independent
+    // completed operation has verified that payload too.
+    for (const operation of manifest.operations) {
+        for (const excluded of operation.exclude ?? []) {
+            const excludedPath = path.resolve(operation.source, excluded);
+            if (!fs.existsSync(excludedPath))
+                continue;
+            const independentlyVerified = [...allSources].some(source => isWithin(source, excludedPath));
+            if (!independentlyVerified) {
+                throw new Error(`migration excluded payload has no verified removal path: ${excludedPath}`);
+            }
+        }
+    }
+    const roots = [...allSources]
+        .filter(source => ![...allSources].some(other => other !== source && isWithin(other, source)))
+        .sort((left, right) => left.localeCompare(right));
+    const destinations = manifest.operations.flatMap(operation => [
+        ...(operation.destination ? [operation.destination] : []),
+        ...(operation.destinations ?? []),
+    ]);
+    for (const source of roots) {
+        if (destinations.some(destination => isWithin(source, destination))) {
+            throw new Error(`migration destination is inside a legacy source and cannot be purged: ${source}`);
+        }
+    }
+    return roots;
+}
+function archiveHash(filePath) {
+    return crypto.createHash('sha256').update(fs.readFileSync(filePath)).digest('hex');
+}
+function verifyArchiveContains(archivePath, sourcePaths) {
+    const tar = process.platform === 'win32' ? 'tar.exe' : 'tar';
+    const normalizeArchivePath = (value) => value
+        .trim()
+        .replace(/\\/g, '/')
+        .replace(/\/+$/, '');
+    let entries;
+    try {
+        entries = new Set(execFileSync(tar, ['-tzf', archivePath], { encoding: 'utf8' })
+            .split('\n')
+            .map(normalizeArchivePath)
+            .filter(Boolean));
+    }
+    catch (error) {
+        throw new Error(`cannot verify migration archive: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    for (const source of sourcePaths) {
+        if (!entries.has(normalizeArchivePath(source))) {
+            throw new Error(`migration archive is missing source: ${source}`);
+        }
+    }
+}
+function pruneEmptyLegacyParents(root, sourcePaths) {
+    for (const source of sourcePaths) {
+        let current = path.dirname(source);
+        while (current !== root && isWithin(root, current)) {
+            const relative = path.relative(root, current);
+            // Never remove the two top-level runtime roots themselves.
+            if (relative === 'data' || relative === 'agents')
+                break;
+            let entries;
+            try {
+                entries = fs.readdirSync(current);
+            }
+            catch {
+                break;
+            }
+            if (entries.length > 0)
+                break;
+            fs.rmdirSync(current);
+            current = path.dirname(current);
+        }
+    }
+}
+function pruneEmptyLegacyDirectories(root) {
+    // Some legacy roots contain empty per-Agent directories that never produced
+    // a migration operation. Remove only empty children of known legacy roots;
+    // unresolved directories containing data are left untouched.
+    const roots = [path.join(root, 'data', 'triggers')];
+    const pruneChildren = (directory) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(directory, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const child = path.join(directory, entry.name);
+            pruneChildren(child);
+            try {
+                if (fs.readdirSync(child).length === 0)
+                    fs.rmdirSync(child);
+            }
+            catch { }
+        }
+    };
+    for (const directory of roots)
+        pruneChildren(directory);
+}
+function removeMigrationStaging(manifest) {
+    try {
+        fs.rmSync(migrationStagingDir(manifest.root, manifest.id), { recursive: true, force: true });
+    }
+    catch { }
+}
+/**
+ * Archive and remove only source paths already proven by a completed migration.
+ * The CLI invokes this as the final phase of --apply. An archive is
+ * verified before any source is removed.
+ */
+export function finalizeDataMigration(root, manifest) {
+    if (path.resolve(manifest.root) !== path.resolve(root)) {
+        throw new Error(`migration root does not match requested root: ${manifest.id}`);
+    }
+    const existing = readJson(finalizationPath(root, manifest.id));
+    if (existing?.schemaVersion === 1 && existing.migrationId === manifest.id) {
+        if (!fs.existsSync(existing.archivePath) || archiveHash(existing.archivePath) !== existing.archiveSha256) {
+            throw new Error(`existing migration archive is missing or corrupt: ${existing.archivePath}`);
+        }
+        pruneEmptyLegacyDirectories(root);
+        removeMigrationStaging(manifest);
+        return existing;
+    }
+    const absoluteSources = finalizationSourcePaths(root, manifest);
+    const sourcePaths = absoluteSources.map(source => rootRelative(root, source));
+    const archivePath = path.join(root, 'backups', 'data-migration', `${manifest.id}-legacy-sources.tar.gz`);
+    if (fs.existsSync(archivePath)) {
+        throw new Error(`migration archive already exists without a finalization receipt: ${archivePath}`);
+    }
+    fs.mkdirSync(path.dirname(archivePath), { recursive: true });
+    const temporary = `${archivePath}.${process.pid}.${crypto.randomBytes(6).toString('hex')}.tmp`;
+    const tar = process.platform === 'win32' ? 'tar.exe' : 'tar';
+    try {
+        execFileSync(tar, ['-czf', temporary, ...sourcePaths], { cwd: root, stdio: 'pipe' });
+        verifyArchiveContains(temporary, sourcePaths);
+        fs.renameSync(temporary, archivePath);
+    }
+    catch (error) {
+        try {
+            fs.rmSync(temporary, { force: true });
+        }
+        catch { }
+        throw new Error(`cannot create migration archive: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    // Recheck immediately before deletion in case another writer appeared in
+    // the maintenance window after the archive was created.
+    for (const operation of manifest.operations)
+        assertFinalizableOperation(root, operation);
+    for (const source of absoluteSources)
+        fs.rmSync(source, { recursive: true, force: false });
+    pruneEmptyLegacyParents(root, absoluteSources);
+    pruneEmptyLegacyDirectories(root);
+    const finalization = {
+        schemaVersion: 1,
+        migrationId: manifest.id,
+        root,
+        finalizedAt: new Date().toISOString(),
+        archivePath,
+        archiveSha256: archiveHash(archivePath),
+        sourcePaths,
+    };
+    writeFinalization(finalization);
+    removeMigrationStaging(manifest);
+    return finalization;
+}
 function atomicWriteText(target, content) {
     const temporary = `${target}.${process.pid}.${crypto.randomBytes(6).toString('hex')}.tmp`;
     fs.writeFileSync(temporary, content);
@@ -1109,6 +1536,22 @@ function executeCopy(operation, checkpoint) {
             checkpoint();
             return;
         }
+        if (operation.transform === 'normalize-session-channel-key'
+            && (operation.allowExistingDestinationMerge || canMergeSessionDestination(operation))) {
+            // A control-AID rotation can legitimately converge an old transcript
+            // onto a newer live transcript for the same peer. The same checked
+            // transaction also handles a live destination that differs only in
+            // historical active-session metadata.
+            operation.allowExistingDestinationMerge = true;
+            operation.kind = 'merge-copy';
+            operation.expectedHash = undefined;
+            operation.stagedHash = undefined;
+            operation.destinationHash = undefined;
+            operation.error = undefined;
+            operation.verificationError = undefined;
+            executeMergeCopy(operation, checkpoint);
+            return;
+        }
         throw new Error(`destination conflict: ${operation.destination}`);
     }
     if (!operation.staging)
@@ -1180,7 +1623,9 @@ function copyTree(source, destination) {
             copyTree(path.join(source, entry.name), path.join(destination, entry.name));
     }
 }
-function mergeTree(source, destination, stagingRoot, relative = '') {
+function mergeTree(source, destination, stagingRoot, relative = '', exclude = []) {
+    if (relative && exclude.includes(relative))
+        return;
     const stat = fs.statSync(source);
     if (stat.isFile()) {
         if (!fs.existsSync(destination)) {
@@ -1206,20 +1651,26 @@ function mergeTree(source, destination, stagingRoot, relative = '') {
         if (!entry.isDirectory() && !entry.isFile())
             continue;
         const childRelative = relative ? path.join(relative, entry.name) : entry.name;
-        mergeTree(path.join(source, entry.name), path.join(destination, entry.name), stagingRoot, childRelative);
+        mergeTree(path.join(source, entry.name), path.join(destination, entry.name), stagingRoot, childRelative, exclude);
     }
 }
 function executeMergeCopy(operation, checkpoint) {
     if (!operation.destination || !operation.staging)
         throw new Error('merge-copy operation is incomplete');
     const sources = trackMergeSources(operation);
-    const sourceOutputHashes = sources.map(source => treeHash(source, operation.exclude, '', operation.transform, operation.sessionChannelKey));
-    // The legacy copies remain authoritative, so a partially built stage may
-    // always be recreated safely. No destination is touched before validation.
+    const destinationBeforeHash = fs.existsSync(operation.destination)
+        ? treeHash(operation.destination)
+        : undefined;
+    // A partially built stage may always be recreated safely. Seed it from the
+    // current destination first, then merge legacy sources into that snapshot;
+    // JSONL is de-duplicated while conflicting singleton files stay recoverable
+    // below _legacy-conflicts. No destination is touched before validation.
     if (fs.existsSync(operation.staging))
         fs.rmSync(operation.staging, { recursive: true, force: true });
+    if (destinationBeforeHash !== undefined)
+        copyTree(operation.destination, operation.staging);
     for (const source of sources)
-        mergeTree(source, operation.staging, operation.staging);
+        mergeTree(source, operation.staging, operation.staging, '', operation.exclude);
     transformTree(operation.staging, operation.transform, operation.sessionChannelKey);
     operation.status = 'staged';
     operation.stagedHash = treeHash(operation.staging);
@@ -1234,8 +1685,8 @@ function executeMergeCopy(operation, checkpoint) {
     checkpoint();
     if (fs.existsSync(operation.destination)) {
         const destinationHash = treeHash(operation.destination);
-        if (destinationHash !== expectedHash && !sourceOutputHashes.includes(destinationHash)) {
-            throw new Error(`destination conflict: ${operation.destination}`);
+        if (destinationHash !== destinationBeforeHash) {
+            throw new Error(`destination changed during migration: ${operation.destination}`);
         }
         if (destinationHash !== expectedHash)
             copyTree(operation.staging, operation.destination);
@@ -1256,6 +1707,7 @@ function executeMergeCopy(operation, checkpoint) {
  * later items still run and a subsequent `--resume` only retries failures.
  */
 export function applyDataMigration(manifest) {
+    restoreLegacyControlMergeEligibility(manifest);
     manifest.state = 'running';
     writeManifest(manifest);
     for (const operation of manifest.operations) {
@@ -1297,7 +1749,11 @@ export function readDataMigration(root, id) {
 export function inspectDataMigrationRequirement(root) {
     const plan = planDataMigration(root);
     const planSignature = plan.planSignature ?? migrationPlanSignature(plan.operations);
-    if (plan.operations.length === 0) {
+    // A plan may retain already-proven source copies while a later plan grows.
+    // Only operations that still require a copy/merge/audit warrant a startup
+    // gate; acknowledged entries are historical evidence, not pending work.
+    const pendingOperations = plan.operations.filter(operation => operation.status !== 'acknowledged');
+    if (pendingOperations.length === 0) {
         return { required: false, operationCount: 0, planSignature };
     }
     let completedMigrationId;
@@ -1316,12 +1772,27 @@ export function inspectDataMigrationRequirement(root) {
     catch { }
     return {
         required: !completedMigrationId,
-        operationCount: plan.operations.length,
+        operationCount: completedMigrationId ? 0 : pendingOperations.length,
         planSignature,
         completedMigrationId,
     };
 }
+function finalizedSources(manifest) {
+    const receipt = readJson(finalizationPath(manifest.root, manifest.id));
+    if (!receipt || receipt.schemaVersion !== 1 || receipt.migrationId !== manifest.id)
+        return new Set();
+    try {
+        if (!fs.existsSync(receipt.archivePath) || archiveHash(receipt.archivePath) !== receipt.archiveSha256)
+            return new Set();
+    }
+    catch {
+        return new Set();
+    }
+    return new Set(receipt.sourcePaths.map(source => path.resolve(manifest.root, source)));
+}
 export function verifyDataMigration(manifest, { strictTargetContent = true } = {}) {
+    const archivedSources = finalizedSources(manifest);
+    const sourceArchived = (source) => archivedSources.has(path.resolve(source));
     for (const operation of manifest.operations) {
         if (operation.status === 'acknowledged')
             continue;
@@ -1342,10 +1813,15 @@ export function verifyDataMigration(manifest, { strictTargetContent = true } = {
         }
         if (operation.kind === 'contact-audit-partition') {
             try {
-                const sourceHash = treeHash(operation.source);
-                if (operation.sourceHash && operation.sourceHash !== sourceHash)
-                    throw new Error('source changed since migration began');
-                operation.sourceHash = sourceHash;
+                if (fs.existsSync(operation.source)) {
+                    const sourceHash = treeHash(operation.source);
+                    if (operation.sourceHash && operation.sourceHash !== sourceHash)
+                        throw new Error('source changed since migration began');
+                    operation.sourceHash = sourceHash;
+                }
+                else if (!sourceArchived(operation.source)) {
+                    throw new Error(`source missing: ${operation.source}`);
+                }
                 for (const destination of operation.destinations ?? []) {
                     if (!fs.existsSync(destination))
                         throw new Error(`destination missing: ${destination}`);
@@ -1371,7 +1847,14 @@ export function verifyDataMigration(manifest, { strictTargetContent = true } = {
             try {
                 if (!operation.destination || !fs.existsSync(operation.destination))
                     throw new Error('destination missing');
-                trackMergeSources(operation);
+                const sources = operationSources(operation);
+                const liveSources = sources.filter(source => fs.existsSync(source));
+                const removedSources = sources.filter(source => !fs.existsSync(source));
+                if (removedSources.some(source => !sourceArchived(source))) {
+                    throw new Error(`source missing: ${removedSources.find(source => !sourceArchived(source))}`);
+                }
+                if (liveSources.length > 0)
+                    trackMergeSources(operation);
                 validateTree(operation.destination);
                 const destinationHash = treeHash(operation.destination);
                 operation.destinationHash = destinationHash;
@@ -1398,16 +1881,26 @@ export function verifyDataMigration(manifest, { strictTargetContent = true } = {
         }
         try {
             validateTree(operation.destination);
-            const sourceHash = treeHash(operation.source, operation.exclude);
-            if (operation.sourceHash && operation.sourceHash !== sourceHash) {
-                throw new Error('source changed since migration began');
+            let sourceHash = operation.sourceHash;
+            let expectedHash = operation.expectedHash;
+            if (fs.existsSync(operation.source)) {
+                sourceHash = treeHash(operation.source, operation.exclude);
+                if (operation.sourceHash && operation.sourceHash !== sourceHash) {
+                    throw new Error('source changed since migration began');
+                }
+                expectedHash = treeHash(operation.source, operation.exclude, '', operation.transform, operation.sessionChannelKey);
+                if (operation.expectedHash && operation.expectedHash !== expectedHash) {
+                    throw new Error('expected output changed since migration began');
+                }
             }
-            const expectedHash = treeHash(operation.source, operation.exclude, '', operation.transform, operation.sessionChannelKey);
-            if (operation.expectedHash && operation.expectedHash !== expectedHash) {
-                throw new Error('expected output changed since migration began');
+            else if (!sourceArchived(operation.source)) {
+                throw new Error(`source missing: ${operation.source}`);
             }
+            if (!expectedHash)
+                throw new Error('expected output hash missing');
             const destinationHash = treeHash(operation.destination);
-            operation.sourceHash = sourceHash;
+            if (sourceHash)
+                operation.sourceHash = sourceHash;
             operation.expectedHash = expectedHash;
             operation.destinationHash = destinationHash;
             if (!strictTargetContent && operation.status === 'error' && operation.error?.startsWith('destination conflict') && expectedHash !== destinationHash) {