@fps-games/editor 0.2.1-beta.3 → 0.2.1-beta.4

package/node_modules/@fps-games/editor-core/dist/editor-command-system.js

@@ -0,0 +1,1098 @@
+import { EDITOR_COMMAND_SCHEMA_VERSION, } from '@fps-games/editor-protocol';
+import { isAuthorizedCommandComposedRegistration } from './editor-command-composed-authority.js';
+const DEFAULT_MAX_RETAINED_OPERATIONS = 200;
+const DEFAULT_MAX_RESULT_BYTES = 128 * 1024;
+const MAX_SCHEMA_DIAGNOSTICS = 20;
+export function createEditorCommandSystem(options = {}) {
+    const registrations = new Map();
+    const operations = new Map();
+    const idempotency = new Map();
+    const now = options.now ?? Date.now;
+    const createOperationId = options.createOperationId ?? createDefaultOperationIdFactory();
+    const maxRetainedOperations = normalizePositiveInteger(options.maxRetainedOperations, DEFAULT_MAX_RETAINED_OPERATIONS);
+    const maxResultBytes = normalizePositiveInteger(options.maxResultBytes, DEFAULT_MAX_RESULT_BYTES);
+    let catalogRevision = 0;
+    let disposed = false;
+    let executionInterceptor;
+    let executionAuthorityScopeId = '';
+    const readTimestamp = (fallback) => {
+        try {
+            const value = now();
+            return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+        }
+        catch {
+            // Operation timestamps are observability metadata. A broken clock must
+            // never turn an already-committed command into a failed operation.
+            return fallback;
+        }
+    };
+    const system = {
+        get catalogRevision() { return catalogRevision; },
+        get executionAuthorityInstalled() { return executionInterceptor !== undefined; },
+        registerCommand(registration) {
+            assertActive();
+            const normalized = snapshotRegistration(registration);
+            const commandId = normalized.manifest.id;
+            if (registrations.has(commandId)) {
+                throw new Error(`Editor command is already registered: ${commandId}`);
+            }
+            registrations.set(commandId, normalized);
+            catalogRevision += 1;
+            let active = true;
+            return () => {
+                if (!active)
+                    return;
+                active = false;
+                if (registrations.get(commandId) === normalized) {
+                    registrations.delete(commandId);
+                    for (const [scope, record] of idempotency) {
+                        if (record.registration === normalized)
+                            idempotency.delete(scope);
+                    }
+                    catalogRevision += 1;
+                }
+            };
+        },
+        installExecutionInterceptor(interceptor, interceptorOptions = {}) {
+            assertActive();
+            if (typeof interceptor !== 'function')
+                throw new Error('Editor command execution interceptor is required.');
+            if (executionInterceptor)
+                throw new Error('Editor command execution authority is already installed.');
+            executionInterceptor = interceptor;
+            executionAuthorityScopeId = interceptorOptions.scopeId?.trim() ?? '';
+            let active = true;
+            return () => {
+                if (!active)
+                    return;
+                active = false;
+                if (executionInterceptor === interceptor) {
+                    executionInterceptor = undefined;
+                    executionAuthorityScopeId = '';
+                }
+            };
+        },
+        listManifests() {
+            assertActive();
+            return [...registrations.values()]
+                .map(registration => cloneManifest(registration.manifest));
+        },
+        async getCatalog(query = {}) {
+            assertActive();
+            const normalizedQuery = normalizeCatalogQuery(query);
+            const candidates = [...registrations.values()]
+                .filter(registration => !normalizedQuery.target || registration.manifest.target === normalizedQuery.target)
+                .filter(registration => !normalizedQuery.access || registration.manifest.access === normalizedQuery.access)
+                .map(registration => ({
+                registration,
+                score: scoreManifest(registration.manifest, normalizedQuery.text),
+            }))
+                .filter(candidate => candidate.score >= 0)
+                .sort((left, right) => right.score - left.score
+                || left.registration.manifest.id.localeCompare(right.registration.manifest.id))
+                .slice(0, normalizedQuery.limit);
+            const commands = await Promise.all(candidates.map(async ({ registration }) => ({
+                manifest: cloneManifest(registration.manifest),
+                availability: await resolveAvailability(registration),
+            })));
+            return { catalogRevision, commands };
+        },
+        async describeCommand(commandId) {
+            assertActive();
+            const normalizedId = normalizeCommandId(commandId);
+            const registration = registrations.get(normalizedId);
+            if (!registration)
+                return null;
+            return {
+                manifest: cloneManifest(registration.manifest),
+                availability: await resolveAvailability(registration),
+            };
+        },
+        invoke(rawInvocation) {
+            assertActive();
+            const commandId = normalizeCommandId(rawInvocation?.commandId);
+            const registration = registrations.get(commandId);
+            const invocation = snapshotInvocation(rawInvocation, registration?.validateInput === false);
+            const fingerprint = stableStringify({
+                intentCommandId: invocation.intentCommandId ?? null,
+                input: invocation.input === undefined
+                    ? { presence: 'omitted' }
+                    : { presence: 'provided', value: invocation.input },
+                expectedRevision: invocation.expectedRevision ?? null,
+            });
+            const idempotencyScope = invocation.idempotencyKey
+                ? createIdempotencyScope(invocation, executionAuthorityScopeId)
+                : undefined;
+            if (idempotencyScope) {
+                const existing = idempotency.get(idempotencyScope);
+                if (existing) {
+                    if (existing.fingerprint === fingerprint) {
+                        return createHandle(existing, true);
+                    }
+                    const conflict = createOperationRecord(invocation, registration, fingerprint);
+                    operations.set(conflict.snapshot.operationId, conflict);
+                    conflict.completion = observeCompletion(conflict, Promise.resolve(finalizeFailure(conflict, [{
+                            severity: 'error',
+                            source: 'command-system',
+                            code: 'command.idempotencyConflict',
+                            message: `Idempotency key was reused with different input: ${invocation.idempotencyKey}`,
+                        }])));
+                    pruneOperations();
+                    return createHandle(conflict, false);
+                }
+            }
+            const record = createOperationRecord(invocation, registration, fingerprint, idempotencyScope);
+            operations.set(record.snapshot.operationId, record);
+            if (idempotencyScope)
+                idempotency.set(idempotencyScope, record);
+            record.completion = observeCompletion(record, runOperation(record));
+            return createHandle(record, false);
+        },
+        execute(invocation) {
+            return system.invoke(invocation).completion;
+        },
+        getOperation(operationId) {
+            const record = operations.get(operationId);
+            return record ? cloneOperationSnapshot(record.snapshot) : null;
+        },
+        cancelOperation(operationId) {
+            const record = operations.get(operationId);
+            if (!record || record.snapshot.status !== 'accepted')
+                return false;
+            record.controller.abort();
+            return true;
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            registrations.clear();
+            executionInterceptor = undefined;
+            catalogRevision += 1;
+            for (const record of operations.values()) {
+                if (record.snapshot.status === 'accepted')
+                    record.controller.abort();
+            }
+            idempotency.clear();
+        },
+    };
+    return system;
+    function assertActive() {
+        if (disposed)
+            throw new Error('Editor Command System is disposed.');
+    }
+    function createOperationRecord(invocation, registration, fingerprint, idempotencyScope) {
+        const operationId = normalizeOpaqueId(createOperationId(), 'operationId');
+        const snapshot = {
+            operationId,
+            requestId: invocation.requestId,
+            commandId: invocation.commandId,
+            ...(invocation.intentCommandId ? { intentCommandId: invocation.intentCommandId } : {}),
+            status: 'accepted',
+            source: invocation.source,
+            principal: { ...invocation.principal },
+            createdAt: readTimestamp(0),
+            ...(invocation.traceId ? { traceId: invocation.traceId } : {}),
+            ...(invocation.traceStepId ? { traceStepId: invocation.traceStepId } : {}),
+            ...(invocation.transactionId ? { transactionId: invocation.transactionId } : {}),
+        };
+        const record = {
+            controller: new AbortController(),
+            fingerprint,
+            ...(idempotencyScope ? { idempotencyScope } : {}),
+            ...(registration ? { registration } : {}),
+            invocation,
+            snapshot,
+            completion: Promise.resolve(undefined),
+        };
+        return record;
+    }
+    async function runOperation(record) {
+        if (record.controller.signal.aborted)
+            return finalizeCancelled(record);
+        const registration = record.registration;
+        if (!registration) {
+            return finalizeFailure(record, [{
+                    severity: 'error',
+                    source: 'command-system',
+                    code: 'command.notFound',
+                    message: `Editor command is not registered: ${record.invocation.commandId}`,
+                }]);
+        }
+        if (registration.manifest.target === 'authoring'
+            && registration.manifest.access === 'write'
+            && !executionInterceptor) {
+            return finalizeFailure(record, [{
+                    severity: 'error',
+                    source: 'command-system',
+                    code: 'command.authorityUnavailable',
+                    message: 'Editor authoring authority is unavailable.',
+                }]);
+        }
+        try {
+            const context = {
+                ...record.invocation,
+                operationId: record.snapshot.operationId,
+                manifest: cloneManifest(registration.manifest),
+                signal: record.controller.signal,
+                ...(registration.authorityTransaction
+                    ? { authorityTransaction: registration.authorityTransaction }
+                    : {}),
+            };
+            const execute = async (authorityContext) => {
+                const availability = await resolveAvailability(registration, record.controller.signal);
+                if (record.controller.signal.aborted)
+                    return cancelledOutcome(record.invocation.commandId);
+                if (!availability.available)
+                    return { ok: false, diagnostics: availability.reasons };
+                const input = record.invocation.input !== undefined
+                    ? record.invocation.input
+                    : registration.manifest.presentation?.inputMode === 'none' ? {} : null;
+                if (registration.validateInput !== false) {
+                    const diagnostics = validateJsonSchema(input, registration.manifest.inputSchema, '$', 'command.inputInvalid');
+                    if (diagnostics.length)
+                        return { ok: false, diagnostics };
+                }
+                if (record.controller.signal.aborted)
+                    return cancelledOutcome(record.invocation.commandId);
+                record.snapshot = {
+                    ...record.snapshot,
+                    status: 'running',
+                    startedAt: readTimestamp(record.snapshot.createdAt),
+                };
+                const handlerContext = authorityContext === undefined
+                    ? context
+                    : { ...context, authorityContext };
+                const handlerPromise = Promise.resolve(registration.handler(input, handlerContext));
+                const outcome = registration.authorityTransaction === 'composed'
+                    ? await handlerPromise
+                    : await awaitAbortable(handlerPromise, record.controller.signal);
+                if (outcome === ABORTED)
+                    return cancelledOutcome(record.invocation.commandId);
+                if (!outcome.ok)
+                    return { ok: false, diagnostics: normalizeDiagnostics(outcome.diagnostics) };
+                if (registration.validateOutput !== false) {
+                    const diagnostics = validateJsonSchema(outcome.output, registration.manifest.outputSchema, '$', 'command.outputInvalid');
+                    if (diagnostics.length)
+                        return { ok: false, diagnostics };
+                }
+                const diagnostics = outcome.diagnostics?.length
+                    ? normalizeDiagnostics(outcome.diagnostics)
+                    : undefined;
+                return {
+                    ok: true,
+                    output: cloneBoundedResult(outcome.output, maxResultBytes),
+                    ...(diagnostics ? { diagnostics } : {}),
+                };
+            };
+            const outcome = executionInterceptor
+                ? await executionInterceptor(context, execute)
+                : await execute();
+            if (!outcome.ok) {
+                const diagnostics = normalizeDiagnostics(outcome.diagnostics);
+                return diagnostics.some(diagnostic => diagnostic.code === 'command.cancelled')
+                    ? finalizeFailure(record, diagnostics, 'cancelled')
+                    : finalizeFailure(record, diagnostics);
+            }
+            record.snapshot = {
+                ...record.snapshot,
+                status: 'completed',
+                completedAt: readTimestamp(record.snapshot.startedAt ?? record.snapshot.createdAt),
+                output: outcome.output,
+                ...(outcome.diagnostics?.length
+                    ? { diagnostics: [...outcome.diagnostics] }
+                    : {}),
+            };
+            pruneOperations();
+            return cloneOperationSnapshot(record.snapshot);
+        }
+        catch (error) {
+            if (record.controller.signal.aborted)
+                return finalizeCancelled(record);
+            return finalizeFailure(record, [{
+                    severity: 'error',
+                    source: 'command-system',
+                    code: error instanceof EditorCommandResultTooLargeError
+                        ? 'command.resultTooLarge'
+                        : 'command.exception',
+                    message: error instanceof Error ? error.message : String(error),
+                }]);
+        }
+    }
+    function finalizeCancelled(record) {
+        return finalizeFailure(record, [{
+                severity: 'warning',
+                source: 'command-system',
+                code: 'command.cancelled',
+                message: `Editor command was cancelled: ${record.invocation.commandId}`,
+            }], 'cancelled');
+    }
+    function finalizeFailure(record, diagnostics, status = 'failed') {
+        record.snapshot = {
+            ...record.snapshot,
+            status,
+            completedAt: readTimestamp(record.snapshot.startedAt ?? record.snapshot.createdAt),
+            diagnostics: normalizeDiagnostics(diagnostics),
+        };
+        pruneOperations();
+        return cloneOperationSnapshot(record.snapshot);
+    }
+    async function observeCompletion(record, completion) {
+        const operation = await completion;
+        try {
+            options.onOperationSettled?.({
+                invocation: snapshotInvocation(record.invocation, record.registration?.validateInput === false),
+                ...(record.registration ? { manifest: cloneManifest(record.registration.manifest) } : {}),
+                operation: structuredClone(operation),
+            });
+        }
+        catch {
+            // Observability is bounded best-effort metadata and never changes command semantics.
+        }
+        return operation;
+    }
+    function pruneOperations() {
+        if (operations.size <= maxRetainedOperations)
+            return;
+        for (const [operationId, record] of operations) {
+            if (!isTerminalStatus(record.snapshot.status))
+                continue;
+            operations.delete(operationId);
+            // Operation query retention is bounded, but idempotency lives for the
+            // service instance. A late retry must not execute again merely because
+            // its operation snapshot aged out of the query window.
+            if (operations.size <= maxRetainedOperations)
+                break;
+        }
+    }
+}
+function snapshotRegistration(registration) {
+    if (!registration || typeof registration !== 'object') {
+        throw new Error('Editor command registration must be an object.');
+    }
+    if (typeof registration.handler !== 'function') {
+        throw new Error('Editor command handler is required.');
+    }
+    if (registration.available !== undefined && typeof registration.available !== 'function') {
+        throw new Error('Editor command availability must be a function.');
+    }
+    if (registration.authorityTransaction !== undefined
+        && registration.authorityTransaction !== 'isolated'
+        && registration.authorityTransaction !== 'composed') {
+        throw new Error('Editor command authority transaction mode is invalid.');
+    }
+    if (registration.authorityTransaction === 'composed'
+        && !isAuthorizedCommandComposedRegistration(registration)) {
+        throw new Error('Composed Editor command authority is reserved for the owning Authoring Host.');
+    }
+    return {
+        manifest: snapshotEditorCommandManifest(registration.manifest),
+        ...(registration.available ? { available: registration.available } : {}),
+        handler: registration.handler,
+        ...(registration.validateInput === false ? { validateInput: false } : {}),
+        ...(registration.validateOutput === false ? { validateOutput: false } : {}),
+        ...(registration.authorityTransaction ? { authorityTransaction: registration.authorityTransaction } : {}),
+    };
+}
+export function snapshotEditorCommandManifest(manifest) {
+    if (!manifest || typeof manifest !== 'object')
+        throw new Error('Editor command manifest is required.');
+    if (manifest.schemaVersion !== EDITOR_COMMAND_SCHEMA_VERSION) {
+        throw new Error(`Unsupported Editor command schema version: ${String(manifest.schemaVersion)}`);
+    }
+    const id = normalizeCommandId(manifest.id);
+    if (!Number.isInteger(manifest.version) || manifest.version <= 0) {
+        throw new Error(`Editor command version must be a positive integer: ${id}`);
+    }
+    const title = normalizeRequiredText(manifest.title, `Editor command title is required: ${id}`);
+    const targets = new Set(['workspace-service', 'tooling', 'authoring', 'view', 'renderer']);
+    if (!targets.has(manifest.target))
+        throw new Error(`Editor command target is invalid: ${id}`);
+    if (manifest.access !== 'read' && manifest.access !== 'write') {
+        throw new Error(`Editor command access is invalid: ${id}`);
+    }
+    const stabilities = new Set(['experimental', 'stable', 'deprecated']);
+    if (!stabilities.has(manifest.stability))
+        throw new Error(`Editor command stability is invalid: ${id}`);
+    if (!manifest.effects || typeof manifest.effects !== 'object') {
+        throw new Error(`Editor command effects are required: ${id}`);
+    }
+    const persistence = new Set(['none', 'view', 'authoring', 'filesystem']);
+    if (!persistence.has(manifest.effects.persistence)) {
+        throw new Error(`Editor command persistence is invalid: ${id}`);
+    }
+    if (typeof manifest.effects.undoable !== 'boolean' || typeof manifest.effects.idempotent !== 'boolean') {
+        throw new Error(`Editor command effects flags are invalid: ${id}`);
+    }
+    const description = normalizeOptionalText(manifest.description);
+    const snapshot = {
+        schemaVersion: EDITOR_COMMAND_SCHEMA_VERSION,
+        id,
+        version: manifest.version,
+        title,
+        ...(description ? { description } : {}),
+        target: manifest.target,
+        access: manifest.access,
+        stability: manifest.stability,
+        inputSchema: snapshotJsonSchema(manifest.inputSchema, `${id}.inputSchema`),
+        outputSchema: snapshotJsonSchema(manifest.outputSchema, `${id}.outputSchema`),
+        ...(manifest.requires ? { requires: snapshotRequirements(manifest.requires, id) } : {}),
+        effects: Object.freeze({ ...manifest.effects }),
+        ...(manifest.presentation ? { presentation: snapshotPresentation(manifest.presentation, id, manifest.inputSchema) } : {}),
+    };
+    return Object.freeze(snapshot);
+}
+function snapshotRequirements(value, commandId) {
+    for (const key of ['editorReady', 'viewAttached', 'rendererAttached']) {
+        if (value[key] !== undefined && typeof value[key] !== 'boolean') {
+            throw new Error(`Editor command requirement ${key} is invalid: ${commandId}`);
+        }
+    }
+    return Object.freeze({
+        ...(value.editorReady !== undefined ? { editorReady: value.editorReady } : {}),
+        ...(value.viewAttached !== undefined ? { viewAttached: value.viewAttached } : {}),
+        ...(value.rendererAttached !== undefined ? { rendererAttached: value.rendererAttached } : {}),
+        ...(value.activeScope ? { activeScope: Object.freeze(snapshotStringList(value.activeScope, commandId)) } : {}),
+        ...(value.permissions ? { permissions: Object.freeze(snapshotStringList(value.permissions, commandId)) } : {}),
+    });
+}
+function snapshotPresentation(value, commandId, inputSchema) {
+    const category = normalizeOptionalText(value.category);
+    const shortcut = normalizeOptionalText(value.shortcut);
+    const inputModes = new Set(['none', 'inline-json', 'schema-form']);
+    if (value.inputMode !== undefined && !inputModes.has(value.inputMode)) {
+        throw new Error(`Editor command presentation input mode is invalid: ${commandId}`);
+    }
+    const menu = value.menu
+        ? Object.freeze({
+            path: Object.freeze(snapshotStringList(value.menu.path, commandId)),
+            ...(normalizeOptionalText(value.menu.group) ? { group: value.menu.group.trim() } : {}),
+            ...(value.menu.order !== undefined ? { order: normalizeFiniteNumber(value.menu.order, `${commandId}.menu.order`) } : {}),
+        })
+        : undefined;
+    const selectionBinding = value.selectionBinding
+        ? snapshotSelectionBinding(value.selectionBinding, commandId, inputSchema)
+        : undefined;
+    return Object.freeze({
+        ...(category ? { category } : {}),
+        ...(value.aliases ? { aliases: Object.freeze(snapshotStringList(value.aliases, commandId)) } : {}),
+        ...(value.keywords ? { keywords: Object.freeze(snapshotStringList(value.keywords, commandId)) } : {}),
+        ...(value.examples ? { examples: Object.freeze(snapshotStringList(value.examples, commandId)) } : {}),
+        ...(shortcut ? { shortcut } : {}),
+        ...(menu ? { menu } : {}),
+        ...(value.inputMode ? { inputMode: value.inputMode } : {}),
+        ...(selectionBinding ? { selectionBinding } : {}),
+    });
+}
+function snapshotSelectionBinding(value, commandId, inputSchema) {
+    const activeId = normalizeOptionalText(value.activeId);
+    const selectedIds = normalizeOptionalText(value.selectedIds);
+    if (!activeId && !selectedIds)
+        throw new Error(`Editor command selection binding is empty: ${commandId}`);
+    const properties = inputSchema.properties && typeof inputSchema.properties === 'object'
+        ? inputSchema.properties
+        : {};
+    if (activeId && properties[activeId]?.type !== 'string') {
+        throw new Error(`Editor command active selection binding must target a string property: ${commandId}.${activeId}`);
+    }
+    if (selectedIds && (properties[selectedIds]?.type !== 'array' || properties[selectedIds]?.items?.type !== 'string')) {
+        throw new Error(`Editor command multi-selection binding must target a string array property: ${commandId}.${selectedIds}`);
+    }
+    return Object.freeze({ ...(activeId ? { activeId } : {}), ...(selectedIds ? { selectedIds } : {}) });
+}
+function snapshotInvocation(invocation, allowUnvalidatedInput = false) {
+    if (!invocation || typeof invocation !== 'object')
+        throw new Error('Editor command invocation is required.');
+    const commandId = normalizeCommandId(invocation.commandId);
+    const intentCommandId = invocation.intentCommandId === undefined
+        ? undefined
+        : normalizeCommandId(invocation.intentCommandId);
+    const requestId = normalizeOpaqueId(invocation.requestId, 'requestId');
+    if (!invocation.principal || typeof invocation.principal !== 'object') {
+        throw new Error('Editor command principal is required.');
+    }
+    const principalType = normalizeRequiredText(invocation.principal.type, 'Editor command principal type is required.');
+    const source = normalizeRequiredText(invocation.source, 'Editor command source is required.');
+    const principalId = normalizeOptionalText(invocation.principal.id);
+    const idempotencyKey = normalizeOptionalText(invocation.idempotencyKey);
+    const traceId = normalizeOptionalText(invocation.traceId);
+    const traceStepId = normalizeOptionalText(invocation.traceStepId);
+    const transactionId = normalizeOptionalText(invocation.transactionId);
+    const clientId = normalizeOptionalText(invocation.clientId);
+    return Object.freeze({
+        commandId,
+        ...(intentCommandId ? { intentCommandId } : {}),
+        ...(invocation.input !== undefined ? {
+            input: (allowUnvalidatedInput
+                ? cloneUnvalidatedInput(invocation.input, '$input')
+                : cloneJsonValue(invocation.input, '$input')),
+        } : {}),
+        requestId,
+        ...(idempotencyKey ? { idempotencyKey } : {}),
+        principal: Object.freeze({ type: principalType, ...(principalId ? { id: principalId } : {}) }),
+        source,
+        ...(invocation.expectedRevision ? {
+            expectedRevision: Object.freeze(snapshotExpectedRevision(invocation.expectedRevision)),
+        } : {}),
+        ...(traceId ? { traceId } : {}),
+        ...(traceStepId ? { traceStepId } : {}),
+        ...(transactionId ? { transactionId } : {}),
+        ...(clientId ? { clientId } : {}),
+    });
+}
+function snapshotExpectedRevision(value) {
+    const result = {};
+    if (value.serviceInstanceId !== undefined) {
+        const serviceInstanceId = normalizeRequiredText(value.serviceInstanceId, 'expectedRevision.serviceInstanceId');
+        result.serviceInstanceId = serviceInstanceId;
+    }
+    for (const key of ['document', 'scope', 'catalog']) {
+        const revision = value[key];
+        if (revision === undefined)
+            continue;
+        if (!Number.isSafeInteger(revision) || revision < 0) {
+            throw new Error(`Editor command expected revision is invalid: ${key}`);
+        }
+        result[key] = revision;
+    }
+    return result;
+}
+const ABORTED = Symbol('editor-command-aborted');
+async function awaitAbortable(promise, signal) {
+    if (signal.aborted)
+        return ABORTED;
+    return new Promise((resolve, reject) => {
+        const onAbort = () => resolve(ABORTED);
+        signal.addEventListener('abort', onAbort, { once: true });
+        promise.then(value => {
+            signal.removeEventListener('abort', onAbort);
+            resolve(value);
+        }, error => {
+            signal.removeEventListener('abort', onAbort);
+            reject(error);
+        });
+    });
+}
+function cancelledOutcome(commandId) {
+    return {
+        ok: false,
+        diagnostics: [{
+                severity: 'warning',
+                source: 'command-system',
+                code: 'command.cancelled',
+                message: `Editor command was cancelled: ${commandId}`,
+            }],
+    };
+}
+async function resolveAvailability(registration, signal) {
+    if (!registration.available)
+        return { available: true, reasons: [] };
+    try {
+        const pending = Promise.resolve(registration.available());
+        const value = signal ? await awaitAbortable(pending, signal) : await pending;
+        if (value === ABORTED)
+            return unavailable('Editor command was cancelled.', 'command.cancelled');
+        if (value === true)
+            return { available: true, reasons: [] };
+        if (value === false)
+            return unavailable('Editor command is unavailable.');
+        if (typeof value === 'string')
+            return unavailable(value.trim() || 'Editor command is unavailable.');
+        if (!value || typeof value !== 'object' || typeof value.available !== 'boolean') {
+            return unavailable('Editor command availability returned an invalid result.', 'command.availabilityInvalid');
+        }
+        return {
+            available: value.available,
+            reasons: value.available || value.reasons?.length
+                ? normalizeDiagnostics(value.reasons ?? [])
+                : unavailable('Editor command is unavailable.').reasons,
+        };
+    }
+    catch (error) {
+        return unavailable(error instanceof Error ? error.message : String(error), 'command.availabilityException');
+    }
+}
+function unavailable(message, code = 'command.unavailable') {
+    return {
+        available: false,
+        reasons: [{ severity: 'error', source: 'command-system', code, message }],
+    };
+}
+function validateJsonSchema(value, schema, path, code) {
+    const issues = [];
+    validateSchemaNode(value, schema, path, issues);
+    return issues.slice(0, MAX_SCHEMA_DIAGNOSTICS).map(message => ({
+        severity: 'error',
+        source: 'command-system',
+        code,
+        message,
+        path: message.split(':', 1)[0],
+    }));
+}
+function snapshotJsonSchema(value, path) {
+    const schema = cloneJsonObject(value, path);
+    assertJsonSchemaDefinition(schema, path);
+    return schema;
+}
+function assertJsonSchemaDefinition(rawSchema, path) {
+    if (typeof rawSchema === 'boolean')
+        return;
+    if (!isPlainObject(rawSchema))
+        throw new Error(`Editor command JSON Schema is invalid at ${path}.`);
+    const schema = rawSchema;
+    const jsonTypes = new Set(['null', 'object', 'array', 'string', 'number', 'integer', 'boolean']);
+    if ('type' in schema) {
+        const types = typeof schema.type === 'string' ? [schema.type] : schema.type;
+        if (!Array.isArray(types) || types.length === 0
+            || types.some(type => typeof type !== 'string' || !jsonTypes.has(type))
+            || new Set(types).size !== types.length) {
+            throw new Error(`Editor command JSON Schema type is invalid at ${path}.type.`);
+        }
+    }
+    if ('required' in schema) {
+        if (!Array.isArray(schema.required)
+            || schema.required.some(key => typeof key !== 'string' || key.length === 0)
+            || new Set(schema.required).size !== schema.required.length) {
+            throw new Error(`Editor command JSON Schema required is invalid at ${path}.required.`);
+        }
+    }
+    if ('properties' in schema) {
+        if (!isPlainObject(schema.properties)) {
+            throw new Error(`Editor command JSON Schema properties is invalid at ${path}.properties.`);
+        }
+        for (const [key, child] of Object.entries(schema.properties)) {
+            assertJsonSchemaDefinition(child, `${path}.properties.${key}`);
+        }
+    }
+    if ('additionalProperties' in schema
+        && typeof schema.additionalProperties !== 'boolean'
+        && !isPlainObject(schema.additionalProperties)) {
+        throw new Error(`Editor command JSON Schema additionalProperties is invalid at ${path}.additionalProperties.`);
+    }
+    if (isPlainObject(schema.additionalProperties)) {
+        assertJsonSchemaDefinition(schema.additionalProperties, `${path}.additionalProperties`);
+    }
+    if ('items' in schema)
+        assertJsonSchemaDefinition(schema.items, `${path}.items`);
+    for (const keyword of ['allOf', 'anyOf', 'oneOf']) {
+        if (!(keyword in schema))
+            continue;
+        const children = schema[keyword];
+        if (!Array.isArray(children) || children.length === 0) {
+            throw new Error(`Editor command JSON Schema ${keyword} is invalid at ${path}.${keyword}.`);
+        }
+        children.forEach((child, index) => assertJsonSchemaDefinition(child, `${path}.${keyword}[${index}]`));
+    }
+    if ('not' in schema)
+        assertJsonSchemaDefinition(schema.not, `${path}.not`);
+    if ('enum' in schema && (!Array.isArray(schema.enum) || schema.enum.length === 0)) {
+        throw new Error(`Editor command JSON Schema enum is invalid at ${path}.enum.`);
+    }
+    for (const keyword of ['minLength', 'maxLength', 'minItems', 'maxItems', 'minProperties', 'maxProperties']) {
+        if (keyword in schema && (!Number.isSafeInteger(schema[keyword]) || schema[keyword] < 0)) {
+            throw new Error(`Editor command JSON Schema ${keyword} is invalid at ${path}.${keyword}.`);
+        }
+    }
+    for (const keyword of ['minimum', 'maximum', 'exclusiveMinimum', 'exclusiveMaximum']) {
+        if (keyword in schema && (typeof schema[keyword] !== 'number' || !Number.isFinite(schema[keyword]))) {
+            throw new Error(`Editor command JSON Schema ${keyword} is invalid at ${path}.${keyword}.`);
+        }
+    }
+    if ('multipleOf' in schema
+        && (typeof schema.multipleOf !== 'number' || !Number.isFinite(schema.multipleOf) || schema.multipleOf <= 0)) {
+        throw new Error(`Editor command JSON Schema multipleOf is invalid at ${path}.multipleOf.`);
+    }
+    if ('uniqueItems' in schema && typeof schema.uniqueItems !== 'boolean') {
+        throw new Error(`Editor command JSON Schema uniqueItems is invalid at ${path}.uniqueItems.`);
+    }
+    if ('pattern' in schema) {
+        if (typeof schema.pattern !== 'string') {
+            throw new Error(`Editor command JSON Schema pattern is invalid at ${path}.pattern.`);
+        }
+        try {
+            new RegExp(schema.pattern);
+        }
+        catch {
+            throw new Error(`Editor command JSON Schema pattern is invalid at ${path}.pattern.`);
+        }
+    }
+}
+function validateSchemaNode(value, rawSchema, path, issues) {
+    if (issues.length >= MAX_SCHEMA_DIAGNOSTICS)
+        return;
+    if (rawSchema === true || rawSchema === undefined)
+        return;
+    if (rawSchema === false) {
+        issues.push(`${path}: value is not allowed`);
+        return;
+    }
+    if (!rawSchema || typeof rawSchema !== 'object' || Array.isArray(rawSchema)) {
+        issues.push(`${path}: schema is invalid`);
+        return;
+    }
+    const schema = rawSchema;
+    if (Array.isArray(schema.allOf)) {
+        for (const child of schema.allOf)
+            validateSchemaNode(value, child, path, issues);
+    }
+    if (Array.isArray(schema.anyOf)) {
+        const matched = schema.anyOf.some(child => {
+            const childIssues = [];
+            validateSchemaNode(value, child, path, childIssues);
+            return childIssues.length === 0;
+        });
+        if (!matched)
+            issues.push(`${path}: value does not match any allowed schema`);
+    }
+    if (Array.isArray(schema.oneOf)) {
+        const matches = schema.oneOf.filter(child => {
+            const childIssues = [];
+            validateSchemaNode(value, child, path, childIssues);
+            return childIssues.length === 0;
+        }).length;
+        if (matches !== 1)
+            issues.push(`${path}: value must match exactly one allowed schema`);
+    }
+    if (schema.not !== undefined) {
+        const childIssues = [];
+        validateSchemaNode(value, schema.not, path, childIssues);
+        if (childIssues.length === 0)
+            issues.push(`${path}: value matches a disallowed schema`);
+    }
+    if (Array.isArray(schema.enum) && !schema.enum.some(entry => deepJsonEqual(entry, value))) {
+        issues.push(`${path}: value is not in the allowed enum`);
+        return;
+    }
+    if ('const' in schema && !deepJsonEqual(schema.const, value)) {
+        issues.push(`${path}: value does not match the required constant`);
+        return;
+    }
+    const allowedTypes = typeof schema.type === 'string'
+        ? [schema.type]
+        : Array.isArray(schema.type)
+            ? schema.type.filter(type => typeof type === 'string')
+            : [];
+    if (allowedTypes.length && !allowedTypes.some(type => matchesJsonType(value, type))) {
+        issues.push(`${path}: expected ${allowedTypes.join(' or ')}`);
+        return;
+    }
+    if (typeof value === 'string') {
+        if (typeof schema.minLength === 'number' && value.length < schema.minLength) {
+            issues.push(`${path}: string is shorter than ${schema.minLength}`);
+        }
+        if (typeof schema.maxLength === 'number' && value.length > schema.maxLength) {
+            issues.push(`${path}: string is longer than ${schema.maxLength}`);
+        }
+        if (typeof schema.pattern === 'string') {
+            try {
+                if (!new RegExp(schema.pattern).test(value))
+                    issues.push(`${path}: string does not match pattern`);
+            }
+            catch {
+                issues.push(`${path}: schema pattern is invalid`);
+            }
+        }
+    }
+    if (typeof value === 'number') {
+        if (typeof schema.minimum === 'number' && value < schema.minimum)
+            issues.push(`${path}: number is below minimum`);
+        if (typeof schema.maximum === 'number' && value > schema.maximum)
+            issues.push(`${path}: number is above maximum`);
+        if (typeof schema.exclusiveMinimum === 'number' && value <= schema.exclusiveMinimum)
+            issues.push(`${path}: number is not above exclusive minimum`);
+        if (typeof schema.exclusiveMaximum === 'number' && value >= schema.exclusiveMaximum)
+            issues.push(`${path}: number is not below exclusive maximum`);
+        if (typeof schema.multipleOf === 'number' && !isJsonNumberMultipleOf(value, schema.multipleOf)) {
+            issues.push(`${path}: number is not a multiple of ${schema.multipleOf}`);
+        }
+    }
+    if (Array.isArray(value)) {
+        if (typeof schema.minItems === 'number' && value.length < schema.minItems)
+            issues.push(`${path}: array has too few items`);
+        if (typeof schema.maxItems === 'number' && value.length > schema.maxItems)
+            issues.push(`${path}: array has too many items`);
+        if (schema.uniqueItems === true && value.some((entry, index) => value.slice(0, index).some(previous => deepJsonEqual(previous, entry)))) {
+            issues.push(`${path}: array items are not unique`);
+        }
+        if (schema.items !== undefined) {
+            value.forEach((entry, index) => validateSchemaNode(entry, schema.items, `${path}[${index}]`, issues));
+        }
+    }
+    if (isPlainObject(value)) {
+        const properties = isPlainObject(schema.properties) ? schema.properties : {};
+        const required = Array.isArray(schema.required)
+            ? schema.required.filter(key => typeof key === 'string')
+            : [];
+        if (typeof schema.minProperties === 'number' && Object.keys(value).length < schema.minProperties) {
+            issues.push(`${path}: object has too few properties`);
+        }
+        if (typeof schema.maxProperties === 'number' && Object.keys(value).length > schema.maxProperties) {
+            issues.push(`${path}: object has too many properties`);
+        }
+        for (const key of required) {
+            if (!hasOwn(value, key))
+                issues.push(`${path}.${key}: required property is missing`);
+        }
+        for (const [key, child] of Object.entries(value)) {
+            if (hasOwn(properties, key)) {
+                validateSchemaNode(child, properties[key], `${path}.${key}`, issues);
+            }
+            else if (schema.additionalProperties === false) {
+                issues.push(`${path}.${key}: additional property is not allowed`);
+            }
+            else if (isPlainObject(schema.additionalProperties)) {
+                validateSchemaNode(child, schema.additionalProperties, `${path}.${key}`, issues);
+            }
+        }
+    }
+}
+function matchesJsonType(value, type) {
+    switch (type) {
+        case 'null': return value === null;
+        case 'object': return isPlainObject(value);
+        case 'array': return Array.isArray(value);
+        case 'string': return typeof value === 'string';
+        case 'number': return typeof value === 'number' && Number.isFinite(value);
+        case 'integer': return typeof value === 'number' && Number.isSafeInteger(value);
+        case 'boolean': return typeof value === 'boolean';
+        default: return false;
+    }
+}
+function hasOwn(value, key) {
+    return Object.prototype.hasOwnProperty.call(value, key);
+}
+function isJsonNumberMultipleOf(value, multiple) {
+    const left = toDecimalInteger(value);
+    const right = toDecimalInteger(multiple);
+    const numerator = left.coefficient * (10n ** BigInt(right.scale));
+    const denominator = right.coefficient * (10n ** BigInt(left.scale));
+    return denominator !== 0n && numerator % denominator === 0n;
+}
+function toDecimalInteger(value) {
+    const text = value.toString().toLowerCase();
+    const [mantissa, exponentText] = text.split('e');
+    const exponent = exponentText === undefined ? 0 : Number(exponentText);
+    const negative = mantissa.startsWith('-');
+    const unsigned = negative ? mantissa.slice(1) : mantissa;
+    const [integerPart, fractionalPart = ''] = unsigned.split('.');
+    const digits = `${integerPart}${fractionalPart}`.replace(/^0+(?=\d)/, '') || '0';
+    let coefficient = BigInt(digits);
+    if (negative)
+        coefficient = -coefficient;
+    const scale = fractionalPart.length - exponent;
+    if (scale >= 0)
+        return { coefficient, scale };
+    return { coefficient: coefficient * (10n ** BigInt(-scale)), scale: 0 };
+}
+function normalizeDiagnostics(diagnostics) {
+    if (!Array.isArray(diagnostics))
+        return unavailable('Command diagnostics are invalid.').reasons;
+    return diagnostics.slice(0, MAX_SCHEMA_DIAGNOSTICS).map((diagnostic, index) => {
+        if (!diagnostic || typeof diagnostic !== 'object') {
+            return {
+                severity: 'error', source: 'command-system', code: 'command.diagnosticInvalid',
+                message: `Command diagnostic is invalid at index ${index}.`,
+            };
+        }
+        return {
+            severity: diagnostic.severity === 'info' || diagnostic.severity === 'warning'
+                ? diagnostic.severity
+                : 'error',
+            source: normalizeOptionalText(diagnostic.source) ?? 'command',
+            code: normalizeOptionalText(diagnostic.code) ?? 'command.failed',
+            message: normalizeOptionalText(diagnostic.message) ?? 'Editor command failed.',
+            ...(normalizeOptionalText(diagnostic.path) ? { path: diagnostic.path.trim() } : {}),
+            ...(normalizeOptionalText(diagnostic.objectId) ? { objectId: diagnostic.objectId.trim() } : {}),
+            ...(diagnostic.details ? { details: cloneJsonObject(diagnostic.details, '$diagnostic.details') } : {}),
+        };
+    });
+}
+function normalizeCatalogQuery(query) {
+    const text = normalizeOptionalText(query.text)?.toLocaleLowerCase();
+    const limit = query.limit === undefined ? 200 : query.limit;
+    if (!Number.isInteger(limit) || limit < 1 || limit > 1000) {
+        throw new Error('Editor command catalog limit must be an integer between 1 and 1000.');
+    }
+    return { ...query, ...(text ? { text } : {}), limit };
+}
+function scoreManifest(manifest, query) {
+    if (!query)
+        return 0;
+    const id = manifest.id.toLocaleLowerCase();
+    const title = manifest.title.toLocaleLowerCase();
+    const aliases = manifest.presentation?.aliases?.map(value => value.toLocaleLowerCase()) ?? [];
+    const keywords = manifest.presentation?.keywords?.map(value => value.toLocaleLowerCase()) ?? [];
+    if (id === query)
+        return 100;
+    if (aliases.includes(query))
+        return 90;
+    if (id.startsWith(query))
+        return 80;
+    if (title.startsWith(query))
+        return 70;
+    if (id.includes(query))
+        return 60;
+    if (title.includes(query))
+        return 50;
+    if (aliases.some(value => value.includes(query)))
+        return 40;
+    if (keywords.some(value => value.includes(query)))
+        return 30;
+    return manifest.description?.toLocaleLowerCase().includes(query) ? 10 : -1;
+}
+function createHandle(record, reused) {
+    return {
+        operationId: record.snapshot.operationId,
+        requestId: record.snapshot.requestId,
+        reused,
+        completion: record.completion,
+    };
+}
+function createIdempotencyScope(invocation, authorityScopeId) {
+    return stableStringify([
+        authorityScopeId,
+        invocation.principal.type,
+        invocation.principal.id ?? '',
+        invocation.source,
+        invocation.commandId,
+        invocation.idempotencyKey ?? '',
+    ]);
+}
+function cloneManifest(manifest) {
+    return cloneJsonValue(manifest, '$manifest');
+}
+function cloneOperationSnapshot(snapshot) {
+    return cloneJsonValue(snapshot, '$operation');
+}
+function cloneBoundedResult(value, maxBytes) {
+    if (value === undefined)
+        throw new Error('Editor command result is not JSON-serializable: undefined.');
+    let json;
+    try {
+        json = JSON.stringify(value);
+    }
+    catch (error) {
+        throw new Error(`Editor command result is not serializable: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (json === undefined)
+        throw new Error('Editor command result is not serializable.');
+    const byteLength = new TextEncoder().encode(json).byteLength;
+    if (byteLength > maxBytes) {
+        throw new EditorCommandResultTooLargeError(`Editor command result exceeds the ${maxBytes} byte limit (${byteLength} bytes).`);
+    }
+    return JSON.parse(json);
+}
+class EditorCommandResultTooLargeError extends Error {
+}
+function cloneJsonObject(value, path) {
+    const cloned = cloneJsonValue(value, path);
+    if (!isPlainObject(cloned))
+        throw new Error(`Editor command JSON object is required at ${path}.`);
+    return Object.freeze(cloned);
+}
+function cloneJsonValue(value, path) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (Array.isArray(value))
+        return Object.freeze(value.map((entry, index) => cloneJsonValue(entry, `${path}[${index}]`)));
+    if (!isPlainObject(value))
+        throw new Error(`Editor command value must be JSON-compatible at ${path}.`);
+    const result = Object.create(null);
+    for (const [key, entry] of Object.entries(value)) {
+        if (entry === undefined)
+            continue;
+        result[key] = cloneJsonValue(entry, `${path}.${key}`);
+    }
+    return Object.freeze(result);
+}
+function cloneUnvalidatedInput(value, path) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number')
+        return value;
+    if (Array.isArray(value))
+        return Object.freeze(value.map((entry, index) => cloneUnvalidatedInput(entry, `${path}[${index}]`)));
+    if (!isPlainObject(value))
+        throw new Error(`Unvalidated Editor command input must contain plain values at ${path}.`);
+    const result = Object.create(null);
+    for (const [key, entry] of Object.entries(value)) {
+        if (entry === undefined)
+            continue;
+        result[key] = cloneUnvalidatedInput(entry, `${path}.${key}`);
+    }
+    return Object.freeze(result);
+}
+function isPlainObject(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function deepJsonEqual(left, right) {
+    try {
+        return stableStringify(left) === stableStringify(right);
+    }
+    catch {
+        return false;
+    }
+}
+function stableStringify(value) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return JSON.stringify(value);
+    if (typeof value === 'number') {
+        if (Number.isFinite(value))
+            return JSON.stringify(value);
+        if (Number.isNaN(value))
+            return '"__non_json_finite_nan__"';
+        return value > 0 ? '"__non_json_finite_infinity__"' : '"__non_json_finite_negative_infinity__"';
+    }
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(',')}]`;
+    if (!isPlainObject(value))
+        throw new Error('Editor command idempotency input must be JSON-compatible.');
+    return `{${Object.keys(value).sort().filter(key => value[key] !== undefined).map(key => (`${JSON.stringify(key)}:${stableStringify(value[key])}`)).join(',')}}`;
+}
+function snapshotStringList(value, commandId) {
+    if (!Array.isArray(value))
+        throw new Error(`Editor command string list is invalid: ${commandId}`);
+    return [...new Set(value.map(entry => normalizeRequiredText(entry, `Editor command string list contains an empty value: ${commandId}`)))];
+}
+function normalizeCommandId(value) {
+    const id = normalizeRequiredText(value, 'Editor command id is required.');
+    if (id.length > 160 || /\s/.test(id))
+        throw new Error(`Editor command id is invalid: ${id}`);
+    return id;
+}
+function normalizeOpaqueId(value, label) {
+    const id = normalizeRequiredText(value, `Editor command ${label} is required.`);
+    if (id.length > 256)
+        throw new Error(`Editor command ${label} is too long.`);
+    return id;
+}
+function normalizeRequiredText(value, message) {
+    if (typeof value !== 'string' || !value.trim())
+        throw new Error(message);
+    return value.trim();
+}
+function normalizeOptionalText(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+function normalizeFiniteNumber(value, path) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw new Error(`Editor command number is invalid: ${path}`);
+    }
+    return value;
+}
+function normalizePositiveInteger(value, fallback) {
+    return Number.isInteger(value) && value > 0 ? value : fallback;
+}
+function isTerminalStatus(status) {
+    return status === 'completed' || status === 'failed' || status === 'cancelled';
+}
+function createDefaultOperationIdFactory() {
+    let sequence = 0;
+    return () => `editor-command-${Date.now().toString(36)}-${(++sequence).toString(36)}`;
+}
+//# sourceMappingURL=editor-command-system.js.map