@jangts/agent-core 0.1.1 → 0.2.1

package/dist/esm/kits/intents/scopes.d.ts

@@ -1,16 +1,50 @@
+/**
+ * Intents Kit: an ordered, sealable registry of scope declarations and their aliases.
+ *
+ * Place in the package: part of the `intents` Kit. Categories, extra fields and intent
+ * acceptance policy are App configuration; this class owns validation, alias normalization,
+ * relationship lookups and sealing.
+ *
+ * Exports: `ScopeRegistry`, `createScopeRegistry`, and the scope registry types.
+ */
 import type { ScopeDefinition, ScopeDescription, ScopeRegistryPolicy, RegisteredScope, RegisteredScopeEvidence } from '../../structs/kits/intents/scopes.js';
-/** Generic scope relationships; categories, intent policy and extra fields belong to the host. */
+/**
+ * Generic scope relationships; categories, intent policy and extra fields belong to the host.
+ *
+ * A scope is addressable by its id or by any of its aliases; aliases resolve to the declaring
+ * scope, and a name may be claimed only once across both namespaces.
+ */
 export declare class ScopeRegistry<Definition extends ScopeDefinition = ScopeDefinition> {
+    /** Create and seal a complete scope catalog in one call. */
     static readonly create: typeof createScopeRegistry;
     private readonly byId;
     private readonly sources;
     private readonly aliases;
     private sealed;
     private readonly policy;
+    /**
+     * @param policy - Optional id pattern, categories, required-binding switches, intent
+     *   acceptance override, error wording and assertion hook; lists are copied on construction.
+     */
     constructor(policy?: ScopeRegistryPolicy<Definition>);
+    /**
+     * Validate, freeze and add one scope together with its aliases.
+     *
+     * Every name is checked for conflicts before any of them is stored, so a rejected scope
+     * leaves no partial alias entry behind.
+     *
+     * @param input - Scope declaration; the raw object is retained for `acceptsIntent` overrides
+     *   while the compiled copy serves lookups.
+     * @returns This registry, for chaining.
+     * @throws A configured error for a sealed registry, an invalid name/description/category,
+     *   a missing required binding, duplicate intent ids or an already-claimed name.
+     */
     register(input: Definition): this;
+    /** Register every scope in iteration order. */
     registerAll(definitions: Iterable<Definition>): this;
+    /** Finalize the registry; no registration is accepted afterwards. */
     seal(): this;
+    /** Registered scopes in registration order. */
     get definitions(): readonly Readonly<Omit<Readonly<ScopeDefinition & import("../../utils/registration.js").RegistrationData<Definition> & Pick<Definition, Extract<keyof Definition, keyof ScopeDefinition>>>, "evidence" | ("toolIds" | "intentIds" | "queryScopeIds" | "knowledgeTopicIds" | "aliases")> & {
         readonly toolIds: [NonNullable<Definition["toolIds"]>] extends [never] ? readonly [] : NonNullable<Definition["toolIds"]> extends readonly string[] ? Readonly<readonly string[] & Definition["toolIds"]> : readonly string[];
         readonly intentIds: [NonNullable<Definition["intentIds"]>] extends [never] ? readonly [] : NonNullable<Definition["intentIds"]> extends readonly string[] ? Readonly<readonly string[] & Definition["intentIds"]> : readonly string[];
@@ -20,7 +54,9 @@ export declare class ScopeRegistry<Definition extends ScopeDefinition = ScopeDef
     } & {
         evidence: [NonNullable<Definition["evidence"]>] extends [never] ? readonly [] : NonNullable<Definition["evidence"]> extends readonly import("../evidence.js").EvidenceRequirement[] ? readonly import("../evidence.js").EvidenceRequirement[] & Definition["evidence"] extends infer T extends readonly import("../evidence.js").EvidenceRequirement[] ? { readonly [Index in keyof T]: Readonly<import("../../utils/registration.js").RegistrationData<T[Index]>>; } : never : readonly Readonly<import("../../utils/registration.js").RegistrationData<NonNullable<Definition["evidence"]>[number]>>[];
     }>[];
+    /** Registered scope ids in registration order; aliases are not included. */
     ids(): readonly string[];
+    /** Iterate the registered scopes. */
     values(): MapIterator<Readonly<Omit<Readonly<ScopeDefinition & import("../../utils/registration.js").RegistrationData<Definition> & Pick<Definition, Extract<keyof Definition, keyof ScopeDefinition>>>, "evidence" | ("toolIds" | "intentIds" | "queryScopeIds" | "knowledgeTopicIds" | "aliases")> & {
         readonly toolIds: [NonNullable<Definition["toolIds"]>] extends [never] ? readonly [] : NonNullable<Definition["toolIds"]> extends readonly string[] ? Readonly<readonly string[] & Definition["toolIds"]> : readonly string[];
         readonly intentIds: [NonNullable<Definition["intentIds"]>] extends [never] ? readonly [] : NonNullable<Definition["intentIds"]> extends readonly string[] ? Readonly<readonly string[] & Definition["intentIds"]> : readonly string[];
@@ -30,6 +66,7 @@ export declare class ScopeRegistry<Definition extends ScopeDefinition = ScopeDef
     } & {
         evidence: [NonNullable<Definition["evidence"]>] extends [never] ? readonly [] : NonNullable<Definition["evidence"]> extends readonly import("../evidence.js").EvidenceRequirement[] ? readonly import("../evidence.js").EvidenceRequirement[] & Definition["evidence"] extends infer T extends readonly import("../evidence.js").EvidenceRequirement[] ? { readonly [Index in keyof T]: Readonly<import("../../utils/registration.js").RegistrationData<T[Index]>>; } : never : readonly Readonly<import("../../utils/registration.js").RegistrationData<NonNullable<Definition["evidence"]>[number]>>[];
     }>>;
+    /** Iterate `[id, scope]` pairs. */
     entries(): MapIterator<[string, Readonly<Omit<Readonly<ScopeDefinition & import("../../utils/registration.js").RegistrationData<Definition> & Pick<Definition, Extract<keyof Definition, keyof ScopeDefinition>>>, "evidence" | ("toolIds" | "intentIds" | "queryScopeIds" | "knowledgeTopicIds" | "aliases")> & {
         readonly toolIds: [NonNullable<Definition["toolIds"]>] extends [never] ? readonly [] : NonNullable<Definition["toolIds"]> extends readonly string[] ? Readonly<readonly string[] & Definition["toolIds"]> : readonly string[];
         readonly intentIds: [NonNullable<Definition["intentIds"]>] extends [never] ? readonly [] : NonNullable<Definition["intentIds"]> extends readonly string[] ? Readonly<readonly string[] & Definition["intentIds"]> : readonly string[];
@@ -39,6 +76,11 @@ export declare class ScopeRegistry<Definition extends ScopeDefinition = ScopeDef
     } & {
         evidence: [NonNullable<Definition["evidence"]>] extends [never] ? readonly [] : NonNullable<Definition["evidence"]> extends readonly import("../evidence.js").EvidenceRequirement[] ? readonly import("../evidence.js").EvidenceRequirement[] & Definition["evidence"] extends infer T extends readonly import("../evidence.js").EvidenceRequirement[] ? { readonly [Index in keyof T]: Readonly<import("../../utils/registration.js").RegistrationData<T[Index]>>; } : never : readonly Readonly<import("../../utils/registration.js").RegistrationData<NonNullable<Definition["evidence"]>[number]>>[];
     }>]>;
+    /**
+     * Registered scope for an id or alias.
+     *
+     * @throws TypeError When the name resolves to nothing.
+     */
     require(id: string): Readonly<Omit<Readonly<ScopeDefinition & import("../../utils/registration.js").RegistrationData<Definition> & Pick<Definition, Extract<keyof Definition, keyof ScopeDefinition>>>, "evidence" | ("toolIds" | "intentIds" | "queryScopeIds" | "knowledgeTopicIds" | "aliases")> & {
         readonly toolIds: [NonNullable<Definition["toolIds"]>] extends [never] ? readonly [] : NonNullable<Definition["toolIds"]> extends readonly string[] ? Readonly<readonly string[] & Definition["toolIds"]> : readonly string[];
         readonly intentIds: [NonNullable<Definition["intentIds"]>] extends [never] ? readonly [] : NonNullable<Definition["intentIds"]> extends readonly string[] ? Readonly<readonly string[] & Definition["intentIds"]> : readonly string[];
@@ -48,18 +90,46 @@ export declare class ScopeRegistry<Definition extends ScopeDefinition = ScopeDef
     } & {
         evidence: [NonNullable<Definition["evidence"]>] extends [never] ? readonly [] : NonNullable<Definition["evidence"]> extends readonly import("../evidence.js").EvidenceRequirement[] ? readonly import("../evidence.js").EvidenceRequirement[] & Definition["evidence"] extends infer T extends readonly import("../evidence.js").EvidenceRequirement[] ? { readonly [Index in keyof T]: Readonly<import("../../utils/registration.js").RegistrationData<T[Index]>>; } : never : readonly Readonly<import("../../utils/registration.js").RegistrationData<NonNullable<Definition["evidence"]>[number]>>[];
     }>;
+    /** Resolve an alias to its scope id; unknown names are returned unchanged. */
     normalize(scope: string): string;
+    /** Registered scope for an id or alias, or `undefined` for a null/unknown name. */
     get(scope?: string | null): RegisteredScope<Definition> | undefined;
+    /** Whether the name resolves to a registered scope. */
     has(scope?: string | null): boolean;
+    /**
+     * Whether a scope accepts an intent.
+     *
+     * The App may override the declared `intentIds` through `acceptsIntent`; without an
+     * override the membership check applies.
+     */
     acceptsIntent(scope: string, goal: string): boolean;
+    /** Whether the scope declares this query scope; a null scope accepts nothing. */
     acceptsQuery(scope: string | null, queryScope: string): boolean;
+    /** Whether the scope belongs to the given App category. */
     is(scope: string | null | undefined, category: Definition['category']): boolean;
+    /** Every query scope declared by any registered scope, deduplicated. */
     queryScopeIds(): string[];
+    /** Knowledge topic ids of one scope; copied so callers cannot mutate the registry. */
     topics(scope?: string | null): string[];
+    /** Evidence declarations of one scope; copied so callers cannot mutate the registry. */
     evidence(scope?: string | null): RegisteredScopeEvidence<Definition>[];
+    /** Declared context tier of one scope, if any. */
     contextTier(scope?: string | null): Definition['contextTier'] | undefined;
+    /**
+     * Copy the scopes that accept at least one of the given intents.
+     *
+     * @param goals - Intent ids to filter by; omit to include every registered scope.
+     * @returns Descriptions whose arrays are copied so callers cannot mutate registry state.
+     */
     describe(goals?: readonly string[]): ScopeDescription<Definition>[];
 }
