@leuduan/lagent 0.0.0-stage → 0.1.2

package/dist/plugins/compaction/records.d.ts

@@ -0,0 +1,227 @@
+import { z } from 'zod';
+/** The plugin that writes compaction's stand-ins, whichever strategy wrote them, as their `source` names it. */
+export declare const COMPACTION_PLUGIN = "lagent:compaction";
+/**
+ * The `source` of every checkpoint the `summarize` strategy records: what it planned, so a reader
+ * of the row can tell how much room the summary had and whether the plan reached its target.
+ */
+export declare const checkpointRecord: {
+    record: (value: {
+        summary_cap: number;
+        target_reached: boolean | null;
+    }) => import("../../models/index.js").ExtensionRecord;
+    parse: (value: {
+        summary_cap: number;
+        target_reached: boolean | null;
+    }) => {
+        summary_cap: number;
+        target_reached: boolean | null;
+    };
+    entry: (value: {
+        summary_cap: number;
+        target_reached: boolean | null;
+    }, options: import("../../plugin.js").AppendOptions) => {
+        type: "ext";
+        data: {
+            plugin: string;
+            instance_id: string;
+            kind: string;
+            version: number;
+            data: z.core.util.JSONType;
+        };
+        options: import("../../plugin.js").AppendOptions;
+    };
+    append(journal: import("../../plugin.js").PluginJournal, value: {
+        summary_cap: number;
+        target_reached: boolean | null;
+    }, options: import("../../plugin.js").AppendOptions): Promise<import("../../models/index.js").JournalEvent<"ext">>;
+    read(event: import("../../models/index.js").JournalEvent): {
+        summary_cap: number;
+        target_reached: boolean | null;
+    } | undefined;
+    contribution(message: {
+        role?: import("../../models/index.js").InputRole;
+        content: string | readonly import("../../llm/content.js").ContentPartInput[];
+    }, value: {
+        summary_cap: number;
+        target_reached: boolean | null;
+    }, options?: {
+        sourceSeqs?: readonly import("../../models/index.js").Seq[];
+    }): import("../../models/index.js").StepContribution;
+    matchesSource(record: import("../../util/json.js").DeepReadonly<import("../../models/index.js").ExtensionRecord>): boolean;
+    rejection(reason: string, value: {
+        summary_cap: number;
+        target_reached: boolean | null;
+    }): {
+        decision: "reject";
+        reason: string;
+        source: import("../../models/index.js").ExtensionRecord;
+    };
+    readContribution: (event: import("../../models/index.js").JournalEvent) => {
+        summary_cap: number;
+        target_reached: boolean | null;
+    } | undefined;
+    readSource: (source: import("../../util/json.js").DeepReadonly<import("../../models/index.js").ExtensionRecord> | null) => {
+        summary_cap: number;
+        target_reached: boolean | null;
+    } | undefined;
+    told: import("../../plugin.js").PluginProjection<import("../../kit/extension.js").ToldNotices<{
+        summary_cap: number;
+        target_reached: boolean | null;
+    }>>;
+    projection<State>(fold: {
+        key: string;
+        init(): State;
+        apply(state: State, value: {
+            summary_cap: number;
+            target_reached: boolean | null;
+        }, event: import("../../models/index.js").JournalEvent<"ext">): State;
+        onFork?: "inherit" | "reset";
+    }): import("../../plugin.js").PluginProjection<State>;
+};
+/**
+ * The `source` of every stand-in the `prune` strategy records: what the result it replaced held,
+ * its text in characters and its attachments (image and file parts), which the stand-in drops with
+ * the text.
+ */
+export declare const pruneRecord: {
+    record: (value: {
+        chars: number;
+        attachments: number;
+    }) => import("../../models/index.js").ExtensionRecord;
+    parse: (value: {
+        chars: number;
+        attachments: number;
+    }) => {
+        chars: number;
+        attachments: number;
+    };
+    entry: (value: {
+        chars: number;
+        attachments: number;
+    }, options: import("../../plugin.js").AppendOptions) => {
+        type: "ext";
+        data: {
+            plugin: string;
+            instance_id: string;
+            kind: string;
+            version: number;
+            data: z.core.util.JSONType;
+        };
+        options: import("../../plugin.js").AppendOptions;
+    };
+    append(journal: import("../../plugin.js").PluginJournal, value: {
+        chars: number;
+        attachments: number;
+    }, options: import("../../plugin.js").AppendOptions): Promise<import("../../models/index.js").JournalEvent<"ext">>;
+    read(event: import("../../models/index.js").JournalEvent): {
+        chars: number;
+        attachments: number;
+    } | undefined;
+    contribution(message: {
+        role?: import("../../models/index.js").InputRole;
+        content: string | readonly import("../../llm/content.js").ContentPartInput[];
+    }, value: {
+        chars: number;
+        attachments: number;
+    }, options?: {
+        sourceSeqs?: readonly import("../../models/index.js").Seq[];
+    }): import("../../models/index.js").StepContribution;
+    matchesSource(record: import("../../util/json.js").DeepReadonly<import("../../models/index.js").ExtensionRecord>): boolean;
+    rejection(reason: string, value: {
+        chars: number;
+        attachments: number;
+    }): {
+        decision: "reject";
+        reason: string;
+        source: import("../../models/index.js").ExtensionRecord;
+    };
+    readContribution: (event: import("../../models/index.js").JournalEvent) => {
+        chars: number;
+        attachments: number;
+    } | undefined;
+    readSource: (source: import("../../util/json.js").DeepReadonly<import("../../models/index.js").ExtensionRecord> | null) => {
+        chars: number;
+        attachments: number;
+    } | undefined;
+    told: import("../../plugin.js").PluginProjection<import("../../kit/extension.js").ToldNotices<{
+        chars: number;
+        attachments: number;
+    }>>;
+    projection<State>(fold: {
+        key: string;
+        init(): State;
+        apply(state: State, value: {
+            chars: number;
+            attachments: number;
+        }, event: import("../../models/index.js").JournalEvent<"ext">): State;
+        onFork?: "inherit" | "reset";
+    }): import("../../plugin.js").PluginProjection<State>;
+};
+/**
+ * A summary the `summarize` strategy could not use, recorded with the request that asked for it:
+ * what its breaker counts. A run of them stops pressure from compacting until a checkpoint commits
+ * or the thread's installations change; it lasts across reopening, and a fork inherits it.
+ */
+export declare const unusableSummaryRecord: {
+    record: (value: {
+        reason: string;
+    }) => import("../../models/index.js").ExtensionRecord;
+    parse: (value: {
+        reason: string;
+    }) => {
+        reason: string;
+    };
+    entry: (value: {
+        reason: string;
+    }, options: import("../../plugin.js").AppendOptions) => {
+        type: "ext";
+        data: {
+            plugin: string;
+            instance_id: string;
+            kind: string;
+            version: number;
+            data: z.core.util.JSONType;
+        };
+        options: import("../../plugin.js").AppendOptions;
+    };
+    append(journal: import("../../plugin.js").PluginJournal, value: {
+        reason: string;
+    }, options: import("../../plugin.js").AppendOptions): Promise<import("../../models/index.js").JournalEvent<"ext">>;
+    read(event: import("../../models/index.js").JournalEvent): {
+        reason: string;
+    } | undefined;
+    contribution(message: {
+        role?: import("../../models/index.js").InputRole;
+        content: string | readonly import("../../llm/content.js").ContentPartInput[];
+    }, value: {
+        reason: string;
+    }, options?: {
+        sourceSeqs?: readonly import("../../models/index.js").Seq[];
+    }): import("../../models/index.js").StepContribution;
+    matchesSource(record: import("../../util/json.js").DeepReadonly<import("../../models/index.js").ExtensionRecord>): boolean;
+    rejection(reason: string, value: {
+        reason: string;
+    }): {
+        decision: "reject";
+        reason: string;
+        source: import("../../models/index.js").ExtensionRecord;
+    };
+    readContribution: (event: import("../../models/index.js").JournalEvent) => {
+        reason: string;
+    } | undefined;
+    readSource: (source: import("../../util/json.js").DeepReadonly<import("../../models/index.js").ExtensionRecord> | null) => {
+        reason: string;
+    } | undefined;
+    told: import("../../plugin.js").PluginProjection<import("../../kit/extension.js").ToldNotices<{
+        reason: string;
+    }>>;
+    projection<State>(fold: {
+        key: string;
+        init(): State;
+        apply(state: State, value: {
+            reason: string;
+        }, event: import("../../models/index.js").JournalEvent<"ext">): State;
+        onFork?: "inherit" | "reset";
+    }): import("../../plugin.js").PluginProjection<State>;
+};

