@ornexus/neocortex 4.60.18 → 4.60.19

package/packages/shared/dist/command-registry-contract.js

@@ -0,0 +1,382 @@
+/** P205.06 public data-only command-registry admission contract. */
+import { createHash } from 'node:crypto';
+export const COMMAND_REGISTRY_ERROR_CODES = [
+    'REGISTRY_UTF8_INVALID', 'REGISTRY_JSON_INVALID', 'REGISTRY_DUPLICATE_MEMBER',
+    'REGISTRY_SCHEMA_INVALID', 'REGISTRY_VERSION_UNSUPPORTED', 'REGISTRY_COLLISION',
+    'REGISTRY_PROJECTION_DRIFT', 'REGISTRY_HANDLER_ORPHAN', 'REGISTRY_UNAVAILABLE',
+];
+export class CommandRegistryContractError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = 'CommandRegistryContractError';
+    }
+}
+const ID = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const compareBytes = (a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b));
+const fail = (code) => { throw new CommandRegistryContractError(code); };
+export function normalizeCommandTokenExact(input) {
+    if (typeof input !== 'string' || /[^\x20-\x7e]/.test(input))
+        return '';
+    const trimmed = input.replace(/^[\t\n\r ]+|[\t\n\r ]+$/g, '');
+    if (!trimmed || trimmed.startsWith('**'))
+        return '';
+    const unstarred = trimmed.startsWith('*') ? trimmed.slice(1) : trimmed;
+    const normalized = unstarred.replace(/[A-Z]/g, (letter) => letter.toLowerCase());
+    return ID.test(normalized) || normalized === '?' ? normalized : '';
+}
+function assertUnicode(value) {
+    for (let i = 0; i < value.length; i++) {
+        const current = value.charCodeAt(i);
+        if (current >= 0xd800 && current <= 0xdbff) {
+            const next = value.charCodeAt(++i);
+            if (!(next >= 0xdc00 && next <= 0xdfff))
+                fail('REGISTRY_SCHEMA_INVALID');
+        }
+        else if (current >= 0xdc00 && current <= 0xdfff)
+            fail('REGISTRY_SCHEMA_INVALID');
+    }
+}
+export function canonicalizeCommandRegistryJcs(value) {
+    if (value === null)
+        return 'null';
+    if (typeof value === 'string') {
+        assertUnicode(value);
+        return JSON.stringify(value);
+    }
+    if (typeof value === 'boolean')
+        return value ? 'true' : 'false';
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value) || (Number.isInteger(value) && !Number.isSafeInteger(value)))
+            fail('REGISTRY_SCHEMA_INVALID');
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value))
+        return `[${value.map(canonicalizeCommandRegistryJcs).join(',')}]`;
+    if (!value || typeof value !== 'object')
+        fail('REGISTRY_SCHEMA_INVALID');
+    const record = value;
+    return `{${Object.keys(record).sort(compareBytes).map((key) => `${JSON.stringify(key)}:${canonicalizeCommandRegistryJcs(record[key])}`).join(',')}}`;
+}
+/** Detect duplicate object members before JSON.parse can silently last-win. */
+function rejectDuplicateMembers(text) {
+    let index = 0;
+    const ws = () => { while (/\s/.test(text[index] ?? ''))
+        index++; };
+    const string = () => {
+        if (text[index++] !== '"')
+            fail('REGISTRY_JSON_INVALID');
+        const start = index - 1;
+        let escaped = false;
+        while (index < text.length) {
+            const char = text[index++];
+            if (!escaped && char === '"') {
+                try {
+                    return JSON.parse(text.slice(start, index));
+                }
+                catch {
+                    fail('REGISTRY_JSON_INVALID');
+                }
+            }
+            escaped = !escaped && char === '\\';
+            if (char !== '\\')
+                escaped = false;
+        }
+        return fail('REGISTRY_JSON_INVALID');
+    };
+    const value = () => {
+        ws();
+        const char = text[index];
+        if (char === '{')
+            object();
+        else if (char === '[')
+            array();
+        else if (char === '"') {
+            string();
+        }
+        else {
+            const match = /^(?:true|false|null|-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?)/.exec(text.slice(index));
+            if (!match)
+                return fail('REGISTRY_JSON_INVALID');
+            index += match[0].length;
+        }
+        ws();
+    };
+    const array = () => {
+        index++;
+        ws();
+        if (text[index] === ']') {
+            index++;
+            return;
+        }
+        while (true) {
+            value();
+            if (text[index] === ']') {
+                index++;
+                return;
+            }
+            if (text[index++] !== ',')
+                fail('REGISTRY_JSON_INVALID');
+        }
+    };
+    const object = () => {
+        index++;
+        ws();
+        const keys = new Set();
+        if (text[index] === '}') {
+            index++;
+            return;
+        }
+        while (true) {
+            ws();
+            const key = string();
+            if (keys.has(key))
+                fail('REGISTRY_DUPLICATE_MEMBER');
+            keys.add(key);
+            ws();
+            if (text[index++] !== ':')
+                fail('REGISTRY_JSON_INVALID');
+            value();
+            if (text[index] === '}') {
+                index++;
+                return;
+            }
+            if (text[index++] !== ',')
+                fail('REGISTRY_JSON_INVALID');
+        }
+    };
+    value();
+    if (index !== text.length)
+        fail('REGISTRY_JSON_INVALID');
+}
+const ROOT_KEYS = ['commands', 'registryVersion', 'schemaVersion'];
+const COMMAND_KEYS = ['aliases', 'category', 'compatibility', 'description', 'examples', 'handlerClass', 'handlerRef', 'id', 'inputShape', 'invocation', 'mode', 'name', 'number', 'policy', 'projections', 'stepId', 'subcommands', 'visibility'];
+const OPERATION_KEYS = ['aliases', 'compatibility', 'handlerClass', 'handlerRef', 'id', 'policy', 'projections', 'visibility'];
+const INVOCATION_KEYS = ['operation', 'options', 'positionals', 'terminator'];
+const INVOCATION_OPERATION_KEYS = ['required', 'unknownAsPositional'];
+const INVOCATION_OPTION_KEYS = ['aliases', 'cardinality', 'default', 'id', 'kind', 'required', 'syntax', 'valuePattern'];
+const INVOCATION_POSITIONAL_KEYS = ['cardinality', 'id', 'kind', 'order', 'required'];
+const POLICY_KEYS = ['billingClass', 'idempotencyClass', 'minimumTier', 'mutationClass', 'privilege', 'quotaClass', 'replayClass', 'strictReadOnly'];
+const COMPATIBILITY_KEYS = ['deprecatedIn', 'introducedIn', 'removedIn', 'replacement'];
+const DESCRIPTION_KEYS = ['en', 'es', 'pt-BR'];
+const PROJECTIONS = ['admin', 'client', 'docs', 'metrics', 'server', 'shared'];
+function exactKeys(value, expected) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        fail('REGISTRY_SCHEMA_INVALID');
+    const actual = Object.keys(value).sort(compareBytes);
+    const keys = [...expected].sort(compareBytes);
+    if (actual.length !== keys.length || actual.some((key, index) => key !== keys[index]))
+        fail('REGISTRY_SCHEMA_INVALID');
+}
+function stringArray(value, allowQuestion = false) {
+    if (!Array.isArray(value))
+        fail('REGISTRY_SCHEMA_INVALID');
+    const result = value.map((item) => {
+        if (typeof item !== 'string')
+            fail('REGISTRY_SCHEMA_INVALID');
+        const text = item;
+        if (allowQuestion && text === '?')
+            return text;
+        if (normalizeCommandTokenExact(text) !== text)
+            fail('REGISTRY_SCHEMA_INVALID');
+        return text;
+    });
+    if (new Set(result).size !== result.length)
+        fail('REGISTRY_COLLISION');
+    return [...result].sort(compareBytes);
+}
+function validateCompatibility(value) {
+    exactKeys(value, COMPATIBILITY_KEYS);
+    const record = value;
+    for (const key of COMPATIBILITY_KEYS) {
+        if (record[key] !== null && typeof record[key] !== 'string')
+            fail('REGISTRY_SCHEMA_INVALID');
+    }
+    return record;
+}
+function validatePolicy(value) {
+    exactKeys(value, POLICY_KEYS);
+    const record = value;
+    const allowed = {
+        privilege: ['authenticated', 'admin'], minimumTier: ['free', 'pro', 'enterprise'],
+        billingClass: ['billable', 'non-billable'], quotaClass: ['none', 'invocation', 'workflow', 'planning'],
+        mutationClass: ['read-only', 'stateful', 'external'], strictReadOnly: ['allow', 'deny'],
+        replayClass: ['signed-request', 'none'], idempotencyClass: ['none', 'logical-supported', 'logical-required'],
+    };
+    for (const [key, values] of Object.entries(allowed))
+        if (!values.includes(record[key]))
+            fail('REGISTRY_SCHEMA_INVALID');
+    return record;
+}
+function validateInvocation(value) {
+    exactKeys(value, INVOCATION_KEYS);
+    const invocation = value;
+    exactKeys(invocation.operation, INVOCATION_OPERATION_KEYS);
+    if (typeof invocation.operation.required !== 'boolean'
+        || typeof invocation.operation.unknownAsPositional !== 'boolean'
+        || invocation.terminator !== true)
+        fail('REGISTRY_SCHEMA_INVALID');
+    if (!Array.isArray(invocation.options) || !Array.isArray(invocation.positionals))
+        fail('REGISTRY_SCHEMA_INVALID');
+    const optionIds = new Set();
+    const optionAliases = new Set();
+    const options = invocation.options.map((raw) => {
+        exactKeys(raw, INVOCATION_OPTION_KEYS);
+        const option = raw;
+        if (typeof option.id !== 'string' || !/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(option.id)
+            || optionIds.has(option.id) || optionAliases.has(option.id))
+            fail('REGISTRY_COLLISION');
+        const optionId = option.id;
+        optionIds.add(optionId);
+        const aliases = stringArray(option.aliases);
+        for (const alias of aliases) {
+            if (optionIds.has(alias) || optionAliases.has(alias))
+                fail('REGISTRY_COLLISION');
+            optionAliases.add(alias);
+        }
+        if (!['boolean', 'string', 'string-list', 'url', 'path'].includes(option.kind)
+            || !['one', 'many'].includes(option.cardinality) || typeof option.required !== 'boolean')
+            fail('REGISTRY_SCHEMA_INVALID');
+        if (option.default !== null && typeof option.default !== 'boolean' && typeof option.default !== 'string')
+            fail('REGISTRY_SCHEMA_INVALID');
+        if (!Array.isArray(option.syntax) || !option.syntax.length
+            || option.syntax.some((syntax) => !['bare', 'split', 'inline'].includes(syntax))
+            || new Set(option.syntax).size !== option.syntax.length)
+            fail('REGISTRY_SCHEMA_INVALID');
+        if (option.kind === 'boolean' && (option.default !== false || JSON.stringify(option.syntax) !== '["bare"]'))
+            fail('REGISTRY_SCHEMA_INVALID');
+        if (option.kind !== 'boolean' && (option.syntax.includes('bare') || option.default !== null))
+            fail('REGISTRY_SCHEMA_INVALID');
+        if (option.valuePattern !== null && (typeof option.valuePattern !== 'string'
+            || option.valuePattern.length > 256 || !option.valuePattern.startsWith('^') || !option.valuePattern.endsWith('$')))
+            fail('REGISTRY_SCHEMA_INVALID');
+        if (option.kind === 'boolean' && option.valuePattern !== null)
+            fail('REGISTRY_SCHEMA_INVALID');
+        return { ...option, id: optionId, aliases };
+    }).sort((a, b) => compareBytes(a.id, b.id));
+    const positionalIds = new Set();
+    const positionals = invocation.positionals.map((raw, index) => {
+        exactKeys(raw, INVOCATION_POSITIONAL_KEYS);
+        const positional = raw;
+        if (typeof positional.id !== 'string' || !/^[a-z][A-Za-z0-9]*$/.test(positional.id) || positionalIds.has(positional.id)
+            || !['string', 'story-ref', 'epic-ref', 'target-ref', 'uiux-part'].includes(positional.kind)
+            || !['one', 'many'].includes(positional.cardinality) || typeof positional.required !== 'boolean'
+            || positional.order !== index)
+            fail('REGISTRY_SCHEMA_INVALID');
+        const positionalId = positional.id;
+        positionalIds.add(positionalId);
+        return { ...positional, id: positionalId };
+    });
+    if (positionals.some((positional, index) => positional.cardinality === 'many' && index !== positionals.length - 1))
+        fail('REGISTRY_SCHEMA_INVALID');
+    return { operation: invocation.operation, options, positionals, terminator: true };
+}
+export function normalizeCommandRegistryDocument(root) {
+    exactKeys(root, ROOT_KEYS);
+    if (root.schemaVersion !== 1 || typeof root.registryVersion !== 'string' || !/^\d+\.\d+\.\d+$/.test(root.registryVersion) || !Array.isArray(root.commands)) {
+        fail('REGISTRY_VERSION_UNSUPPORTED');
+    }
+    const tokens = new Map();
+    const numbers = new Set();
+    const handlerRefs = new Set();
+    const commands = root.commands.map((raw) => {
+        exactKeys(raw, COMMAND_KEYS);
+        const command = raw;
+        if (typeof command.id !== 'string' || normalizeCommandTokenExact(command.id) !== command.id)
+            fail('REGISTRY_COLLISION');
+        if (command.visibility !== 'public' && command.visibility !== 'internal')
+            fail('REGISTRY_SCHEMA_INVALID');
+        if (command.visibility === 'public') {
+            if (!Number.isSafeInteger(command.number) || command.number <= 0 || numbers.has(command.number))
+                fail('REGISTRY_COLLISION');
+            numbers.add(command.number);
+        }
+        else if (command.number !== null)
+            fail('REGISTRY_SCHEMA_INVALID');
+        const aliases = stringArray(command.aliases, true);
+        for (const token of [command.id, ...aliases]) {
+            const normalized = normalizeCommandTokenExact(token);
+            if (!normalized || tokens.has(normalized))
+                fail('REGISTRY_COLLISION');
+            tokens.set(normalized, command.id);
+        }
+        if (typeof command.handlerRef !== 'string' || !/^handler\.[a-z0-9.-]+\.v\d+$/.test(command.handlerRef) || handlerRefs.has(command.handlerRef))
+            fail('REGISTRY_HANDLER_ORPHAN');
+        handlerRefs.add(command.handlerRef);
+        if (command.handlerClass !== 'step' && command.handlerClass !== 'specialized')
+            fail('REGISTRY_SCHEMA_INVALID');
+        if (typeof command.category !== 'string' || typeof command.inputShape !== 'string' || typeof command.mode !== 'string' || typeof command.name !== 'string' || typeof command.stepId !== 'string')
+            fail('REGISTRY_SCHEMA_INVALID');
+        exactKeys(command.description, DESCRIPTION_KEYS);
+        for (const key of DESCRIPTION_KEYS)
+            if (typeof command.description[key] !== 'string')
+                fail('REGISTRY_SCHEMA_INVALID');
+        if (!Array.isArray(command.examples) || command.examples.some((entry) => typeof entry !== 'string'))
+            fail('REGISTRY_SCHEMA_INVALID');
+        const projections = stringArray(command.projections).filter((entry) => PROJECTIONS.includes(entry));
+        if (projections.length !== command.projections.length)
+            fail('REGISTRY_SCHEMA_INVALID');
+        if (!Array.isArray(command.subcommands))
+            fail('REGISTRY_SCHEMA_INVALID');
+        const local = new Set();
+        const subcommands = command.subcommands.map((rawOperation) => {
+            exactKeys(rawOperation, OPERATION_KEYS);
+            const operation = rawOperation;
+            if (typeof operation.id !== 'string' || normalizeCommandTokenExact(operation.id) !== operation.id || local.has(operation.id))
+                fail('REGISTRY_COLLISION');
+            local.add(operation.id);
+            const operationAliases = stringArray(operation.aliases);
+            for (const alias of operationAliases) {
+                if (local.has(alias))
+                    fail('REGISTRY_COLLISION');
+                local.add(alias);
+            }
+            if (operation.visibility !== command.visibility)
+                fail('REGISTRY_SCHEMA_INVALID');
+            if (typeof operation.handlerRef !== 'string' || handlerRefs.has(operation.handlerRef))
+                fail('REGISTRY_HANDLER_ORPHAN');
+            handlerRefs.add(operation.handlerRef);
+            if (operation.handlerClass !== 'step' && operation.handlerClass !== 'specialized')
+                fail('REGISTRY_SCHEMA_INVALID');
+            const operationProjections = stringArray(operation.projections);
+            if (operationProjections.some((entry) => !PROJECTIONS.includes(entry)))
+                fail('REGISTRY_SCHEMA_INVALID');
+            return { ...operation, aliases: operationAliases, projections: operationProjections, policy: validatePolicy(operation.policy), compatibility: validateCompatibility(operation.compatibility) };
+        }).sort((left, right) => compareBytes(left.id, right.id));
+        return {
+            ...command,
+            aliases,
+            projections,
+            policy: validatePolicy(command.policy),
+            compatibility: validateCompatibility(command.compatibility),
+            invocation: validateInvocation(command.invocation),
+            subcommands,
+        };
+    }).sort((left, right) => compareBytes(left.id, right.id));
+    return { schemaVersion: 1, registryVersion: root.registryVersion, commands };
+}
+export function parseCommandRegistryBytes(bytes) {
+    let text = '';
+    try {
+        text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    }
+    catch {
+        fail('REGISTRY_UTF8_INVALID');
+    }
+    const trimmed = text.trim();
+    rejectDuplicateMembers(trimmed);
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        fail('REGISTRY_JSON_INVALID');
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        fail('REGISTRY_SCHEMA_INVALID');
+    return normalizeCommandRegistryDocument(parsed);
+}
+export function commandRegistryChecksum(document) {
+    return createHash('sha256').update(canonicalizeCommandRegistryJcs(document)).digest('hex');
+}