@jangts/agent-core 0.1.1 → 0.2.0

package/dist/cjs/kits/presentation/events.js

@@ -6,28 +6,51 @@ exports.publishReplyEvents = publishReplyEvents;
 exports.serializeOutputEvents = serializeOutputEvents;
 exports.textOutputEvents = textOutputEvents;
 const rules_js_1 = require("../../utils/rules.js");
-/** Internal boundary between validated assistant bubbles. Never sent as visible text. */
+/**
+ * Internal boundary between validated assistant bubbles. Never sent as visible text.
+ *
+ * U+001E (record separator) is a non-printing control character that ordinary replies do not
+ * contain, so splitting on it cannot truncate visible prose.
+ */
 exports.REPLY_BUBBLE_BOUNDARY = '\u001e';
+/**
+ * Collect the non-empty-text parts of a reply.
+ *
+ * @param reply - Primary text plus optional extra bubbles.
+ * @returns The text and every string bubble; non-string entries are dropped.
+ */
 function replyBubbleTexts(reply) {
     const { text, bubbles } = reply;
-    return [text, ...(Array.isArray(bubbles) ? bubbles : [])]
-        .filter((text) => typeof text === 'string');
+    return [text, ...(Array.isArray(bubbles) ? bubbles : [])].filter((text) => typeof text === 'string');
 }
