@leuduan/lagent 0.0.0-stage → 0.1.2

package/dist/plugins/verify/index.d.ts

@@ -0,0 +1,75 @@
+import type { Plugin } from '@leuduan/cordis';
+import { z } from 'zod';
+export declare const VerifyConfigSchema: z.ZodObject<{
+    command: z.ZodString;
+    cwd: z.ZodString;
+}, z.core.$strict>;
+export type VerifyConfig = z.input<typeof VerifyConfigSchema>;
+/**
+ * A gate that holds a thread's answer while it has an unverified change: an `edit_files`
+ * result, a `run_command` other than the verification, or a background command's start or end,
+ * with no passing verification since. The verification is a `run_command` whose command text and
+ * working directory are the configured ones, run by the model like any other command, through the
+ * conversation's confirmation; the gate runs nothing itself.
+ *
+ * A verification counts only if its allowed attempt — the `tool/authorization` row written just
+ * before it starts — comes after the result row of the last other change, and its result says it
+ * ran to completion with exit code 0. Commands and edits are exclusive, so within one response a
+ * verification starts after the changes before it settled; the attempt still decides, as results
+ * land in model order and a change from elsewhere — a background command, a tool by another plugin
+ * under the same name — need not be. Until its outcome is known it is a possible change itself, since a
+ * formatter in the check rewrites files: one that passes proves its own changes and everything
+ * settled before it started; one that fails, is cancelled, times out, is interrupted or leaves
+ * processes behind leaves verification outstanding. A background command that ends after it
+ * started makes it stale; one still running at the stop is not held against the gate. A call that
+ * was never allowed to run, denied or rejected, changed nothing and is not counted.
+ *
+ * With an unverified change it sends the model back to run the command, at most
+ * {@link VERIFY_REMINDERS} times since the last change other than a verification run, or since the
+ * person last wrote, and then rejects the answer, so the turn ends `rejected`. When policy denied
+ * the latest verification attempt since the person last wrote, a read-only conversation say, it
+ * rejects at once, wherever that attempt's result landed among the changes' results.
+ *
+ * The {@link verify} service is the judge: the preset puts its verification in force on the thread
+ * it serves for as long as it is mounted (`ctx.verify.gate`), and tells the model of it. A
+ * requirement recorded for the assignment the thread serves on the same verification is judged
+ * with the gate, once: a barrier at its arming, with or without a change, counting its reminders
+ * and denials from it.
+ *
+ * So that the model need not learn the command from an objection, the thread is also told it up
+ * front, as a notice at the next model step whenever no notice it can still see says the same: on
+ * its first step, and again after a replacement took it away. The notice is neither a change nor a
+ * reminder.
+ *
+ * A pure fold over each thread's rows, not the current turn's, so a crash or an approval pause
+ * cannot hide an earlier turn's unverified work, and judging an answer again after a crash repeats
+ * nothing. The fold records what happened whatever the verification is, so it is one for every
+ * gate, and each verification is judged from it at the stop.
+ *
+ * The thread's delegated work is its own: a change made by any thread its calls started, at any
+ * depth, counts as the thread's, at its row, so a verification must have started after it. Every
+ * command a child ran counts, a passing run of the same verification included: a check may rewrite
+ * files, and a child's proof is not its caller's. Rows are numbered in one journal order across threads, so the two
+ * compare directly; a child's change also starts the count of reminders over. A child that is not
+ * loaded is read from the catalog, so this holds across a restart, and a child whose changes cannot
+ * be read rejects the answer at once rather than pass it. A thread an owner assigned, such as a
+ * workflow's isolated participant, is that owner's work, not its caller's. The preset is not handed
+ * down: a child is not gated itself.
+ *
+ * Installed per thread, with `cwd` resolved against the thread's cwd by the host; or mounted
+ * (`mountPreset`) from the setup of a preset placed on a thread, which gates that thread. Refuses
+ * to mount without the {@link verify} service.
+ */
+export declare const verifyPreset: import("../../services/preset.js").Preset<z.ZodObject<{
+    command: z.ZodString;
+    cwd: z.ZodString;
+}, z.core.$strict>>;
+/**
+ * The `ctx.verify` service ({@link VerifyService}), the one judge of verification on every thread:
+ * the gates {@link verifyPreset} mounts, and the requirements an owner records for an assignment
+ * with `owed(...)`, whose threads require {@link VERIFY_OWNER}. Root-only, mounted once by the
+ * application, before anything mounts the preset.
+ */
+export declare const verify: Plugin.Object<undefined>;
+export { VERIFY_PRESET, VERIFY_REMINDERS } from './facts.js';
+export { VERIFY_OWNER, type OwedVerification, type VerifyService } from './service.js';

package/dist/plugins/verify/index.js

