evolcore 0.0.1 → 0.0.3

package/dist/config/resolved-config-op.js

@@ -0,0 +1,483 @@
+import { normalizeCliArgv } from '../cli/cli-argv.js';
+import { parseConfigSelector } from '../cli/config-selector.js';
+import { parseConfigFieldValue, resolveConfigFieldRule, } from './config-field-policy.js';
+import { ConfigError, routeFieldPath } from './config-manager.js';
+const SELECTOR_OPTIONS = {
+    '--self': 'value',
+    '--peer': 'value',
+    '--default': 'boolean',
+    '--process': 'boolean',
+    '--daemon': 'boolean',
+};
+const FIELD_OPTIONS = {
+    ...SELECTOR_OPTIONS,
+    '--format': 'value',
+};
+const SCOPED_SUBCOMMANDS = new Set(['show', 'effective', 'fields', 'validate', 'init']);
+const GLOBAL_SUBCOMMANDS = new Set(['list', 'snapshot', 'prune', 'history', 'diff', 'restore', 'current', 'boots', 'schema']);
+export function resolveConfigCommand(inputArgv, options = {}) {
+    let argv = normalizeCliArgv(inputArgv);
+    if (argv[0] !== 'config') {
+        return { ok: false, code: 'INVALID_CONFIG_COMMAND', reason: 'Expected a config command' };
+    }
+    const subcommand = argv[1];
+    if (!subcommand) {
+        return { ok: false, code: 'MISSING_ARG', reason: 'A config subcommand is required' };
+    }
+    if (options.defaultRelation?.self && options.defaultRelation.peerKey
+        && isScopedConfigSubcommand(subcommand)
+        && !hasExplicitConfigSelector(argv)) {
+        argv = [...argv, '--self', options.defaultRelation.self, '--peer', options.defaultRelation.peerKey];
+    }
+    if (subcommand === 'get' || subcommand === 'set' || subcommand === 'unset') {
+        const field = resolveFieldCommand(argv, subcommand, options);
+        return field.ok ? { ok: true, command: field.op } : field;
+    }
+    if (SCOPED_SUBCOMMANDS.has(subcommand)) {
+        return resolveScopedCommand(argv, subcommand);
+    }
+    if (GLOBAL_SUBCOMMANDS.has(subcommand)) {
+        return resolveGlobalCommand(argv, subcommand);
+    }
+    return {
+        ok: false,
+        code: 'UNKNOWN_CONFIG_SUBCOMMAND',
+        reason: `Unknown config subcommand: ${subcommand}`,
+    };
+}
+export function resolveConfigOperation(inputArgv, options = {}) {
+    const resolved = resolveConfigCommand(inputArgv, options);
+    if (!resolved.ok)
+        return resolved;
+    if (resolved.command.kind !== 'field') {
+        return {
+            ok: false,
+            code: 'NOT_CONFIG_FIELD_COMMAND',
+            reason: `Config subcommand ${resolved.command.subcommand} is not field-scoped`,
+        };
+    }
+    return { ok: true, op: resolved.command };
+}
+export function isResolvedConfigMutation(command) {
+    if (command.kind === 'field')
+        return command.subcommand !== 'get';
+    if (command.kind === 'scoped')
+        return command.subcommand === 'init';
+    return command.subcommand === 'snapshot' || command.subcommand === 'prune' || command.subcommand === 'restore';
+}
+const FIELD_USAGE = {
+    get: 'config get <field> [selector]',
+    set: 'config set <field> <value> [selector]',
+    unset: 'config unset <field> [selector]',
+};
+function resolveFieldCommand(argv, subcommand, options = {}) {
+    const businessCount = subcommand === 'set' ? 2 : 1;
+    const business = parseLeadingPositionals(argv.slice(2), businessCount, FIELD_USAGE[subcommand]);
+    if (!business.ok)
+        return business;
+    const parsedOptions = parseOptions(business.rest, FIELD_OPTIONS);
+    if (!parsedOptions.ok)
+        return parsedOptions;
+    const formatCheck = validateOutputFormat(parsedOptions.values.format);
+    if (!formatCheck.ok)
+        return formatCheck;
+    // 先按"不强制 selector"解析，拿到用于路由的 scope；selector 是否缺失的判定推迟到字段校验之后，
+    // 这样非法字段会先于 SELECTOR_REQUIRED 暴露真正的 UNKNOWN_FIELD，而不是被通用的"缺 selector"掩盖。
+    const selector = parseConfigSelector(business.rest, { requireSelector: false });
+    if (!selector.ok)
+        return { ok: false, code: selector.code, reason: selector.reason };
+    const field = business.values[0].trim();
+    if (!field)
+        return { ok: false, code: 'MISSING_ARG', reason: `config ${subcommand} requires a field` };
+    if (field === 'permissionMode') {
+        return {
+            ok: false,
+            code: 'ROLE_POLICY_MANAGED',
+            reason: 'permissionMode is defined by roles; use the role policy editor',
+        };
+    }
+    if (field === 'role') {
+        return {
+            ok: false,
+            code: 'ROLE_POLICY_MANAGED',
+            reason: 'Relation role assignments are managed through the role assignment service',
+        };
+    }
+    if (subcommand !== 'get' && (field === 'roles' || field.startsWith('roles.'))) {
+        return {
+            ok: false,
+            code: 'ROLE_POLICY_MANAGED',
+            reason: 'Agent role policies are managed through the role policy editor',
+        };
+    }
+    const fieldRule = resolveConfigFieldRule(field);
+    if (subcommand !== 'get' && fieldRule.class === 'safe-readonly-object') {
+        return {
+            ok: false,
+            code: 'UNSUPPORTED_CONFIG_VALUE',
+            reason: `Config field ${field} does not support object writes`,
+        };
+    }
+    const commandScope = selector.scope === 'defaults' ? 'process' : selector.scope;
+    const isSafe = fieldRule.class === 'safe-scalar' || fieldRule.class === 'safe-readonly-object';
+    const isManagementOperation = commandScope === 'process' || !isSafe;
+    const operationId = isManagementOperation
+        ? subcommand === 'get' ? 'config.read' : 'config.write'
+        : `config.${subcommand}`;
+    let route;
+    const routeRequired = subcommand !== 'get' || !isManagementOperation;
+    try {
+        route = routeFieldPath(field, selector.scope);
+    }
+    catch (error) {
+        if (routeRequired)
+            return configErrorResult(error);
+    }
+    // 字段已校验通过，再补齐"写操作必须显式 selector"的约束（get 不要求）。
+    const selectorMissing = selector.scope === 'agent' && !selector.self;
+    if (subcommand !== 'get' && selectorMissing) {
+        return {
+            ok: false,
+            code: 'SELECTOR_REQUIRED',
+            reason: `config ${subcommand} ${field} needs a target: --self <aid> [--peer <peerKey>] | --default | --process`,
+        };
+    }
+    // get 在独立 CLI 模式（无 defaultRelation）也要求显式 selector，避免"不知道读谁的"。
+    if (subcommand === 'get' && selectorMissing && !options.defaultRelation?.self) {
+        return {
+            ok: false,
+            code: 'SELECTOR_REQUIRED',
+            reason: `config get ${field} needs a target: --self <aid> [--peer <peerKey>] | --default | --process`,
+        };
+    }
+    if (subcommand === 'unset' && selector.scope === 'process') {
+        return { ok: false, code: 'UNSET_PROCESS_REJECT', reason: 'daemon.json has no lower config layer to fall back to' };
+    }
+    const rawValue = subcommand === 'set' ? business.values[1] : undefined;
+    let value;
+    if (subcommand === 'set') {
+        if (fieldRule.class === 'safe-scalar') {
+            const parsedValue = parseConfigFieldValue(field, rawValue);
+            if (!parsedValue.ok)
+                return { ok: false, code: 'INVALID_CONFIG_VALUE', reason: parsedValue.reason };
+            value = parsedValue.value;
+        }
+        else {
+            if (!route)
+                return { ok: false, code: 'UNKNOWN_FIELD', reason: `Unknown config field: ${field}` };
+            value = coerceConfigValue(rawValue, route);
+        }
+    }
+    return {
+        ok: true,
+        op: {
+            kind: 'field',
+            canonicalArgv: buildFieldCanonicalArgv(subcommand, field, rawValue, selector, parsedOptions.values.format),
+            subcommand,
+            configScope: selector.scope,
+            commandScope,
+            operationId,
+            dangerous: operationId === 'config.read' || operationId === 'config.write',
+            field,
+            fieldRule,
+            route,
+            ...(selector.self ? { self: selector.self } : {}),
+            ...(selector.peerKey ? { peerKey: selector.peerKey } : {}),
+            ...(rawValue !== undefined ? { rawValue, value } : {}),
+            ...(parsedOptions.values.format ? { format: parsedOptions.values.format } : {}),
+        },
+    };
+}
+function resolveScopedCommand(argv, subcommand) {
+    const positionalCount = subcommand === 'fields' ? { min: 0, max: 1 } : { min: 0, max: 0 };
+    const parsed = parseStructuredArgs(argv.slice(2), {
+        options: { ...SELECTOR_OPTIONS, '--format': 'value' },
+        ...positionalCount,
+    });
+    if (!parsed.ok)
+        return parsed;
+    const formatCheck = validateOutputFormat(parsed.values.format);
+    if (!formatCheck.ok)
+        return formatCheck;
+    const selector = parseConfigSelector(argv.slice(2), { requireSelector: subcommand !== 'fields' });
+    if (!selector.ok)
+        return { ok: false, code: selector.code, reason: selector.reason };
+    const commandScope = selector.scope === 'defaults' ? 'process' : selector.scope;
+    const format = parsed.values.format;
+    const field = parsed.positionals[0];
+    return {
+        ok: true,
+        command: {
+            kind: 'scoped',
+            canonicalArgv: buildScopedCanonicalArgv(subcommand, selector, field, format),
+            subcommand,
+            configScope: selector.scope,
+            commandScope,
+            operationId: `config.${subcommand}`,
+            dangerous: true,
+            ...(selector.self ? { self: selector.self } : {}),
+            ...(selector.peerKey ? { peerKey: selector.peerKey } : {}),
+            ...(field ? { field } : {}),
+            ...(format ? { format } : {}),
+        },
+    };
+}
+function resolveGlobalCommand(argv, subcommand) {
+    const specs = {
+        list: { min: 0, max: 0, options: { '--format': 'value' } },
+        snapshot: { min: 0, max: 0, options: { '--full': 'boolean', '--desc': 'value', '--format': 'value' } },
+        prune: { min: 0, max: 0, options: { '--keep-full': 'value', '--keep-delta': 'value', '--yes': 'boolean', '--format': 'value' } },
+        history: { min: 0, max: 0, options: { '--format': 'value' } },
+        diff: { min: 2, max: 2, options: { '--format': 'value' } },
+        restore: { min: 1, max: 1, options: { '--format': 'value' } },
+        current: { min: 0, max: 0, options: { '--format': 'value' } },
+        boots: { min: 0, max: 0, options: { '-n': 'value', '--num': 'value', '--format': 'value' }, aliases: [['-n', '--num']] },
+        schema: { min: 0, max: 2, options: { '--list': 'boolean', '--format': 'value' } },
+    };
+    const parsed = parseStructuredArgs(argv.slice(2), specs[subcommand]);
+    if (!parsed.ok)
+        return parsed;
+    const formatCheck = validateOutputFormat(parsed.values.format);
+    if (!formatCheck.ok)
+        return formatCheck;
+    const format = parsed.values.format;
+    const command = {
+        kind: 'global',
+        canonicalArgv: [],
+        subcommand,
+        configScope: 'process',
+        commandScope: 'process',
+        operationId: `config.${subcommand}`,
+        dangerous: true,
+        ...(format ? { format } : {}),
+    };
+    if (subcommand === 'snapshot') {
+        command.full = parsed.flags.has('full');
+        if (parsed.values.desc !== undefined)
+            command.description = parsed.values.desc;
+    }
+    else if (subcommand === 'prune') {
+        command.yes = parsed.flags.has('yes');
+        const keepFull = parseNonNegativeInteger(parsed.values.keepFull, '--keep-full');
+        if (!keepFull.ok)
+            return keepFull;
+        const keepDelta = parseNonNegativeInteger(parsed.values.keepDelta, '--keep-delta');
+        if (!keepDelta.ok)
+            return keepDelta;
+        if (keepFull.value !== undefined)
+            command.keepFull = keepFull.value;
+        if (keepDelta.value !== undefined)
+            command.keepDelta = keepDelta.value;
+    }
+    else if (subcommand === 'diff') {
+        command.versions = [parsed.positionals[0], parsed.positionals[1]];
+    }
+    else if (subcommand === 'restore') {
+        command.version = parsed.positionals[0];
+    }
+    else if (subcommand === 'boots') {
+        const count = parsePositiveInteger(parsed.values.n ?? parsed.values.num, '-n/--num');
+        if (!count.ok)
+            return count;
+        command.count = count.value ?? 10;
+    }
+    else if (subcommand === 'schema') {
+        command.schemaList = parsed.flags.has('list');
+        if (parsed.positionals[0])
+            command.schemaName = parsed.positionals[0];
+        if (parsed.positionals[1] !== undefined) {
+            if (command.schemaList) {
+                return { ok: false, code: 'INVALID_CONFIG_COMMAND', reason: 'config schema --list does not take a version argument' };
+            }
+            const version = parseNonNegativeInteger(parsed.positionals[1], 'version');
+            if (!version.ok)
+                return version;
+            command.schemaVersion = version.value;
+        }
+        if (!command.schemaName && (command.schemaList || command.schemaVersion !== undefined)) {
+            return { ok: false, code: 'MISSING_ARG', reason: 'config schema requires a schema name' };
+        }
+    }
+    command.canonicalArgv = buildGlobalCanonicalArgv(command);
+    return { ok: true, command };
+}
+function isScopedConfigSubcommand(subcommand) {
+    return subcommand === 'get' || subcommand === 'set' || subcommand === 'unset'
+        || SCOPED_SUBCOMMANDS.has(subcommand);
+}
+function hasExplicitConfigSelector(argv) {
+    const selectors = new Set(['--self', '--peer', '--default', '--process', '--daemon']);
+    return argv.some(arg => selectors.has(arg));
+}
+function parseLeadingPositionals(argv, count, usage) {
+    const values = argv.slice(0, count);
+    if (values.length !== count || values.some(value => !value || value.startsWith('-'))) {
+        const noun = count === 1 ? '<field>' : '<field> <value>';
+        return {
+            ok: false,
+            code: 'MISSING_ARG',
+            reason: `Missing ${noun}. Usage: ${usage}`,
+        };
+    }
+    const rest = argv.slice(count);
+    if (rest[0] && !rest[0].startsWith('-')) {
+        return { ok: false, code: 'INVALID_CONFIG_COMMAND', reason: `Unexpected argument "${rest[0]}". Usage: ${usage}` };
+    }
+    return { ok: true, values, rest };
+}
+function parseOptions(argv, options) {
+    const parsed = parseStructuredArgs(argv, { min: 0, max: 0, options, aliases: [['--process', '--daemon']] });
+    if (!parsed.ok)
+        return parsed;
+    return { ok: true, values: parsed.values, flags: parsed.flags };
+}
+function parseStructuredArgs(argv, spec) {
+    const positionals = [];
+    const values = {};
+    const flags = new Set();
+    const seen = new Set();
+    const aliasGroups = spec.aliases ?? [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--') {
+            return { ok: false, code: 'INVALID_CONFIG_COMMAND', reason: '-- is not supported in config commands' };
+        }
+        if (!arg.startsWith('-')) {
+            positionals.push(arg);
+            continue;
+        }
+        const kind = spec.options[arg];
+        if (!kind)
+            return { ok: false, code: 'INVALID_CONFIG_COMMAND', reason: `Unexpected config argument: ${arg}` };
+        const aliasGroup = aliasGroups.find(group => group.includes(arg));
+        if (seen.has(arg) || aliasGroup?.some(alias => seen.has(alias))) {
+            return { ok: false, code: 'SELECTOR_CONFLICT', reason: `Duplicate config option: ${arg}` };
+        }
+        seen.add(arg);
+        const key = optionKey(arg);
+        if (kind === 'boolean') {
+            flags.add(key);
+            continue;
+        }
+        const value = argv[i + 1];
+        if (!value || value.startsWith('-')) {
+            return { ok: false, code: 'MISSING_FLAG_VALUE', reason: `${arg} requires a value` };
+        }
+        values[key] = value;
+        i += 1;
+    }
+    if (positionals.length < spec.min) {
+        return { ok: false, code: 'MISSING_ARG', reason: `Config command requires ${spec.min} positional argument${spec.min === 1 ? '' : 's'}` };
+    }
+    if (positionals.length > spec.max) {
+        return { ok: false, code: 'INVALID_CONFIG_COMMAND', reason: `Unexpected positional argument: ${positionals[spec.max]}` };
+    }
+    return { ok: true, positionals, values, flags };
+}
+function optionKey(option) {
+    return option.replace(/^-+/, '').replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+function parseNonNegativeInteger(raw, option) {
+    if (raw === undefined)
+        return { ok: true };
+    if (!/^\d+$/.test(raw))
+        return { ok: false, code: 'INVALID_CONFIG_VALUE', reason: `${option} requires a non-negative integer` };
+    const value = Number(raw);
+    if (!Number.isSafeInteger(value)) {
+        return { ok: false, code: 'INVALID_CONFIG_VALUE', reason: `${option} is outside the supported integer range` };
+    }
+    return { ok: true, value };
+}
+function parsePositiveInteger(raw, option) {
+    const parsed = parseNonNegativeInteger(raw, option);
+    if (!parsed.ok || parsed.value === undefined)
+        return parsed;
+    if (parsed.value < 1)
+        return { ok: false, code: 'INVALID_CONFIG_VALUE', reason: `${option} requires a positive integer` };
+    return parsed;
+}
+function validateOutputFormat(format) {
+    if (format === undefined || format === 'json' || format === 'text')
+        return { ok: true };
+    return { ok: false, code: 'INVALID_CONFIG_VALUE', reason: `Unsupported config output format: ${format}` };
+}
+function buildFieldCanonicalArgv(subcommand, field, rawValue, selector, format) {
+    const argv = ['config', subcommand, field];
+    if (rawValue !== undefined)
+        argv.push(rawValue);
+    appendCanonicalSelector(argv, selector);
+    if (format)
+        argv.push('--format', format);
+    return argv;
+}
+function buildScopedCanonicalArgv(subcommand, selector, field, format) {
+    const argv = ['config', subcommand];
+    if (field)
+        argv.push(field);
+    appendCanonicalSelector(argv, selector);
+    if (format)
+        argv.push('--format', format);
+    return argv;
+}
+function appendCanonicalSelector(argv, selector) {
+    if (selector.scope === 'process')
+        argv.push('--process');
+    if (selector.scope === 'defaults')
+        argv.push('--default');
+    if (selector.self)
+        argv.push('--self', selector.self);
+    if (selector.peerKey)
+        argv.push('--peer', selector.peerKey);
+}
+function buildGlobalCanonicalArgv(command) {
+    const argv = ['config', command.subcommand];
+    if (command.subcommand === 'diff' && command.versions)
+        argv.push(...command.versions);
+    if (command.subcommand === 'restore' && command.version)
+        argv.push(command.version);
+    if (command.subcommand === 'snapshot') {
+        if (command.full)
+            argv.push('--full');
+        if (command.description !== undefined)
+            argv.push('--desc', command.description);
+    }
+    if (command.subcommand === 'prune') {
+        if (command.keepFull !== undefined)
+            argv.push('--keep-full', String(command.keepFull));
+        if (command.keepDelta !== undefined)
+            argv.push('--keep-delta', String(command.keepDelta));
+        if (command.yes)
+            argv.push('--yes');
+    }
+    if (command.subcommand === 'boots' && command.count !== undefined)
+        argv.push('-n', String(command.count));
+    if (command.subcommand === 'schema') {
+        if (command.schemaName)
+            argv.push(command.schemaName);
+        if (command.schemaVersion !== undefined)
+            argv.push(String(command.schemaVersion));
+        if (command.schemaList)
+            argv.push('--list');
+    }
+    if (command.format)
+        argv.push('--format', command.format);
+    return argv;
+}
+function coerceConfigValue(raw, route) {
+    if (route.merge === 'list')
+        return [raw];
+    if (route.enum)
+        return raw;
+    if (raw === 'true')
+        return true;
+    if (raw === 'false')
+        return false;
+    if (/^-?\d+(\.\d+)?$/.test(raw))
+        return Number(raw);
+    return raw;
+}
+function configErrorResult(error) {
+    if (error instanceof ConfigError)
+        return { ok: false, code: error.code, reason: error.message };
+    return { ok: false, code: 'CONFIG_ERROR', reason: error instanceof Error ? error.message : String(error) };
+}

package/dist/config/role-config-v4-startup.js

@@ -0,0 +1,32 @@
+import path from 'path';
+import { pathToFileURL } from 'url';
+import { getPackageRoot, resolvePaths } from '../paths.js';
+import { assertRoleConfigV4Ready, ConfigError } from './config-manager.js';
+/**
+ * Automatically applies the one-off role config migration before daemon startup.
+ * The migration script owns backup, validation, atomic writes, rollback, and locking.
+ */
+export async function ensureRoleConfigV4OnStartup() {
+    try {
+        assertRoleConfigV4Ready();
+        return null;
+    }
+    catch (error) {
+        if (!(error instanceof ConfigError) || error.code !== 'ROLE_CONFIG_MIGRATION_REQUIRED')
+            throw error;
+    }
+    const home = resolvePaths().root;
+    const script = path.join(getPackageRoot(), 'kits', 'migrations', 'migrate-role-config-v4.mjs');
+    try {
+        const migration = await import(pathToFileURL(script).href);
+        const result = migration.runMigration({ home, apply: true });
+        assertRoleConfigV4Ready();
+        return result;
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new ConfigError('ROLE_CONFIG_MIGRATION_FAILED', `Automatic role config v4 migration failed: ${detail}\n` +
+            `Fix the reported config or run manually:\n` +
+            `node kits/migrations/migrate-role-config-v4.mjs --apply --home ${JSON.stringify(home)}`, { cause: error });
+    }
+}

package/dist/config/role-config-v5-startup.js

@@ -0,0 +1,27 @@
+import path from 'path';
+import { pathToFileURL } from 'url';
+import { getPackageRoot, resolvePaths } from '../paths.js';
+import { assertRoleConfigV5Ready, ConfigError } from './config-manager.js';
+export async function ensureRoleConfigV5OnStartup() {
+    try {
+        assertRoleConfigV5Ready();
+        return null;
+    }
+    catch (error) {
+        if (!(error instanceof ConfigError) || error.code !== 'ROLE_CONFIG_V5_MIGRATION_REQUIRED')
+            throw error;
+    }
+    const home = resolvePaths().root;
+    const script = path.join(getPackageRoot(), 'kits', 'migrations', 'migrate-role-config-v5.mjs');
+    try {
+        const migration = await import(pathToFileURL(script).href);
+        const result = migration.runMigration({ home, apply: true });
+        assertRoleConfigV5Ready();
+        return result;
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new ConfigError('ROLE_CONFIG_V5_MIGRATION_FAILED', `Automatic standalone role migration failed: ${detail}\n` +
+            `node kits/migrations/migrate-role-config-v5.mjs --apply --home ${JSON.stringify(home)}`, { cause: error });
+    }
+}

package/dist/config/role-ranks.js

@@ -0,0 +1,18 @@
+export const ROLE_RANKS = Object.freeze({
+    owner: 900,
+    admin: 700,
+    custom: 500,
+    member: 300,
+    visitor: 100,
+});
+export function expectedRoleRank(role) {
+    if (role === 'owner')
+        return ROLE_RANKS.owner;
+    if (role === 'admin')
+        return ROLE_RANKS.admin;
+    if (role === 'member')
+        return ROLE_RANKS.member;
+    if (role === 'visitor')
+        return ROLE_RANKS.visitor;
+    return ROLE_RANKS.custom;
+}

package/dist/config/role-schema.js

@@ -0,0 +1,105 @@
+import { loadSchema } from './schema-registry.js';
+export function rolePermissionFields() {
+    const raw = loadSchema('role-config').raw['x-permission-fields'];
+    if (!Array.isArray(raw))
+        return [];
+    return raw
+        .filter(isDescriptor)
+        .map(field => ({
+        value: field.value,
+        label: field.label,
+        valueType: field.valueType,
+        hasOptions: field.hasOptions,
+        relationOverrideApplied: field.relationOverrideApplied,
+        constraintsApplied: field.constraintsApplied,
+        editable: field.editable,
+        runtimeApplied: field['x-runtimeApplied'],
+        optionsSource: field['x-optionsSource'],
+        options: field.options?.map((option) => ({ ...option })),
+        patterns: field.patterns?.map((pattern) => ({ ...pattern, kind: 'pattern' })),
+    }));
+}
+function isDescriptor(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const item = value;
+    return typeof item.value === 'string'
+        && typeof item.label === 'string'
+        && (item.valueType === 'enum' || item.valueType === 'model')
+        && typeof item.hasOptions === 'boolean'
+        && typeof item.relationOverrideApplied === 'boolean'
+        && typeof item.constraintsApplied === 'boolean'
+        && typeof item.editable === 'boolean'
+        && typeof item['x-runtimeApplied'] === 'boolean'
+        && (item['x-optionsSource'] === 'static-enum' || item['x-optionsSource'] === 'model-catalog');
+}
+export function rolePermissionFieldOptions(field) {
+    return field.options?.map(option => ({ ...option })) ?? [];
+}
+export function rolePermissionFieldPatterns(field) {
+    return field.patterns?.map(pattern => ({ ...pattern })) ?? [];
+}
+/** Shared RoleService/Menu validation backed by the published role schema. */
+export function validateRoleConfig(value) {
+    const normalized = isRecord(value) && !Object.hasOwn(value, '$schema_version')
+        ? { ...value, $schema_version: 1 }
+        : value;
+    const schema = loadSchema('role-config');
+    if (!schema.validate(normalized)) {
+        return (schema.validate.errors ?? []).map(error => ({
+            field: schemaErrorField(error),
+            code: String(error.keyword || 'SCHEMA_INVALID').toUpperCase(),
+            message: error.message || 'role configuration is invalid',
+        }));
+    }
+    return validateRoleConfigSemantics(normalized);
+}
+/** Validate constraints that JSON Schema draft-07 cannot express across sibling fields. */
+export function validateRoleConfigSemantics(value) {
+    if (!isRecord(value) || !isRecord(value.permissions))
+        return [];
+    const issues = [];
+    for (const [field, rawPermission] of Object.entries(value.permissions)) {
+        if (!isRecord(rawPermission))
+            continue;
+        const defaultValue = rawPermission.default;
+        if (Array.isArray(rawPermission.allowedValues)
+            && !rawPermission.allowedValues.some(candidate => Object.is(candidate, defaultValue))) {
+            issues.push({
+                field: `permissions.${field}.default`,
+                code: 'VALUE_NOT_ALLOWED',
+                message: 'default must be included in allowedValues',
+            });
+        }
+        if (Array.isArray(rawPermission.allowedModels)
+            && typeof defaultValue === 'string'
+            && !rawPermission.allowedModels.some(pattern => typeof pattern === 'string' && wildcardMatch(pattern, defaultValue))) {
+            issues.push({
+                field: `permissions.${field}.default`,
+                code: 'MODEL_NOT_ALLOWED',
+                message: 'default model must be allowed by allowedModels',
+            });
+        }
+    }
+    return issues;
+}
+function wildcardMatch(pattern, value) {
+    const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+    return new RegExp(`^${escaped}$`).test(value);
+}
+function isRecord(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+function schemaErrorField(error) {
+    const path = String(error?.instancePath || '')
+        .split('/')
+        .filter(Boolean)
+        .map((part) => part.replace(/~1/g, '/').replace(/~0/g, '~'));
+    if (error?.keyword === 'required' && typeof error?.params?.missingProperty === 'string') {
+        path.push(error.params.missingProperty);
+    }
+    else if (error?.keyword === 'additionalProperties' && typeof error?.params?.additionalProperty === 'string') {
+        path.push(error.params.additionalProperty);
+    }
+    return path.filter(part => part !== '$schema_version').join('.') || 'definition';
+}