-/** Create and seal a complete catalog; use the constructor for incremental installation. */
+/**
+ * Create and seal a complete catalog; use the constructor for incremental installation.
+ *
+ * @param definitions - Scope declarations registered in iteration order.
+ * @param policy - Optional registry policy forwarded to the constructor.
+ * @returns A sealed registry.
+ * @throws A configured error for the first invalid or duplicate declaration.
+ */
 export declare function createScopeRegistry<Definition extends ScopeDefinition>(definitions: Iterable<Definition>, policy?: ScopeRegistryPolicy<Definition>): ScopeRegistry<Definition>;
-export type { ScopeDefinition, ScopeDescription, ScopeRegistryPolicy, RegisteredScope, RegisteredScopeEvidence } from '../../structs/kits/intents/scopes.js';
+export type { ScopeDefinition, ScopeDescription, ScopeRegistryPolicy, RegisteredScope, RegisteredScopeEvidence, } from '../../structs/kits/intents/scopes.js';

package/dist/esm/kits/intents/scopes.js

@@ -1,62 +1,148 @@
 import { assertion, booleanResult } from '../../utils/synchronous.js';
 import { breakWhile } from '../../utils/rules.js';
 import { registrationData } from '../../utils/registration.js';
-/** Generic scope relationships; categories, intent policy and extra fields belong to the host. */
+/**
+ * Generic scope relationships; categories, intent policy and extra fields belong to the host.
+ *
+ * A scope is addressable by its id or by any of its aliases; aliases resolve to the declaring
+ * scope, and a name may be claimed only once across both namespaces.
+ */
 export class ScopeRegistry {
+    /** Create and seal a complete scope catalog in one call. */
     static create = createScopeRegistry;
     byId = new Map();
     sources = new Map();
     aliases = new Map();
     sealed = false;
     policy;
+    /**
+     * @param policy - Optional id pattern, categories, required-binding switches, intent
+     *   acceptance override, error wording and assertion hook; lists are copied on construction.
+     */
     constructor(policy = {}) {
         const pattern = policy.idPattern;
         const errorPorts = policy.errors, { sealed, invalid } = errorPorts ?? {};
         const listFields = ['categories', 'tags'];
-        const lists = Object.fromEntries(listFields.map(key => { const value = policy[key]; return [key, value === undefined ? undefined : Object.freeze([...value])]; }));
-        this.policy = Object.freeze({ ...registrationData(policy, ['idPattern', 'assertDefinition', 'acceptsIntent', 'errors', ...listFields]), ...lists, idPattern: pattern ? new RegExp(pattern.source, pattern.flags) : undefined,
-            errors: errorPorts && Object.freeze({ sealed: typeof sealed === 'function' ? sealed.bind(errorPorts) : sealed,
-                invalid: typeof invalid === 'function' ? invalid.bind(errorPorts) : invalid }),
-            assertDefinition: policy.assertDefinition?.bind(policy), acceptsIntent: policy.acceptsIntent?.bind(policy) });
+        const lists = Object.fromEntries(listFields.map((key) => {
+            const value = policy[key];
+            return [key, value === undefined ? undefined : Object.freeze([...value])];
+        }));
+        this.policy = Object.freeze({
+            ...registrationData(policy, [
+                'idPattern',
+                'assertDefinition',
+                'acceptsIntent',
+                'errors',
+                ...listFields,
+            ]),
+            ...lists,
+            idPattern: pattern ? new RegExp(pattern.source, pattern.flags) : undefined,
+            errors: errorPorts &&
+                Object.freeze({
+                    sealed: typeof sealed === 'function' ? sealed.bind(errorPorts) : sealed,
+                    invalid: typeof invalid === 'function' ? invalid.bind(errorPorts) : invalid,
+                }),
+            assertDefinition: policy.assertDefinition?.bind(policy),
+            acceptsIntent: policy.acceptsIntent?.bind(policy),
+        });
     }
+    /**
+     * Validate, freeze and add one scope together with its aliases.
+     *
+     * Every name is checked for conflicts before any of them is stored, so a rejected scope
+     * leaves no partial alias entry behind.
+     *
+     * @param input - Scope declaration; the raw object is retained for `acceptsIntent` overrides
+     *   while the compiled copy serves lookups.
+     * @returns This registry, for chaining.
+     * @throws A configured error for a sealed registry, an invalid name/description/category,
+     *   a missing required binding, duplicate intent ids or an already-claimed name.
+     */
     register(input) {
-        const definition = { ...registrationData(input, ['id', 'description', 'category', 'intentIds', 'queryScopeIds', 'knowledgeTopicIds', 'toolIds', 'aliases', 'evidence', 'contextTier']), id: input.id, description: input.description, category: input.category,
-            intentIds: input.intentIds ?? [], queryScopeIds: input.queryScopeIds ?? [],
-            knowledgeTopicIds: input.knowledgeTopicIds ?? [], toolIds: input.toolIds ?? [],
-            aliases: input.aliases, evidence: input.evidence, contextTier: input.contextTier,
+        const definition = {
+            ...registrationData(input, [
+                'id',
+                'description',
+                'category',
+                'intentIds',
+                'queryScopeIds',
+                'knowledgeTopicIds',
+                'toolIds',
+                'aliases',
+                'evidence',
+                'contextTier',
+            ]),
+            id: input.id,
+            description: input.description,
+            category: input.category,
+            intentIds: input.intentIds ?? [],
+            queryScopeIds: input.queryScopeIds ?? [],
+            knowledgeTopicIds: input.knowledgeTopicIds ?? [],
+            toolIds: input.toolIds ?? [],
+            aliases: input.aliases,
+            evidence: input.evidence,
+            contextTier: input.contextTier,
         };
         const names = [definition.id, ...(definition.aliases ?? [])];
         const policy = this.policy, tags = policy.tags ?? [];
         const invalid = policy.errors?.invalid ?? 'Invalid scope definition';
-        const validName = (name) => { if (typeof name !== 'string' || !name.trim())
-            return false; if (!policy.idPattern)
-            return true; policy.idPattern.lastIndex = 0; return policy.idPattern.test(name); };
+        const validName = (name) => {
+            if (typeof name !== 'string' || !name.trim())
+                return false;
+            if (!policy.idPattern)
+                return true;
+            policy.idPattern.lastIndex = 0;
+            return policy.idPattern.test(name);
+        };
         breakWhile([
-            { occur: () => this.sealed, error: policy.errors?.sealed ?? 'Scope registry is sealed', tags: ['sealed'] },
+            {
+                occur: () => this.sealed,
+                error: policy.errors?.sealed ?? 'Scope registry is sealed',
+                tags: ['sealed'],
+            },
             {
                 occur: [
                     () => !names.every(validName),
                     () => !definition.description.trim(),
                     () => policy.categories !== undefined && !policy.categories.includes(definition.category),
-                ], error: invalid, tags: ['identity'],
+                ],
+                error: invalid,
+                tags: ['identity'],
             },
-            { occur: () => policy.requireIntents === true && !definition.intentIds.length, error: invalid, tags: ['intents', 'required'] },
             {
-                occur: [() => policy.requireSources === true && !definition.queryScopeIds.length && !definition.knowledgeTopicIds.length, () => policy.requireTools === true && !definition.toolIds.length],
-                error: invalid, tags: ['capability-bindings'],
+                occur: () => policy.requireIntents === true && !definition.intentIds.length,
+                error: invalid,
+                tags: ['intents', 'required'],
             },
             {
-                occur: [() => definition.intentIds.some(intent => typeof intent !== 'string'), () => new Set(definition.intentIds).size !== definition.intentIds.length],
-                error: invalid, tags: ['intents', 'values'],
+                occur: [
+                    () => policy.requireSources === true &&
+                        !definition.queryScopeIds.length &&
+                        !definition.knowledgeTopicIds.length,
+                    () => policy.requireTools === true && !definition.toolIds.length,
+                ],
+                error: invalid,
+                tags: ['capability-bindings'],
+            },
+            {
+                occur: [
+                    () => definition.intentIds.some((intent) => typeof intent !== 'string'),
+                    () => new Set(definition.intentIds).size !== definition.intentIds.length,
+                ],
+                error: invalid,
+                tags: ['intents', 'values'],
             },
         ], tags);
         assertion(policy.assertDefinition?.(input), 'Registry definition assertions must return void synchronously');
-        breakWhile(names.some(name => this.byId.has(name) || this.aliases.has(name)), invalid, [...tags, 'duplicate']);
+        breakWhile(names.some((name) => this.byId.has(name) || this.aliases.has(name)), invalid, [...tags, 'duplicate']);
         const frozen = Object.freeze({
-            ...definition, intentIds: Object.freeze([...definition.intentIds]), toolIds: Object.freeze([...definition.toolIds]),
-            queryScopeIds: Object.freeze([...definition.queryScopeIds]), knowledgeTopicIds: Object.freeze([...definition.knowledgeTopicIds]),
+            ...definition,
+            intentIds: Object.freeze([...definition.intentIds]),
+            toolIds: Object.freeze([...definition.toolIds]),
+            queryScopeIds: Object.freeze([...definition.queryScopeIds]),
+            knowledgeTopicIds: Object.freeze([...definition.knowledgeTopicIds]),
             aliases: Object.freeze([...(definition.aliases ?? [])]),
-            evidence: Object.freeze([...(definition.evidence ?? [])].map(item => Object.freeze(registrationData(item)))),
+            evidence: Object.freeze([...(definition.evidence ?? [])].map((item) => Object.freeze(registrationData(item)))),
         });
         this.byId.set(definition.id, frozen);
         this.sources.set(definition.id, input);
@@ -64,42 +150,125 @@ export class ScopeRegistry {
             this.aliases.set(alias, definition.id);
         return this;
     }
+    /** Register every scope in iteration order. */
     registerAll(definitions) {
         for (const definition of definitions)
             this.register(definition);
         return this;
     }
-    seal() { this.sealed = true; return this; }
-    get definitions() { return Object.freeze([...this.byId.values()]); }
-    ids() { return Object.freeze([...this.byId.keys()]); }
-    values() { return this.byId.values(); }
-    entries() { return this.byId.entries(); }
-    require(id) { const value = this.get(id); if (!value)
-        throw new TypeError(`Unknown scope: ${id}`); return value; }
-    normalize(scope) { return this.aliases.get(scope) ?? scope; }
-    get(scope) { return scope ? this.byId.get(this.normalize(scope)) : undefined; }
-    has(scope) { return !!this.get(scope); }
+    /** Finalize the registry; no registration is accepted afterwards. */
+    seal() {
+        this.sealed = true;
+        return this;
+    }
+    /** Registered scopes in registration order. */
+    get definitions() {
+        return Object.freeze([...this.byId.values()]);
+    }
+    /** Registered scope ids in registration order; aliases are not included. */
+    ids() {
+        return Object.freeze([...this.byId.keys()]);
+    }
+    /** Iterate the registered scopes. */
+    values() {
+        return this.byId.values();
+    }
+    /** Iterate `[id, scope]` pairs. */
+    entries() {
+        return this.byId.entries();
+    }
+    /**
+     * Registered scope for an id or alias.
+     *
+     * @throws TypeError When the name resolves to nothing.
+     */
+    require(id) {
+        const value = this.get(id);
+        if (!value)
+            throw new TypeError(`Unknown scope: ${id}`);
+        return value;
+    }
+    /** Resolve an alias to its scope id; unknown names are returned unchanged. */
+    normalize(scope) {
+        return this.aliases.get(scope) ?? scope;
+    }
+    /** Registered scope for an id or alias, or `undefined` for a null/unknown name. */
+    get(scope) {
+        return scope ? this.byId.get(this.normalize(scope)) : undefined;
+    }
+    /** Whether the name resolves to a registered scope. */
+    has(scope) {
+        return !!this.get(scope);
+    }
+    /**
+     * Whether a scope accepts an intent.
+     *
+     * The App may override the declared `intentIds` through `acceptsIntent`; without an
+     * override the membership check applies.
+     */
     acceptsIntent(scope, goal) {
         const definition = this.get(scope);
         if (!definition)
             return false;
         const ids = definition.intentIds;
-        return this.policy.acceptsIntent ? booleanResult(this.policy.acceptsIntent(this.sources.get(this.normalize(scope)), goal), 'Scope intent predicates must return boolean synchronously') : ids.includes(goal);
-    }
-    acceptsQuery(scope, queryScope) { const ids = this.get(scope)?.queryScopeIds ?? []; return !!scope && ids.includes(queryScope); }
-    is(scope, category) { return this.get(scope)?.category === category; }
-    queryScopeIds() { return [...new Set([...this.byId.values()].flatMap(item => item.queryScopeIds))]; }
-    topics(scope) { return [...(this.get(scope)?.knowledgeTopicIds ?? [])]; }
-    evidence(scope) { return [...(this.get(scope)?.evidence ?? [])]; }
-    contextTier(scope) { return this.get(scope)?.contextTier; }
+        return this.policy.acceptsIntent
+            ? booleanResult(this.policy.acceptsIntent(this.sources.get(this.normalize(scope)), goal), 'Scope intent predicates must return boolean synchronously')
+            : ids.includes(goal);
+    }
+    /** Whether the scope declares this query scope; a null scope accepts nothing. */
+    acceptsQuery(scope, queryScope) {
+        const ids = this.get(scope)?.queryScopeIds ?? [];
+        return !!scope && ids.includes(queryScope);
+    }
+    /** Whether the scope belongs to the given App category. */
+    is(scope, category) {
+        return this.get(scope)?.category === category;
+    }
+    /** Every query scope declared by any registered scope, deduplicated. */
+    queryScopeIds() {
+        return [...new Set([...this.byId.values()].flatMap((item) => item.queryScopeIds))];
+    }
+    /** Knowledge topic ids of one scope; copied so callers cannot mutate the registry. */
+    topics(scope) {
+        return [...(this.get(scope)?.knowledgeTopicIds ?? [])];
+    }
+    /** Evidence declarations of one scope; copied so callers cannot mutate the registry. */
+    evidence(scope) {
+        return [...(this.get(scope)?.evidence ?? [])];
+    }
+    /** Declared context tier of one scope, if any. */
+    contextTier(scope) {
+        return this.get(scope)?.contextTier;
+    }
+    /**
+     * Copy the scopes that accept at least one of the given intents.
+     *
+     * @param goals - Intent ids to filter by; omit to include every registered scope.
+     * @returns Descriptions whose arrays are copied so callers cannot mutate registry state.
+     */
     describe(goals) {
         const selected = goals ? new Set(goals) : undefined;
-        return [...this.byId.values()].filter(item => !selected || item.intentIds.some(goal => selected.has(goal)))
-            .map(item => ({ ...item, intentIds: [...item.intentIds], queryScopeIds: [...item.queryScopeIds],
-            knowledgeTopicIds: [...item.knowledgeTopicIds], toolIds: [...item.toolIds], aliases: [...item.aliases], evidence: [...item.evidence] }));
+        return [...this.byId.values()]
+            .filter((item) => !selected || item.intentIds.some((goal) => selected.has(goal)))
+            .map((item) => ({
+            ...item,
+            intentIds: [...item.intentIds],
+            queryScopeIds: [...item.queryScopeIds],
+            knowledgeTopicIds: [...item.knowledgeTopicIds],
+            toolIds: [...item.toolIds],
+            aliases: [...item.aliases],
+            evidence: [...item.evidence],
+        }));
     }
 }