@@ -0,0 +1 @@
+import{o as T}from"../../chunks/EGZI4XQX.js";import"../../chunks/UD3VJER6.js";import"../../chunks/SGGMBSBA.js";import"../../chunks/3QCW4WDJ.js";import"../../chunks/C5LYCXJG.js";import"../../chunks/J5S4URAW.js";import{a as N}from"../../chunks/G74AGRAJ.js";import{a as C}from"../../chunks/SL2YLB2F.js";import"../../chunks/JPZFKSWT.js";import"../../chunks/RK3VP2Q4.js";import"../../chunks/74HKUGRR.js";import{a as V}from"../../chunks/QMMLQJBS.js";import"../../chunks/YIR5MYGU.js";import{a as F}from"../../chunks/L3N4FIEN.js";import"../../chunks/NAOUTU7A.js";import"../../chunks/UKXMCHHT.js";import"../../chunks/GQGNVSKB.js";import"../../chunks/DXFXAYDN.js";import{b as g,e as M}from"../../chunks/DRYAN665.js";import{d as O}from"../../chunks/2OSESBIL.js";import{o as w}from"../../chunks/YLNJXQ3Z.js";import"../../chunks/DDANMY45.js";import{h as S}from"../../chunks/37YOGDGY.js";import{a as R}from"../../chunks/KESCTXGO.js";import"../../chunks/TYTQRLTX.js";import"../../chunks/D7E6EWIE.js";import{isAbsolute as se,resolve as oe}from"node:path";import{z as E}from"zod";import{isAbsolute as H,resolve as y}from"node:path";import{z as d}from"zod";var p="verify",Y=2,Q="edit_files",X="run_command",q=d.strictObject({command:d.string(),cwd:d.string()}),z=g({plugin:"lagent:verify",kind:"notice",version:1,schema:q}),J=g({plugin:"lagent:verify",kind:"reminder",version:1,schema:q}),k=g({plugin:"lagent:verify",kind:"rejected",version:1,schema:d.strictObject({...q.shape,cause:d.enum(["denied","unverified"])})}),m=(n,e)=>JSON.stringify([n,e]);function Z(n,e){let{metadata:t}=n;return!n.is_error&&t.exit_code===0&&t.timed_out===!1&&t.aborted===!1&&t.stop_failed===!1&&typeof t.cwd=="string"&&y(t.cwd)===e}var P=(n,e)=>{let t=n.commands.get(e);return t===void 0&&(t={resultAt:null,failedAt:null,provenAt:null,decision:null},n.commands.set(e,t)),t},A=(n,e)=>{for(let t of[...n.reminders.keys()])t!==e&&n.reminders.delete(t)},h=S({key:"lagent:verify:facts",init:()=>({threadCwd:null,calls:new Map,changedAt:null,commands:new Map,personAt:null,reminders:new Map}),apply(n,e){switch(e.type){case"thread/spawned":n.threadCwd=y(e.data.environment.cwd);break;case"assistant/message":for(let t of e.data.response.message.tool_calls)t.arguments===null?n.calls.delete(t.call_id):t.name===Q?n.calls.set(t.call_id,{run:null,allowedAt:null}):t.name===X?n.calls.set(t.call_id,{run:ee(n,t.arguments),allowedAt:null}):n.calls.delete(t.call_id);break;case"tool/authorization":{let t=n.calls.get(e.data.call_id);if(t===void 0)break;e.data.decision==="allow"&&(t.allowedAt=e.seq),t.run!==null&&(P(n,t.run.key).decision={seq:e.seq,denied:e.data.decision==="deny"});break}case"tool/result":{let{result:t}=e.data,r=n.calls.get(t.call_id);if(n.calls.delete(t.call_id),r===void 0||r.allowedAt===null)break;if(r.run===null){n.changedAt=e.seq,A(n,null);break}let i=P(n,r.run.key);i.resultAt=e.seq,Z(t,r.run.cwd)?i.provenAt=Math.max(i.provenAt??0,r.allowedAt):i.failedAt=e.seq,A(n,r.run.key);break}case"ext":N.read(e)!==void 0&&(n.changedAt=e.seq,A(n,null));break;case"input/message":if(e.data.source===null)n.personAt=e.seq,n.reminders.clear();else{let t=J.readContribution(e);if(t!==void 0){let r=m(t.command,t.cwd);n.reminders.set(r,[...n.reminders.get(r)??[],e.seq])}}break;default:break}return n}});function ee(n,e){let t=e.command;if(typeof t!="string"||n.threadCwd===null)return{key:m(JSON.stringify(t??null),null),cwd:null};let r=e.workdir,i=typeof r=="string"&&r!==""?y(n.threadCwd,r):n.threadCwd;return{key:m(t,i),cwd:i}}var f=(n,e)=>n===null?e:e===null?n:Math.max(n,e);function ne(n){let e=n.changedAt;for(let t of n.commands.values())e=f(e,t.resultAt);return e}var j=C({key:"verify",version:1,schema:d.strictObject({changed_at:d.number().int().positive().nullable()}),applies:()=>!0,compute:(n,e)=>({changed_at:ne(n.state(h,e))})});function D(n,e){let t=new Set([e]),r=null;for(let i of n.origins.subtree(e,{self:!0})){let{origin:s,thread_id:o}=i;if(s===null||s.cause.kind==="assignment"||!t.has(s.caller_thread_id))continue;t.add(o);let a=j.read(n,o);if(a.status!=="available")return{unreadable:`agent ${o}: ${a.status==="unavailable"?a.reason:"its changes are not recorded"}`};r=f(r,a.value.changed_at)}return{at:r}}function _(n,e,t,r){let i=m(e.command,e.cwd),s=r;for(let[u,$]of n.commands)s=f(s,u===i?$.failedAt:$.resultAt);s=f(s,n.changedAt);let o=n.commands.get(i),a=o?.decision??null,c=f(n.personAt,t),l=f(t,r);return{mutatedAt:s,provenAt:o?.provenAt??null,denied:a!==null&&a.denied&&(c===null||a.seq>c),reminders:(n.reminders.get(i)??[]).filter(u=>l===null||u>l).length}}var te=d.strictObject({owner:d.string().min(1),assignment:d.string().min(1),generation:d.number().int().nonnegative(),input:d.string().min(1),command:d.string().trim().min(1),cwd:d.string().refine(H,"An absolute path")}),x=g({plugin:"lagent:verify",kind:"requirement",version:1,schema:te});function I(n){let e=x.parse(n);return{...e,cwd:y(e.cwd)}}var K=n=>JSON.stringify([n.owner,n.assignment,n.generation]),U=x.projection({key:"requirements",init:()=>new Map,onFork:"reset",apply(n,e,t){let r=K(e);return n.has(r)||n.set(r,{value:e,seq:t.seq}),n}});function W(n,e,t,r){let i=t?void 0:n.state(U,e).get(K(r));return i===void 0?[x.entry(r,{threadId:e})]:JSON.stringify(i.value)===JSON.stringify(r)?[]:{refuse:{message:`Verification for assignment ${r.assignment} is already owed on ${e}, differently`}}}function B(n,e){let t=n.state(U,e);if(t.size===0)return null;let{inputs:r}=n.state(w,e),i=T(n,e),s=null;for(let{value:o,seq:a}of t.values()){let c=r.get(o.input)?.claimedAt??null;if(c===null)continue;let l=Math.max(a,c);i!==null&&i>l||(s===null||s.at<l)&&(s={verification:{command:o.command,cwd:o.cwd},at:l})}return s}function L(n,e,t,r){let i=`\`${e.command}\` (in ${e.cwd})`;if("unreadable"in r)return k.rejection(`The changes of the work this conversation delegated cannot be read (${r.unreadable}), so ${i} cannot be shown to cover them.`,{...e,cause:"unverified"});let{mutatedAt:s,provenAt:o,denied:a,reminders:c}=_(n,e,t,r.at),l=f(s,t);if(l===null||o!==null&&o>l)return;let u=t!==null&&t===l;return a?k.rejection(`Verification is not allowed in this mode: ${i} was denied, so ${u?"the assignment is":"the changes since it last passed are"} unverified.`,{...e,cause:"denied"}):c>=Y?k.rejection(`${i} has not passed since ${u?"the assignment began":"the last change"}, after ${c} reminder${c===1?"":"s"} to run it.`,{...e,cause:"unverified"}):{decision:"continue",message:J.contribution({content:`Before finishing, run ${i} and fix what fails.`},e)}}import{resolve as G}from"node:path";import{Service as re}from"@leuduan/cordis";function ie(n){if(n.kind==="send")return null;if(n.kind==="create"){let{origin:i,spec:s}=n.opening;return{origin:i,requires:s.requires,installations:s.installations}}let{origin:e,requires:t,inherits:r}=n.opening;return{origin:e,requires:t,installations:r.installations}}var v="lagent:verify",b=class extends re{static inject=["threads","journal"];gates=new Map;constructor(e){super(e,"verify"),e.effect(()=>e.threads.registerOwner({owner:v}).dispose),e.effect(()=>e.journal.register(h)),j.register(e),e.on("lagent/turn/stop",t=>this.judge(t))}gate(e,t){let r=Symbol("verify gate"),i=this.gates.get(e);return i===void 0&&this.gates.set(e,i=new Map),i.set(r,{command:t.command,cwd:G(t.cwd)}),()=>{i.delete(r),i.size===0&&this.gates.get(e)===i&&this.gates.delete(e)}}owed(e){let{inputId:t,...r}=e,i=I({...r,input:t}),s=m(i.command,i.cwd);return o=>{let{threadId:a}=o,c=ie(o);if(!this.required(a,c))return{refuse:{message:`Thread ${a} owes verification, so it must require ${v}`}};let l=this.inPlace(a,c).find(u=>m(u.command,u.cwd)!==s);return l!==void 0?{refuse:{message:`Thread ${a} verifies with \`${l.command}\` (in ${l.cwd}), not the \`${i.command}\` (in ${i.cwd}) this assignment pins`}}:W(this.ctx.journal,a,c!==null,i)}}judge({threadId:e,observe:t}){t(()=>this.observed(e));let{judged:r,delegated:i}=this.reading(e);if(r.size===0)return;let s=this.ctx.journal.state(h,e),o;for(let{verification:a,armedAt:c}of r.values()){let l=L(s,a,c,i);if(l?.decision==="reject")return l;o??=l}return o}observed(e){let{judged:t,delegated:r}=this.reading(e),i=this.ctx.journal.state(h,e);return JSON.stringify([[...t].map(([s,{verification:o,armedAt:a}])=>[s,a,"unreadable"in r?null:_(i,o,a,r.at)]),r])}reading(e){let t=new Map,r=B(this.ctx.journal,e);for(let i of this.gates.get(e)?.values()??[])t.set(m(i.command,i.cwd),{verification:i,armedAt:null});return r!==null&&t.set(m(r.verification.command,r.verification.cwd),{verification:r.verification,armedAt:r.at}),{judged:t,delegated:t.size===0?{at:null}:D(this.ctx.journal,e)}}inPlace(e,t){return[...(t===null?[...this.ctx.journal.state(w,e).installations.current.values()].map(({presetId:s,config:o})=>({presetId:s,config:o})):t.installations.map(({preset_id:s,config:o})=>({presetId:s,config:o}))).flatMap(({presetId:s,config:o})=>{if(s!==p)return[];let{command:a,cwd:c}=o;return[{command:a,cwd:G(c)}]}),...this.gates.get(e)?.values()??[]]}required(e,t){let{owners:r}=this.ctx.journal.origins.requiredOwners(t??e);return r.some(({owner:i})=>i===v)}};var ae=E.strictObject({command:E.string().trim().min(1),cwd:E.string().refine(se,"An absolute path: resolve it against the thread's cwd before installing")}),Oe=F({id:p,placement:"thread",schema:ae,inject:["journal","verify"],setup(n,e,t){let r=V(n,"verify","verifyPreset"),i={command:e.command,cwd:oe(e.cwd)},s=`\`${i.command}\` (in ${i.cwd})`;M(n,{event:z,rank:1,current:()=>i,render:()=>R("verification",`This conversation verifies its work with ${s}: after changing files, run it and fix what fails before you finish.`)}),n.effect(()=>r.gate(t.thread.id,i))}}),Fe={name:"lagent:verify",inject:["threads","journal"],async apply(n){O(n,"verify"),await n.plugin(b)}};export{v as VERIFY_OWNER,p as VERIFY_PRESET,Y as VERIFY_REMINDERS,ae as VerifyConfigSchema,Fe as verify,Oe as verifyPreset};

