@leuduan/lagent 0.0.0-stage → 44.0.0

package/dist/state/inbox.d.ts

@@ -0,0 +1,188 @@
+import type { ExtensionRecord, InboxTarget, QueuedInput, Seq, ThreadInput } from '../records/journal.js';
+import type { AppendEntry, Journal } from '../journal/index.js';
+import type { DeepReadonly, ReadonlyJsonValue } from '../util/json.js';
+import type { RouteAuthority } from './route.js';
+import type { FreshOpening, ForkOpening } from './birth.js';
+import { type Wake } from './wake.js';
+/**
+ * Why a write-time callback refused its write, as data a host or plugin can act on without parsing
+ * `message`: the text a person is shown, an optional `code` for the cause when a reader branches on
+ * one, and optional `data` for its facts.
+ */
+export type Refusal = {
+    readonly message: string;
+    readonly code?: string;
+    readonly data?: ReadonlyJsonValue;
+};
+/**
+ * What a write-time callback returns: the plugin rows to add to the write's group, or `{ refuse }`,
+ * its explicit veto, which writes nothing and gives the {@link Refusal} to whoever asked. Anything
+ * the callback throws is a failure, not a veto: it propagates as it was thrown.
+ */
+export type RowsResult = readonly AppendEntry<'ext'>[] | {
+    readonly refuse: Refusal;
+};
+/** Whether a callback vetoed its write. */
+export declare const isVeto: (result: RowsResult) => result is {
+    readonly refuse: Refusal;
+};
+/** What every write that queues input tells its callback: the thread, where the input waits, and the run its cause joins. */
+type WriteBase = {
+    readonly threadId: string;
+    /** Where the input waits, which `send` decides inside the write; a creation always queues for `next-turn`. */
+    readonly target: InboxTarget;
+    /** The run request the write's cause joins or opens; `null` when it brings none. */
+    readonly runId: string | null;
+};
+/**
+ * What a write-time callback is told, by the write it runs in. A creation or a fork carries the
+ * resolved opening it records, a frozen copy, so a callback reads what core records and cannot
+ * change it; `inputId` is the first input's id, `null` when the write queues none. A `send`
+ * carries the id it queues.
+ */
+export type RowsWrite = (WriteBase & {
+    readonly kind: 'create';
+    readonly inputId: string | null;
+    readonly opening: DeepReadonly<FreshOpening>;
+}) | (WriteBase & {
+    readonly kind: 'fork';
+    readonly inputId: string | null;
+    readonly opening: DeepReadonly<ForkOpening>;
+}) | (WriteBase & {
+    readonly kind: 'send';
+    readonly inputId: string;
+});
+/**
+ * A write-time callback on a write that queues input — `create`, `fork` or `send`: run inside the
+ * write's transaction, once the write's own rows are built and before anything is stored, it returns
+ * plugin rows for the same group, or vetoes the write by returning `{ refuse }` (see
+ * {@link RowsResult}). Synchronous, as every `transact` callback is.
+ */
+export type WriteRows = (write: RowsWrite) => RowsResult;
+/**
+ * What `send` returns for input it accepted: the input's id and `queuedAt`, the seq of the row that
+ * queued it. The id is the one the caller passed or the one `send` made.
+ */
+export type InputReceipt = {
+    readonly inputId: string;
+    readonly queuedAt: Seq;
+};
+/**
+ * What a `send` did: queued the input, with the run request its wake joined or opened in the same
+ * write (`runId`, `null` when it had no wake; see `waitForRun`); found its id already known and
+ * wrote nothing, its receipt naming the row that queued it the first time; or wrote nothing because
+ * its `rows` callback vetoed, for `refusal`.
+ */
+export type SendOutcome = ({
+    readonly status: 'queued';
+    readonly runId: string | null;
+} & InputReceipt) | ({
+    readonly status: 'known';
+} & InputReceipt) | {
+    readonly status: 'refused';
+    readonly refusal: Refusal;
+};
+/**
+ * How `send` queues: under `id`, attributed to `source`, with `rows` added to its write, and with
+ * `wake`, a cause in the same write that asks the thread to run (`{}` for a person's). A sourced
+ * input needs its `id`.
+ */
+export type SendOptions = {
+    readonly id?: string;
+    readonly source?: ExtensionRecord;
+    readonly rows?: WriteRows;
+    readonly wake?: Wake;
+    /**
+     * Where the input waits; omitted, admission places it (a running turn's next step, else a turn of
+     * its own). `next-turn` waits for a turn of its own even while a run holds the thread. `next-step`
+     * joins the next model step whichever turn takes it: a running turn's, a resumed turn's once its
+     * parked calls are answered, or a new turn's first step together with what waits for that turn.
+     */
+    readonly target?: InboxTarget;
+};
+/**
+ * A write-time callback on a `withdraw`: run inside its transaction, told whether the input was
+ * still queued and is withdrawn by this write, it returns plugin rows for the same group, written
+ * either way, or vetoes the withdrawal by returning `{ refuse }` (see {@link RowsResult}).
+ */
+export type WithdrawRows = (write: {
+    readonly threadId: string;
+    readonly withdrawn: boolean;
+}) => RowsResult;
+export type WithdrawOptions = {
+    readonly rows?: WithdrawRows;
+};
+/**
+ * What a `withdraw` did: took the input out of the queue (`withdrawn`); found it not queued, being
+ * claimed, discarded or unknown (`not-queued`), writing only what `rows` returned; or wrote nothing
+ * because `rows` vetoed, with its `refusal`.
+ */
+export type WithdrawOutcome = {
+    readonly status: 'withdrawn' | 'not-queued';
+} | {
+    readonly status: 'refused';
+    readonly refusal: Refusal;
+};
+/**
+ * Input waiting for a boundary, held in the journal rather than in memory.
+ *
+ * Every mutation is an `inbox/spliced` event, so a message queued while the agent was busy survives
+ * a crash exactly like the conversation does. `next-turn` is claimed only by a turn's first step,
+ * when that step asks the model: a turn that opens by answering calls an earlier turn left leaves it
+ * for the next turn. `next-step` joins the next model step of whichever turn takes it: the turn in
+ * flight, which is what makes steering possible, a resumed turn once its calls are answered, or the
+ * first step of the next turn.
+ */
+export declare class Inbox {
+    private readonly journal;
+    private readonly threadId;
+    constructor(journal: Journal, threadId: string);
+    private get queues();
+    private get state();
+    get nextTurn(): readonly QueuedInput[];
+    get nextStep(): readonly QueuedInput[];
+    /** The row that queued input `id`, or `undefined` when this thread was never handed that id. */
+    private queuedAt;
+    /** Everything waiting for a step to claim it, in the order it was sent. */
+    get pending(): QueuedInput[];
+    /**
+     * Idempotent durable input. The target is the sender's when it names one; otherwise execution
+     * admission chooses it (`target`), asked inside the write, as is whether the id was queued
+     * before: two sends of one id queue it once, and a known id calls no `rows`. Input attributed to
+     * a plugin (`source`) needs the id the plugin derived, since a redelivery must find it. `routes`
+     * checks a wake's route statement.
+     */
+    send(input: ThreadInput, target: () => InboxTarget, options?: SendOptions, routes?: RouteAuthority): Promise<SendOutcome>;
+    /**
+     * Discards one queued input by id, wherever it waits, deciding inside the write whether it is still
+     * queued; `rows` adds a plugin's rows to the same write either way (see {@link WithdrawRows}).
+     */
+    withdraw(id: string, options?: WithdrawOptions): Promise<WithdrawOutcome>;
+    /**
+     * The rows that discard everything pending, `next-step` first so a drained turn cannot pick it
+     * up: none when nothing waits. Built inside the write that carries them, a cancel's.
+     */
+    clearRows(): AppendEntry<'inbox/spliced'>[];
+    /**
+     * The batch one step will consume: everything queued for the next step, plus, when this boundary
+     * opens a turn, the head of what waits for one: a single unsourced input, or every consecutive
+     * sourced input at the head. The batch is ordered by seq; order holds within a batch, not across
+     * the whole queue, so `next-step` input sent after something still waiting for a turn can enter
+     * before it. A person's message is never skipped to collect plugin input waiting for a turn behind
+     * it, so sourced input left at `next-turn` (notice, notice, person, notice) opens three turns:
+     * `[N, N]`, `[U]`, `[N]`; with the notices at `next-step`, it opens one: `[N, N, U, N]`. With
+     * `sentBack`, a later step takes the next such batch too: a turn that opened by answering calls
+     * claimed nothing that waited for a turn, and once a stop check sent its answer back, what waits
+     * could be what the check holds the answer for.
+     *
+     * Reading only. The input leaves the queue when its `input/message` is appended, so recording it
+     * and claiming it are the same event and a crash between them is not a thing that can happen.
+     */
+    peek(target: InboxTarget, sentBack?: boolean): QueuedInput[];
+    /**
+     * Array-splice semantics, normalized against the inbox as it stands: the row that records it, or
+     * nothing to record. Built inside a write, so the indices are the ones the row lands on.
+     */
+    private spliceEntry;
+}
+export {};