package/dist/plugins/compaction/segments.d.ts

@@ -0,0 +1,23 @@
+/**
+ * One run of a surface between direct developer inputs: entries `start` up to, not including,
+ * `end`. A span may lie anywhere inside one and never across one, since no replacement may contain
+ * direct developer input, a `developer` `input/message` with no `source`.
+ */
+export type SurfaceSegment = {
+    readonly start: number;
+    readonly end: number;
+    /** Whether it runs to the newest message: the only segment that keeps a tail. */
+    readonly last: boolean;
+};
+/**
+ * The segments of `entries` from index `from` on, oldest first: the runs between direct developer
+ * inputs, which are the boundaries and belong to no segment. An empty run is not a segment, so when
+ * the newest entry is itself direct developer input no segment is `last`. Entries before `from`,
+ * such as a pinned opening, belong to none.
+ *
+ * Generic over anything that says whether it is direct developer input, so a strategy can segment
+ * the surface entries themselves or its own snapshot of them.
+ */
+export declare function surfaceSegments(entries: readonly {
+    readonly directDeveloperInput: boolean;
+}[], from?: number): SurfaceSegment[];

package/dist/plugins/compaction/shared.d.ts

@@ -0,0 +1,14 @@
+import { type Context } from '@leuduan/cordis';
+import type { SurfacePrepareInput } from '../../loop/index.js';
+/**
+ * A reporter that says each condition once for as long as the strategy lives, one activation. `key`
+ * names the condition (its cause, the route, the latest replacement), so a step that finds it again
+ * stays quiet.
+ */
+export declare function onceReporter(ctx: Context): (key: string, message: string) => void;
+/** Whether the thread's agent has both recall tools granted now, so a stand-in or a footer may point at them. */
+export declare function recallGranted(ctx: Context, agentName: string): boolean;
+/** What the next request sends ahead of its messages: the recorded prompt and the tools the agent has now. */
+export declare function estimateThreadHead(ctx: Context, threadId: string, agentName: string): number;
+/** The input a step claims, which the request sends after the surface. */
+export declare const estimateClaimed: (prepare: SurfacePrepareInput) => number;