package/dist/plugins/verify/service.d.ts

@@ -0,0 +1,90 @@
+import { Service, type Context } from '@leuduan/cordis';
+import { type WriteRows } from '../../loop/index.js';
+import { type Verification } from './facts.js';
+declare module '@leuduan/cordis' {
+    interface Context {
+        /** Verification: the gates and assignment requirements of every thread (optional plugin). */
+        verify: VerifyService;
+    }
+}
+/**
+ * The constraint owner a thread owing verification requires (`requires` in its creation, its own
+ * or a thread's above it by origin): while the `verify` service is not mounted, the thread is held
+ * `missing`, and a judgment made without this registration does not end its turn (core's fence on
+ * required registrations).
+ */
+export declare const VERIFY_OWNER = "lagent:verify";
+/** The verification one assignment owes, as its owner records it with {@link VerifyService.owed}. */
+export type OwedVerification = {
+    /** The owner that schedules the assignment, as an assignment origin names it. */
+    readonly owner: string;
+    /** The assignment's id. */
+    readonly assignment: string;
+    /** The participant generation serving it. */
+    readonly generation: number;
+    /** The input whose claim activates the assignment, which arms the requirement. */
+    readonly inputId: string;
+    /** The pinned verification: the command text `run_command` must be given. */
+    readonly command: string;
+    /** The absolute directory it must run in. */
+    readonly cwd: string;
+};
+/**
+ * Verification, the one judge of every thread's answers on it. Two things put a verification in
+ * force on a thread: a gate the verify preset mounts there ({@link gate}), which demands a pass
+ * after the last change; and the requirement an owner recorded for the assignment the thread
+ * serves ({@link owed}), armed when the assignment's input is claimed, which demands a pass after
+ * both its arming and the last change, whether or not the thread changed anything. A gate and a
+ * requirement on one verification are judged once, together; a later requirement supersedes an
+ * earlier one, as does a delegation task opened on the thread after it armed, and replaying one
+ * renews no reminder or denial.
+ *
+ * Each verification covers the thread's delegated work too: a change any thread its calls started
+ * made, at any depth, its passing runs of the same verification included, needs a pass after it, read from that thread's facts when it is loaded and
+ * otherwise from the catalog, which the service contributes every thread's changes to.
+ *
+ * It registers {@link VERIFY_OWNER}: a thread owing verification requires it, so while the service
+ * is not mounted the thread is held rather than its answer accepted unchecked.
+ */
+export declare class VerifyService extends Service {
+    static inject: string[];
+    /** The gates mounted now, by thread: each mount's verification. */
+    private readonly gates;
+    constructor(ctx: Context);
+    /**
+     * Puts `verification` in force on `threadId` until the returned function is called: what the
+     * verify preset's setup does for the thread it serves, for as long as it is mounted.
+     */
+    gate(threadId: string, verification: Verification): () => void;
+    /**
+     * The rows recording `requirement` on the thread a write schedules its assignment on, for that
+     * write's `rows`. Decided inside the write, refused: unless the thread requires
+     * {@link VERIFY_OWNER}, by its own creation or a thread's above it by origin, so its run is held
+     * while this service is missing; when a verify preset installed on the thread, or a gate mounted
+     * there now, names another verification, which the two would demand in turn and never both pass;
+     * and for one recorded under the same assignment and generation differently. None for one
+     * recorded already exactly so: a replay renews nothing.
+     */
+    owed(requirement: OwedVerification): WriteRows;
+    /**
+     * The thread's say on its answer: every verification in force on it, each judged once, a gate's
+     * on the same verification as the requirement judged with the requirement's arming. Any rejection
+     * wins, then the first continuation. It declares what the say rests on (`observed`) whichever it
+     * is, an abstention too, so a change while another check awaited sends the answer to be judged again.
+     */
+    private judge;
+    /**
+     * What a verdict on the thread rests on, as one token: each verification in force with its arming
+     * and what its judgment reads of the thread's facts, and the last change of its delegated work.
+     */
+    private observed;
+    /**
+     * The verifications in force on the thread, by {@link commandKey}, each with the moment its
+     * requirement armed (`null` for a gate alone), and its delegated work's last change.
+     */
+    private reading;
+    /** The verifications the thread is configured with: its installed verify presets, and the gates mounted on it now. */
+    private inPlace;
+    /** Whether the thread, or one above it by origin, requires {@link VERIFY_OWNER}; its opening when the write opens it. */
+    private required;
+}