package/dist/state/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * What the rest of the package may use of recorded state: the folds of a thread's rows, the queries
+ * over them, and the writes that need no activation (the inbox, closing an interrupted turn, the
+ * surface replacement writer). Nothing here runs a turn or imports Cordis; the loop executes against
+ * these and the services read them. The journal substrate itself is `journal/`, imported directly.
+ */
+export * from './thread.js';
+export * from './turns.js';
+export * from './dispatches.js';
+export * from './waits.js';
+export * from './confirmations.js';
+export * from './prompt.js';
+export * from './inputs.js';
+export * from './installations.js';
+export * from './surface.js';
+export * from './requests.js';
+export * from './holds.js';
+export * from './chain.js';
+export * from './route.js';
+export * from './errors.js';
+export * from './limits.js';
+export * from './birth.js';
+export * from './continuation.js';
+export * from './decide.js';
+export * from './forks.js';
+export * from './inbox.js';
+export * from './recovery.js';
+export * from './replace.js';
+export * from './surfaceRead.js';
+export * from './summary.js';
+export * from './wake.js';

package/dist/state/inputs.d.ts

@@ -0,0 +1,58 @@
+import type { InboxTarget, QueuedInput, Seq } from '../records/journal.js';
+import type { ReadonlyState } from '../util/foldState.js';
+import type { Reducer, ThreadState } from './thread.js';
+export type InboxState = Record<InboxTarget, QueuedInput[]>;
+/**
+ * Input waiting for a turn or a step boundary. Durable, so a crash does not lose a queued message.
+ * A fork starts with nothing queued: its source's queued input is not the fork's.
+ */
+export declare const inbox: Reducer<InboxState>;
+/** Where one input id's life is recorded: the row that queued it, and the step's row that claimed it. */
+export type InputRows = {
+    readonly queuedAt: Seq;
+    readonly claimedAt: Seq | null;
+};
+/**
+ * Every input id this thread was ever handed: the row that queued it and, once a step took it, the
+ * `input/message` that claimed it. Never forgets: this is what makes `send` with an explicit id
+ * idempotent across a re-dispatch or a restart, and why a withdrawn or cancelled id stays
+ * spent. A fork starts over: the ids its source was handed are the source's.
+ */
+export declare const inputs: Reducer<Map<string, InputRows>>;
+/**
+ * What became of the input id a thread was handed: `unknown` when it never was; `queued` while it
+ * waits, for `target`; `claimed` once a step took it; `discarded` when it left the queue unclaimed,
+ * withdrawn or cleared by a cancel. Each names the row that queued it, and a claim the
+ * `input/message` that took it. A discarded or claimed id stays spent: it is never queued again.
+ */
+export type InputFate = {
+    readonly state: 'unknown';
+} | {
+    readonly state: 'queued';
+    readonly queuedAt: Seq;
+    readonly target: InboxTarget;
+} | {
+    readonly state: 'claimed';
+    readonly queuedAt: Seq;
+    readonly claimedAt: Seq;
+} | {
+    readonly state: 'discarded';
+    readonly queuedAt: Seq;
+};
+/**
+ * The fate of input `id` from a thread's state: the one answer to "what became of input X", read
+ * inside a write or a contributor from the state the journal folds, or through `ThreadView.input`.
+ * A fork's own ids only: its source's are the source's.
+ */
+export declare function inputFate(state: ReadonlyState<Pick<ThreadState, 'inputs' | 'inbox'>>, id: string): InputFate;
+/**
+ * Whether a fork has yet to claim the task it was created with. A fork cut at a request inherits a
+ * conversation that ends on input its source is answering. Created to regenerate that answer, the
+ * fork owes it; created with a task, it owes only the task. So a task discarded before it was
+ * claimed — by `cancel()` — leaves the fork with nothing to do, rather than answering its source's
+ * request. Any input the fork records settles it.
+ */
+export declare const forkTask: Reducer<{
+    spawnSeq: Seq | null;
+    unclaimed: boolean;
+}>;

