evolcore 0.0.1 → 0.0.3

package/dist/core/command/role-menu.js

@@ -0,0 +1,1623 @@
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+import { ConfigTarget, read, resolveEffectiveWithSources, write } from '../../config/config-manager.js';
+import { getBuiltinRolesConfig, getRoleDefinition, isValidUserRoleName, readRolesConfig, } from '../../config/roles.js';
+import { BUILTIN_USER_ROLES, MANAGEMENT_ROLES, expectedRoleRank, isManagementRole } from '../../config/builtin-roles.js';
+import { checkRoleAccess, isStaticAgentOwner, resolvePeerRoleDetail } from '../../config/peer-role-resolver.js';
+import { relationFieldWriteOperation, resolveRoleFieldPermission, } from '../../config/config-field-policy.js';
+import { evaluateRoleOperationCapability } from '../auth/operation-authorizer.js';
+import { listOperations } from '../auth/operation-catalog.js';
+import { auditRoleMutation } from '../auth/authorization-audit.js';
+import { formatPeerKey, parsePeerKey } from '../relation/peer-identity.js';
+import { agentDir, agentRoleConfig, agentRolesIndex, agentRelationConfig, agentRelationsDir, resolvePaths } from '../../paths.js';
+import { atomicReadJson, atomicWrite, atomicWriteJson } from '../../utils/atomic-write.js';
+import { fileCache } from '../daemon-file-cache.js';
+import { currentVersion } from '../../config/schema-registry.js';
+import { loadSchema } from '../../config/schema-registry.js';
+import { rolePermissionFields, rolePermissionFieldOptions, rolePermissionFieldPatterns, validateRoleConfig, } from '../../config/role-schema.js';
+import { groupInfo, groupList } from '../../aun/msg/group.js';
+import { aidLookup, isValidAid } from '../../aun/aid/identity.js';
+import { isExplicitGroupId } from '../../aun/group-identity.js';
+import { readJsonFile, readLastJsonlLine, scanChatDirs, scanMetaFiles } from '../session/session-fs-store.js';
+import { constrainResolvedModelForRole } from '../model/model-permission.js';
+import { resolveRuntimePermissionMode, resolveRuntimeStringField } from '../role/runtime-policy.js';
+import { readRoleDefinition, readRoleRegistry, registerRole, writeRoleDefinition, writeRoleRegistry, } from '../../config/role-service.js';
+import { clearRoleStoreCache, readRoleStore, roleRegistryExists } from '../../config/role-store.js';
+const ROLE_MENU_SCHEMA_VERSION = 1;
+const ROLE_UPDATE_MAX_BYTES = 1024 * 1024;
+const DEFAULT_PAGE_SIZE = 50;
+const MAX_PAGE_SIZE = 200;
+const ROLE_JOURNAL_FILE = 'role-menu-mutation.json';
+const DEFAULT_DIRECTORY = {
+    lookupAid: aidLookup,
+    getGroup: groupInfo,
+    listGroups: groupList,
+};
+const mutationTails = new Map();
+export class RoleMenuError extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.code = code;
+        this.data = data;
+        this.name = 'RoleMenuError';
+    }
+}
+export function roleMenuOperation(kind, args, value) {
+    if (kind === 'options')
+        return 'role.policy.read';
+    if (kind === 'query') {
+        return ['targets', 'assignments', 'target'].includes(String(args?.view))
+            ? 'role.relation.read'
+            : 'role.policy.read';
+    }
+    if (kind === 'action')
+        return 'role.policy.write';
+    if (args?.resource !== 'assignment' && args?.resource !== 'admin')
+        return 'role.policy.write';
+    if (args?.resource === 'admin')
+        return 'role.assign';
+    try {
+        return JSON.parse(value ?? '') === null ? 'role.revoke' : 'role.assign';
+    }
+    catch {
+        return 'role.assign';
+    }
+}
+export async function roleMenuOptions(context, args) {
+    assertRequest(context, args);
+    await recoverRoleMutation(context.self);
+    assertRoleDomainReady(context.self);
+    const option = stringArg(args?.option);
+    if (option === 'roles')
+        return roleItems(context.self);
+    if (option === 'operations') {
+        return listOperations().map(operation => ({
+            value: operation.id,
+            label: operationLabel(operation.id),
+            category: operation.category,
+            dangerous: operation.dangerous,
+            defaultScopes: operation.defaultScopes,
+            description: operation.description,
+            sources: operation.sources ?? [],
+        }));
+    }
+    if (option === 'permission-fields') {
+        return permissionFieldsForContext(context).map(field => ({
+            ...field,
+            supportsDefault: true,
+            supportsAllowOverride: field.value !== 'permissionMode',
+            supportsAllowedValues: field.valueType === 'enum',
+            supportsAllowedModels: field.valueType === 'model',
+            runtimeApplied: field.runtimeApplied,
+            ...(relationFieldWriteOperation(field.value)
+                ? { operation: relationFieldWriteOperation(field.value) }
+                : {}),
+        }));
+    }
+    if (option === 'permission-values')
+        return permissionValueOptions(context, args);
+    throw roleError('NOT_SUPPORTED', 'The requested Role option is not supported', context.self, {
+        option: option || null,
+    });
+}
+export async function roleMenuQuery(context, args) {
+    assertRequest(context, args);
+    await recoverRoleMutation(context.self);
+    assertRoleDomainReady(context.self);
+    const view = stringArg(args?.view);
+    const agent = readAgent(context.self);
+    const policyRevision = revision(policyDocument(agent));
+    if (view === 'capabilities') {
+        const hasAunDirectory = context.aunAvailable !== false;
+        return {
+            $schema_version: ROLE_MENU_SCHEMA_VERSION,
+            self: context.self,
+            capabilities: {
+                roleList: true, roleRead: true, roleWrite: true, roleCreate: true, roleDelete: true, roleReset: true,
+                defaultRoleRead: true, defaultRoleWrite: true, permissionFields: true, permissionValues: true,
+                operations: true, privateTargetsList: true, joinedGroupsList: hasAunDirectory, assignmentInventory: true,
+                relationSnapshot: hasAunDirectory, privateRoleAssign: hasAunDirectory, groupRoleAssign: hasAunDirectory,
+                deleteWithReplacement: true, jsonStringUpdateValue: true,
+            },
+        };
+    }
+    if (view === 'defaults') {
+        return {
+            $schema_version: ROLE_MENU_SCHEMA_VERSION,
+            self: context.self,
+            policyRevision,
+            defaultRoles: effectiveDefaultRoles(context.self),
+        };
+    }
+    if (view === 'role') {
+        const roleId = requiredRoleId(args, context.self);
+        const definition = getRoleDefinition(roleId, context.self);
+        if (!definition)
+            throw roleNotFound(context.self, roleId);
+        return {
+            $schema_version: ROLE_MENU_SCHEMA_VERSION,
+            self: context.self,
+            policyRevision,
+            roleId,
+            meta: roleMeta(context.self, roleId),
+            definition: clone(definition),
+        };
+    }
+    if (view === 'assignments')
+        return assignmentInventory(context, args, policyRevision);
+    if (view === 'target')
+        return targetSnapshot(context, args, policyRevision);
+    if (view === 'targets')
+        return targetList(context, args);
+    throw roleError('NOT_SUPPORTED', 'The requested Role view is not supported', context.self, {
+        view: view || null,
+    });
+}
+export async function roleMenuUpdate(context, args, rawValue) {
+    assertRequest(context, args);
+    const value = parseUpdateValue(rawValue, context.self);
+    return withAgentMutation(context.self, async () => {
+        recoverRoleMutationSync(context.self);
+        assertRoleDomainReady(context.self);
+        const before = mutationAuditSnapshot(context.self, args);
+        const resource = stringArg(args?.resource);
+        let result;
+        if (resource === 'definition') {
+            assertRolePolicyMutationTarget(context, args);
+            result = updateDefinition(context.self, args, value);
+        }
+        else if (resource === 'defaultRoles')
+            result = updateDefaultRoles(context, args, value);
+        else if (resource === 'assignment')
+            result = await updateAssignment(context, args, value);
+        else if (resource === 'admin')
+            result = await updateAdminAssignment(context, args, value);
+        else
+            throw roleError('NOT_SUPPORTED', 'The requested Role resource is not supported', context.self, { resource: resource || null });
+        auditMutation(context, args, before, result, resource === 'defaultRoles' ? 'default-update' : resource === 'assignment' ? 'assignment' : 'update');
+        return result;
+    });
+}
+export async function roleMenuAction(context, action, args) {
+    assertRequest(context, args);
+    return withAgentMutation(context.self, async () => {
+        recoverRoleMutationSync(context.self);
+        assertRoleDomainReady(context.self);
+        const before = mutationAuditSnapshot(context.self, args, action === 'delete');
+        let result;
+        if (action === 'create')
+            result = createRole(context.self, args);
+        else if (action === 'reset') {
+            assertRolePolicyMutationTarget(context, args);
+            result = resetRole(context.self, args);
+        }
+        else if (action === 'delete')
+            result = await deleteRole(context, args);
+        else
+            throw roleError('NOT_SUPPORTED', 'The requested Role action is not supported', context.self, { action });
+        auditMutation(context, args, before, result, action);
+        return result;
+    });
+}
+function mutationAuditSnapshot(self, args, includeRoleRelations = false) {
+    const files = {};
+    const roleId = stringArg(args?.roleId);
+    const filePaths = [agentRolesIndex(self), roleId ? agentRoleConfig(self, roleId) : null].filter(Boolean);
+    for (const file of filePaths)
+        files[file] = readAuditValue(file);
+    if (includeRoleRelations && roleId) {
+        for (const file of walkRelationConfigFiles(agentRelationsDir(self))) {
+            const value = readAuditJson(file);
+            if (isObject(value) && value.role === roleId)
+                files[file] = value;
+        }
+    }
+    const target = args?.target;
+    if (target && typeof target === 'object') {
+        try {
+            const normalized = normalizeTarget(target, self);
+            const relationFile = agentRelationConfig(self, normalized.peerKey);
+            files[relationFile] = readAuditJson(relationFile);
+            return { files, relation: normalized.peerKey };
+        }
+        catch { }
+    }
+    return { files };
+}
+function walkRelationConfigFiles(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(...walkRelationConfigFiles(full));
+        else if (entry.isFile() && entry.name === 'config.json')
+            files.push(full);
+    }
+    return files;
+}
+function readAuditJson(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function readAuditValue(file) {
+    return readAuditJson(file);
+}
+function auditMutation(context, args, before, result, operation) {
+    if (result?.changed === false)
+        return;
+    const afterFiles = {};
+    for (const file of Object.keys(before.files))
+        afterFiles[file] = readAuditValue(file);
+    const changedFiles = Object.keys(before.files)
+        .filter(file => stableStringify(before.files[file]) !== stableStringify(afterFiles[file]));
+    const relationFile = changedFiles.find(file => isPathInside(file, agentRelationsDir(context.self)));
+    const beforeRelation = relationFile ? before.files[relationFile] : undefined;
+    const afterRelation = relationFile ? afterFiles[relationFile] : undefined;
+    const roleId = (stringArg(args?.roleId) || undefined)
+        ?? result?.roleId
+        ?? result?.assignment?.explicitRole
+        ?? result?.assignment?.explicitDefaultRole
+        ?? (isObject(afterRelation) && typeof afterRelation.role === 'string' ? afterRelation.role : undefined)
+        ?? (isObject(beforeRelation) && typeof beforeRelation.role === 'string' ? beforeRelation.role : undefined);
+    const primaryFile = before.relation
+        ? relationFile
+        : roleId
+            ? changedFiles.find(file => path.resolve(file) === path.resolve(agentRoleConfig(context.self, roleId))) ?? changedFiles[0]
+            : changedFiles.find(file => path.resolve(file) === path.resolve(agentRolesIndex(context.self))) ?? changedFiles[0];
+    auditRoleMutation({
+        operation,
+        actor: context.actorAid ?? context.actorRole,
+        selfAid: context.self,
+        roleId,
+        relation: before.relation,
+        oldValue: primaryFile ? before.files[primaryFile] : undefined,
+        newValue: primaryFile ? afterFiles[primaryFile] : undefined,
+        files: changedFiles.map(file => ({ file, before: before.files[file], after: afterFiles[file] })),
+    });
+}
+function isPathInside(file, directory) {
+    const relative = path.relative(path.resolve(directory), path.resolve(file));
+    return relative === '' || (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+export function recoverRoleMutationSync(self) {
+    const journalFile = roleJournalPath(self);
+    const journal = atomicReadJson(journalFile);
+    if (!journal)
+        return;
+    validateJournal(self, journal);
+    if (journal.state === 'prepared') {
+        for (const change of [...journal.changes].reverse())
+            applyFileContent(change.file, change.before);
+    }
+    removeJournalFiles(journalFile);
+    invalidateChanges(journal.changes);
+}
+export function recoverAllRoleMutationsSync() {
+    const agentsDir = resolvePaths().agentsDir;
+    if (!fs.existsSync(agentsDir))
+        return;
+    for (const entry of fs.readdirSync(agentsDir, { withFileTypes: true })) {
+        if (!entry.isDirectory() || !isValidAid(entry.name))
+            continue;
+        if (!fs.existsSync(roleJournalPath(entry.name)))
+            continue;
+        recoverRoleMutationSync(entry.name);
+    }
+}
+async function recoverRoleMutation(self) {
+    return withAgentMutation(self, async () => recoverRoleMutationSync(self));
+}
+function assertRequest(context, args) {
+    const requestedSelf = stringArg(args?.self);
+    if (!requestedSelf || requestedSelf !== context.self) {
+        throw roleError('PERMISSION_DENIED', 'args.self does not match the receiving Agent', context.self, {
+            kind: 'agent_scope_mismatch',
+            requestedSelf: requestedSelf || null,
+            receivingSelf: context.self,
+        });
+    }
+    if (context.actorRole !== 'owner' && context.actorRole !== 'admin') {
+        throw roleError('PERMISSION_DENIED', 'Role management requires Agent owner or admin', context.self, {
+            kind: 'role_permission_denied',
+            actorRole: context.actorRole,
+        });
+    }
+}
+function assertRolePolicyMutationTarget(context, args) {
+    const roleId = requiredRoleId(args, context.self);
+    if (context.actorRole === 'admin' && roleId === 'owner') {
+        throw roleError('PERMISSION_DENIED', 'Agent admin cannot modify the owner role policy', context.self, {
+            kind: 'role_hierarchy_violation',
+            actorRole: context.actorRole,
+            targetRole: roleId,
+        });
+    }
+}
+function assertRoleDomainReady(self) {
+    if (!roleRegistryExists(self)) {
+        throw roleError('CONFLICT', 'Standalone role registry is required before using Role management', self, {
+            kind: 'role_registry_missing',
+            file: path.relative(resolvePaths().root, agentRolesIndex(self)),
+            migration: 'kits/migrations/migrate-role-config-v5.mjs --apply',
+        });
+    }
+    const agent = readAgent(self);
+    if (Object.prototype.hasOwnProperty.call(agent, 'roles')) {
+        throw roleError('CONFLICT', 'Agent contains both legacy roles and the standalone role registry', self, {
+            kind: 'role_registry_ambiguous',
+            migration: 'kits/migrations/migrate-role-config-v5.mjs --apply',
+        });
+    }
+    const invalid = readRoleStore(self).diagnostics.find(issue => issue.code === 'INVALID_ROLE_REGISTRY');
+    if (invalid) {
+        throw roleError('CONFLICT', 'Standalone role registry is invalid', self, {
+            kind: 'role_registry_invalid',
+            file: invalid.file ?? path.relative(resolvePaths().root, agentRolesIndex(self)),
+        });
+    }
+}
+function roleItems(self) {
+    const roles = readRolesConfig(self).roles;
+    const userItems = Object.keys(roles).sort((a, b) => {
+        const ai = BUILTIN_USER_ROLES.indexOf(a);
+        const bi = BUILTIN_USER_ROLES.indexOf(b);
+        if (ai >= 0 || bi >= 0)
+            return (ai < 0 ? 99 : ai) - (bi < 0 ? 99 : bi);
+        return a.localeCompare(b);
+    }).map(roleId => ({
+        value: roleId,
+        label: title(roleId),
+        ...roleMeta(self, roleId),
+    }));
+    const managementItems = MANAGEMENT_ROLES.map(roleId => ({
+        value: roleId,
+        label: title(roleId),
+        ...roleMeta(self, roleId),
+    }));
+    return [...userItems, ...managementItems];
+}
+async function permissionValueOptions(context, args) {
+    const field = stringArg(args?.field);
+    const descriptor = permissionFieldsForContext(context).find(item => item.value === field);
+    if (!descriptor || !descriptor.hasOptions) {
+        throw roleError('NOT_SUPPORTED', 'The requested permission field does not provide option values', context.self, {
+            field: field || null,
+            hasOptions: descriptor?.hasOptions ?? false,
+        });
+    }
+    const staticOptions = rolePermissionFieldOptions(descriptor);
+    if (staticOptions.length)
+        return clone(staticOptions);
+    const patterns = rolePermissionFieldPatterns(descriptor);
+    const baseagent = field.split('.')[1];
+    let models = [];
+    try {
+        models = context.listModels ? await context.listModels(baseagent) : [];
+    }
+    catch { }
+    return [
+        ...patterns,
+        ...Array.from(new Set(models.filter(value => typeof value === 'string' && value.trim()))).map(value => ({
+            value,
+            label: value,
+            kind: 'model',
+            isAlias: false,
+        })),
+    ];
+}
+function permissionFieldsForContext(context) {
+    const fields = rolePermissionFields();
+    if (!context.availableBaseagents?.length)
+        return fields;
+    const available = new Set(context.availableBaseagents);
+    return fields.filter(field => {
+        const match = /^baseagents\.([^.]+)\./.exec(field.value);
+        return !match || available.has(match[1]);
+    });
+}
+function updateDefinition(self, args, value) {
+    if (!isObject(value))
+        throw invalidJsonType(self, 'definition', 'object');
+    const roleId = requiredRoleId(args, self);
+    const current = getRoleDefinition(roleId, self);
+    if (!current)
+        throw roleNotFound(self, roleId);
+    assertPolicyRevision(self, args);
+    validateRemove(args?.remove, self, roleId);
+    const nextDefinition = mergeDefinition(current, value, args?.remove, self, roleId);
+    const errors = validateRoleConfig(nextDefinition);
+    if (errors.length)
+        throw validationFailed(self, roleId, errors);
+    const currentDefinition = readRoleDefinition(self, roleId);
+    const changed = stableStringify(currentDefinition) !== stableStringify(nextDefinition);
+    if (changed)
+        writeRoleDefinition(self, roleId, nextDefinition);
+    const nextAgent = readAgent(self);
+    return {
+        $schema_version: ROLE_MENU_SCHEMA_VERSION,
+        self,
+        resource: 'definition',
+        roleId,
+        changed,
+        policyRevision: revision(policyDocument(nextAgent)),
+        definition: clone(getRoleDefinition(roleId, self) ?? nextDefinition),
+        ...(args?.remove ? { removed: normalizeRemove(args.remove) } : {}),
+    };
+}
+function updateDefaultRoles(context, args, value) {
+    const self = context.self;
+    if (!isObject(value))
+        throw invalidJsonType(self, 'defaultRoles', 'object');
+    assertOnlyKeys(value, ['private', 'group'], 'defaultRoles', self);
+    if (!Object.prototype.hasOwnProperty.call(value, 'private') || !Object.prototype.hasOwnProperty.call(value, 'group')) {
+        throw validationFailed(self, undefined, [{ field: 'defaultRoles', code: 'MISSING_FIELD', message: 'private and group are required' }]);
+    }
+    const nextDefaults = {
+        private: validateAssignableRole(value.private, self, 'defaultRoles.private'),
+        group: validateAssignableRole(value.group, self, 'defaultRoles.group'),
+    };
+    assertPolicyRevision(self, args);
+    const registry = readRoleRegistry(self);
+    const changesAdminDefault = ['private', 'group'].some(scene => registry.defaultRoles[scene] !== nextDefaults[scene]
+        && (registry.defaultRoles[scene] === 'admin' || nextDefaults[scene] === 'admin'));
+    if (context.actorRole !== 'owner' && changesAdminDefault) {
+        throw roleError('NOT_ALLOWED', 'Only an owner can set or replace an admin default role', self, {
+            kind: 'admin_owner_only',
+        });
+    }
+    const nextRegistry = { ...registry, defaultRoles: nextDefaults };
+    const changed = stableStringify(registry) !== stableStringify(nextRegistry);
+    if (changed)
+        writeRoleRegistry(self, nextRegistry);
+    const nextAgent = readAgent(self);
+    return {
+        $schema_version: ROLE_MENU_SCHEMA_VERSION,
+        self,
+        resource: 'defaultRoles',
+        changed,
+        policyRevision: revision(policyDocument(nextAgent)),
+        defaultRoles: nextDefaults,
+    };
+}
+async function updateAssignment(context, args, value) {
+    const self = context.self;
+    if (value !== null && typeof value !== 'string')
+        throw invalidJsonType(self, 'assignment', 'string or null');
+    assertPolicyRevision(self, args);
+    let target = normalizeTarget(args?.target, self);
+    const roleId = value === null ? null : validateAssignableRole(value, self, 'assignment');
+    if (roleId !== null)
+        target = await validateTargetExists(context, target);
+    const targetAid = target.kind === 'private' ? target.peerAid : null;
+    if (targetAid && isStaticAgentOwner(self, targetAid)) {
+        throw roleError('NOT_ALLOWED', 'Owner assignments cannot be changed through relations', self, {
+            kind: 'owner_protected',
+            targetAid,
+        });
+    }
+    const current = readRelation(target.peerKey, self);
+    if (context.actorRole !== 'owner' && (roleId === 'admin' || current?.config.role === 'admin')) {
+        throw roleError('NOT_ALLOWED', 'Only an owner can grant or revoke admin', self, {
+            kind: 'admin_owner_only',
+            target: target.peerKey,
+        });
+    }
+    assertRelationRevision(self, args, current?.revision ?? null, target.peerKey);
+    if (!current && roleId === null)
+        return assignmentResponse(self, target, null, false, null);
+    const relation = clone(current?.config ?? { $schema_version: currentVersion('relation-config') });
+    relation.targetKind = target.kind;
+    if (roleId === null)
+        delete relation.role;
+    else
+        relation.role = roleId;
+    const normalized = normalizeRelationForScene(relation, target.kind);
+    const changed = stableStringify(current?.config ?? null) !== stableStringify(normalized);
+    if (changed)
+        write(ConfigTarget.Relation, normalized, { self, peerKey: target.peerKey });
+    const nextRevision = changed ? revision(normalized) : current?.revision ?? null;
+    return assignmentResponse(self, target, normalized, changed, nextRevision);
+}
+async function updateAdminAssignment(context, args, value) {
+    const self = context.self;
+    if (context.actorRole !== 'owner') {
+        throw roleError('NOT_ALLOWED', 'Only an owner can grant or revoke admin', self, { kind: 'admin_owner_only' });
+    }
+    let target = normalizeTarget(args?.target, self);
+    if (target.kind !== 'private')
+        throw invalidTargetValue(self, 'target.kind');
+    if (isStaticAgentOwner(self, target.peerAid)) {
+        throw roleError('NOT_ALLOWED', 'Owner assignments cannot be changed through contact admin', self, { kind: 'owner_protected' });
+    }
+    const enabled = value === true || value === 'grant'
+        ? true
+        : value === false || value === null || value === 'revoke'
+            ? false
+            : undefined;
+    if (enabled === undefined)
+        throw invalidJsonType(self, 'admin', 'boolean, grant, revoke, or null');
+    if (enabled)
+        target = await validateTargetExists(context, target);
+    const current = readRelation(target.peerKey, self);
+    assertRelationRevision(self, args, current?.revision ?? null, target.peerKey);
+    if (!current && !enabled) {
+        return {
+            $schema_version: ROLE_MENU_SCHEMA_VERSION, self, resource: 'admin', target,
+            changed: false, relationRevision: null, admin: false,
+        };
+    }
+    const relation = clone(current?.config ?? { $schema_version: currentVersion('relation-config') });
+    relation.targetKind = 'private';
+    if (enabled)
+        relation.role = 'admin';
+    else if (relation.role === 'admin')
+        delete relation.role;
+    const normalized = normalizeRelationForScene(relation, 'private');
+    const changed = stableStringify(current?.config ?? null) !== stableStringify(normalized);
+    if (changed)
+        write(ConfigTarget.Relation, normalized, { self, peerKey: target.peerKey });
+    const nextRevision = changed ? revision(normalized) : current?.revision ?? null;
+    return {
+        $schema_version: ROLE_MENU_SCHEMA_VERSION, self, resource: 'admin', target,
+        changed, relationRevision: nextRevision, admin: normalized.role === 'admin',
+    };
+}
+function createRole(self, args) {
+    const roleId = requiredRoleId(args, self);
+    if (!isValidUserRoleName(roleId)) {
+        throw validationFailed(self, roleId, [{ field: 'roleId', code: 'INVALID_VALUE', message: 'roleId must match ^[a-z0-9_-]+$ and cannot be owner/admin' }]);
+    }
+    if (getRoleDefinition(roleId, self)) {
+        throw roleError('CONFLICT', 'Role already exists', self, { kind: 'role_exists', roleId });
+    }
+    assertPolicyRevision(self, args);
+    if (!isObject(args?.definition))
+        throw validationFailed(self, roleId, [{ field: 'definition', code: 'INVALID_TYPE', message: 'definition must be an object' }]);
+    const definition = clone(args.definition);
+    if (definition.rank !== undefined && definition.rank !== expectedRoleRank(roleId)) {
+        throw validationFailed(self, roleId, [{ field: 'definition.rank', code: 'INVALID_VALUE', message: 'custom role rank is fixed at 500' }]);
+    }
+    definition.rank = expectedRoleRank(roleId);
+    const errors = validateRoleConfig(definition);
+    if (errors.length)
+        throw validationFailed(self, roleId, errors);
+    registerRole(self, roleId, definition);
+    const nextAgent = readAgent(self);
+    return {
+        $schema_version: ROLE_MENU_SCHEMA_VERSION,
+        self,
+        action: 'create',
+        changed: true,
+        roleId,
+        policyRevision: revision(policyDocument(nextAgent)),
+        meta: roleMeta(self, roleId),
+        definition,
+    };
+}
+function resetRole(self, args) {
+    const roleId = requiredRoleId(args, self);
+    if (!BUILTIN_USER_ROLES.includes(roleId)) {
+        if (isManagementRole(roleId))
+            return resetManagementRole(self, roleId, args);
+        if (!getRoleDefinition(roleId, self))
+            throw roleNotFound(self, roleId);
+        throw roleError('NOT_ALLOWED', 'Only overridden built-in user roles can be reset', self, {
+            kind: 'protected_role', roleId, allowedAction: null,
+        });
+    }
+    assertPolicyRevision(self, args);
+    const file = agentRoleConfig(self, roleId);
+    const changed = fs.existsSync(file);
+    if (changed) {
+        fs.rmSync(file, { force: true });
+        clearRoleStoreCache(self);
+    }
+    const nextAgent = readAgent(self);
+    return {
+        $schema_version: ROLE_MENU_SCHEMA_VERSION, self, action: 'reset', changed, roleId,
+        policyRevision: revision(policyDocument(nextAgent)),
+        meta: roleMeta(self, roleId),
+    };
+}
+function resetManagementRole(self, roleId, args) {
+    assertPolicyRevision(self, args);
+    const file = agentRoleConfig(self, roleId);
+    const changed = fs.existsSync(file);
+    if (changed) {
+        fs.rmSync(file, { force: true });
+        clearRoleStoreCache(self);
+    }
+    const nextAgent = readAgent(self);
+    return {
+        $schema_version: ROLE_MENU_SCHEMA_VERSION,
+        self,
+        action: 'reset',
+        changed,
+        roleId,
+        policyRevision: revision(policyDocument(nextAgent)),
+        meta: roleMeta(self, roleId),
+    };
+}
+async function deleteRole(context, args) {
+    const self = context.self;
+    const roleId = requiredRoleId(args, self);
+    if ([...MANAGEMENT_ROLES, ...BUILTIN_USER_ROLES].includes(roleId)) {
+        throw protectedRole(self, roleId, BUILTIN_USER_ROLES.includes(roleId) ? 'reset' : null);
+    }
+    const agent = readAgent(self);
+    const domainDefinitions = readRoleStore(self).definitions;
+    if (!Object.prototype.hasOwnProperty.call(domainDefinitions, roleId)) {
+        throw roleNotFound(self, roleId);
+    }
+    assertPolicyRevision(self, args, agent);
+    const hasReplacement = Object.prototype.hasOwnProperty.call(args ?? {}, 'replacementRoleId');
+    const replacement = hasReplacement
+        ? validateAssignableRole(args?.replacementRoleId, self, 'replacementRoleId')
+        : undefined;
+    if (replacement === 'admin' && context.actorRole !== 'owner') {
+        throw roleError('NOT_ALLOWED', 'Only an owner can replace role assignments with admin', self, {
+            kind: 'admin_owner_only',
+        });
+    }
+    if (replacement === roleId) {
+        throw validationFailed(self, roleId, [{ field: 'replacementRoleId', code: 'INVALID_VALUE', message: 'replacementRoleId must differ from roleId' }]);
+    }
+    const relations = listRelations(self, await knownRelationTargets(context));
+    const ambiguous = relations.filter(relation => relation.targetKind === 'unknown' && relationReferencesRole(relation.config, roleId));
+    if (ambiguous.length) {
+        throw roleError('CONFLICT', 'Role references relations whose target type is unknown', self, {
+            kind: 'ambiguous_relation_target', roleId, peerKeys: ambiguous.map(relation => relation.peerKey),
+        });
+    }
+    const usage = countRoleUsage(self, relations, roleId);
+    const hasUsage = usage.defaultScenes.length > 0 || usage.privateRelations > 0 || usage.groupRelations > 0;
+    if (hasUsage && !hasReplacement) {
+        throw roleError('CONFLICT', 'Role is still referenced', self, { kind: 'role_in_use', roleId, ...usage });
+    }
+    const registry = readRoleRegistry(self);
+    const nextRegistry = clone(registry);
+    nextRegistry.roles = nextRegistry.roles.filter(item => item !== roleId);
+    for (const scene of ['private', 'group']) {
+        if (nextRegistry.defaultRoles[scene] === roleId)
+            nextRegistry.defaultRoles[scene] = replacement ?? null;
+    }
+    const changes = [
+        {
+            file: agentRolesIndex(self),
+            before: readFileText(agentRolesIndex(self)),
+            after: jsonText(nextRegistry),
+        },
+        {
+            file: agentRoleConfig(self, roleId),
+            before: readFileText(agentRoleConfig(self, roleId)),
+            after: null,
+        },
+    ];
+    appendRoleRelationChanges(self, relations, roleId, replacement, changes);
+    validateRoleDomainTransactionChanges(self, nextRegistry, changes);
+    commitJournal(self, changes);
+    return {
+        $schema_version: ROLE_MENU_SCHEMA_VERSION, self, action: 'delete', changed: true, roleId,
+        replacementRoleId: hasReplacement ? replacement : null,
+        policyRevision: revision(policyDocument(readAgent(self))),
+        migrated: usage,
+    };
+}
+async function assignmentInventory(context, args, policyRevision) {
+    const self = context.self;
+    const roleFilter = args?.roleId === undefined ? undefined : stringArg(args.roleId);
+    if (args?.roleId !== undefined && !roleFilter)
+        throw validationFailed(self, undefined, [{ field: 'roleId', code: 'INVALID_VALUE', message: 'roleId must be a non-empty string' }]);
+    const items = [];
+    if (args?.includeDefaults !== false) {
+        const defaults = effectiveDefaultRoles(self);
+        for (const scene of ['private', 'group']) {
+            const roleId = defaults[scene];
+            if (roleId && (!roleFilter || roleFilter === roleId)) {
+                items.push({ target: { kind: 'default', scene }, roleId, relationRevision: null });
+            }
+        }
+    }
+    let complete = true;
+    for (const relation of listRelations(self, await knownRelationTargets(context))) {
+        const assigned = relation.config.role;
+        if (typeof assigned === 'string' && (!roleFilter || roleFilter === assigned)) {
+            if (relation.targetKind === 'unknown')
+                complete = false;
+            items.push({
+                target: relation.targetKind === 'group'
+                    ? { kind: 'group', groupId: relation.channelId, peerKey: relation.peerKey }
+                    : relation.targetKind === 'private'
+                        ? { kind: 'private', peerAid: relation.channelId, peerKey: relation.peerKey }
+                        : { kind: 'unknown', channelId: relation.channelId, peerKey: relation.peerKey },
+                roleId: assigned,
+                relationRevision: relation.revision,
+            });
+        }
+    }
+    items.sort((a, b) => assignmentKey(a).localeCompare(assignmentKey(b)));
+    const page = paginate(items, args, self, assignmentKey);
+    return {
+        $schema_version: ROLE_MENU_SCHEMA_VERSION,
+        self,
+        policyRevision,
+        items: page.items,
+        nextCursor: page.nextCursor,
+        dataSource: {
+            kind: 'agent-and-relation-config', authoritative: complete, complete, observedAt: Date.now(),
+            ...(complete ? {} : { limitation: 'Some legacy relations have no authoritative private/group target kind' }),
+        },
+    };
+}
+async function targetSnapshot(context, args, policyRevision) {
+    const self = context.self;
+    const target = await validateTargetExists(context, normalizeTarget(args?.target, self), { allowAuthenticatedPrivateActor: true });
+    const relation = readRelation(target.peerKey, self);
+    return {
+        $schema_version: ROLE_MENU_SCHEMA_VERSION,
+        self,
+        policyRevision,
+        target,
+        relationRevision: relation?.revision ?? null,
+        ...targetRoleView(self, target, relation?.config ?? null),
+        relationConfig: relationConfigView(context, target, relation?.config ?? null),
+    };
+}
+async function targetList(context, args) {
+    const self = context.self;
+    const targetType = stringArg(args?.targetType);
+    if (targetType === 'group') {
+        assertAunDirectory(context);
+        const result = await listJoinedGroups(context);
+        const items = result.items.map(group => {
+            const peerKey = formatPeerKey('aun', group.group_id);
+            const relation = readRelation(peerKey, self);
+            const view = targetRoleView(self, { kind: 'group', groupId: group.group_id, peerKey }, relation?.config ?? null);
+            return {
+                kind: 'group', groupId: group.group_id, peerKey, displayName: group.name,
+                status: group.status ?? 'active', memberCount: group.member_count ?? null,
+                relationRevision: relation?.revision ?? null,
+                explicitDefaultRole: view.assignment.explicitDefaultRole,
+                baselineRole: view.baselineRole.roleId,
+                baselineRoleSource: view.baselineRole.source,
+            };
+        });
+        items.sort((left, right) => left.peerKey.localeCompare(right.peerKey));
+        const page = paginate(items, args, self, item => item.peerKey);
+        const complete = result.items.length >= result.total;
+        return {
+            $schema_version: ROLE_MENU_SCHEMA_VERSION, self, targetType, items: page.items, nextCursor: page.nextCursor,
+            total: result.total,
+            dataSource: {
+                kind: 'aun-live', authoritative: true, complete, observedAt: Date.now(),
+                limitation: complete ? null : `AUN returned ${result.items.length} of ${result.total} joined groups without a continuation cursor`,
+            },
+        };
+    }
+    if (targetType !== 'private') {
+        throw validationFailed(self, undefined, [{ field: 'targetType', code: 'INVALID_VALUE', message: 'targetType must be private or group' }]);
+    }
+    const candidates = privateHistoryTargets(self);
+    const page = paginate(candidates, args, self, item => item.peerKey);
+    return {
+        $schema_version: ROLE_MENU_SCHEMA_VERSION, self, targetType, items: page.items, nextCursor: page.nextCursor,
+        dataSource: {
+            kind: 'local-history', authoritative: false, complete: false, observedAt: Date.now(),
+            limitation: 'History removed from local storage cannot be recovered',
+        },
+    };
+}
+function roleDirectory(context) {
+    return context.directory ?? DEFAULT_DIRECTORY;
+}
+function assertAunDirectory(context) {
+    if (context.aunAvailable === false) {
+        throw roleError('NOT_SUPPORTED', 'Role target validation requires an enabled AUN channel', context.self, {
+            kind: 'aun_directory_unavailable',
+        });
+    }
+}
+async function listJoinedGroups(context) {
+    assertAunDirectory(context);
+    const directory = roleDirectory(context);
+    const items = new Map();
+    let cursor;
+    let total = 0;
+    let attempts = 0;
+    while (attempts < 1000) {
+        attempts += 1;
+        const result = await directory.listGroups({ from: context.self, size: MAX_PAGE_SIZE, ...(cursor ? { cursor } : {}) });
+        if (!result.ok) {
+            throw roleError('TEMPORARILY_UNAVAILABLE', result.error || 'Unable to list joined groups', context.self, {
+                kind: 'target_source_unavailable', targetType: 'group',
+            });
+        }
+        total = Math.max(total, result.total);
+        const previousSize = items.size;
+        for (const group of result.items)
+            items.set(group.group_id, group);
+        if (items.size >= total)
+            break;
+        if (items.size === previousSize)
+            break;
+        if (result.nextCursor && result.nextCursor !== cursor) {
+            cursor = result.nextCursor;
+            continue;
+        }
+        break;
+    }
+    return { items: [...items.values()], total };
+}
+async function knownRelationTargets(context) {
+    const known = localKnownRelationTargets(context.self);
+    if (context.aunAvailable === false)
+        return known;
+    try {
+        const groups = await listJoinedGroups(context);
+        for (const group of groups.items)
+            known.groups.add(group.group_id);
+    }
+    catch {
+        return known;
+    }
+    return known;
+}
+function localKnownRelationTargets(self) {
+    const known = { groups: new Set(), privates: new Set() };
+    for (const chat of scanChatDirs(resolvePaths().sessionsDir)) {
+        if (chat.channelType !== 'aun' || chat.selfAID !== self)
+            continue;
+        const active = readJsonFile(path.join(chat.dirPath, 'active.json'));
+        if (chatIsGroup(chat))
+            known.groups.add(String(active?.metadata?.groupId || chat.channelId));
+        else
+            known.privates.add(String(active?.metadata?.peerId || chat.channelId));
+    }
+    return known;
+}
+async function validateTargetExists(context, target, options = {}) {
+    assertAunDirectory(context);
+    if (options.allowAuthenticatedPrivateActor === true
+        && target.kind === 'private'
+        && context.chatType === 'private'
+        && context.actorAid === target.peerAid) {
+        return target;
+    }
+    const directory = roleDirectory(context);
+    if (target.kind === 'private') {
+        const lookup = await directory.lookupAid(target.peerAid);
+        if (!lookup.exists) {
+            throw roleError('NOT_FOUND', 'Private Role target was not found', context.self, {
+                kind: 'target_not_found', target,
+            });
+        }
+        const declaredType = lookup.content?.match(/^type:\s*["']?([^"'\r\n]+)["']?\s*$/mi)?.[1]?.trim().toLowerCase();
+        const groupProbe = await directory.getGroup({ from: context.self, groupId: target.peerAid, required: ['member'] });
+        if (declaredType === 'group' || (groupProbe.ok && groupProbe.found)) {
+            throw roleError('INVALID_ARGUMENT', 'Private Role target resolves to a group', context.self, {
+                kind: 'target_kind_mismatch', target,
+            });
+        }
+        return target;
+    }
+    const info = await directory.getGroup({ from: context.self, groupId: target.groupId, required: ['member'] });
+    if (!info.ok) {
+        throw roleError('NOT_FOUND', info.error || 'Group Role target was not found', context.self, {
+            kind: 'target_not_found', target,
+        });
+    }
+    const group = info.group;
+    if (!info.found || !group || !group.my_role || group.status === 'dissolved') {
+        throw roleError('NOT_FOUND', 'Group Role target is not joined by this Agent', context.self, {
+            kind: 'target_not_joined', target,
+        });
+    }
+    const canonicalGroupId = group.group_aid || group.group_id || target.groupId;
+    return canonicalGroupId === target.groupId
+        ? target
+        : { ...target, groupId: canonicalGroupId, peerKey: formatPeerKey('aun', canonicalGroupId) };
+}
+function privateHistoryTargets(self) {
+    const aggregate = new Map();
+    for (const chat of scanChatDirs(resolvePaths().sessionsDir)) {
+        if (chat.channelType !== 'aun' || chat.selfAID !== self || chatIsGroup(chat))
+            continue;
+        const sessions = [];
+        const active = readJsonFile(path.join(chat.dirPath, 'active.json'));
+        if (active)
+            sessions.push(active);
+        for (const metaFile of scanMetaFiles(chat.dirPath)) {
+            const session = readLastJsonlLine(path.join(chat.dirPath, metaFile));
+            if (session)
+                sessions.push(session);
+        }
+        if (!sessions.length)
+            continue;
+        const times = sessions.map(session => Number(session.updatedAt || session.createdAt || 0)).filter(Number.isFinite);
+        const created = sessions.map(session => Number(session.createdAt || 0)).filter(Number.isFinite);
+        aggregate.set(chat.channelId, {
+            first: created.length ? Math.min(...created) : 0,
+            last: times.length ? Math.max(...times) : 0,
+            count: new Set(sessions.map(session => session.id).filter(Boolean)).size,
+            displayName: sessions.find(session => session.metadata?.peerName)?.metadata?.peerName,
+            peerType: sessions.find(session => session.metadata?.peerType)?.metadata?.peerType,
+        });
+    }
+    return [...aggregate.entries()].map(([peerAid, history]) => {
+        const peerKey = formatPeerKey('aun', peerAid);
+        const relation = readRelation(peerKey, self);
+        const view = targetRoleView(self, { kind: 'private', peerAid, peerKey }, relation?.config ?? null);
+        return {
+            kind: 'private', peerAid, peerKey, displayName: history.displayName ?? peerAid,
+            peerType: history.peerType ?? 'unknown', lastSessionAt: history.last, firstSessionAt: history.first,
+            sessionCount: history.count, relationRevision: relation?.revision ?? null,
+            explicitRole: view.assignment.explicitRole,
+            effectiveRole: view.effectiveRole.roleId,
+            effectiveRoleSource: view.effectiveRole.source,
+        };
+    }).sort((a, b) => a.peerKey.localeCompare(b.peerKey));
+}
+function chatIsGroup(chat) {
+    if (isExplicitGroupId(chat.channelId))
+        return true;
+    const active = readJsonFile(path.join(chat.dirPath, 'active.json'));
+    if (active?.chatType === 'group' || active?.metadata?.groupId)
+        return true;
+    return scanMetaFiles(chat.dirPath).some(metaFile => {
+        const session = readLastJsonlLine(path.join(chat.dirPath, metaFile));
+        return session?.chatType === 'group' || !!session?.metadata?.groupId;
+    });
+}
+function assignmentResponse(self, target, config, changed, relationRevision) {
+    return {
+        $schema_version: ROLE_MENU_SCHEMA_VERSION,
+        self,
+        resource: 'assignment',
+        target,
+        changed,
+        relationRevision,
+        ...targetRoleView(self, target, config),
+    };
+}
+function normalizeTarget(value, self) {
+    if (!isObject(value))
+        throw validationFailed(self, undefined, [{ field: 'target', code: 'INVALID_TYPE', message: 'target must be an object' }]);
+    const kind = stringArg(value.kind);
+    if (kind === 'private') {
+        const peerAid = stringArg(value.peerAid);
+        if (!peerAid)
+            throw invalidTarget(self, 'target.peerAid');
+        if (!isValidAid(peerAid) || isExplicitGroupId(peerAid))
+            throw invalidTargetValue(self, 'target.peerAid');
+        return { kind, peerAid, peerKey: formatPeerKey('aun', peerAid) };
+    }
+    if (kind === 'group') {
+        const groupId = stringArg(value.groupId);
+        if (!groupId)
+            throw invalidTarget(self, 'target.groupId');
+        if (!isValidAid(groupId) && !isExplicitGroupId(groupId))
+            throw invalidTargetValue(self, 'target.groupId');
+        return { kind, groupId, peerKey: formatPeerKey('aun', groupId) };
+    }
+    throw validationFailed(self, undefined, [{ field: 'target.kind', code: 'INVALID_VALUE', message: 'target.kind must be private or group' }]);
+}
+function targetRoleView(self, target, relation = null) {
+    if (target.kind === 'private') {
+        const explicitRole = relation?.role ?? null;
+        const detail = resolvePeerRoleDetail({
+            selfAid: self, channelKey: `aun#${self}#main`, channelType: 'aun', chatType: 'private', actorId: target.peerAid, conversationId: target.peerAid,
+        });
+        return {
+            assignment: { explicitRole },
+            effectiveRole: roleResult(detail.effectiveRole, detail.source, self),
+        };
+    }
+    const explicitDefaultRole = relation?.role ?? null;
+    const roleId = validRoleOrNull(explicitDefaultRole, self) ?? effectiveDefaultRoles(self).group;
+    return {
+        assignment: { explicitDefaultRole },
+        baselineRole: roleResult(roleId, explicitDefaultRole ? 'relation' : 'agent-default', self),
+    };
+}
+function relationConfigView(context, target, config) {
+    const self = context.self;
+    const permissionFields = permissionFieldsForContext(context);
+    const explicit = {};
+    for (const field of permissionFields) {
+        const value = getNested(config, field.value);
+        if (value !== undefined)
+            explicit[field.value] = value;
+    }
+    const roleView = targetRoleView(self, target, config);
+    const roleId = roleView.effectiveRole?.roleId ?? roleView.baselineRole?.roleId ?? null;
+    const roleDefinition = roleId ? getRoleDefinition(roleId, self) : null;
+    const effective = resolveEffectiveWithSources({ self, peerKey: target.peerKey }, { cache: false, fields: permissionFields.filter(field => field.value !== 'permissionMode').map(field => field.value) });
+    return {
+        explicit,
+        fields: permissionFields.map(field => {
+            const explicitValue = getNested(config, field.value);
+            const resolved = effective[field.value];
+            const isPermissionMode = field.value === 'permissionMode';
+            const operation = relationFieldWriteOperation(field.value);
+            const fieldPermission = roleDefinition
+                ? resolveRoleFieldPermission(roleDefinition.permissions || {}, field.value)
+                : undefined;
+            const operationCapability = roleId && operation
+                ? evaluateRoleOperationCapability({
+                    role: roleId,
+                    selfAid: self,
+                    operation,
+                    scope: 'relation',
+                    chatType: target.kind === 'group' ? 'group' : 'private',
+                })
+                : null;
+            const appliesToTarget = field.value === 'chatmode.private'
+                ? target.kind === 'private'
+                : field.value === 'chatmode.group' || field.value === 'mentionMode'
+                    ? target.kind === 'group'
+                    : true;
+            const writable = appliesToTarget
+                && !isPermissionMode
+                && !!operationCapability?.allow
+                && fieldPermission?.allowOverride !== false;
+            const writeReason = writable
+                ? undefined
+                : !appliesToTarget
+                    ? `${field.value} does not apply to this relation type`
+                    : isPermissionMode
+                        ? 'permissionMode is managed by the role policy'
+                        : !roleId
+                            ? 'No effective role is assigned'
+                            : fieldPermission?.allowOverride === false
+                                ? `Role ${roleId} does not allow relation overrides for ${field.value}`
+                                : operationCapability?.reason ?? `Role ${roleId} cannot write ${field.value}`;
+            const modelMatch = /^baseagents\.([^.]+)\.model$/.exec(field.value);
+            const permissionDecision = isPermissionMode
+                ? resolveRuntimePermissionMode({ selfAid: self, role: roleId })
+                : null;
+            const modelDecision = modelMatch
+                ? constrainResolvedModelForRole({
+                    selfAid: self,
+                    role: roleId ?? 'none',
+                    baseagent: modelMatch[1],
+                    model: typeof resolved?.value === 'string' ? resolved.value : undefined,
+                    resolveModelId: context.resolveModelId
+                        ? model => context.resolveModelId(modelMatch[1], model)
+                        : undefined,
+                })
+                : null;
+            const stringDecision = !isPermissionMode && !modelMatch
+                ? resolveRuntimeStringField({
+                    selfAid: self,
+                    role: roleId,
+                    field: field.value,
+                    configuredValue: resolved?.value,
+                })
+                : null;
+            return {
+                field: field.value,
+                hasExplicitValue: explicitValue !== undefined,
+                ...(explicitValue !== undefined ? { explicitValue } : {}),
+                effectiveValue: permissionDecision?.effectiveValue
+                    ?? modelDecision?.model
+                    ?? stringDecision?.effectiveValue
+                    ?? resolved?.value
+                    ?? null,
+                effectiveContext: target.kind === 'private' ? 'private-peer' : 'group-baseline',
+                source: permissionDecision
+                    ? (permissionDecision.decidedBy === 'role' ? 'role' : 'builtin')
+                    : modelDecision?.constrained
+                        ? 'role'
+                        : stringDecision?.decidedBy === 'role'
+                            ? 'role'
+                            : resolved?.source ?? null,
+                ...(modelDecision ? {
+                    configuredValue: resolved?.value ?? null,
+                    configuredSource: resolved?.source ?? null,
+                    constrainedByRole: modelDecision.constrained,
+                } : {}),
+                ...(stringDecision ? {
+                    configuredValue: resolved?.value ?? null,
+                    configuredSource: resolved?.source ?? null,
+                    constrainedByRole: stringDecision.constrained,
+                } : {}),
+                readable: true,
+                ...(operation ? { operation } : {}),
+                writable,
+                ...(writeReason ? { writeReason } : {}),
+            };
+        }),
+    };
+}
+function roleResult(roleId, source, self) {
+    return { roleId, source: roleId ? source : 'none', allowAccess: roleId ? checkRoleAccess(roleId, self) : false };
+}
+function readAgent(self) {
+    const agent = read(ConfigTarget.Agent, { self }, { cache: false });
+    if (!agent)
+        throw roleError('NOT_FOUND', 'Agent was not found', self, { kind: 'agent_not_found' });
+    return agent;
+}
+function effectiveDefaultRoles(self) {
+    const defaults = readRolesConfig(self).defaultRoles ?? {};
+    return { private: defaults.private ?? null, group: defaults.group ?? null };
+}
+function policyDocument(agent) {
+    const store = readRoleStore(agent.aid);
+    return {
+        $schema_version: ROLE_MENU_SCHEMA_VERSION,
+        registry: store.registry,
+        definitions: store.definitions,
+    };
+}
+function roleMeta(self, roleId) {
+    if (isManagementRole(roleId)) {
+        const overridden = fs.existsSync(agentRoleConfig(self, roleId));
+        return {
+            origin: 'builtin',
+            overridden,
+            kind: 'management',
+            assignable: roleId === 'admin',
+            editable: true,
+            deletable: false,
+            resettable: true,
+        };
+    }
+    const builtin = Object.prototype.hasOwnProperty.call(getBuiltinRolesConfig().roles, roleId);
+    const overridden = fs.existsSync(agentRoleConfig(self, roleId));
+    return {
+        origin: builtin ? 'builtin' : 'custom',
+        overridden,
+        kind: 'user',
+        assignable: true,
+        editable: true,
+        deletable: !builtin,
+        resettable: builtin,
+    };
+}
+function assertPolicyRevision(self, args, providedAgent) {
+    if (!Object.prototype.hasOwnProperty.call(args ?? {}, 'expectedPolicyRevision')) {
+        throw validationFailed(self, undefined, [{ field: 'expectedPolicyRevision', code: 'MISSING_FIELD', message: 'expectedPolicyRevision is required' }]);
+    }
+    const current = revision(policyDocument(providedAgent ?? readAgent(self)));
+    if (args?.expectedPolicyRevision !== current) {
+        throw revisionConflict(self, 'policy', args?.expectedPolicyRevision, current);
+    }
+}
+function assertRelationRevision(self, args, current, peerKey) {
+    if (!Object.prototype.hasOwnProperty.call(args ?? {}, 'expectedRelationRevision')) {
+        throw validationFailed(self, undefined, [{ field: 'expectedRelationRevision', code: 'MISSING_FIELD', message: 'expectedRelationRevision is required' }]);
+    }
+    if (args?.expectedRelationRevision !== current) {
+        throw revisionConflict(self, 'relation', args?.expectedRelationRevision, current, { peerKey });
+    }
+}
+function parseUpdateValue(rawValue, self) {
+    if (Buffer.byteLength(rawValue, 'utf8') > ROLE_UPDATE_MAX_BYTES) {
+        throw roleError('INVALID_ARGUMENT', 'Role update value is too large', self, { kind: 'invalid_json_value', maxBytes: ROLE_UPDATE_MAX_BYTES });
+    }
+    try {
+        return JSON.parse(rawValue);
+    }
+    catch {
+        throw roleError('INVALID_ARGUMENT', 'Role update value must contain valid JSON text', self, { kind: 'invalid_json_value' });
+    }
+}
+function validateAssignableRole(value, self, field) {
+    if (value === null)
+        return null;
+    if (typeof value !== 'string' || !value.trim() || value === 'owner' || !getRoleDefinition(value, self)) {
+        throw validationFailed(self, undefined, [{ field, code: 'INVALID_VALUE', message: 'value must be null or an existing assignable user role' }]);
+    }
+    return value;
+}
+function mergeDefinition(current, patch, remove, self, roleId) {
+    assertOnlyKeys(patch, ['description', 'allowAccess', 'permissions', 'commandPermissions', 'usageLimits'], 'definition', self);
+    const next = clone(current);
+    if (patch.description !== undefined)
+        next.description = patch.description;
+    if (patch.allowAccess !== undefined)
+        next.allowAccess = patch.allowAccess;
+    if (patch.permissions !== undefined) {
+        if (!isObject(patch.permissions))
+            throw validationFailed(self, roleId, [{ field: 'permissions', code: 'INVALID_TYPE', message: 'permissions must be an object' }]);
+        next.permissions = { ...(next.permissions ?? {}) };
+        for (const [field, permission] of Object.entries(patch.permissions))
+            next.permissions[field] = clone(permission);
+    }
+    if (patch.commandPermissions !== undefined) {
+        if (!isObject(patch.commandPermissions))
+            throw validationFailed(self, roleId, [{ field: 'commandPermissions', code: 'INVALID_TYPE', message: 'commandPermissions must be an object' }]);
+        next.commandPermissions = { ...(next.commandPermissions ?? {}) };
+        for (const [operation, permission] of Object.entries(patch.commandPermissions))
+            next.commandPermissions[operation] = clone(permission);
+    }
+    if (patch.usageLimits !== undefined)
+        next.usageLimits = clone(patch.usageLimits);
+    const normalizedRemove = normalizeRemove(remove);
+    for (const field of normalizedRemove.permissions)
+        delete next.permissions[field];
+    for (const operation of normalizedRemove.commandPermissions)
+        delete next.commandPermissions?.[operation];
+    if (normalizedRemove.usageLimits)
+        delete next.usageLimits;
+    return next;
+}
+function normalizeRemove(value) {
+    if (!isObject(value))
+        return { permissions: [], commandPermissions: [], usageLimits: false };
+    return {
+        permissions: Array.isArray(value.permissions) ? value.permissions.filter(item => typeof item === 'string') : [],
+        commandPermissions: Array.isArray(value.commandPermissions) ? value.commandPermissions.filter(item => typeof item === 'string') : [],
+        usageLimits: value.usageLimits === true,
+    };
+}
+function validateRemove(value, self, roleId) {
+    if (value === undefined)
+        return;
+    const errors = [];
+    if (!isObject(value)) {
+        throw validationFailed(self, roleId, [{ field: 'remove', code: 'INVALID_TYPE', message: 'remove must be an object' }]);
+    }
+    for (const key of Object.keys(value)) {
+        if (!['permissions', 'commandPermissions', 'usageLimits'].includes(key))
+            errors.push({ field: `remove.${key}`, code: 'UNKNOWN_FIELD', message: `Unknown remove field: ${key}` });
+    }
+    for (const field of ['permissions', 'commandPermissions']) {
+        const item = value[field];
+        if (item !== undefined && (!Array.isArray(item) || !item.every(entry => typeof entry === 'string' && entry.length > 0))) {
+            errors.push({ field: `remove.${field}`, code: 'INVALID_TYPE', message: `${field} must be a non-empty string array` });
+        }
+    }
+    if (value.usageLimits !== undefined && typeof value.usageLimits !== 'boolean')
+        errors.push({ field: 'remove.usageLimits', code: 'INVALID_TYPE', message: 'usageLimits must be a boolean' });
+    if (errors.length)
+        throw validationFailed(self, roleId, errors);
+}
+function listRelations(self, known = { groups: new Set(), privates: new Set() }) {
+    const dir = agentRelationsDir(self);
+    if (!fs.existsSync(dir))
+        return [];
+    const records = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (!entry.isDirectory() || entry.name.startsWith('_'))
+            continue;
+        let parsed;
+        try {
+            parsed = parsePeerKey(entry.name);
+        }
+        catch {
+            continue;
+        }
+        const config = read(ConfigTarget.Relation, { self, peerKey: entry.name }, { cache: false });
+        if (!config)
+            continue;
+        const targetKind = relationTargetKind(config, parsed.channelId, known);
+        records.push({
+            peerKey: entry.name,
+            config,
+            revision: revision(config),
+            ...parsed,
+            targetKind,
+            isGroup: targetKind === 'group',
+        });
+    }
+    return records;
+}
+function readRelation(peerKey, self) {
+    const config = read(ConfigTarget.Relation, { self, peerKey }, { cache: false });
+    if (!config)
+        return null;
+    const parsed = parsePeerKey(peerKey);
+    const targetKind = relationTargetKind(config, parsed.channelId);
+    return { peerKey, config, revision: revision(config), ...parsed, targetKind, isGroup: targetKind === 'group' };
+}
+function relationTargetKind(config, channelId, known = { groups: new Set(), privates: new Set() }) {
+    if (config.targetKind)
+        return config.targetKind;
+    if (known.groups.has(channelId) || isExplicitGroupId(channelId))
+        return 'group';
+    if (known.privates.has(channelId))
+        return 'private';
+    return 'unknown';
+}
+function countRoleUsage(self, relations, roleId) {
+    const configuredDefaults = effectiveDefaultRoles(self);
+    const defaultScenes = ['private', 'group'].filter(scene => configuredDefaults[scene] === roleId);
+    let privateRelations = 0;
+    let groupRelations = 0;
+    for (const relation of relations) {
+        if (relation.config.role === roleId) {
+            if (relation.isGroup)
+                groupRelations += 1;
+            else
+                privateRelations += 1;
+        }
+    }
+    return { defaultScenes, privateRelations, groupRelations };
+}
+function relationReferencesRole(config, roleId) {
+    return config.role === roleId;
+}
+function appendRoleRelationChanges(self, relations, roleId, replacement, changes) {
+    for (const relation of relations) {
+        if (!relationReferencesRole(relation.config, roleId))
+            continue;
+        const next = clone(relation.config);
+        if (replacement === null)
+            delete next.role;
+        else
+            next.role = replacement;
+        const normalized = normalizeRelationForScene(next, relation.isGroup ? 'group' : 'private');
+        const file = agentRelationConfig(self, relation.peerKey);
+        changes.push({ file, before: readFileText(file), after: jsonText(normalized) });
+    }
+}
+function validateRoleDomainTransactionChanges(self, registry, changes) {
+    const schema = loadSchema('role-registry');
+    if (!schema.validate(registry)) {
+        throw validationFailed(self, undefined, (schema.validate.errors ?? []).map(error => ({
+            field: 'registry', code: 'SCHEMA_INVALID', message: error.message ?? 'invalid role registry',
+        })));
+    }
+    for (const change of changes) {
+        if (!change.after || !change.file.endsWith('.json') || change.file.endsWith('index.json'))
+            continue;
+        const isRelation = change.file.includes(`${path.sep}relations${path.sep}`);
+        const schema = loadSchema(isRelation ? 'relation-config' : 'role-config');
+        const value = JSON.parse(change.after);
+        if (!schema.validate(value)) {
+            throw validationFailed(self, undefined, [{
+                    field: isRelation ? 'relation' : 'role',
+                    code: 'SCHEMA_INVALID',
+                    message: isRelation ? 'invalid relation config' : 'invalid role definition',
+                }]);
+        }
+    }
+}
+function normalizeRelationForScene(value, scene) {
+    const normalized = clone(value);
+    normalized.$schema_version = currentVersion('relation-config');
+    normalized.targetKind = scene;
+    return normalized;
+}
+function commitJournal(self, changes) {
+    const journalFile = roleJournalPath(self);
+    const journal = { $schema_version: 1, self, state: 'prepared', changes };
+    atomicWriteJson(journalFile, journal);
+    try {
+        for (const change of changes)
+            applyFileContent(change.file, change.after);
+        journal.state = 'committed';
+        atomicWriteJson(journalFile, journal);
+        removeJournalFiles(journalFile);
+        invalidateChanges(changes);
+    }
+    catch (error) {
+        try {
+            recoverRoleMutationSync(self);
+        }
+        catch { }
+        throw error;
+    }
+}
+function removeJournalFiles(journalFile) {
+    // Remove backups first. If the process exits mid-cleanup, a committed main
+    // journal remains authoritative and recovery will keep the committed files.
+    for (const candidate of [`${journalFile}_`, `${journalFile}__`, journalFile]) {
+        try {
+            fs.unlinkSync(candidate);
+        }
+        catch (error) {
+            if (error?.code !== 'ENOENT')
+                throw error;
+        }
+    }
+}
+function validateJournal(self, journal) {
+    const root = path.resolve(agentDir(self));
+    if (journal.$schema_version !== 1 || journal.self !== self
+        || (journal.state !== 'prepared' && journal.state !== 'committed')
+        || !Array.isArray(journal.changes))
+        throw new Error('Invalid Role mutation journal');
+    const seen = new Set();
+    for (const change of journal.changes) {
+        if (!change || typeof change !== 'object' || typeof change.file !== 'string'
+            || (change.before !== null && typeof change.before !== 'string')
+            || (change.after !== null && typeof change.after !== 'string')) {
+            throw new Error('Role mutation journal contains an invalid change');
+        }
+        const file = path.resolve(change.file);
+        if (file === root || !file.startsWith(root + path.sep))
+            throw new Error('Role mutation journal contains an unsafe path');
+        if (seen.has(file))
+            throw new Error('Role mutation journal contains duplicate file changes');
+        seen.add(file);
+    }
+}
+function applyFileContent(file, content) {
+    if (content === null) {
+        for (const candidate of [file, `${file}_`, `${file}__`]) {
+            try {
+                fs.unlinkSync(candidate);
+            }
+            catch (error) {
+                if (error?.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+        return;
+    }
+    atomicWrite(file, content);
+}
+function invalidateChanges(changes) {
+    for (const change of changes)
+        fileCache.invalidate(change.file);
+    clearRoleStoreCache();
+}
+function roleJournalPath(self) {
+    return path.join(agentDir(self), ROLE_JOURNAL_FILE);
+}
+async function withAgentMutation(self, operation) {
+    const previous = mutationTails.get(self) ?? Promise.resolve();
+    let release;
+    const current = new Promise(resolve => { release = resolve; });
+    const queued = previous.then(() => current);
+    mutationTails.set(self, queued);
+    await previous;
+    try {
+        return await operation();
+    }
+    finally {
+        release();
+        if (mutationTails.get(self) === queued)
+            mutationTails.delete(self);
+    }
+}
+function paginate(items, args, self, key) {
+    const limit = normalizeLimit(args?.limit);
+    let start = 0;
+    if (args?.cursor !== undefined && args.cursor !== null) {
+        try {
+            const decoded = JSON.parse(Buffer.from(String(args.cursor), 'base64url').toString('utf8'));
+            if (!decoded || typeof decoded.after !== 'string')
+                throw new Error();
+            start = items.findIndex(item => key(item) > decoded.after);
+            if (start < 0)
+                start = items.length;
+        }
+        catch {
+            throw validationFailed(self, undefined, [{ field: 'cursor', code: 'INVALID_VALUE', message: 'cursor is invalid' }]);
+        }
+    }
+    const page = items.slice(start, start + limit);
+    const hasMore = start + page.length < items.length;
+    return {
+        items: page,
+        nextCursor: hasMore && page.length
+            ? Buffer.from(JSON.stringify({ after: key(page[page.length - 1]) }), 'utf8').toString('base64url')
+            : null,
+    };
+}
+function normalizeLimit(value) {
+    const number = Number(value ?? DEFAULT_PAGE_SIZE);
+    if (!Number.isInteger(number) || number <= 0)
+        return DEFAULT_PAGE_SIZE;
+    return Math.min(number, MAX_PAGE_SIZE);
+}
+function assignmentKey(item) {
+    const target = item.target;
+    return [target.kind, target.scene ?? '', target.peerKey ?? '', target.memberAid ?? ''].join('\u0000');
+}
+function requiredRoleId(args, self) {
+    const roleId = stringArg(args?.roleId);
+    if (!roleId)
+        throw validationFailed(self, undefined, [{ field: 'roleId', code: 'MISSING_FIELD', message: 'roleId is required' }]);
+    return roleId;
+}
+function assertOnlyKeys(value, allowed, field, self) {
+    const unexpected = Object.keys(value).filter(key => !allowed.includes(key));
+    if (unexpected.length)
+        throw validationFailed(self, undefined, unexpected.map(key => ({ field: `${field}.${key}`, code: 'UNKNOWN_FIELD', message: `Unknown field: ${key}` })));
+}
+function invalidTarget(self, field) {
+    return validationFailed(self, undefined, [{ field, code: 'MISSING_FIELD', message: `${field} is required` }]);
+}
+function invalidTargetValue(self, field) {
+    return validationFailed(self, undefined, [{ field, code: 'INVALID_VALUE', message: `${field} is not a valid AUN private target` }]);
+}
+function invalidJsonType(self, resource, expected) {
+    return roleError('INVALID_ARGUMENT', `Role ${resource} value must decode to ${expected}`, self, {
+        kind: 'invalid_json_value', resource, expected,
+    });
+}
+function roleNotFound(self, roleId) {
+    return roleError('NOT_FOUND', 'Role was not found', self, { kind: 'role_not_found', roleId });
+}
+function protectedRole(self, roleId, allowedAction) {
+    return roleError('NOT_ALLOWED', 'Built-in roles cannot be deleted; use reset instead', self, {
+        kind: 'protected_role', roleId, allowedAction,
+    });
+}
+function revisionConflict(self, resource, expectedRevision, currentRevision, extra) {
+    return roleError('CONFLICT', resource === 'policy' ? 'Role policy has changed' : 'Relation has changed', self, {
+        kind: 'revision_conflict', resource, expectedRevision: expectedRevision ?? null, currentRevision, ...(extra ?? {}),
+    });
+}
+function validationFailed(self, roleId, errors) {
+    return roleError('INVALID_ARGUMENT', 'RoleDefinition validation failed', self, {
+        kind: 'validation_failed', ...(roleId ? { roleId } : {}), errors,
+    });
+}
+function roleError(code, message, self, data) {
+    return new RoleMenuError(code, message, { $schema_version: ROLE_MENU_SCHEMA_VERSION, self, ...data });
+}
+function revision(value) {
+    return `sha256:${crypto.createHash('sha256').update(stableStringify(value)).digest('hex')}`;
+}
+function stableStringify(value) {
+    return JSON.stringify(sortValue(value));
+}
+function sortValue(value) {
+    if (Array.isArray(value))
+        return value.map(sortValue);
+    if (!isObject(value))
+        return value;
+    return Object.fromEntries(Object.keys(value).sort().map(key => [key, sortValue(value[key])]));
+}
+function clone(value) {
+    return value === undefined ? value : JSON.parse(JSON.stringify(value));
+}
+function stringArg(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+function isObject(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+function title(value) {
+    return value.split(/[-_.]/g).filter(Boolean).map(part => part === 'xhigh' ? 'Extra High' : part.charAt(0).toUpperCase() + part.slice(1)).join(' ');
+}
+function operationLabel(id) {
+    const labels = {
+        'role.policy.read': 'Read role policy',
+        'role.policy.write': 'Write role policy',
+        'role.relation.read': 'Read role assignments',
+        'role.assign': 'Assign role',
+        'role.revoke': 'Revoke role',
+    };
+    return labels[id] ?? title(id);
+}
+function validRoleOrNull(value, self) {
+    return typeof value === 'string' && value !== 'owner' && getRoleDefinition(value, self) ? value : null;
+}
+function getNested(value, field) {
+    let cursor = value;
+    for (const segment of field.split('.')) {
+        if (!cursor || typeof cursor !== 'object' || !Object.prototype.hasOwnProperty.call(cursor, segment))
+            return undefined;
+        cursor = cursor[segment];
+    }
+    return cursor;
+}
+function readFileText(file) {
+    try {
+        return fs.readFileSync(file, 'utf8');
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+function jsonText(value) {
+    return JSON.stringify(value, null, 2) + '\n';
+}