package/dist/plugins/workflows/assignment.d.ts

@@ -0,0 +1,16 @@
+import type { Context } from '@leuduan/cordis';
+import { type Governance } from './policy.js';
+/**
+ * Presents each instance to the threads working it at the model steps they take (§6 of the design),
+ * at rank 2, after the rank-1 notices of what is in force (sandbox, verification, permission mode):
+ * to its root, its assignment, with everything needed to work it, or the decision, block or cleanup
+ * it waits on; to an isolated participant's child, its own assignment. Contributed only when no
+ * notice the thread can still see says the same: at the step that claims the assignment's activation
+ * input, and again after compaction or a replacement took it away; a contribution never wakes the
+ * thread. An instance that ended is told so to its root once, and only while an earlier presentation
+ * that restricted it is still visible. Notice visibility decides what is told, never authority,
+ * which the activation's claim alone gives.
+ */
+export declare function presentAssignments(ctx: Context, governance: Governance): void;
+/** A host decision's verdict as the model is told it: what was decided, never who decided it. */
+export declare function verdictOf(verdict: 'approve' | 'revise'): string;

package/dist/plugins/workflows/bindings.d.ts

@@ -0,0 +1,95 @@
+import type { ReadonlyJsonValue } from '../../util/json.js';
+import type { CanonicalDefinition } from './definition.js';
+import type { InstanceState, ResultDecision } from './fold.js';
+import type { Acquired } from './providers.js';
+import type { ReadonlyState } from '../../util/foldState.js';
+import { type Entered, type InstanceRowInput, type TransitionCause } from './record.js';
+/**
+ * The results no longer current: each retired by its own step's re-entry (and `retiring`, retired
+ * by an entry being planned), and transitively each result whose attempt bound a stale one as a
+ * `current` input. Historical bindings need no freshness. A result binds only results accepted
+ * before it, so one pass in acceptance order settles every chain.
+ */
+export declare const staleResults: (state: ReadonlyState<InstanceState>, retiring?: ReadonlySet<string>) => Set<string>;
+/**
+ * The results that were no longer current when row `seq` was recorded: retired by the entries
+ * recorded up to it, and what was bound to those. What went stale after it is the difference from
+ * {@link staleResults}.
+ */
+export declare function staleAsOf(state: ReadonlyState<InstanceState>, seq: number): Set<string>;
+/** A recorded decision as the routing envelope carries it. */
+export declare function resultDecision(state: ReadonlyState<InstanceState>, decision: string | null): ResultDecision | null;
+/**
+ * The value input `name` of an attempt was bound to, as recorded: immutable results make a result's
+ * citation exact, and evidence is read from the entry that recorded it, never acquired again.
+ */
+export declare function boundValue(state: ReadonlyState<InstanceState>, entered: ReadonlyState<Entered>, name: string): ReadonlyJsonValue;
+/**
+ * A decision being planned in the same write as the entry: what it records on `result` (`null` for
+ * a recovery's), and the persistent participants it restarts, whose new generation the entry pins.
+ */
+export type Deciding = {
+    readonly result: string | null;
+    readonly id: string;
+    readonly decision: ResultDecision;
+    readonly restart: readonly string[];
+};
+/** An entry refused: the input that could not be bound, and why. Nothing is retired or consumed. */
+export type EntryRefusal = {
+    readonly refused: string;
+};
+/** The evidence an entry needs before it can be planned: what to acquire, for exactly this attempt. */
+export type EvidenceNeeds = {
+    readonly transition: string;
+    readonly attempt: string;
+    readonly step: string;
+    readonly inputs: readonly {
+        readonly input: string;
+        readonly provider: string;
+    }[];
+};
+/** Evidence acquired outside the write, for one transition into one attempt, by input. */
+export type EntryEvidence = {
+    readonly transition: string;
+    readonly attempt: string;
+    readonly inputs: ReadonlyMap<string, Acquired>;
+};
+/**
+ * Plans entering `step`, atomically: re-entry retires the step's current result, then every input
+ * binds against what remains, then the attempt opens with its assignments. The plan is one
+ * `entered` row, so its write retires, binds, opens and consumes the step's allowance together, or,
+ * refused, does none of it. Each assignment records where it runs and what activates it: the
+ * conversation participant's runs on the root, activated by `activation`, the host's first input at
+ * opening and the transition's scheduling input after; an isolated participant's runs as the task
+ * of its assignment on the child of its generation (the one a restart being decided gives it), its
+ * task's input activating it.
+ *
+ * - A `current` binding needs the producer's current result, approved if the step is gated; an
+ *   optional one binds `null` only when the producer has accepted nothing (for that participant).
+ *   A stale or unapproved result is not absence. The step's own current result is always retired
+ *   by its entry, so an optional current self-binding binds `null`.
+ * - A `historical` binding takes the producer's latest accepted result, retired or stale included,
+ *   such as the one this entry retires; optional when there is none yet.
+ * - An isolated participant the opening did not pin (one the definition registered now added, or
+ *   moved off the conversation) cannot run: the entry is refused.
+ * - An evidence binding takes what its provider acquired for this very attempt (`evidence`), with
+ *   the provider's citation, the value recorded in the row; once every other input binds, what is
+ *   not acquired yet is returned as `needs`. Absence binds `null` when the binding is optional and
+ *   refuses the entry otherwise; an unavailable answer refuses it either way.
+ */
+export declare function planEntry(state: ReadonlyState<InstanceState>, definition: CanonicalDefinition, request: {
+    readonly instance: string;
+    readonly step: string;
+    readonly cause: TransitionCause;
+    readonly activation: string;
+    /** The decision this entry's write records, which bindings already see. */
+    readonly deciding?: Deciding;
+    /** Evidence acquired for the entry; used only when it is for this very transition and attempt. */
+    readonly evidence?: EntryEvidence;
+}): {
+    readonly row: Extract<InstanceRowInput, {
+        op: 'entered';
+    }>;
+} | EntryRefusal | {
+    readonly needs: EvidenceNeeds;
+};

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

