@nowcrew/daemon 0.6.97-beta.1 → 0.6.97-beta.2

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

@@ -0,0 +1,317 @@
+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';
+/** 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;
+export const isHarmlessMigrationRemainder = (text) => !text.replace(/<!--[\s\S]*?-->/gu, '').replace(/^#{1,2}[^\n]*$/gmu, '').trim();
+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 category = /^notes\/(.+)\.md$/u.exec(fields.file ?? '')?.[1] ?? '';
+    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(categories.test(category) && fields.summary
+            && ['procedural', 'semantic', 'episodic', 'preference'].includes(fields.type ?? '')
+            && ['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,
+    };
+}
+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/'))
+                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 knownMetadata = new Map();
+        mappings = confirmedMappings;
+        if (mappings.length > 0) {
+            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);
+                if (uncovered.trim())
+                    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 = [...content.matchAll(/^### (.+)\r?\n([\s\S]*?)(?=^### |$(?![\s\S]))/gmu)];
+            if (content.slice(0, cards[0]?.index ?? content.length).trim())
+                issues.push({ path: 'MEMORY.md', reason: 'index_text_requires_mapping' });
+            const seenFiles = new Set();
+            for (const card of cards) {
+                const fieldMatches = [...card[2].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[2].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[1], status: fields.status });
+                if (!parsed.success)
+                    issues.push({ path, reason: 'card_metadata_invalid' });
+                else {
+                    mappings.push(parsed.data);
+                    knownMetadata.set(path, { 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),
+                ...(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/') && 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 };
+}

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

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+const identifier = z.string().min(1).max(256).regex(/^[A-Za-z0-9_.:@-]+$/u);
+export const MigrationDigestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
+export const MigrationIdentitySchema = z.object({
+    workspaceId: identifier, agentId: identifier, migrationId: identifier,
+    sourceStorageVersion: z.union([z.literal(0), z.literal(1)]), targetStorageVersion: z.literal(2),
+    rootFingerprint: MigrationDigestSchema, ownerIdentity: identifier, machineId: identifier, executionId: identifier,
+}).strict();
+export const MigrationIntentReceiptSchema = MigrationIdentitySchema.extend({
+    kind: z.literal('server_write_intent'), sourceDigest: MigrationDigestSchema, planDigest: MigrationDigestSchema,
+    intentVersion: z.number().int().positive(), confirmedAt: z.string().datetime(),
+}).strict();
+export const MigrationProcessStoppedReceiptSchema = z.object({
+    kind: z.literal('migration_process_stopped'), migrationId: identifier, machineId: identifier,
+    executionId: identifier, ownerIdentity: identifier, pid: z.number().int().positive().nullable(),
+    stoppedAt: z.string().datetime(), proof: z.enum(['supervisor_exit', 'journal_reconciled', 'not_started']),
+}).strict().refine(value => value.proof === 'not_started' ? value.pid === null : value.proof === 'supervisor_exit' ? value.pid !== null : true, 'migration_stop_proof_invalid');
+export const MigrationPathSchema = z.string().max(512).refine(value => (value === 'MEMORY.md' || value === 'notes' || value === '.crew/memory/pending'
+    || value.startsWith('notes/') || value.startsWith('.crew/memory/pending/'))
+    && !/[\\\u0000-\u001f\u007f:]/u.test(value)
+    && value.split('/').every(part => part !== '.' && part !== '..' && part.length > 0), 'migration_path_invalid');
+export const MigrationRecordMappingSchema = z.object({
+    sourceFile: MigrationPathSchema.refine(value => value === 'MEMORY.md' || value.startsWith('notes/'), 'migration_pending_promotion_forbidden'), start: z.number().int().nonnegative(), end: z.number().int().positive(),
+    sourceSha256: MigrationDigestSchema.optional(),
+    scope: z.string().min(1).max(1000), category: z.enum(['preferences', 'project-rules', 'testing', 'debugging', 'git', 'incidents', 'lessons']),
+    targetId: z.string().regex(/^[A-Za-z0-9_-]+$/u).optional(), title: z.string().min(1).max(300),
+    status: z.enum(['active', 'pinned', 'candidate', 'stale', 'superseded', 'archived']).default('active'),
+}).strict().refine(value => value.end > value.start, 'migration_mapping_range_invalid');
+const image = z.discriminatedUnion('exists', [z.object({ exists: z.literal(false) }).strict(),
+    z.object({ exists: z.literal(true), sha256: MigrationDigestSchema, ref: z.string().regex(/^\.crew\/memory\/migrations\/[A-Za-z0-9_.:@-]+\/(?:backup|staged)\/[a-f0-9]{64}$/u), bytes: z.number().int().nonnegative() }).strict()]);
+export const MigrationManifestSchema = z.object({
+    directories: z.array(MigrationPathSchema).max(10000),
+    files: z.array(z.object({ path: MigrationPathSchema, before: image, after: image }).strict()).max(20000),
+    recordMappings: z.array(MigrationRecordMappingSchema).max(10000),
+}).strict();
+export const MigrationIssueSchema = z.object({ path: z.string(), reason: z.string(), start: z.number().optional(), end: z.number().optional() }).strict();
+export const MigrationStateSchema = z.object({
+    schemaVersion: z.literal(1), identity: MigrationIdentitySchema,
+    storageVersion: z.union([z.literal(0), z.literal(1), z.literal(2)]), targetStorageVersion: z.literal(2), origin: z.enum(['migrated', 'initialized']),
+    migrationId: identifier, phase: z.enum(['prepared', 'applying', 'committed', 'rolled_back', 'repair_required']),
+    sourceDigest: MigrationDigestSchema, planDigest: MigrationDigestSchema, manifest: MigrationManifestSchema,
+    intentReceipt: MigrationIntentReceiptSchema.optional(), issues: z.array(MigrationIssueSchema),
+}).strict();
+export const MigrationHistorySchema = z.object({ kind: z.enum(['none', 'existing', 'unavailable']), migrationId: identifier.optional(), writeIntentConfirmed: z.boolean().optional(), isNewAgent: z.boolean().optional(),
+    rolledBackOperations: z.array(z.object({ migrationId: identifier, sourceDigest: MigrationDigestSchema, planDigest: MigrationDigestSchema }).strict()).max(10000).optional(),
+}).strict();
+export class MigrationError extends Error {
+    code;
+    issues;
+    constructor(code, issues = []) {
+        super(code);
+        this.code = code;
+        this.issues = issues;
+    }
+}

package/dist/local-memory/migration-state-invariants.js

@@ -0,0 +1,65 @@
+import { createHash } from 'node:crypto';
+import { MigrationError, MigrationIntentReceiptSchema, } from './migration-schema.js';
+export const migrationOperationRoot = (identity) => `.crew/memory/migrations/${identity.migrationId}`;
+function canonical(data) {
+    if (Array.isArray(data))
+        return data.map(canonical);
+    if (data !== null && typeof data === 'object') {
+        return Object.fromEntries(Object.entries(data)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, value]) => [key, canonical(value)]));
+    }
+    return data;
+}
+export const encodeMigrationData = (data) => Buffer.from(JSON.stringify(canonical(data)));
+export const sameMigrationData = (left, right) => encodeMigrationData(left).equals(encodeMigrationData(right));
+export function migrationPlanDigest(identity, sourceDigest, manifest) {
+    return createHash('sha256')
+        .update(encodeMigrationData({ identity, sourceDigest, manifest }))
+        .digest('hex');
+}
+export function verifyMigrationIntent(receipt, state) {
+    const parsed = MigrationIntentReceiptSchema.parse(receipt);
+    for (const key of Object.keys(state.identity)) {
+        if (parsed[key] !== state.identity[key])
+            throw new MigrationError('migration_intent_identity_mismatch');
+    }
+    if (parsed.sourceDigest !== state.sourceDigest || parsed.planDigest !== state.planDigest) {
+        throw new MigrationError('migration_intent_digest_mismatch');
+    }
+    return parsed;
+}
+/** Pure validation shared by migration recovery and read-only inventory. */
+export function assertMigrationStateIntegrity(state, identity) {
+    if (!sameMigrationData(state.identity, identity) || state.migrationId !== identity.migrationId
+        || state.planDigest !== migrationPlanDigest(identity, state.sourceDigest, state.manifest)) {
+        throw new MigrationError('migration_identity_or_manifest_invalid');
+    }
+    // A prepared/applying/rolled-back journal still describes the source store;
+    // only a committed journal describes the V2 target.  repair_required may
+    // represent either side because it can be recorded after a committed target
+    // is found damaged.  Reject contradictory states before any recovery or
+    // pending-only escape hatch can use them.
+    const sourceVersion = state.identity.sourceStorageVersion;
+    const sourcePhase = state.phase === 'prepared' || state.phase === 'applying' || state.phase === 'rolled_back';
+    if (state.origin === 'initialized' && sourceVersion !== 0
+        || sourcePhase && state.storageVersion !== sourceVersion
+        || state.phase === 'committed' && state.storageVersion !== state.targetStorageVersion
+        || state.targetStorageVersion !== identity.targetStorageVersion) {
+        throw new MigrationError('migration_identity_or_manifest_invalid');
+    }
+    const paths = state.manifest.files.map(file => file.path);
+    if (new Set(paths).size !== paths.length || !paths.includes('MEMORY.md')) {
+        throw new MigrationError('migration_manifest_invalid');
+    }
+    const operationRoot = `${migrationOperationRoot(identity)}/`;
+    for (const file of state.manifest.files) {
+        for (const image of [file.before, file.after]) {
+            if (image.exists && !image.ref.startsWith(operationRoot)) {
+                throw new MigrationError('migration_manifest_invalid');
+            }
+        }
+    }
+    if (state.intentReceipt !== undefined)
+        verifyMigrationIntent(state.intentReceipt, state);
+}