@jangts/agent-core 0.1.0 → 0.2.0

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

@@ -1,13 +1,36 @@
-/** 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 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/esm/kits/answering/checks.d.ts

@@ -1,6 +1,17 @@
 import type { OperationContext } from '../../structs/common.js';
 import type { AnswerCheck } from '../../structs/kits/answering/flow.js';
 import type { AnswerChecker } from '../../structs/kits/answering/checks.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.
+ */
 export declare function defineAnswerCheckCatalog<Value, App>(definitions: readonly AnswerChecker<Value, App>[]): Readonly<{
     check(request: {
         checkIds: readonly string[];

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

@@ -1,13 +1,34 @@
+/**
+ * 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.
+ */
 import { snapshotAnswerCheck } from './check-result.js';
 import { readonlyCatalog } from '../../utils/catalog.js';
 import { synchronous } from '../../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.
+ */
 export function defineAnswerCheckCatalog(definitions) {
-    const checks = readonlyCatalog(definitions.map(check => {
+    const checks = 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 = [];

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

@@ -1,10 +1,33 @@
 import type { OperationContext } from '../../structs/common.js';
 import type { AnswerFlowDefinition, AnswerItem, AnswerResult } from '../../structs/kits/answering/flow.js';
-/** Reusable answer workflow. Requests own cells and repair budgets; models remain caller-owned. */
+/**
+ * Compile a reusable answer workflow.
+ *
+ * Reusable answer workflow. Requests own cells and repair budgets; models remain caller-owned.
+ * The flow runs at most `maxRepairs + 1` rounds: one generation pass, then one repair round per
+ * failing item set, and finally an explicit accepted/fallback/blocked result per item.
+ *
+ * @param definition - Batch limits, review policy, generation/check/review/fallback/canInvoke
+ *   handlers and an optional observer; handlers are bound to this object.
+ * @returns A frozen flow whose `run({ inputIds, items }, context)` returns one result per item.
+ * @throws TypeError At construction for invalid limits or policy, or a missing handler; from
+ *   `run` for an invalid batch, non-synchronous handlers, or generated/reviewed values that do
+ *   not belong to the requested items.
+ */
 export declare function defineAnswerFlow<Data, Value, App = undefined>(definition: AnswerFlowDefinition<Data, Value, App>): Readonly<{
+    /**
+     * Run one answer batch.
+     *
+     * @param request - Input ids the batch must cover and the items to answer; validated before
+     *   any handler runs.
+     * @param context - Operation context supplying app, signal and diagnostics.
+     * @returns One accepted, fallback or blocked result per item, in request order.
+     * @throws TypeError For an invalid batch or handler output, or when the repair budget is
+     *   exhausted without a final result.
+     */
     run(request: {
         inputIds: readonly string[];
         items: readonly AnswerItem<Data>[];
     }, context: OperationContext<App>): Promise<AnswerResult<Data, Value>[]>;
 }>;
-export type { AnswerFlowDefinition, AnswerCheck, AnswerItem, AnswerIssue, AnswerResult } from '../../structs/kits/answering/flow.js';
+export type { AnswerFlowDefinition, AnswerCheck, AnswerItem, AnswerIssue, AnswerResult, } from '../../structs/kits/answering/flow.js';

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

@@ -1,3 +1,12 @@
+/**
+ * Answering Kit: the bounded generate → check → review → repair → deliver workflow.
+ *
+ * Place in the package: part of the `answering` Kit and the only module that composes the
+ * other answering pieces. Generation, checking, review, fallback and budget checks are App
+ * handlers; this module owns the stage graph, cell state, repair budget and result statuses.
+ *
+ * Exports: `defineAnswerFlow`, and the answer flow/item/result/check types.
+ */
 import { booleanResult, synchronous } from '../../utils/synchronous.js';
 import { awaitWithSignal } from '../../utils/cancellation.js';
 import { AgentCoreEngine } from '../../execution/engine.js';
@@ -6,13 +15,34 @@ import { validateAnswerBatch } from './batch.js';
 import { snapshotAnswerCheck } from './check-result.js';
 import { observeSafely } from '../../utils/observer.js';
 const unavailable = () => ({ status: 'unavailable', issues: [] });
-/** Reusable answer workflow. Requests own cells and repair budgets; models remain caller-owned. */
+/**
+ * Compile a reusable answer workflow.
+ *
+ * Reusable answer workflow. Requests own cells and repair budgets; models remain caller-owned.
+ * The flow runs at most `maxRepairs + 1` rounds: one generation pass, then one repair round per
+ * failing item set, and finally an explicit accepted/fallback/blocked result per item.
+ *
+ * @param definition - Batch limits, review policy, generation/check/review/fallback/canInvoke
+ *   handlers and an optional observer; handlers are bound to this object.
+ * @returns A frozen flow whose `run({ inputIds, items }, context)` returns one result per item.
+ * @throws TypeError At construction for invalid limits or policy, or a missing handler; from
+ *   `run` for an invalid batch, non-synchronous handlers, or generated/reviewed values that do
+ *   not belong to the requested items.
+ */
 export function defineAnswerFlow(definition) {
     const { maxItems, maxRepairs } = definition, reviewPolicy = definition.reviewPolicy ?? 'optional';
-    if (!Number.isSafeInteger(maxItems) || maxItems < 1 || !Number.isSafeInteger(maxRepairs) || maxRepairs < 0
-        || !['optional', 'required', 'off'].includes(reviewPolicy))
+    if (!Number.isSafeInteger(maxItems) ||
+        maxItems < 1 ||
+        !Number.isSafeInteger(maxRepairs) ||
+        maxRepairs < 0 ||
+        !['optional', 'required', 'off'].includes(reviewPolicy))
         throw new TypeError('Invalid answer flow limits or policy');
-    for (const handler of [definition.generate, definition.check, definition.fallback, definition.canInvoke]) {
+    for (const handler of [
+        definition.generate,
+        definition.check,
+        definition.fallback,
+        definition.canInvoke,
+    ]) {
         if (typeof handler !== 'function')
             throw new TypeError('Missing answer flow handler');
     }
@@ -26,9 +56,15 @@ export function defineAnswerFlow(definition) {
         return value;
     };
     const issues = (cell) => {
-        const result = [...cell.local.issues, ...(cell.review.status === 'failed' ? cell.review.issues : [])];
+        const result = [
+            ...cell.local.issues,
+            ...(cell.review.status === 'failed' ? cell.review.issues : []),
+        ];
         if (!cell.hasValue || cell.local.status !== 'passed')
-            result.push({ code: !cell.hasValue ? 'ANSWER_MISSING' : 'ANSWER_LOCAL_CHECK', message: 'No locally accepted value' });
+            result.push({
+                code: !cell.hasValue ? 'ANSWER_MISSING' : 'ANSWER_LOCAL_CHECK',
+                message: 'No locally accepted value',
+            });
         if ((reviewPolicy === 'required' || cell.knownReviewFailure) && cell.review.status !== 'passed')
             result.push({ code: 'ANSWER_REVIEW_REQUIRED', message: 'Required review is unresolved' });
         return result;
@@ -36,20 +72,26 @@ export function defineAnswerFlow(definition) {
     function observe(stageId, cells, context) {
         if (!observer)
             return;
-        const results = cells.map(cell => ({ item: cell.item, value: cell.value, status: 'blocked', issues: issues(cell), checks: { local: cell.local, review: cell.review } }));
-        observeSafely(input => observer(input, context), { stageId, results });
+        const results = cells.map((cell) => ({
+            item: cell.item,
+            value: cell.value,
+            status: 'blocked',
+            issues: issues(cell),
+            checks: { local: cell.local, review: cell.review },
+        }));
+        observeSafely((input) => observer(input, context), { stageId, results });
     }
     async function generate(cells, repair, context) {
         context.signal.throwIfAborted();
         if (!cells.length || !allowed(context))
             return;
-        const previous = new Map(cells.flatMap(cell => !cell.hasValue ? [] : [[cell.item.id, cell.value]]));
-        const repairs = repair ? new Map(cells.map(cell => [cell.item.id, issues(cell)])) : undefined;
+        const previous = new Map(cells.flatMap((cell) => !cell.hasValue ? [] : [[cell.item.id, cell.value]]));
+        const repairs = repair ? new Map(cells.map((cell) => [cell.item.id, issues(cell)])) : undefined;
         for (const cell of cells)
             cell.generated = false;
         let values;
         try {
-            values = await awaitWithSignal(generateValues({ items: cells.map(cell => cell.item), repairs, previous }, context), context.signal);
+            values = await awaitWithSignal(generateValues({ items: cells.map((cell) => cell.item), repairs, previous }, context), context.signal);
         }
         catch {
             context.signal.throwIfAborted();
@@ -57,7 +99,10 @@ export function defineAnswerFlow(definition) {
             return;
         }
         context.signal.throwIfAborted();
-        if (!values || typeof values.get !== 'function' || typeof values.keys !== 'function' || [...values.keys()].some(id => !cells.some(cell => cell.item.id === id)))
+        if (!values ||
+            typeof values.get !== 'function' ||
+            typeof values.keys !== 'function' ||
+            [...values.keys()].some((id) => !cells.some((cell) => cell.item.id === id)))
             throw new TypeError('Invalid generated answer ownership');
         for (const cell of cells) {
             cell.hasValue = values.has(cell.item.id);
@@ -83,7 +128,7 @@ export function defineAnswerFlow(definition) {
     }
     async function review(cells, context) {
         context.signal.throwIfAborted();
-        const selected = cells.filter(cell => cell.local.status === 'passed' && cell.hasValue);
+        const selected = cells.filter((cell) => cell.local.status === 'passed' && cell.hasValue);
         if (!selected.length)
             return;
         if (reviewPolicy === 'off') {
@@ -98,7 +143,7 @@ export function defineAnswerFlow(definition) {
         }
         let checks;
         try {
-            checks = await awaitWithSignal(reviewValues({ items: selected.map(cell => ({ item: cell.item, value: cell.value })) }, context), context.signal);
+            checks = await awaitWithSignal(reviewValues({ items: selected.map((cell) => ({ item: cell.item, value: cell.value })) }, context), context.signal);
         }
         catch {
             context.signal.throwIfAborted();
@@ -107,7 +152,10 @@ export function defineAnswerFlow(definition) {
             return;
         }
         context.signal.throwIfAborted();
-        if (!checks || typeof checks.get !== 'function' || typeof checks.keys !== 'function' || [...checks.keys()].some(id => !selected.some(cell => cell.item.id === id)))
+        if (!checks ||
+            typeof checks.get !== 'function' ||
+            typeof checks.keys !== 'function' ||
+            [...checks.keys()].some((id) => !selected.some((cell) => cell.item.id === id)))
             throw new TypeError('Invalid answer review ownership');
         const checked = new Map([...checks].map(([id, result]) => [id, snapshotAnswerCheck(result)]));
         for (const cell of selected) {
@@ -118,32 +166,140 @@ export function defineAnswerFlow(definition) {
                 cell.knownReviewFailure = false;
         }
     }
-    const workflow = defineWorkflow({ id: 'answer-flow', entryNodeId: 'generate', nodes: [
-            { id: 'generate', description: 'Generate available items', startsRound: true, run: async (state, context) => { await generate(state.cells.filter(cell => cell.item.sourceStatus === 'ready'), false, context); }, routes: [{ id: 'to-validate', targetNodeId: 'validate' }] },
-            { id: 'validate', description: 'Check values and retain sanitized output', run: (state, context) => { check(state.cells.filter(cell => cell.item.sourceStatus === 'ready'), context); }, routes: [{ id: 'to-review', targetNodeId: 'review' }] },
-            { id: 'review', description: 'Review locally accepted values', run: async (state, context) => { await review(state.cells.filter(cell => cell.item.sourceStatus === 'ready'), context); observe('checked', state.cells, context); }, routes: [{ id: 'to-select-repair', targetNodeId: 'select-repair' }] },
-            { id: 'select-repair', description: 'Select only failed available items', run: state => ({ pending: state.cells.filter(cell => cell.item.sourceStatus === 'ready' && issues(cell).length > 0) }), routes: [{ id: 'to-repair', conditionId: '{nid}.{rid}', when: (state, context) => state.pending.length > 0 && state.repairBudget.available && allowed(context), targetNodeId: 'repair' }, { id: 'to-deliver', targetNodeId: 'deliver' }] },
-            { id: 'repair', description: 'Use one bounded repair attempt', startsRound: true, run: async (state, context) => { if (!state.repairBudget.take())
-                    throw new TypeError('Answer repair budget exhausted'); await generate(state.pending, true, context); }, routes: [{ id: 'to-recheck', targetNodeId: 'recheck' }] },
-            { id: 'recheck', description: 'Recheck only repaired items', run: async (state, context) => { const generated = state.pending.filter(cell => cell.generated); check(generated, context); await review(generated, context); observe('repaired', state.pending, context); }, routes: [{ id: 'to-select-repair', targetNodeId: 'select-repair' }] },
-            { id: 'deliver', description: 'Return accepted values or explicit fallback states', run: (state, context) => ({ result: state.cells.map(cell => {
+    const workflow = defineWorkflow({
+        id: 'answer-flow',
+        entryNodeId: 'generate',
+        nodes: [
+            {
+                id: 'generate',
+                description: 'Generate available items',
+                startsRound: true,
+                run: async (state, context) => {
+                    await generate(state.cells.filter((cell) => cell.item.sourceStatus === 'ready'), false, context);
+                },
+                routes: [{ id: 'to-validate', targetNodeId: 'validate' }],
+            },
+            {
+                id: 'validate',
+                description: 'Check values and retain sanitized output',
+                run: (state, context) => {
+                    check(state.cells.filter((cell) => cell.item.sourceStatus === 'ready'), context);
+                },
+                routes: [{ id: 'to-review', targetNodeId: 'review' }],
+            },
+            {
+                id: 'review',
+                description: 'Review locally accepted values',
+                run: async (state, context) => {
+                    await review(state.cells.filter((cell) => cell.item.sourceStatus === 'ready'), context);
+                    observe('checked', state.cells, context);
+                },
+                routes: [{ id: 'to-select-repair', targetNodeId: 'select-repair' }],
+            },
+            {
+                id: 'select-repair',
+                description: 'Select only failed available items',
+                run: (state) => ({
+                    pending: state.cells.filter((cell) => cell.item.sourceStatus === 'ready' && issues(cell).length > 0),
+                }),
+                routes: [
+                    {
+                        id: 'to-repair',
+                        conditionId: '{nid}.{rid}',
+                        when: (state, context) => state.pending.length > 0 && state.repairBudget.available && allowed(context),
+                        targetNodeId: 'repair',
+                    },
+                    { id: 'to-deliver', targetNodeId: 'deliver' },
+                ],
+            },
+            {
+                id: 'repair',
+                description: 'Use one bounded repair attempt',
+                startsRound: true,
+                run: async (state, context) => {
+                    if (!state.repairBudget.take())
+                        throw new TypeError('Answer repair budget exhausted');
+                    await generate(state.pending, true, context);
+                },
+                routes: [{ id: 'to-recheck', targetNodeId: 'recheck' }],
+            },
+            {
+                id: 'recheck',
+                description: 'Recheck only repaired items',
+                run: async (state, context) => {
+                    const generated = state.pending.filter((cell) => cell.generated);
+                    check(generated, context);
+                    await review(generated, context);
+                    observe('repaired', state.pending, context);
+                },
+                routes: [{ id: 'to-select-repair', targetNodeId: 'select-repair' }],
+            },
+            {
+                id: 'deliver',
+                description: 'Return accepted values or explicit fallback states',
+                run: (state, context) => ({
+                    result: state.cells.map((cell) => {
                         context.signal.throwIfAborted();
                         const errors = issues(cell);
                         if (cell.item.sourceStatus === 'ready' && !errors.length && cell.hasValue)
-                            return { item: cell.item, value: cell.value, status: 'accepted', issues: errors, checks: { local: cell.local, review: cell.review } };
+                            return {
+                                item: cell.item,
+                                value: cell.value,
+                                status: 'accepted',
+                                issues: errors,
+                                checks: { local: cell.local, review: cell.review },
+                            };
                         const outcome = synchronous(fallbackValue({ item: cell.item, issues: errors }, context), 'Answer fallback must be synchronous');
-                        if (!outcome || typeof outcome.handled !== 'boolean' || (outcome.handled && !('value' in outcome)))
+                        if (!outcome ||
+                            typeof outcome.handled !== 'boolean' ||
+                            (outcome.handled && !('value' in outcome)))
                             throw new TypeError('Invalid answer fallback outcome');
-                        return { item: cell.item, value: outcome.handled ? outcome.value : undefined, status: outcome.handled ? 'fallback' : 'blocked', issues: errors, checks: { local: cell.local, review: cell.review } };
-                    }) }), routes: [{ id: 'complete', complete: state => state.result }] },
-        ] });
-    return Object.freeze({ async run(request, context) {
+                        return {
+                            item: cell.item,
+                            value: outcome.handled ? outcome.value : undefined,
+                            status: outcome.handled ? 'fallback' : 'blocked',
+                            issues: errors,
+                            checks: { local: cell.local, review: cell.review },
+                        };
+                    }),
+                }),
+                routes: [{ id: 'complete', complete: (state) => state.result }],
+            },
+        ],
+    });
+    return Object.freeze({
+        /**
+         * Run one answer batch.
+         *
+         * @param request - Input ids the batch must cover and the items to answer; validated before
+         *   any handler runs.
+         * @param context - Operation context supplying app, signal and diagnostics.
+         * @returns One accepted, fallback or blocked result per item, in request order.
+         * @throws TypeError For an invalid batch or handler output, or when the repair budget is
+         *   exhausted without a final result.
+         */
+        async run(request, context) {
             context.signal.throwIfAborted();
             validateAnswerBatch(request.inputIds, request.items, maxItems);
-            const cells = request.items.map(item => ({ item: Object.freeze({ id: item.id, data: item.data, sourceStatus: item.sourceStatus, inputIds: Object.freeze([...item.inputIds]) }),
-                hasValue: false, local: { status: 'not-run', issues: [] }, review: { status: 'not-run', issues: [] }, knownReviewFailure: false }));
-            return new AgentCoreEngine({ maxRounds: maxRepairs + 1,
-                errors: { exhausted: () => new TypeError('Answer flow exhausted') }, execution: { signal: context.signal, diagnostics: context.diagnostics },
-            }).bindWorkflow(workflow, context.app).run({ cells, pending: [], repairBudget: new AttemptBudget(maxRepairs) });
-        } });
+            const cells = request.items.map((item) => ({
+                item: Object.freeze({
+                    id: item.id,
+                    data: item.data,
+                    sourceStatus: item.sourceStatus,
+                    inputIds: Object.freeze([...item.inputIds]),
+                }),
+                hasValue: false,
+                local: { status: 'not-run', issues: [] },
+                review: { status: 'not-run', issues: [] },
+                knownReviewFailure: false,
+            }));
+            return new AgentCoreEngine({
+                maxRounds: maxRepairs + 1,
+                errors: { exhausted: () => new TypeError('Answer flow exhausted') },
+                execution: { signal: context.signal, diagnostics: context.diagnostics },
+            })
+                .bindWorkflow(workflow, context.app)
+                .run({ cells, pending: [], repairBudget: new AttemptBudget(maxRepairs) });
+        },
+    });
 }

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

@@ -1,3 +1,14 @@
+/**
+ * Answering Kit entry: batch validation, per-value checks, task/reader catalogs and the
+ * generate-check-review-repair workflow.
+ *
+ * Place in the package: an optional App-side library for answering a bounded batch of items.
+ * Models, readers, checks, fallbacks and repair policy are supplied by the App; this module
+ * owns their composition, bounds and status aggregation. Core never imports it.
+ *
+ * Exports: everything from `./flow.js`, `./tasks.js`, `./batch.js` and `./checks.js`, plus the
+ * `Answering` namespace object.
+ */
 export * from './flow.js';
 export * from './tasks.js';
 export * from './batch.js';
@@ -6,6 +17,7 @@ import { defineAnswerTaskCatalog, defineAnswerReaderCatalog } from './tasks.js';
 import { defineAnswerCheckCatalog } from './checks.js';
 import { defineAnswerFlow } from './flow.js';
 import { validateAnswerBatch } from './batch.js';
+/** Namespace object for callers that prefer one import over named helpers. */
 export declare const Answering: Readonly<{
     defineAnswerTaskCatalog: typeof defineAnswerTaskCatalog;
     defineAnswerReaderCatalog: typeof defineAnswerReaderCatalog;

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

@@ -1,3 +1,14 @@
+/**
+ * Answering Kit entry: batch validation, per-value checks, task/reader catalogs and the
+ * generate-check-review-repair workflow.
+ *
+ * Place in the package: an optional App-side library for answering a bounded batch of items.
+ * Models, readers, checks, fallbacks and repair policy are supplied by the App; this module
+ * owns their composition, bounds and status aggregation. Core never imports it.
+ *
+ * Exports: everything from `./flow.js`, `./tasks.js`, `./batch.js` and `./checks.js`, plus the
+ * `Answering` namespace object.
+ */
 export * from './flow.js';
 export * from './tasks.js';
 export * from './batch.js';
@@ -6,4 +17,11 @@ import { defineAnswerTaskCatalog, defineAnswerReaderCatalog } from './tasks.js';
 import { defineAnswerCheckCatalog } from './checks.js';
 import { defineAnswerFlow } from './flow.js';
 import { validateAnswerBatch } from './batch.js';
-export const Answering = Object.freeze({ defineAnswerTaskCatalog, defineAnswerReaderCatalog, defineAnswerCheckCatalog, defineAnswerFlow, validateAnswerBatch });
+/** Namespace object for callers that prefer one import over named helpers. */
+export const Answering = Object.freeze({
+    defineAnswerTaskCatalog,
+    defineAnswerReaderCatalog,
+    defineAnswerCheckCatalog,
+    defineAnswerFlow,
+    validateAnswerBatch,
+});

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

@@ -1,13 +1,34 @@
 import type { OperationContext } from '../../structs/common.js';
 import type { AnswerTaskDefinition, AnswerReader, AnswerTaskPorts } from '../../structs/kits/answering/tasks.js';
-/** Task ids, schema, readers, outputs and checks have one compiled authority. */
+/**
+ * Compile a reader catalog.
+ *
+ * @param definitions - Readers with unique ids and a `read` handler.
+ * @returns A frozen catalog; unknown ids fail through `require`.
+ * @throws TypeError When a reader has no `read` handler.
+ */
 export declare function defineAnswerReaderCatalog<Input, Evidence, App, Data = unknown>(definitions: readonly AnswerReader<Input, Evidence, App, Data>[]): import("../../index.js").ReadonlyCatalog<{
     id: string;
     read: (input: Input, context: OperationContext<App> & {
         readonly task: Readonly<AnswerTaskDefinition<Input, Data>>;
     }) => import("../../index.js").MaybePromise<Evidence>;
 }>;
+/**
+ * Compile the answer task catalog from its declarations and shared ports.
+ *
+ * Task ids, schemas, readers, outputs and checks have one compiled authority: a task can only
+ * reference a reader or check that the ports actually registered, and metadata is cloned and
+ * frozen so later mutation by the caller cannot change a registered task.
+ *
+ * @param definitions - Task declarations with identity, reader/output/scope references,
+ *   intent ids, check ids, input schema and metadata.
+ * @param ports - Registered readers, checks, outputs and an optional definition assertion.
+ * @returns A frozen catalog extended with `describe`, `read` and `readAsync`.
+ * @throws TypeError For a task with missing identity, an unknown reader/output/check, empty or
+ *   duplicate intent ids, a duplicate check id, or a failed definition assertion.
+ */
 export declare function defineAnswerTaskCatalog<Input, Evidence, App, Data = unknown>(definitions: readonly AnswerTaskDefinition<Input, Data>[], ports: AnswerTaskPorts<Input, Evidence, App, Data>): Readonly<{
+    /** Task metadata with the JSON schema flattened for model or admin presentation. */
     describe: () => {
         inputJsonSchema: Readonly<Record<string, unknown>>;
         id: string;
@@ -19,10 +40,20 @@ export declare function defineAnswerTaskCatalog<Input, Evidence, App, Data = unk
         checkIds: readonly any[];
         metadata: Data;
     }[];
+    /**
+     * Read evidence through a task's registered reader, synchronously.
+     *
+     * @throws TypeError For an unknown task, a parse failure, or a reader returning a Promise.
+     */
     read(request: {
         taskId: string;
         input: unknown;
     }, context: OperationContext<App>): Evidence;
+    /**
+     * Read evidence through a task's registered reader, awaiting an async reader.
+     *
+     * @throws TypeError For an unknown task or a parse failure; aborts with the caller's signal.
+     */
     readAsync(request: {
         taskId: string;
         input: unknown;