package/dist/state/installations.d.ts

@@ -0,0 +1,28 @@
+import type { InstallationLifetime } from '../records/journal.js';
+import type { JsonValue } from '../util/json.js';
+import type { Reducer } from './thread.js';
+/** One installation a thread holds, as its folds read it. */
+export type InstallationRecord = {
+    readonly installationId: string;
+    readonly presetId: string;
+    /** The validated configuration, defaults included: exactly what `setup` receives. */
+    readonly config: JsonValue;
+    /**
+     * `defining` for one recorded as such in its thread's spawn row, on this thread or on the one a
+     * fork inherited it from, which cannot be removed; `configurable` for any other, one applied
+     * later included.
+     */
+    readonly lifetime: InstallationLifetime;
+};
+/** A thread's installations: the current ones in application order, and every id it ever used. */
+export type InstallationsState = {
+    readonly current: Map<string, InstallationRecord>;
+    readonly used: Set<string>;
+};
+/**
+ * The preset installations that define a thread's plugins. A fork inherits its source's
+ * installations and reserved ids at the cut: its own spawn row carries none, and the source's spawn
+ * row, which it folds through lineage, keeps a defining installation defining on every fork.
+ * Installations never move, so application order is also the order they are restored in.
+ */
+export declare const installations: Reducer<InstallationsState>;

