@jangts/agent-core 0.1.1 → 0.2.0

package/dist/esm/kits/durable.js

@@ -1,39 +1,99 @@
+/**
+ * Durable Kit: replay-safe sequential task execution on top of an App-owned checkpoint store.
+ *
+ * Place in the package: an optional App-side library for work that must survive a restart.
+ * The Kit owns step ordering, attempt and model-call accounting, deadline checks, checkpoint
+ * validation and the exclusive-store protocol; the store, its atomicity and the real side
+ * effects stay with the App. Core itself never imports this module.
+ *
+ * Exports: `defineDurableTask`, `Durable`, the checkpoint/step/store types, and the
+ * `durableStatuses` / `durableReplayPolicies` enumerations.
+ */
 import { booleanResult } from '../utils/synchronous.js';
 import { awaitWithSignal, awaitAssertion, createDeadlineSignal } from '../utils/cancellation.js';
 import { durableStatuses, durableReplayPolicies } from '../structs/kits/durable.js';
 import { AgentCoreEngine } from '../execution/engine.js';
+/**
+ * Compile a durable task definition into a resumable runner.
+ *
+ * Each `run` call locks the task id in the store, loads the checkpoint and resumes at
+ * `nextStepIndex`. A checkpoint from another definition id or revision, or one that fails the
+ * predicates below, is rejected instead of being repaired, because silently accepting it would
+ * replay App side effects under a different contract.
+ *
+ * @param definition - Task identity, state predicate, ordered steps and optional authorization.
+ * @param options - Fallback store plus optional clock; both are bound to their owners.
+ * @returns A frozen task with `run({ taskId, store? }, context)`.
+ * @throws TypeError At construction for an invalid identity, step list, replay policy or
+ *   duplicate step id; from `run` for a malformed request/context/store, an invalid
+ *   checkpoint, or a step whose returned state fails the predicate. Also throws when the
+ *   deadline passed, the attempt budget is exhausted, or the model-call budget cannot fund
+ *   one more attempt.
+ */
 export function defineDurableTask(definition, options = {}) {
     if (!definition || typeof definition !== 'object')
         throw new TypeError('Use isState and replayPolicy');
     const { id: definitionId, revision, steps: definitions, isState } = definition;
     const clock = options.now;
-    if (typeof definitionId !== 'string' || !definitionId.trim() || typeof revision !== 'string' || !revision.trim()
-        || typeof isState !== 'function' || !Array.isArray(definitions) || !definitions.length
-        || (clock !== undefined && typeof clock !== 'function'))
+    if (typeof definitionId !== 'string' ||
+        !definitionId.trim() ||
+        typeof revision !== 'string' ||
+        !revision.trim() ||
+        typeof isState !== 'function' ||
+        !Array.isArray(definitions) ||
+        !definitions.length ||
+        (clock !== undefined && typeof clock !== 'function'))
         throw new TypeError('Invalid durable task');
     const now = clock?.bind(options) ?? Date.now, validate = isState.bind(definition);
     const authorize = definition.authorize?.bind(definition);
-    const boundStore = options.store && { exclusive: options.store.exclusive.bind(options.store), load: options.store.load.bind(options.store), save: options.store.save.bind(options.store) };
+    const boundStore = options.store && {
+        exclusive: options.store.exclusive.bind(options.store),
+        load: options.store.load.bind(options.store),
+        save: options.store.save.bind(options.store),
+    };
     const steps = Object.freeze(definitions.map((step) => {
         if (!step || typeof step !== 'object')
             throw new TypeError('Use replayPolicy and OperationContext');
         const { id, replayPolicy, run, reconcile } = step;
-        if (typeof id !== 'string' || !id.trim() || !durableReplayPolicies.includes(replayPolicy) || typeof run !== 'function'
-            || (reconcile !== undefined && typeof reconcile !== 'function'))
+        if (typeof id !== 'string' ||
+            !id.trim() ||
+            !durableReplayPolicies.includes(replayPolicy) ||
+            typeof run !== 'function' ||
+            (reconcile !== undefined && typeof reconcile !== 'function'))
             throw new TypeError('Invalid durable step');
-        return Object.freeze({ id, replayPolicy, run: run.bind(step), reconcile: reconcile?.bind(step) });
+        return Object.freeze({
+            id,
+            replayPolicy,
+            run: run.bind(step),
+            reconcile: reconcile?.bind(step),
+        });
     }));
-    if (new Set(steps.map(step => step.id)).size !== steps.length)
+    if (new Set(steps.map((step) => step.id)).size !== steps.length)
         throw new TypeError('Duplicate durable step id');
     return Object.freeze({
+        /**
+         * Resume or start one durable task.
+         *
+         * @param request - Task id plus an optional per-call store that overrides the bound one.
+         * @param context - Operation context supplying app, signal and diagnostics.
+         * @returns The final state, cloned so the caller cannot mutate the stored checkpoint.
+         * @throws As described for `defineDurableTask`; an already-completed task returns its state
+         *   without running any step.
+         */
         async run(request, context) {
-            if (!request || typeof request !== 'object' || typeof request.taskId !== 'string' || !request.taskId.trim())
+            if (!request ||
+                typeof request !== 'object' ||
+                typeof request.taskId !== 'string' ||
+                !request.taskId.trim())
                 throw new TypeError('Use a named durable task request');
             if (!context?.signal)
                 throw new TypeError('Durable tasks require OperationContext');
             const { taskId } = request, store = request.store ?? boundStore, { app, signal, diagnostics } = context;
             signal.throwIfAborted();
-            if (!store || typeof store.exclusive !== 'function' || typeof store.load !== 'function' || typeof store.save !== 'function')
+            if (!store ||
+                typeof store.exclusive !== 'function' ||
+                typeof store.load !== 'function' ||
+                typeof store.save !== 'function')
                 throw new TypeError('Invalid durable store');
             const exclusive = store.exclusive.bind(store), load = store.load.bind(store), save = store.save.bind(store);
             signal.throwIfAborted();
@@ -44,24 +104,42 @@ export function defineDurableTask(definition, options = {}) {
                 if (!loaded)
                     throw new TypeError('Invalid durable checkpoint');
                 let record = snapshotCheckpoint(loaded);
-                if (record.definitionId !== definitionId || record.revision !== revision
-                    || !booleanResult(validate(record.state), 'Durable state predicates must return boolean synchronously') || !Number.isSafeInteger(record.nextStepIndex) || record.nextStepIndex < 0 || record.nextStepIndex > steps.length
-                    || !Number.isSafeInteger(record.attemptCount) || record.attemptCount < 0 || !Number.isSafeInteger(record.maxAttempts) || record.maxAttempts < 1
-                    || record.attemptCount > record.maxAttempts || record.attemptCount < record.nextStepIndex || !Number.isFinite(record.deadlineAtMs)
-                    || !durableStatuses.includes(record.status)
-                    || (record.status === 'completed') !== (record.nextStepIndex === steps.length))
+                if (record.definitionId !== definitionId ||
+                    record.revision !== revision ||
+                    !booleanResult(validate(record.state), 'Durable state predicates must return boolean synchronously') ||
+                    !Number.isSafeInteger(record.nextStepIndex) ||
+                    record.nextStepIndex < 0 ||
+                    record.nextStepIndex > steps.length ||
+                    !Number.isSafeInteger(record.attemptCount) ||
+                    record.attemptCount < 0 ||
+                    !Number.isSafeInteger(record.maxAttempts) ||
+                    record.maxAttempts < 1 ||
+                    record.attemptCount > record.maxAttempts ||
+                    record.attemptCount < record.nextStepIndex ||
+                    !Number.isFinite(record.deadlineAtMs) ||
+                    !durableStatuses.includes(record.status) ||
+                    (record.status === 'completed') !== (record.nextStepIndex === steps.length))
                     throw new TypeError('Invalid durable checkpoint');
                 const deadline = record.deadlineAtMs;
                 assertActive(signal, deadline, now);
                 if (record.modelBudget) {
                     const { maxCalls, reservedCalls, maxCallsPerAttempt } = record.modelBudget;
-                    if (!Number.isSafeInteger(maxCalls) || maxCalls < 1 || !Number.isSafeInteger(reservedCalls) || reservedCalls < 0 || reservedCalls > maxCalls
-                        || !Number.isSafeInteger(maxCallsPerAttempt) || maxCallsPerAttempt < 1 || maxCallsPerAttempt > maxCalls)
+                    if (!Number.isSafeInteger(maxCalls) ||
+                        maxCalls < 1 ||
+                        !Number.isSafeInteger(reservedCalls) ||
+                        reservedCalls < 0 ||
+                        reservedCalls > maxCalls ||
+                        !Number.isSafeInteger(maxCallsPerAttempt) ||
+                        maxCallsPerAttempt < 1 ||
+                        maxCallsPerAttempt > maxCalls)
                         throw new TypeError('Invalid durable model budget');
                 }
                 const lifetime = createDeadlineSignal(deadline, signal, now), activeSignal = lifetime.signal;
                 let saving;
-                const persist = async () => { saving = save(taskId, record); await saving; };
+                const persist = async () => {
+                    saving = save(taskId, record);
+                    await saving;
+                };
                 try {
                     if (authorize)
                         await awaitAssertion(() => authorize(snapshotCheckpoint(record), { app, signal: activeSignal, diagnostics }), activeSignal, 'Durable authorization must return void');
@@ -73,7 +151,10 @@ export function defineDurableTask(definition, options = {}) {
                     }
                     if (record.status === 'cancelled')
                         throw new Error('Durable task cancelled');
-                    const engine = new AgentCoreEngine({ maxRounds: Math.max(1, record.maxAttempts - record.attemptCount), execution: { signal: activeSignal, diagnostics } });
+                    const engine = new AgentCoreEngine({
+                        maxRounds: Math.max(1, record.maxAttempts - record.attemptCount),
+                        execution: { signal: activeSignal, diagnostics },
+                    });
                     return await engine.run(async (_index, execution) => {
                         assertActive(activeSignal, deadline, now);
                         if (record.attemptCount >= record.maxAttempts)
@@ -82,25 +163,46 @@ export function defineDurableTask(definition, options = {}) {
                         if (interrupted && step.replayPolicy === 'reconcile' && !step.reconcile)
                             throw new Error('Durable task reconciliation required');
                         const modelBudget = record.modelBudget;
-                        if (modelBudget && modelBudget.maxCalls - modelBudget.reservedCalls < modelBudget.maxCallsPerAttempt)
+                        if (modelBudget &&
+                            modelBudget.maxCalls - modelBudget.reservedCalls < modelBudget.maxCallsPerAttempt)
                             throw new Error('Durable model budget exhausted');
-                        record = { ...record, attemptCount: record.attemptCount + 1, status: 'running',
-                            ...(modelBudget ? { modelBudget: { ...modelBudget, reservedCalls: modelBudget.reservedCalls + modelBudget.maxCallsPerAttempt } } : {}) };
+                        record = {
+                            ...record,
+                            attemptCount: record.attemptCount + 1,
+                            status: 'running',
+                            ...(modelBudget
+                                ? {
+                                    modelBudget: {
+                                        ...modelBudget,
+                                        reservedCalls: modelBudget.reservedCalls + modelBudget.maxCallsPerAttempt,
+                                    },
+                                }
+                                : {}),
+                        };
                         // Await every save under the lock; cancellation cannot undo an in-flight commit.
                         await persist();
                         assertActive(activeSignal, deadline, now);
                         const local = structuredClone(record.state);
                         assertActive(activeSignal, deadline, now);
                         const handle = interrupted && step.replayPolicy === 'reconcile' ? step.reconcile : step.run;
-                        const nextState = await awaitWithSignal(handle(local, { app, signal: execution.signal, diagnostics: execution.diagnostics,
-                            attemptCount: record.attemptCount, maxModelCalls: record.modelBudget?.maxCallsPerAttempt }), activeSignal);
+                        const nextState = await awaitWithSignal(handle(local, {
+                            app,
+                            signal: execution.signal,
+                            diagnostics: execution.diagnostics,
+                            attemptCount: record.attemptCount,
+                            maxModelCalls: record.modelBudget?.maxCallsPerAttempt,
+                        }), activeSignal);
                         assertActive(activeSignal, deadline, now);
                         if (!booleanResult(validate(nextState), 'Durable state predicates must return boolean synchronously'))
                             throw new TypeError('Invalid durable step state');
                         const state = structuredClone(nextState);
                         assertActive(activeSignal, deadline, now);
-                        record = { ...record, state, nextStepIndex: record.nextStepIndex + 1,
-                            status: record.nextStepIndex + 1 === steps.length ? 'completed' : 'ready' };
+                        record = {
+                            ...record,
+                            state,
+                            nextStepIndex: record.nextStepIndex + 1,
+                            status: record.nextStepIndex + 1 === steps.length ? 'completed' : 'ready',
+                        };
                         await persist();
                         assertActive(activeSignal, deadline, now);
                         if (record.status === 'completed') {
@@ -131,15 +233,37 @@ function assertActive(signal, deadlineAtMs, now) {
         throw new Error('Durable task expired');
     signal.throwIfAborted();
 }
+/** Namespace object for callers that prefer one import over named helpers. */
 export const Durable = Object.freeze({ defineDurableTask });
+/** Allowed checkpoint lifecycle states; re-exported so hosts can validate their own stores. */
 export { durableStatuses, durableReplayPolicies } from '../structs/kits/durable.js';
 function snapshotCheckpoint(record) {
     const { version } = record;
+    // Only checkpoint layout 2 is readable; older layouts are not upgraded in place.
     if (version !== 2)
         throw new TypeError('Unsupported durable checkpoint version');
-    const { definitionId, revision, nextStepIndex, attemptCount, maxAttempts, deadlineAtMs, status, state, modelBudget } = record;
-    if (modelBudget !== undefined && (!modelBudget || typeof modelBudget !== 'object' || Array.isArray(modelBudget)))
+    const { definitionId, revision, nextStepIndex, attemptCount, maxAttempts, deadlineAtMs, status, state, modelBudget, } = record;
+    if (modelBudget !== undefined &&
+        (!modelBudget || typeof modelBudget !== 'object' || Array.isArray(modelBudget)))
         throw new TypeError('Invalid durable model budget');
-    return { version, definitionId, revision, nextStepIndex, attemptCount, maxAttempts, deadlineAtMs, status, state: structuredClone(state),
-        ...(modelBudget !== undefined ? { modelBudget: { maxCalls: modelBudget.maxCalls, reservedCalls: modelBudget.reservedCalls, maxCallsPerAttempt: modelBudget.maxCallsPerAttempt } } : {}) };
+    return {
+        version,
+        definitionId,
+        revision,
+        nextStepIndex,
+        attemptCount,
+        maxAttempts,
+        deadlineAtMs,
+        status,
+        state: structuredClone(state),
+        ...(modelBudget !== undefined
+            ? {
+                modelBudget: {
+                    maxCalls: modelBudget.maxCalls,
+                    reservedCalls: modelBudget.reservedCalls,
+                    maxCallsPerAttempt: modelBudget.maxCallsPerAttempt,
+                },
+            }
+            : {}),
+    };
 }

package/dist/esm/kits/evidence.d.ts

@@ -1,5 +1,16 @@
 import type { EvidenceProvider, EvidenceRequirement, EvidenceProjectionDefinition } from '../structs/kits/evidence.js';
-/** A reusable completion checklist over actual observations. Hosts define evidence semantics. */
+/**
+ * Compile a reusable completion checklist over actual observations.
+ *
+ * A requirement is satisfied when at least one observation satisfies the provider registered
+ * for its `kind`; `isComplete` requires every requirement to be satisfied, and `missing`
+ * returns those that are not. Hosts define evidence semantics.
+ *
+ * @param definitions - One provider per evidence kind, each with an `isSatisfied` predicate.
+ * @returns A frozen checklist exposing `isSatisfied`, `isComplete` and `missing`.
+ * @throws TypeError For duplicate kinds, missing predicates, or an unknown requirement kind;
+ *   predicates must return a boolean synchronously.
+ */
 export declare function defineEvidenceChecklist<Observation, Requirement extends EvidenceRequirement>(definitions: readonly EvidenceProvider<Observation, Requirement>[]): Readonly<{
     isSatisfied: (request: {
         observations: readonly Observation[];
@@ -9,19 +20,31 @@ export declare function defineEvidenceChecklist<Observation, Requirement extends
         observations: readonly Observation[];
         requirements: readonly Requirement[];
     }) => boolean;
-    missing({ observations, requirements }: {
+    missing({ observations, requirements, }: {
         observations: readonly Observation[];
         requirements: readonly Requirement[];
     }): Requirement[];
 }>;
-/** No selection retains the complete evidence; selection narrows registered source-bearing results. */
+/**
+ * Compile a projection that keeps only the sources a caller asked to see.
+ *
+ * No selection retains the complete evidence; a selection narrows registered source-bearing
+ * results. Observations whose tool has no provider pass through untouched, so the projection
+ * can only ever remove sources it knows how to name.
+ *
+ * @param definition - Source id selector, optional tool id selector, and per-tool providers.
+ * @returns A frozen object whose `project({ observations, sourceIds })` returns new values.
+ * @throws TypeError For a provider without both handlers; selectors and handlers must be
+ *   synchronous.
+ */
 export declare function defineEvidenceProjection<Observation, Source>(definition: EvidenceProjectionDefinition<Observation, Source>): Readonly<{
-    project({ observations, sourceIds }: {
+    project({ observations, sourceIds, }: {
         observations: Observation[];
         sourceIds?: readonly string[];
     }): Observation[];
 }>;
-export type { EvidenceRequirement, EvidenceProvider, EvidenceProjectionDefinition, EvidenceProjectionProvider } from '../structs/kits/evidence.js';
+export type { EvidenceRequirement, EvidenceProvider, EvidenceProjectionDefinition, EvidenceProjectionProvider, } from '../structs/kits/evidence.js';
+/** Namespace object for callers that prefer one import over named helpers. */
 export declare const Evidence: Readonly<{
     defineEvidenceChecklist: typeof defineEvidenceChecklist;
     defineEvidenceProjection: typeof defineEvidenceProjection;

package/dist/esm/kits/evidence.js

@@ -1,51 +1,102 @@
+/**
+ * Evidence Kit: check completion requirements against observations and narrow observations.
+ *
+ * Place in the package: an optional App-side library for "did we actually observe enough"
+ * logic. This module only compares observations with registered providers; what counts as
+ * evidence, where observations come from and how they are stored remain App-owned.
+ *
+ * Exports: `defineEvidenceChecklist`, `defineEvidenceProjection`, `Evidence`, and the
+ * evidence requirement/provider/projection types.
+ */
 import { synchronous, booleanResult } from '../utils/synchronous.js';
 import { breakWhile } from '../utils/rules.js';
-/** A reusable completion checklist over actual observations. Hosts define evidence semantics. */
+/**
+ * Compile a reusable completion checklist over actual observations.
+ *
+ * A requirement is satisfied when at least one observation satisfies the provider registered
+ * for its `kind`; `isComplete` requires every requirement to be satisfied, and `missing`
+ * returns those that are not. Hosts define evidence semantics.
+ *
+ * @param definitions - One provider per evidence kind, each with an `isSatisfied` predicate.
+ * @returns A frozen checklist exposing `isSatisfied`, `isComplete` and `missing`.
+ * @throws TypeError For duplicate kinds, missing predicates, or an unknown requirement kind;
+ *   predicates must return a boolean synchronously.
+ */
 export function defineEvidenceChecklist(definitions) {
     const providers = new Map();
     for (const definition of definitions) {
         const predicate = definition.isSatisfied;
         breakWhile([
-            { occur: () => providers.has(definition.kind), error: () => `Duplicate evidence kind: ${definition.kind}` },
-            { occur: () => typeof predicate !== 'function', error: () => `Missing evidence provider: ${definition.kind}` },
+            {
+                occur: () => providers.has(definition.kind),
+                error: () => `Duplicate evidence kind: ${definition.kind}`,
+            },
+            {
+                occur: () => typeof predicate !== 'function',
+                error: () => `Missing evidence provider: ${definition.kind}`,
+            },
         ]);
-        providers.set(definition.kind, Object.freeze({ kind: definition.kind, description: definition.description, isSatisfied: predicate.bind(definition) }));
+        providers.set(definition.kind, Object.freeze({
+            kind: definition.kind,
+            description: definition.description,
+            isSatisfied: predicate.bind(definition),
+        }));
     }
     const satisfied = (observations, requirement) => {
         const provider = providers.get(requirement.kind);
         breakWhile(!provider, () => `Unknown evidence kind: ${requirement.kind}`);
-        return observations.some(observation => booleanResult(provider.isSatisfied(observation, requirement), 'Evidence predicates must be synchronous', 'Evidence predicates must return boolean'));
+        return observations.some((observation) => booleanResult(provider.isSatisfied(observation, requirement), 'Evidence predicates must be synchronous', 'Evidence predicates must return boolean'));
     };
     return Object.freeze({
         isSatisfied: (request) => satisfied(request.observations, request.requirement),
-        isComplete: (request) => request.requirements.every(requirement => satisfied(request.observations, requirement)),
-        missing({ observations, requirements }) {
-            return requirements.filter(requirement => !satisfied(observations, requirement));
+        isComplete: (request) => request.requirements.every((requirement) => satisfied(request.observations, requirement)),
+        missing({ observations, requirements, }) {
+            return requirements.filter((requirement) => !satisfied(observations, requirement));
         },
     });
 }
-/** No selection retains the complete evidence; selection narrows registered source-bearing results. */
+/**
+ * Compile a projection that keeps only the sources a caller asked to see.
+ *
+ * No selection retains the complete evidence; a selection narrows registered source-bearing
+ * results. Observations whose tool has no provider pass through untouched, so the projection
+ * can only ever remove sources it knows how to name.
+ *
+ * @param definition - Source id selector, optional tool id selector, and per-tool providers.
+ * @returns A frozen object whose `project({ observations, sourceIds })` returns new values.
+ * @throws TypeError For a provider without both handlers; selectors and handlers must be
+ *   synchronous.
+ */
 export function defineEvidenceProjection(definition) {
     const sourceId = definition.sourceId.bind(definition);
-    const toolId = definition.toolId?.bind(definition) ?? ((observation) => { const value = observation; return value.toolId ?? value.tool; });
+    const toolId = definition.toolId?.bind(definition) ??
+        ((observation) => {
+            // Fallback tool selector: accept either the current `toolId` field or the legacy `tool`.
+            const value = observation;
+            return value.toolId ?? value.tool;
+        });
     const providers = new Map();
     for (const [tool, provider] of Object.entries(definition.providers)) {
-        breakWhile(![provider.sources, provider.withSources].every(handler => typeof handler === 'function'), `Invalid evidence projection: ${tool}`);
-        providers.set(tool, Object.freeze({ sources: provider.sources.bind(provider), withSources: provider.withSources.bind(provider) }));
+        breakWhile(![provider.sources, provider.withSources].every((handler) => typeof handler === 'function'), `Invalid evidence projection: ${tool}`);
+        providers.set(tool, Object.freeze({
+            sources: provider.sources.bind(provider),
+            withSources: provider.withSources.bind(provider),
+        }));
     }
     return Object.freeze({
-        project({ observations, sourceIds = [] }) {
+        project({ observations, sourceIds = [], }) {
             // Unknown/empty claims still need review against every available candidate.
             if (!sourceIds.length)
                 return observations;
-            return observations.map(observation => {
+            return observations.map((observation) => {
                 const provider = providers.get(synchronous(toolId(observation), 'Evidence tool selectors must be synchronous'));
                 if (!provider)
                     return observation;
-                const sources = synchronous(provider.sources(observation), 'Evidence source projection must be synchronous').filter(source => sourceIds.includes(synchronous(sourceId(source), 'Evidence source selectors must be synchronous')));
+                const sources = synchronous(provider.sources(observation), 'Evidence source projection must be synchronous').filter((source) => sourceIds.includes(synchronous(sourceId(source), 'Evidence source selectors must be synchronous')));
                 return synchronous(provider.withSources(observation, sources), 'Evidence observations must be synchronous');
             });
         },
     });
 }
+/** Namespace object for callers that prefer one import over named helpers. */
 export const Evidence = Object.freeze({ defineEvidenceChecklist, defineEvidenceProjection });

package/dist/esm/kits/family.d.ts

@@ -1,8 +1,24 @@
 import type { AgentFamily, FamilyDefinition } from '../structs/kits/family.js';
-/** Versioned App data around existing Engine branches. No executable functions or authority are restored. */
+/**
+ * Compile a versioned family backed by an App-owned compare-and-swap store.
+ *
+ * Every mutation reads the record, verifies the caller's expected revision, then commits with
+ * a compare-and-swap, so concurrent writers fail with a revision conflict rather than
+ * overwriting each other. Reads are also treated as policy checks because the App binds its
+ * read rules into the store it supplies.
+ *
+ * @param definition - Store, authorization, validation, state predicate, branch/state snapshots
+ *   and optional merge handler, clock and bounds.
+ * @returns A frozen family with `read`, `create`, `fork`, `merge` and `promote`.
+ * @throws A configured error (often `TypeError`) for an invalid id, expired or unknown record,
+ *   revision conflict, exhausted capacity, lineage mismatch, missing merge configuration,
+ *   invalid merge result, or changed active version.
+ */
 export declare function defineAgentFamily<State, App>(definition: FamilyDefinition<State, App>): AgentFamily<State, App>;
+/** Namespace object for callers that prefer one import over named helpers. */
 export declare const Family: Readonly<{
     defineAgentFamily: typeof defineAgentFamily;
 }>;
 export type * from '../structs/kits/family.js';
+/** Operation names accepted by the family `authorize` hook. */
 export { familyOperations } from '../structs/kits/family.js';