-/** Create and seal a complete catalog; use the constructor for incremental installation. */
+/**
+ * Create and seal a complete catalog; use the constructor for incremental installation.
+ *
+ * @param definitions - Scope declarations registered in iteration order.
+ * @param policy - Optional registry policy forwarded to the constructor.
+ * @returns A sealed registry.
+ * @throws A configured error for the first invalid or duplicate declaration.
+ */
 export function createScopeRegistry(definitions, policy = {}) {
     return new ScopeRegistry(policy).registerAll(definitions).seal();
 }

package/dist/esm/kits/interaction/command.d.ts

@@ -1,8 +1,42 @@
 import type { Command, CommandDefinition, ProtocolShape } from '../../structs/kits/interaction.js';
-/** Compile declarations once. Parsing is synchronous and never executes a registered tool. */
+/**
+ * Compile declarations once. Parsing is synchronous and never executes a registered tool.
+ *
+ * Two schemas are produced from one declaration: `modelJsonSchema` marks only fields the model
+ * must fill, while `inputJsonSchema` marks every required field. A discriminator, when present,
+ * is prepended as a required constant field.
+ *
+ * @param definition - Fields, discriminator, checks, tags, error wording and optional
+ *   formatter; predicates and formatters are bound to this object.
+ * @returns A frozen command with `keys`, `assert`, `parse` and the three schemas.
+ * @throws TypeError For an unknown category, a duplicate field or discriminator field, a check
+ *   that still uses the retired `condition`/`conditions` names, or a non-synchronous predicate.
+ */
 export declare function defineCommand<Value extends object = Record<string, unknown>, Result = Value, Args extends unknown[] = []>(definition: CommandDefinition<Value, Result, Args>): Command<Value, Result, Args>;