package/dist/plugins/compaction/summarize.d.ts

@@ -0,0 +1,13 @@
+import type { Plugin } from '@leuduan/cordis';
+import { type StrategyOptions, type SummarizeStrategyConfig } from './config.js';
+/**
+ * The `summarize` strategy on one thread, provided from the thread's own scope. What it measures
+ * from is the journal, its breaker included (unusable summaries are recorded, see
+ * `unusableSummaryRecord`); its rate-limited reports last one activation.
+ *
+ * A thread runs one strategy, and every way of mounting this one, a root mount whose selector
+ * covers the thread, an installation on it, or both, ends here: providing it is refused when the
+ * thread already has one, the later of the two, which fails the activation or the installation
+ * rather than letting two strategies replace the same surface.
+ */
+export declare const summarizeStrategy: Plugin.Object<StrategyOptions<SummarizeStrategyConfig>>;

package/dist/plugins/dateAndBranch.d.ts

@@ -0,0 +1,47 @@
+import type { Plugin } from '@leuduan/cordis';
+import { z } from 'zod';
+declare const DateAndBranchSchema: z.ZodObject<{
+    date: z.ZodString;
+    time_zone: z.ZodString;
+    head: z.ZodNullable<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"branch">;
+        name: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"detached">;
+        commit: z.ZodString;
+    }, z.core.$strict>], "kind">>;
+}, z.core.$strict>;
+/** What a thread is told: the day and, in a repository, its branch. */
+export type DateAndBranch = z.output<typeof DateAndBranchSchema>;
+declare const DateAndBranchConfigSchema: z.ZodObject<{
+    agents: z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodLiteral<"global">, z.ZodLiteral<"all">]>;
+}, z.core.$strict>;
+export type DateAndBranchConfig = z.input<typeof DateAndBranchConfigSchema>;
+/**
+ * Tells an agent the date and, when its `cwd` is in a git repository, the branch, as one notice
+ * that says both every time. `codexPreset` mounts it for the agents it equips; it is not handed
+ * down, since a sub-agent's task depends on neither.
+ *
+ * The facts are compared only on a turn's first model step, and told when they differ from the
+ * latest notice the model can still see: on a thread's first turn, on the first step of a turn after
+ * the day or the branch changed, and after a replacement took the notice off the surface. Never
+ * mid-turn, where a branch change is most likely the agent's own `git checkout`, which it knows.
+ *
+ * The date is the day in the process's time zone, which the notice names. The branch is read
+ * synchronously from the filesystem, since step listeners must not await: the repository is the
+ * nearest one at or above the `cwd` (`findRepository`), through a `.git` file for a linked worktree
+ * or a submodule, and its `HEAD` names the branch, or a commit for a detached head.
+ *
+ * Not a prompt section: the recorded prompt must not change while the thread lives, and both facts
+ * do. Mounted on the root it tells the agents `agents` selects on every thread; mounted through
+ * `thread.ctx`, that thread when it selects its agent.
+ */
+export declare const dateAndBranch: Plugin.Object<DateAndBranchConfig>;
+/** The day `now` falls on in the process's time zone, and the branch of the repository holding `cwd`. */
+export declare function currentDateAndBranch(cwd: string, now: Date): DateAndBranch;
+/**
+ * What a thread is told: the day and, in a repository, the branch, whole every time, with what
+ * differs from `told`, the notice the model can still see, noted as previously.
+ */
+export declare function renderDateAndBranch(facts: DateAndBranch, told: DateAndBranch | null): string;
+export {};