package/dist/state/limits.d.ts

@@ -0,0 +1,14 @@
+/**
+ * What bounds a runaway turn. Each is a number the loop can hand back to the model as a tool result
+ * or a turn ending it can react to; together with the depth cap they bound total spend.
+ */
+export type TurnLimits = {
+    /** Positive finite integer: steps in one thread's turn before it stops with `max-steps`. */
+    maxStepsPerTurn: number;
+    /** Non-negative finite integer: nesting below a root. Zero forbids delegation; each hop is one level. */
+    maxThreadDepth: number;
+    /** Positive finite integer: tool calls dispatched at once within one step; the rest wait for a slot. */
+    maxParallelToolCalls: number;
+};
+export declare const DEFAULT_TURN_LIMITS: TurnLimits;
+export declare const resolveLimits: (overrides?: Partial<TurnLimits>) => TurnLimits;

package/dist/state/prompt.d.ts

@@ -0,0 +1,13 @@
+import type { ToolSpec } from '../llm/primitives.js';
+import type { PromptBlock } from '../llm/prompt.js';
+import type { Reducer } from './thread.js';
+/**
+ * The system prompt a thread sends: the latest `thread/prompt` row, or none yet. A fork inherits
+ * it and never renders its own, so it sends its source's exact prompt.
+ */
+export declare const threadPrompt: Reducer<PromptBlock[] | null>;
+/**
+ * The tool specifications a thread's requests send: the latest `thread/tools` row, or none before
+ * its first request. Read at a request's seq, what that request sent. A fork inherits it.
+ */
+export declare const threadTools: Reducer<readonly ToolSpec[] | null>;

package/dist/state/recovery.d.ts

