@jangts/agent-core 0.1.1 → 0.2.1

package/dist/esm/structs/invocation.d.ts

@@ -1,27 +1,57 @@
+/**
+ * Invocation identity and success receipts.
+ *
+ * Every Core-initiated model call or tool call returns its value together with the metadata that
+ * identifies the invocation, so callers can correlate results with diagnostics without parsing
+ * logs. These records describe completed calls only; failures surface as thrown errors.
+ *
+ * Exports: `InvocationMetadata`, `InvocationResult`, `ModelCallRecord`, `ToolCallRecord`,
+ * `ModelResult`, `ToolResult`.
+ */
 import type { ModelUsage } from './model/messages.js';
+/** Identity and timing shared by every invocation receipt. */
 export interface InvocationMetadata {
+    /** Root run this invocation belongs to, when the host runs inside a diagnostics scope. */
     readonly runId?: string;
+    /** Diagnostics span of this invocation. */
     readonly spanId?: string;
+    /** Span that caused this invocation; absent for a root invocation. */
     readonly parentSpanId?: string;
+    /** Enclosing invocation when one call triggers another. */
     readonly parentInvocationId?: string;
+    /** Opaque per-invocation id shared by receipt, events and diagnostic records. */
     readonly invocationId: string;
+    /** Start instant in epoch milliseconds. */
     readonly startedAtMs: number;
+    /** Elapsed milliseconds from start to completion. */
     readonly durationMs: number;
 }
+/** A produced value together with the receipt of the invocation that produced it. */
 export interface InvocationResult<Value, Metadata extends InvocationMetadata = InvocationMetadata> {
     readonly value: Value;
     readonly invocation: Readonly<Metadata>;
 }
+/** Receipt of a model call that returned successfully. */
 export interface ModelCallRecord extends InvocationMetadata {
+    /** Records are only emitted for successful calls; failures are thrown instead. */
     readonly status: 'success';
+    /** Workflow stage that requested the call. */
     readonly stageId?: string;
+    /** Configured model binding used for the call. */
     readonly modelId?: string;
+    /** One-based position of the call within its runner's lifetime. */
     readonly callSequence: number;
+    /** Provider-reported token usage; present only when the provider supplied it. */
     readonly usage?: Readonly<ModelUsage>;
 }
+/** Receipt of a tool call that returned successfully. */
 export interface ToolCallRecord extends InvocationMetadata {
+    /** Records are only emitted for successful calls; failures are thrown instead. */
     readonly status: 'success';
+    /** Registered tool that produced the value. */
     readonly toolId: string;
 }
+/** Model call result with its model-call receipt. */
 export type ModelResult<Value> = InvocationResult<Value, ModelCallRecord>;
+/** Tool call result with its tool-call receipt. */
 export type ToolResult<Value> = InvocationResult<Value, ToolCallRecord>;

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

@@ -1,5 +1,17 @@
+/**
+ * Query aggregation contract: several ordered reads collapsed into one item list.
+ *
+ * Place in the package: an optional App-side helper for merging results of the same query shape
+ * run against several inputs. The Kit owns ordering and optional stable-key merging; every real
+ * read, the merge policy and the meaning of an item stay with the App.
+ *
+ * Exports: `QueryAggregationOptions`.
+ */
 export interface QueryAggregationOptions<Input, Item, Context> {
+    /** Reads one input. Called once per input, in caller order, and must return synchronously. */
     readonly execute: (input: Input, context: Context) => readonly Item[];
+    /** Optional stable merge key. Items with the same key collapse into the first position seen. */
     readonly key?: (item: Item, input: Input, context: Context) => string;
+    /** Combines a duplicate with the value merged so far; receives `undefined` for the first item. */
     readonly merge?: (item: Item, previous: Item | undefined, input: Input, context: Context) => Item;
 }

package/dist/esm/structs/kits/answering/checks.d.ts

