@nowcrew/daemon 0.6.101-beta.3 → 0.6.101-beta.5

package/dist/local-memory/migration-io.js

@@ -0,0 +1,199 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, opendir, realpath, rename, rm } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { MigrationError, MigrationIdentitySchema } from './migration-schema.js';
+import { LOCAL_MEMORY_NOTE_BYTE_CAP, LOCAL_MEMORY_READ_BYTE_CAP, LOCAL_MEMORY_STORAGE_BYTE_CAP } from './storage-format.js';
+export const digest = (data) => createHash('sha256').update(data).digest('hex');
+export const STATE_PATH = '.crew/memory/migration.v1.json';
+export async function validateMigrationRoot(agentDir, raw) {
+    const identity = MigrationIdentitySchema.parse(raw);
+    if (!isAbsolute(agentDir) || resolve(agentDir) !== agentDir)
+        throw new MigrationError('migration_root_invalid');
+    // macOS /var -> /private/var is a trusted system alias; the agent root itself may not be a symlink.
+    const stat = await lstat(agentDir);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || String(stat.uid) !== identity.ownerIdentity)
+        throw new MigrationError('migration_owner_invalid');
+    if (digest(await realpath(agentDir)) !== identity.rootFingerprint)
+        throw new MigrationError('migration_root_fingerprint_invalid');
+    return identity;
+}
+export async function safePath(root, path, createParents = false) {
+    const target = resolve(root, path);
+    const rel = relative(root, target);
+    if (!rel || rel.startsWith(`..${sep}`) || rel === '..' || isAbsolute(rel))
+        throw new MigrationError('migration_path_invalid', [{ path, reason: 'outside_root' }]);
+    const parts = rel.split(sep);
+    let current = root;
+    for (let i = 0; i < parts.length; i++) {
+        current = join(current, parts[i]);
+        let stat = await lstat(current).catch((error) => {
+            if (error.code === 'ENOENT')
+                return null;
+            throw error;
+        });
+        if (!stat && createParents && i < parts.length - 1) {
+            await mkdir(current, { mode: 0o700 });
+            stat = await lstat(current);
+        }
+        if (stat?.isSymbolicLink() || (stat && i < parts.length - 1 && !stat.isDirectory()))
+            throw new MigrationError('migration_path_unsafe', [{ path, reason: 'symlink_or_non_directory' }]);
+    }
+    return target;
+}
+export async function readBytes(root, path, cap = LOCAL_MEMORY_NOTE_BYTE_CAP) {
+    const target = await safePath(root, path);
+    const file = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW).catch((error) => {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    });
+    if (!file)
+        return null;
+    try {
+        const stat = await file.stat();
+        if (!stat.isFile() || stat.size > cap)
+            throw new MigrationError('migration_read_limit', [{ path, reason: 'invalid_file_or_size' }]);
+        const data = Buffer.alloc(stat.size + 1);
+        const { bytesRead } = await file.read(data, 0, data.length, 0);
+        if (bytesRead !== stat.size || (await file.stat()).size !== stat.size)
+            throw new MigrationError('migration_source_changed', [{ path, reason: 'changed_during_read' }]);
+        return data.subarray(0, bytesRead);
+    }
+    finally {
+        await file.close();
+    }
+}
+export async function atomicBytes(root, path, data, options = {}) {
+    const target = await safePath(root, path, true);
+    const temporaryPath = options.temporaryPath ?? `${path}.tmp-${randomUUID()}`;
+    const temp = await safePath(root, temporaryPath, true);
+    if ((await lstat(dirname(target))).dev !== (await lstat(dirname(temp))).dev) {
+        throw new MigrationError('migration_publication_filesystem_mismatch');
+    }
+    const existing = options.temporaryPath ? await readBytes(root, temporaryPath) : null;
+    if (existing && digest(existing) !== digest(data)) {
+        throw new MigrationError('migration_publication_copy_unknown', [{ path: temporaryPath, reason: 'publication_hash_mismatch' }]);
+    }
+    if (!existing) {
+        // The plan-recognized name is only published after every byte is complete and synced.
+        // An interrupted unpublished file is never a recovery source and is preserved as evidence.
+        const writePath = options.temporaryPath
+            ? `${dirname(dirname(temporaryPath))}/unpublished/${randomUUID()}.tmp`
+            : temporaryPath;
+        const unpublished = await safePath(root, writePath, true);
+        if ((await lstat(dirname(unpublished))).dev !== (await lstat(dirname(temp))).dev) {
+            throw new MigrationError('migration_publication_filesystem_mismatch');
+        }
+        const file = await open(unpublished, 'wx', 0o600);
+        try {
+            if (options.temporaryPath) {
+                for (let offset = 0; offset < data.length; offset += 64 * 1024) {
+                    const end = Math.min(offset + 64 * 1024, data.length);
+                    await file.writeFile(data.subarray(offset, end));
+                    await options.afterWriteChunk?.(writePath, end, data.length);
+                }
+            }
+            else
+                await file.writeFile(data);
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        if (options.temporaryPath) {
+            const complete = await readBytes(root, writePath);
+            if (!complete || digest(complete) !== digest(data))
+                throw new MigrationError('migration_unpublished_copy_invalid');
+            const appeared = await readBytes(root, temporaryPath);
+            if (appeared && digest(appeared) !== digest(data))
+                throw new MigrationError('migration_publication_copy_unknown');
+            if (!appeared) {
+                await safePath(root, temporaryPath);
+                await rename(unpublished, temp);
+                await syncDirectory(dirname(temp));
+                await syncDirectory(dirname(unpublished));
+            }
+        }
+    }
+    try {
+        await options.beforeRename?.();
+        await safePath(root, path);
+        if (options.temporaryPath) {
+            const verified = await readBytes(root, temporaryPath);
+            if (!verified || digest(verified) !== digest(data))
+                throw new MigrationError('migration_publication_copy_unknown');
+        }
+        await rename(temp, target);
+        await syncDirectory(dirname(target));
+    }
+    finally {
+        // Controlled copies survive interruption; recovery verifies their plan-bound name and content before reuse.
+        if (!options.temporaryPath)
+            await rm(temp, { force: true });
+    }
+}
+export async function syncDirectory(path) {
+    const fd = await open(path, 'r');
+    try {
+        await fd.sync();
+    }
+    finally {
+        await fd.close();
+    }
+}
+export async function inventory(root) {
+    const files = new Map();
+    const directories = [];
+    let bytes = 0;
+    let fileCount = 0;
+    let directoryCount = 0;
+    function reserveFile() {
+        if (++fileCount > 20000)
+            throw new MigrationError('migration_file_limit');
+    }
+    function reserveDirectory() {
+        if (++directoryCount > 10000)
+            throw new MigrationError('migration_directory_limit');
+    }
+    async function scan(path, reserved = false) {
+        const target = await safePath(root, path);
+        const stat = await lstat(target).catch((error) => {
+            if (error.code === 'ENOENT')
+                return null;
+            throw error;
+        });
+        if (!stat)
+            return;
+        if (stat.isDirectory()) {
+            if (!reserved)
+                reserveDirectory();
+            directories.push(path);
+            const children = [];
+            for await (const entry of await opendir(target)) {
+                if (entry.isDirectory())
+                    reserveDirectory();
+                else
+                    reserveFile();
+                children.push(entry.name);
+            }
+            for (const name of children.sort())
+                await scan(`${path}/${name}`, true);
+        }
+        else {
+            if (!reserved)
+                reserveFile();
+            const content = await readBytes(root, path, path === 'MEMORY.md' ? LOCAL_MEMORY_STORAGE_BYTE_CAP : LOCAL_MEMORY_NOTE_BYTE_CAP);
+            if (content) {
+                bytes += content.length;
+                if (bytes > LOCAL_MEMORY_READ_BYTE_CAP)
+                    throw new MigrationError('migration_read_limit');
+                files.set(path, content);
+            }
+        }
+    }
+    await scan('MEMORY.md');
+    await scan('notes');
+    await scan('.crew/memory/pending');
+    return { files, directories: directories.sort() };
+}

package/dist/local-memory/migration-pending.js

@@ -0,0 +1,9 @@
+import { detectLocalMemoryStorageVersion } from "./storage-format.js";
+export function shouldUseMigrationDeferredPending(input) {
+    return input.pruneTraceId !== null
+        && input.writerMode === "blocked"
+        && input.rolloutEnabled
+        && input.legacyFallback !== true
+        && input.failure !== "inspection_failed"
+        && detectLocalMemoryStorageVersion(input.memory) === 1;
+}

package/dist/local-memory/migration-plan.js

@@ -0,0 +1,432 @@
+import { digest } from './migration-io.js';
+import { MigrationError, MigrationRecordMappingSchema } from './migration-schema.js';
+import { assertLocalMemoryStorageSize, detectLocalMemoryStorageVersion, LOCAL_MEMORY_GENERATED_INDEX_PATTERN, LOCAL_MEMORY_NOTE_BYTE_CAP, LOCAL_MEMORY_READ_BYTE_CAP, parseFullMemoryIndex, renderFullMemoryIndex, selectLocalMemoryPreview } from './storage-format.js';
+import { memorySeed } from '../workspace.js';
+import { isDeferredMemoryArtifactPath } from './source-path.js';
+/** Reproduce the current workspace seed with its original handle and Role before accepting it as pristine. */
+export function initializeExactWorkspaceSeed(bytes) {
+    const memory = bytes.toString('utf8');
+    const prefix = /^# ([^\r\n]+)\n\n## Role\n/u.exec(memory);
+    if (!prefix)
+        return null;
+    const template = memorySeed(prefix[1]);
+    const tail = template.slice(template.indexOf('\n\n## Core Goals\n'));
+    if (!memory.endsWith(tail))
+        return null;
+    const role = memory.slice(prefix[0].length, memory.length - tail.length);
+    if (!bytes.equals(Buffer.from(memorySeed(prefix[1], role))))
+        return null;
+    const heading = '\n## Knowledge Index\n';
+    const insertion = memory.length - tail.length + tail.indexOf(heading) + heading.length;
+    const initialized = `${memory.slice(0, insertion)}${renderFullMemoryIndex([])}\n${memory.slice(insertion)}`;
+    return Buffer.from(initialized
+        .replace(/<!-- 使用以下格式：[\s\S]*?-->\n<!-- 示例：[\s\S]*?-->\n/u, "<!-- V2 结构化索引由 daemon 管理。规范字段为 id、file、type、status、summary、triggers、priority、revision、anchor、updated，可选 review_after；不包含 scope。 -->\n")
+        .replace("- 每条索引必须保留 file、type、scope、summary、triggers、priority、updated 这些英文协议字段名。", "- V2 结构化索引由 daemon 管理；不要直接编辑索引字段或正文锚点。"));
+}
+const categories = /^(?:preferences|project-rules|testing|debugging|git|incidents|lessons)$/u;
+const blockPattern = /<!--\s*NOWWORK:MEMORY_ENTRY:BEGIN\s+id=([A-Za-z0-9_-]+)\s+revision=([1-9][0-9]*)\s*-->([\s\S]*?)<!--\s*NOWWORK:MEMORY_ENTRY:END\s+id=\1\s*-->/gu;
+const controlMarker = /<!--\s*NOWWORK:MEMORY_/u;
+const legacyCardPattern = /^### (.+)\r?\n([\s\S]*?)(?=^### |^维护规则：|$(?![\s\S]))/gmu;
+function legacySeedMaintenanceRules() {
+    const seed = memorySeed('__memory-migration__');
+    return seed.slice(seed.indexOf('\n维护规则：'));
+}
+function matchLegacyCards(content) {
+    const masked = content.replace(/<!--[\s\S]*?-->/gu, value => value.replace(/[^\r\n]/gu, ' '));
+    return [...masked.matchAll(legacyCardPattern)].map(card => {
+        const index = card.index;
+        const matchedText = content.slice(index, index + card[0].length);
+        const commentIndex = matchedText.indexOf('<!--');
+        const text = commentIndex === -1 ? matchedText : matchedText.slice(0, commentIndex);
+        return { title: card[1], text, fields: text.slice(text.indexOf('\n') + 1), index };
+    });
+}
+export const isHarmlessMigrationRemainder = (text) => !text.replace(/<!--[\s\S]*?-->/gu, '').replace(/^#{1,2}[^\n]*$/gmu, '').trim();
+function isHarmlessLegacyIndexRemainder(text) {
+    const normalized = text.replace(/\r\n/gu, '\n');
+    // Covered card ranges can consume the newline before the exact seed rules.
+    const seedRules = legacySeedMaintenanceRules().trimStart();
+    const withoutSeedRules = normalized.includes(seedRules)
+        ? normalized.replace(seedRules, '')
+        : normalized;
+    return isHarmlessMigrationRemainder(withoutSeedRules);
+}
+function migrationSummary(body, title) {
+    const clean = (value) => value.replace(/<!--[\s\S]*?-->/gu, ' ')
+        .replace(/[\u0000-\u001f\u007f]+/gu, ' ').replace(/\s+/gu, ' ').trim().slice(0, 180);
+    return clean(body) || clean(title) || 'Migrated memory';
+}
+const MIGRATION_EPOCH_DATE = '1970-01-01';
+function parseLegacyCardMetadata(card) {
+    const fieldMatches = [...card.matchAll(/^- ([a-z_]+):[^\S\r\n]*(.*)$/gmu)];
+    const fields = Object.fromEntries(fieldMatches.map(match => [match[1], match[2].trim()]));
+    const allowedFields = new Set(['file', 'scope', 'type', 'status', 'summary', 'priority', 'updated', 'triggers', 'review_after', 'id', 'anchor', 'revision']);
+    const sourceFile = /^notes\/[^\r\n]+$/u.test(fields.file ?? '');
+    const valid = !card.replace(/^- ([a-z_]+):[^\S\r\n]*(.*)$/gmu, '').replace(/^### .+\r?\n/u, '').trim()
+        && fieldMatches.length === Object.keys(fields).length
+        && Object.keys(fields).every(key => allowedFields.has(key))
+        && Boolean(sourceFile && fields.summary
+            && ['procedural', 'semantic', 'episodic', 'preference'].includes(fields.type ?? '')
+            // Older templates omit status; reviewed mappings still determine the target status.
+            && (fields.status === undefined || ['candidate', 'active', 'pinned', 'stale', 'superseded', 'archived'].includes(fields.status))
+            && ['high', 'medium', 'low'].includes(fields.priority ?? '') && fields.updated);
+    if (!valid)
+        return null;
+    return {
+        type: fields.type, summary: fields.summary,
+        priority: fields.priority, updated: fields.updated,
+        triggers: (fields.triggers ?? '').split(/[,，、]/u).map(item => item.trim()).filter(Boolean),
+        reviewAfter: fields.review_after ?? null,
+    };
+}
+/**
+ * Read metadata from complete legacy cards even when the caller supplies an
+ * explicit notes mapping. A reviewed mapping can select a slice of a notes
+ * file, but the legacy card is still the only trustworthy source for its
+ * type/summary/priority/date/triggers. Multiple cards pointing at one source
+ * file are matched by reviewed title/range pairs; duplicate or unmatched
+ * pairs remain fail-closed in the planner.
+ */
+function collectLegacyCardMetadata(memory) {
+    const section = /^## Knowledge Index\s*\n([\s\S]*?)(?=^## (?!#)|$(?![\s\S]))/mu.exec(memory);
+    const content = section?.[1] ?? '';
+    const bySourceFile = new Map();
+    const bySourceAndTitle = new Map();
+    const ambiguousKeys = new Set();
+    const recordsBySourceFile = new Map();
+    const records = [];
+    const contentStart = section?.index === undefined ? 0 : section.index + section[0].length - content.length;
+    const cards = matchLegacyCards(content);
+    for (const card of cards) {
+        const parsed = parseLegacyCardMetadata(card.text);
+        if (!parsed)
+            continue;
+        const file = /^- file:[^\S\r\n]*(notes\/[^\r\n]+)$/mu.exec(card.text)?.[1];
+        if (!file)
+            continue;
+        const record = { sourceFile: file, title: card.title, start: contentStart + card.index, end: contentStart + card.index + card.text.length, metadata: parsed };
+        records.push(record);
+        const sourceRecords = recordsBySourceFile.get(file) ?? [];
+        recordsBySourceFile.set(file, [...sourceRecords, record]);
+        const key = `${file}\u0000${record.title}`;
+        if (ambiguousKeys.has(key))
+            continue;
+        if (!bySourceAndTitle.has(key))
+            bySourceAndTitle.set(key, parsed);
+        else {
+            bySourceAndTitle.delete(key);
+            ambiguousKeys.add(key);
+        }
+    }
+    for (const [file, sourceRecords] of recordsBySourceFile) {
+        if (sourceRecords.length === 1)
+            bySourceFile.set(file, sourceRecords[0].metadata);
+    }
+    return { bySourceFile, bySourceAndTitle, records };
+}
+const migrationDate = () => new Date().toISOString().slice(0, 10);
+export function validateMigrationTarget(files) {
+    let totalBytes = 0;
+    for (const [path, bytes] of files) {
+        totalBytes += bytes.length;
+        if (bytes.length > LOCAL_MEMORY_NOTE_BYTE_CAP || totalBytes > LOCAL_MEMORY_READ_BYTE_CAP)
+            throw new MigrationError('migration_target_resource_limit', [{ path, reason: 'target_bytes_exceeded' }]);
+    }
+    const memory = files.get('MEMORY.md')?.toString('utf8');
+    if (!memory)
+        throw new MigrationError('migration_memory_missing');
+    const entries = parseFullMemoryIndex(memory);
+    selectLocalMemoryPreview(memory);
+    for (const entry of entries) {
+        const content = files.get(entry.file)?.toString('utf8') ?? '';
+        const blocks = [...content.matchAll(blockPattern)].filter(match => match[1] === entry.id);
+        if (blocks.length !== 1 || Number(blocks[0][2]) > entry.revision)
+            throw new MigrationError('migration_detail_invalid', [{ path: entry.file, reason: `missing_or_newer_detail:${entry.id}` }]);
+    }
+}
+/** Pure conversion; every source range is measured in UTF-16 offsets in the exact UTF-8 decoded source. */
+export function planMemoryMigration(identity, files, supplied = []) {
+    for (const [path, bytes] of files) {
+        if ((path === 'MEMORY.md' || path.startsWith('notes/')) && !Buffer.from(bytes.toString('utf8')).equals(bytes)) {
+            throw new MigrationError('migration_source_encoding_invalid', [{ path, reason: 'invalid_utf8' }]);
+        }
+    }
+    const memory = files.get('MEMORY.md')?.toString('utf8');
+    if (memory === undefined)
+        throw new MigrationError('migration_memory_missing');
+    assertLocalMemoryStorageSize(memory);
+    if (detectLocalMemoryStorageVersion(memory) !== identity.sourceStorageVersion)
+        throw new MigrationError('migration_source_version_mismatch');
+    const confirmedMappings = supplied.map(value => MigrationRecordMappingSchema.parse(value));
+    const fallbackUpdated = migrationDate();
+    const mappingSourceDigests = new Map();
+    for (const mapping of confirmedMappings) {
+        if (mapping.sourceSha256 === undefined)
+            continue;
+        const source = files.get(mapping.sourceFile);
+        const actual = source === undefined ? undefined : mappingSourceDigests.get(mapping.sourceFile) ?? digest(source);
+        if (actual !== undefined)
+            mappingSourceDigests.set(mapping.sourceFile, actual);
+        if (actual !== mapping.sourceSha256) {
+            throw new MigrationError('migration_source_changed', [{ path: mapping.sourceFile, reason: 'mapping_source_digest_mismatch', start: mapping.start, end: mapping.end }]);
+        }
+    }
+    const output = new Map(files);
+    const issues = [];
+    let mappings = [];
+    if (identity.sourceStorageVersion === 1) {
+        const upgraded = memory.replace(LOCAL_MEMORY_GENERATED_INDEX_PATTERN, block => block.replace(/schema=1(?=\s*-->)/u, 'schema=2'));
+        const entries = parseFullMemoryIndex(upgraded);
+        const existingIds = new Set(entries.map(entry => entry.id));
+        const additions = confirmedMappings.map(mapping => ({ ...mapping, targetId: mapping.targetId
+                ?? `mem_${digest(`${identity.migrationId}:${mapping.sourceFile}:${mapping.start}:${mapping.end}`).slice(0, 24)}` }));
+        const retainedHistory = new Map();
+        for (const mapping of additions) {
+            const body = files.get(mapping.sourceFile)?.toString('utf8');
+            if (!mapping.sourceFile.startsWith('notes/') || body === undefined || mapping.end > body.length)
+                issues.push({ path: mapping.sourceFile, reason: 'mapping_range_not_unindexed_notes', start: mapping.start, end: mapping.end });
+            if (existingIds.has(mapping.targetId))
+                issues.push({ path: mapping.sourceFile, reason: 'mapping_target_id_conflict' });
+            existingIds.add(mapping.targetId);
+        }
+        for (const [path, bytes] of files) {
+            if (!path.startsWith('notes/') || isDeferredMemoryArtifactPath(path))
+                continue;
+            const content = bytes.toString('utf8');
+            const blocks = [...content.matchAll(blockPattern)];
+            const ranges = additions.filter(mapping => mapping.sourceFile === path);
+            for (const block of blocks) {
+                const entry = entries.find(entry => entry.file === path && entry.id === block[1]);
+                if (!entry) {
+                    const mapping = ranges.find(value => value.start === block.index && value.end === block.index + block[0].length);
+                    // schema1 归档/替代会移除索引而保留正文。只接入确认过的完整历史块，不重包或推断其状态。
+                    if (mapping?.sourceSha256 && mapping.targetId === block[1] && path === `notes/${mapping.category}.md`
+                        && mapping.status !== 'active' && mapping.status !== 'pinned' && !controlMarker.test(block[3]))
+                        retainedHistory.set(mapping.targetId, { revision: Number(block[2]), body: block[3] });
+                    else
+                        issues.push({ path, reason: 'unindexed_detail', start: block.index, end: block.index + block[0].length });
+                }
+                else
+                    mappings.push({ sourceFile: path, start: block.index, end: block.index + block[0].length, scope: `agent:${identity.agentId}`, category: path.slice(6, -3), targetId: entry.id, title: entry.title, status: entry.status });
+            }
+            const covered = [...blocks.map(block => ({ start: block.index, end: block.index + block[0].length })),
+                ...ranges.filter(mapping => !retainedHistory.has(mapping.targetId))].sort((a, b) => a.start - b.start);
+            let cursor = 0, remainder = '';
+            for (const range of covered) {
+                if (range.start < cursor)
+                    issues.push({ path, reason: 'mapping_overlaps_controlled_or_confirmed_range', start: range.start, end: range.end });
+                remainder += content.slice(cursor, range.start);
+                cursor = Math.max(cursor, range.end);
+            }
+            remainder += content.slice(cursor);
+            if (!isHarmlessMigrationRemainder(remainder))
+                issues.push({ path, reason: 'unindexed_text_requires_mapping' });
+        }
+        for (const mapping of additions) {
+            const body = files.get(mapping.sourceFile)?.toString('utf8').slice(mapping.start, mapping.end) ?? '';
+            if (!retainedHistory.has(mapping.targetId) && controlMarker.test(body))
+                issues.push({ path: mapping.sourceFile, reason: 'mapping_contains_control_marker', start: mapping.start, end: mapping.end });
+        }
+        if (issues.length)
+            throw new MigrationError('migration_needs_review', issues);
+        const appended = new Map();
+        const replacements = new Map();
+        const newEntries = additions.map(mapping => ({ id: mapping.targetId, title: mapping.title,
+            file: `notes/${mapping.category}.md`, type: 'semantic', status: mapping.status,
+            summary: migrationSummary(retainedHistory.get(mapping.targetId)?.body ?? files.get(mapping.sourceFile).toString('utf8').slice(mapping.start, mapping.end), mapping.title),
+            triggers: [], priority: 'medium', updated: fallbackUpdated, anchor: mapping.targetId, revision: retainedHistory.get(mapping.targetId)?.revision ?? 1, reviewAfter: null }));
+        for (const mapping of additions) {
+            if (retainedHistory.has(mapping.targetId))
+                continue;
+            const body = files.get(mapping.sourceFile).toString('utf8').slice(mapping.start, mapping.end);
+            const file = `notes/${mapping.category}.md`;
+            const block = `<!-- NOWWORK:MEMORY_ENTRY:BEGIN id=${mapping.targetId} revision=1 -->\n## ${mapping.title}\n\nScope: ${mapping.scope}\n\n${body}\n<!-- NOWWORK:MEMORY_ENTRY:END id=${mapping.targetId} -->\n`;
+            if (mapping.sourceFile === file)
+                replacements.set(file, [...(replacements.get(file) ?? []), { start: mapping.start, end: mapping.end, block }]);
+            else
+                appended.set(file, [...(appended.get(file) ?? []), block]);
+        }
+        for (const path of new Set([...replacements.keys(), ...appended.keys()])) {
+            let content = files.get(path)?.toString('utf8') ?? '';
+            for (const replacement of (replacements.get(path) ?? []).sort((a, b) => b.start - a.start))
+                content = content.slice(0, replacement.start) + replacement.block + content.slice(replacement.end);
+            const blocks = appended.get(path);
+            if (blocks)
+                content += '\n' + blocks.join('\n');
+            output.set(path, Buffer.from(content));
+        }
+        mappings.push(...additions);
+        const target = upgraded.replace(LOCAL_MEMORY_GENERATED_INDEX_PATTERN, () => renderFullMemoryIndex([...entries, ...newEntries]));
+        output.set('MEMORY.md', Buffer.from(target));
+    }
+    else {
+        const legacyCardMetadata = collectLegacyCardMetadata(memory);
+        const knownMetadata = new Map(legacyCardMetadata.bySourceFile);
+        for (const [key, value] of legacyCardMetadata.bySourceAndTitle)
+            knownMetadata.set(key, value);
+        mappings = confirmedMappings;
+        if (mappings.length > 0) {
+            const mappingsBySourceFile = new Map();
+            for (const mapping of mappings) {
+                const sourceMappings = mappingsBySourceFile.get(mapping.sourceFile) ?? [];
+                mappingsBySourceFile.set(mapping.sourceFile, [...sourceMappings, mapping]);
+            }
+            for (const [path, sourceMappings] of mappingsBySourceFile) {
+                const ordered = sourceMappings.sort((left, right) => left.start - right.start || left.end - right.end);
+                for (let index = 1; index < ordered.length; index += 1) {
+                    const previous = ordered[index - 1];
+                    const current = ordered[index];
+                    if (current.start < previous.end)
+                        issues.push({ path, reason: 'mapping_overlaps_controlled_or_confirmed_range', start: current.start, end: current.end });
+                }
+            }
+            const heading = /^## Knowledge Index\s*$/mu.exec(memory);
+            if (heading?.index !== undefined) {
+                const start = heading.index + heading[0].length;
+                const tail = memory.slice(start);
+                const next = /^## (?!#)/mu.exec(tail);
+                const end = next?.index === undefined ? memory.length : start + next.index;
+                let uncovered = memory.slice(start, end);
+                for (const mapping of mappings.filter(value => value.sourceFile === 'MEMORY.md').sort((a, b) => b.start - a.start)) {
+                    if (mapping.start < start || mapping.end > end) {
+                        issues.push({ path: 'MEMORY.md', reason: 'mapping_crosses_identity_or_index_boundary' });
+                        continue;
+                    }
+                    uncovered = uncovered.slice(0, mapping.start - start) + ' '.repeat(mapping.end - mapping.start) + uncovered.slice(mapping.end - start);
+                }
+                uncovered = uncovered.replace(/^[-*]\s+\[[^\]]+\]\((notes\/[^)]+)\)\s*$/gmu, (line, path) => mappings.some(value => value.sourceFile === path) ? '' : line);
+                const recordsBySourceFile = new Map();
+                for (const record of legacyCardMetadata.records) {
+                    const sourceRecords = recordsBySourceFile.get(record.sourceFile) ?? [];
+                    recordsBySourceFile.set(record.sourceFile, [...sourceRecords, record]);
+                }
+                for (const [sourceFile, records] of recordsBySourceFile) {
+                    const sourceMappings = mappings.filter(mapping => mapping.sourceFile === sourceFile);
+                    const source = files.get(sourceFile);
+                    const mappingTitles = new Set(sourceMappings.map(mapping => mapping.title));
+                    const completeMappingSet = sourceMappings.length === records.length
+                        && mappingTitles.size === sourceMappings.length
+                        && sourceMappings.every(mapping => records.some(record => record.title === mapping.title));
+                    for (const record of records) {
+                        const matchingMappings = sourceMappings.filter(mapping => mapping.title === record.title);
+                        const mapping = matchingMappings.length === 1 ? matchingMappings[0] : undefined;
+                        const rangedUniqueCard = records.length === 1 && sourceMappings.length === 1 && source !== undefined
+                            && mapping !== undefined && mapping.start >= 0 && mapping.end <= source.toString('utf8').length;
+                        const rangedMultiCard = records.length > 1 && completeMappingSet && source !== undefined
+                            && mapping !== undefined && mapping.start >= 0 && mapping.end <= source.toString('utf8').length;
+                        if (mapping === undefined || (!rangedUniqueCard && !rangedMultiCard)) {
+                            if (sourceMappings.length > 0)
+                                issues.push({ path: 'MEMORY.md', reason: 'card_mapping_unconfirmed', start: record.start, end: record.end });
+                            continue;
+                        }
+                        uncovered = uncovered.slice(0, record.start - start) + ' '.repeat(record.end - record.start) + uncovered.slice(record.end - start);
+                    }
+                }
+                if (!isHarmlessLegacyIndexRemainder(uncovered))
+                    issues.push({ path: 'MEMORY.md', reason: 'index_text_requires_mapping', start, end });
+            }
+        }
+        // Known complete cards may declare their exact scope and unique whole-file body.
+        if (mappings.length === 0) {
+            const section = /^## Knowledge Index\s*\n([\s\S]*?)(?=^## (?!#)|$(?![\s\S]))/mu.exec(memory);
+            const content = section?.[1] ?? '';
+            const cards = matchLegacyCards(content);
+            if (!isHarmlessLegacyIndexRemainder(content.slice(0, cards[0]?.index ?? content.length)))
+                issues.push({ path: 'MEMORY.md', reason: 'index_text_requires_mapping' });
+            const seenFiles = new Set();
+            for (const card of cards) {
+                const fieldMatches = [...card.fields.matchAll(/^- ([a-z_]+):[^\S\r\n]*(.*)$/gmu)];
+                const fields = Object.fromEntries(fieldMatches.map(match => [match[1], match[2].trim()]));
+                const allowedFields = new Set(['file', 'scope', 'type', 'status', 'summary', 'priority', 'updated', 'triggers', 'review_after', 'id', 'anchor', 'revision']);
+                if (card.fields.replace(/^- ([a-z_]+):[^\S\r\n]*(.*)$/gmu, '').trim() || fieldMatches.length !== Object.keys(fields).length || Object.keys(fields).some(key => !allowedFields.has(key))) {
+                    issues.push({ path: 'MEMORY.md', reason: 'card_contains_unmapped_text', start: card.index });
+                    continue;
+                }
+                const path = fields.file ?? '';
+                const category = /^notes\/(.+)\.md$/u.exec(path)?.[1] ?? '';
+                const body = files.get(path)?.toString('utf8');
+                if (!fields.scope || !categories.test(category) || !body?.trim() || seenFiles.has(path)
+                    || !fields.summary || !['procedural', 'semantic', 'episodic', 'preference'].includes(fields.type ?? '') || !fields.status || !['high', 'medium', 'low'].includes(fields.priority ?? '') || !fields.updated) {
+                    issues.push({ path: 'MEMORY.md', reason: 'card_mapping_unconfirmed', start: card.index });
+                    continue;
+                }
+                seenFiles.add(path);
+                const parsed = MigrationRecordMappingSchema.safeParse({ sourceFile: path, start: 0, end: body.length, scope: fields.scope, category, title: card.title, status: fields.status });
+                if (!parsed.success)
+                    issues.push({ path, reason: 'card_metadata_invalid' });
+                else {
+                    mappings.push(parsed.data);
+                    knownMetadata.set(`${path}\u0000${card.title}`, { type: fields.type, summary: fields.summary, priority: fields.priority, updated: fields.updated,
+                        triggers: (fields.triggers ?? '').split(/[,，、]/u).map(value => value.trim()).filter(Boolean), reviewAfter: fields.review_after ?? null });
+                }
+            }
+            if (!cards.length)
+                issues.push({ path: 'MEMORY.md', reason: 'legacy_source_requires_mapping' });
+        }
+        const entries = [];
+        for (const mapping of mappings) {
+            const body = files.get(mapping.sourceFile)?.toString('utf8');
+            if (body === undefined || mapping.end > body.length) {
+                issues.push({ path: mapping.sourceFile, reason: 'range_out_of_bounds' });
+                continue;
+            }
+            const id = mapping.targetId ?? `mem_${digest(`${identity.migrationId}:${mapping.sourceFile}:${mapping.start}:${mapping.end}`).slice(0, 24)}`;
+            const confirmedMetadata = mapping.sourceFile === 'MEMORY.md' ? parseLegacyCardMetadata(body.slice(mapping.start, mapping.end)) : null;
+            entries.push({ id, title: mapping.title, file: `notes/${mapping.category}.md`, type: 'semantic', status: mapping.status, summary: migrationSummary(body.slice(mapping.start, mapping.end), mapping.title),
+                triggers: [], priority: 'medium', updated: fallbackUpdated, anchor: id, revision: 1, reviewAfter: null,
+                ...(knownMetadata.get(`${mapping.sourceFile}\u0000${mapping.title}`) ?? knownMetadata.get(mapping.sourceFile) ?? {}),
+                ...(confirmedMetadata ? (() => {
+                    const source = confirmedMetadata;
+                    return { type: source.type, summary: source.summary, triggers: source.triggers, priority: source.priority,
+                        updated: source.updated === MIGRATION_EPOCH_DATE ? fallbackUpdated : source.updated, reviewAfter: source.reviewAfter };
+                })() : {}) });
+        }
+        for (const [path, bytes] of files) {
+            if ((!path.startsWith('notes/') || isDeferredMemoryArtifactPath(path)) && path !== 'MEMORY.md')
+                continue;
+            const text = bytes.toString('utf8');
+            const ranges = mappings.filter(mapping => mapping.sourceFile === path).sort((a, b) => a.start - b.start);
+            if (path === 'MEMORY.md')
+                continue; // Retained identity stays byte-for-byte; replaced index coverage is checked above.
+            let cursor = 0;
+            for (const range of ranges) {
+                if (range.start < cursor || text.slice(cursor, range.start).trim())
+                    issues.push({ path, reason: 'mapping_gap_or_overlap', start: cursor, end: range.start });
+                cursor = range.end;
+            }
+            if (text.slice(cursor).trim())
+                issues.push({ path, reason: 'unmapped_source_text', start: cursor, end: text.length });
+        }
+        if (issues.length)
+            throw new MigrationError('migration_needs_review', issues);
+        // Retain original files (external references may exist); only same-path fully covered sources are rewritten.
+        const targets = new Map();
+        mappings.forEach((mapping, index) => {
+            const entry = entries[index];
+            const body = files.get(mapping.sourceFile).toString('utf8').slice(mapping.start, mapping.end);
+            const blocks = targets.get(entry.file) ?? [];
+            targets.set(entry.file, [...blocks, `<!-- NOWWORK:MEMORY_ENTRY:BEGIN id=${entry.id} revision=1 -->\n## ${entry.title}\n\nScope: ${mapping.scope}\n\n${body}\n<!-- NOWWORK:MEMORY_ENTRY:END id=${entry.id} -->\n`]);
+        });
+        for (const [path, blocks] of targets) {
+            const existing = files.get(path);
+            if (existing && !mappings.some(mapping => mapping.sourceFile === path))
+                throw new MigrationError('migration_needs_review', [{ path, reason: 'target_contains_unmapped_text' }]);
+            output.set(path, Buffer.from(blocks.join('\n')));
+        }
+        const index = renderFullMemoryIndex(entries);
+        const heading = /^## Knowledge Index\s*$/mu.exec(memory);
+        let target;
+        if (heading?.index !== undefined) {
+            const start = heading.index + heading[0].length;
+            const tail = memory.slice(start);
+            const next = /^## (?!#)/mu.exec(tail);
+            target = memory.slice(0, start) + `\n${index}\n` + (next?.index === undefined ? '' : tail.slice(next.index));
+        }
+        else
+            target = `${memory}\n\n## Knowledge Index\n${index}\n`;
+        output.set('MEMORY.md', Buffer.from(target));
+        mappings = mappings.map((mapping, index) => ({ ...mapping, targetId: entries[index].id }));
+    }
+    validateMigrationTarget(output);
+    return { files: output, recordMappings: mappings };
+}