-/** Publish a validated reply without exposing its internal boundary to consumers. */
+/**
+ * Stream one reply as paced text chunks and bubble separators.
+ *
+ * Publish a validated reply without exposing its internal boundary to consumers. The pacing
+ * options are upper bounds, not exact timings: the pause and interval are clamped against
+ * `maxDurationMs`, so added delay never exceeds the budget while every chunk is still emitted.
+ *
+ * @param request - Reply text (bubbles separated by `REPLY_BUBBLE_BOUNDARY`) and pacing options.
+ * @param context - Execution context supplying the abort signal.
+ * @returns An async stream of `text` and `bubble` events, in order.
+ * @throws TypeError For a malformed request, missing signal, or invalid chunk/pacing values;
+ *   aborts with the caller's signal.
+ */
 async function* publishReplyEvents(request, context) {
     (0, rules_js_1.breakWhile)(!request || typeof request !== 'object', () => new TypeError('Use a named reply delivery request'));
     const { text, delivery } = request, { signal } = context;
     (0, rules_js_1.breakWhile)(typeof text !== 'string' || !signal, () => new TypeError('Reply delivery requires text and ExecutionContext'));
     (0, rules_js_1.breakWhile)(delivery !== undefined && (!delivery || typeof delivery !== 'object'), () => new TypeError('Reply delivery requires named options'));
-    const { chunkSize = 240, intervalMs = 0, bubblePauseMs = 0, maxDurationMs = 3000 } = delivery ?? {};
+    const { chunkSize = 240, intervalMs = 0, bubblePauseMs = 0, maxDurationMs = 3000, } = delivery ?? {};
     (0, rules_js_1.breakWhile)(!Number.isSafeInteger(chunkSize) || chunkSize < 1, () => new TypeError('Invalid output chunk size'));
     for (const [name, value] of Object.entries({ intervalMs, bubblePauseMs, maxDurationMs }))
         (0, rules_js_1.breakWhile)(!Number.isFinite(value) || value < 0, () => new TypeError(`Invalid ${name}`));
     signal.throwIfAborted();
-    const bubbles = text.split(exports.REPLY_BUBBLE_BOUNDARY).map(bubble => Array.from(bubble));
+    const bubbles = text.split(exports.REPLY_BUBBLE_BOUNDARY).map((bubble) => Array.from(bubble));
     const chunkCount = bubbles.reduce((sum, bubble) => sum + Math.ceil(bubble.length / chunkSize), 0);
     const pause = Math.min(bubblePauseMs, maxDurationMs / Math.max(1, bubbles.length - 1));
-    const interval = Math.min(intervalMs, Math.max(0, maxDurationMs - pause * (bubbles.length - 1)) / Math.max(1, chunkCount - bubbles.filter(bubble => bubble.length).length));
+    const interval = Math.min(intervalMs, Math.max(0, maxDurationMs - pause * (bubbles.length - 1)) /
+        Math.max(1, chunkCount - bubbles.filter((bubble) => bubble.length).length));
     const deadline = performance.now() + maxDurationMs;
     for (let bubble = 0; bubble < bubbles.length; bubble++) {
         if (bubble) {
@@ -50,14 +73,29 @@ async function wait(milliseconds, signal) {
     if (!milliseconds)
         return;
     await new Promise((resolve, reject) => {
-        const stop = () => { clearTimeout(timer); signal.removeEventListener('abort', stop); reject(signal.reason); };
-        const timer = setTimeout(() => { signal.removeEventListener('abort', stop); resolve(); }, milliseconds);
+        const stop = () => {
+            clearTimeout(timer);
+            signal.removeEventListener('abort', stop);
+            reject(signal.reason);
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener('abort', stop);
+            resolve();
+        }, milliseconds);
         signal.addEventListener('abort', stop, { once: true });
         if (signal.aborted)
             stop();
     });
 }
-/** Serialize the event protocol for callers using a text stream. */
+/**
+ * Serialize the event protocol for callers using a text stream.
+ *
+ * `preview` events are dropped because they are not final text; bubbles become the boundary
+ * character again, so a consumer can re-split the stream.
+ *
+ * @param events - Event stream carrying `text`, `bubble` or `preview` entries.
+ * @returns The equivalent string chunks.
+ */
 async function* serializeOutputEvents(events) {
     for await (const event of events) {
         if (event.type === 'preview')
@@ -65,6 +103,12 @@ async function* serializeOutputEvents(events) {
         yield event.type === 'bubble' ? exports.REPLY_BUBBLE_BOUNDARY : event.text;
     }
 }
+/**
+ * Wrap already-chunked text as `text` events.
+ *
+ * @param chunks - Text chunks in delivery order.
+ * @returns The same chunks as events.
+ */
 async function* textOutputEvents(chunks) {
     for await (const text of chunks)
         yield { type: 'text', text };

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

@@ -15,6 +15,17 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Presentation = void 0;
+/**
+ * Presentation Kit entry: output contracts, text templates, semantic slots, variants and the
+ * reply/chunk event stream.
+ *
+ * Place in the package: an optional App-side library for shaping what the user finally sees.
+ * The App owns copy, styling and transport; this directory owns contract validation, template
+ * substitution, variant selection and the bubble/chunk protocol.
+ *
+ * Exports: everything from `./outputs.js`, `./variants.js`, `./templates.js` and `./events.js`,
+ * plus the `Presentation` namespace object.
+ */
 __exportStar(require("./outputs.js"), exports);
 __exportStar(require("./variants.js"), exports);
 __exportStar(require("./templates.js"), exports);
@@ -23,4 +34,16 @@ const outputs_js_1 = require("./outputs.js");
 const templates_js_1 = require("./templates.js");
 const variants_js_1 = require("./variants.js");
 const events_js_1 = require("./events.js");
-exports.Presentation = Object.freeze({ defineOutputCatalog: outputs_js_1.defineOutputCatalog, defineTextTemplate: templates_js_1.defineTextTemplate, defineSemanticSlots: templates_js_1.defineSemanticSlots, selectVariant: variants_js_1.selectVariant, resolvePreference: variants_js_1.resolvePreference, REPLY_BUBBLE_BOUNDARY: events_js_1.REPLY_BUBBLE_BOUNDARY, replyBubbleTexts: events_js_1.replyBubbleTexts, publishReplyEvents: events_js_1.publishReplyEvents, serializeOutputEvents: events_js_1.serializeOutputEvents, textOutputEvents: events_js_1.textOutputEvents });
+/** Namespace object for callers that prefer one import over named helpers. */
+exports.Presentation = Object.freeze({
+    defineOutputCatalog: outputs_js_1.defineOutputCatalog,
+    defineTextTemplate: templates_js_1.defineTextTemplate,
+    defineSemanticSlots: templates_js_1.defineSemanticSlots,
+    selectVariant: variants_js_1.selectVariant,
+    resolvePreference: variants_js_1.resolvePreference,
+    REPLY_BUBBLE_BOUNDARY: events_js_1.REPLY_BUBBLE_BOUNDARY,
+    replyBubbleTexts: events_js_1.replyBubbleTexts,
+    publishReplyEvents: events_js_1.publishReplyEvents,
+    serializeOutputEvents: events_js_1.serializeOutputEvents,
+    textOutputEvents: events_js_1.textOutputEvents,
+});

package/dist/cjs/kits/presentation/outputs.js

@@ -1,20 +1,55 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.defineOutputCatalog = defineOutputCatalog;
+/**
+ * Presentation Kit: declarative output contracts for text, master, record and group outputs.
+ *
+ * Place in the package: part of the `presentation` Kit. A definition decides which fields the
+ * model generates, which are bound to App providers, which are constants and which select a
+ * semantic key; this module validates those declarations and composes the final value.
+ *
+ * Exports: `defineOutputCatalog`, and the output definition/field/provider/result types.
+ */
 const schema_adapter_js_1 = require("../../utils/schema-adapter.js");
 const catalog_js_1 = require("../../utils/catalog.js");
 const synchronous_js_1 = require("../../utils/synchronous.js");
 const templates_js_1 = require("./templates.js");
 const object_js_1 = require("../../utils/object.js");
 const observer_js_1 = require("../../utils/observer.js");
-function snapshotValue(value) { const copy = structuredClone(value); (0, object_js_1.freezeSchema)(copy); return copy; }
-const textValueSchema = (0, schema_adapter_js_1.snapshotSchemaAdapter)({ jsonSchema: { type: 'string' }, parse(value) {
+function snapshotValue(value) {
+    const copy = structuredClone(value);
+    (0, object_js_1.freezeSchema)(copy);
+    return copy;
+}
+const textValueSchema = (0, schema_adapter_js_1.snapshotSchemaAdapter)({
+    jsonSchema: { type: 'string' },
+    parse(value) {
         if (typeof value !== 'string')
             throw new TypeError('Invalid output field value');
         return value;
-    } });
-function parseField(field, value) { return field.valueSchema.parse(value); }
-const validId = (id) => typeof id === 'string' && /^[A-Za-z][A-Za-z0-9_.-]*$/.test(id) && !['__proto__', 'constructor', 'prototype'].includes(id);
+    },
+});
+function parseField(field, value) {
+    return field.valueSchema.parse(value);
+}
+// Object-prototype names are excluded so a field id can never shadow `__proto__` or replace a
+// prototype member when values are assembled into a dictionary.
+const validId = (id) => typeof id === 'string' &&
+    /^[A-Za-z][A-Za-z0-9_.-]*$/.test(id) &&
+    !['__proto__', 'constructor', 'prototype'].includes(id);
+/**
+ * Compile output definitions into one catalog.
+ *
+ * Compilation is where most mistakes surface: group membership is checked for cycles, master
+ * templates must have exactly one slot per field, and every `bound`/`semantic` field must name
+ * a registered provider. Composition then trusts the compiled catalog.
+ *
+ * @param definitions - Output definitions with unique ids and a supported `kind`.
+ * @param options - Provider list and an optional observer for composed results.
+ * @returns A frozen catalog extended with `toModelSchema`, `check` and `compose`.
+ * @throws TypeError For an invalid id or kind, a malformed group, mismatched master slots,
+ *   an invalid field owner or semantic keys, or an unknown provider id.
+ */
 function defineOutputCatalog(definitions, options = {}) {
     const providers = options.providers ?? [], observe = options.observe?.bind(options);
     const providerMap = new Map();
@@ -30,42 +65,70 @@ function defineOutputCatalog(definitions, options = {}) {
         const { id, kind, fields: fieldDefinitions, master, maxItems, allowedOutputIds } = definition;
         if (!validId(id) || catalog.has(id) || !['text', 'master', 'record', 'group'].includes(kind))
             throw new TypeError('Invalid output definition');
-        const fields = fieldDefinitions?.map(field => {
+        const fields = fieldDefinitions?.map((field) => {
             const { id, owner, required, valueSchema, providerId, constantValue, semanticKeys } = field;
-            return Object.freeze({ id, owner, required, valueSchema: valueSchema === undefined ? textValueSchema : (0, schema_adapter_js_1.snapshotSchemaAdapter)(valueSchema),
-                providerId, constantValue: owner === 'constant' ? snapshotValue(constantValue) : undefined,
-                semanticKeys: semanticKeys === undefined ? undefined : Object.freeze([...semanticKeys]) });
+            return Object.freeze({
+                id,
+                owner,
+                required,
+                valueSchema: valueSchema === undefined ? textValueSchema : (0, schema_adapter_js_1.snapshotSchemaAdapter)(valueSchema),
+                providerId,
+                constantValue: owner === 'constant' ? snapshotValue(constantValue) : undefined,
+                semanticKeys: semanticKeys === undefined ? undefined : Object.freeze([...semanticKeys]),
+            });
+        });
+        const entry = Object.freeze({
+            id,
+            kind,
+            master,
+            maxItems,
+            fields: fields ? Object.freeze(fields) : undefined,
+            allowedOutputIds: allowedOutputIds === undefined ? undefined : Object.freeze([...allowedOutputIds]),
         });
-        const entry = Object.freeze({ id, kind, master, maxItems, fields: fields ? Object.freeze(fields) : undefined,
-            allowedOutputIds: allowedOutputIds === undefined ? undefined : Object.freeze([...allowedOutputIds]) });
         if (entry.kind === 'group') {
-            if (entry.fields?.length || entry.master !== undefined || !entry.allowedOutputIds?.length || new Set(entry.allowedOutputIds).size !== entry.allowedOutputIds.length || !Number.isSafeInteger(entry.maxItems) || entry.maxItems < 1)
+            if (entry.fields?.length ||
+                entry.master !== undefined ||
+                !entry.allowedOutputIds?.length ||
+                new Set(entry.allowedOutputIds).size !== entry.allowedOutputIds.length ||
+                !Number.isSafeInteger(entry.maxItems) ||
+                entry.maxItems < 1)
                 throw new TypeError('Invalid output group');
         }
         else {
-            if (!fields?.length || new Set(fields.map(field => field.id)).size !== fields.length || (entry.kind === 'text' && (fields.length !== 1 || fields[0].required === false)))
+            if (!fields?.length ||
+                new Set(fields.map((field) => field.id)).size !== fields.length ||
+                (entry.kind === 'text' && (fields.length !== 1 || fields[0].required === false)))
                 throw new TypeError('Invalid output fields');
             for (const field of fields) {
-                if (!validId(field.id) || !['generated', 'bound', 'constant', 'semantic'].includes(field.owner))
+                if (!validId(field.id) ||
+                    !['generated', 'bound', 'constant', 'semantic'].includes(field.owner))
                     throw new TypeError('Invalid output ownership');
                 if (['bound', 'semantic'].includes(field.owner) && !providerMap.has(field.providerId))
                     throw new TypeError(`Unknown output provider: ${field.providerId}`);
-                if (field.owner === 'semantic' && (!field.semanticKeys?.length || new Set(field.semanticKeys).size !== field.semanticKeys.length || field.semanticKeys.some(key => typeof key !== 'string' || !key)))
+                if (field.owner === 'semantic' &&
+                    (!field.semanticKeys?.length ||
+                        new Set(field.semanticKeys).size !== field.semanticKeys.length ||
+                        field.semanticKeys.some((key) => typeof key !== 'string' || !key)))
                     throw new TypeError('Invalid semantic output keys');
             }
             if (entry.kind === 'master') {
                 if (typeof entry.master !== 'string')
                     throw new TypeError('Missing output master');
                 const template = (0, templates_js_1.defineTextTemplate)(entry.master);
-                if (template.slots.length !== fields.length || template.slots.some(id => !fields.some(field => field.id === id)))
+                if (template.slots.length !== fields.length ||
+                    template.slots.some((id) => !fields.some((field) => field.id === id)))
                     throw new TypeError('Output master fields do not match slots');
                 masters.set(entry.id, template);
             }
         }
         catalog.set(entry.id, entry);
     }
-    const get = (id) => { const entry = catalog.get(id); if (!entry)
-        throw new TypeError(`Unknown output: ${id}`); return entry; };
+    const get = (id) => {
+        const entry = catalog.get(id);
+        if (!entry)
+            throw new TypeError(`Unknown output: ${id}`);
+        return entry;
+    };
     const visited = new Set(), visiting = new Set();
     function checkRefs(id) {
         if (visited.has(id))
@@ -81,13 +144,23 @@ function defineOutputCatalog(definitions, options = {}) {
     for (const id of catalog.keys())
         checkRefs(id);
     // Both callers reject groups before asking for their validated nonempty fields.
-    const modelFields = (entry) => entry.fields.filter(field => ['generated', 'semantic'].includes(field.owner));
+    const modelFields = (entry) => entry.fields.filter((field) => ['generated', 'semantic'].includes(field.owner));
     function toModelSchema(id) {
         const entry = get(id);
         if (entry.kind === 'group')
             throw new TypeError('Output groups require program-assigned items');
         const fields = modelFields(entry);
-        return { type: 'object', properties: Object.fromEntries(fields.map(field => [field.id, field.owner === 'semantic' ? { type: 'string', enum: [...field.semanticKeys] } : field.valueSchema.jsonSchema])), required: fields.filter(field => field.required !== false).map(field => field.id), additionalProperties: false };
+        return {
+            type: 'object',
+            properties: Object.fromEntries(fields.map((field) => [
+                field.id,
+                field.owner === 'semantic'
+                    ? { type: 'string', enum: [...field.semanticKeys] }
+                    : field.valueSchema.jsonSchema,
+            ])),
+            required: fields.filter((field) => field.required !== false).map((field) => field.id),
+            additionalProperties: false,
+        };
     }
     function inspect(id, value, signal) {
         signal?.throwIfAborted();
@@ -96,16 +169,27 @@ function defineOutputCatalog(definitions, options = {}) {
             throw new TypeError('Inspect individual group items');
         const issues = [], values = Object.create(null);
         if (!value || typeof value !== 'object' || Array.isArray(value))
-            return { values, issues: [{ path: [id], code: 'OUTPUT_SHAPE', message: 'Expected an output object' }] };
+            return {
+                values,
+                issues: [{ path: [id], code: 'OUTPUT_SHAPE', message: 'Expected an output object' }],
+            };
         const input = value, fields = modelFields(entry);
         for (const key of Object.keys(input))
-            if (!fields.some(field => field.id === key))
-                issues.push({ path: [id, key], code: 'OUTPUT_FOREIGN_FIELD', message: 'Unknown generated field' });
+            if (!fields.some((field) => field.id === key))
+                issues.push({
+                    path: [id, key],
+                    code: 'OUTPUT_FOREIGN_FIELD',
+                    message: 'Unknown generated field',
+                });
         for (const field of fields) {
             signal?.throwIfAborted();
             if (!Object.hasOwn(input, field.id)) {
                 if (field.required !== false)
-                    issues.push({ path: [id, field.id], code: 'OUTPUT_MISSING', message: 'Required generated field is missing' });
+                    issues.push({
+                        path: [id, field.id],
+                        code: 'OUTPUT_MISSING',
+                        message: 'Required generated field is missing',
+                    });
                 continue;
             }
             const value = input[field.id];
@@ -121,9 +205,16 @@ function defineOutputCatalog(definitions, options = {}) {
             }
             catch (error) {
                 signal?.throwIfAborted();
-                if (error && typeof error === 'object' && 'name' in error && ['AbortError', 'TimeoutError'].includes(String(error.name)))
+                if (error &&
+                    typeof error === 'object' &&
+                    'name' in error &&
+                    ['AbortError', 'TimeoutError'].includes(String(error.name)))
                     throw error;
-                issues.push({ path: [id, field.id], code: 'OUTPUT_VALUE', message: 'Generated field does not match its schema' });
+                issues.push({
+                    path: [id, field.id],
+                    code: 'OUTPUT_VALUE',
+                    message: 'Generated field does not match its schema',
+                });
             }
             signal?.throwIfAborted();
         }
@@ -134,16 +225,25 @@ function defineOutputCatalog(definitions, options = {}) {
         const entry = get(id), { generated, items } = input;
         context.signal.throwIfAborted();
         if (entry.kind === 'group') {
-            if (Object.keys(generated ?? {}).length || !Array.isArray(items) || items.length > entry.maxItems)
+            if (Object.keys(generated ?? {}).length ||
+                !Array.isArray(items) ||
+                items.length > entry.maxItems)
                 throw new TypeError('Invalid output group items');
-            const assigned = items.map((item) => ({ id: item.id, outputId: item.outputId, input: item.input }));
-            if (new Set(assigned.map(item => item.id)).size !== assigned.length)
+            const assigned = items.map((item) => ({
+                id: item.id,
+                outputId: item.outputId,
+                input: item.input,
+            }));
+            if (new Set(assigned.map((item) => item.id)).size !== assigned.length)
                 throw new TypeError('Invalid output group items');
-            const value = assigned.map(item => {
+            const value = assigned.map((item) => {
                 context.signal.throwIfAborted();
                 if (!validId(item.id) || !entry.allowedOutputIds.includes(item.outputId))
                     throw new TypeError('Invalid output group reference');
-                return Object.freeze({ id: item.id, ...composeInternal(item.outputId, item.input, context) });
+                return Object.freeze({
+                    id: item.id,
+                    ...composeInternal(item.outputId, item.input, context),
+                });
             });
             context.signal.throwIfAborted();
             return Object.freeze({ outputId: id, kind: entry.kind, value: Object.freeze(value) });
@@ -151,17 +251,26 @@ function defineOutputCatalog(definitions, options = {}) {
         const checked = inspect(id, generated ?? {}, context.signal);
         context.signal.throwIfAborted();
         if (checked.issues.length)
-            throw Object.assign(new TypeError('Output contract rejected generated fields'), { issues: checked.issues });
+            throw Object.assign(new TypeError('Output contract rejected generated fields'), {
+                issues: checked.issues,
+            });
         const values = Object.create(null);
         for (const field of entry.fields) {
             context.signal.throwIfAborted();
-            if (['generated', 'semantic'].includes(field.owner) && !Object.hasOwn(checked.values, field.id) && field.required === false) {
+            if (['generated', 'semantic'].includes(field.owner) &&
+                !Object.hasOwn(checked.values, field.id) &&
+                field.required === false) {
                 if (entry.kind === 'master')
                     values[field.id] = '';
                 continue;
             }
-            const value = field.owner === 'constant' ? field.constantValue : ['bound', 'semantic'].includes(field.owner)
-                ? (0, synchronous_js_1.synchronous)(providerMap.get(field.providerId).resolve({ key: field.owner === 'semantic' ? checked.values[field.id] : undefined }, context), 'Output providers must be synchronous') : checked.values[field.id];
+            const value = field.owner === 'constant'
+                ? field.constantValue
+                : ['bound', 'semantic'].includes(field.owner)
+                    ? (0, synchronous_js_1.synchronous)(providerMap.get(field.providerId).resolve({
+                        key: field.owner === 'semantic' ? checked.values[field.id] : undefined,
+                    }, context), 'Output providers must be synchronous')
+                    : checked.values[field.id];
             context.signal.throwIfAborted();
             if (value === undefined && field.required === false) {
                 if (entry.kind === 'master')
@@ -171,7 +280,11 @@ function defineOutputCatalog(definitions, options = {}) {
             values[field.id] = field.owner === 'generated' ? value : parseField(field, value);
             context.signal.throwIfAborted();
         }
-        const value = entry.kind === 'master' ? masters.get(id).render(values) : entry.kind === 'text' ? values[entry.fields[0].id] : Object.freeze(values);
+        const value = entry.kind === 'master'
+            ? masters.get(id).render(values)
+            : entry.kind === 'text'
+                ? values[entry.fields[0].id]
+                : Object.freeze(values);
         if ((entry.kind === 'text' || entry.kind === 'master') && typeof value !== 'string')
             throw new TypeError('Text output requires a string value');
         const result = Object.freeze({ outputId: id, kind: entry.kind, value });
@@ -179,8 +292,33 @@ function defineOutputCatalog(definitions, options = {}) {
         (0, observer_js_1.observeSafely)(observe, result);
         return result;
     }
-    return Object.freeze({ ...(0, catalog_js_1.readonlyCatalog)(catalog.values(), id => new TypeError(`Unknown output: ${id}`)), toModelSchema,
-        check(request) { const result = inspect(request.outputId, request.value); return { status: result.issues.length ? 'failed' : 'passed', value: result.values, issues: result.issues }; },
+    return Object.freeze({
+        ...(0, catalog_js_1.readonlyCatalog)(catalog.values(), (id) => new TypeError(`Unknown output: ${id}`)),
+        /** JSON schema of the fields a model must generate for this output. */
+        toModelSchema,
+        /**
+         * Validate a generated value without composing it.
+         *
+         * @param request - Output id and the candidate value.
+         * @returns `passed` or `failed` with the collected issues and accepted values.
+         */
+        check(request) {
+            const result = inspect(request.outputId, request.value);
+            return {
+                status: result.issues.length ? 'failed' : 'passed',
+                value: result.values,
+                issues: result.issues,
+            };
+        },
+        /**
+         * Compose the final output value from generated fields, providers and constants.
+         *
+         * @param request - Output id and the generated/group input.
+         * @param context - Operation context; cancellation is checked between every step.
+         * @returns The frozen composed result, also forwarded to the observer.
+         * @throws TypeError For a malformed request, missing context, rejected generated fields
+         *   (carrying `issues`), a non-synchronous provider, or a text output that is not a string.
+         */
         compose(request, context) {
             if (!request || typeof request !== 'object')
                 throw new TypeError('Use a named output request');

package/dist/cjs/kits/presentation/templates.js

@@ -4,9 +4,21 @@ exports.defineTextTemplate = defineTextTemplate;
 exports.defineSemanticSlots = defineSemanticSlots;
 const rules_js_1 = require("../../utils/rules.js");
 const observer_js_1 = require("../../utils/observer.js");
-/** The program owns the master; inserted model text is a value and is substituted once only. */
+/**
+ * The program owns the master; inserted model text is a value and is substituted once only.
+ *
+ * Substitution is single-pass `String.replace`: a value that itself contains `{{slot}}` is
+ * left as literal text, so a slot value cannot inject further substitutions.
+ *
+ * @param master - Template text using `{{slot}}` placeholders; slot names may repeat.
+ * @param options - Error wording and an optional observer for rendered text.
+ * @returns A frozen template exposing the deduplicated `slots` and `render(values)`.
+ * @throws Error From `render` when a referenced slot is missing from `values`.
+ */
 function defineTextTemplate(master, options = {}) {
-    const slots = Object.freeze([...new Set([...master.matchAll(/\{\{(\w+)\}\}/g)].map(match => match[1]))]);
+    const slots = Object.freeze([
+        ...new Set([...master.matchAll(/\{\{(\w+)\}\}/g)].map((match) => match[1])),
+    ]);
     const errors = options.errors, missingField = errors?.missingField?.bind(errors), observe = options.observe?.bind(options);
     return Object.freeze({
         slots,
@@ -20,12 +32,26 @@ function defineTextTemplate(master, options = {}) {
         },
     });
 }
-/** Models select public semantic keys; hosts retain private values and selection policy. */
+/**
+ * Models select public semantic keys; hosts retain private values and selection policy.
+ *
+ * A text is valid when it uses at most `maxOccurrences` namespaced slots, every name is a
+ * declared key, and no malformed `{{namespace` remnant is left behind — the last check stops
+ * partial or misspelled placeholders from reaching the template engine.
+ *
+ * @param definition - Namespace (lower-case words joined by hyphens), allowed keys and the
+ *   occurrence limit (a non-negative safe integer, 0 forbidding the slot entirely).
+ * @returns A frozen validator with the namespace and `isValid(text)`.
+ * @throws TypeError For an invalid namespace or occurrence limit.
+ */
 function defineSemanticSlots(definition) {
     const { namespace, maxOccurrences } = definition;
     (0, rules_js_1.breakWhile)([
         { occur: () => !/^[a-z][a-z0-9-]*$/.test(namespace), error: 'Invalid slot namespace' },
-        { occur: () => !Number.isSafeInteger(maxOccurrences) || maxOccurrences < 0, error: 'Invalid slot limit' },
+        {
+            occur: () => !Number.isSafeInteger(maxOccurrences) || maxOccurrences < 0,
+            error: 'Invalid slot limit',
+        },
     ]);
     const keys = new Set(definition.keys);
     const pattern = new RegExp(`\\{\\{${namespace}:([^{}]*)\\}\\}`, 'g');
@@ -33,7 +59,9 @@ function defineSemanticSlots(definition) {
         namespace,
         isValid(text) {
             const matches = [...text.matchAll(pattern)];
-            return matches.length <= maxOccurrences && matches.every(match => keys.has(match[1])) && !text.replace(pattern, '').includes(`{{${namespace}`);
+            return (matches.length <= maxOccurrences &&
+                matches.every((match) => keys.has(match[1])) &&
+                !text.replace(pattern, '').includes(`{{${namespace}`));
         },
     });
 }

package/dist/cjs/kits/presentation/variants.js

@@ -1,11 +1,30 @@
 "use strict";
+/**
+ * Presentation Kit: variant selection and preference resolution over App-supplied values.
+ *
+ * Place in the package: part of the `presentation` Kit. Copy, priorities and randomness are
+ * App policy; this module only applies a deterministic rule to what it is given.
+ *
+ * Exports: `selectVariant`, `resolvePreference`.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.selectVariant = selectVariant;
 exports.resolvePreference = resolvePreference;
+/**
+ * Pick one variant, avoiding an immediate repeat when alternatives exist.
+ *
+ * When every candidate equals `previous`, the full list is used again, so a single-value set
+ * still yields a result instead of failing.
+ *
+ * @param values - Candidate variants; an empty list returns `undefined`.
+ * @param options - Previous value to avoid and a random index source in `[0, limit)`.
+ * @returns The selected value, or `undefined` when there are no candidates.
+ * @throws TypeError When `randomIndex` returns a non-integer or an out-of-range index.
+ */
 function selectVariant(values, options) {
     if (!values.length)
         return undefined;
-    const candidates = values.length > 1 ? values.filter(value => value !== options.previous) : [...values];
+    const candidates = values.length > 1 ? values.filter((value) => value !== options.previous) : [...values];
     const pool = candidates.length ? candidates : [...values];
     if (pool.length === 1)
         return pool[0];
@@ -14,8 +33,18 @@ function selectVariant(values, options) {
         throw new TypeError('Invalid variant index');
     return pool[index];
 }
+/**
+ * Resolve the preferred candidate.
+ *
+ * Highest `priority` wins; `order` breaks ties with the later entry first, so recency can be
+ * encoded without touching priority. The input array is copied before sorting.
+ *
+ * @param candidates - Values with a priority and an order marker.
+ * @returns The winning value, or `undefined` for an empty list.
+ * @throws TypeError When any priority or order is not finite.
+ */
 function resolvePreference(candidates) {
-    if (candidates.some(item => !Number.isFinite(item.priority) || !Number.isFinite(item.order)))
+    if (candidates.some((item) => !Number.isFinite(item.priority) || !Number.isFinite(item.order)))
         throw new TypeError('Invalid preference priority');
     return [...candidates].sort((left, right) => right.priority - left.priority || right.order - left.order)[0]?.value;
 }