@@ -1,5 +1,16 @@
+/**
+ * Answer checker contract for the Answering Kit.
+ *
+ * Place in the package: part of the `answering` Kit. A checker is one named validation unit over
+ * a generated value; the flow owns when it runs and what a failure means for the result.
+ *
+ * Exports: `AnswerChecker`.
+ */
 import type { OperationContext, CheckResult } from '../../common.js';
+/** One named check applied to a generated answer value. */
 export interface AnswerChecker<Value, App> {
+    /** Check id, reported with the issue and matched against a task's `checkIds`. */
     readonly id: string;
+    /** Returns the verdict; `unavailable` and `not-run` are not verdicts on the value. */
     check(value: Value, context: OperationContext<App>): CheckResult<Value>;
 }

package/dist/esm/structs/kits/answering/flow.d.ts

@@ -1,50 +1,84 @@
+/**
+ * Answer flow contract for the Answering Kit.
+ *
+ * Place in the package: the only `answering` module that composes the others. Generation, checking,
+ * review, fallback and budget checks are App handlers; the flow owns the stage graph, cell state,
+ * repair budget and per-item result statuses.
+ *
+ * Exports: `AnswerIssue`, `AnswerCheck`, `AnswerItem`, `AnswerResult`, `AnswerFlowDefinition`.
+ */
 import type { CheckResult, Issue, OperationContext, MaybePromise } from '../../common.js';
 import type { RecoveryResult } from '../policies.js';
+/** Validation problem produced while checking a generated answer. */
 export interface AnswerIssue extends Issue {
 }
+/** Result of one local or review check over a generated answer. */
 export interface AnswerCheck<Value> extends CheckResult<Value> {
 }
+/** One unit an answer batch must produce. */
 export interface AnswerItem<Data> {
+    /** Unique item id inside the batch; also the key used for values and repairs. */
     readonly id: string;
+    /** Input ids this item answers; every batch input must be covered exactly once overall. */
     readonly inputIds: readonly string[];
+    /** App-owned data the generator and readers consume. */
     readonly data: Data;
+    /** Availability of the item's source material; anything but `ready` cannot be answered. */
     readonly sourceStatus: 'ready' | 'unavailable' | 'conflict';
 }
+/** Final outcome for one item. */
 export interface AnswerResult<Data, Value> {
     readonly item: AnswerItem<Data>;
+    /** Accepted or recovered value; absent when the item was blocked. */
     readonly value?: Value;
+    /** `accepted` needs both checks resolved; `fallback` used recovery; `blocked` has no value. */
     readonly status: 'accepted' | 'fallback' | 'blocked';
+    /** Combined local and review issues, plus generated codes such as a missing value. */
     readonly issues: readonly AnswerIssue[];
+    /** Verdicts that produced this result. */
     readonly checks: {
         readonly local: AnswerCheck<Value>;
         readonly review: AnswerCheck<Value>;
     };
 }
