evolcore 0.0.2 → 0.0.4

package/dist/config/contact-book-store.js

@@ -0,0 +1,622 @@
+import crypto from 'crypto';
+import fs from 'fs';
+import path from 'path';
+import { isValidAid } from '../aun/aid/validation.js';
+import { isExplicitGroupId } from '../aun/group-identity.js';
+import { agentConfig, agentContactConfig, agentDir, resolvePaths } from '../paths.js';
+import { atomicReadJson, atomicWrite, atomicWriteJson } from '../utils/atomic-write.js';
+import { fileCache } from '../core/daemon-file-cache.js';
+import { ConfigTarget, notifyConfigWrite, validateConfig } from './config-manager.js';
+import { parseContactAlias } from './contact-alias.js';
+import { clearRoleStoreCache } from './role-store.js';
+const LOCK_NAME = '.contact-book-mutation.lock';
+const JOURNAL_NAME = '.contact-book-mutation.json';
+const LOCK_WAIT_MS = 5_000;
+const LOCK_RETRY_MS = 20;
+export const EMPTY_CONTACT_REVISION = crypto.createHash('sha256').update('').digest('hex');
+export class ContactMutationError extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.code = code;
+        this.data = data;
+        this.name = 'ContactMutationError';
+    }
+}
+const mutationTails = new Map();
+export function contactRevision(config) {
+    if (!config)
+        return EMPTY_CONTACT_REVISION;
+    return crypto.createHash('sha256').update(stableStringify(config)).digest('hex');
+}
+export function readContactRevision(selfAid) {
+    return contactRevision(readContactBookFromDisk(selfAid));
+}
+export function mutateContactBook(request) {
+    return enqueueContactMutation(request, []);
+}
+/**
+ * Prepare a mutation while holding the same cross-process lock used by every Contact Book write.
+ * The callback must stay synchronous so the lock is never retained across an await boundary.
+ */
+export function mutateContactBookPrepared(selfAid, prepare) {
+    const normalizedAid = normalizeAid(selfAid, 'self AID');
+    const previous = mutationTails.get(normalizedAid) ?? Promise.resolve();
+    let release;
+    const tail = new Promise(resolve => { release = resolve; });
+    mutationTails.set(normalizedAid, tail);
+    return previous
+        .catch(() => { })
+        .then(() => mutateContactBookPreparedSyncInternal(normalizedAid, prepare))
+        .finally(() => {
+        release();
+        if (mutationTails.get(normalizedAid) === tail)
+            mutationTails.delete(normalizedAid);
+    });
+}
+export function mutateContactBookTransaction(request, changes) {
+    return enqueueContactMutation(request, changes);
+}
+/** Synchronous transaction variant for configuration writes that must commit atomically with contacts. */
+export function mutateContactBookTransactionSync(request, changes) {
+    return mutateContactBookSyncInternal(request, changes);
+}
+function enqueueContactMutation(request, changes) {
+    const selfAid = normalizeAid(request.selfAid, 'self AID');
+    const previous = mutationTails.get(selfAid) ?? Promise.resolve();
+    let release;
+    const tail = new Promise(resolve => { release = resolve; });
+    mutationTails.set(selfAid, tail);
+    return previous
+        .catch(() => { })
+        .then(() => mutateContactBookSyncInternal({ ...request, selfAid }, changes))
+        .finally(() => {
+        release();
+        if (mutationTails.get(selfAid) === tail)
+            mutationTails.delete(selfAid);
+    });
+}
+/** Synchronous compatibility entry for channel bind flows. The critical section has no await. */
+export function mutateContactBookSync(request) {
+    return mutateContactBookSyncInternal(request, []);
+}
+/** Recover every interrupted Contact transaction before startup reads config. */
+export function recoverAllContactBookMutationsSync() {
+    const agentsRoot = resolvePaths().agentsDir;
+    if (!fs.existsSync(agentsRoot))
+        return 0;
+    let recovered = 0;
+    for (const entry of fs.readdirSync(agentsRoot, { withFileTypes: true })) {
+        if (!entry.isDirectory() || !isValidAid(entry.name))
+            continue;
+        if (!fs.existsSync(journalFile(entry.name)))
+            continue;
+        const release = acquireAgentLock(entry.name);
+        try {
+            if (recoverMutation(entry.name))
+                recovered += 1;
+        }
+        finally {
+            release();
+        }
+    }
+    return recovered;
+}
+function mutateContactBookSyncInternal(request, transactionChanges) {
+    const selfAid = normalizeAid(request.selfAid, 'self AID');
+    const release = acquireAgentLock(selfAid);
+    try {
+        recoverMutation(selfAid);
+        const file = agentContactConfig(selfAid);
+        const current = readContactBookFromDisk(selfAid);
+        const previousRevision = contactRevision(current);
+        if (request.expectedContactRevision !== undefined
+            && request.expectedContactRevision !== previousRevision) {
+            throw new ContactMutationError('CONFLICT', 'Contact book changed since it was read', {
+                expectedContactRevision: request.expectedContactRevision,
+                contactRevision: previousRevision,
+            });
+        }
+        const next = cloneBook(current);
+        applyMutation(next, request.mutation, selfAid);
+        validateContactBook(next, selfAid);
+        const nextRevision = contactRevision(next);
+        validateTransactionChanges(selfAid, transactionChanges);
+        if (nextRevision === previousRevision && transactionChanges.length === 0) {
+            return { changed: false, contactRevision: previousRevision, previousContactRevision: previousRevision, contact: next };
+        }
+        const before = readTextOrNull(file);
+        const after = `${JSON.stringify(next, null, 2)}\n`;
+        const changes = [
+            ...(nextRevision === previousRevision ? [] : [{ file, before, after }]),
+            ...transactionChanges,
+        ];
+        writeJournal(selfAid, { schemaVersion: 1, state: 'prepared', selfAid, changes });
+        try {
+            for (const change of changes)
+                applyTransactionChange(change);
+            writeJournal(selfAid, { schemaVersion: 1, state: 'committed', selfAid, changes });
+            removeJournal(selfAid);
+        }
+        catch (error) {
+            recoverMutation(selfAid);
+            throw error;
+        }
+        if (nextRevision !== previousRevision) {
+            notifyConfigWrite(ConfigTarget.Contact, { self: selfAid });
+            appendAudit(selfAid, request, previousRevision, nextRevision);
+        }
+        for (const change of transactionChanges)
+            fileCache.invalidate(change.file);
+        if (transactionChanges.length)
+            clearRoleStoreCache(selfAid);
+        return {
+            changed: nextRevision !== previousRevision,
+            contactRevision: nextRevision,
+            previousContactRevision: previousRevision,
+            contact: next,
+        };
+    }
+    finally {
+        release();
+    }
+}
+function mutateContactBookPreparedSyncInternal(selfAid, prepare) {
+    const release = acquireAgentLock(selfAid);
+    try {
+        recoverMutation(selfAid);
+        const file = agentContactConfig(selfAid);
+        const current = readContactBookFromDisk(selfAid);
+        const previousRevision = contactRevision(current);
+        const next = cloneBook(current);
+        const prepared = prepare({ contact: next, contactRevision: previousRevision });
+        if (prepared.mutation)
+            applyMutation(next, prepared.mutation, selfAid);
+        validateContactBook(next, selfAid);
+        const nextRevision = contactRevision(next);
+        if (nextRevision === previousRevision) {
+            return {
+                changed: false,
+                contactRevision: previousRevision,
+                previousContactRevision: previousRevision,
+                contact: next,
+                value: prepared.value,
+            };
+        }
+        prepared.beforeCommit?.({
+            contact: next,
+            previousContactRevision: previousRevision,
+            contactRevision: nextRevision,
+        });
+        const before = readTextOrNull(file);
+        const after = `${JSON.stringify(next, null, 2)}\n`;
+        const changes = [{ file, before, after }];
+        writeJournal(selfAid, { schemaVersion: 1, state: 'prepared', selfAid, changes });
+        try {
+            applyTransactionChange(changes[0]);
+            writeJournal(selfAid, { schemaVersion: 1, state: 'committed', selfAid, changes });
+            removeJournal(selfAid);
+        }
+        catch (error) {
+            recoverMutation(selfAid);
+            throw error;
+        }
+        notifyConfigWrite(ConfigTarget.Contact, { self: selfAid });
+        appendAudit(selfAid, {
+            selfAid,
+            actor: prepared.actor,
+            mutation: prepared.mutation,
+        }, previousRevision, nextRevision);
+        return {
+            changed: true,
+            contactRevision: nextRevision,
+            previousContactRevision: previousRevision,
+            contact: next,
+            value: prepared.value,
+        };
+    }
+    finally {
+        release();
+    }
+}
+function applyMutation(book, mutation, selfAid) {
+    const contacts = book.contacts;
+    if (mutation.type === 'batch') {
+        for (const item of mutation.mutations)
+            applyMutation(book, item, selfAid);
+        return;
+    }
+    if (mutation.type === 'ensure-contacts') {
+        for (const rawPrimaryId of mutation.primaryIds) {
+            const primaryId = normalizeContactAid(rawPrimaryId);
+            if (!contacts[primaryId])
+                contacts[primaryId] = {};
+        }
+        return;
+    }
+    const primaryId = normalizeContactAid(mutation.primaryId);
+    const existing = contacts[primaryId];
+    if (mutation.type === 'set-status') {
+        if (isOwner(selfAid, primaryId) && mutation.status === 'blocked') {
+            throw new ContactMutationError('OWNER_PROTECTED', 'An Agent owner cannot be blocked');
+        }
+        contacts[primaryId] = compactEntry({
+            ...existing,
+            status: mutation.status === 'active' ? undefined : mutation.status,
+            pendingRequest: undefined,
+            declinedAt: mutation.status === 'declined' ? existing?.declinedAt ?? new Date().toISOString() : undefined,
+        });
+        return;
+    }
+    if (mutation.type === 'set-request') {
+        if (isOwner(selfAid, primaryId)) {
+            throw new ContactMutationError('OWNER_PROTECTED', 'An Agent owner cannot submit a contact request');
+        }
+        contacts[primaryId] = compactEntry({
+            ...existing,
+            status: 'pending',
+            pendingRequest: { ...mutation.request },
+            declinedAt: undefined,
+        });
+        return;
+    }
+    if (mutation.type === 'review-request') {
+        if (!existing || existing.status !== 'pending' || existing.pendingRequest?.id !== mutation.requestId) {
+            throw new ContactMutationError('REQUEST_STALE', 'The contact request has changed or was already handled');
+        }
+        if (Date.parse(existing.pendingRequest.expiresAt) <= Date.parse(mutation.now)) {
+            throw new ContactMutationError('REQUEST_EXPIRED', 'The contact request has expired');
+        }
+        if (mutation.decision === 'reject') {
+            delete contacts[primaryId];
+        }
+        else {
+            contacts[primaryId] = compactEntry({
+                ...existing,
+                status: mutation.decision === 'block' ? 'blocked' : undefined,
+                pendingRequest: undefined,
+                declinedAt: undefined,
+            });
+        }
+        return;
+    }
+    if (mutation.type === 'expire-request') {
+        if (!existing || existing.status !== 'pending' || existing.pendingRequest?.id !== mutation.requestId)
+            return;
+        if (Date.parse(existing.pendingRequest.expiresAt) > Date.parse(mutation.now))
+            return;
+        contacts[primaryId] = compactEntry({
+            ...existing,
+            status: 'declined',
+            pendingRequest: undefined,
+            declinedAt: existing.pendingRequest.expiresAt,
+        });
+        return;
+    }
+    if (mutation.type === 'set-display-name') {
+        contacts[primaryId] = compactEntry({ ...existing, displayName: mutation.displayName ?? undefined });
+        return;
+    }
+    if (mutation.type === 'bind-alias' || mutation.type === 'bind-alias-eligible') {
+        if (mutation.type === 'bind-alias-eligible') {
+            const eligible = isOwner(selfAid, primaryId)
+                || (!!existing && (existing.status === undefined || existing.status === 'active'));
+            if (!eligible) {
+                throw new ContactMutationError('CONTACT_NOT_ACTIVE', 'Only an active contact or Agent owner can bind an alias');
+            }
+        }
+        for (const [owner, entry] of Object.entries(contacts)) {
+            if (owner !== primaryId && entry.aliases?.includes(mutation.alias)) {
+                throw new ContactMutationError('ALIAS_CONFLICT', `Alias ${mutation.alias} is already bound to ${owner}`);
+            }
+        }
+        const aliases = Array.isArray(contacts[primaryId]?.aliases) ? [...contacts[primaryId].aliases] : [];
+        if (!aliases.includes(mutation.alias))
+            aliases.push(mutation.alias);
+        contacts[primaryId] = compactEntry({ ...contacts[primaryId], aliases });
+        return;
+    }
+    if (mutation.type === 'unbind-alias') {
+        removeAliasEverywhere(contacts, mutation.alias, primaryId);
+        return;
+    }
+    throw new ContactMutationError('INVALID_MUTATION', `Unsupported Contact Book mutation: ${String(mutation?.type)}`);
+}
+function validateContactBook(book, selfAid) {
+    const schemaErrors = validateConfig(ConfigTarget.Contact, book);
+    if (schemaErrors.length) {
+        throw new ContactMutationError('INVALID_CONTACT_BOOK', schemaErrors.join('; '));
+    }
+    const aliases = new Map();
+    const configuredChannelKeys = readConfiguredContactChannelKeys(selfAid);
+    for (const [primaryId, entry] of Object.entries(book.contacts)) {
+        if (!isValidAid(primaryId) || isExplicitGroupId(primaryId)) {
+            throw new ContactMutationError('INVALID_CONTACT_BOOK', `Invalid contact AID: ${primaryId}`);
+        }
+        if (entry.status && isOwner(selfAid, primaryId)) {
+            throw new ContactMutationError('OWNER_PROTECTED', 'An Agent owner must remain active');
+        }
+        if (entry.status === 'pending') {
+            if (!entry.pendingRequest || !Number.isFinite(Date.parse(entry.pendingRequest.submittedAt))
+                || !Number.isFinite(Date.parse(entry.pendingRequest.expiresAt))
+                || Date.parse(entry.pendingRequest.expiresAt) <= Date.parse(entry.pendingRequest.submittedAt)) {
+                throw new ContactMutationError('INVALID_CONTACT_BOOK', `Invalid pending request for ${primaryId}`);
+            }
+        }
+        else if (entry.pendingRequest) {
+            throw new ContactMutationError('INVALID_CONTACT_BOOK', `pendingRequest requires pending status for ${primaryId}`);
+        }
+        if (entry.status === 'declined' && !Number.isFinite(Date.parse(entry.declinedAt ?? ''))) {
+            throw new ContactMutationError('INVALID_CONTACT_BOOK', `declinedAt is required for ${primaryId}`);
+        }
+        if (entry.status !== 'declined' && entry.declinedAt) {
+            throw new ContactMutationError('INVALID_CONTACT_BOOK', `declinedAt requires declined status for ${primaryId}`);
+        }
+        for (const alias of entry.aliases ?? []) {
+            const parsed = parseContactAlias(alias, selfAid);
+            if (!parsed) {
+                throw new ContactMutationError('INVALID_CONTACT_BOOK', `Invalid contact alias for ${selfAid}: ${String(alias)}`);
+            }
+            if (!configuredChannelKeys.has(parsed.channelKey)) {
+                throw new ContactMutationError('INVALID_CONTACT_BOOK', `Contact alias references an unconfigured channel instance: ${alias}`);
+            }
+            const owner = aliases.get(alias);
+            if (owner && owner !== primaryId) {
+                throw new ContactMutationError('ALIAS_CONFLICT', `Alias ${alias} is bound to both ${owner} and ${primaryId}`);
+            }
+            aliases.set(alias, primaryId);
+        }
+    }
+}
+function readConfiguredContactChannelKeys(selfAid) {
+    let agent;
+    try {
+        agent = atomicReadJson(agentConfig(selfAid));
+    }
+    catch (error) {
+        throw new ContactMutationError('INVALID_CONTACT_BOOK', `Cannot read Agent channel inventory: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return new Set((Array.isArray(agent?.channels) ? agent.channels : [])
+        .filter((channel) => channel && typeof channel === 'object' && String(channel.type || '').toLowerCase() !== 'aun')
+        .map((channel) => {
+        const type = String(channel.type || '').trim().toLowerCase();
+        const name = String(channel.name || '').trim();
+        return type && name ? `${type}#${selfAid}#${name}` : '';
+    })
+        .filter(Boolean));
+}
+function cloneBook(book) {
+    const contacts = {};
+    for (const [primaryId, entry] of Object.entries(book?.contacts ?? {})) {
+        contacts[primaryId] = {
+            ...entry,
+            ...(entry.aliases ? { aliases: [...entry.aliases] } : {}),
+            ...(entry.pendingRequest ? { pendingRequest: { ...entry.pendingRequest } } : {}),
+        };
+    }
+    return { $schema_version: 3, contacts };
+}
+function compactEntry(entry) {
+    return Object.fromEntries(Object.entries(entry).filter(([, value]) => value !== undefined));
+}
+function removeAliasEverywhere(contacts, alias, onlyOwner) {
+    for (const [primaryId, entry] of Object.entries(contacts)) {
+        if (onlyOwner && primaryId !== onlyOwner)
+            continue;
+        const aliases = (entry.aliases ?? []).filter(candidate => candidate !== alias);
+        if (aliases.length !== (entry.aliases ?? []).length)
+            contacts[primaryId] = compactEntry({ ...entry, aliases });
+    }
+}
+function readContactBookFromDisk(selfAid) {
+    try {
+        return atomicReadJson(agentContactConfig(selfAid));
+    }
+    catch (error) {
+        throw new ContactMutationError('INVALID_CONTACT_BOOK', `Cannot read contact book: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function acquireAgentLock(selfAid) {
+    const lockDir = path.join(agentDir(selfAid), LOCK_NAME);
+    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, `${JSON.stringify({
+        pid: process.pid,
+        processStartedAt: Date.now() - Math.floor(process.uptime() * 1000),
+        createdAt: new Date().toISOString(),
+        lockToken,
+    }, null, 2)}\n`, { mode: 0o600 });
+    const deadline = Date.now() + LOCK_WAIT_MS;
+    let acquired = false;
+    try {
+        while (true) {
+            try {
+                fs.renameSync(candidateDir, lockDir);
+                acquired = true;
+                return () => releaseAgentLock(lockDir, ownerFile, lockToken);
+            }
+            catch (error) {
+                if (error?.code !== 'EEXIST' && error?.code !== 'ENOTEMPTY')
+                    throw error;
+                if (removeStaleLock(lockDir, ownerFile))
+                    continue;
+                if (Date.now() >= deadline) {
+                    throw new ContactMutationError('LOCK_TIMEOUT', `Timed out waiting for contact mutation lock: ${lockDir}`);
+                }
+                Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, LOCK_RETRY_MS);
+            }
+        }
+    }
+    finally {
+        if (!acquired)
+            fs.rmSync(candidateDir, { recursive: true, force: true });
+    }
+}
+function removeStaleLock(lockDir, ownerFile) {
+    let rawOwner;
+    let pid;
+    try {
+        rawOwner = fs.readFileSync(ownerFile, 'utf8');
+        pid = Number(JSON.parse(rawOwner).pid);
+    }
+    catch {
+        return false;
+    }
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return false;
+    }
+    catch (error) {
+        if (error?.code !== 'ESRCH')
+            return false;
+        const staleClaim = `${lockDir}.reclaimed-${crypto.createHash('sha256').update(rawOwner).digest('hex').slice(0, 16)}`;
+        try {
+            fs.renameSync(lockDir, staleClaim);
+            return true;
+        }
+        catch (renameError) {
+            if (renameError?.code === 'ENOENT')
+                return true;
+            if (renameError?.code === 'EEXIST' || renameError?.code === 'ENOTEMPTY')
+                return false;
+            throw renameError;
+        }
+    }
+}
+function releaseAgentLock(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 {
+        // A missing or replaced owner file means ownership can no longer be proven.
+    }
+}
+function recoverMutation(selfAid) {
+    const file = journalFile(selfAid);
+    if (!fs.existsSync(file))
+        return false;
+    const journal = atomicReadJson(file);
+    if (!journal || journal.schemaVersion !== 1 || journal.selfAid !== selfAid
+        || !['prepared', 'committed'].includes(journal.state) || !Array.isArray(journal.changes)) {
+        throw new ContactMutationError('INVALID_JOURNAL', `Invalid contact mutation journal: ${file}`);
+    }
+    validateTransactionChanges(selfAid, journal.changes);
+    if (journal.state === 'prepared') {
+        for (const change of [...journal.changes].reverse()) {
+            applyTransactionChange({ ...change, after: change.before });
+        }
+    }
+    for (const change of journal.changes)
+        fileCache.invalidate(change.file);
+    clearRoleStoreCache(selfAid);
+    removeJournal(selfAid);
+    return true;
+}
+function validateTransactionChanges(selfAid, changes) {
+    const root = path.resolve(agentDir(selfAid));
+    const seen = new Set();
+    for (const change of changes) {
+        if (!change || typeof change !== 'object' || typeof change.file !== 'string' || !change.file) {
+            throw new ContactMutationError('INVALID_TRANSACTION', 'Transaction changes must contain a file path');
+        }
+        const file = path.resolve(change.file);
+        const relative = path.relative(root, file);
+        if (!relative || relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+            throw new ContactMutationError('UNSAFE_TRANSACTION', `Transaction file is outside the Agent directory: ${file}`);
+        }
+        if (seen.has(file)) {
+            throw new ContactMutationError('INVALID_TRANSACTION', `Transaction contains duplicate file changes: ${file}`);
+        }
+        seen.add(file);
+        if ((change.before !== null && typeof change.before !== 'string')
+            || (change.after !== null && typeof change.after !== 'string')) {
+            throw new ContactMutationError('INVALID_TRANSACTION', `Invalid transaction content for ${file}`);
+        }
+    }
+}
+function applyTransactionChange(change) {
+    if (change.after === null) {
+        for (const candidate of [change.file, `${change.file}_`, `${change.file}__`]) {
+            fs.rmSync(candidate, { force: true });
+        }
+    }
+    else {
+        atomicWrite(change.file, change.after);
+    }
+}
+function writeJournal(selfAid, journal) {
+    atomicWriteJson(journalFile(selfAid), journal);
+}
+function removeJournal(selfAid) {
+    const file = journalFile(selfAid);
+    for (const candidate of [file, `${file}_`, `${file}__`])
+        fs.rmSync(candidate, { force: true });
+}
+function journalFile(selfAid) {
+    return path.join(agentDir(selfAid), JOURNAL_NAME);
+}
+function appendAudit(selfAid, request, previousContactRevision, contactRevisionValue) {
+    const file = path.join(resolvePaths().dataDir, 'contact-book-audit.jsonl');
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.appendFileSync(file, `${JSON.stringify({
+        timestamp: new Date().toISOString(),
+        selfAid,
+        actor: request.actor ?? 'system',
+        mutation: request.mutation,
+        previousContactRevision,
+        contactRevision: contactRevisionValue,
+    })}\n`, { mode: 0o600 });
+}
+function isOwner(selfAid, primaryId) {
+    try {
+        const config = atomicReadJson(path.join(agentDir(selfAid), 'config.json'));
+        return config?.owners?.some(value => String(value || '').trim() === primaryId) ?? false;
+    }
+    catch {
+        return false;
+    }
+}
+function normalizeAid(value, label) {
+    const aid = String(value || '').trim();
+    if (!isValidAid(aid))
+        throw new ContactMutationError('INVALID_AID', `Invalid ${label}: ${JSON.stringify(value)}`);
+    return aid;
+}
+function normalizeContactAid(value) {
+    const aid = normalizeAid(value, 'contact AID');
+    if (isExplicitGroupId(aid)) {
+        throw new ContactMutationError('INVALID_AID', `Contact Book does not support group AID: ${JSON.stringify(value)}`);
+    }
+    return aid;
+}
+function stableStringify(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(',')}]`;
+    if (value && typeof value === 'object') {
+        return `{${Object.entries(value)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([key, item]) => `${JSON.stringify(key)}:${stableStringify(item)}`)
+            .join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+function readTextOrNull(file) {
+    try {
+        return fs.readFileSync(file, 'utf8');
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}

package/dist/config/contact-book-v2-startup.js

@@ -0,0 +1,35 @@
+import path from 'path';
+import { pathToFileURL } from 'url';
+import { getPackageRoot, resolvePaths } from '../paths.js';
+import { assertContactBookV2Ready, ConfigError } from './config-manager.js';
+import { recoverAllContactBookMutationsSync } from './contact-book-store.js';
+export async function ensureContactBookV2OnStartup() {
+    try {
+        recoverAllContactBookMutationsSync();
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new ConfigError('CONTACT_BOOK_V2_RECOVERY_FAILED', `Interrupted contact transaction recovery failed: ${detail}`, { cause: error });
+    }
+    try {
+        assertContactBookV2Ready();
+        return null;
+    }
+    catch (error) {
+        if (!(error instanceof ConfigError) || error.code !== 'CONTACT_BOOK_V2_MIGRATION_REQUIRED')
+            throw error;
+    }
+    const home = resolvePaths().root;
+    const script = path.join(getPackageRoot(), 'kits', 'migrations', 'migrate-contact-book-v2.mjs');
+    try {
+        const migration = await import(pathToFileURL(script).href);
+        const result = migration.runMigration({ home, apply: true });
+        assertContactBookV2Ready();
+        return result;
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new ConfigError('CONTACT_BOOK_V2_MIGRATION_FAILED', `Automatic contact book v2 migration failed: ${detail}\n` +
+            `node kits/migrations/migrate-contact-book-v2.mjs --apply --home ${JSON.stringify(home)}`, { cause: error });
+    }
+}