@jangts/agent-core 0.1.1 → 0.2.0

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

@@ -1,9 +1,31 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.defineKnowledgeCatalog = defineKnowledgeCatalog;
+/**
+ * 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.
+ */
 const catalog_js_1 = require("../../utils/catalog.js");
 const sections_js_1 = require("./sections.js");
 const observer_js_1 = require("../../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`.
+ */
 function defineKnowledgeCatalog(documents, options = {}) {
     const { maxChars } = options, observe = options.observe?.bind(options);
     const catalog = new Map();
@@ -23,7 +45,9 @@ 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))
@@ -31,21 +55,48 @@ 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({ ...(0, catalog_js_1.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({
+        ...(0, catalog_js_1.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' ? (0, sections_js_1.knowledgeText)(entry.document.parts) : selection.sectionIds.map(id => (0, sections_js_1.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'
+                ? (0, sections_js_1.knowledgeText)(entry.document.parts)
+                : selection.sectionIds
+                    .map((id) => (0, sections_js_1.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,
+                ]),
+            });
             (0, observer_js_1.observeSafely)(observe, snapshot);
             return snapshot;
         },

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

@@ -15,6 +15,16 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Knowledge = exports.parseKnowledgeDocument = void 0;
+/**
+ * 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.
+ */
 __exportStar(require("./catalog.js"), exports);
 var sections_js_1 = require("./sections.js");
 Object.defineProperty(exports, "parseKnowledgeDocument", { enumerable: true, get: function () { return sections_js_1.parseKnowledgeDocument; } });
@@ -22,4 +32,9 @@ const catalog_js_1 = require("./catalog.js");
 const sections_js_2 = require("./sections.js");
 const publication_js_1 = require("./publication.js");
 __exportStar(require("./publication.js"), exports);
-exports.Knowledge = Object.freeze({ defineKnowledgeCatalog: catalog_js_1.defineKnowledgeCatalog, parseKnowledgeDocument: sections_js_2.parseKnowledgeDocument, defineKnowledgePublication: publication_js_1.defineKnowledgePublication });
+/** Namespace object for callers that prefer one import over named helpers. */
+exports.Knowledge = Object.freeze({
+    defineKnowledgeCatalog: catalog_js_1.defineKnowledgeCatalog,
+    parseKnowledgeDocument: sections_js_2.parseKnowledgeDocument,
+    defineKnowledgePublication: publication_js_1.defineKnowledgePublication,
+});

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

@@ -1,17 +1,44 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.defineKnowledgePublication = defineKnowledgePublication;
+/**
+ * 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.
+ */
 const catalog_js_1 = require("./catalog.js");
 const invocation_js_1 = require("../../utils/invocation.js");
 const cancellation_js_1 = require("../../utils/cancellation.js");
 const rules_js_1 = require("../../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.
+ */
 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 ?? []);
-    (0, rules_js_1.breakWhile)(!Number.isSafeInteger(maxCandidates) || maxCandidates < 1 || !Number.isSafeInteger(retention) || retention < 1, 'Invalid publication bounds');
+    (0, rules_js_1.breakWhile)(!Number.isSafeInteger(maxCandidates) ||
+        maxCandidates < 1 ||
+        !Number.isSafeInteger(retention) ||
+        retention < 1, 'Invalid publication bounds');
     const compile = (documents) => {
         const catalog = (0, catalog_js_1.defineKnowledgeCatalog)(documents, { maxChars });
         for (const read of reads)
@@ -24,24 +51,53 @@ function defineKnowledgePublication(options) {
     const sourceSnapshot = (sources) => {
         const invalid = 'Invalid or expired knowledge provenance';
         (0, rules_js_1.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 }));
-        (0, rules_js_1.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,
+        }));
+        (0, rules_js_1.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 (0, cancellation_js_1.awaitWithSignal)(load(), context.signal));
-        (0, rules_js_1.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');
-        (0, rules_js_1.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)]);
+        (0, rules_js_1.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');
+        (0, rules_js_1.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;
         }
@@ -64,14 +120,19 @@ function defineKnowledgePublication(options) {
         return record;
     };
     const replacement = (record, document) => {
-        const previous = record.documents.find(item => item.id === document.id);
-        (0, rules_js_1.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);
+        (0, rules_js_1.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);
         (0, rules_js_1.breakWhile)(!item || item.expiresAtMs <= now(), 'Knowledge candidate unavailable');
         return item;
     };
@@ -86,10 +147,16 @@ function defineKnowledgePublication(options) {
             replacement(record, document);
             await (0, cancellation_js_1.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());
             (0, rules_js_1.breakWhile)(candidates.length >= maxCandidates, 'Knowledge candidate capacity exhausted');
-            const item = { id: (0, invocation_js_1.invocationId)(), baseRevision: record.publishedRevision, document, sources,
-                createdAtMs: now(), expiresAtMs: Math.min(now() + retention, ...sources.map(source => source.expiresAtMs ?? Infinity)) };
+            const item = {
+                id: (0, invocation_js_1.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);
                 (0, rules_js_1.breakWhile)(item.expiresAtMs <= now(), 'Knowledge candidate expired');
@@ -104,8 +171,13 @@ function defineKnowledgePublication(options) {
             await (0, cancellation_js_1.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);
             });
@@ -115,7 +187,11 @@ function defineKnowledgePublication(options) {
             await (0, cancellation_js_1.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/cjs/kits/knowledge/sections.js

@@ -3,7 +3,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseKnowledgeDocument = parseKnowledgeDocument;
 exports.compileKnowledgeDocument = compileKnowledgeDocument;
 exports.knowledgeText = knowledgeText;
-/** 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.
+ */
 function parseKnowledgeDocument(input) {
     const parts = [];
     const stack = [];
@@ -29,6 +36,14 @@ function parseKnowledgeDocument(input) {
     parts.push(input.text.slice(offset));
     return { id: input.id, revision: input.revision, locale: input.locale, parts };
 }
+/**
+ * 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.
+ */
 function compileKnowledgeDocument(document) {
     if (!document.id?.trim() || !document.revision?.trim() || !Array.isArray(document.parts))
         throw new TypeError('Invalid knowledge document');
@@ -40,7 +55,7 @@ function compileKnowledgeDocument(document) {
         ancestors.add(parts);
         // Visit empty array slots too: a sparse tree is not valid knowledge, and
         // must not share a serialized cache identity with an explicit null part.
-        const result = Array.from(parts, part => {
+        const result = Array.from(parts, (part) => {
             if (typeof part === 'string')
                 return part;
             if (!part || typeof part.id !== 'string' || !part.id.trim() || sections.has(part.id))
@@ -54,9 +69,23 @@ function compileKnowledgeDocument(document) {
         ancestors.delete(parts);
         return Object.freeze(result);
     }
-    const value = Object.freeze({ id: document.id, revision: document.revision, locale: document.locale, parts: copy(document.parts) });
+    const value = Object.freeze({
+        id: document.id,
+        revision: document.revision,
+        locale: document.locale,
+        parts: copy(document.parts),
+    });
     return { document: value, sections };
 }
+/**
+ * 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.
+ */
 function knowledgeText(parts, subtree = true) {
-    return parts.map(part => typeof part === 'string' ? part : subtree ? knowledgeText(part.parts) : '').join('');
+    return parts
+        .map((part) => (typeof part === 'string' ? part : subtree ? knowledgeText(part.parts) : ''))
+        .join('');
 }

package/dist/cjs/kits/normalization.js

@@ -3,20 +3,53 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Normalization = void 0;
 exports.defineNormalization = defineNormalization;
 exports.uniqueBy = uniqueBy;
+/**
+ * Normalization Kit: ordered synchronous value transformations and stable deduplication.
+ *
+ * Place in the package: an optional App-side helper for cleaning model or transport input
+ * before it reaches business logic. Replacement, completion detection and input ownership stay
+ * explicit; this module never mutates the caller's arrays.
+ *
+ * Exports: `defineNormalization`, `uniqueBy`, `Normalization`, and the step/option types.
+ */
 const synchronous_js_1 = require("../utils/synchronous.js");
 const rules_js_1 = require("../utils/rules.js");
-/** Ordered value transformations; replacement, completion and input ownership are explicit. */
+/**
+ * Compile an ordered normalization pipeline.
+ *
+ * Steps run in declaration order. Each step may be skipped by its `when` predicate, receives
+ * the value produced by the previous step, and `isComplete` can stop the walk early, so the
+ * usual contract is "first completion wins" rather than "always run everything".
+ *
+ * @param definitions - Steps with unique non-blank ids and a synchronous `normalize` handler.
+ * @param options - Optional completion predicate; bound to the options object.
+ * @returns A frozen pipeline exposing `steps` (ids plus handlers) and `normalize`.
+ * @throws TypeError At construction for blank/duplicate ids or a missing handler; from
+ *   `normalize` when a predicate or handler returns a thenable or a non-boolean.
+ */
 function defineNormalization(definitions, options = {}) {
     const isComplete = options.isComplete?.bind(options);
     const predicate = (value) => (0, synchronous_js_1.booleanResult)(value, 'Normalization predicates must be synchronous', 'Normalization predicates must return boolean');
     const ids = new Set();
-    const steps = Object.freeze(definitions.map(step => {
+    const steps = Object.freeze(definitions.map((step) => {
         (0, rules_js_1.breakWhile)([
-            { occur: () => !step.id.trim() || ids.has(step.id), error: 'Invalid or duplicate normalization step', tags: ['id'] },
-            { occur: () => typeof step.normalize !== 'function', error: 'Missing normalization handler', tags: ['handler'] },
+            {
+                occur: () => !step.id.trim() || ids.has(step.id),
+                error: 'Invalid or duplicate normalization step',
+                tags: ['id'],
+            },
+            {
+                occur: () => typeof step.normalize !== 'function',
+                error: 'Missing normalization handler',
+                tags: ['handler'],
+            },
         ]);
         ids.add(step.id);
-        return Object.freeze({ id: step.id, when: step.when?.bind(step), normalize: step.normalize.bind(step) });
+        return Object.freeze({
+            id: step.id,
+            when: step.when?.bind(step),
+            normalize: step.normalize.bind(step),
+        });
     }));
     return Object.freeze({
         steps,
@@ -32,10 +65,20 @@ function defineNormalization(definitions, options = {}) {
         },
     });
 }
-/** Stable deduplication preserves the original values; the host chooses equivalence. */
+/**
+ * Stable deduplication preserves the original values; the host chooses equivalence.
+ *
+ * The first occurrence of each key wins and the input order is kept, so callers can rely on
+ * deduplication never reordering their list.
+ *
+ * @param values - Values in the order to retain.
+ * @param key - Equivalence selector.
+ * @param initial - Keys already treated as seen, for example those owned by another batch.
+ * @returns The retained values as a new array.
+ */
 function uniqueBy(values, key, initial = []) {
     const seen = new Set(initial);
-    return values.filter(value => {
+    return values.filter((value) => {
         const id = key(value);
         if (seen.has(id))
             return false;
@@ -43,4 +86,5 @@ function uniqueBy(values, key, initial = []) {
         return true;
     });
 }
+/** Namespace object for callers that prefer one import over named helpers. */
 exports.Normalization = Object.freeze({ defineNormalization, uniqueBy });

package/dist/cjs/kits/policies.js

@@ -3,30 +3,72 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Policies = void 0;
 exports.definePolicySet = definePolicySet;
 exports.defineRecoveryChain = defineRecoveryChain;
+/**
+ * Policies Kit: assess which declared policies apply, and run ordered recovery handlers.
+ *
+ * Place in the package: an optional App-side library for policy and recovery tables. Policy
+ * predicates, recovery handlers, kinds and descriptions are App configuration; this module
+ * owns registration checks, evaluation order and outcome validation.
+ *
+ * Exports: `definePolicySet`, `defineRecoveryChain`, `Policies`, and the policy types.
+ */
 const catalog_js_1 = require("../utils/catalog.js");
 const synchronous_js_1 = require("../utils/synchronous.js");
 const rules_js_1 = require("../utils/rules.js");
-/** Collect every matching reason; a configured mode cannot silently override a mandatory policy. */
+/**
+ * Compile a policy set that reports every matching reason.
+ *
+ * Collect every matching reason; a configured mode cannot silently override a mandatory
+ * policy. `assess` returns the matched ids and deduplicated kinds rather than a single verdict,
+ * so callers keep the ordering information they need for messages and diagnostics.
+ *
+ * @param definitions - Policies with unique ids, descriptions and a synchronous `when`.
+ * @returns A frozen catalog extended with `assess(input)`.
+ * @throws TypeError For blank/duplicate ids, a blank description, a missing `when`, or a
+ *   predicate that is not synchronous boolean.
+ */
 function definePolicySet(definitions) {
     const catalog = registerPolicies(definitions, 'when');
     return Object.freeze({
-        ...(0, catalog_js_1.readonlyCatalog)(catalog, id => new TypeError(`Unknown policy: ${id}`)),
+        ...(0, catalog_js_1.readonlyCatalog)(catalog, (id) => new TypeError(`Unknown policy: ${id}`)),
         assess(input) {
-            const matched = catalog.filter(policy => booleanMatch(policy.when(input)));
-            return { required: matched.length > 0, reasons: matched.map(policy => policy.id), kinds: [...new Set(matched.map(policy => policy.kind))] };
+            const matched = catalog.filter((policy) => booleanMatch(policy.when(input)));
+            return {
+                required: matched.length > 0,
+                reasons: matched.map((policy) => policy.id),
+                kinds: [...new Set(matched.map((policy) => policy.kind))],
+            };
         },
     });
 }
-/** A handler reports whether it handled the input; handled undefined values remain explicit. */
+/**
+ * Compile an ordered recovery chain.
+ *
+ * A handler reports whether it handled the input; handled undefined values remain explicit.
+ * The first handler that reports `handled` ends the walk, so declaration order is the
+ * precedence, and `{ handled: false }` is the only way to fall through.
+ *
+ * @param definitions - Recovery handlers with unique ids, descriptions and `tryRecover`.
+ * @returns A frozen catalog extended with `tryRecover(input)`.
+ * @throws TypeError For blank/duplicate ids, a missing handler, or an outcome that lacks a
+ *   boolean `handled` or omits `value` while claiming to have handled the input.
+ */
 function defineRecoveryChain(definitions) {
-    const catalog = registerPolicies(definitions, 'tryRecover').map(definition => {
-        return Object.freeze({ id: definition.id, description: definition.description, tryRecover(input) {
+    const catalog = registerPolicies(definitions, 'tryRecover').map((definition) => {
+        return Object.freeze({
+            id: definition.id,
+            description: definition.description,
+            tryRecover(input) {
                 const value = (0, synchronous_js_1.synchronous)(definition.tryRecover(input), 'Recovery handlers must be synchronous');
                 const result = value;
-                if (!result || typeof result !== 'object' || typeof result.handled !== 'boolean' || (result.handled && !('value' in result)))
+                if (!result ||
+                    typeof result !== 'object' ||
+                    typeof result.handled !== 'boolean' ||
+                    (result.handled && !('value' in result)))
                     throw new TypeError('Invalid recovery outcome');
                 return result;
-            } });
+            },
+        });
     });
     const tryRecover = (input) => {
         for (const policy of catalog) {
@@ -36,20 +78,42 @@ function defineRecoveryChain(definitions) {
         }
         return { handled: false };
     };
-    return Object.freeze({ ...(0, catalog_js_1.readonlyCatalog)(catalog, id => new TypeError(`Unknown recovery policy: ${id}`)), tryRecover });
+    return Object.freeze({
+        ...(0, catalog_js_1.readonlyCatalog)(catalog, (id) => new TypeError(`Unknown recovery policy: ${id}`)),
+        tryRecover,
+    });
 }
 function registerPolicies(definitions, handler) {
     const ids = new Set();
-    return Object.freeze(definitions.map(definition => {
+    return Object.freeze(definitions.map((definition) => {
         (0, rules_js_1.breakWhile)([
-            { occur: () => !definition.id.trim() || !definition.description.trim(), error: 'Invalid policy declaration', tags: ['metadata'] },
-            { occur: () => ids.has(definition.id), error: () => `Duplicate policy: ${definition.id}`, tags: ['id'] },
-            { occur: () => typeof definition[handler] !== 'function', error: () => `Missing policy handler: ${definition.id}`, tags: ['handler'] },
+            {
+                occur: () => !definition.id.trim() || !definition.description.trim(),
+                error: 'Invalid policy declaration',
+                tags: ['metadata'],
+            },
+            {
+                occur: () => ids.has(definition.id),
+                error: () => `Duplicate policy: ${definition.id}`,
+                tags: ['id'],
+            },
+            {
+                occur: () => typeof definition[handler] !== 'function',
+                error: () => `Missing policy handler: ${definition.id}`,
+                tags: ['handler'],
+            },
         ], ['agent-core', 'policy-registration']);
         ids.add(definition.id);
-        return Object.freeze({ ...definition, id: definition.id, description: definition.description, ...('kind' in definition ? { kind: definition.kind } : {}), [handler]: definition[handler].bind(definition) });
+        return Object.freeze({
+            ...definition,
+            id: definition.id,
+            description: definition.description,
+            ...('kind' in definition ? { kind: definition.kind } : {}),
+            [handler]: definition[handler].bind(definition),
+        });
     }));
 }
+/** Namespace object for callers that prefer one import over named helpers. */
 exports.Policies = Object.freeze({ definePolicySet, defineRecoveryChain });
 function booleanMatch(value) {
     return (0, synchronous_js_1.booleanResult)(value, 'Policy predicates must be synchronous', 'Policy predicates must return boolean');