@jangts/agent-core 0.1.0 → 0.2.0

package/dist/esm/execution/workflow.js

@@ -1,5 +1,15 @@
+/**
+ * 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)
@@ -13,17 +23,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.
+ */
 export 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');
@@ -43,18 +80,33 @@ export 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,
@@ -69,49 +121,117 @@ export 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}`);
             }
         }
@@ -124,29 +244,68 @@ export 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) => {
@@ -160,6 +319,11 @@ export 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.
@@ -181,20 +345,47 @@ export class AgentWorkflow {
             visit(id);
     }
 }
+/**
+ * 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.
+ */
 export 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.
+ */
 export 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;
@@ -202,5 +393,6 @@ export class AttemptBudget {
         return true;
     }
 }
+// Re-exported so workflow authors get state helpers and route builders from one module.
 export { requireWorkflowValue, route } from './state.js';
 export { WorkflowContractError } from '../structs/errors.js';

package/dist/esm/index.d.ts

@@ -1,3 +1,19 @@
+/**
+ * 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.
+ */
 export * from './execution/engine.js';
 export { getErrorInfo } from './errors.js';
 export { BudgetError, ValidationError, type AgentErrorInfo } from './structs/errors.js';
@@ -10,7 +26,7 @@ export * from './context/journal.js';
 export { assembleFragments } from './context/assembly.js';
 export * from './support/context/assembly.js';
 export { defineEvidenceChecklist, defineEvidenceProjection } from './kits/evidence.js';
-export type { EvidenceRequirement, EvidenceProvider, EvidenceProjectionDefinition, EvidenceProjectionProvider } from './structs/kits/evidence.js';
+export type { EvidenceRequirement, EvidenceProvider, EvidenceProjectionDefinition, EvidenceProjectionProvider, } from './structs/kits/evidence.js';
 export * from './kits/presentation/events.js';
 export * from './support/transport/index.js';
 export * from './support/model/chat-completions.js';

package/dist/esm/index.js

@@ -1,3 +1,19 @@
+/**
+ * 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.
+ */
 export * from './execution/engine.js';
 export { getErrorInfo } from './errors.js';
 export { BudgetError, ValidationError } from './structs/errors.js';
@@ -6,6 +22,8 @@ export * from './model/index.js';
 export * from './capabilities/index.js';
 export * from './context/fragments.js';
 export * from './context/journal.js';
+// Named re-export: the context barrel also forwards its Kit evidence helpers, which the
+// root surface publishes separately below.
 export { assembleFragments } from './context/assembly.js';
 export * from './support/context/assembly.js';
 export { defineEvidenceChecklist, defineEvidenceProjection } from './kits/evidence.js';

package/dist/esm/kits/aggregation.d.ts

@@ -1,14 +1,46 @@
 import type { QueryAggregationOptions } from '../structs/kits/aggregation.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.
+ */
 export declare function mergeByKey<Item, Key>(items: Iterable<Item>, key: (item: Item) => Key, select: (item: Item, previous: Item | undefined) => Item): Item[];
-/** 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.
+ */
 export declare function defineQueryAggregation<Input, Item, Context>(options: QueryAggregationOptions<Input, Item, Context>): Readonly<{
+    /**
+     * 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: readonly Input[], context: Context): {
         total: number;
         items: Item[];
     };
 }>;
 export type { QueryAggregationOptions } from '../structs/kits/aggregation.js';
+/** Namespace object for callers that prefer one import over named helpers. */
 export declare const Aggregation: Readonly<{
     defineQueryAggregation: typeof defineQueryAggregation;
     mergeByKey: typeof mergeByKey;

package/dist/esm/kits/aggregation.js

@@ -1,5 +1,24 @@
+/**
+ * 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`.
+ */
 import { synchronous } from '../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.
+ */
 export function mergeByKey(items, key, select) {
     const values = new Map();
     for (const item of items) {
@@ -8,10 +27,30 @@ export 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.
+ */
 export 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)
@@ -21,11 +60,14 @@ export function defineQueryAggregation(options) {
                         continue;
                     }
                     const key = synchronous(keyFor(item, input, context), 'Aggregation keys must be synchronous');
-                    merged.set(key, merge ? synchronous(merge(item, merged.get(key), input, context), 'Aggregation merge must be synchronous') : item);
+                    merged.set(key, merge
+                        ? 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. */
 export const Aggregation = Object.freeze({ defineQueryAggregation, mergeByKey });

package/dist/esm/kits/answering/batch.d.ts

@@ -1,2 +1,19 @@
+/**
+ * Answering Kit: batch shape validation for one answer request.
+ *
+ * Place in the package: part of the `answering` Kit. It guards the request envelope only;
+ * reading, checking and repairing answers happens in the flow and task modules.
+ *
+ * Exports: `validateAnswerBatch`.
+ */
 import type { AnswerItem } from '../../structs/kits/answering/flow.js';
+/**
+ * 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.
+ */
 export declare function validateAnswerBatch<Data>(inputIds: readonly string[], items: readonly AnswerItem<Data>[], maxItems: number): void;

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

@@ -1,11 +1,30 @@
+/**
+ * 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.
+ */
 export 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))
@@ -13,6 +32,6 @@ export 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/esm/kits/answering/check-result.d.ts

@@ -1,3 +1,20 @@
+/**
+ * Answering Kit: the frozen result contract shared by checkers and batch review.
+ *
+ * Place in the package: part of the `answering` Kit. It normalizes one check outcome and
+ * rejects internally inconsistent statuses so aggregation can trust what it receives.
+ *
+ * Exports: `snapshotAnswerCheck`.
+ */
 import type { AnswerCheck } from '../../structs/kits/answering/flow.js';
-/** 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.
+ */
 export declare function snapshotAnswerCheck<Value>(check: AnswerCheck<Value>, checkId?: string): AnswerCheck<Value>;