@jangts/agent-core 0.1.1 → 0.2.1

package/dist/esm/structs/kits/intents/catalog.d.ts

@@ -1,23 +1,42 @@
+/**
+ * Agent catalog contract for the Intents Kit.
+ *
+ * Place in the package: an optional App-side projection that describes which intents, scopes and
+ * tools are available to one request. The ports read the App's real registries, so no parallel
+ * capability list exists; this module only declares what the catalog needs from them.
+ *
+ * Exports: `CatalogIntent`, `CatalogScope`, `CatalogTask`, `CatalogTool`, `DescribedTool`,
+ * `AgentCatalogPorts`.
+ */
+/** Intent as the catalog sees it: an id plus its declared steps. */
 export interface CatalogIntent<Id extends string = string> {
     readonly id: Id;
     readonly steps: readonly string[];
 }
+/** Scope as the catalog sees it: an id plus the tools it may use. */
 export interface CatalogScope {
     readonly id: string;
     readonly toolIds: readonly string[];
 }
+/** The task currently accepted for the request, used to narrow the catalog. */
 export interface CatalogTask<Id extends string = string> {
     readonly intentId: Id;
+    /** Selected scope; `null` or `undefined` means a scope has not been chosen yet. */
     readonly scopeId?: string | null;
 }
+/** Tool facts the catalog needs, independent of lifecycle details. */
 export interface CatalogTool<App> {
     readonly id: string;
+    /** Intent ids the tool serves, or `'all'` when it is always available. */
     readonly intentIds: 'all' | readonly string[];
+    /** Returns whether the tool may run for this App state; absent means always available. */
     available?(app: App): boolean;
+    /** Invocation step, when the tool participates in the step-based lifecycle. */
     readonly invocation?: {
         readonly step: string;
     };
 }
