evolcore 0.0.2 → 0.0.3

package/dist/config/builtin-roles.js

@@ -1,4 +1,6 @@
 import { readBuiltinRoleTemplate } from './builtin-role-templates.js';
+import { expectedRoleRank } from './role-ranks.js';
+export { expectedRoleRank, ROLE_RANKS } from './role-ranks.js';
 export const BUILTIN_USER_ROLES = ['member', 'visitor'];
 export const MANAGEMENT_ROLES = ['owner', 'admin'];
 export function isManagementRole(role) {
@@ -22,8 +24,10 @@ export function getBuiltinRolesConfig() {
  * Management grants are a code-level ceiling, not configurable role policy.
  * A role file may narrow these rules but can never add a management grant.
  */
-export function getManagementCommandPermissions(_role) {
+export function getManagementCommandPermissions(role) {
     return {
+        'contact.read': { allow: true, scopes: ['agent'] },
+        'contact.block': { allow: true, scopes: ['agent'] },
         'role.assign': { allow: true, scopes: ['agent'] },
         'role.revoke': { allow: true, scopes: ['agent'] },
         'role.policy.read': { allow: true, scopes: ['agent'] },
@@ -37,6 +41,7 @@ export function getManagementCommandPermissions(_role) {
 export function applyManagementRoleCeiling(role, configured) {
     const fallback = {
         description: role === 'owner' ? 'Agent owner' : 'Agent administrator',
+        rank: expectedRoleRank(role),
         allowAccess: true,
         permissions: {
             permissionMode: { default: 'request', allowOverride: false },
@@ -46,6 +51,7 @@ export function applyManagementRoleCeiling(role, configured) {
     const policy = configured ?? readBuiltinRoleTemplate(role).definition ?? fallback;
     return {
         ...policy,
+        rank: expectedRoleRank(role),
         allowAccess: true,
         commandPermissions: narrowManagementCommandPermissions(getManagementCommandPermissions(role), policy.commandPermissions || {}),
     };

package/dist/config/config-manager.js

@@ -16,6 +16,8 @@ import { resolvePaths, agentConfig as agentConfigPath, agentContactConfig, agent
 import { atomicReadJson, atomicWriteJson } from '../utils/atomic-write.js';
 import { fileCache } from '../core/daemon-file-cache.js';
 import { isValidAid } from '../aun/aid/validation.js';
+import { isExplicitGroupId } from '../aun/group-identity.js';
+import { parseContactAlias } from './contact-alias.js';
 import { loadSchema, currentVersion, isSchemaName, } from './schema-registry.js';
 import { mergeLayers, expandVars, buildEnvResolver } from './merge.js';
 import { normalizeAgentLifecycle } from './lifecycle.js';
@@ -76,10 +78,7 @@ export function assertRoleConfigV4Ready() {
     if (!fs.existsSync(agentsRoot))
         return;
     const issues = [];
-    const agentSchema = loadSchema('agent-config');
-    const agentSchemaV4 = loadSchema('agent-config', 4);
-    const relationSchema = loadSchema('relation-config');
-    const inspect = (file, schema, legacyAgent = false) => {
+    const inspect = (file, logicalName, minimumVersion) => {
         let value;
         try {
             value = JSON.parse(fs.readFileSync(file, 'utf8'));
@@ -88,18 +87,25 @@ export function assertRoleConfigV4Ready() {
             issues.push({ file, detail: `invalid JSON: ${error instanceof Error ? error.message : String(error)}` });
             return;
         }
-        const expectedVersion = schema.version;
         const actualVersion = value && typeof value === 'object'
             ? value.$schema_version
             : undefined;
-        const acceptedLegacyAgent = legacyAgent && actualVersion === 4;
-        if (actualVersion !== expectedVersion && !acceptedLegacyAgent) {
+        if (typeof actualVersion !== 'number' || actualVersion < minimumVersion) {
             issues.push({
                 file,
-                detail: `$schema_version must be ${expectedVersion}, got ${String(actualVersion)}`,
+                detail: `$schema_version must be at least ${minimumVersion}, got ${String(actualVersion)}`,
             });
+            return;
+        }
+        let schema;
+        try {
+            schema = loadSchema(logicalName, actualVersion);
         }
-        if (!schema.validate(value) && !acceptedLegacyAgent) {
+        catch {
+            issues.push({ file, detail: `unsupported ${logicalName} schema version ${actualVersion}` });
+            return;
+        }
+        if (!schema.validate(value)) {
             const detail = (schema.validate.errors ?? []).map(error => {
                 const extra = typeof error.params?.additionalProperty === 'string'
                     ? ` (additionalProperty=${error.params.additionalProperty})`
@@ -128,12 +134,10 @@ export function assertRoleConfigV4Ready() {
         const agentDirPath = path.join(agentsRoot, entry.name);
         const agentFile = path.join(agentDirPath, 'config.json');
         if (fs.existsSync(agentFile)) {
-            const raw = JSON.parse(fs.readFileSync(agentFile, 'utf8'));
-            const legacyVersion = typeof raw?.$schema_version === 'number' && raw.$schema_version <= 4;
-            inspect(agentFile, legacyVersion ? agentSchemaV4 : agentSchema, raw?.$schema_version === 4);
+            inspect(agentFile, 'agent-config', 4);
         }
         for (const relationFile of walkRelationConfigs(path.join(agentDirPath, 'relations'))) {
-            inspect(relationFile, relationSchema);
+            inspect(relationFile, 'relation-config', 4);
         }
     }
     if (!issues.length)
@@ -156,7 +160,6 @@ export function assertRoleConfigV5Ready() {
     if (!fs.existsSync(agentsRoot))
         return;
     const issues = [];
-    const agentSchema = loadSchema('agent-config', 5);
     const registrySchema = loadSchema('role-registry');
     const readJson = (file) => {
         try {
@@ -177,9 +180,22 @@ export function assertRoleConfigV5Ready() {
         if (!fs.existsSync(agentFile))
             continue;
         const agent = readJson(agentFile);
-        if (!agent || !agentSchema.validate(agent)) {
+        const agentVersion = agent?.$schema_version;
+        let agentSchema = null;
+        if (typeof agentVersion === 'number' && agentVersion >= 5) {
+            try {
+                agentSchema = loadSchema('agent-config', agentVersion);
+            }
+            catch { }
+        }
+        if (!agent || !agentSchema || !agentSchema.validate(agent)) {
             if (agent)
-                issues.push({ file: agentFile, detail: schemaErrors(agentSchema) });
+                issues.push({
+                    file: agentFile,
+                    detail: agentSchema
+                        ? schemaErrors(agentSchema)
+                        : `agent schema version must be supported and >= 5, got ${String(agentVersion)}`,
+                });
             continue;
         }
         const registryFile = agentRolesIndex(aid);
@@ -201,6 +217,191 @@ export function assertRoleConfigV5Ready() {
         `node kits/migrations/migrate-role-config-v5.mjs --home ${JSON.stringify(root)}\n` +
         `node kits/migrations/migrate-role-config-v5.mjs --apply --home ${JSON.stringify(root)}`, { issues });
 }
+/** Final startup gate for the contact-book authorization migration. */
+export function assertContactBookV2Ready() {
+    const root = resolvePaths().root;
+    const agentsRoot = resolvePaths().agentsDir;
+    if (!fs.existsSync(agentsRoot))
+        return;
+    const issues = [];
+    const agentSchema = loadSchema('agent-config', 6);
+    const contactSchema = loadSchema('contact-book', 2);
+    const relationSchema = loadSchema('relation-config', 5);
+    const inspect = (file, schema) => {
+        let value;
+        try {
+            value = JSON.parse(fs.readFileSync(file, 'utf8'));
+        }
+        catch (error) {
+            issues.push({ file, detail: `invalid JSON: ${error instanceof Error ? error.message : String(error)}` });
+            return;
+        }
+        if (!schema.validate(value)) {
+            const detail = (schema.validate.errors ?? [])
+                .map(error => `${error.instancePath || '/'} ${error.message}`)
+                .join('; ');
+            issues.push({ file, detail });
+        }
+    };
+    const walkRelationConfigs = (dir) => {
+        if (!fs.existsSync(dir))
+            return [];
+        const files = [];
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory())
+                files.push(...walkRelationConfigs(full));
+            else if (entry.isFile() && entry.name === 'config.json')
+                files.push(full);
+        }
+        return files;
+    };
+    for (const entry of fs.readdirSync(agentsRoot, { withFileTypes: true })) {
+        if (!entry.isDirectory() || !isValidAid(entry.name))
+            continue;
+        const dir = path.join(agentsRoot, entry.name);
+        const agentFile = path.join(dir, 'config.json');
+        if (!fs.existsSync(agentFile))
+            continue;
+        inspect(agentFile, agentSchema);
+        const contactFile = path.join(dir, 'contact.json');
+        if (fs.existsSync(contactFile)) {
+            inspect(contactFile, contactSchema);
+            inspectContactBookDomain(contactFile, agentFile, issues);
+        }
+        for (const relationFile of walkRelationConfigs(path.join(dir, 'relations'))) {
+            inspect(relationFile, relationSchema);
+        }
+    }
+    const correctionReceipt = path.join(root, 'data', 'contact-book-v2-relation-role-authority.json');
+    if (!hasContactRoleAuthorityReceipt(correctionReceipt)) {
+        const recoverable = findRelationRoleRemovedByExperimentalMigration(root);
+        if (recoverable) {
+            issues.push({
+                file: recoverable,
+                detail: 'experimental contact-book migration backup must be reviewed and relation role authority correction recorded',
+            });
+        }
+    }
+    if (!issues.length)
+        return;
+    const shown = issues.slice(0, 20)
+        .map(issue => `- ${path.relative(root, issue.file)}: ${issue.detail}`)
+        .join('\n');
+    const omitted = issues.length > 20 ? `\n- ... ${issues.length - 20} more issue(s)` : '';
+    throw new ConfigError('CONTACT_BOOK_V2_MIGRATION_REQUIRED', `Contact book authorization migration is required before daemon startup:\n${shown}${omitted}\n` +
+        `node kits/migrations/migrate-contact-book-v2.mjs --home ${JSON.stringify(root)}\n` +
+        `node kits/migrations/migrate-contact-book-v2.mjs --apply --home ${JSON.stringify(root)}`, { issues });
+}
+function inspectContactBookDomain(contactFile, agentFile, issues) {
+    let contact;
+    let agent;
+    try {
+        contact = JSON.parse(fs.readFileSync(contactFile, 'utf8'));
+        agent = JSON.parse(fs.readFileSync(agentFile, 'utf8'));
+    }
+    catch {
+        return;
+    }
+    const owners = new Set(Array.isArray(agent?.owners) ? agent.owners.map(String) : []);
+    const configuredChannelKeys = new Set((Array.isArray(agent?.channels) ? agent.channels : [])
+        .filter((channel) => channel && typeof channel === 'object' && channel.type !== 'aun')
+        .map((channel) => {
+        const type = String(channel.type || '').trim().toLowerCase();
+        const name = String(channel.name || '').trim();
+        return type && name ? `${type}#${String(agent?.aid || '').trim()}#${name}` : '';
+    })
+        .filter(Boolean));
+    const aliases = new Map();
+    for (const [primaryId, entry] of Object.entries(contact?.contacts ?? {})) {
+        if (isExplicitGroupId(primaryId)) {
+            issues.push({ file: contactFile, detail: `group contact ${primaryId} is not supported` });
+        }
+        if (entry?.status === 'blocked' && owners.has(primaryId)) {
+            issues.push({ file: contactFile, detail: `owner contact ${primaryId} cannot be blocked` });
+        }
+        for (const alias of Array.isArray(entry?.aliases) ? entry.aliases : []) {
+            const parsed = parseContactAlias(alias, agent?.aid);
+            if (!parsed) {
+                issues.push({ file: contactFile, detail: `invalid Contact alias ${String(alias)}; expected <channelKey>:<urlEncode(peerId)>` });
+                continue;
+            }
+            if (!configuredChannelKeys.has(parsed.channelKey)) {
+                issues.push({ file: contactFile, detail: `alias ${alias} references an unconfigured channel instance` });
+                continue;
+            }
+            const previous = aliases.get(parsed.alias);
+            if (previous && previous !== primaryId) {
+                issues.push({ file: contactFile, detail: `alias ${parsed.alias} is assigned to both ${previous} and ${primaryId}` });
+            }
+            else {
+                aliases.set(parsed.alias, primaryId);
+            }
+        }
+    }
+}
+function hasContactRoleAuthorityReceipt(file) {
+    try {
+        const value = JSON.parse(fs.readFileSync(file, 'utf8'));
+        return value?.migration === 'contact-book-v2-relation-role-authority' && value?.designVersion === 2;
+    }
+    catch {
+        return false;
+    }
+}
+function findRelationRoleRemovedByExperimentalMigration(root) {
+    const backupsRoot = path.join(root, 'backups', 'contact-book-v2-migration');
+    if (!fs.existsSync(backupsRoot))
+        return null;
+    for (const stamp of fs.readdirSync(backupsRoot, { withFileTypes: true })) {
+        if (!stamp.isDirectory())
+            continue;
+        try {
+            const manifest = JSON.parse(fs.readFileSync(path.join(backupsRoot, stamp.name, 'manifest.json'), 'utf8'));
+            if (manifest?.designVersion >= 2)
+                continue;
+        }
+        catch { }
+        const agentsRoot = path.join(backupsRoot, 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 relationsRoot = path.join(agentsRoot, agent.name, 'relations');
+            if (!fs.existsSync(relationsRoot))
+                continue;
+            for (const relation of fs.readdirSync(relationsRoot, { withFileTypes: true })) {
+                if (!relation.isDirectory() || relation.name.startsWith('_'))
+                    continue;
+                const backupFile = path.join(relationsRoot, relation.name, 'config.json');
+                if (!fs.existsSync(backupFile))
+                    continue;
+                let backupValue;
+                try {
+                    backupValue = JSON.parse(fs.readFileSync(backupFile, 'utf8'));
+                }
+                catch {
+                    continue;
+                }
+                if (typeof backupValue?.role !== 'string' || backupValue.role === 'owner')
+                    continue;
+                const currentFile = path.join(root, 'agents', agent.name, 'relations', relation.name, 'config.json');
+                let currentValue;
+                try {
+                    currentValue = JSON.parse(fs.readFileSync(currentFile, 'utf8'));
+                }
+                catch {
+                    continue;
+                }
+                if (currentValue?.$schema_version === 5) {
+                    return currentFile;
+                }
+            }
+        }
+    }
+    return null;
+}
 /**
  * 启动时检查 schema 版本（daemon 启动时调用）。
  * 扫描所有配置文件，如有版本不匹配则警告一次。
@@ -459,6 +660,10 @@ function finishConfigWrite(target, sel, file) {
         }
     }
 }
+/** Notify cache and security listeners after a caller-owned atomic transaction commits. */
+export function notifyConfigWrite(target, sel) {
+    finishConfigWrite(target, sel, targetPath(target, sel));
+}
 function ensureSchemaVersion(value, version) {
     return value && typeof value === 'object'
         ? { ...value, $schema_version: version }
@@ -643,7 +848,6 @@ export function resolveEffective(sel, opts = {}) {
         lifecycle: config.lifecycle,
         initialized: config.initialized,
         owners: config.owners,
-        admins: config.admins,
         aun: config.aun,
         channels: config.channels ?? [],
         models: config.models,

package/dist/config/contact-alias.js

@@ -0,0 +1,68 @@
+import { isValidAid } from '../aun/aid/validation.js';
+const CHANNEL_SEGMENT = /^[A-Za-z0-9_-]+$/;
+/** Parse the canonical channel instance key used by Contact aliases. */
+export function parseContactChannelKey(value) {
+    if (typeof value !== 'string')
+        return null;
+    const text = value.trim();
+    const parts = text.split('#');
+    if (parts.length !== 3)
+        return null;
+    const [rawType, selfAid, channelName] = parts;
+    const channelType = rawType.toLowerCase();
+    if (!CHANNEL_SEGMENT.test(channelType)
+        || rawType !== channelType
+        || !isValidAid(selfAid)
+        || !CHANNEL_SEGMENT.test(channelName))
+        return null;
+    return {
+        channelType,
+        selfAid,
+        channelName,
+        channelKey: `${channelType}#${selfAid}#${channelName}`,
+    };
+}
+/** Validate that a runtime channelKey belongs to the expected Agent and channel type. */
+export function normalizeContactChannelKey(selfAid, channelType, channelKey) {
+    const parsed = parseContactChannelKey(channelKey);
+    const expectedType = String(channelType || '').trim().toLowerCase();
+    const expectedSelf = String(selfAid || '').trim();
+    if (!parsed || parsed.channelType !== expectedType || parsed.selfAid !== expectedSelf)
+        return null;
+    return parsed.channelKey;
+}
+/** Format `<channelKey>:<urlEncode(peerId)>`. */
+export function formatContactAlias(channelKey, peerId) {
+    const parsed = parseContactChannelKey(channelKey);
+    const peer = String(peerId || '').trim();
+    if (!parsed || parsed.channelType === 'aun' || !peer) {
+        throw new Error(`Invalid Contact alias input: ${String(channelKey)}:${String(peerId)}`);
+    }
+    return `${parsed.channelKey}:${encodeURIComponent(peer)}`;
+}
+/** Parse and canonicalize a stored Contact alias. Non-canonical URL encoding is rejected. */
+export function parseContactAlias(value, expectedSelfAid) {
+    if (typeof value !== 'string')
+        return null;
+    const text = value.trim();
+    const separator = text.indexOf(':');
+    if (separator <= 0 || separator === text.length - 1)
+        return null;
+    const parsedChannel = parseContactChannelKey(text.slice(0, separator));
+    if (!parsedChannel || parsedChannel.channelType === 'aun')
+        return null;
+    if (expectedSelfAid !== undefined && parsedChannel.selfAid !== String(expectedSelfAid || '').trim())
+        return null;
+    const encodedPeerId = text.slice(separator + 1);
+    let peerId;
+    try {
+        peerId = decodeURIComponent(encodedPeerId);
+    }
+    catch {
+        return null;
+    }
+    if (!peerId || encodeURIComponent(peerId) !== encodedPeerId)
+        return null;
+    const alias = `${parsedChannel.channelKey}:${encodedPeerId}`;
+    return { ...parsedChannel, peerId, alias };
+}