@jangts/agent-core 0.1.0 → 0.2.0

package/dist/cjs/kits/intents/registry.js

@@ -5,95 +5,240 @@ exports.createIntentRegistry = createIntentRegistry;
 const synchronous_js_1 = require("../../utils/synchronous.js");
 const rules_js_1 = require("../../utils/rules.js");
 const registration_js_1 = require("../../utils/registration.js");
-/** Intent semantics and allowed values are configuration; the registry owns their common lifecycle. */
+/**
+ * Intent semantics and allowed values are configuration; the registry owns their common lifecycle.
+ *
+ * Registration order is preserved by `ids`, `definitions`, `values` and `entries`; once
+ * `seal()` is called the set is final and further registration is rejected.
+ */
 class IntentRegistry {
+    /** Create and seal a complete catalog in one call. */
     static create = createIntentRegistry;
     byId = new Map();
     sealed = false;
     policy;
+    /**
+     * @param policy - Optional id pattern, vocabulary lists, error wording and assertion hook.
+     *   Lists and the pattern are copied so later mutation of the input cannot weaken checks.
+     */
     constructor(policy = {}) {
         const pattern = policy.idPattern;
         const errorPorts = policy.errors, { sealed, invalid, duplicate } = errorPorts ?? {};
-        const listFields = ['scopeModes', 'targetModes', 'contextTiers', 'actions', 'steps', 'handoffValues', 'tags'];
-        const lists = Object.fromEntries(listFields.map(key => { const value = policy[key]; return [key, value === undefined ? undefined : Object.freeze([...value])]; }));
-        this.policy = Object.freeze({ ...(0, registration_js_1.registrationData)(policy, ['idPattern', 'assertDefinition', '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, duplicate: duplicate?.bind(errorPorts) }),
-            assertDefinition: policy.assertDefinition?.bind(policy) });
+        const listFields = [
+            'scopeModes',
+            'targetModes',
+            'contextTiers',
+            'actions',
+            'steps',
+            'handoffValues',
+            'tags',
+        ];
+        const lists = Object.fromEntries(listFields.map((key) => {
+            const value = policy[key];
+            return [key, value === undefined ? undefined : Object.freeze([...value])];
+        }));
+        this.policy = Object.freeze({
+            ...(0, registration_js_1.registrationData)(policy, ['idPattern', 'assertDefinition', '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,
+                    duplicate: duplicate?.bind(errorPorts),
+                }),
+            assertDefinition: policy.assertDefinition?.bind(policy),
+        });
     }
+    /**
+     * Validate, freeze and add one intent.
+     *
+     * Checks run in a fixed order — sealed, identity, context contract, auxiliary actions,
+     * handoff, plan, steps — so the reported violation is stable when several rules fail.
+     *
+     * @param input - Intent declaration; the App's own assertion receives this original object,
+     *   not the compiled copy, so helpers and prototype methods keep working.
+     * @returns This registry, for chaining.
+     * @throws A configured error for a sealed registry, invalid identity or vocabulary values,
+     *   empty/duplicate steps, or a duplicate intent id.
+     */
     register(input) {
         const id = input.id;
-        const definition = { ...(0, registration_js_1.registrationData)(input, ['id', 'description', 'steps', 'scopePolicy', 'targetPolicy', 'contextTier', 'planIntent', 'auxiliaryActions', 'preparedHandoff']), id, description: input.description, steps: input.steps,
-            scopePolicy: input.scopePolicy, targetPolicy: input.targetPolicy, contextTier: input.contextTier,
-            planIntent: input.planIntent, auxiliaryActions: input.auxiliaryActions, preparedHandoff: input.preparedHandoff };
+        const definition = {
+            ...(0, registration_js_1.registrationData)(input, [
+                'id',
+                'description',
+                'steps',
+                'scopePolicy',
+                'targetPolicy',
+                'contextTier',
+                'planIntent',
+                'auxiliaryActions',
+                'preparedHandoff',
+            ]),
+            id,
+            description: input.description,
+            steps: input.steps,
+            scopePolicy: input.scopePolicy,
+            targetPolicy: input.targetPolicy,
+            contextTier: input.contextTier,
+            planIntent: input.planIntent,
+            auxiliaryActions: input.auxiliaryActions,
+            preparedHandoff: input.preparedHandoff,
+        };
         const policy = this.policy;
         const invalid = policy.errors?.invalid ?? 'Invalid intent definition';
         const tags = policy.tags ?? [];
-        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);
+        };
         (0, rules_js_1.breakWhile)([
-            { occur: () => this.sealed, error: policy.errors?.sealed ?? 'Intent registry is sealed', tags: ['sealed'] },
+            {
+                occur: () => this.sealed,
+                error: policy.errors?.sealed ?? 'Intent registry is sealed',
+                tags: ['sealed'],
+            },
             {
                 occur: [() => !validName(definition.id), () => !definition.description.trim()],
-                error: invalid, tags: ['identity'],
+                error: invalid,
+                tags: ['identity'],
             },
             {
                 occur: [
-                    () => policy.scopeModes !== undefined && !policy.scopeModes.includes(definition.scopePolicy),
-                    () => policy.targetModes !== undefined && !policy.targetModes.includes(definition.targetPolicy),
-                    () => policy.contextTiers !== undefined && !policy.contextTiers.includes(definition.contextTier),
-                ], error: invalid, tags: ['context-contract'],
+                    () => policy.scopeModes !== undefined &&
+                        !policy.scopeModes.includes(definition.scopePolicy),
+                    () => policy.targetModes !== undefined &&
+                        !policy.targetModes.includes(definition.targetPolicy),
+                    () => policy.contextTiers !== undefined &&
+                        !policy.contextTiers.includes(definition.contextTier),
+                ],
+                error: invalid,
+                tags: ['context-contract'],
             },
             {
                 occur: [
                     () => definition.auxiliaryActions !== undefined && !definition.auxiliaryActions.length,
-                    () => definition.auxiliaryActions !== undefined && definition.auxiliaryActions.some(action => policy.actions !== undefined && !policy.actions.includes(action)),
-                    () => definition.auxiliaryActions !== undefined && new Set(definition.auxiliaryActions).size !== definition.auxiliaryActions.length,
-                ], error: invalid, tags: ['auxiliary-actions'],
+                    () => definition.auxiliaryActions !== undefined &&
+                        definition.auxiliaryActions.some((action) => policy.actions !== undefined && !policy.actions.includes(action)),
+                    () => definition.auxiliaryActions !== undefined &&
+                        new Set(definition.auxiliaryActions).size !== definition.auxiliaryActions.length,
+                ],
+                error: invalid,
+                tags: ['auxiliary-actions'],
+            },
+            {
+                occur: () => definition.preparedHandoff !== undefined &&
+                    policy.handoffValues !== undefined &&
+                    !policy.handoffValues.includes(definition.preparedHandoff),
+                error: invalid,
+                tags: ['handoff'],
+            },
+            {
+                occur: () => policy.actions !== undefined && !policy.actions.includes(definition.planIntent),
+                error: invalid,
+                tags: ['plan'],
             },
-            { occur: () => definition.preparedHandoff !== undefined && policy.handoffValues !== undefined && !policy.handoffValues.includes(definition.preparedHandoff), error: invalid, tags: ['handoff'] },
-            { occur: () => policy.actions !== undefined && !policy.actions.includes(definition.planIntent), error: invalid, tags: ['plan'] },
             {
                 occur: [
                     () => !definition.steps.length,
-                    () => definition.steps.some(step => policy.steps !== undefined && !policy.steps.includes(step)),
+                    () => definition.steps.some((step) => policy.steps !== undefined && !policy.steps.includes(step)),
                     () => new Set(definition.steps).size !== definition.steps.length,
-                ], error: invalid, tags: ['steps'],
+                ],
+                error: invalid,
+                tags: ['steps'],
             },
         ], tags);