@@ -0,0 +1,38 @@
+import type { Context } from '@leuduan/cordis';
+import type { AppendEntry } from '../../journal/index.js';
+import { type InstanceState } from './fold.js';
+import type { InstanceRowInput } from './record.js';
+import type { Barrier } from './routing.js';
+import type { ReadonlyState } from '../../util/foldState.js';
+/**
+ * The one evidence barrier an instance's cancellation, its pending recovery's decision, the restarts
+ * that decision names and the successor it opens all wait on (decision 18 of the slice-2 plan). The
+ * lifetime owners answer for their own work, from durable evidence ({@link workUnder}): commands for
+ * whether each command ended, delegations for each task's settlement, cleanup and stop
+ * acknowledgement, and for whether a conversation can take another task (`continuation`). This
+ * combines them over what the instance owns:
+ *
+ * - an admitted cancellation: everything under the root;
+ * - a pending recovery: its attempt's isolated participants' children and everything under them,
+ *   with the root's stops of them; on a mixed step, whose root assignment it superseded too, also
+ *   the root's own work: its commands, the threads it started and the run that was under way at
+ *   the recovery's boundary; and each persistent participant's conversation, which is
+ *   draining while delegations says to wait, unknown while it cannot be asked (delegations not
+ *   mounted, the child not loaded), unresolved while its task state cannot be read, and
+ *   uncontinuable, so a decision must restart it, once delegations refuses it more work.
+ *
+ * Either way, a participant's start still in flight (`starting`, its assignments) is work still
+ * ending: it may yet open a task, or find its assignment superseded and open none. Anything else
+ * waits on nothing. Read synchronously, inside a write or while the threads it reads are held loaded.
+ */
+export declare function barrierOf(ctx: Context, state: ReadonlyState<InstanceState>, starting: readonly string[]): Barrier;
+/**
+ * The stop obligation, for the root write that records `row`, over the tasks a recovery it opens
+ * leaves running: when one of its observations ends a task without acceptance, the attempt recovers,
+ * and every other open isolated assignment's task that delegations' records show open or still
+ * draining is stopped for good, so nothing of the attempt keeps working while a person decides.
+ * Delegations carries it out from that write, or at its next repair. None otherwise.
+ */
+export declare function siblingStops(ctx: Context, state: ReadonlyState<InstanceState>, row: Extract<InstanceRowInput, {
+    op: 'observed';
+}>): AppendEntry<'ext'>[];