@@ -0,0 +1,7 @@
+import type { Journal } from '../journal/index.js';
+import type { TurnLimits } from './limits.js';
+/**
+ * Close a process-interrupted turn from journal state, including when no new execution is needed.
+ * Decided inside the write, so a turn something else closed meanwhile is not closed twice.
+ */
+export declare function closeInterruptedTurn(journal: Journal, threadId: string, limits: TurnLimits): Promise<void>;

package/dist/state/replace.d.ts

@@ -0,0 +1,33 @@
+import type { Journal } from '../journal/index.js';
+import { type JournalEventInput, type ReplacementTrigger, type Seq } from '../records/journal.js';
+import { type RowRef } from './surface.js';
+type ReplacedData = JournalEventInput['surface/replaced'];
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+/**
+ * One replacement as a strategy offers it: what a `surface/replaced` row records that the strategy
+ * decides — its kind, stand-in and `source` — and the rows it replaces, in surface order. The
+ * engine fills in the rest.
+ */
+export type ReplacementInput = DistributiveOmit<ReplacedData, 'trigger' | 'turn' | 'step' | 'auxiliary_request_seq'> & {
+    /** The rows replaced: a contiguous run of the current surface for a `span`, one row for a `rewrite`. */
+    readonly source_seqs: readonly Seq[];
+    /** The `auxiliary/request` row the stand-in was made from, when a model call made it. */
+    readonly auxiliary_request_seq?: Seq | null;
+};
+/** Where a replacement is recorded: what caused it, and the turn and step, both `null` between turns. */
+export type ReplacementContext = {
+    readonly trigger: ReplacementTrigger;
+    readonly turn: number | null;
+    readonly step: number | null;
+};
+/**
+ * The one way a replacement reaches the journal: appends `replacements` as one atomic group on
+ * `threadId`, each with the context filled in. The group is judged inside the write, against the
+ * durable surface, each row against the surface the previous one left, and refused whole with a
+ * {@link ReplacementRefusedError} when one breaks a rule; nothing of it is written then. Counts
+ * nothing and judges nothing of its own: the rules are the surface's (`judgeGroup`).
+ *
+ * The caller holds the thread's lease; `runSurfacePrepare` checks it before recording.
+ */
+export declare function replaceSurface(journal: Journal, threadId: string, context: ReplacementContext, replacements: readonly ReplacementInput[]): Promise<RowRef[]>;
+export {};

package/dist/state/requests.d.ts