package/dist/plugins/dateAndBranch.js

@@ -0,0 +1 @@
+import{a,b,c}from"../chunks/O4PPOM5Z.js";import"../chunks/OVZFGILJ.js";import"../chunks/G6RXC3AL.js";import"../chunks/DRYAN665.js";import"../chunks/2OSESBIL.js";import"../chunks/YLNJXQ3Z.js";import"../chunks/DDANMY45.js";import"../chunks/37YOGDGY.js";import"../chunks/KESCTXGO.js";import"../chunks/TYTQRLTX.js";import"../chunks/D7E6EWIE.js";export{b as currentDateAndBranch,a as dateAndBranch,c as renderDateAndBranch};

package/dist/plugins/delegations/answers.d.ts

@@ -0,0 +1,39 @@
+import type { ToolResult } from '../../models/index.js';
+import type { TaskSettlement } from './record.js';
+import type { DelegationOutcome } from './request.js';
+/** The most a failed task's answer quotes of the child's latest text. */
+export declare const LATEST_TEXT_CHARS = 2000;
+/** `text`, or its last `LATEST_TEXT_CHARS` characters marked as cut. */
+export declare const quoteLatest: (text: string) => string;
+/** What a caller is told of a settled task. */
+export declare function outcomeOf(settlement: TaskSettlement): DelegationOutcome;
+/** Why a call's result ended its task: how the call was answered. */
+export declare function answeredBy(result: ToolResult): string;
+/** A task holding one of its origin root's slots, and why it still holds it. */
+export type SlotHolder = {
+    readonly taskId: string;
+    /** The thread doing it, or that will once the call that reserved the slot has opened the task. */
+    readonly childId: string;
+    readonly callerId: string;
+    readonly why: 'starting' | 'open' | 'waiting for an approval' | 'running a late turn' | 'being stopped';
+};
+/**
+ * Why a delegating call gets no slot, in words the model can act on: how many of its origin root's
+ * slots are in use, which of them the calling thread holds and how to free one, or that the capacity is
+ * held elsewhere.
+ */
+export declare function capRefusal(limit: number, holders: readonly SlotHolder[], callerId: string): string;
+/**
+ * Why a delegating call gets no slot while some thread's task state cannot be read: that thread
+ * may hold a slot, so how many are in use is unknown, and the cap fails closed.
+ */
+export declare function unknownOccupancy(unreadable: readonly {
+    childId: string;
+    error: string;
+}[]): string;
+/**
+ * Why a delegating call gets no slot when the thread at the top of the caller's origin tree cannot be
+ * found, a caller the catalog does not hold above it: whose slots it would take is unknown, and the
+ * cap fails closed.
+ */
+export declare const UNKNOWN_ROOT = "Cannot give an agent a task now: the conversation this thread belongs to cannot be found, so how many task slots are in use is unknown.";