-        // App assertions may use implementation helpers; never pass a compiled view as the source instance.
+        // App assertions may use implementation helpers; never pass a compiled view as the source
+        // instance.
         (0, synchronous_js_1.assertion)(policy.assertDefinition?.(input), 'Registry definition assertions must return void synchronously');
-        (0, rules_js_1.breakWhile)(this.byId.has(definition.id), () => policy.errors?.duplicate?.(definition.id) ?? new Error(`Duplicate intent: ${definition.id}`), [...tags, 'duplicate']);
+        (0, rules_js_1.breakWhile)(this.byId.has(definition.id), () => policy.errors?.duplicate?.(definition.id) ??
+            new Error(`Duplicate intent: ${definition.id}`), [...tags, 'duplicate']);
         this.byId.set(definition.id, Object.freeze({
-            ...definition, steps: Object.freeze([...definition.steps]),
-            ...(definition.auxiliaryActions ? { auxiliaryActions: Object.freeze([...definition.auxiliaryActions]) } : {}),
+            ...definition,
+            steps: Object.freeze([...definition.steps]),
+            ...(definition.auxiliaryActions
+                ? { auxiliaryActions: Object.freeze([...definition.auxiliaryActions]) }
+                : {}),
         }));
         return this;
     }
+    /** Register every intent in iteration order. */
     registerAll(definitions) {
         for (const definition of definitions)
             this.register(definition);
         return this;
     }