@@ -0,0 +1,129 @@
+import type { CancelIntent, RunChain, RunOutcomeKind, RunSettledReason, Seq } from '../records/journal.js';
+import type { InputFate } from './inputs.js';
+import type { Reducer } from './thread.js';
+/** One `run/cause` row as the request fold keeps it. */
+export type RunCause = {
+    readonly seq: Seq;
+    /** The row's timestamp: how old the cause is, which the startup policy judges. */
+    readonly at: string;
+    readonly inputId: string | null;
+    readonly releases: boolean;
+    readonly chain: RunChain;
+};
+/** The request a thread is authorized to run, with every cause it holds, residual ones first. */
+export type PendingRun = {
+    readonly runId: string;
+    /** The `run/requested` row. */
+    readonly requestedAt: Seq;
+    readonly causes: readonly RunCause[];
+};
+/** One `run/settled` row as the request fold keeps it. */
+export type RunSettlement = {
+    readonly runId: string;
+    readonly seq: Seq;
+    readonly outcome: RunOutcomeKind;
+    readonly reason: RunSettledReason;
+    readonly errorText: string | null;
+    readonly through: Seq;
+    readonly residual: readonly Seq[];
+};
+/** One `thread/cancel` row as the request fold keeps it. */
+export type CancelRecord = {
+    readonly seq: Seq;
+    readonly cancelId: string;
+    readonly intent: CancelIntent;
+    readonly runId: string | null;
+    readonly reason: string;
+};
+/**
+ * A thread's run requests, folded from its `run/*` and `thread/cancel` rows: the pending request,
+ * the first cancel that captured it, the latest settlement and user cancel, the latest releasing
+ * cause, and every request it ever
+ * opened with its settlement, so a waiter can read any run by id. A row that breaks the request
+ * rules (a cause or settlement for a run that is not pending, a request opened over a pending one)
+ * is kept in `inconsistencies` rather than thrown: core's fold is fatal, and a bad row must not
+ * stop the thread from being read.
+ */
+export type RequestsState = {
+    pending: PendingRun | null;
+    /**
+     * The first cancel row naming the pending request's execution, whichever its intent: what a
+     * recovery settles that request by when the process died before its execution's finalization did.
+     * The first capture fixes the intent; a later cancel joining it changes nothing here.
+     */
+    pendingCancel: CancelRecord | null;
+    latestSettlement: RunSettlement | null;
+    latestUserCancel: CancelRecord | null;
+    /** The seq of the latest cause that releases holds, on any request. */
+    latestReleasing: Seq | null;
+    /** Every request by id: its `run/requested` row, and its settlement once it has one. */
+    readonly runs: Map<string, {
+        readonly requestedAt: Seq;
+        settlement: RunSettlement | null;
+    }>;
+    /**
+     * The latest `turn/start`: the run it served and the attempt cutoff of the execution that opened
+     * it, which a recovery settles a failure recorded before a crash with.
+     */
+    latestTurn: {
+        readonly seq: Seq;
+        readonly runId: string;
+        readonly attemptCutoff: Seq;
+    } | null;
+    /**
+     * The turns of the pending request in a row, since its latest releasing cause, that ended
+     * `interrupted` with the activation or the judgment as the cause; an abandonment by recovery leaves
+     * the count as it was. What an
+     * entry decision spends its repairs against: a request held on an interrupted turn that was
+     * already repaired is not repaired again until a releasing cause releases it.
+     */
+    interruptions: number;
+    /** The causes a settlement carried over, until the successor request it opened takes them. */
+    carried: readonly RunCause[];
+    readonly inconsistencies: string[];
+};
+/**
+ * The request fold: core's {@link RequestsState} concern of `threadState`. A fork starts with none
+ * of its source's requests.
+ */
+export declare const requests: Reducer<RequestsState>;
+/** Where a run stands from its rows alone: pending, settled with its settlement, or unknown on this thread. */
+export type DurableRunState = {
+    readonly state: 'pending';
+} | {
+    readonly state: 'settled';
+    readonly settlement: RunSettlement;
+} | {
+    readonly state: 'unknown';
+};
+export declare function durableRunState(state: RequestsState, runId: string): DurableRunState;
+/**
+ * What a settlement decided, and where its execution's cutoffs fall, for {@link residualOf}: the
+ * attempt cutoff, the position the execution was admitted at, and the cancel's write, when a cancel
+ * settled the request and its write landed.
+ */
+export type ResidualRule = {
+    readonly outcome: RunOutcomeKind;
+    readonly reason: RunSettledReason;
+    readonly attemptCutoff: Seq;
+    readonly cancelSeq: Seq | null;
+};
+/**
+ * The causes of `pending` a settlement carries over to a successor request, by seq. A cause whose
+ * input a step claimed, or that left the queue unclaimed, carries nothing whatever its position;
+ * of the rest:
+ *
+ * - `completed` carries the causes recorded after the attempt cutoff: a wake that landed while the
+ *   execution was finishing runs once more;
+ * - `failed` carries only the releasing ones recorded after the cutoff: a person's message that
+ *   arrived during the attempt runs, while the cause that started it, and a notice or a fire, does
+ *   not retry a failure;
+ * - a cancel's carries those recorded after its write, which it did not clear, or, when that write
+ *   failed and cleared nothing, those after the attempt cutoff;
+ * - an `obsolete` request carries nothing: its authority is gone, and a successor comes with causes
+ *   of its own.
+ *
+ * `fate` reads an input's fate on the thread (`inputFate`). Input left queued with no cause runs
+ * again only when a new cause arrives.
+ */
+export declare function residualOf(pending: PendingRun, rule: ResidualRule, fate: (inputId: string) => InputFate['state']): Seq[];

package/dist/state/route.d.ts

