@jangts/agent-core 0.1.0 → 0.2.0

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

@@ -2,7 +2,12 @@ import type { InteractionProtocolDefinition } from '../../structs/kits/interacti
 import { CommandCatalog } from './commands.js';
 import { defineCommand, commandSchema } from './command.js';
 import { bindInteraction } from './handlers.js';
-/** Web/AI payload family. HTTP/SSE framing and actual command execution remain separate ports. */
+/**
+ * Web/AI payload family. HTTP/SSE framing and actual command execution remain separate ports.
+ *
+ * Every command registered here gets the envelope's discriminator forced to its own id, so a
+ * payload cannot claim one command while carrying another command's data.
+ */
 export declare class InteractionProtocol<Value extends object = Record<string, unknown>, Result = Value, Args extends unknown[] = [], Id extends string = string> {
     static readonly define: typeof defineInteractionProtocol;
     static readonly Commands: typeof CommandCatalog;
@@ -10,20 +15,52 @@ export declare class InteractionProtocol<Value extends object = Record<string, u
     static readonly commandSchema: typeof commandSchema;
     static readonly bind: typeof bindInteraction;
     static readonly categories: readonly import("./handlers.js").InteractionCategory[];
+    /** Field carrying the command id in a payload. */
     readonly commandField: string;
+    /** Accepted selector names: the command field first, then any declared aliases. */
     readonly commandSelectors: readonly string[];
+    /** Sealed catalog of the compiled commands. */
     readonly commands: CommandCatalog<Value, Result, Args, Id>;
     private readonly selectionError?;
+    /**
+     * @param definition - Command definitions plus envelope, selector aliases and error wording.
+     * @throws An error for a blank or duplicate selector, a conflicting per-command discriminator
+     *   (it must match the envelope field and the command's own id).
+     */
     constructor(definition: InteractionProtocolDefinition<Value, Result, Args, Id>);
+    /** JSON schema for the model, expressed as a union of the per-command schemas. */
     get modelJsonSchema(): Record<string, unknown>;
+    /** Strict JSON schema for transport input, expressed as a union of per-command schemas. */
     get inputJsonSchema(): Record<string, unknown>;
+    /**
+     * Parse a payload and return only the result.
+     *
+     * @param value - Raw payload.
+     * @param args - Extra arguments forwarded to the command parser.
+     * @throws The same errors as `receive`.
+     */
     parse(value: Value, ...args: Args): Result;
-    /** Retain the selected command separately from a formatter's output. */
+    /**
+     * Retain the selected command id separately from a formatter's output.
+     *
+     * @param value - Raw payload; aliases are normalized when more than one selector is allowed.
+     * @param args - Extra arguments forwarded to the command parser.
+     * @returns The selected command id and its parsed result.
+     * @throws A configured error for a malformed or ambiguous selector, or the catalog's
+     *   command/mode/ownership errors.
+     */
     receive(value: Value, ...args: Args): {
         id: Id;
         result: Result;
     };
     private normalizeSelector;
 }
+/**
+ * Construct a protocol from one definition.
+ *
+ * @param definition - Commands, envelope and selector configuration.
+ * @returns A new protocol instance.
+ * @throws The same errors as the constructor.
+ */
 export declare function defineInteractionProtocol<Value extends object = Record<string, unknown>, Result = Value, Args extends unknown[] = [], Id extends string = string>(definition: InteractionProtocolDefinition<Value, Result, Args, Id>): InteractionProtocol<Value, Result, Args, Id>;
 export type { InteractionProtocolDefinition } from '../../structs/kits/interaction.js';

package/dist/esm/kits/interaction/transfer.js

@@ -1,10 +1,24 @@
+/**
+ * Interaction Kit: the web/AI payload family with selector normalization.
+ *
+ * Place in the package: part of the `interaction` Kit and its main entry. HTTP/SSE framing and
+ * the actual command execution remain separate ports; this class only validates the envelope,
+ * accepts selector aliases and delegates parsing to the sealed command catalog.
+ *
+ * Exports: `InteractionProtocol`, `defineInteractionProtocol`, and its definition type.
+ */
 import { pinCommandDefinition } from '../../utils/interaction-definition.js';
 import { breakWhile } from '../../utils/rules.js';
 import { defineCommandCatalog, CommandCatalog } from './commands.js';
 import { defineCommand, commandSchema } from './command.js';
 import { bindInteraction } from './handlers.js';
 import { INTERACTION_CATEGORIES } from '../../structs/kits/interaction.js';