package/dist/plugins/delegations/assignmentKey.d.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import type { OriginCause } from '../../models/index.js';
+import type { StartedOrigin } from './record.js';
+/**
+ * What delegations records of an owner's assignment in a task's origin: which assignment, and the
+ * participant generation it runs on. The origin's `key` is opaque to core; this is the one codec
+ * that writes and reads it, so a host that attributes a task decodes it with {@link assignmentKey}.
+ */
+declare const AssignmentKeySchema: z.ZodObject<{
+    assignment: z.ZodString;
+    generation: z.ZodNumber;
+}, z.core.$strict>;
+export type AssignmentKey = z.infer<typeof AssignmentKeySchema>;
+/** A cause that is not an assignment of delegations' shape: a call's, or one whose `key` does not decode. */
+export declare class AssignmentKeyError extends Error {
+    constructor(detail: string);
+}
+/** The assignment cause an owner's task records: the owner, and `key` as the codec writes it. */
+export declare function assignmentCause(owner: string, key: AssignmentKey): StartedOrigin['cause'];
+/** The key of an assignment cause, decoded; throws {@link AssignmentKeyError} for a call's cause or an invalid key. */
+export declare function assignmentKey(cause: OriginCause): AssignmentKey;
+export {};

package/dist/plugins/delegations/cleanup.d.ts