-/** Install an entire catalog with shared envelope fields; applications declare data and handlers only. */
+/**
+ * Compile a whole catalog with shared envelope fields.
+ *
+ * Applications declare only their own data and handlers. Defaults are merged in this order:
+ * unrelated default keys, then the command's own keys, with `fields`, `checks` and `tags`
+ * concatenated so shared envelope checks always run before per-command checks.
+ *
+ * @param definitions - Commands keyed by their wire id.
+ * @param defaults - Shared envelope definition; its discriminator field is removed per command.
+ * @returns A frozen record from id to compiled command.
+ * @throws TypeError From `defineCommand` for the first invalid declaration.
+ */
 export declare function compileCommands<Value extends object, Result = Value, Args extends unknown[] = [], Id extends string = string>(definitions: Readonly<Record<Id, CommandDefinition<Value, Result, Args>>>, defaults?: Partial<CommandDefinition<Value, Result, Args>>): Readonly<Record<Id, Command<Value, Result, Args>>>;
-/** Prefer compiled schemas; retain the existing open-schema contract for dynamic host protocols. */
+/**
+ * Build a JSON schema for one command id.
+ *
+ * Prefer compiled schemas; retain the existing open-schema contract for dynamic host protocols.
+ * A protocol without `fieldSchemas` falls back to an open object that only pins the
+ * discriminator, which keeps legacy hosts working without weakening compiled ones.
+ *
+ * @param id - Command id used as the discriminator value.
+ * @param protocol - Compiled command, or a shape carrying only `fieldSchemas`/`keys`.
+ * @param discriminator - Field name carrying the command id; defaults to `type`.
+ * @returns The compiled model schema, or a generated open schema.
+ */
 export declare function commandSchema(id: string, protocol: ProtocolShape, discriminator?: string): Record<string, unknown>;
-export type { Command, CommandDefinition, ProtocolCheck, ProtocolField, ProtocolReason, ProtocolPredicate, ProtocolShape, RegisteredProtocol } from '../../structs/kits/interaction.js';
+export type { Command, CommandDefinition, ProtocolCheck, ProtocolField, ProtocolReason, ProtocolPredicate, ProtocolShape, RegisteredProtocol, } from '../../structs/kits/interaction.js';