+/** Model- or host-facing description of one tool. */
 export interface DescribedTool {
     readonly id: string;
     readonly kind: string;
@@ -26,16 +45,23 @@ export interface DescribedTool {
     readonly effect: string;
     readonly intentIds: readonly string[];
 }
+/** Ports the catalog reads from the App's registries. */
 export interface AgentCatalogPorts<App, Id extends string, Intent extends CatalogIntent<Id>, Scope extends CatalogScope> {
+    /** All registered intent ids, before availability filtering. */
     intentIds(): readonly Id[];
+    /** Registered intents, optionally narrowed to `ids`. */
     intents(ids?: readonly Id[]): readonly Intent[];
+    /** Registered scopes for the given intent ids (all scopes when omitted). */
     scopes(ids?: readonly Id[]): readonly Scope[];
+    /** When not `false`, the catalog is narrowed to `currentTask`; defaults to restriction on. */
     readonly restrictToTask?: boolean;
+    /** Task accepted for this request, if any. */
     currentTask(app: App): CatalogTask<Id> | undefined;
     readonly tools: {
         values(): Iterable<CatalogTool<App>>;
         has(id: string): boolean;
         supportsIntent(id: Id, app: App): boolean;
+        /** Describes tools for an audience (for example `'model'`); must be synchronous. */
         describe(audience?: string, app?: App): readonly DescribedTool[];
     };
 }

package/dist/esm/structs/kits/intents/registry.d.ts

@@ -1,41 +1,75 @@
+/**
+ * Intent registry contract for the Intents Kit.
+ *
+ * Place in the package: an optional App-side catalog of model intents. An intent names its ordered
+ * steps and optional App-declared policies; the registry checks identity, allowed vocabulary,
+ * duplicate ids and sealing, while the meaning of each vocabulary value stays with the App.
+ *
+ * Exports: `IntentDefinition`, `IntentRegistryPolicy`, `IntentDescription`, `IntentId`,
+ * `RegisteredIntent`.
+ */
 import type { BreakReason } from '../../utils/rules.js';
 import type { RegistrationProjection } from '../../../utils/registration.js';
+/** One declarable intent. */
 export interface IntentDefinition {
+    /** Unique intent id, matched against the policy's `idPattern` when configured. */
     id: string;
+    /** Non-blank model-facing description. */
     description: string;
+    /** Ordered step ids; non-empty, unique and, when `policy.steps` is set, drawn from it. */
     steps: readonly string[];
+    /** App-declared scope-mode name; validated against `policy.scopeModes` when that is set. */
     scopePolicy?: string;
+    /** App-declared target-mode name; validated against `policy.targetModes` when that is set. */
     targetPolicy?: string;
+    /** App-declared context tier; validated against `policy.contextTiers` when that is set. */
     contextTier?: string;
+    /** App-declared planning action; validated against `policy.actions` when that is set. */
     planIntent?: string;
+    /** Additional actions the intent may use; must be unique. */
     auxiliaryActions?: readonly string[];
+    /** App-declared handoff marker; validated against `policy.handoffValues` when that is set. */
     preparedHandoff?: unknown;
 }
+/** Registration rules for one intent registry. */
 export interface IntentRegistryPolicy<Definition extends IntentDefinition> {
+    /** Pattern every intent id must match. */
     readonly idPattern?: RegExp;
+    /** Allowed `scopePolicy` values; `undefined` accepts any value. */
     readonly scopeModes?: readonly string[];
+    /** Allowed `targetPolicy` values; `undefined` accepts any value. */
     readonly targetModes?: readonly string[];
+    /** Allowed `contextTier` values; `undefined` accepts any value. */
     readonly contextTiers?: readonly string[];
+    /** Allowed `planIntent` values; `undefined` accepts any value. */
     readonly actions?: readonly string[];
+    /** Allowed step ids; `undefined` accepts any non-empty step. */
     readonly steps?: readonly string[];
+    /** Allowed `preparedHandoff` values; `undefined` accepts any value. */
     readonly handoffValues?: readonly unknown[];
+    /** Extra App assertion, called after the built-in checks; must return void synchronously. */
     readonly assertDefinition?: (definition: Definition) => void;
+    /** Diagnostic tags attached to registration rejections. */
     readonly tags?: readonly string[];
     readonly errors?: {
         readonly sealed?: BreakReason;
         readonly invalid?: BreakReason;
+        /** Builds the duplicate-id rejection; receives the intent id. */
         readonly duplicate?: (goal: string) => Error | string;
     };
 }
+/** Registered intent with its steps widened to the definition's step literals. */
 export type IntentDescription<Definition extends IntentDefinition> = Omit<RegisteredIntent<Definition>, 'steps'> & {
     steps: Definition['steps'][number][];
 };
+/** Union of the ids of a definition set, or `string` when it cannot be narrowed. */
 export type IntentId<Definition> = Definition extends {
     id: infer Id extends string;
 } ? Id : string;
 type RegisteredIntentLists<Definition extends IntentDefinition> = {
     readonly [Key in keyof Pick<Definition, Extract<keyof Definition, 'steps' | 'auxiliaryActions'>>]: Readonly<Definition[Key]>;
 };
+/** Frozen registration view: list fields are frozen copies, helper methods are dropped. */
 export type RegisteredIntent<Definition extends IntentDefinition> = Readonly<Omit<RegistrationProjection<Definition, IntentDefinition>, 'steps' | 'auxiliaryActions'> & RegisteredIntentLists<Definition> & {
     id: Definition['id'];
     steps: Readonly<Definition['steps']>;

package/dist/esm/structs/kits/intents/scopes.d.ts

@@ -1,32 +1,63 @@
+/**
+ * Scope registry contract for the Intents Kit.
+ *
+ * Place in the package: an optional App-side catalog of scope definitions. A scope binds an intent
+ * to the sources and tools it may use; the registry validates identity, aliases, required bindings
+ * and allowed categories, while resolution and business meaning stay with the App.
+ *
+ * Exports: `ScopeDefinition`, `ScopeRegistryPolicy`, `RegisteredScopeEvidence`, `RegisteredScope`,
+ * `ScopeDescription`.
+ */
 import type { EvidenceRequirement } from '../evidence.js';
 import type { BreakReason } from '../../utils/rules.js';
 import type { RegistrationData, RegistrationProjection } from '../../../utils/registration.js';
+/** One declarable scope. Ids and aliases share one namespace and must be unique. */
 export interface ScopeDefinition {
+    /** Unique scope id, matched against the policy's `idPattern` when configured. */
     id: string;
+    /** Non-blank description. */
     description: string;
+    /** Scope category; validated against `policy.categories` when that is set. */
     category: string;
+    /** Intents this scope serves; required when the policy sets `requireIntents`. */
     intentIds?: readonly string[];
+    /** Referenced query scopes, resolved by the App. */
     queryScopeIds?: readonly string[];
+    /** Referenced knowledge topics, resolved by the App. */
     knowledgeTopicIds?: readonly string[];
+    /** Referenced tool ids; required when the policy sets `requireTools`. */
     toolIds?: readonly string[];
+    /** Alternate names accepted by lookup; must not collide with ids or other aliases. */
     aliases?: readonly string[];
+    /** App-declared context tier, passed through for the App's own policy. */
     contextTier?: string;
+    /** Evidence requirements that must be satisfied before this scope may answer. */
     evidence?: readonly EvidenceRequirement[];
 }
+/** Registration rules for one scope registry. */
 export interface ScopeRegistryPolicy<Definition extends ScopeDefinition> {
+    /** Require at least one intent id per scope. */
     readonly requireIntents?: boolean;
+    /** Require at least one query scope or knowledge topic per scope. */
     readonly requireSources?: boolean;
+    /** Require at least one tool id per scope. */
     readonly requireTools?: boolean;
+    /** Pattern every id and alias must match. */
     readonly idPattern?: RegExp;
+    /** Allowed `category` values; `undefined` accepts any value. */
     readonly categories?: readonly string[];
+    /** Extra App assertion, called after the built-in checks; must return void synchronously. */
     readonly assertDefinition?: (definition: Definition) => void;
+    /** Replaces the default intent membership test; must return boolean synchronously. */
     readonly acceptsIntent?: (definition: Readonly<Definition>, goal: string) => boolean;
+    /** Diagnostic tags attached to registration rejections. */
     readonly tags?: readonly string[];
     readonly errors?: {
         readonly sealed?: BreakReason;
         readonly invalid?: BreakReason;
     };
 }
+/** Registered evidence entry: public data only, frozen by the registry. */
 export type RegisteredScopeEvidence<Definition extends ScopeDefinition> = Readonly<RegistrationData<NonNullable<Definition['evidence']>[number]>>;
 type ScopeListKey = 'intentIds' | 'queryScopeIds' | 'knowledgeTopicIds' | 'toolIds' | 'aliases';
 type RegisteredScopeLists<Definition extends ScopeDefinition> = {
@@ -35,10 +66,14 @@ type RegisteredScopeLists<Definition extends ScopeDefinition> = {
 type RegisteredEvidenceList<Values extends readonly EvidenceRequirement[]> = {
     readonly [Index in keyof Values]: Readonly<RegistrationData<Values[Index]>>;
 };
-type ScopeEvidenceList<Definition extends ScopeDefinition> = [NonNullable<Definition['evidence']>] extends [never] ? readonly [] : NonNullable<Definition['evidence']> extends readonly EvidenceRequirement[] ? RegisteredEvidenceList<NonNullable<Definition['evidence']>> : readonly RegisteredScopeEvidence<Definition>[];
+type ScopeEvidenceList<Definition extends ScopeDefinition> = [
+    NonNullable<Definition['evidence']>
+] extends [never] ? readonly [] : NonNullable<Definition['evidence']> extends readonly EvidenceRequirement[] ? RegisteredEvidenceList<NonNullable<Definition['evidence']>> : readonly RegisteredScopeEvidence<Definition>[];
+/** Frozen registration view: every list is a frozen copy, evidence entries are projected. */
 export type RegisteredScope<Definition extends ScopeDefinition> = Readonly<Omit<RegistrationProjection<Definition, ScopeDefinition>, ScopeListKey | 'evidence'> & RegisteredScopeLists<Definition> & {
     evidence: ScopeEvidenceList<Definition>;
 }>;
+/** Plain description with mutable arrays, for documentation and model-facing catalogs. */
 export type ScopeDescription<Definition extends ScopeDefinition> = Omit<RegisteredScope<Definition>, 'intentIds' | 'queryScopeIds' | 'knowledgeTopicIds' | 'toolIds' | 'aliases' | 'evidence'> & {
     intentIds: string[];
     queryScopeIds: string[];

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

@@ -1,85 +1,148 @@
+/**
+ * Interaction protocol contract: the validated payload family exchanged with a client.
+ *
+ * Place in the package: an optional App-side library for command-shaped values. A declaration
+ * produces both the model-visible schema and the runtime input schema from one field list, so
+ * validation, routing and documentation cannot drift. HTTP/SSE framing and command execution stay
+ * in separate ports; nothing here executes a registered tool.
+ *
+ * Exports: `ProtocolField`, `InteractionCategory`, `INTERACTION_CATEGORIES`,
+ * `InteractionDescriptor`, `InteractionHandlers`, `ProtocolReason`, `ProtocolPredicate`,
+ * `ProtocolCheck`, `CommandDefinition`, `Command`, `CommandCatalogOptions`,
+ * `InteractionProtocolDefinition`, `ProtocolShape`, `RegisteredProtocol`.
+ */
 /** Field presence, schema and ownership are declared together; schemas describe model input. */
 export interface ProtocolField {
+    /** Property schema; missing means the provider accepts any value. */
     readonly jsonSchema?: Readonly<Record<string, unknown>>;
+    /** Required on input; such a field may be optional for the model. */
     readonly required?: boolean;
+    /** Required from the model; such a field may be optional on input. */
     readonly modelRequired?: boolean;
+    /** Written by the program, never supplied by the model. */
     readonly owned?: boolean;
 }
 /** Interaction purpose, never an authorization level or an assertion of execution success. */
 export type InteractionCategory = 'query' | 'action' | 'presentation' | 'input' | 'receipt';
+/** Frozen list of accepted categories, used for validation and enumeration. */
 export declare const INTERACTION_CATEGORIES: readonly InteractionCategory[];
+/** Catalog metadata for one command, independent of its field shape. */
 export interface InteractionDescriptor {
     readonly id: string;
+    /** Declared purpose; validated against the frozen category list. */
     readonly category?: InteractionCategory;
     readonly description?: string;
+    /** Marks a command that ends the interaction. */
     readonly terminal?: boolean;
+    /** App-declared modes in which the command is available. */
     readonly modes?: readonly string[];
 }
+/** Handler map keyed by command id; each handler receives the parsed value and App context. */
 export type InteractionHandlers<Id extends string, Value, Context, Output> = Readonly<Record<Id, (value: Value, context: Context) => Output>>;
+/** Lazy rejection wording: a fixed message, a pre-built error, or a factory bound to the value. */
 export type ProtocolReason<Value, Args extends unknown[]> = Error | string | ((value: Value, ...args: Args) => Error | string);
+/** Predicate evaluated during validation; any truthy result counts as a failure. */
 export type ProtocolPredicate<Value, Args extends unknown[]> = (value: Value, ...args: Args) => unknown;
+/** One declarative rejection rule. */
 export interface ProtocolCheck<Value, Args extends unknown[]> {
+    /** Runs the check only when it returns true; must be synchronous. */
     readonly when?: (value: Value, ...args: Args) => boolean;
+    /** Failing predicate or ordered OR-list; evaluation stops at the first failure. */
     readonly occur: ProtocolPredicate<Value, Args> | readonly ProtocolPredicate<Value, Args>[];
+    /** Rejection wording; omitted means a default `TypeError`. */
     readonly error?: ProtocolReason<Value, Args>;
+    /** Diagnostic tags attached to the rejection. */
     readonly tags?: readonly string[];
 }
+/** Declarative command shape before compilation. */
 export interface CommandDefinition<Value extends object, Result = Value, Args extends unknown[] = []> {
+    /** Declared purpose; validated against the frozen category list. */
     readonly category?: InteractionCategory;
+    /** Protocol version, used to reject incompatible registrations. */
     readonly version?: number;
     readonly description?: string;
+    /** Marks a command that ends the interaction. */
     readonly terminal?: boolean;
+    /** Constant field identifying the command; its value is forced to the command id. */
     readonly discriminator?: {
         readonly field: string;
         readonly value: string;
     };
+    /** Field declarations by name, or an ordered list of field names. */
     readonly fields: Readonly<Record<string, ProtocolField>> | readonly string[];
+    /** Fields the program writes; may name fields not declared in `fields`. */
     readonly ownedFields?: readonly string[];
+    /** Whether fields outside the declaration are rejected; defaults to the compiler policy. */
     readonly additionalProperties?: boolean;
     /** 'defined' rejects an explicitly undefined optional property; 'own' preserves its presence. */
     readonly optionalPresence?: 'own' | 'defined';
+    /** App-declared modes in which the command is available. */
     readonly modes?: readonly string[];
+    /** Rejection wording for the command as a whole. */
     readonly error?: ProtocolReason<Value, Args>;
+    /** Diagnostic tags attached to rejections from this command. */
     readonly tags?: readonly string[];
+    /** Declarative rejection rules, evaluated in order after the structural checks. */
     readonly checks?: readonly ProtocolCheck<Value, Args>[];
     /** Domain checks/bindings only; invoked after structural and declarative checks. */
     readonly refine?: (value: Value, ...args: Args) => void;
+    /** Formats the validated value into the command result. */
     readonly format?: (value: Value, ...args: Args) => Result;
 }
+/** Compiled command. */
 export interface Command<Value extends object, Result = Value, Args extends unknown[] = []> {
     readonly category?: InteractionCategory;
     readonly version?: number;
     readonly description?: string;
     readonly terminal?: boolean;
+    /** Per-field schemas, including the forced discriminator field. */
     readonly fieldSchemas: Record<string, unknown>;
+    /** Schema for model output; only `modelRequired` fields are required here. */
     readonly modelJsonSchema: Record<string, unknown>;
+    /** Schema for runtime input; every `required` field is required here. */
     readonly inputJsonSchema: Record<string, unknown>;
     readonly modes?: readonly string[];
+    /** Field names the program owns; the model must not supply them. */
     readonly ownedFields: readonly string[];
+    /** Selector values carried by `value`, used to resolve the command before parsing. */
     keys(value: Record<string, unknown>): string[];
+    /** Validates without formatting; throws on the first failed check. */
     assert(value: Value, ...args: Args): void;
+    /** Validates and returns the formatted result. */
     parse(value: Value, ...args: Args): Result;
 }
+/** Envelope-level options for a command catalog. */
 export interface CommandCatalogOptions {
+    /** Field carrying the mode selector, when modes are used. */
     readonly modeField?: string;
+    /** Rejection wording for an unknown command selector. */
     readonly unknownError?: Error | string;
+    /** Rejection wording for a command used outside its declared modes. */
     readonly modeError?: Error | string;
+    /** Rejection wording for a model-supplied owned field. */
     readonly ownershipError?: Error | string;
+    /** Diagnostic tags attached to every rejection from this catalog. */
     readonly tags?: readonly string[];
 }
 /** Transfer envelope plus its registered command family; no change to HTTP or SSE framing. */
 export type InteractionProtocolDefinition<Value extends object, Result = Value, Args extends unknown[] = [], Id extends string = string> = Omit<Partial<CommandDefinition<Value, Result, Args>>, 'discriminator' | 'modes' | 'ownedFields'> & CommandCatalogOptions & {
+    /** Field carrying the command id; also the canonical key in normalized output. */
     readonly commandField: string;
     /** Accepted only on input. Schema and normalized output always use commandField. */
     readonly commandAliases?: readonly string[];
+    /** Rejection wording when a payload selects no command. */
     readonly selectionError?: ProtocolReason<Value, Args>;
     readonly commands: Readonly<Record<Id, CommandDefinition<Value, Result, Args>>>;
 };
 /** Custom protocols may derive dynamic keys without supplying a compiled schema. */
 export interface ProtocolShape {
+    /** Optional schema for model output. */
     readonly modelJsonSchema?: Record<string, unknown>;
+    /** Optional schema for runtime input. */
     readonly inputJsonSchema?: Record<string, unknown>;
+    /** Optional per-field schemas. */
     readonly fieldSchemas?: Record<string, unknown>;
+    /** Selector values carried by `value`. */
     keys(value: Record<string, unknown>): string[];
 }
 /** Runtime extension contract; hosts retain their own version values and validation context. */
@@ -87,5 +150,6 @@ export interface RegisteredProtocol<Args extends unknown[] = []> extends Protoco
     readonly version?: number;
     readonly description?: string;
     readonly terminal?: boolean;
+    /** Structural validation for an already resolved command value. */
     assert?(value: Record<string, unknown>, ...args: Args): void;
 }

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

@@ -1 +1,8 @@
-export const INTERACTION_CATEGORIES = Object.freeze(['query', 'action', 'presentation', 'input', 'receipt']);
+/** Frozen list of accepted categories, used for validation and enumeration. */
+export const INTERACTION_CATEGORIES = Object.freeze([
+    'query',
+    'action',
+    'presentation',
+    'input',
+    'receipt',
+]);

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

@@ -1,51 +1,93 @@
+/**
+ * Knowledge publication contract: staged document revisions with explicit provenance.
+ *
+ * Place in the package: an optional App-side workflow for proposing, publishing or rejecting a
+ * knowledge document. Candidates are validated against the same catalog compiler as published
+ * documents and expire unless published; the store performs one atomic revision swap.
+ *
+ * Exports: `knowledgePublicationOperations`, `KnowledgeSourceReference`, `KnowledgeCandidate`,
+ * `KnowledgePublicationRecord`, `KnowledgePublicationStore`, `KnowledgePublicationOptions`,
+ * `KnowledgePublication`.
+ */
 import type { KnowledgeDocument, KnowledgeRead } from './knowledge.js';
 import type { MaybePromise, OperationContext } from '../common.js';
+/** Operation names accepted by the publication `authorize` hook. */
 export declare const knowledgePublicationOperations: readonly ["propose", "publish", "reject"];
+/** Citation of the material a candidate was derived from. */
 export interface KnowledgeSourceReference {
+    /** Source identity, for example a stored document or manual id. */
     readonly id: string;
+    /** Revision of that source that was read. */
     readonly revision: string;
+    /** Optional expiry instant; a stale source invalidates the candidate. */
     readonly expiresAtMs?: number;
 }
+/** A proposed document awaiting publish or reject. */
 export interface KnowledgeCandidate {
+    /** Candidate id, generated by the Kit. */
     readonly id: string;
+    /** Record revision the candidate was proposed against, used for stale-proposal detection. */
     readonly baseRevision: number;
+    /** Complete document that would replace the published revision with the same id. */
     readonly document: KnowledgeDocument;
+    /** Provenance the candidate depends on; verified by the App, never trusted from the model. */
     readonly sources: readonly KnowledgeSourceReference[];
     readonly createdAtMs: number;
+    /** Instant after which the candidate is discarded. */
     readonly expiresAtMs: number;
 }
+/** Stored publication state: one published revision plus pending candidates. */
 export interface KnowledgePublicationRecord {
+    /** Monotonic record revision; every accepted mutation increments it. */
     readonly revision: number;
+    /** Revision number of the currently published document set. */
     readonly publishedRevision: number;
+    /** Published documents, in catalog order. */
     readonly documents: readonly KnowledgeDocument[];
+    /** Pending candidates; expired entries are removed before use. */
     readonly candidates: readonly KnowledgeCandidate[];
 }
+/** Single-writer store for the publication record. */
 export interface KnowledgePublicationStore {
+    /** Returns the current record; it must always be readable. */
     load(): Promise<KnowledgePublicationRecord>;
+    /** Atomically replaces the record when the stored revision still equals `expectedRevision`. */
     compareAndSwap(expectedRevision: number, next: KnowledgePublicationRecord): Promise<boolean>;
 }
+/** App-owned guards, store and limits for a publication workflow. */
 export interface KnowledgePublicationOptions<App> {
     readonly store: KnowledgePublicationStore;
+    /** Reads that must succeed against every compiled document set, proving sections still exist. */
     readonly requiredReads?: readonly KnowledgeRead[];
+    /** Per-read character budget applied by the catalog compiler. */
     readonly maxReadChars?: number;
+    /** Maximum pending candidates retained; defaults to 32 and must be a positive integer. */
     readonly maxCandidates?: number;
+    /** Candidate retention window; defaults to seven days. */
     readonly candidateRetentionMs?: number;
+    /** Clock override for timestamps and expiry; defaults to `Date.now`. */
     readonly now?: () => number;
-    authorize(operation: typeof knowledgePublicationOperations[number], context: OperationContext<App>): MaybePromise<void>;
+    /** Guards one operation before any read or write. */
+    authorize(operation: (typeof knowledgePublicationOperations)[number], context: OperationContext<App>): MaybePromise<void>;
     /** Validate real provenance/revisions/visibility. A model's source list is not a grant. */
     verifySources(sources: readonly KnowledgeSourceReference[], context: OperationContext<App>): MaybePromise<void>;
 }
+/** Compiled publication workflow. */
 export interface KnowledgePublication<App> {
+    /** Returns the current record, with expired candidates already pruned. */
     read(context: OperationContext<App>): Promise<KnowledgePublicationRecord>;
+    /** Adds a candidate based on `revision`; fails when the record moved on. */
     propose(request: {
         revision: number;
         document: KnowledgeDocument;
         sources: readonly KnowledgeSourceReference[];
     }, context: OperationContext<App>): Promise<KnowledgePublicationRecord>;
+    /** Publishes one candidate and removes it from the pending list. */
     publish(request: {
         revision: number;
         candidateId: string;
     }, context: OperationContext<App>): Promise<KnowledgePublicationRecord>;
+    /** Discards one candidate without touching the published documents. */
     reject(request: {
         revision: number;
         candidateId: string;

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

@@ -1 +1,2 @@
+/** Operation names accepted by the publication `authorize` hook. */
 export const knowledgePublicationOperations = ['propose', 'publish', 'reject'];

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

@@ -1,37 +1,74 @@
+/**
+ * Knowledge document contract for the Knowledge Kit.
+ *
+ * Place in the package: an optional App-side catalog of structured text. Documents are nested
+ * sections of strings; a read selects the whole document or explicit sections and returns an
+ * immutable snapshot with content, revision and identity for citation.
+ *
+ * Exports: `KnowledgeSection`, `KnowledgePart`, `KnowledgeDocument`, `SectionSelection`,
+ * `KnowledgeRead`, `KnowledgeSnapshot`, `KnowledgeCatalogOptions`, `KnowledgeCatalog`.
+ */
 import type { ReadonlyCatalog } from '../common.js';
+/** A named section that may contain text and further sections. */
 export interface KnowledgeSection {
+    /** Section id, unique within its document; used by section selections. */
     readonly id: string;
+    /** Section content in order; nested sections are addressed independently. */
     readonly parts: readonly KnowledgePart[];
 }
+/** Document content: a text leaf or a nested section. */
 export type KnowledgePart = string | KnowledgeSection;
+/** One versioned document as supplied by the App. */
 export interface KnowledgeDocument {
+    /** Stable document id; duplicate ids are rejected by the catalog. */
     readonly id: string;
+    /** Revision label recorded in every snapshot so a citation names the exact content. */
     readonly revision: string;
+    /** Locale of the content, when the App maintains translations. */
     readonly locale?: string;
+    /** Ordered content. */
     readonly parts: readonly KnowledgePart[];
 }
-export type SectionSelection = {
+/** Which part of a document a read returns. */
+export type SectionSelection = 
+/** The whole document. */
+{
     readonly mode: 'document';
-} | {
+}
+/** `self` returns only the named sections; `subtree` also includes their descendants. */
+ | {
     readonly mode: 'self' | 'subtree';
     readonly sectionIds: readonly string[];
 };
+/** A request for one document selection. */
 export interface KnowledgeRead {
     readonly documentId: string;
+    /** Must reference existing sections; an invalid selection throws. */
     readonly selection: SectionSelection;
 }
+/** Materialized read result. */
 export interface KnowledgeSnapshot extends KnowledgeRead {
+    /** Deterministic identity derived from document, revision and selection. */
     readonly id: string;
+    /** Revision of the document that produced this content. */
     readonly revision: string;
     readonly locale?: string;
+    /** Rendered text, trimmed; sections are separated by blank lines. */
     readonly content: string;
 }
+/** Catalog construction options. */
 export interface KnowledgeCatalogOptions {
+    /** Maximum characters per read; exceeding it throws a `RangeError`. */
     readonly maxChars?: number;
+    /** Observer invoked with every produced snapshot. */
     readonly observe?: (snapshot: KnowledgeSnapshot) => void | Promise<void>;
 }
+/** Compiled catalog of knowledge documents. */
 export interface KnowledgeCatalog extends ReadonlyCatalog<KnowledgeDocument> {
+    /** Section ids of one document, in declaration order; throws for an unknown document. */
     sectionIds(documentId: string): readonly string[];
+    /** Validates a read without producing content; throws when the selection is invalid. */
     assertSelection(read: KnowledgeRead): void;
+    /** Produces a snapshot for the read; throws for unknown documents, sections or budget excess. */
     read(read: KnowledgeRead): KnowledgeSnapshot;
 }

package/dist/esm/structs/kits/normalization.d.ts

@@ -1,8 +1,23 @@
+/**
+ * Normalization contract for the Normalization Kit.
+ *
+ * Place in the package: an optional App-side helper that cleans model or transport input before it
+ * reaches business logic. Steps are ordered, synchronous value-to-value transformations; the Kit
+ * never mutates the caller's arrays.
+ *
+ * Exports: `NormalizationStep`, `NormalizationOptions`.
+ */
+/** One ordered transformation. */
 export interface NormalizationStep<Value, Context> {
+    /** Unique, non-blank step id used in errors. */
     readonly id: string;
+    /** Skips the step when it returns false; must be synchronous boolean. */
     readonly when?: (value: Value, context: Context) => boolean;
+    /** Returns the next value; receives the output of the previous step. Must be synchronous. */
     readonly normalize: (value: Value, context: Context) => Value;
 }
+/** Pipeline options. */
 export interface NormalizationOptions<Value, Context> {
+    /** Stops the walk after the step that first returns true; later steps then do not run. */
     readonly isComplete?: (value: Value, context: Context) => boolean;
 }

package/dist/esm/structs/kits/policies.d.ts

@@ -1,22 +1,46 @@
+/**
+ * Policy and recovery contract for the Policies Kit.
+ *
+ * Place in the package: an optional App-side library for policy and recovery tables. Predicates,
+ * recovery handlers, kinds and descriptions are App configuration; the Kit owns registration
+ * checks, evaluation order and outcome validation.
+ *
+ * Exports: `PolicyDefinition`, `PolicyAssessment`, `RecoveryResult`, `RecoveryDefinition`.
+ */
+/** One declarative policy. */
 export interface PolicyDefinition<Input, Kind extends string = string> {
+    /** Unique policy id; also reported as a reason when the policy matches. */
     readonly id: string;
+    /** Human-readable explanation; must not be blank. */
     readonly description: string;
+    /** Policy family used to deduplicate reported kinds. */
     readonly kind: Kind;
+    /** Returns whether the policy applies; must be synchronous boolean. */
     when(input: Input): boolean;
 }
+/** Result of assessing every registered policy against one input. */
 export interface PolicyAssessment<Kind extends string = string> {
+    /** True when at least one policy matched. */
     readonly required: boolean;
+    /** Ids of the matched policies, in registration order. */
     readonly reasons: readonly string[];
+    /** Distinct kinds of the matched policies, in first-match order. */
     readonly kinds: readonly Kind[];
 }
-export type RecoveryResult<Value> = {
+/** Outcome of one recovery handler, or of the whole chain. */
+export type RecoveryResult<Value> = 
+/** The handler declined; the chain continues with the next declaration. */
+{
     readonly handled: false;
 } | {
     readonly handled: true;
     readonly value: Value;
 };
+/** One recovery handler in an ordered chain. */
 export interface RecoveryDefinition<Input, Result> {
+    /** Unique handler id. */
     readonly id: string;
     readonly description: string;
+    /** Attempts recovery; must be synchronous and the first handled result wins. */
     tryRecover(input: Input): RecoveryResult<Result>;
 }