@jangts/agent-core 0.1.1 → 0.2.1

package/dist/cjs/execution/workflow.js

@@ -2,8 +2,18 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WorkflowContractError = exports.route = exports.requireWorkflowValue = exports.AttemptBudget = exports.AgentWorkflow = void 0;
 exports.defineWorkflow = defineWorkflow;
+/**
+ * Derive unique route ids for one node.
+ *
+ * Explicit ids are reserved before any suffix is generated, so a generated `~2` id can
+ * never collide with an id that is already declared later in the same node. The first
+ * occurrence keeps its id; later duplicates are renamed deterministically in order.
+ *
+ * @param routes - Routes of one node, in declaration order.
+ * @returns One id per route, using undefined where the route declared none.
+ */
 function assignRouteIds(routes) {
-    const reserved = new Set(routes.map(route => route.id));
+    const reserved = new Set(routes.map((route) => route.id));
     const used = new Set();
     return routes.map(({ id }) => {
         if (id === undefined)
@@ -17,17 +27,44 @@ function assignRouteIds(routes) {
         return id;
     });
 }
+/**
+ * Reject node fields that were renamed.
+ *
+ * Accepting `round` or `onError` silently would change budget and recovery behavior, so
+ * the older names are reported instead of being mapped.
+ *
+ * @param node - Node about to be registered.
+ * @throws TypeError When a renamed field is present.
+ */
 function validateNodeFields(node) {
     if ('round' in node || 'onError' in node)
         throw new TypeError(`Use startsRound and onErrorNodeId: ${node.id}`);
 }
-/** Executable catalog: validate references and bounded cycles before any handler runs. */
+/**
+ * Executable catalog: validate references and bounded cycles before any handler runs.
+ *
+ * Validation happens once, at construction, so traversal can assume every target exists
+ * and every cycle is budget-bounded.
+ */
 class AgentWorkflow {
+    /** Workflow id, also used in diagnostics and error messages. */
     id;
+    /** First node visited; always starts a round. */
     entryNodeId;
+    /** Optional revision passed through to diagnostics. */
     revision;
+    /** Optional result guard; when present it must return exactly true. */
     isResult;
     nodes = new Map();
+    /**
+     * Build and validate a workflow.
+     *
+     * The entry node must start a round, because otherwise a workflow could loop forever
+     * without consuming the round budget. Renamed top-level fields are rejected as well.
+     *
+     * @param definition - Nodes, entry, id, optional revision and result guard.
+     * @throws TypeError When the definition, a node, a route or a graph invariant is invalid.
+     */
     constructor(definition) {
         if ('entry' in definition || 'validateResult' in definition)
             throw new TypeError('Use entryNodeId and isResult');
@@ -47,18 +84,33 @@ class AgentWorkflow {
         this.checkReachability();
         this.checkBoundedCycles();
     }
+    /**
+     * Derive an extended workflow without mutating this catalog.
+     *
+     * Every node is copied with its callbacks rebound, so the new catalog keeps the same
+     * entry and result guard and can be composed repeatedly. Route overrides are keyed by
+     * node id and must name a node that exists after the merge.
+     *
+     * @param extension - Extension patch, or another workflow whose definitions are merged.
+     * @param routes - Route overrides keyed by node id.
+     * @returns A new, fully re-validated workflow.
+     * @throws TypeError When an override names an unknown node or a node is invalid.
+     */
     add(extension, routes = {}) {
         const patch = extension instanceof AgentWorkflow ? { nodes: extension.definitions, routes } : extension;
         for (const node of patch.nodes)
             validateNodeFields(node);
         const nodes = [...this.definitions, ...patch.nodes];
         for (const id of Object.keys(patch.routes ?? {})) {
-            if (!nodes.some(node => node.id === id))
+            if (!nodes.some((node) => node.id === id))
                 throw new TypeError(`Unknown workflow route source: ${id}`);
         }
         return new AgentWorkflow({
-            id: this.id, revision: patch.revision, entryNodeId: this.entryNodeId, isResult: this.isResult,
-            nodes: nodes.map(node => ({
+            id: this.id,
+            revision: patch.revision,
+            entryNodeId: this.entryNodeId,
+            isResult: this.isResult,
+            nodes: nodes.map((node) => ({
                 id: node.id,
                 description: node.description,
                 name: node.name,
@@ -73,49 +125,117 @@ class AgentWorkflow {
             })),
         });
     }
+    /**
+     * Look up a node that must exist.
+     *
+     * @param id - Node id.
+     * @returns The registered node.
+     * @throws TypeError When the node is unknown.
+     */
     require(id) {
         const node = this.nodes.get(id);
         if (!node)
             throw new TypeError(`Unknown workflow node: ${id}`);
         return node;
     }
-    get definitions() { return Object.freeze([...this.nodes.values()]); }
-    ids() { return Object.freeze([...this.nodes.keys()]); }
-    values() { return this.nodes.values(); }
-    entries() { return this.nodes.entries(); }
-    has(id) { return this.nodes.has(id); }
-    get(id) { return this.nodes.get(id); }
+    /** Frozen snapshot of all nodes, in registration order. */
+    get definitions() {
+        return Object.freeze([...this.nodes.values()]);
+    }
+    /** @returns A frozen array of node ids in registration order. */
+    ids() {
+        return Object.freeze([...this.nodes.keys()]);
+    }
+    /** @returns An iterator over the registered nodes. */
+    values() {
+        return this.nodes.values();
+    }
+    /** @returns An iterator over id/node pairs. */
+    entries() {
+        return this.nodes.entries();
+    }
+    /**
+     * @param id - Node id.
+     * @returns Whether the node is registered.
+     */
+    has(id) {
+        return this.nodes.has(id);
+    }
+    /**
+     * @param id - Node id.
+     * @returns The node, or undefined when it is not registered.
+     */
+    get(id) {
+        return this.nodes.get(id);
+    }
+    /**
+     * Produce a serializable description of every node and route.
+     *
+     * Used by documentation and registration listings; it reports resolved ids and which
+     * routes are terminal or conditional, never the handler implementations.
+     *
+     * @returns An array of plain description objects in registration order.
+     */
     describe() {
-        return [...this.nodes.values()].map(node => ({
-            id: node.id, description: node.description, ...(node.name ? { name: node.name } : {}), startsRound: node.startsRound === true, onErrorNodeId: node.onErrorNodeId,
-            requires: node.requires ?? [], provides: node.provides ?? [],
-            routes: node.routes.map(route => ({ ...(route.id !== undefined ? { id: route.id } : {}), ...(route.description !== undefined ? { description: route.description } : {}), ...(route.conditionId !== undefined ? { conditionId: route.conditionId } : {}), targetNodeId: route.targetNodeId, terminal: !!route.complete, conditional: !!route.when })),
+        return [...this.nodes.values()].map((node) => ({
+            id: node.id,
+            description: node.description,
+            ...(node.name ? { name: node.name } : {}),
+            startsRound: node.startsRound === true,
+            onErrorNodeId: node.onErrorNodeId,
+            requires: node.requires ?? [],
+            provides: node.provides ?? [],
+            routes: node.routes.map((route) => ({
+                ...(route.id !== undefined ? { id: route.id } : {}),
+                ...(route.description !== undefined ? { description: route.description } : {}),
+                ...(route.conditionId !== undefined ? { conditionId: route.conditionId } : {}),
+                targetNodeId: route.targetNodeId,
+                terminal: !!route.complete,
+                conditional: !!route.when,
+            })),
         }));
     }
+    /**
+     * Validate and freeze one node, then add it to the catalog.
+     *
+     * A route must be either a jump with a target or a completion, never both; an
+     * unconditional route must be last, because it would shadow every later route. Route
+     * ids and condition ids are resolved here so the engine never interpolates templates at
+     * run time.
+     *
+     * @param node - Node supplied by the workflow definition.
+     * @throws TypeError When the node, a route or a state contract is invalid.
+     */
     register(node) {
-        if (!node.id?.trim() || !node.description?.trim() || this.nodes.has(node.id) || !node.routes.length
-            || (node.run !== undefined && typeof node.run !== 'function')) {
+        if (!node.id?.trim() ||
+            !node.description?.trim() ||
+            this.nodes.has(node.id) ||
+            !node.routes.length ||
+            (node.run !== undefined && typeof node.run !== 'function')) {
             throw new TypeError('Invalid or duplicate workflow node');
         }
         validateNodeFields(node);
-        if (node.onErrorRouteId !== undefined && (!node.onErrorRouteId.trim() || !(node.onErrorNodeId)))
+        if (node.onErrorRouteId !== undefined && (!node.onErrorRouteId.trim() || !node.onErrorNodeId))
             throw new TypeError(`Invalid workflow error route identity: ${node.id}`);
         const ids = assignRouteIds(node.routes);
         for (const [index, route] of node.routes.entries()) {
-            if (('to' in route)
-                || (route.id !== undefined && !route.id.trim())
-                || (route.conditionId !== undefined && (!route.conditionId.trim() || !route.when)))
+            if ('to' in route ||
+                (route.id !== undefined && !route.id.trim()) ||
+                (route.conditionId !== undefined && (!route.conditionId.trim() || !route.when)))
                 throw new TypeError(`Invalid workflow route identity: ${node.id}`);
             const hasTarget = typeof route.targetNodeId === 'string';
             const hasCompletion = typeof route.complete === 'function';
             const shadowsFollowingRoutes = !route.when && index !== node.routes.length - 1;
-            if (hasTarget === hasCompletion || shadowsFollowingRoutes
-                || (route.when !== undefined && typeof route.when !== 'function')) {
+            if (hasTarget === hasCompletion ||
+                shadowsFollowingRoutes ||
+                (route.when !== undefined && typeof route.when !== 'function')) {
                 throw new TypeError(`Invalid or unreachable workflow route: ${node.id}`);
             }
         }
         for (const fields of [node.requires, node.provides]) {
-            if (fields && (fields.some(field => typeof field !== 'string' || !field.trim()) || new Set(fields).size !== fields.length)) {
+            if (fields &&
+                (fields.some((field) => typeof field !== 'string' || !field.trim()) ||
+                    new Set(fields).size !== fields.length)) {
                 throw new TypeError(`Invalid workflow state contract: ${node.id}`);
             }
         }
@@ -128,29 +248,68 @@ class AgentWorkflow {
                     throw new TypeError(`Condition ID references a missing route ID: ${node.id}`);
                 return id;
             });
-            const common = { id, description: route.description, conditionId, when: route.when?.bind(route) };
-            return Object.freeze(route.complete ? { ...common, complete: route.complete.bind(route) }
+            const common = {
+                id,
+                description: route.description,
+                conditionId,
+                when: route.when?.bind(route),
+            };
+            return Object.freeze(route.complete
+                ? { ...common, complete: route.complete.bind(route) }
                 : { ...common, targetNodeId: route.targetNodeId });
         }));
+        // The entry node starts a round unless it says otherwise; any other node starts one
+        // only when it declares it explicitly.
         const startsRound = node.startsRound ?? (node.id === this.entryNodeId ? true : undefined);
-        this.nodes.set(node.id, Object.freeze({ ...node, id: node.id, description: node.description, name: node.name, report: node.report?.bind(node), startsRound, onErrorRouteId: node.onErrorRouteId,
-            onErrorNodeId: node.onErrorNodeId, run: node.run?.bind(node), routes,
+        this.nodes.set(node.id, Object.freeze({
+            ...node,
+            id: node.id,
+            description: node.description,
+            name: node.name,
+            report: node.report?.bind(node),
+            startsRound,
+            onErrorRouteId: node.onErrorRouteId,
+            onErrorNodeId: node.onErrorNodeId,
+            run: node.run?.bind(node),
+            routes,
             requires: node.requires ? Object.freeze([...node.requires]) : undefined,
             provides: node.provides ? Object.freeze([...node.provides]) : undefined,
         }));
     }
+    /**
+     * Collect every node a visit can hand control to.
+     *
+     * Error targets are included so a recovery node is treated as reachable and is subject
+     * to the same cycle rule as a normal transition.
+     *
+     * @param node - Node whose outgoing edges are collected.
+     * @returns Target node ids, including the error node.
+     */
     targets(node) {
-        const targets = node.routes.flatMap(route => route.targetNodeId !== undefined ? [route.targetNodeId] : []);
+        const targets = node.routes.flatMap((route) => route.targetNodeId !== undefined ? [route.targetNodeId] : []);
         if (node.onErrorNodeId !== undefined)
             targets.push(node.onErrorNodeId);
         return targets;
     }
+    /**
+     * Require every route target to name a registered node.
+     *
+     * @throws TypeError When any target is unknown.
+     */
     checkReferences() {
         for (const node of this.nodes.values()) {
             for (const target of this.targets(node))
                 this.require(target);
         }
     }
+    /**
+     * Require every node to be reachable from the entry.
+     *
+     * An unreachable node is a declaration mistake: it would never run, yet it still
+     * appears in listings and documentation.
+     *
+     * @throws TypeError When any node cannot be reached.
+     */
     checkReachability() {
         const reachable = new Set();
         const visit = (id) => {
@@ -164,6 +323,11 @@ class AgentWorkflow {
         if (reachable.size !== this.nodes.size)
             throw new TypeError('Unreachable workflow node');
     }
+    /**
+     * Require every cycle to cross a round boundary.
+     *
+     * @throws TypeError When a cycle can be traversed without ever starting a new round.
+     */
     checkBoundedCycles() {
         // Graph traversal is procedural: every possible cycle, including error routes,
         // must cross a round boundary so the engine can enforce the shared budget.
@@ -186,20 +350,47 @@ class AgentWorkflow {
     }
 }
 exports.AgentWorkflow = AgentWorkflow;
+/**
+ * Build a validated workflow from a definition.
+ *
+ * @param definition - Workflow definition; validated like the constructor argument.
+ * @returns A validated, immutable workflow catalog.
+ * @throws TypeError When the definition is invalid.
+ */
 function defineWorkflow(definition) {
     return new AgentWorkflow(definition);
 }
-/** Successful acquisitions consume attempts; a refused acquisition never grants another. */
+/**
+ * Successful acquisitions consume attempts; a refused acquisition never grants another.
+ *
+ * `available` is a snapshot of the counter, not a reservation: a caller must still call
+ * `take` and honor its boolean result before acting.
+ */
 class AttemptBudget {
     limit;
     consumed = 0;
+    /**
+     * @param limit - Total attempts allowed; must be a nonnegative integer.
+     * @throws TypeError When `limit` is not a nonnegative integer.
+     */
     constructor(limit) {
         this.limit = limit;
         if (!Number.isInteger(limit) || limit < 0)
             throw new TypeError('Attempt limit must be a nonnegative integer');
     }
-    get used() { return this.consumed; }
-    get available() { return this.consumed < this.limit; }
+    /** Attempts consumed so far. */
+    get used() {
+        return this.consumed;
+    }
+    /** Whether at least one attempt remains unspent. */
+    get available() {
+        return this.consumed < this.limit;
+    }
+    /**
+     * Consume one attempt if one remains.
+     *
+     * @returns True when the attempt was granted, false when the budget is exhausted.
+     */
     take() {
         if (!this.available)
             return false;
@@ -208,6 +399,7 @@ class AttemptBudget {
     }
 }
 exports.AttemptBudget = AttemptBudget;
+// Re-exported so workflow authors get state helpers and route builders from one module.
 var state_js_1 = require("./state.js");
 Object.defineProperty(exports, "requireWorkflowValue", { enumerable: true, get: function () { return state_js_1.requireWorkflowValue; } });
 Object.defineProperty(exports, "route", { enumerable: true, get: function () { return state_js_1.route; } });

package/dist/cjs/index.js

@@ -37,6 +37,22 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.assembleContextPlan = exports.Support = exports.defineCandidateSelection = exports.ToolLifecycleRegistry = exports.defineTextSkillLoader = exports.defineRetrieval = exports.defineEvidenceProjection = exports.defineEvidenceChecklist = exports.assembleFragments = exports.defineRecoveryChain = exports.definePolicySet = exports.ValidationError = exports.BudgetError = exports.getErrorInfo = void 0;
+/**
+ * Aggregate public entry of `@jangts/agent-core`: Core runtime contracts, one `Support`
+ * namespace with a few named Support helpers, and the declaration helpers of optional Kits.
+ *
+ * Layering. Core owns the runtime contracts Apps call (engine, model runner, capabilities,
+ * context, diagnostics) and the handler contracts Core calls back into the App. Support only
+ * supplies recommended implementations of those same contracts, so it is published as a single
+ * namespace instead of a second dispatch layer. Kits are optional business libraries reached
+ * through their own subpath entries; the Kit entries re-exported here are declaration helpers
+ * and standalone modules, not additional Core guarantees. Shared utilities are re-exported
+ * because they are needed alongside these contracts, and they carry no Agent semantics.
+ *
+ * Exports are grouped by responsibility, not by dependency order. Deep subpath entries
+ * (`/engine`, `/model`, `/tools`, `/context`, `/journal`, `/diagnostics`, `/kits/...`)
+ * resolve to the same implementations, so this file is a convenience surface only.
+ */
 __exportStar(require("./execution/engine.js"), exports);
 var errors_js_1 = require("./errors.js");
 Object.defineProperty(exports, "getErrorInfo", { enumerable: true, get: function () { return errors_js_1.getErrorInfo; } });
@@ -50,6 +66,8 @@ __exportStar(require("./model/index.js"), exports);
 __exportStar(require("./capabilities/index.js"), exports);
 __exportStar(require("./context/fragments.js"), exports);
 __exportStar(require("./context/journal.js"), exports);
+// Named re-export: the context barrel also forwards its Kit evidence helpers, which the
+// root surface publishes separately below.
 var assembly_js_1 = require("./context/assembly.js");
 Object.defineProperty(exports, "assembleFragments", { enumerable: true, get: function () { return assembly_js_1.assembleFragments; } });
 __exportStar(require("./support/context/assembly.js"), exports);

package/dist/cjs/kits/aggregation.js

@@ -3,8 +3,27 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Aggregation = void 0;
 exports.mergeByKey = mergeByKey;
 exports.defineQueryAggregation = defineQueryAggregation;
+/**
+ * Aggregation Kit: fold several synchronous query results into one ordered item list.
+ *
+ * Place in the package: an optional App-side helper. Reads, selection rules and result
+ * semantics stay with the host; this module only sequences the calls and preserves order.
+ *
+ * Exports: `mergeByKey`, `defineQueryAggregation`, `Aggregation`.
+ */
 const synchronous_js_1 = require("../utils/synchronous.js");
-/** Merge duplicates without moving their first position; selection policy remains host-owned. */
+/**
+ * Merge duplicates without moving their first position; selection policy remains host-owned.
+ *
+ * The first occurrence of a key fixes the output position; `select` decides which item that
+ * position finally holds, so callers can prefer the newest or the most complete duplicate.
+ *
+ * @param items - Source items in the order the caller wants to display them.
+ * @param key - Key selector; items sharing a key collapse into one slot.
+ * @param select - Chooses the retained item from the incoming item and the earlier choice
+ *   (`undefined` on the first occurrence).
+ * @returns One item per key, in first-occurrence order.
+ */
 function mergeByKey(items, key, select) {
     const values = new Map();
     for (const item of items) {
@@ -13,10 +32,30 @@ function mergeByKey(items, key, select) {
     }
     return [...values.values()];
 }
-/** Ordered synchronous queries, optional stable-key merging; each real read stays host-owned. */
+/**
+ * Compile one ordered read plan over a list of inputs.
+ *
+ * Ordered synchronous queries with optional stable-key merging; each real read stays
+ * host-owned. Inputs run sequentially in the given order, so a host can rely on a
+ * deterministic visit sequence. Without `key` every item is kept; with `key` the last write
+ * wins per key but the position of the first occurrence is retained.
+ *
+ * @param options - Read handler plus optional key/merge policy; handlers are bound to the
+ *   options object so method-style implementations keep their `this`.
+ * @returns A frozen plan whose `collect` returns `{ total, items }`.
+ * @throws TypeError From `collect` when any handler returns a thenable: the whole plan is
+ *   synchronous by contract, and an async handler cannot be awaited here.
+ */
 function defineQueryAggregation(options) {
     const execute = options.execute.bind(options), keyFor = options.key?.bind(options), merge = options.merge?.bind(options);
     return Object.freeze({
+        /**
+         * Run every input in order.
+         *
+         * @param inputs - Query inputs; order determines both read order and result order.
+         * @param context - Host context forwarded unchanged to `execute`, `key` and `merge`.
+         * @returns The merged items and their count.
+         */
         collect(inputs, context) {
             const rows = [], merged = new Map();
             for (const input of inputs)
@@ -26,11 +65,14 @@ function defineQueryAggregation(options) {
                         continue;
                     }
                     const key = (0, synchronous_js_1.synchronous)(keyFor(item, input, context), 'Aggregation keys must be synchronous');
-                    merged.set(key, merge ? (0, synchronous_js_1.synchronous)(merge(item, merged.get(key), input, context), 'Aggregation merge must be synchronous') : item);
+                    merged.set(key, merge
+                        ? (0, synchronous_js_1.synchronous)(merge(item, merged.get(key), input, context), 'Aggregation merge must be synchronous')
+                        : item);
                 }
             const items = keyFor ? [...merged.values()] : rows;
             return { total: items.length, items };
         },
     });
 }
+/** Namespace object for callers that prefer one import over named helpers. */
 exports.Aggregation = Object.freeze({ defineQueryAggregation, mergeByKey });

package/dist/cjs/kits/answering/batch.js

@@ -1,14 +1,33 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateAnswerBatch = validateAnswerBatch;
+/**
+ * Validate that one batch is well formed and fully covered.
+ *
+ * @param inputIds - Every input id the batch must answer; non-empty, unique, non-blank.
+ * @param items - Answer items; each must reference known inputs and together cover all of them.
+ * @param maxItems - Maximum allowed item count, a positive safe integer.
+ * @throws TypeError For an invalid limit or input ids, an empty or oversized item list,
+ *   duplicate item ids, an unknown source status or input id, or an uncovered input.
+ */
 function validateAnswerBatch(inputIds, items, maxItems) {
-    if (!Number.isSafeInteger(maxItems) || maxItems < 1 || !inputIds.length || new Set(inputIds).size !== inputIds.length || inputIds.some(id => typeof id !== 'string' || !id))
+    if (!Number.isSafeInteger(maxItems) ||
+        maxItems < 1 ||
+        !inputIds.length ||
+        new Set(inputIds).size !== inputIds.length ||
+        inputIds.some((id) => typeof id !== 'string' || !id))
         throw new TypeError('Invalid answer input ids or limit');
-    if (!items.length || items.length > maxItems || new Set(items.map(item => item.id)).size !== items.length)
+    if (!items.length ||
+        items.length > maxItems ||
+        new Set(items.map((item) => item.id)).size !== items.length)
         throw new TypeError('Invalid answer item count or ids');
     const covered = new Set();
     for (const item of items) {
-        if (typeof item.id !== 'string' || !item.id || !['ready', 'unavailable', 'conflict'].includes(item.sourceStatus) || !item.inputIds.length || new Set(item.inputIds).size !== item.inputIds.length)
+        if (typeof item.id !== 'string' ||
+            !item.id ||
+            !['ready', 'unavailable', 'conflict'].includes(item.sourceStatus) ||
+            !item.inputIds.length ||
+            new Set(item.inputIds).size !== item.inputIds.length)
             throw new TypeError('Invalid answer item');
         for (const id of item.inputIds) {
             if (!inputIds.includes(id))
@@ -16,6 +35,6 @@ function validateAnswerBatch(inputIds, items, maxItems) {
             covered.add(id);
         }
     }
-    if (inputIds.some(id => !covered.has(id)))
+    if (inputIds.some((id) => !covered.has(id)))
         throw new TypeError('Answer tasks do not cover every input');
 }

package/dist/cjs/kits/answering/check-result.js

@@ -1,16 +1,39 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.snapshotAnswerCheck = snapshotAnswerCheck;
-/** One result contract for individual checkers and batch review. */
+/**
+ * Freeze and validate one check result.
+ *
+ * @param check - Check outcome: status, issues and an optional replacement value.
+ * @param checkId - Id stamped onto issues that do not carry their own, so the failing checker
+ *   stays identifiable after aggregation.
+ * @returns A frozen copy with frozen issues and paths.
+ * @throws TypeError When the status is unknown, an issue is malformed, a `passed` result still
+ *   reports issues, or a `failed` result reports none.
+ */
 function snapshotAnswerCheck(check, checkId) {
-    if (!check || !['passed', 'failed', 'unavailable', 'not-run'].includes(check.status) || !Array.isArray(check.issues)
-        || check.issues.some(issue => !issue || typeof issue.code !== 'string' || !issue.code || typeof issue.message !== 'string'
-            || (issue.path !== undefined && (!Array.isArray(issue.path) || issue.path.some((part) => typeof part !== 'string' && typeof part !== 'number'))))
-        || (check.status === 'passed' && check.issues.length) || (check.status === 'failed' && !check.issues.length))
+    if (!check ||
+        !['passed', 'failed', 'unavailable', 'not-run'].includes(check.status) ||
+        !Array.isArray(check.issues) ||
+        check.issues.some((issue) => !issue ||
+            typeof issue.code !== 'string' ||
+            !issue.code ||
+            typeof issue.message !== 'string' ||
+            (issue.path !== undefined &&
+                (!Array.isArray(issue.path) ||
+                    issue.path.some((part) => typeof part !== 'string' && typeof part !== 'number')))) ||
+        (check.status === 'passed' && check.issues.length) ||
+        (check.status === 'failed' && !check.issues.length))
         throw new TypeError('Invalid answer check result');
-    return Object.freeze({ status: check.status, ...('value' in check ? { value: check.value } : {}),
-        issues: Object.freeze(check.issues.map(issue => Object.freeze({ code: issue.code, message: issue.message,
-            ...(issue.checkId !== undefined || checkId !== undefined ? { checkId: issue.checkId ?? checkId } : {}),
+    return Object.freeze({
+        status: check.status,
+        ...('value' in check ? { value: check.value } : {}),
+        issues: Object.freeze(check.issues.map((issue) => Object.freeze({
+            code: issue.code,
+            message: issue.message,
+            ...(issue.checkId !== undefined || checkId !== undefined
+                ? { checkId: issue.checkId ?? checkId }
+                : {}),
             ...(issue.path !== undefined ? { path: Object.freeze([...issue.path]) } : {}),
         }))),
     });

package/dist/cjs/kits/answering/checks.js

@@ -1,16 +1,37 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.defineAnswerCheckCatalog = defineAnswerCheckCatalog;
+/**
+ * Answering Kit: a catalog of named value checkers with one aggregated result.
+ *
+ * Place in the package: part of the `answering` Kit. Checkers are App business rules; this
+ * module only registers them, runs a selected ordered subset and folds their statuses.
+ *
+ * Exports: `defineAnswerCheckCatalog`, and the answer checker types.
+ */
 const check_result_js_1 = require("./check-result.js");
 const catalog_js_1 = require("../../utils/catalog.js");
 const synchronous_js_1 = require("../../utils/synchronous.js");
+/**
+ * Compile a checker catalog.
+ *
+ * A checker may return a replacement value; it is threaded into the next checker, so the
+ * selected ids behave like an ordered chain rather than independent assertions.
+ *
+ * @param definitions - Checkers with unique ids and a synchronous `check` handler.
+ * @returns A frozen catalog whose `check({ checkIds, value }, context)` folds the results.
+ * @throws TypeError For a missing handler or a duplicate id; from `check` for a repeated
+ *   selected id, a non-synchronous checker or an invalid check result.
+ */
 function defineAnswerCheckCatalog(definitions) {
-    const checks = (0, catalog_js_1.readonlyCatalog)(definitions.map(check => {
+    const checks = (0, catalog_js_1.readonlyCatalog)(definitions.map((check) => {
         if (typeof check.check !== 'function')
             throw new TypeError('Invalid answer checker');
         return Object.freeze({ id: check.id, check: check.check.bind(check) });
-    }), id => new TypeError(`Unknown answer checker: ${id}`));
-    return Object.freeze({ ...checks,
+    }), (id) => new TypeError(`Unknown answer checker: ${id}`));
+    return Object.freeze({
+        ...checks,
+        // Severity only escalates: `failed` wins over `unavailable`, which wins over `passed`.
         check(request, context) {
             context.signal.throwIfAborted();
             const issues = [];