-/** Web/AI payload family. HTTP/SSE framing and actual command execution remain separate ports. */
+/**
+ * Web/AI payload family. HTTP/SSE framing and actual command execution remain separate ports.
+ *
+ * Every command registered here gets the envelope's discriminator forced to its own id, so a
+ * payload cannot claim one command while carrying another command's data.
+ */
 export class InteractionProtocol {
     static define = defineInteractionProtocol;
     static Commands = CommandCatalog;
@@ -12,39 +26,79 @@ export class InteractionProtocol {
     static commandSchema = commandSchema;
     static bind = bindInteraction;
     static categories = INTERACTION_CATEGORIES;
+    /** Field carrying the command id in a payload. */
     commandField;
+    /** Accepted selector names: the command field first, then any declared aliases. */
     commandSelectors;
+    /** Sealed catalog of the compiled commands. */
     commands;
     selectionError;
+    /**
+     * @param definition - Command definitions plus envelope, selector aliases and error wording.
+     * @throws An error for a blank or duplicate selector, a conflicting per-command discriminator
+     *   (it must match the envelope field and the command's own id).
+     */
     constructor(definition) {
-        const { commands, commandField, commandAliases, modeField, unknownError, modeError, ownershipError } = definition;
+        const { commands, commandField, commandAliases, modeField, unknownError, modeError, ownershipError, } = definition;
         const { discriminator: _discriminator, modes: _modes, ownedFields: _ownedFields, ...envelope } = pinCommandDefinition(definition);
-        const selectionError = typeof definition.selectionError === 'function' ? definition.selectionError.bind(definition) : definition.selectionError;
+        const selectionError = typeof definition.selectionError === 'function'
+            ? definition.selectionError.bind(definition)
+            : definition.selectionError;
         breakWhile(!commandField.trim(), 'Missing transfer command field');
         this.commandField = commandField;
         this.commandSelectors = Object.freeze([commandField, ...(commandAliases ?? [])]);
         breakWhile([
-            { occur: () => this.commandSelectors.some(field => !field.trim()), error: 'Missing transfer selector' },
-            { occur: () => new Set(this.commandSelectors).size !== this.commandSelectors.length, error: 'Duplicate transfer selector' },
+            {
+                occur: () => this.commandSelectors.some((field) => !field.trim()),
+                error: 'Missing transfer selector',
+            },
+            {
+                occur: () => new Set(this.commandSelectors).size !== this.commandSelectors.length,
+                error: 'Duplicate transfer selector',
+            },
         ]);
         this.selectionError = selectionError;
         const registered = Object.fromEntries(Object.entries(commands).map(([id, value]) => {
             const command = pinCommandDefinition(value);
-            breakWhile(command.discriminator && (command.discriminator.field !== commandField || command.discriminator.value !== id), 'Conflicting transfer command discriminator');
+            breakWhile(command.discriminator &&
+                (command.discriminator.field !== commandField || command.discriminator.value !== id), 'Conflicting transfer command discriminator');
             return [id, { ...command, discriminator: { field: commandField, value: id } }];
         }));
         this.commands = defineCommandCatalog(registered, envelope, {
-            modeField, unknownError, modeError, ownershipError, tags: envelope.tags,
+            modeField,
+            unknownError,
+            modeError,
+            ownershipError,
+            tags: envelope.tags,
         });
     }
+    /** JSON schema for the model, expressed as a union of the per-command schemas. */
     get modelJsonSchema() {
-        return { anyOf: [...this.commands.values()].map(command => command.modelJsonSchema) };
+        return { anyOf: [...this.commands.values()].map((command) => command.modelJsonSchema) };
     }
-    get inputJsonSchema() { return { anyOf: [...this.commands.values()].map(command => command.inputJsonSchema) }; }
+    /** Strict JSON schema for transport input, expressed as a union of per-command schemas. */
+    get inputJsonSchema() {
+        return { anyOf: [...this.commands.values()].map((command) => command.inputJsonSchema) };
+    }
+    /**
+     * Parse a payload and return only the result.
+     *
+     * @param value - Raw payload.
+     * @param args - Extra arguments forwarded to the command parser.
+     * @throws The same errors as `receive`.
+     */
     parse(value, ...args) {
         return this.receive(value, ...args).result;
     }
-    /** Retain the selected command separately from a formatter's output. */
+    /**
+     * Retain the selected command id separately from a formatter's output.
+     *
+     * @param value - Raw payload; aliases are normalized when more than one selector is allowed.
+     * @param args - Extra arguments forwarded to the command parser.
+     * @returns The selected command id and its parsed result.
+     * @throws A configured error for a malformed or ambiguous selector, or the catalog's
+     *   command/mode/ownership errors.
+     */
     receive(value, ...args) {
         const normalized = this.normalizeSelector(value, args);
         const id = normalized[this.commandField];
@@ -54,14 +108,19 @@ export class InteractionProtocol {
         // Preserve the original no-alias parsing path; alias handling is an explicit host choice.
         if (this.commandSelectors.length === 1)
             return value;
-        const fail = () => typeof this.selectionError === 'function' ? this.selectionError(value, ...args)
-            : this.selectionError ?? new TypeError('Invalid transfer selector');
+        const fail = () => typeof this.selectionError === 'function'
+            ? this.selectionError(value, ...args)
+            : (this.selectionError ?? new TypeError('Invalid transfer selector'));
         breakWhile(!value || typeof value !== 'object' || Array.isArray(value), fail);
         const record = value;
-        const selectors = this.commandSelectors.filter(field => Object.hasOwn(record, field));
+        const selectors = this.commandSelectors.filter((field) => Object.hasOwn(record, field));
         breakWhile([
             { occur: () => selectors.length !== 1, error: fail, tags: ['selector-count'] },
-            { occur: () => typeof record[selectors[0]] !== 'string', error: fail, tags: ['selector-value'] },
+            {
+                occur: () => typeof record[selectors[0]] !== 'string',
+                error: fail,
+                tags: ['selector-value'],
+            },
         ]);
         const normalized = { ...record, [this.commandField]: record[selectors[0]] };
         if (selectors[0] !== this.commandField)
@@ -69,6 +128,13 @@ export class InteractionProtocol {
         return normalized;
     }
 }
+/**
+ * Construct a protocol from one definition.
+ *
+ * @param definition - Commands, envelope and selector configuration.
+ * @returns A new protocol instance.
+ * @throws The same errors as the constructor.
+ */
 export function defineInteractionProtocol(definition) {
     return new InteractionProtocol(definition);
 }

package/dist/esm/kits/knowledge/catalog.d.ts

@@ -1,3 +1,16 @@
 import type { KnowledgeCatalogOptions, KnowledgeDocument, KnowledgeCatalog } from '../../structs/kits/knowledge.js';
+/**
+ * Compile a knowledge catalog from document declarations.
+ *
+ * Reads are declarative: `document` returns the whole text, `self` returns exactly the named
+ * sections and `subtree` includes their nested sections. Section ids are validated up front,
+ * so a typo fails at read time instead of silently returning partial content.
+ *
+ * @param documents - Unique-id documents, each compiled into an immutable section tree.
+ * @param options - Optional `maxChars` budget and an observer for successful reads.
+ * @returns A frozen catalog extended with `sectionIds`, `assertSelection` and `read`.
+ * @throws TypeError For a duplicate document id, an invalid budget, an unknown document or
+ *   section, or a malformed selection; `RangeError` when the content exceeds `maxChars`.
+ */
 export declare function defineKnowledgeCatalog(documents: readonly KnowledgeDocument[], options?: KnowledgeCatalogOptions): KnowledgeCatalog;
 export type * from '../../structs/kits/knowledge.js';

package/dist/esm/kits/knowledge/catalog.js

@@ -1,6 +1,28 @@
+/**
+ * Knowledge Kit: compile documents into a sectioned catalog and read budgeted snapshots.
+ *
+ * Place in the package: part of the `knowledge` Kit. A snapshot carries text, revision and an
+ * opaque id; this module never fetches, authorizes or persists — it only resolves declared
+ * documents and sections.
+ *
+ * Exports: `defineKnowledgeCatalog`, and the knowledge document/read/snapshot types.
+ */
 import { readonlyCatalog } from '../../utils/catalog.js';
 import { compileKnowledgeDocument, knowledgeText } from './sections.js';
 import { observeSafely } from '../../utils/observer.js';
+/**
+ * Compile a knowledge catalog from document declarations.
+ *
+ * Reads are declarative: `document` returns the whole text, `self` returns exactly the named
+ * sections and `subtree` includes their nested sections. Section ids are validated up front,
+ * so a typo fails at read time instead of silently returning partial content.
+ *
+ * @param documents - Unique-id documents, each compiled into an immutable section tree.
+ * @param options - Optional `maxChars` budget and an observer for successful reads.
+ * @returns A frozen catalog extended with `sectionIds`, `assertSelection` and `read`.
+ * @throws TypeError For a duplicate document id, an invalid budget, an unknown document or
+ *   section, or a malformed selection; `RangeError` when the content exceeds `maxChars`.
+ */
 export function defineKnowledgeCatalog(documents, options = {}) {
     const { maxChars } = options, observe = options.observe?.bind(options);
     const catalog = new Map();
@@ -20,7 +42,9 @@ export function defineKnowledgeCatalog(documents, options = {}) {
         if (!read.selection || !['document', 'self', 'subtree'].includes(read.selection.mode))
             throw new TypeError('Invalid knowledge selection');
         if (read.selection.mode !== 'document') {
-            if (!Array.isArray(read.selection.sectionIds) || !read.selection.sectionIds.length || new Set(read.selection.sectionIds).size !== read.selection.sectionIds.length)
+            if (!Array.isArray(read.selection.sectionIds) ||
+                !read.selection.sectionIds.length ||
+                new Set(read.selection.sectionIds).size !== read.selection.sectionIds.length)
                 throw new TypeError('Invalid knowledge section selection');
             for (const id of read.selection.sectionIds)
                 if (!entry.sections.has(id))
@@ -28,21 +52,48 @@ export function defineKnowledgeCatalog(documents, options = {}) {
         }
         return { read, entry };
     };
-    const sectionIds = (id) => { const entry = catalog.get(id); if (!entry)
-        throw new TypeError(`Unknown knowledge document: ${id}`); return Object.freeze([...entry.sections.keys()]); };
-    const assertSelection = (read) => { resolve(read); };
-    return Object.freeze({ ...readonlyCatalog([...catalog.values()].map(entry => entry.document), id => new TypeError(`Unknown knowledge document: ${id}`)),
-        sectionIds, assertSelection,
+    const sectionIds = (id) => {
+        const entry = catalog.get(id);
+        if (!entry)
+            throw new TypeError(`Unknown knowledge document: ${id}`);
+        return Object.freeze([...entry.sections.keys()]);
+    };
+    const assertSelection = (read) => {
+        resolve(read);
+    };
+    return Object.freeze({
+        ...readonlyCatalog([...catalog.values()].map((entry) => entry.document), (id) => new TypeError(`Unknown knowledge document: ${id}`)),
+        sectionIds,
+        assertSelection,
         read(input) {
             const { read, entry } = resolve(input), raw = read.selection;
-            const selection = raw.mode === 'document' ? Object.freeze({ mode: 'document' }) : Object.freeze({ mode: raw.mode, sectionIds: Object.freeze([...raw.sectionIds]) });
-            const content = (selection.mode === 'document' ? knowledgeText(entry.document.parts) : selection.sectionIds.map(id => knowledgeText(entry.sections.get(id).parts, selection.mode === 'subtree')).join('\n\n')).trim();
+            const selection = raw.mode === 'document'
+                ? Object.freeze({ mode: 'document' })
+                : Object.freeze({ mode: raw.mode, sectionIds: Object.freeze([...raw.sectionIds]) });
+            const content = (selection.mode === 'document'
+                ? knowledgeText(entry.document.parts)
+                : selection.sectionIds
+                    .map((id) => knowledgeText(entry.sections.get(id).parts, selection.mode === 'subtree'))
+                    .join('\n\n')).trim();
             if (maxChars !== undefined && content.length > maxChars)
                 throw new RangeError('Knowledge selection exceeds its budget');
             // Preserve the existing opaque snapshot identity format.
-            const identitySelection = selection.mode === 'document' ? selection : { mode: selection.mode, sections: selection.sectionIds };
-            const snapshot = Object.freeze({ documentId: read.documentId, selection, revision: entry.document.revision, locale: entry.document.locale, content,
-                id: JSON.stringify([read.documentId, entry.document.revision, entry.document.locale, identitySelection]) });
+            const identitySelection = selection.mode === 'document'
+                ? selection
+                : { mode: selection.mode, sections: selection.sectionIds };
+            const snapshot = Object.freeze({
+                documentId: read.documentId,
+                selection,
+                revision: entry.document.revision,
+                locale: entry.document.locale,
+                content,
+                id: JSON.stringify([
+                    read.documentId,
+                    entry.document.revision,
+                    entry.document.locale,
+                    identitySelection,
+                ]),
+            });
             observeSafely(observe, snapshot);
             return snapshot;
         },

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

@@ -1,9 +1,20 @@
+/**
+ * Knowledge Kit entry: sectioned knowledge documents, snapshot reads and candidate publication.
+ *
+ * Place in the package: an optional App-side library. Documents, storage, authorization and
+ * provenance are App-owned; this directory owns the section tree, budgeted reads, opaque
+ * snapshot identity and the candidate/publish lifecycle over an atomic store revision.
+ *
+ * Exports: everything from `./catalog.js` and `./publication.js`, `parseKnowledgeDocument`, and
+ * the `Knowledge` namespace object.
+ */
 export * from './catalog.js';
 export { parseKnowledgeDocument } from './sections.js';
 import { defineKnowledgeCatalog } from './catalog.js';
 import { parseKnowledgeDocument } from './sections.js';
 import { defineKnowledgePublication } from './publication.js';
 export * from './publication.js';
+/** Namespace object for callers that prefer one import over named helpers. */
 export declare const Knowledge: Readonly<{
     defineKnowledgeCatalog: typeof defineKnowledgeCatalog;
     parseKnowledgeDocument: typeof parseKnowledgeDocument;

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

@@ -1,7 +1,22 @@
+/**
+ * Knowledge Kit entry: sectioned knowledge documents, snapshot reads and candidate publication.
+ *
+ * Place in the package: an optional App-side library. Documents, storage, authorization and
+ * provenance are App-owned; this directory owns the section tree, budgeted reads, opaque
+ * snapshot identity and the candidate/publish lifecycle over an atomic store revision.
+ *
+ * Exports: everything from `./catalog.js` and `./publication.js`, `parseKnowledgeDocument`, and
+ * the `Knowledge` namespace object.
+ */
 export * from './catalog.js';
 export { parseKnowledgeDocument } from './sections.js';
 import { defineKnowledgeCatalog } from './catalog.js';
 import { parseKnowledgeDocument } from './sections.js';
 import { defineKnowledgePublication } from './publication.js';
 export * from './publication.js';
-export const Knowledge = Object.freeze({ defineKnowledgeCatalog, parseKnowledgeDocument, defineKnowledgePublication });
+/** Namespace object for callers that prefer one import over named helpers. */
+export const Knowledge = Object.freeze({
+    defineKnowledgeCatalog,
+    parseKnowledgeDocument,
+    defineKnowledgePublication,
+});

package/dist/esm/kits/knowledge/publication.d.ts

@@ -1,4 +1,18 @@
 import type { KnowledgePublication, KnowledgePublicationOptions } from '../../structs/kits/knowledge-publication.js';
-/** Candidate preparation and publication share the same compiler and an App-owned atomic revision. */
+/**
+ * Compile a publication lifecycle over one App-owned atomic record.
+ *
+ * Candidate preparation and publication share the same compiler and an App-owned atomic
+ * revision. `propose` compiles and validates a candidate but leaves published documents alone;
+ * `publish` re-verifies sources and the base revision before swapping, so a stale candidate can
+ * never overwrite newer content.
+ *
+ * @param options - Store, authorization, provenance verification, clock, optional required
+ *   reads, capacity and retention bounds; handlers are bound to this options object.
+ * @returns A frozen publication exposing `read`, `propose`, `publish` and `reject`.
+ * @throws A configured error for invalid bounds, a malformed record or candidate, a revision
+ *   conflict, an expired candidate, exhausted capacity, a changed base revision, or a public
+ *   document whose content changed without a new revision.
+ */
 export declare function defineKnowledgePublication<App>(options: KnowledgePublicationOptions<App>): KnowledgePublication<App>;
 export type * from '../../structs/kits/knowledge-publication.js';

package/dist/esm/kits/knowledge/publication.js

@@ -1,14 +1,41 @@
+/**
+ * Knowledge Kit: candidate preparation, verification and atomic publication of documents.
+ *
+ * Place in the package: part of the `knowledge` Kit. The store, authorization and provenance
+ * checks are App ports; this module owns revision checking, candidate expiry and capacity,
+ * compilation of proposed documents and the compare-and-swap commit.
+ *
+ * Exports: `defineKnowledgePublication`, and the publication record/candidate/source types.
+ */
 import { defineKnowledgeCatalog } from './catalog.js';
 import { invocationId } from '../../utils/invocation.js';
 import { awaitWithSignal, awaitAssertion } from '../../utils/cancellation.js';
 import { breakWhile } from '../../utils/rules.js';
-/** Candidate preparation and publication share the same compiler and an App-owned atomic revision. */
+/**
+ * Compile a publication lifecycle over one App-owned atomic record.
+ *
+ * Candidate preparation and publication share the same compiler and an App-owned atomic
+ * revision. `propose` compiles and validates a candidate but leaves published documents alone;
+ * `publish` re-verifies sources and the base revision before swapping, so a stale candidate can
+ * never overwrite newer content.
+ *
+ * @param options - Store, authorization, provenance verification, clock, optional required
+ *   reads, capacity and retention bounds; handlers are bound to this options object.
+ * @returns A frozen publication exposing `read`, `propose`, `publish` and `reject`.
+ * @throws A configured error for invalid bounds, a malformed record or candidate, a revision
+ *   conflict, an expired candidate, exhausted capacity, a changed base revision, or a public
+ *   document whose content changed without a new revision.
+ */
 export function defineKnowledgePublication(options) {
     const load = options.store.load.bind(options.store), swap = options.store.compareAndSwap.bind(options.store);
     const authorize = options.authorize.bind(options), verify = options.verifySources.bind(options), now = options.now?.bind(options) ?? Date.now;
+    // Defaults keep one record small: at most 32 pending candidates, each valid for seven days.
     const maxCandidates = options.maxCandidates ?? 32, retention = options.candidateRetentionMs ?? 7 * 86400_000;
     const maxChars = options.maxReadChars, reads = structuredClone(options.requiredReads ?? []);
-    breakWhile(!Number.isSafeInteger(maxCandidates) || maxCandidates < 1 || !Number.isSafeInteger(retention) || retention < 1, 'Invalid publication bounds');
+    breakWhile(!Number.isSafeInteger(maxCandidates) ||
+        maxCandidates < 1 ||
+        !Number.isSafeInteger(retention) ||
+        retention < 1, 'Invalid publication bounds');
     const compile = (documents) => {
         const catalog = defineKnowledgeCatalog(documents, { maxChars });
         for (const read of reads)
@@ -21,24 +48,53 @@ export function defineKnowledgePublication(options) {
     const sourceSnapshot = (sources) => {
         const invalid = 'Invalid or expired knowledge provenance';
         breakWhile(!Array.isArray(sources) || !sources.length || sources.length > 32, invalid);
-        const snapshot = Array.from(sources, source => ({ id: source?.id, revision: source?.revision, expiresAtMs: source?.expiresAtMs }));
-        breakWhile(snapshot.some(source => typeof source.id !== 'string' || !source.id.trim()
-            || typeof source.revision !== 'string' || !source.revision.trim() || source.expiresAtMs !== undefined && (!Number.isFinite(source.expiresAtMs) || source.expiresAtMs <= now())), invalid);
+        const snapshot = Array.from(sources, (source) => ({
+            id: source?.id,
+            revision: source?.revision,
+            expiresAtMs: source?.expiresAtMs,
+        }));
+        breakWhile(snapshot.some((source) => typeof source.id !== 'string' ||
+            !source.id.trim() ||
+            typeof source.revision !== 'string' ||
+            !source.revision.trim() ||
+            (source.expiresAtMs !== undefined &&
+                (!Number.isFinite(source.expiresAtMs) || source.expiresAtMs <= now()))), invalid);
         return snapshot;
     };
     const read = async (context) => {
         context.signal.throwIfAborted();
         const record = structuredClone(await awaitWithSignal(load(), context.signal));
-        breakWhile(!record || !Number.isSafeInteger(record.revision) || record.revision < 0 || !Number.isSafeInteger(record.publishedRevision) || record.publishedRevision < 0 || record.publishedRevision > record.revision
-            || !Array.isArray(record.documents) || !Array.isArray(record.candidates) || record.candidates.length > maxCandidates, 'Invalid publication record');
-        breakWhile(new Set(record.candidates.map(item => item?.id)).size !== record.candidates.length || record.candidates.some(item => !item || typeof item.id !== 'string' || !item.id
-            || !Number.isSafeInteger(item.baseRevision) || item.baseRevision < 0 || item.baseRevision > record.publishedRevision
-            || !Number.isFinite(item.createdAtMs) || !Number.isFinite(item.expiresAtMs) || item.expiresAtMs <= item.createdAtMs
-            || !Array.isArray(item.sources) || !item.sources.length || item.sources.length > 32), 'Invalid knowledge candidate');
-        const compilationKey = JSON.stringify([record.revision, record.publishedRevision, record.documents, record.candidates.map(item => item.document)]);
+        breakWhile(!record ||
+            !Number.isSafeInteger(record.revision) ||
+            record.revision < 0 ||
+            !Number.isSafeInteger(record.publishedRevision) ||
+            record.publishedRevision < 0 ||
+            record.publishedRevision > record.revision ||
+            !Array.isArray(record.documents) ||
+            !Array.isArray(record.candidates) ||
+            record.candidates.length > maxCandidates, 'Invalid publication record');
+        breakWhile(new Set(record.candidates.map((item) => item?.id)).size !== record.candidates.length ||
+            record.candidates.some((item) => !item ||
+                typeof item.id !== 'string' ||
+                !item.id ||
+                !Number.isSafeInteger(item.baseRevision) ||
+                item.baseRevision < 0 ||
+                item.baseRevision > record.publishedRevision ||
+                !Number.isFinite(item.createdAtMs) ||
+                !Number.isFinite(item.expiresAtMs) ||
+                item.expiresAtMs <= item.createdAtMs ||
+                !Array.isArray(item.sources) ||
+                !item.sources.length ||
+                item.sources.length > 32), 'Invalid knowledge candidate');
+        const compilationKey = JSON.stringify([
+            record.revision,
+            record.publishedRevision,
+            record.documents,
+            record.candidates.map((item) => item.document),
+        ]);
         if (compilationKey !== compiledRecord) {
             for (const item of record.candidates)
-                compile([...record.documents.filter(doc => doc.id !== item.document.id), item.document]);
+                compile([...record.documents.filter((doc) => doc.id !== item.document.id), item.document]);
             compile(record.documents);
             compiledRecord = compilationKey;
         }
@@ -61,14 +117,19 @@ export function defineKnowledgePublication(options) {
         return record;
     };
     const replacement = (record, document) => {
-        const previous = record.documents.find(item => item.id === document.id);
-        breakWhile(!!previous && previous.revision === document.revision && JSON.stringify(previous) !== JSON.stringify(document), 'Changed knowledge needs a new document revision');
-        const documents = [...record.documents.filter(item => item.id !== document.id), structuredClone(document)];
+        const previous = record.documents.find((item) => item.id === document.id);
+        breakWhile(!!previous &&
+            previous.revision === document.revision &&
+            JSON.stringify(previous) !== JSON.stringify(document), 'Changed knowledge needs a new document revision');
+        const documents = [
+            ...record.documents.filter((item) => item.id !== document.id),
+            structuredClone(document),
+        ];
         compile(documents);
         return documents;
     };
     const candidate = (record, id) => {
-        const item = record.candidates.find(value => value.id === id);
+        const item = record.candidates.find((value) => value.id === id);
         breakWhile(!item || item.expiresAtMs <= now(), 'Knowledge candidate unavailable');
         return item;
     };
@@ -83,10 +144,16 @@ export function defineKnowledgePublication(options) {
             replacement(record, document);
             await awaitAssertion(() => verify(structuredClone(sources), context), context.signal, 'Knowledge provenance validation must return void');
             sourceSnapshot(sources);
-            const candidates = record.candidates.filter(item => item.expiresAtMs > now());
+            const candidates = record.candidates.filter((item) => item.expiresAtMs > now());
             breakWhile(candidates.length >= maxCandidates, 'Knowledge candidate capacity exhausted');
-            const item = { id: invocationId(), baseRevision: record.publishedRevision, document, sources,
-                createdAtMs: now(), expiresAtMs: Math.min(now() + retention, ...sources.map(source => source.expiresAtMs ?? Infinity)) };
+            const item = {
+                id: invocationId(),
+                baseRevision: record.publishedRevision,
+                document,
+                sources,
+                createdAtMs: now(),
+                expiresAtMs: Math.min(now() + retention, ...sources.map((source) => source.expiresAtMs ?? Infinity)),
+            };
             return commit(record, { ...record, revision: record.revision + 1, candidates: [...candidates, item] }, context, () => {
                 sourceSnapshot(sources);
                 breakWhile(item.expiresAtMs <= now(), 'Knowledge candidate expired');
@@ -101,8 +168,13 @@ export function defineKnowledgePublication(options) {
             await awaitAssertion(() => verify(structuredClone(sources), context), context.signal, 'Knowledge provenance validation must return void');
             sourceSnapshot(sources);
             const documents = replacement(record, item.document);
-            return commit(record, { ...record, revision: record.revision + 1, publishedRevision: record.publishedRevision + 1, documents,
-                candidates: record.candidates.filter(value => value.id !== item.id) }, context, () => {
+            return commit(record, {
+                ...record,
+                revision: record.revision + 1,
+                publishedRevision: record.publishedRevision + 1,
+                documents,
+                candidates: record.candidates.filter((value) => value.id !== item.id),
+            }, context, () => {
                 candidate(record, item.id);
                 sourceSnapshot(sources);
             });
@@ -112,7 +184,11 @@ export function defineKnowledgePublication(options) {
             await awaitAssertion(() => authorize('reject', context), context.signal, 'Knowledge publication authorization must return void');
             const record = await checked(revision, context);
             candidate(record, candidateId);
-            return commit(record, { ...record, revision: record.revision + 1, candidates: record.candidates.filter(item => item.id !== candidateId) }, context);
+            return commit(record, {
+                ...record,
+                revision: record.revision + 1,
+                candidates: record.candidates.filter((item) => item.id !== candidateId),
+            }, context);
         },
     });
 }

package/dist/esm/kits/knowledge/sections.d.ts

@@ -1,11 +1,34 @@
+/**
+ * Knowledge Kit: adapter and helpers for sectioned knowledge documents.
+ *
+ * Place in the package: part of the `knowledge` Kit. The anchor format is one text adapter;
+ * other sources build the same document contract directly. No I/O happens here.
+ *
+ * Exports: `parseKnowledgeDocument`, `compileKnowledgeDocument`, `knowledgeText`.
+ */
 import type { KnowledgeDocument, KnowledgePart, KnowledgeSection } from '../../structs/kits/knowledge.js';
-/** Paired, nestable anchors are one text adapter. Other sources supply the same document contract directly. */
+/**
+ * Paired, nestable anchors are one text adapter. Other sources supply the same document
+ * contract directly.
+ *
+ * @param input - Document identity, revision, optional locale and the anchored text.
+ * @returns A document whose parts alternate text strings and section objects.
+ * @throws TypeError For an unmatched closing anchor or an anchor left open at the end.
+ */
 export declare function parseKnowledgeDocument(input: {
     id: string;
     revision: string;
     text: string;
     locale?: string;
 }): KnowledgeDocument;
+/**
+ * Deep-copy and freeze a document while indexing its sections by id.
+ *
+ * @param document - Declared document, possibly sharing arrays or containing cycles.
+ * @returns The frozen document plus a map from section id to its frozen section.
+ * @throws TypeError For a missing identity or parts array, a sparse or cyclic tree, a blank
+ *   section id, or a duplicate section id.
+ */
 export declare function compileKnowledgeDocument(document: KnowledgeDocument): {
     document: Readonly<{
         id: string;
@@ -15,4 +38,11 @@ export declare function compileKnowledgeDocument(document: KnowledgeDocument): {
     }>;
     sections: Map<string, KnowledgeSection>;
 };
+/**
+ * Flatten parts into text.
+ *
+ * @param parts - Document parts; nested sections are traversed in order.
+ * @param subtree - When false, nested section text is skipped and only top-level text remains.
+ * @returns Concatenated text with separators left to the caller.
+ */
 export declare function knowledgeText(parts: readonly KnowledgePart[], subtree?: boolean): string;