@@ -0,0 +1,61 @@
+import type { ModelRoute } from '../llm/provider.js';
+import type { ModelSelection } from '../llm/provider.js';
+import type { Reducer } from './thread.js';
+/**
+ * What a wake says about the route it runs on, checked by core inside the write that records it:
+ * `expect`, the route the caller was shown and did not change; `select`, the route to run on,
+ * folded over the thread's route as a creation's fields are, so a complete one is itself. A wake
+ * that states none runs on the thread's route as it is, unchecked.
+ */
+export type RouteStatement = {
+    readonly expect: ModelRoute;
+} | {
+    readonly select: ModelSelection;
+};
+/**
+ * The thread's route as a statement is checked against: the route, why it cannot run here
+ * (its provider is not registered), and whether a route change is accepted now — no run serving the
+ * pending request holds the thread, and no request is pending, the route cannot run, or the
+ * request is held by a failure or a cancellation.
+ */
+export type Target = {
+    readonly route: ModelRoute;
+    readonly blocked: string | null;
+    readonly selectable: boolean;
+};
+/** What checks a route statement inside its write: the thread owner, which knows admission and the registry. */
+export interface RouteAuthority {
+    /** The thread's target as its rows and the process stand now. */
+    target(threadId: string): Target;
+    /** `selection` folded over `base`; throws `RouteUnavailableError` when the provider is not registered. */
+    resolve(selection: ModelSelection, base: ModelRoute): ModelRoute;
+}
+/** A route statement does not match the thread's route as it stands, or would change it when it may not. */
+export declare class RouteConflictError extends Error {
+    readonly threadId: string;
+    readonly route: ModelRoute;
+    constructor(threadId: string, 
+    /** The thread's route when the statement was refused. */
+    route: ModelRoute, reason: string);
+}
+/** A route cannot run here: its provider is not registered. Nothing was written, or no turn opened. */
+export declare class RouteUnavailableError extends Error {
+    readonly route: Pick<ModelRoute, 'provider'> & Partial<ModelRoute>;
+    constructor(route: Pick<ModelRoute, 'provider'> & Partial<ModelRoute>);
+}
+/** Whether two routes are the same tuple; a `null` effort (the provider's own default) is a value like any other. */
+export declare const sameRoute: (a: ModelRoute, b: ModelRoute) => boolean;
+/**
+ * The route a cause records for `statement`, read inside its write: `null` when the cause leaves
+ * the thread's route as it is. `expect` needs the route runnable, then matching; `select` resolves
+ * over it, and a different route is written only while the target is selectable. Refusals throw,
+ * which refuses the whole write.
+ */
+export declare function statedRoute(threadId: string, statement: RouteStatement, routes: RouteAuthority): ModelRoute | null;
+/**
+ * The thread's route: the one its spawn row was born with, replaced by each cause that changed it.
+ * A lineage fold: a fork, born with none of its own, goes on with the route its inherited rows fold
+ * to at the cut, which keeps it on the model whose cache holds its history. Nothing else changes it:
+ * not turns, settlements, cancels or compaction. `null` only before a spawn row, which no thread lacks.
+ */
+export declare const threadRoute: Reducer<ModelRoute | null>;

package/dist/state/summary.d.ts

@@ -0,0 +1,16 @@
+import type { Journal, ThreadSummaryCore } from '../journal/index.js';
+import type { TurnLimits } from './limits.js';
+/**
+ * A thread's catalog summary, from its folds as they stand: the spawn row's identity, how its last
+ * turn ended, the thread's route, whether a turn is open, whether a run would find
+ * work, and where its run requests stand — the pending one the run owner picks its candidates by at
+ * `threads.start`, from the catalog, so only those are loaded and run; the latest settlement and person's cancel the holds
+ * derive from; and the latest answer, which tells a parked caller an answer landed under it. The confirmations it waits on and the calls it
+ * suspended are listed as descriptors, enough to find them without the thread's rows; the full
+ * requests and dependencies come from the thread once it is loaded.
+ *
+ * Registered with the journal by the journal plugin, which is how `journal/` never learns what a
+ * turn is. Everything here is a thread-scoped fold, so the summary is a function of the thread's
+ * own lineage and nothing else.
+ */
+export declare function summarizeThread(journal: Journal, threadId: string, limits: TurnLimits): ThreadSummaryCore;