-/** Static handlers and limits. Request signal, diagnostics and App dependencies arrive only at run. */
+/** Static handlers and limits; signal, diagnostics and App dependencies arrive at run. */
 export interface AnswerFlowDefinition<Data, Value, App = undefined> {
+    /** Maximum items in one batch; must be a positive integer. */
     readonly maxItems: number;
+    /** Repair rounds; the flow runs at most `maxRepairs + 1` rounds in total. */
     readonly maxRepairs: number;
+    /** Review policy; defaults to `optional`, `required` blocks on an unresolved review. */
     readonly reviewPolicy?: 'optional' | 'required' | 'off';
+    /** Request-level budget guard; must return boolean synchronously. */
     canInvoke(context: OperationContext<App>): boolean;
+    /**
+     * Produces values for the items that still need one.
+     *
+     * `repairs` carries the issues of a failed attempt and `previous` its rejected values.
+     */
     generate(input: {
         readonly items: readonly AnswerItem<Data>[];
         readonly repairs?: ReadonlyMap<string, readonly AnswerIssue[]>;
         readonly previous?: ReadonlyMap<string, Value>;
     }, context: OperationContext<App>): Promise<ReadonlyMap<string, Value>>;
+    /** Local check for one generated value; must return synchronously. */
     check(input: {
         readonly item: AnswerItem<Data>;
         readonly value: Value;
     }, context: OperationContext<App>): AnswerCheck<Value>;
+    /** Batch review; returns one check per reviewed item and must cover the submitted items. */
     review?(input: {
         readonly items: readonly {
             item: AnswerItem<Data>;
             value: Value;
         }[];
     }, context: OperationContext<App>): Promise<ReadonlyMap<string, AnswerCheck<Value>>>;
+    /** Last resort for a failed item; `handled` supplies a replacement value. */
     fallback(input: {
         readonly item: AnswerItem<Data>;
         readonly issues: readonly AnswerIssue[];
     }, context: OperationContext<App>): RecoveryResult<Value>;
+    /** Observes a stage outcome; failures must not affect the flow result. */
     observe?(input: {
         readonly stageId: string;
         readonly results: readonly AnswerResult<Data, Value>[];

package/dist/esm/structs/kits/answering/state.d.ts

@@ -1,19 +1,40 @@
+/**
+ * Answer flow state for the Answering Kit.
+ *
+ * Place in the package: mutable bookkeeping owned by the flow for one request. Cells are never
+ * shared between requests, and the repair budget is consumed by the flow itself.
+ *
+ * Exports: `AnswerCell`, `AnswerFlowState`.
+ */
 import type { AnswerItem, AnswerCheck, AnswerResult } from './flow.js';
+/** One item's progress through generate, check, review and repair. */
 export interface AnswerCell<D, V> {
+    /** Item being answered. */
     item: AnswerItem<D>;
+    /** Latest generated value; absent before generation or when generation produced none. */
     value?: V;
+    /** True when `value` is present, kept explicit so a valid `undefined` value is representable. */
     hasValue: boolean;
+    /** Latest local check verdict. */
     local: AnswerCheck<V>;
+    /** Latest review verdict. */
     review: AnswerCheck<V>;
+    /** Sticky marker: a review once failed, so review must resolve before the item is accepted. */
     knownReviewFailure: boolean;
+    /** Whether the most recent generation pass produced this cell's value. */
     generated?: boolean;
 }
+/** Whole-flow state for one request. */
 export interface AnswerFlowState<D, V> {
+    /** All cells of the batch, in request order. */
     cells: AnswerCell<D, V>[];
+    /** Cells still being processed in the current round. */
     pending: AnswerCell<D, V>[];
+    /** Repair allowance; `take()` returns false once the configured rounds are spent. */
     repairBudget: {
         readonly available: boolean;
         take(): boolean;
     };
+    /** Final results, present only after the flow completes. */
     result?: AnswerResult<D, V>[];
 }

package/dist/esm/structs/kits/answering/tasks.d.ts

@@ -1,21 +1,41 @@
+/**
+ * Answer task contract for the Answering Kit.
+ *
+ * Place in the package: part of the `answering` Kit. A task binds an intent set, an optional scope,
+ * one reader, one output contract and a list of checks; readers remain App-owned I/O.
+ *
+ * Exports: `AnswerTaskDefinition`, `AnswerReader`, `AnswerTaskPorts`.
+ */
 import type { MaybePromise, OperationContext, SchemaAdapter, ReadonlyCatalog } from '../../common.js';
+/** Static binding of one answerable task. */
 export interface AnswerTaskDefinition<Input = unknown, Data = unknown> {
+    /** Unique task id. */
     readonly id: string;
     readonly description: string;
+    /** Reader that produces the evidence for this task; must be registered. */
     readonly readerId: string;
+    /** Output contract the answer must satisfy; must be registered. */
     readonly outputId: string;
+    /** Intents this task serves; non-empty. */
     readonly intentIds: readonly string[];
+    /** Optional scope narrowing the task. */
     readonly scopeId?: string;
+    /** Checks applied to the produced value; every id must be registered. */
     readonly checkIds: readonly string[];
+    /** Schema for the task input, validated before the reader runs. */
     readonly inputSchema: SchemaAdapter<Input>;
+    /** App metadata passed back through the reader context; opaque to the Kit. */
     readonly metadata: Data;
 }
+/** App-owned reader that gathers evidence for one task. */
 export interface AnswerReader<Input, Evidence, App, Data = unknown> {
     readonly id: string;
+    /** Produces evidence for the validated input; the task is passed through for context. */
     read(input: Input, context: OperationContext<App> & {
         readonly task: Readonly<AnswerTaskDefinition<Input, Data>>;
     }): MaybePromise<Evidence>;
 }
+/** Registries a task catalog validates its references against. */
 export interface AnswerTaskPorts<Input, Evidence, App, Data = unknown> {
     readonly readers: ReadonlyCatalog<AnswerReader<Input, Evidence, App, Data>>;
     readonly outputs: ReadonlyCatalog<{
@@ -24,5 +44,6 @@ export interface AnswerTaskPorts<Input, Evidence, App, Data = unknown> {
     readonly checks: ReadonlyCatalog<{
         readonly id: string;
     }>;
+    /** Extra App assertion over a raw definition, before it is compiled. */
     assertDefinition?(task: Readonly<AnswerTaskDefinition<Input, Data>>): void;
 }

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

@@ -1,11 +1,25 @@
+/**
+ * Artifact reference contract for the Artifacts Kit.
+ *
+ * Place in the package: an optional App-side library. A reference only names a resolver and an
+ * artifact; the resolver, not Core, establishes access, provenance and whether the referenced
+ * revision is still current. Nothing is cached or persisted by these types.
+ *
+ * Exports: `ArtifactReference`, `ArtifactResolver`.
+ */
 import type { MaybePromise, OperationContext } from '../common.js';
 /** References locate artifacts; only the App resolver establishes access and current validity. */
 export interface ArtifactReference {
+    /** Resolver that owns the artifact namespace. */
     readonly resolverId: string;
+    /** Artifact identity inside that namespace; never blank. */
     readonly artifactId: string;
+    /** Optional pinned revision; omission asks the resolver for its current revision. */
     readonly revision?: string;
 }
+/** App-registered resolver that turns a reference into an App value. */
 export interface ArtifactResolver<Value, App> {
     readonly id: string;
+    /** Resolves the reference; throws when the artifact is unknown or not accessible. */
     resolve(reference: ArtifactReference, context: OperationContext<App>): MaybePromise<Value>;
 }

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

@@ -1,8 +1,27 @@
+/**
+ * Candidate envelope contract for the Candidates Kit.
+ *
+ * Place in the package: an optional App-side validator for a model reply that may offer several
+ * alternatives under one named field. The definition only declares the shape and bounds; which
+ * alternatives are acceptable, and what happens after the user picks one, stays with the App.
+ *
+ * Exports: `CandidateSelectionDefinition`.
+ */
 import type { BreakReason } from '../utils/rules.js';
+/**
+ * Declares the alternative-proposal envelope.
+ *
+ * A value without the declared field is treated as a single implicit candidate.
+ */
 export interface CandidateSelectionDefinition {
+    /** Reply field that carries the alternatives. */
     readonly field: string;
+    /** Minimum number of distinct candidates once the envelope is present; defaults to 1. */
     readonly minCandidates?: number;
+    /** Maximum number of candidates; must be a safe integer not below the minimum. */
     readonly maxCandidates: number;
+    /** Rejection wording, either fixed, a pre-built error or a lazy factory. */
     readonly error?: BreakReason;
+    /** Diagnostic tags attached to every rejection from this contract. */
     readonly tags?: readonly string[];
 }

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

@@ -1,15 +1,37 @@
+/**
+ * Delivery pipeline contract for the Delivery Kit.
+ *
+ * Place in the package: an optional App-side pipeline that ends with one result, for example
+ * formatting and sending a reply. The Kit owns ordering, cancellation checks and outcome
+ * validation; the stages, their state and the real side effects belong to the App.
+ *
+ * Exports: `DeliveryStage`, `DeliveryOptions`.
+ */
 import type { ExecutionContext, OperationContext } from '../common.js';
 import type { StepOutcome } from '../execution/engine.js';
+/** One pipeline stage, identified for reporting and optional observation. */
 export interface DeliveryStage<Input, State, Result, StageId extends string> {
+    /** Unique, non-blank stage id in declaration order. */
     readonly id: StageId;
+    /**
+     * Handles this stage.
+     *
+     * Returning `complete` ends the pipeline immediately; `continue` moves to the next stage.
+     * Omitting the handler makes the stage a named hook that only `beforeStage` observes.
+     */
     readonly handle?: (state: State, context: OperationContext<Input>) => StepOutcome<Result>;
 }
+/** Pipeline construction options. */
 export interface DeliveryOptions<Input, State, Result, StageId extends string> {
+    /** Creates the mutable per-run state; must return synchronously. */
     readonly createState: (input: Input, context: ExecutionContext) => State;
+    /** Stages in execution order; ids must be unique. */
     readonly stages: readonly DeliveryStage<Input, State, Result, StageId>[];
+    /** Observes every stage before it runs, including stages without a handler. */
     readonly beforeStage?: (input: {
         stageId: StageId;
         state: State;
     }, context: OperationContext<Input>) => void;
+    /** Builds the error thrown when every stage returned `continue`. */
     readonly missingResult: () => Error;
 }

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

@@ -1,15 +1,43 @@
+/**
+ * Durable task contract for the Durable Kit.
+ *
+ * Place in the package: an optional App-side library for sequential 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: `durableStatuses`, `durableReplayPolicies`, `DurableCheckpoint`, `DurableStore`,
+ * `DurableStep`, `DurableStepContext`, `DurableTaskDefinition`, `DurableTaskOptions`,
+ * `DurableTask`.
+ */
 import type { OperationContext } from '../common.js';
+/** Checkpoint lifecycle values, in the order a task passes through them. */
 export declare const durableStatuses: readonly ["ready", "running", "completed", "cancelled"];
+/**
+ * How an interrupted step is resumed.
+ *
+ * `safe` re-runs `run` (the step must tolerate repeating its side effect); `reconcile` requires a
+ * `reconcile` handler because the previous attempt may have taken effect already.
+ */
 export declare const durableReplayPolicies: readonly ["safe", "reconcile"];
+/** Persisted task progress; the only state a resume reads back. */
 export interface DurableCheckpoint<State> {
+    /** Checkpoint format version; other versions are rejected on load. */
     version: 2;
+    /** Definition that produced the checkpoint; a mismatch invalidates it. */
     definitionId: string;
+    /** Definition revision that produced the checkpoint; a mismatch invalidates it. */
     revision: string;
+    /** Zero-based index of the next step to run. */
     nextStepIndex: number;
+    /** Attempts already spent; one is spent per step entry. */
     attemptCount: number;
+    /** Total attempts allowed for the whole task. */
     maxAttempts: number;
+    /** Absolute deadline in epoch milliseconds; expiry cancels the task. */
     deadlineAtMs: number;
-    status: typeof durableStatuses[number];
+    status: (typeof durableStatuses)[number];
+    /** App-owned task state; only `isState` decides whether it is still valid. */
     state: State;
     /** Durable, conservative reservations. An interrupted attempt never refunds its allowance. */
     modelBudget?: {
@@ -20,34 +48,59 @@ export interface DurableCheckpoint<State> {
 }
 /** App implements an exclusive lock across every writer and validates/serializes stored state. */
 export interface DurableStore<State> {
+    /** Runs `operation` under the exclusive lock for `id`; other writers must wait or fail. */
     exclusive<T>(id: string, operation: () => Promise<T>): Promise<T>;
+    /** Returns the stored checkpoint, or `undefined` when the task has never been saved. */
     load(id: string): Promise<DurableCheckpoint<State> | undefined>;
+    /** Persists a checkpoint; must be durable before the promise resolves. */
     save(id: string, checkpoint: DurableCheckpoint<State>): Promise<void>;
 }
+/** One step of a durable task. */
 export interface DurableStep<State, App> {
+    /** Unique step id used in errors and diagnostics. */
     readonly id: string;
-    readonly replayPolicy: typeof durableReplayPolicies[number];
+    /** Resume behaviour when a previous attempt was interrupted mid-step. */
+    readonly replayPolicy: (typeof durableReplayPolicies)[number];
+    /** Executes the step and returns the complete next state. */
     run(state: Readonly<State>, context: DurableStepContext<App>): Promise<State>;
+    /** Required when `replayPolicy` is `reconcile`; repairs state after an interrupted attempt. */
     reconcile?(state: Readonly<State>, context: DurableStepContext<App>): Promise<State>;
 }
+/** Execution facts handed to a durable step. */
 export interface DurableStepContext<App> extends OperationContext<App> {
+    /** One-based attempt number currently executing (already counted and persisted). */
     readonly attemptCount: number;
-    /** App binds its real Runner to this reserved per-attempt maximum, also keeping request limits. */
+    /** App binds its real Runner to this reserved per-attempt maximum, keeping request limits. */
     readonly maxModelCalls?: number;
 }
+/** Task definition, including the App hooks that guard every resume. */
 export interface DurableTaskDefinition<State, App> {
     readonly id: string;
+    /** Definition revision; stored in the checkpoint so resumed work matches its code. */
     readonly revision: string;
+    /** Steps in execution order; the checkpoint stores an index into this list. */
     readonly steps: readonly DurableStep<State, App>[];
+    /** Validates a loaded checkpoint state before any step runs. */
     isState(state: unknown): state is State;
     /** Recheck current identity, source versions and grants on every explicit resume. */
     authorize?(checkpoint: Readonly<DurableCheckpoint<State>>, context: import('../common.js').OperationContext<App>): import('../common.js').MaybePromise<void>;
 }
+/** Runtime options for a compiled durable task. */
 export interface DurableTaskOptions<State = unknown> {
+    /** Clock override for deadlines and timestamps; defaults to `Date.now`. */
     readonly now?: () => number;
+    /** Default store; a call may pass its own store instead. */
     readonly store?: DurableStore<State>;
 }
+/** Compiled task: resumes from the store and returns the final state. */
 export interface DurableTask<State, App> {
+    /**
+     * Runs or resumes the task.
+     *
+     * @param request - Task id and an optional store overriding the definition's default.
+     * @param context - App host object, cancellation and diagnostics.
+     * @returns The completed state; a completed checkpoint returns a detached copy.
+     */
     run(request: {
         readonly taskId: string;
         readonly store?: DurableStore<State>;

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

@@ -1,2 +1,9 @@
+/** Checkpoint lifecycle values, in the order a task passes through them. */
 export const durableStatuses = ['ready', 'running', 'completed', 'cancelled'];
+/**
+ * How an interrupted step is resumed.
+ *
+ * `safe` re-runs `run` (the step must tolerate repeating its side effect); `reconcile` requires a
+ * `reconcile` handler because the previous attempt may have taken effect already.
+ */
 export const durableReplayPolicies = ['safe', 'reconcile'];

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

@@ -1,20 +1,43 @@
+/**
+ * Evidence contract for the Evidence Kit.
+ *
+ * Place in the package: an optional App-side library for "did we actually observe enough" logic.
+ * A requirement may only be satisfied by an observation; a model's claim that it succeeded is
+ * never itself evidence. What counts as evidence and where observations come from stay App-owned.
+ *
+ * Exports: `EvidenceRequirement`, `EvidenceProvider`, `EvidenceProjectionProvider`,
+ * `EvidenceProjectionDefinition`.
+ */
 /** Requirements describe evidence that must already exist, never a model's assertion of success. */
 export interface EvidenceRequirement {
+    /** Evidence kind; selects the provider that adjudicates satisfaction. */
     readonly kind: string;
+    /** Identity inside that kind, for example a document or record id. */
     readonly id: string;
+    /** Optional operation the evidence must cover; interpreted by the provider. */
     readonly operation?: string;
 }
+/** Adjudicates one evidence kind against real observations. */
 export interface EvidenceProvider<Observation, Requirement extends EvidenceRequirement> {
+    /** Kind this provider answers; one provider per kind. */
     readonly kind: Requirement['kind'];
     readonly description: string;
+    /** Returns whether one observation satisfies one requirement; must be synchronous boolean. */
     isSatisfied(observation: Observation, requirement: Requirement): boolean;
 }
+/** Describes which sources an observation can cite, and how to narrow it to cited ones. */
 export interface EvidenceProjectionProvider<Observation, Source> {
+    /** All sources the observation currently carries. */
     sources(observation: Observation): readonly Source[];
+    /** Returns a copy of the observation restricted to `sources`. */
     withSources(observation: Observation, sources: Source[]): Observation;
 }
+/** Projection configuration, keyed by the tool that produced an observation. */
 export interface EvidenceProjectionDefinition<Observation, Source> {
+    /** One provider per tool id; observations without a provider pass through unchanged. */
     readonly providers: Readonly<Record<string, EvidenceProjectionProvider<Observation, Source>>>;
+    /** Stable citation id for a source. */
     readonly sourceId: (source: Source) => string;
+    /** Selects the tool id of an observation; defaults to its `toolId` (or legacy `tool`) field. */
     readonly toolId?: (observation: Observation) => string;
 }

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

@@ -1,36 +1,78 @@
+/**
+ * Family version contract for the Family Kit.
+ *
+ * Place in the package: an optional App-side library that versions App state hanging off Core
+ * branches. A family is a bounded, expiring record of immutable versions; the Kit owns revision
+ * checks, capacity, retention and lineage rules, while the store, authorization, validation and
+ * merge policy stay with the App. No executable function or authority is restored here.
+ *
+ * Exports: `familyOperations`, `FamilyOperation`, `FamilyVersion`, `FamilyRecord`, `FamilyStore`,
+ * `FamilyDefinition`, `AgentFamily`.
+ */
 import type { OperationContext, MaybePromise } from '../common.js';
 import type { AgentBranch } from '../../execution/engine.js';
+/** Operation names accepted by the family `authorize` hook. */
 export declare const familyOperations: readonly ["create", "fork", "merge", "promote"];
-export type FamilyOperation = typeof familyOperations[number];
+/** One of the four family mutations. */
+export type FamilyOperation = (typeof familyOperations)[number];
+/** Immutable snapshot of App state at one point on a branch. */
 export interface FamilyVersion<State> {
+    /** Unique version id, generated by the Kit. */
     readonly id: string;
+    /** Version this one was forked or merged from, when lineage applies. */
     readonly parentId?: string;
+    /** Source version of a merge; present only on versions created by `merge`. */
     readonly mergeSourceId?: string;
+    /** Common ancestor recorded for fork/merge bookkeeping. */
     readonly baseId?: string;
+    /** Core branch snapshot paired with this state. */
     readonly branch: AgentBranch;
+    /** App state; treated as immutable by the Kit and snapshotted on write. */
     readonly state: State;
+    /** Creation instant in epoch milliseconds. */
     readonly createdAtMs: number;
 }
+/** A whole family: its versions and which version is currently active. */
 export interface FamilyRecord<State> {
+    /** Family id; also the store key. */
     readonly id: string;
+    /** Optimistic concurrency token; every accepted mutation increments it by one. */
     readonly revision: number;
+    /** Id of the active version; promotion moves this pointer. */
     readonly activeId: string;
+    /** Instant after which the record is no longer retained, in epoch milliseconds. */
     readonly expiresAtMs: number;
+    /** Versions in creation order; bounded by `maxVersions` when configured. */
     readonly versions: readonly FamilyVersion<State>[];
 }
 /** CAS must cover every writer and the active pointer in one real storage commit. */
 export interface FamilyStore<State> {
+    /** Returns the record, or `undefined` when it does not exist. */
     load(id: string): Promise<FamilyRecord<State> | undefined>;
+    /** Commits `next` only when the stored revision equals `expectedRevision`; returns success. */
     compareAndSwap(id: string, expectedRevision: number | undefined, next: FamilyRecord<State>): Promise<boolean>;
 }
+/** App-owned hooks and limits for one family. */
 export interface FamilyDefinition<State, App> {
     readonly store: FamilyStore<State>;
+    /** Maximum retained versions; older versions are dropped once the bound is exceeded. */
     readonly maxVersions?: number;
+    /** Retention window in milliseconds, measured from a write. */
     readonly retentionMs?: number;
+    /** Clock override for timestamps and expiry; defaults to `Date.now`. */
     readonly now?: () => number;
+    /** Validates a state loaded from the store before it is used. */
     isState(value: unknown): value is State;
+    /** Guards one mutation; called before any write, including with an absent record. */
     authorize(operation: FamilyOperation, record: FamilyRecord<State> | undefined, context: OperationContext<App>): MaybePromise<void>;
+    /** Validates a candidate version before it is appended. */
     validate(candidate: FamilyVersion<State>, context: OperationContext<App>): MaybePromise<void>;
+    /**
+     * Resolves a three-way merge.
+     *
+     * Returns the merged state and any conflicts. A non-empty conflict list aborts the merge without
+     * writing a version, so `value` is ignored in that case.
+     */
     merge?(input: {
         base: State;
         target: State;
@@ -40,13 +82,17 @@ export interface FamilyDefinition<State, App> {
         conflicts: readonly string[];
     }>;
 }
+/** Compiled family API. Every mutation returns the record after the write. */
 export interface AgentFamily<State, App> {
+    /** Reads the record; throws when the family does not exist or has expired. */
     read(id: string, context: OperationContext<App>): Promise<FamilyRecord<State>>;
+    /** Creates the first version and makes it active. */
     create(request: {
         id: string;
         branch: AgentBranch;
         state: State;
     }, context: OperationContext<App>): Promise<FamilyRecord<State>>;
+    /** Appends a version forked from `parentId`; the active pointer does not change. */
     fork(request: {
         id: string;
         revision: number;
@@ -54,6 +100,7 @@ export interface AgentFamily<State, App> {
         branch: AgentBranch;
         state: State;
     }, context: OperationContext<App>): Promise<FamilyRecord<State>>;
+    /** Merges `source` into `target`; `saved` is false when the merge reported conflicts. */
     merge(request: {
         id: string;
         revision: number;
@@ -65,6 +112,7 @@ export interface AgentFamily<State, App> {
         record: FamilyRecord<State>;
         conflicts: readonly string[];
     }>;
+    /** Makes `candidateId` active; fails when the active version changed since `expectedActiveId`. */
     promote(request: {
         id: string;
         revision: number;

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

@@ -1 +1,2 @@
+/** Operation names accepted by the family `authorize` hook. */
 export const familyOperations = ['create', 'fork', 'merge', 'promote'];