@@ -0,0 +1,161 @@
+import type { Context } from '@leuduan/cordis';
+import type { Seq } from '../../models/index.js';
+import { type TaskRef, type TaskState } from './record.js';
+/** Who stops a task, why, and the call that stopped it when a call did. */
+export type StopOptions = {
+    readonly by: 'caller' | 'host' | 'ancestor';
+    readonly reason: string;
+    readonly callSeq: Seq | null;
+};
+/** A stop's durable answer: how the task ended, and whether its stop's cleanup is still running. */
+export type StopOutcome = TaskRef & {
+    readonly state: Exclude<TaskState, 'open'>;
+    readonly cleanupPending: boolean;
+};
+/**
+ * The stop and its subtree cleanup, for the delegations service. A stop is a durable intent and a cleanup over
+ * the stopped thread's subtree: every thread under it with anything to quiet is signalled at once,
+ * then quieted deepest first by a cleanup of its own, one per thread id, which rejects that thread's
+ * unanswered confirmations and revokes its approved calls that have not run; `stop_cleaned` lands
+ * bottom-up. `resume` above it, or another stop of it, resumes a cleanup a crash left pending.
+ *
+ * The ordering it keeps: a stop's write is queued before `stop` returns, with nothing awaited, so a
+ * result listener orders it ahead of every write the caller enqueues after; that write reserves
+ * the walk over the subtree, so an opening queued behind it meets the walk (`blocksOpening`); and
+ * `drain` joins the stops and walks while the journal still takes their rows.
+ */
+export declare class StopCleanup {
+    /** Stops whose intent is on its way to the journal: the task constraint holds a task under one. */
+    private readonly stopping;
+    /** One cleanup per thread id, which every walker that reaches the thread joins. */
+    private readonly cleanups;
+    /**
+     * The walks over a stopped thread's subtree, by the stopped thread, each bound to the task whose
+     * stop started it: taken inside that stop's write, so no task opens on the thread from then until
+     * the walk ends, and a second stop of it joins. `walk` is `null` until the stop's write is durable.
+     */
+    private readonly walks;
+    /** Stopped tasks whose subtree a walk in this process found quiet: revalidated once, then trusted. */
+    private readonly validated;
+    private readonly ctx;
+    private readonly ready;
+    constructor(ctx: Context, 
+    /** Resolves once the task state can be served; a walk waits for it. */
+    ready: Promise<void>);
+    /**
+     * Stops task `taskId` of `childId`, decided inside one write on the child from its own rows: `null`
+     * when the child holds no such task, which a stop sent to a candidate child reads as "not this
+     * one". A settled task is left as it settled, and its outcome reported. A record the child's rows
+     * cannot be read for rejects. When the task is the child's latest and stopped, by this write or
+     * before, the write also takes the walk over the child's subtree for this task, so nothing opens on
+     * the child from then until the walk ends; once the decision is durable, a run of the child still
+     * serving the task is cancelled and the walk starts or is joined. Nobody awaits the walk.
+     */
+    stop(childId: string, taskId: string, options: StopOptions): Promise<StopOutcome | null>;
+    /** Resolves once the walk over `threadId`'s subtree, if one runs, has ended, however it ended. */
+    whenWalked(threadId: string): Promise<void>;
+    /** Whether a stop's walk or a thread cleanup holds `threadId`, so no task may open on it now. */
+    blocksOpening(threadId: string): boolean;
+    /** Stops on their way to the journal that end `task`, or a task of a thread above its child. */
+    stopsAffecting(task: TaskRef): Promise<StopOutcome | null>[];
+    /**
+     * Re-enters `stop` for every thread under `under` whose stop's cleanup is pending, which resumes
+     * it, and for every thread whose latest task is stopped and has not been validated in this
+     * process, which walks its subtree once: a cleanup acknowledged before it covered the subtree can
+     * have left anything under it, an approved call that has not run included, which the catalog
+     * shows only as work a run would find. One under another resumed here is covered by that one's
+     * walk. Returns each stop, which resolves once its decision is durable and its walk started.
+     */
+    resume(under: string): Promise<StopOutcome | null>[];
+    /** Waits for every stop on its way and every walk and thread cleanup running, for shutdown. */
+    drain(): Promise<void>;
+    /**
+     * The stop itself. A thread's own cleanup writes an ancestor's stop with `clean` false, since it
+     * is that cleanup; so the flag stays private rather than an option of `stop`: a stop from outside
+     * that took no walk would leave the stopped subtree unquieted.
+     */
+    private decide;
+    /**
+     * Starts the walk the stop's write took over the stopped thread's subtree, or joins it. Nobody
+     * awaits it; a failure is reported and leaves the stop's cleanup pending, for the next `resume`
+     * above it or the next `stop` of it to resume. A walk that ends lets openings on the thread
+     * through again; one that found the subtree quiet marks every stopped task in it validated.
+     */
+    private cleanUp;
+    /** Marks the stopped tasks at and under `threadId` validated: a walk just found them quiet. */
+    private markValidated;
+    /**
+     * Walks a stopped thread's subtree. Its workset is the stopped thread and every thread under it
+     * with anything to quiet (`toQuiet`), read from the catalog, whatever a thread between them
+     * acknowledged before, so a subtree an older cleanup certified only locally is checked again. Every
+     * thread in it is signalled at once, without waiting for any to go quiet; then each is quieted by
+     * its own cleanup, deepest first, so `stop_cleaned` lands bottom-up and the stopped thread's last.
+     * It is bound to `taskId`: if that is no longer the thread's latest task, it touches nothing. Its
+     * completion depends on each thread's cancel settling, which waits for the operation holding it.
+     */
+    private walk;
+    /** The stopped thread and every thread under it with anything to quiet, by depth, deepest first. */
+    private workset;
+    /**
+     * Whether a thread under a stopped one has anything to quiet: a task open or being cleaned up
+     * after, or one whose state cannot be read; something live on it (`holdsWork`); or work a run
+     * would find, `has_work` or `turn_open`, which is how an approved call that has not run shows.
+     */
+    private toQuiet;
+    /** Whether a run or an operation holds the thread, input waits on it, or a confirmation of it is unanswered. */
+    private holdsWork;
+    /** Whether a run serves the thread now, or an exclusive operation holds it. */
+    private busy;
+    /**
+     * Signals one thread of a stopped subtree, waiting for nothing: stops its task if open, as stopped
+     * by an ancestor, and begins its cancel.
+     */
+    private signal;
+    /**
+     * Whether a cleanup cancel would stop anything on the thread: a run or an operation holding it, a
+     * pending run, or queued input. A cancel of a thread with none of these would only add a row, on
+     * every walk, which a restart repeats for every stopped task.
+     */
+    private cancellable;
+    /** A thread's own cleanup: the one running, which every walker that reaches the thread joins, or a new one. */
+    private quietThread;
+    /**
+     * Quiets one thread of a stopped subtree, owning every write on it. Stops its task if still open,
+     * as stopped by an ancestor, once a stop of it already on its way has landed; cancels it when there
+     * is anything to stop (`cancellable`), which aborts the run or operation holding it, a late turn
+     * after a settle included, clears its queue and settles its pending run, and waits for that; then
+     * rejects its unanswered confirmations and
+     * takes back its approved calls without a result, so no later run runs one; then stops the
+     * commands this process runs for it and every thread under it, and waits for them to end. The
+     * thread and its subtree are loaded and held throughout, since only a loaded thread's
+     * confirmations can be read, and a loaded thread's command evidence needs no commands plugin.
+     * Then acknowledges, or, if something came back meanwhile, a run admitted since or input queued
+     * after the clear, does it again. A command whose end is not established keeps it from going
+     * quiet however often it tries: the failure names it.
+     */
+    private quiet;
+    /** Stops the loaded thread's latest task if it is open, as stopped by an ancestor, once any stop of it on its way has landed. */
+    private stopOwnTask;
+    /** Stops the commands this process runs for `threadId` and every thread under it, and waits for them to end. */
+    private stopCommands;
+    /**
+     * Rejects the loaded thread's unanswered confirmations and takes back its approved calls that have
+     * no result, each as one write. A write that meets an answer given meanwhile, which a person can
+     * give at any time, records nothing; what is pending is read again and tried once more.
+     */
+    private settleConfirmations;
+    /**
+     * Writes `stop_cleaned` for the thread's stops not yet acknowledged, decided inside one write, once
+     * the thread is quiet and so is everything under it; `false` when not. Quiet: no run and no
+     * operation holds the thread, its queue is empty, and none of its confirmations is unanswered or
+     * approved without a result. Under it: no task open or still being cleaned up after, none
+     * unreadable, and nothing running, held, queued or waiting for an answer. On it and under it: every
+     * command known to have ended (`commandWork`), so neither a stop that failed nor a termination no
+     * process saw is acknowledged as quiet. Whether a thread beneath
+     * has an approved call without a result is not in the catalog: its own cleanup, which ran first,
+     * took it back, and nothing can approve one since.
+     */
+    private acknowledge;
+    /** Whether every thread under `threadId` is quiet, as the catalog and this process tell it. */
+    private quietUnder;
+}