-    get(goal) { return this.byId.get(goal); }
-    has(goal) { return this.byId.has(goal); }
-    ids() { return Object.freeze([...this.byId.keys()]); }
-    get definitions() { return Object.freeze([...this.byId.values()]); }
-    values() { return this.byId.values(); }
-    entries() { return this.byId.entries(); }
-    require(id) { const value = this.byId.get(id); if (!value)
-        throw new TypeError(`Unknown intent: ${id}`); return value; }
-    allows(goal, step) { return this.byId.get(goal)?.steps.includes(step) ?? false; }
+    /** Registered intent for `goal`, or `undefined` when it is absent. */
+    get(goal) {
+        return this.byId.get(goal);
+    }
+    /** Whether an intent id is registered. */
+    has(goal) {
+        return this.byId.has(goal);
+    }
+    /** Registered intent ids in registration order. */
+    ids() {
+        return Object.freeze([...this.byId.keys()]);
+    }
+    /** Registered intents in registration order. */
+    get definitions() {
+        return Object.freeze([...this.byId.values()]);
+    }
+    /** Iterate the registered intents. */
+    values() {
+        return this.byId.values();
+    }
+    /** Iterate `[id, intent]` pairs. */
+    entries() {
+        return this.byId.entries();
+    }
+    /**
+     * Registered intent for `id`.
+     *
+     * @throws TypeError When the id is not registered.
+     */
+    require(id) {
+        const value = this.byId.get(id);
+        if (!value)
+            throw new TypeError(`Unknown intent: ${id}`);
+        return value;
+    }
+    /** Whether the intent declares this step; unknown intents allow nothing. */
+    allows(goal, step) {
+        return this.byId.get(goal)?.steps.includes(step) ?? false;
+    }
+    /**
+     * Copy the selected intents out of the registry.
+     *
+     * @param goals - Ids to include; the default is every registered id, in registry order.
+     * @returns Descriptions whose arrays are copied so callers cannot mutate registry state.
+     */
     describe(goals = this.ids()) {
         const selected = new Set(goals);
-        return [...this.byId.values()].filter(item => selected.has(item.id))
-            .map(item => ({ ...item, steps: [...item.steps] }));
+        return [...this.byId.values()]
+            .filter((item) => selected.has(item.id))
+            .map((item) => ({ ...item, steps: [...item.steps] }));
+    }
+    /** Finalize the registry; no registration is accepted afterwards. */
+    seal() {
+        this.sealed = true;
+        return this;
     }
-    seal() { this.sealed = true; return this; }
 }
 exports.IntentRegistry = IntentRegistry;
-/** 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 - Intent 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.
+ */
 function createIntentRegistry(definitions, policy = {}) {
     return new IntentRegistry(policy).registerAll(definitions).seal();
 }

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

@@ -5,62 +5,148 @@ exports.createScopeRegistry = createScopeRegistry;
 const synchronous_js_1 = require("../../utils/synchronous.js");
 const rules_js_1 = require("../../utils/rules.js");
 const registration_js_1 = require("../../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.
+ */
 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({ ...(0, registration_js_1.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({
+            ...(0, registration_js_1.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 = { ...(0, registration_js_1.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 = {
+            ...(0, registration_js_1.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);
+        };
         (0, rules_js_1.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);
         (0, synchronous_js_1.assertion)(policy.assertDefinition?.(input), 'Registry definition assertions must return void synchronously');
-        (0, rules_js_1.breakWhile)(names.some(name => this.byId.has(name) || this.aliases.has(name)), invalid, [...tags, 'duplicate']);
+        (0, rules_js_1.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((0, registration_js_1.registrationData)(item)))),
+            evidence: Object.freeze([...(definition.evidence ?? [])].map((item) => Object.freeze((0, registration_js_1.registrationData)(item)))),
         });
         this.byId.set(definition.id, frozen);
         this.sources.set(definition.id, input);
@@ -68,43 +154,126 @@ 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 ? (0, synchronous_js_1.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
+            ? (0, synchronous_js_1.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],
+        }));
     }
 }
 exports.ScopeRegistry = ScopeRegistry;
-/** 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.
+ */
 function createScopeRegistry(definitions, policy = {}) {
     return new ScopeRegistry(policy).registerAll(definitions).seal();
 }