package/dist/plugins/workflows/definition.d.ts

@@ -0,0 +1,184 @@
+import { z } from 'zod';
+import { type ThinkingEffort } from '../../llm/index.js';
+import { type ReadonlyJsonValue } from '../../util/json.js';
+import type { ResultDecision } from './fold.js';
+/** The edge target that completes an instance. */
+export declare const COMPLETE = "$complete";
+/** A value an edge predicate compares a field with. */
+export type JsonScalar = string | number | boolean | null;
+/** An isolated participant's model: a default, and whether the instance's starter may change it. */
+export type ParticipantModel = {
+    readonly provider: string;
+    readonly model: string;
+    readonly thinkingEffort?: ThinkingEffort;
+    readonly configurable: boolean;
+};
+export type Participant = 
+/** The root's own agent. */
+{
+    readonly context: 'conversation';
+}
+/** A delegated agent the workflow starts itself, under a host-bound role. */
+ | {
+    readonly context: 'isolated';
+    readonly lifetime: 'instance' | 'attempt';
+    readonly role: string;
+    readonly model: ParticipantModel;
+};
+export type Binding = {
+    /** The instance's input, a step's whole result, or one participant's output in it. */
+    readonly source: '$input' | {
+        readonly step: string;
+        readonly participant?: string;
+    };
+    readonly mode: 'current' | 'historical';
+    readonly optional: boolean;
+}
+/** A host-bound evidence provider, resolved at attempt entry. */
+ | {
+    readonly evidence: string;
+    readonly optional: boolean;
+};
+export type Assignment = {
+    readonly participant: string;
+    /** The step inputs this assignment receives. */
+    readonly reads: readonly string[];
+    readonly prompt: string;
+    readonly output: z.ZodType;
+    /** Host-bound check providers judging an isolated participant's answer; omitted = []. */
+    readonly checks?: readonly string[];
+};
+/** A choice a person may attach to a `revise`, with the decision reasons it may accompany. */
+export type StepOption = {
+    readonly name: string;
+    readonly on: readonly ('gate' | 'recovery')[];
+};
+/** One condition of an edge: the JSON Pointer `field` of the routing envelope equals `equals`. */
+export type Condition = {
+    readonly field: string;
+    readonly equals: JsonScalar;
+};
+export type Edge = {
+    readonly when: readonly Condition[] | 'otherwise';
+    readonly to: string;
+};
+export type Step = {
+    readonly inputs: Readonly<Record<string, Binding>>;
+    readonly assignments: readonly Assignment[];
+    /** A person's decision after every assignment is accepted. */
+    readonly gate: boolean;
+    /** Omitted = []. */
+    readonly options?: readonly StepOption[];
+    /** A host-bound allowlist policy name; `null` adds no step restriction. */
+    readonly restriction: string | null;
+    readonly maxAttempts: number;
+    /** Evaluated in order over the step's result; the first match is taken. The last is `otherwise`. */
+    readonly edges: readonly Edge[];
+};
+/**
+ * A workflow as its author writes it, handed to {@link defineWorkflow}. Its `id` is its whole
+ * identity: an edit that keeps the procedure's meaning (a prompt, a schema, an allowance) keeps the
+ * id and applies to running instances from their next action; a breaking one gets a new id.
+ */
+export type Definition = {
+    readonly id: string;
+    /** The instance's input. */
+    readonly input: z.ZodType;
+    readonly entry: string;
+    /** Host-bound checks on the conversation participant's agent; omitted = []. */
+    readonly prerequisites?: readonly string[];
+    readonly participants: Readonly<Record<string, Participant>>;
+    readonly steps: Readonly<Record<string, Step>>;
+};
+/** A definition's data with every omitted list filled in: what is validated. */
+export type DefinitionData = Omit<Definition, 'prerequisites' | 'steps'> & {
+    readonly prerequisites: readonly string[];
+    readonly steps: Readonly<Record<string, Omit<Step, 'options' | 'assignments'> & {
+        readonly options: readonly StepOption[];
+        readonly assignments: readonly (Assignment & {
+            readonly checks: readonly string[];
+        })[];
+    }>>;
+};
+/** A schema as its JSON Schema rendering: what the model is shown and an instance records. */
+export type JsonSchema = {
+    readonly [key: string]: ReadonlyJsonValue;
+};
+/**
+ * A definition as plain JSON: its data, omitted lists filled in, with every schema replaced by its
+ * rendering. It is the readable copy an instance records for audit and display, never executed.
+ */
+export type CanonicalDefinition = Omit<DefinitionData, 'input' | 'steps'> & {
+    readonly input: JsonSchema;
+    readonly steps: Readonly<Record<string, Omit<DefinitionData['steps'][string], 'assignments'> & {
+        readonly assignments: readonly (Omit<DefinitionData['steps'][string]['assignments'][number], 'output'> & {
+            readonly output: JsonSchema;
+        })[];
+    }>>;
+};
+/**
+ * A defined workflow: a frozen, canonical copy of the author's definition, admitted. Only
+ * {@link defineWorkflow} makes one, and registration takes nothing else. Its validators are rebuilt
+ * from the admitted schemas and held apart ({@link schemaOf}), so nothing the host holds, and
+ * nothing reachable from the definition, can change what it validates.
+ */
+export type WorkflowDefinition = CanonicalDefinition;
+/** A definition refused, with every problem found. */
+export declare class WorkflowDefinitionError extends Error {
+    readonly workflow: string;
+    readonly problems: readonly string[];
+    constructor(workflow: string, problems: readonly string[]);
+}
+export declare const isWorkflowDefinition: (value: unknown) => value is WorkflowDefinition;
+/** The schema `definition` validates its input, or one assignment's output, with; for this plugin only. */
+export declare function schemaOf(definition: WorkflowDefinition, target: '$input' | {
+    readonly step: string;
+    readonly participant: string;
+}): z.ZodType;
+/**
+ * Admits a workflow definition (§5 of the design): checks its shape, schemas and graph, then copies
+ * and freezes it. Every problem is reported at once in a {@link WorkflowDefinitionError}.
+ * Later changes to the object passed in change nothing about the definition returned. Names the host
+ * binds (restrictions, prerequisites, roles, providers) are checked when the definition is registered.
+ */
+export declare function defineWorkflow(definition: Definition): WorkflowDefinition;
+/** Splits a JSON Pointer into unescaped tokens, or `undefined` when it is not one. */
+export declare function pointerTokens(pointer: string): string[] | undefined;
+/** What a step's edges test: its accepted outputs by participant, and the decision on them. */
+export type Envelope = {
+    readonly outputs: Readonly<Record<string, ReadonlyJsonValue>>;
+    readonly decision: ResultDecision | null;
+};
+/**
+ * The edge routing takes: the first, in declaration order, whose every condition holds over
+ * `envelope`; a missing field holds no condition. Registration makes the last edge `otherwise`, so
+ * one always matches.
+ */
+export declare function selectEdge(edges: readonly Edge[], envelope: Envelope): Edge;
+/** What a recovery's revise with `option` routes over: no outputs, and the decision. */
+export declare const recoveryEnvelope: (option: string, feedback: string | null) => Envelope;
+/**
+ * Why `edge`, selected for a recovery's revise with `option`, cannot take it, or `null`: it must
+ * guard both `/decision/reason = recovery` and `/decision/option = option`, so an `otherwise` or a
+ * match that happens to hold never routes a recovery, and it must enter a step, not complete the
+ * instance, which a recovery has no result to complete with.
+ */
+export declare function recoveryEdgeProblem(edge: Edge, option: string): string | null;
+/** What a host binds by name for its definitions: what registration checks they name. */
+export type DefinitionBindings = {
+    /** Restriction policies, by name. */
+    readonly restrictions: ReadonlySet<string>;
+    /** Prerequisites the host checks, by name. */
+    readonly prerequisites: ReadonlySet<string>;
+    /** Roles isolated participants run under, by name. */
+    readonly roles: ReadonlySet<string>;
+    /** Check providers, by name. */
+    readonly checks: ReadonlySet<string>;
+    /** Evidence providers, by name. */
+    readonly evidence: ReadonlySet<string>;
+};
+/**
+ * Why `definition` cannot be registered against `bindings`: names it uses that the host does not
+ * bind. Whether a bound provider is available is asked at each opening, never here.
+ */
+export declare function bindingProblems(definition: WorkflowDefinition, bindings: DefinitionBindings): string[];