evolcore 0.0.2 → 0.0.3

package/kits/migrations/migrate-contact-book-v2.mjs

@@ -0,0 +1,747 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import crypto from 'crypto';
+import { fileURLToPath } from 'url';
+import Ajv from 'ajv';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const SCHEMA_DIR = path.resolve(SCRIPT_DIR, '..', 'schemas');
+const AGENT_LOCK_NAME = '.contact-book-mutation.lock';
+const RECEIPT_NAME = 'contact-book-v2-relation-role-authority.json';
+const RECEIPT = Object.freeze({
+  schemaVersion: 1,
+  migration: 'contact-book-v2-relation-role-authority',
+  designVersion: 2,
+});
+const CONTACT_KEYS = new Set(['displayName', 'aliases', 'status', 'subjectType', 'role', 'blocked']);
+const CONTACT_STATUSES = new Set(['active', 'blocked', 'pending']);
+
+function parseArgs(argv) {
+  const options = { apply: false, json: false, home: undefined };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--apply') options.apply = true;
+    else if (arg === '--json') options.json = true;
+    else if (arg === '--home') options.home = argv[++index];
+    else if (arg === '--help' || arg === '-h') options.help = true;
+    else throw new Error(`Unknown argument: ${arg}`);
+  }
+  return options;
+}
+
+function resolveHome(explicit) {
+  return path.resolve(explicit || process.env.EVOLCORE_HOME || path.join(os.homedir(), '.evolcore'));
+}
+
+function isRecord(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isValidAid(name) {
+  if (typeof name !== 'string') return false;
+  const labels = name.split('.');
+  return labels.length >= 3 && labels.every(label => /^[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?$/.test(label));
+}
+
+function isExplicitGroupId(value) {
+  const id = String(value || '').trim();
+  return (id.startsWith('group.') && id.includes('/'))
+    || /^\d+\.[a-z0-9.-]+$/i.test(id)
+    || /^grp_[a-z0-9_-]+$/i.test(id)
+    || /^g-[a-z0-9_-]+(?:[.@][a-z0-9.-]+)?$/i.test(id)
+    || /(?:^|\.)groupid\.pub$/i.test(id);
+}
+
+function readJson(file) {
+  const text = fs.readFileSync(file, 'utf8');
+  return { value: JSON.parse(text), text };
+}
+
+function loadValidators() {
+  const ajv = new Ajv({ allErrors: true, strict: false });
+  const load = name => JSON.parse(fs.readFileSync(path.join(SCHEMA_DIR, name), 'utf8'));
+  return {
+    agent: ajv.compile(load('agent-config.schema.6.json')),
+    contact: ajv.compile(load('contact-book.schema.2.json')),
+    relation: ajv.compile(load('relation-config.schema.5.json')),
+    registry: ajv.compile(load('role-registry.schema.1.json')),
+  };
+}
+
+function validateOrThrow(validate, value, file) {
+  if (validate(value)) return;
+  const detail = (validate.errors ?? [])
+    .map(error => `${error.instancePath || '/'} ${error.message}`)
+    .join('; ');
+  throw new Error(`${file}: ${detail}`);
+}
+
+function parsePeerKey(peerKey, file) {
+  const separator = peerKey.indexOf('#');
+  if (separator <= 0 || separator === peerKey.length - 1) {
+    throw new Error(`${file}: invalid relation peerKey ${JSON.stringify(peerKey)}`);
+  }
+  let channelId;
+  try { channelId = decodeURIComponent(peerKey.slice(separator + 1)); }
+  catch { throw new Error(`${file}: relation peerKey has invalid URL encoding`); }
+  return { channelType: peerKey.slice(0, separator).toLowerCase(), channelId };
+}
+
+function canonicalPeerKey(channelType, channelId) {
+  return `${channelType.toLowerCase()}#${encodeURIComponent(channelId)}`;
+}
+
+function listDirectRelationFiles(relationsDir) {
+  if (!fs.existsSync(relationsDir)) return [];
+  const files = [];
+  for (const entry of fs.readdirSync(relationsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory() || entry.name.startsWith('_')) continue;
+    const file = path.join(relationsDir, entry.name, 'config.json');
+    if (fs.existsSync(file)) files.push(file);
+  }
+  return files.sort();
+}
+
+function jsonText(value) {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+function appendChange(changes, file, kind, before, value) {
+  const after = jsonText(value);
+  if (before === after) return false;
+  changes.push({ file, kind, before, after });
+  return true;
+}
+
+function roleValue(value, roleIds, file, label) {
+  if (value === undefined || value === null) return null;
+  if (typeof value !== 'string' || !value) throw new Error(`${file}: ${label} must be a string or null`);
+  if (value === 'owner') throw new Error(`${file}: ${label} cannot be owner`);
+  if (!roleIds.has(value)) throw new Error(`${file}: ${label} references unknown role ${JSON.stringify(value)}`);
+  return value;
+}
+
+function canonicalChannelKey(channelType, aid, channelName) {
+  return `${channelType.toLowerCase()}#${aid}#${channelName}`;
+}
+
+function channelInventory(agent, aid, file) {
+  const keys = new Set();
+  const keysByName = new Map();
+  const keysByType = new Map();
+  for (const channel of agent.channels ?? []) {
+    if (!isRecord(channel)) continue;
+    const type = String(channel.type || '').trim().toLowerCase();
+    const name = String(channel.name || '').trim();
+    if (!type || !name) continue;
+    if (!/^[A-Za-z0-9_-]+$/.test(type)) throw new Error(`${file}: invalid channel type ${JSON.stringify(type)}`);
+    if (!/^[A-Za-z0-9_-]+$/.test(name)) throw new Error(`${file}: invalid channel instance name ${JSON.stringify(name)}`);
+    if (type === 'aun') continue;
+    const key = canonicalChannelKey(type, aid, name);
+    if (keys.has(key)) throw new Error(`${file}: duplicate channel instance ${key}`);
+    keys.add(key);
+    const byName = keysByName.get(name) ?? new Set();
+    byName.add(key);
+    keysByName.set(name, byName);
+    const byType = keysByType.get(type) ?? new Set();
+    byType.add(key);
+    keysByType.set(type, byType);
+  }
+  return { keys, keysByName, keysByType };
+}
+
+function parseCanonicalChannelKey(channelKey, aid, inventory, file, alias) {
+  const parts = channelKey.split('#');
+  if (parts.length !== 3) throw new Error(`${file}: invalid channelKey in alias ${JSON.stringify(alias)}`);
+  const [type, selfAid, name] = parts;
+  if (!/^[A-Za-z0-9_-]+$/.test(type) || type !== type.toLowerCase()
+    || selfAid !== aid || !/^[A-Za-z0-9_-]+$/.test(name)) {
+    throw new Error(`${file}: alias does not identify this Agent channel instance: ${JSON.stringify(alias)}`);
+  }
+  const canonical = canonicalChannelKey(type, aid, name);
+  if (type === 'aun') return null;
+  if (!inventory.keys.has(canonical)) {
+    throw new Error(`${file}: alias references an unconfigured channel instance: ${JSON.stringify(alias)}`);
+  }
+  return canonical;
+}
+
+function encodedPeerId(value, file, alias, alreadyEncoded = false) {
+  let peerId = value;
+  if (alreadyEncoded) {
+    try { peerId = decodeURIComponent(value); }
+    catch { throw new Error(`${file}: invalid URL encoding in alias ${JSON.stringify(alias)}`); }
+    if (encodeURIComponent(peerId) !== value) {
+      throw new Error(`${file}: non-canonical peer ID encoding in alias ${JSON.stringify(alias)}`);
+    }
+  }
+  if (!peerId) throw new Error(`${file}: alias has an empty peer ID: ${JSON.stringify(alias)}`);
+  return encodeURIComponent(peerId);
+}
+
+function parseLegacyScopedAlias(alias, aid, file) {
+  const encoded = alias.slice('channel-key:'.length);
+  const separator = encoded.indexOf(':');
+  if (separator <= 0 || separator === encoded.length - 1) {
+    throw new Error(`${file}: invalid scoped alias ${JSON.stringify(alias)}`);
+  }
+  let channelKey;
+  let actorId;
+  try {
+    channelKey = decodeURIComponent(encoded.slice(0, separator));
+    actorId = decodeURIComponent(encoded.slice(separator + 1));
+  } catch {
+    throw new Error(`${file}: invalid URL encoding in alias ${JSON.stringify(alias)}`);
+  }
+  return { channelKey, actorId };
+}
+
+function normalizeAlias(alias, aid, inventory, file) {
+  if (typeof alias !== 'string' || !alias.trim()) throw new Error(`${file}: aliases must contain non-empty strings`);
+  const text = alias.trim();
+  if (text.startsWith('channel-key:')) {
+    const legacy = parseLegacyScopedAlias(text, aid, file);
+    const channelKey = parseCanonicalChannelKey(legacy.channelKey, aid, inventory, file, text);
+    if (channelKey === null) return null;
+    return `${channelKey}:${encodedPeerId(legacy.actorId, file, text)}`;
+  }
+  const separator = text.indexOf(':');
+  if (separator <= 0 || separator === text.length - 1) throw new Error(`${file}: invalid alias ${JSON.stringify(alias)}`);
+  const prefix = text.slice(0, separator).trim();
+  const actorId = text.slice(separator + 1).trim();
+  if (prefix.includes('#')) {
+    const channelKey = parseCanonicalChannelKey(prefix, aid, inventory, file, text);
+    if (channelKey === null) return null;
+    return `${channelKey}:${encodedPeerId(actorId, file, text, true)}`;
+  }
+  if (!/^[A-Za-z0-9_-]+$/.test(prefix) || !actorId) throw new Error(`${file}: invalid alias ${JSON.stringify(alias)}`);
+  if (prefix.toLowerCase() === 'aun') return null;
+  const namedInstances = inventory.keysByName.get(prefix);
+  if (namedInstances?.size === 1) {
+    return `${[...namedInstances][0]}:${encodedPeerId(actorId, file, text)}`;
+  }
+  if (namedInstances && namedInstances.size > 1) {
+    throw new Error(`${file}: legacy alias ${JSON.stringify(alias)} is ambiguous across channel instances ${[...namedInstances].join(', ')}`);
+  }
+  const typedInstances = inventory.keysByType.get(prefix.toLowerCase());
+  if (!typedInstances || typedInstances.size === 0) {
+    throw new Error(`${file}: alias ${JSON.stringify(alias)} does not match a configured channel instance or channel type`);
+  }
+  if (typedInstances.size > 1) {
+    throw new Error(`${file}: legacy alias ${JSON.stringify(alias)} is ambiguous across channel instances ${[...typedInstances].join(', ')}`);
+  }
+  return `${[...typedInstances][0]}:${encodedPeerId(actorId, file, text)}`;
+}
+
+function relationBackupIndex(home) {
+  const result = new Map();
+  const root = path.join(home, 'backups', 'contact-book-v2-migration');
+  if (!fs.existsSync(root)) return result;
+  for (const stamp of fs.readdirSync(root, { withFileTypes: true })) {
+    if (!stamp.isDirectory()) continue;
+    try {
+      const manifest = readJson(path.join(root, stamp.name, 'manifest.json')).value;
+      if (manifest?.designVersion >= RECEIPT.designVersion) continue;
+    } catch {}
+    const agentsRoot = path.join(root, stamp.name, 'files', 'agents');
+    if (!fs.existsSync(agentsRoot)) continue;
+    for (const agent of fs.readdirSync(agentsRoot, { withFileTypes: true })) {
+      if (!agent.isDirectory() || !isValidAid(agent.name)) continue;
+      const relationsDir = path.join(agentsRoot, agent.name, 'relations');
+      for (const relationFile of listDirectRelationFiles(relationsDir)) {
+        const peerKey = path.basename(path.dirname(relationFile));
+        const parsed = parsePeerKey(peerKey, relationFile);
+        let relation;
+        try { relation = readJson(relationFile).value; }
+        catch { continue; }
+        if (!isRecord(relation) || typeof relation.role !== 'string' || relation.role === 'owner') continue;
+        const agentMap = result.get(agent.name) ?? new Map();
+        const key = canonicalPeerKey(parsed.channelType, parsed.channelId);
+        const record = agentMap.get(key) ?? { roles: new Set(), targetKinds: new Set() };
+        record.roles.add(relation.role);
+        if (relation.targetKind === 'private' || relation.targetKind === 'group') record.targetKinds.add(relation.targetKind);
+        agentMap.set(key, record);
+        result.set(agent.name, agentMap);
+      }
+    }
+  }
+  return result;
+}
+
+function migrationReceiptPath(home) {
+  return path.join(home, 'data', RECEIPT_NAME);
+}
+
+function hasCurrentReceipt(home) {
+  try {
+    const value = readJson(migrationReceiptPath(home)).value;
+    return isRecord(value) && value.migration === RECEIPT.migration && value.designVersion === RECEIPT.designVersion;
+  } catch {
+    return false;
+  }
+}
+
+function planAgentMigration(home, aid, validators, changes, summary, backupRoles, allowBackupRestore) {
+  const directory = path.join(home, 'agents', aid);
+  const agentFile = path.join(directory, 'config.json');
+  if (!fs.existsSync(agentFile)) return false;
+
+  const { value: agentInput, text: agentText } = readJson(agentFile);
+  if (!isRecord(agentInput)) throw new Error(`${agentFile}: Agent config must be an object`);
+  if (![5, 6].includes(agentInput.$schema_version)) {
+    throw new Error(`${agentFile}: contact v2 migration requires Agent schema v5 or v6`);
+  }
+
+  const registryFile = path.join(directory, 'roles', 'index.json');
+  if (!fs.existsSync(registryFile)) throw new Error(`${registryFile}: role registry is required before contact migration`);
+  const registry = readJson(registryFile).value;
+  validateOrThrow(validators.registry, registry, registryFile);
+  const roleIds = new Set(registry.roles ?? []);
+  const owners = new Set(Array.isArray(agentInput.owners) ? agentInput.owners.map(value => String(value || '').trim()).filter(Boolean) : []);
+  const inventory = channelInventory(agentInput, aid, agentFile);
+
+  const relationsDir = path.join(directory, 'relations');
+  const relations = new Map();
+  for (const relationFile of listDirectRelationFiles(relationsDir)) {
+    const peerKey = path.basename(path.dirname(relationFile));
+    const parsed = parsePeerKey(peerKey, relationFile);
+    const key = canonicalPeerKey(parsed.channelType, parsed.channelId);
+    if (relations.has(key)) {
+      throw new Error(`${relationFile}: duplicate decoded relation target ${key}`);
+    }
+    const { value: relationInput, text: relationText } = readJson(relationFile);
+    if (!isRecord(relationInput)) throw new Error(`${relationFile}: relation config must be an object`);
+    if (![4, 5].includes(relationInput.$schema_version)) {
+      throw new Error(`${relationFile}: contact v2 migration requires Relation schema v4 or v5`);
+    }
+    const currentRole = roleValue(relationInput.role, roleIds, relationFile, 'relation role');
+    const value = { ...relationInput, $schema_version: 5 };
+    if (currentRole === null) delete value.role;
+    else value.role = currentRole;
+    relations.set(key, {
+      key,
+      file: relationFile,
+      before: relationText,
+      channelType: parsed.channelType,
+      channelId: parsed.channelId,
+      value,
+      roleSource: currentRole ? 'relation' : null,
+    });
+    if (currentRole) summary.relationRolesPreserved += 1;
+  }
+
+  const ensureRelation = (channelType, channelId, targetKind) => {
+    const key = canonicalPeerKey(channelType, channelId);
+    let record = relations.get(key);
+    if (!record) {
+      const file = path.join(relationsDir, key, 'config.json');
+      record = {
+        key,
+        file,
+        before: null,
+        channelType,
+        channelId,
+        value: { $schema_version: 5, targetKind },
+        roleSource: null,
+      };
+      relations.set(key, record);
+    }
+    if (record.value.targetKind !== undefined && record.value.targetKind !== targetKind) {
+      throw new Error(`${record.file}: targetKind ${record.value.targetKind} conflicts with required ${targetKind}`);
+    }
+    record.value.targetKind = targetKind;
+    return record;
+  };
+
+  let backupEvidence = false;
+  if (allowBackupRestore) {
+    for (const [key, backup] of backupRoles ?? []) {
+      const record = relations.get(key);
+      if (!record) continue;
+      backupEvidence = true;
+      if (record.value.role !== undefined) continue;
+      if (backup.roles.size !== 1) {
+        throw new Error(`${record.file}: backup history contains conflicting relation roles ${[...backup.roles].join(', ')}`);
+      }
+      const restoredRole = roleValue([...backup.roles][0], roleIds, record.file, 'backup relation role');
+      if (backup.targetKinds.size > 1) {
+        throw new Error(`${record.file}: backup history contains conflicting targetKind values`);
+      }
+      if (record.value.targetKind === undefined && backup.targetKinds.size === 1) {
+        record.value.targetKind = [...backup.targetKinds][0];
+      }
+      record.value.role = restoredRole;
+      record.roleSource = 'backup';
+      summary.relationRolesRestored += 1;
+      if (record.channelType !== 'aun') summary.nonAunRolesRestored += 1;
+    }
+  }
+
+  const contactFile = path.join(directory, 'contact.json');
+  const contactRead = fs.existsSync(contactFile) ? readJson(contactFile) : { value: null, text: null };
+  const contactInput = contactRead.value;
+  if (contactInput !== null && !isRecord(contactInput)) throw new Error(`${contactFile}: contact book must be an object`);
+  if (contactInput?.$schema_version !== undefined && ![1, 2].includes(contactInput.$schema_version)) {
+    throw new Error(`${contactFile}: unsupported contact schema version ${contactInput.$schema_version}`);
+  }
+  const rawContacts = contactInput?.contacts ?? {};
+  if (!isRecord(rawContacts)) throw new Error(`${contactFile}: contacts must be an object`);
+  const contacts = {};
+  const aliasOwners = new Map();
+
+  for (const [primaryId, rawEntry] of Object.entries(rawContacts)) {
+    if (!isValidAid(primaryId)) throw new Error(`${contactFile}: invalid contact primary AID ${JSON.stringify(primaryId)}`);
+    if (!isRecord(rawEntry)) throw new Error(`${contactFile}: contact ${primaryId} must be an object`);
+    const unknown = Object.keys(rawEntry).filter(key => !CONTACT_KEYS.has(key));
+    if (unknown.length) throw new Error(`${contactFile}: contact ${primaryId} has unsupported fields ${unknown.join(', ')}`);
+    const subjectType = rawEntry.subjectType ?? (isExplicitGroupId(primaryId) ? 'group' : 'principal');
+    if (subjectType !== 'principal' && subjectType !== 'group') {
+      throw new Error(`${contactFile}: contact ${primaryId} has invalid subjectType ${JSON.stringify(subjectType)}`);
+    }
+    const contactRole = roleValue(rawEntry.role, roleIds, contactFile, `contact ${primaryId} role`);
+    if (contactRole) {
+      const targetKind = subjectType === 'group' ? 'group' : 'private';
+      const relation = ensureRelation('aun', primaryId, targetKind);
+      if (relation.value.role === undefined) {
+        relation.value.role = contactRole;
+        relation.roleSource = 'contact';
+        summary.contactRolesMigrated += 1;
+      } else if (relation.value.role !== contactRole) {
+        summary.contactRoleConflictsIgnored += 1;
+      }
+    }
+    if (subjectType === 'group') {
+      summary.groupContactsRemoved += 1;
+      continue;
+    }
+
+    const next = {};
+    if (rawEntry.displayName !== undefined) next.displayName = rawEntry.displayName;
+    if (rawEntry.aliases !== undefined) {
+      if (!Array.isArray(rawEntry.aliases)) throw new Error(`${contactFile}: contact ${primaryId} aliases must be an array`);
+      const aliases = [];
+      for (const rawAlias of rawEntry.aliases) {
+        const normalized = normalizeAlias(rawAlias, aid, inventory, contactFile);
+        if (normalized === null) {
+          summary.nativeAunAliasesRemoved += 1;
+          continue;
+        }
+        if (normalized !== rawAlias) summary.aliasesRewritten += 1;
+        const existing = aliasOwners.get(normalized);
+        if (existing && existing !== primaryId) {
+          throw new Error(`${contactFile}: alias ${JSON.stringify(normalized)} is assigned to both ${existing} and ${primaryId}`);
+        }
+        aliasOwners.set(normalized, primaryId);
+        if (!aliases.includes(normalized)) aliases.push(normalized);
+      }
+      if (aliases.length) next.aliases = aliases;
+    }
+    let status = rawEntry.status;
+    if (status !== undefined && !CONTACT_STATUSES.has(status)) {
+      throw new Error(`${contactFile}: contact ${primaryId} has invalid status ${JSON.stringify(status)}`);
+    }
+    if (rawEntry.blocked === true) {
+      if (status !== undefined && status !== 'blocked') {
+        throw new Error(`${contactFile}: contact ${primaryId} has conflicting blocked/status values`);
+      }
+      status = 'blocked';
+      summary.blockedStatusesMigrated += 1;
+    } else if (rawEntry.blocked !== undefined && rawEntry.blocked !== false) {
+      throw new Error(`${contactFile}: contact ${primaryId} blocked must be boolean`);
+    }
+    if (owners.has(primaryId) && status === 'blocked') {
+      throw new Error(`${contactFile}: owner contact ${primaryId} cannot be blocked`);
+    }
+    if (status && status !== 'active') next.status = status;
+    contacts[primaryId] = next;
+  }
+
+  for (const rawAdmin of Array.isArray(agentInput.admins) ? agentInput.admins : []) {
+    const admin = String(rawAdmin || '').trim();
+    if (!isValidAid(admin)) throw new Error(`${agentFile}: invalid admin AID ${JSON.stringify(rawAdmin)}`);
+    if (owners.has(admin)) continue;
+    const relation = ensureRelation('aun', admin, 'private');
+    if (relation.value.role !== 'admin') summary.adminsMigrated += 1;
+    relation.value.role = 'admin';
+    relation.roleSource = 'agent-admin';
+  }
+
+  for (const relation of relations.values()) {
+    validateOrThrow(validators.relation, relation.value, relation.file);
+    appendChange(changes, relation.file, 'relation', relation.before, relation.value);
+  }
+
+  const contactOutput = { $schema_version: 2, contacts };
+  validateOrThrow(validators.contact, contactOutput, contactFile);
+  if (contactRead.text !== null || Object.keys(contacts).length > 0) {
+    appendChange(changes, contactFile, 'contact', contactRead.text, contactOutput);
+  }
+
+  const agentOutput = { ...agentInput, $schema_version: 6 };
+  delete agentOutput.admins;
+  validateOrThrow(validators.agent, agentOutput, agentFile);
+  appendChange(changes, agentFile, 'agent', agentText, agentOutput);
+  return { migrated: true, backupEvidence };
+}
+
+function planMigration(home) {
+  const validators = loadValidators();
+  const agentsRoot = path.join(home, 'agents');
+  const changes = [];
+  const summary = {
+    agentsScanned: 0,
+    agentsMigrated: 0,
+    relationRolesPreserved: 0,
+    relationRolesRestored: 0,
+    nonAunRolesRestored: 0,
+    contactRolesMigrated: 0,
+    contactRoleConflictsIgnored: 0,
+    adminsMigrated: 0,
+    groupContactsRemoved: 0,
+    aliasesRewritten: 0,
+    nativeAunAliasesRemoved: 0,
+    blockedStatusesMigrated: 0,
+  };
+  if (!fs.existsSync(agentsRoot)) return { home, changes, summary };
+  const receiptCurrent = hasCurrentReceipt(home);
+  const backups = receiptCurrent ? new Map() : relationBackupIndex(home);
+  let backupEvidence = false;
+  for (const entry of fs.readdirSync(agentsRoot, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name))) {
+    if (!entry.isDirectory() || !isValidAid(entry.name)) continue;
+    summary.agentsScanned += 1;
+    const result = planAgentMigration(home, entry.name, validators, changes, summary, backups.get(entry.name), !receiptCurrent);
+    if (result?.migrated) summary.agentsMigrated += 1;
+    if (result?.backupEvidence) backupEvidence = true;
+  }
+  if (!receiptCurrent && backupEvidence) {
+    const receiptFile = migrationReceiptPath(home);
+    const before = fs.existsSync(receiptFile) ? fs.readFileSync(receiptFile, 'utf8') : null;
+    appendChange(changes, receiptFile, 'receipt', before, RECEIPT);
+  }
+  return { home, changes, summary };
+}
+
+function assertDaemonStopped(home) {
+  const candidates = [];
+  const pidFile = path.join(home, 'daemon.pid');
+  if (fs.existsSync(pidFile)) candidates.push({ pid: Number(fs.readFileSync(pidFile, 'utf8').trim()), source: pidFile });
+  const instanceDir = path.join(home, 'data', 'instance');
+  if (fs.existsSync(instanceDir)) {
+    for (const name of fs.readdirSync(instanceDir)) {
+      if (!/^main-\d+\.json$/.test(name)) continue;
+      const file = path.join(instanceDir, name);
+      try { candidates.push({ pid: Number(JSON.parse(fs.readFileSync(file, 'utf8'))?.pid), source: file }); } catch {}
+    }
+  }
+  for (const { pid, source } of candidates) {
+    if (!Number.isInteger(pid) || pid <= 0) continue;
+    try { process.kill(pid, 0); }
+    catch (error) {
+      if (error?.code === 'ESRCH') continue;
+      if (error?.code !== 'EPERM') throw error;
+    }
+    throw new Error(`EvolCore daemon appears to be running (pid=${pid}, record=${source}); stop it before migration`);
+  }
+}
+
+function acquireDirectoryLock(lockDir, label) {
+  const ownerFile = path.join(lockDir, 'owner.json');
+  const lockToken = crypto.randomBytes(16).toString('hex');
+  const candidateDir = `${lockDir}.candidate-${process.pid}-${lockToken}`;
+  const candidateOwnerFile = path.join(candidateDir, 'owner.json');
+  fs.mkdirSync(path.dirname(lockDir), { recursive: true });
+  fs.mkdirSync(candidateDir);
+  fs.writeFileSync(candidateOwnerFile, jsonText({
+    pid: process.pid,
+    processStartedAt: Date.now() - Math.floor(process.uptime() * 1000),
+    createdAt: new Date().toISOString(),
+    lockToken,
+  }));
+  let acquired = false;
+  try {
+    while (true) {
+      try {
+        fs.renameSync(candidateDir, lockDir);
+        acquired = true;
+        return () => releaseDirectoryLock(lockDir, ownerFile, lockToken);
+      } catch (error) {
+        if (error?.code !== 'EEXIST' && error?.code !== 'ENOTEMPTY') throw error;
+      }
+      let rawOwner;
+      let ownerPid;
+      try {
+        rawOwner = fs.readFileSync(ownerFile, 'utf8');
+        ownerPid = Number(JSON.parse(rawOwner)?.pid);
+      } catch {
+        throw new Error(`${label} lock is unreadable: ${lockDir}`);
+      }
+      if (!Number.isInteger(ownerPid) || ownerPid <= 0) throw new Error(`${label} lock has an invalid owner: ${lockDir}`);
+      try {
+        process.kill(ownerPid, 0);
+        throw new Error(`${label} is already running (pid=${ownerPid})`);
+      } catch (ownerError) {
+        if (ownerError?.code === 'EPERM') throw new Error(`${label} is already running (pid=${ownerPid})`);
+        if (ownerError?.code !== 'ESRCH') throw ownerError;
+      }
+      const staleClaim = `${lockDir}.reclaimed-${crypto.createHash('sha256').update(rawOwner).digest('hex').slice(0, 16)}`;
+      try {
+        fs.renameSync(lockDir, staleClaim);
+      } catch (error) {
+        if (error?.code === 'ENOENT') continue;
+        if (error?.code === 'EEXIST' || error?.code === 'ENOTEMPTY') {
+          throw new Error(`${label} lock changed while recovering stale ownership: ${lockDir}`);
+        }
+        throw error;
+      }
+    }
+  } finally {
+    if (!acquired) fs.rmSync(candidateDir, { recursive: true, force: true });
+  }
+}
+
+function releaseDirectoryLock(lockDir, ownerFile, lockToken) {
+  try {
+    const owner = JSON.parse(fs.readFileSync(ownerFile, 'utf8'));
+    if (owner?.lockToken !== lockToken) return;
+    fs.rmSync(lockDir, { recursive: true, force: true });
+  } catch {
+    // Ownership cannot be proven after an external replacement.
+  }
+}
+
+function acquireMigrationLocks(home) {
+  const releases = [];
+  try {
+    releases.push(acquireDirectoryLock(path.join(home, 'data', 'contact-book-v2-migration.lock'), 'contact migration'));
+    const agentsRoot = path.join(home, 'agents');
+    if (fs.existsSync(agentsRoot)) {
+      for (const entry of fs.readdirSync(agentsRoot, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name))) {
+        if (!entry.isDirectory() || !isValidAid(entry.name)) continue;
+        releases.push(acquireDirectoryLock(path.join(agentsRoot, entry.name, AGENT_LOCK_NAME), `contact mutation for ${entry.name}`));
+      }
+    }
+    return () => { for (const release of releases.reverse()) release(); };
+  } catch (error) {
+    for (const release of releases.reverse()) release();
+    throw error;
+  }
+}
+
+function atomicWrite(file, content) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const mode = fs.existsSync(file) ? fs.statSync(file).mode & 0o777 : 0o600;
+  const temp = `${file}.contact-v2-${process.pid}-${Math.random().toString(16).slice(2)}.tmp`;
+  fs.writeFileSync(temp, content, { mode });
+  fs.renameSync(temp, file);
+}
+
+function journalPath(home) {
+  return path.join(home, 'data', 'contact-book-v2-migration.json');
+}
+
+function writeJournal(plan, state) {
+  atomicWrite(journalPath(plan.home), jsonText({ schemaVersion: 1, state, home: plan.home, changes: plan.changes }));
+}
+
+function removeJournal(home) {
+  fs.rmSync(journalPath(home), { force: true });
+}
+
+function recoverJournal(home) {
+  const file = journalPath(home);
+  if (!fs.existsSync(file)) return;
+  let journal;
+  try { journal = JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch { throw new Error(`Contact migration journal is unreadable: ${file}`); }
+  if (journal?.schemaVersion !== 1 || !['prepared', 'committed'].includes(journal.state)
+    || path.resolve(journal.home) !== home || !Array.isArray(journal.changes)) {
+    throw new Error(`Contact migration journal is invalid: ${file}`);
+  }
+  const rootPrefix = home + path.sep;
+  for (const item of journal.changes) {
+    const target = path.resolve(item?.file || '');
+    if (!target.startsWith(rootPrefix) || (item.before !== null && typeof item.before !== 'string')
+      || typeof item.after !== 'string') {
+      throw new Error(`Contact migration journal contains an unsafe change: ${file}`);
+    }
+  }
+  if (journal.state === 'prepared') {
+    for (const item of [...journal.changes].reverse()) {
+      if (item.before === null) fs.rmSync(item.file, { force: true });
+      else atomicWrite(item.file, item.before);
+    }
+  }
+  removeJournal(home);
+}
+
+function applyMigration(plan) {
+  if (!plan.changes.length) return null;
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const backup = path.join(plan.home, 'backups', 'contact-book-v2-migration', stamp);
+  fs.mkdirSync(backup, { recursive: true });
+  for (const item of plan.changes) {
+    if (item.before === null) continue;
+    const destination = path.join(backup, 'files', path.relative(plan.home, item.file));
+    fs.mkdirSync(path.dirname(destination), { recursive: true });
+    fs.writeFileSync(destination, item.before);
+  }
+  fs.writeFileSync(path.join(backup, 'manifest.json'), jsonText({
+    schemaVersion: 2,
+    designVersion: RECEIPT.designVersion,
+    createdAt: new Date().toISOString(),
+    summary: plan.summary,
+    files: plan.changes.map(item => ({ path: path.relative(plan.home, item.file), kind: item.kind })),
+  }));
+  writeJournal(plan, 'prepared');
+  try {
+    for (const item of plan.changes) atomicWrite(item.file, item.after);
+    writeJournal(plan, 'committed');
+    removeJournal(plan.home);
+  } catch (error) {
+    recoverJournal(plan.home);
+    throw error;
+  }
+  return backup;
+}
+
+export function runMigration(options = {}) {
+  const home = resolveHome(options.home);
+  const releaseLocks = acquireMigrationLocks(home);
+  try {
+    assertDaemonStopped(home);
+    recoverJournal(home);
+    const plan = planMigration(home);
+    const backup = options.apply ? applyMigration(plan) : null;
+    return {
+      ok: true,
+      mode: options.apply ? 'applied' : 'dry-run',
+      home,
+      changedFiles: plan.changes.length,
+      backup,
+      summary: plan.summary,
+    };
+  } finally {
+    releaseLocks();
+  }
+}
+
+async function main() {
+  try {
+    const options = parseArgs(process.argv.slice(2));
+    if (options.help) {
+      console.log('Usage: node kits/migrations/migrate-contact-book-v2.mjs [--apply] [--home <path>] [--json]');
+      return;
+    }
+    const result = runMigration(options);
+    if (options.json) console.log(JSON.stringify(result));
+    else console.log(`Contact book v2 migration (${result.mode}): ${result.changedFiles} file(s)`);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (process.argv.includes('--json')) console.log(JSON.stringify({ ok: false, error: message }));
+    else console.error(`Migration failed: ${message}`);
+    process.exitCode = 1;
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) await main();