package/dist/plugins/delegations/constraint.d.ts

@@ -0,0 +1,76 @@
+import type { TaskReading } from './record.js';
+/**
+ * What the task predicate reads of one task, every field a synchronous read the service already
+ * keeps: the child's catalog entry, the stops above it and on their way, whether its run still
+ * drains input accepted before it settled, and what authorizes it, by its origin.
+ */
+export type TaskView = {
+    readonly taskId: string;
+    /** The child's latest task, from its catalog entry. */
+    readonly reading: TaskReading;
+    /** Why a stop above the child keeps anything new from it, or `null`. */
+    readonly stoppedAbove: {
+        readonly kind: 'stopping' | 'unreadable';
+        readonly why: string;
+    } | null;
+    /** Whether a stop of the task, or of a thread above its child, is on its way to the journal. */
+    readonly stopOnItsWay: boolean;
+    /** Whether an outstanding stop obligation names the child, or a thread above it. */
+    readonly obligated: boolean;
+    /** Whether the task settled while the run that served it still drains input accepted before. */
+    readonly draining: boolean;
+    /** What authorizes the task: its opening call, or its owner's assignment. */
+    readonly authority: CallAuthority | AssignmentAuthority;
+};
+/** A call-opened task's authority: where its opening call stands. */
+export type CallAuthority = {
+    readonly kind: 'call';
+    readonly background: boolean;
+    /**
+     * The opening call's result: its `receipt`; `answered` by anything else, which ends the task;
+     * `none` yet; `unknown` while the caller's rows have not been indexed in this process.
+     */
+    readonly opening: 'receipt' | 'answered' | 'none' | 'unknown';
+    /**
+     * Whether the opening call still runs in this process, without a result: a background task's
+     * authority until its receipt is durable, a blocking task's until its wait is declared.
+     */
+    readonly callRunsHere: boolean;
+    /** Whether the caller's catalog entry shows the opening call suspended on its wait: a blocking task's authority. */
+    readonly callSuspended: boolean;
+};
+/**
+ * An owner's task's authority: the verdict of its live registered owner on the assignment its
+ * `started` row records, or why there is none (no owner registered under its name).
+ */
+export type AssignmentAuthority = {
+    readonly kind: 'assignment';
+    readonly verdict: {
+        readonly kind: 'allow';
+    } | {
+        readonly kind: 'hold';
+        readonly reason: string;
+    };
+};
+/**
+ * Whether a task may be run now: `allow`; `hold` with why, while something may still change; or
+ * `obsolete` with why, when the task has ended and nothing of its request remains to drain.
+ */
+export type TaskVerdict = {
+    readonly kind: 'allow';
+} | {
+    readonly kind: 'hold';
+    readonly reason: string;
+} | {
+    readonly kind: 'obsolete';
+    readonly reason: string;
+};
+/**
+ * The task predicate, pure: the task is its child's latest and open, or settled with its run still
+ * draining; no stop is recorded above it, on its way, or owed by an obligation; and its authority
+ * holds. A call's: while the task is open, its opening call was not answered by anything but its
+ * receipt, a background task's receipt is durable or its call runs here, and its state is readable;
+ * and a blocking task's call, which the child serves, runs here or waits for it. An owner's
+ * assignment's: its live owner allows it, open or draining; no call, receipt or wait is read.
+ */
+export declare function evaluateTask(view: TaskView): TaskVerdict;