evolcore 0.0.2 → 0.0.3

package/dist/config/contact-book.js

@@ -1,6 +1,9 @@
 import { agentContactConfig } from '../paths.js';
 import { isValidAid } from '../aun/aid/validation.js';
-import { ConfigTarget, read, validateConfig, write } from './config-manager.js';
+import { isExplicitGroupId } from '../aun/group-identity.js';
+import { ConfigTarget, read, validateConfig } from './config-manager.js';
+import { ContactMutationError, contactRevision, mutateContactBookSync } from './contact-book-store.js';
+import { formatContactAlias, normalizeContactChannelKey, parseContactAlias, } from './contact-alias.js';
 export class ContactBookError extends Error {
     code;
     constructor(code, message) {
@@ -10,13 +13,11 @@ export class ContactBookError extends Error {
     }
 }
 let aliasMapCache = new WeakMap();
-const emptyAliasMap = {
-    scopedAliasToPrimary: new Map(),
-    conflictingScopedAliases: new Set(),
-    legacyAliasToPrimary: new Map(),
-    conflictingLegacyAliases: new Set(),
+let snapshotByBook = new WeakMap();
+const EMPTY_ALIAS_MAP = {
+    aliasToPrimary: new Map(),
+    conflictingAliases: new Set(),
 };
-const SCOPED_ALIAS_PREFIX = 'channel-key:';
 export function agentContactConfigPath(aid) {
     return agentContactConfig(aid);
 }
@@ -26,346 +27,198 @@ export function readContactBook(selfAid, opts = {}) {
     return read(ConfigTarget.Contact, { self: selfAid }, { cache: opts.cache ?? true });
 }
 export function resolvePrincipal(selfAid, channelType, actorId, channelKey) {
-    const normalizedActor = String(actorId || '').trim();
-    const normalizedChannel = String(channelType || '').trim().toLowerCase();
-    if (normalizedChannel === 'aun') {
-        return isValidAid(normalizedActor)
-            ? { principalId: normalizedActor, principalStatus: 'native_aid' }
-            : { principalStatus: normalizedActor ? 'unmapped' : 'error' };
-    }
-    const normalizedSelf = String(selfAid || '').trim();
-    const normalizedChannelKey = normalizeChannelKey(normalizedSelf, normalizedChannel, channelKey);
-    const legacyAlias = normalizeLegacyAlias(normalizedChannel, normalizedActor);
-    if (!isValidAid(normalizedSelf) || !normalizedChannelKey || !legacyAlias) {
+    const actor = String(actorId || '').trim();
+    const type = String(channelType || '').trim().toLowerCase();
+    if (type === 'aun') {
+        return isValidAid(actor)
+            ? { principalId: actor, principalStatus: 'native_aid' }
+            : { principalStatus: actor ? 'unmapped' : 'error' };
+    }
+    const canonicalChannelKey = normalizeContactChannelKey(selfAid, type, channelKey);
+    if (!isValidAid(String(selfAid || '').trim()) || !actor || !canonicalChannelKey) {
         return { principalStatus: 'error' };
     }
-    const scopedAlias = scopedAliasLookupKey(normalizedChannelKey, normalizedActor);
     try {
-        const aliases = loadAliasMap(normalizedSelf);
-        if (aliases.conflictingScopedAliases.has(scopedAlias)) {
-            return { principalStatus: 'conflict' };
-        }
-        const scopedPrincipalId = aliases.scopedAliasToPrimary.get(scopedAlias);
-        if (scopedPrincipalId) {
-            return { principalId: scopedPrincipalId, principalStatus: 'mapped' };
-        }
-        // Legacy aliases did not identify a channel instance. They remain trusted only
-        // while the configured channel type has exactly one matching instance.
-        if (!isUnambiguousLegacyChannel(normalizedSelf, normalizedChannel, normalizedChannelKey)) {
-            return { principalStatus: 'unmapped' };
-        }
-        if (aliases.conflictingLegacyAliases.has(legacyAlias)) {
+        const aliases = loadAliasMap(selfAid);
+        const exact = formatContactAlias(canonicalChannelKey, actor);
+        if (aliases.conflictingAliases.has(exact))
             return { principalStatus: 'conflict' };
-        }
-        const legacyPrincipalId = aliases.legacyAliasToPrimary.get(legacyAlias);
-        return legacyPrincipalId
-            ? { principalId: legacyPrincipalId, principalStatus: 'mapped' }
-            : { principalStatus: 'unmapped' };
+        const mapped = aliases.aliasToPrimary.get(exact);
+        if (mapped)
+            return { principalId: mapped, principalStatus: 'mapped' };
+        return { principalStatus: 'unmapped' };
     }
     catch {
         return { principalStatus: 'error' };
     }
 }
 export function resolvePrimaryId(selfAid, channelType, actorId, channelKey) {
-    const normalizedActor = String(actorId || '').trim();
-    return resolvePrincipal(selfAid, channelType, normalizedActor, channelKey).principalId ?? normalizedActor;
+    const actor = String(actorId || '').trim();
+    return resolvePrincipal(selfAid, channelType, actor, channelKey).principalId ?? actor;
 }
 export function bindContactAlias(selfAid, primaryId, channelType, actorId, channelKey) {
     const primary = normalizePrimaryId(primaryId);
-    const alias = requireScopedAlias(selfAid, channelType, actorId, channelKey);
-    const legacyAlias = requireLegacyAlias(channelType, actorId);
-    ensureNativeAidIsNotRemapped(primary, channelType, actorId);
-    const next = cloneContactBook(readContactBook(selfAid, { cache: true }));
-    ensureScopedAliasAvailable(next, selfAid, primary, alias.lookupKey);
-    const contacts = next.contacts ?? {};
-    let removedLegacyAlias = false;
-    // An explicit scoped bind supersedes every unscoped copy of the same alias.
-    // Otherwise unbinding the scoped entry could silently reactivate a legacy
-    // mapping owned by another principal.
-    for (const [contactId, value] of Object.entries(contacts)) {
-        const entry = normalizeContactEntry(value);
-        const filtered = entry.aliases.filter(item => normalizeLegacyAliasString(item) !== legacyAlias);
-        if (filtered.length !== entry.aliases.length) {
-            contacts[contactId] = { ...entry, aliases: filtered };
-            removedLegacyAlias = true;
+    const type = String(channelType || '').trim().toLowerCase();
+    const actor = String(actorId || '').trim();
+    if (type === 'aun') {
+        if (!isValidAid(actor) || actor !== primary) {
+            throw new ContactBookError('NATIVE_AID_REMAP_FORBIDDEN', `Native AID "${actor}" cannot be remapped to "${primary}"`);
         }
-    }
-    const current = normalizeContactEntry(contacts[primary]);
-    const alreadyScoped = current.aliases.some(value => (normalizeScopedAliasString(value, selfAid)?.lookupKey === alias.lookupKey));
-    if (alreadyScoped && !removedLegacyAlias) {
         return false;
     }
-    contacts[primary] = {
-        ...current,
-        aliases: alreadyScoped
-            ? current.aliases
-            : [...current.aliases, alias.serialized],
-    };
-    next.contacts = contacts;
-    write(ConfigTarget.Contact, next, { self: selfAid });
-    return true;
+    const canonicalChannelKey = normalizeContactChannelKey(selfAid, type, channelKey);
+    if (!canonicalChannelKey || !actor) {
+        throw new ContactBookError('INVALID_ALIAS', `Invalid contact alias: ${String(channelKey)}:${String(actorId)}`);
+    }
+    const alias = formatContactAlias(canonicalChannelKey, actor);
+    try {
+        return mutateContactBookSync({
+            selfAid,
+            mutation: { type: 'bind-alias', primaryId: primary, alias },
+        }).changed;
+    }
+    catch (error) {
+        if (error instanceof ContactMutationError)
+            throw new ContactBookError(error.code, error.message);
+        throw error;
+    }
 }
 export function unbindContactAlias(selfAid, primaryId, channelType, actorId, channelKey) {
     const primary = normalizePrimaryId(primaryId);
-    const alias = requireScopedAlias(selfAid, channelType, actorId, channelKey);
-    const legacyAlias = requireLegacyAlias(channelType, actorId);
-    const next = cloneContactBook(readContactBook(selfAid, { cache: true }));
-    const contacts = next.contacts ?? {};
-    let changed = false;
-    // Remove the requested scoped binding from the target principal and purge
-    // every unscoped copy of the same raw alias.  Legacy aliases do not carry a
-    // channel-instance identity, so retaining one on another contact would
-    // silently reactivate that principal after this scoped binding is revoked.
-    for (const [contactId, value] of Object.entries(contacts)) {
-        const entry = normalizeContactEntry(value);
-        const filtered = entry.aliases.filter(item => {
-            const isTargetScoped = contactId.trim() === primary
-                && normalizeScopedAliasString(item, selfAid)?.lookupKey === alias.lookupKey;
-            const isLegacyCopy = normalizeLegacyAliasString(item) === legacyAlias;
-            return !isTargetScoped && !isLegacyCopy;
-        });
-        if (filtered.length !== entry.aliases.length) {
-            contacts[contactId] = { ...entry, aliases: filtered };
-            changed = true;
-        }
+    const type = String(channelType || '').trim().toLowerCase();
+    const actor = String(actorId || '').trim();
+    const canonicalChannelKey = normalizeContactChannelKey(selfAid, type, channelKey);
+    if (!canonicalChannelKey || type === 'aun' || !actor) {
+        throw new ContactBookError('INVALID_ALIAS', `Invalid contact alias: ${String(channelKey)}:${String(actorId)}`);
     }
-    if (!changed) {
-        return false;
+    const alias = formatContactAlias(canonicalChannelKey, actor);
+    try {
+        return mutateContactBookSync({
+            selfAid,
+            mutation: { type: 'unbind-alias', primaryId: primary, alias },
+        }).changed;
+    }
+    catch (error) {
+        if (error instanceof ContactMutationError)
+            throw new ContactBookError(error.code, error.message);
+        throw error;
     }
-    next.contacts = contacts;
-    write(ConfigTarget.Contact, next, { self: selfAid });
-    return true;
 }
 export function clearContactBookCache() {
     aliasMapCache = new WeakMap();
+    snapshotByBook = new WeakMap();
+}
+export function getContactSnapshot(selfAid) {
+    const book = readContactBook(selfAid, { cache: true }) ?? { $schema_version: 2, contacts: {} };
+    const cached = snapshotByBook.get(book);
+    if (cached)
+        return cached;
+    const errors = validateConfig(ConfigTarget.Contact, book);
+    if (errors.length) {
+        throw new ContactBookError('INVALID_CONTACT_BOOK', `Invalid contact book for ${selfAid}: ${errors.join('; ')}`);
+    }
+    const aliases = buildAliasMap(book, selfAid);
+    if (aliases.conflictingAliases.size) {
+        throw new ContactBookError('ALIAS_CONFLICT', `Conflicting contact aliases: ${[...aliases.conflictingAliases].join(', ')}`);
+    }
+    const snapshot = buildSnapshot(book, selfAid, aliases);
+    snapshotByBook.set(book, snapshot);
+    return snapshot;
+}
+export function resolveContactView(selfAid, primaryId) {
+    const id = String(primaryId || '').trim();
+    const owner = listAgentOwners(selfAid).includes(id);
+    const entry = getContactSnapshot(selfAid).contacts.get(id);
+    const status = owner ? 'active' : entry?.status ?? 'active';
+    return {
+        primaryId: id,
+        ...(entry?.displayName ? { displayName: entry.displayName } : {}),
+        aliases: entry?.aliases ?? [],
+        status,
+        blocked: status === 'blocked',
+        isOwner: owner,
+        source: owner ? 'owner' : entry ? 'contact' : 'none',
+    };
+}
+export function isBlockedContact(selfAid, primaryId) {
+    return resolveContactView(selfAid, primaryId).blocked;
+}
+function buildSnapshot(book, selfAid, aliases) {
+    const contacts = new Map();
+    const blockedIndex = new Set();
+    const owners = new Set(listAgentOwners(selfAid));
+    for (const [primaryId, rawEntry] of Object.entries(book.contacts)) {
+        if (!isValidAid(primaryId) || isExplicitGroupId(primaryId)) {
+            throw new ContactBookError('INVALID_CONTACT_BOOK', `Invalid contact AID: ${primaryId}`);
+        }
+        if (rawEntry.status === 'blocked' && owners.has(primaryId)) {
+            throw new ContactBookError('INVALID_CONTACT_BOOK', `Owner contact ${primaryId} cannot be blocked`);
+        }
+        const entry = Object.freeze({
+            ...rawEntry,
+            ...(rawEntry.aliases ? { aliases: Object.freeze([...rawEntry.aliases]) } : {}),
+        });
+        contacts.set(primaryId, entry);
+        if (entry.status === 'blocked')
+            blockedIndex.add(primaryId);
+    }
+    return Object.freeze({
+        contacts,
+        aliasIndex: aliases.aliasToPrimary,
+        conflictingAliases: aliases.conflictingAliases,
+        blockedIndex,
+        contactRevision: contactRevision(book),
+    });
 }
 function loadAliasMap(selfAid) {
     const book = readContactBook(selfAid, { cache: true });
     if (!book)
-        return emptyAliasMap;
+        return EMPTY_ALIAS_MAP;
     const cached = aliasMapCache.get(book);
     if (cached)
         return cached;
-    const validationErrors = validateConfig(ConfigTarget.Contact, book);
-    if (validationErrors.length > 0) {
-        throw new ContactBookError('INVALID_CONTACT_BOOK', `Invalid contact book for ${selfAid}: ${validationErrors.join('; ')}`);
+    const errors = validateConfig(ConfigTarget.Contact, book);
+    if (errors.length) {
+        throw new ContactBookError('INVALID_CONTACT_BOOK', `Invalid contact book for ${selfAid}: ${errors.join('; ')}`);
     }
     const built = buildAliasMap(book, selfAid);
     aliasMapCache.set(book, built);
     return built;
 }
-function buildAliasMap(config, selfAid) {
-    const scopedAliasToPrimary = new Map();
-    const conflictingScopedAliases = new Set();
-    const legacyAliasToPrimary = new Map();
-    const conflictingLegacyAliases = new Set();
-    const contacts = config?.contacts;
-    if (!contacts || typeof contacts !== 'object' || Array.isArray(contacts)) {
-        return {
-            scopedAliasToPrimary,
-            conflictingScopedAliases,
-            legacyAliasToPrimary,
-            conflictingLegacyAliases,
-        };
-    }
-    for (const [rawPrimaryId, entry] of Object.entries(contacts)) {
-        const primaryId = rawPrimaryId.trim();
-        if (!isValidAid(primaryId) || !entry || typeof entry !== 'object' || Array.isArray(entry))
+function buildAliasMap(book, selfAid) {
+    const aliasToPrimary = new Map();
+    const conflictingAliases = new Set();
+    for (const [primaryId, entry] of Object.entries(book?.contacts ?? {})) {
+        if (!isValidAid(primaryId) || isExplicitGroupId(primaryId) || !entry || typeof entry !== 'object')
             continue;
-        const aliases = Array.isArray(entry.aliases) ? entry.aliases : [];
-        for (const rawAlias of aliases) {
-            const scoped = normalizeScopedAliasString(rawAlias, selfAid);
-            if (scoped) {
-                addAliasMapping(scopedAliasToPrimary, conflictingScopedAliases, scoped.lookupKey, primaryId);
+        for (const rawAlias of entry.aliases ?? []) {
+            const parsed = parseContactAlias(rawAlias, selfAid);
+            if (!parsed) {
+                throw new ContactBookError('INVALID_CONTACT_BOOK', `Invalid contact alias for ${selfAid}: ${String(rawAlias)}`);
+            }
+            const alias = parsed.alias;
+            if (conflictingAliases.has(alias))
+                continue;
+            const existing = aliasToPrimary.get(alias);
+            if (existing && existing !== primaryId) {
+                aliasToPrimary.delete(alias);
+                conflictingAliases.add(alias);
             }
             else {
-                const legacy = normalizeLegacyAliasString(rawAlias);
-                if (legacy) {
-                    addAliasMapping(legacyAliasToPrimary, conflictingLegacyAliases, legacy, primaryId);
-                }
+                aliasToPrimary.set(alias, primaryId);
             }
         }
     }
-    return {
-        scopedAliasToPrimary,
-        conflictingScopedAliases,
-        legacyAliasToPrimary,
-        conflictingLegacyAliases,
-    };
-}
-function addAliasMapping(aliases, conflicts, alias, primaryId) {
-    if (conflicts.has(alias))
-        return;
-    const existing = aliases.get(alias);
-    if (existing && existing !== primaryId) {
-        aliases.delete(alias);
-        conflicts.add(alias);
-        return;
-    }
-    aliases.set(alias, primaryId);
-}
-function cloneContactBook(config) {
-    const next = config ? { ...config } : {};
-    const contacts = {};
-    const rawContacts = config?.contacts;
-    if (rawContacts && typeof rawContacts === 'object' && !Array.isArray(rawContacts)) {
-        for (const [primaryId, entry] of Object.entries(rawContacts)) {
-            contacts[primaryId] = normalizeContactEntry(entry);
-        }
-    }
-    next.contacts = contacts;
-    return next;
-}
-function normalizeContactEntry(value) {
-    if (!value || typeof value !== 'object' || Array.isArray(value)) {
-        return { aliases: [] };
-    }
-    const entry = value;
-    return {
-        ...entry,
-        aliases: Array.isArray(entry.aliases)
-            ? entry.aliases.filter((item) => typeof item === 'string')
-            : [],
-    };
-}
-function ensureScopedAliasAvailable(config, selfAid, primaryId, alias) {
-    const owners = findScopedAliasOwners(config, selfAid, alias);
-    if (owners.size === 0)
-        return;
-    if (owners.size === 1 && owners.has(primaryId))
-        return;
-    throw new ContactBookError('ALIAS_CONFLICT', `Alias "${alias}" is already bound to ${[...owners].join(', ')}`);
-}
-function findScopedAliasOwners(config, selfAid, alias) {
-    const owners = new Set();
-    const contacts = config.contacts;
-    if (!contacts || typeof contacts !== 'object' || Array.isArray(contacts))
-        return owners;
-    for (const [rawPrimaryId, entry] of Object.entries(contacts)) {
-        const primaryId = rawPrimaryId.trim();
-        if (!primaryId || !entry || typeof entry !== 'object' || Array.isArray(entry))
-            continue;
-        const aliases = Array.isArray(entry.aliases) ? entry.aliases : [];
-        if (aliases.some(value => normalizeScopedAliasString(value, selfAid)?.lookupKey === alias)) {
-            owners.add(primaryId);
-        }
-    }
-    return owners;
+    return { aliasToPrimary, conflictingAliases };
 }
 function normalizePrimaryId(value) {
-    const primaryId = String(value || '').trim();
-    if (!isValidAid(primaryId)) {
-        throw new ContactBookError('INVALID_PRIMARY_ID', `Invalid contact primary AID: ${String(value)}`);
-    }
-    return primaryId;
-}
-function requireLegacyAlias(channelType, actorId) {
-    const alias = normalizeLegacyAlias(channelType, actorId);
-    if (!alias) {
-        throw new ContactBookError('INVALID_ALIAS', `Invalid contact alias: ${String(channelType)}:${String(actorId)}`);
-    }
-    return alias;
-}
-function normalizeLegacyAlias(channelType, actorId) {
-    const channel = String(channelType || '').trim().toLowerCase();
-    const id = String(actorId || '').trim();
-    if (!/^[a-z0-9_-]+$/.test(channel) || !id)
-        return null;
-    return `${channel}:${id}`;
-}
-function normalizeLegacyAliasString(value) {
-    if (typeof value !== 'string')
-        return null;
-    const trimmed = value.trim();
-    if (trimmed.startsWith(SCOPED_ALIAS_PREFIX))
-        return null;
-    const idx = trimmed.indexOf(':');
-    if (idx <= 0 || idx === trimmed.length - 1)
-        return null;
-    return normalizeLegacyAlias(trimmed.slice(0, idx), trimmed.slice(idx + 1));
-}
-function requireScopedAlias(selfAid, channelType, actorId, channelKey) {
-    const normalizedActor = String(actorId || '').trim();
-    const normalizedChannel = String(channelType || '').trim().toLowerCase();
-    const normalizedChannelKey = normalizeChannelKey(selfAid, normalizedChannel, channelKey);
-    if (!normalizedActor || !normalizedChannelKey) {
-        throw new ContactBookError('INVALID_CHANNEL_ALIAS', `Invalid scoped contact alias: ${String(channelKey)}:${String(actorId)}`);
-    }
-    return {
-        lookupKey: scopedAliasLookupKey(normalizedChannelKey, normalizedActor),
-        serialized: serializeScopedAlias(normalizedChannelKey, normalizedActor),
-    };
-}
-function normalizeScopedAliasString(value, selfAid) {
-    if (typeof value !== 'string')
-        return null;
-    const trimmed = value.trim();
-    if (!trimmed.startsWith(SCOPED_ALIAS_PREFIX))
-        return null;
-    const encoded = trimmed.slice(SCOPED_ALIAS_PREFIX.length);
-    const separator = encoded.indexOf(':');
-    if (separator <= 0 || separator === encoded.length - 1)
-        return null;
-    try {
-        const channelKey = decodeURIComponent(encoded.slice(0, separator));
-        const actorId = decodeURIComponent(encoded.slice(separator + 1)).trim();
-        const channelType = channelKey.split('#', 1)[0]?.toLowerCase() ?? '';
-        const normalizedChannelKey = normalizeChannelKey(selfAid, channelType, channelKey);
-        if (!normalizedChannelKey || !actorId)
-            return null;
-        return {
-            lookupKey: scopedAliasLookupKey(normalizedChannelKey, actorId),
-            serialized: serializeScopedAlias(normalizedChannelKey, actorId),
-        };
-    }
-    catch {
-        return null;
-    }
-}
-function serializeScopedAlias(channelKey, actorId) {
-    return `${SCOPED_ALIAS_PREFIX}${encodeURIComponent(channelKey)}:${encodeURIComponent(actorId)}`;
-}
-function scopedAliasLookupKey(channelKey, actorId) {
-    return JSON.stringify([channelKey, actorId]);
-}
-function normalizeChannelKey(selfAid, channelType, value) {
-    const key = typeof value === 'string' ? value.trim() : '';
-    const parts = key.split('#');
-    if (parts.length !== 3)
-        return null;
-    const [rawType, keySelfAid, name] = parts;
-    const normalizedType = rawType.toLowerCase();
-    if (!/^[a-z0-9_-]+$/.test(normalizedType)
-        || normalizedType !== channelType
-        || keySelfAid !== selfAid
-        || !name) {
-        return null;
+    const id = String(value || '').trim();
+    if (!isValidAid(id) || isExplicitGroupId(id)) {
+        throw new ContactBookError('INVALID_PRIMARY_ID', `Invalid individual contact AID: ${String(value)}`);
     }
-    return `${normalizedType}#${keySelfAid}#${name}`;
+    return id;
 }
-function isUnambiguousLegacyChannel(selfAid, channelType, channelKey) {
-    try {
-        const agent = read(ConfigTarget.Agent, { self: selfAid }, { cache: true });
-        const matches = new Set();
-        for (const candidate of agent?.channels ?? []) {
-            if (!candidate || typeof candidate !== 'object')
-                continue;
-            const candidateType = String(candidate.type || '').trim().toLowerCase();
-            const candidateName = String(candidate.name || '').trim();
-            if (candidateType !== channelType || !candidateName || candidateName.includes('#'))
-                continue;
-            matches.add(`${candidateType}#${selfAid}#${candidateName}`);
-        }
-        return matches.size === 1 && matches.has(channelKey);
-    }
-    catch {
-        return false;
-    }
-}
-function ensureNativeAidIsNotRemapped(primaryId, channelType, actorId) {
-    const channel = String(channelType || '').trim().toLowerCase();
-    const actor = String(actorId || '').trim();
-    if (channel === 'aun' && isValidAid(actor) && actor !== primaryId) {
-        throw new ContactBookError('NATIVE_AID_REMAP_FORBIDDEN', `Native AID "${actor}" cannot be remapped to "${primaryId}"`);
-    }
+function listAgentOwners(selfAid) {
+    const agent = read(ConfigTarget.Agent, { self: selfAid }, { cache: true });
+    return [...new Set((agent?.owners ?? []).map(value => String(value || '').trim()).filter(Boolean))];
 }

package/dist/config/contact-operation-service.js

@@ -0,0 +1,110 @@
+import fs from 'fs';
+import { isValidAid } from '../aun/aid/validation.js';
+import { isExplicitGroupId } from '../aun/group-identity.js';
+import { agentConfig } from '../paths.js';
+import { getContactSnapshot, resolveContactView } from './contact-book.js';
+import { ContactMutationError, mutateContactBook } from './contact-book-store.js';
+export function resolveContactCommand(argv) {
+    const args = argv[0] === 'contact' ? argv.slice(1) : [...argv];
+    const selfAid = String(argValue(args, '--self') || '').trim();
+    if (!isValidAid(selfAid))
+        return invalid('INVALID_SELF', '--self must be a valid Agent AID');
+    const positional = stripOptions(args);
+    const [command, subcommand, ...extra] = positional;
+    if (extra.length > 0)
+        return invalid('INVALID_ARGUMENT', `Unexpected contact arguments: ${extra.join(' ')}`);
+    if (command === 'list') {
+        if (subcommand !== undefined || !args.includes('--blocked')) {
+            return invalid('INVALID_ARGUMENT', 'Only ec contact list --blocked is currently supported');
+        }
+        return {
+            ok: true,
+            command: { kind: 'list-blocked', operationId: 'contact.read', selfAid, canonicalArgv: canonicalArgv(argv) },
+        };
+    }
+    if (command === 'block' || command === 'unblock') {
+        if (!isValidAid(subcommand || '') || isExplicitGroupId(subcommand || '')) {
+            return invalid('INVALID_AID', 'primaryId must be a valid individual AID');
+        }
+        return {
+            ok: true,
+            command: {
+                kind: 'set-blocked',
+                operationId: 'contact.block',
+                selfAid,
+                primaryId: subcommand,
+                blocked: command === 'block',
+                canonicalArgv: canonicalArgv(argv),
+            },
+        };
+    }
+    return invalid('UNKNOWN_COMMAND', `Unknown contact command: ${positional.join(' ')}`);
+}
+export async function executeResolvedContactCommand(command, actor = 'local-cli') {
+    if (!fs.existsSync(agentConfig(command.selfAid))) {
+        return { ok: false, code: 'AGENT_NOT_FOUND', error: `Agent does not exist: ${command.selfAid}` };
+    }
+    try {
+        if (command.kind === 'list-blocked') {
+            const snapshot = getContactSnapshot(command.selfAid);
+            return {
+                ok: true,
+                operation: 'list-blocked',
+                selfAid: command.selfAid,
+                contactRevision: snapshot.contactRevision,
+                items: [...snapshot.blockedIndex].sort().map(id => resolveContactView(command.selfAid, id)),
+            };
+        }
+        if (command.kind === 'set-blocked') {
+            const result = await mutateContactBook({
+                selfAid: command.selfAid,
+                actor,
+                mutation: {
+                    type: 'set-status',
+                    primaryId: command.primaryId,
+                    status: command.blocked ? 'blocked' : 'active',
+                },
+            });
+            return {
+                ok: true,
+                operation: 'set-blocked',
+                selfAid: command.selfAid,
+                primaryId: command.primaryId,
+                blocked: command.blocked,
+                changed: result.changed,
+                contactRevision: result.contactRevision,
+            };
+        }
+        return { ok: false, code: 'CONTACT_OPERATION_FAILED', error: 'Unsupported contact operation' };
+    }
+    catch (error) {
+        if (error instanceof ContactMutationError) {
+            return { ok: false, code: error.code, error: error.message, ...(error.data ? { data: error.data } : {}) };
+        }
+        return { ok: false, code: 'CONTACT_OPERATION_FAILED', error: error instanceof Error ? error.message : String(error) };
+    }
+}
+function argValue(args, flag) {
+    const index = args.indexOf(flag);
+    return index >= 0 ? args[index + 1] : undefined;
+}
+function stripOptions(args) {
+    const result = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === '--self' || arg === '--format') {
+            index += 1;
+            continue;
+        }
+        if (arg === '--blocked')
+            continue;
+        result.push(arg);
+    }
+    return result;
+}
+function canonicalArgv(argv) {
+    return argv[0] === 'contact' ? [...argv] : ['contact', ...argv];
+}
+function invalid(code, reason) {
+    return { ok: false, code, reason };
+}