@parcha/agentrun-pi 0.1.0-beta.12 → 0.1.0-beta.13

package/dist/durable/recording.js

@@ -0,0 +1,292 @@
+// A run's store as durable recording lines (agentrun.recording/1, section 3.1). Three readers share one mapper, so a
+// commit gives the same lines whichever reads it:
+//   - recordCommits, inside the run's process, maps each commit pi publishes as it is adopted (the full history,
+//     tasks at their real commit);
+//   - snapshotLines writes every document at one commit, for a process to record after it opens the run;
+//   - recordingLines reads a store file no process holds: the history pi kept (it deletes a current-only document's
+//     older revisions when it writes a new base, and the driver document checkpoints every 32 deltas).
+import { apply } from "@earendil-works/chord/delta";
+import { frozenEffectPath } from "@parcha/agentrun-dsl/recovery";
+import { withDurableFile } from "./readers.js";
+const PREFIXES = [["agentrun.", "workflow"], ["browser.", "browser"], ["vision.", "vision"], ["transport.", "transport"], ["pi.", "pi"]];
+const sourceOf = (kind) => PREFIXES.find(([prefix]) => kind.startsWith(prefix))?.[1] ?? "host";
+/** The path a node attempt's session key names: `<driver>:<label>:<frame>:<path>:a<n>` (`frozenStepSessionId`). A label
+ *  or a path may hold the frame marker too, and then the key names no single path: only a key with one marker has one. */
+function nodePath(key) {
+    const frames = [...key.matchAll(/:(?:step|adapt):\//g)];
+    const attempt = /:a\d+$/.exec(key);
+    if (frames.length !== 1 || !attempt)
+        return undefined;
+    return key.slice(frames[0].index + frames[0][0].length - 1, attempt.index);
+}
+/** The execution path a document names: an effect's id is `<frame>:<path>#call:<n>` after the journal key and NUL
+ *  (`frozenEffectId`, read by the DSL's own `frozenEffectPath`), a node attempt's key is `nodePath`'s, and any
+ *  other value may carry `executionPath` or `execution_path`. */
+function pathOf(kind, key, value) {
+    if (kind === "agentrun.effects" && key !== undefined)
+        return frozenEffectPath(key.slice(key.indexOf("\u0000") + 1))?.path;
+    if (kind === "agentrun.nodes" && key !== undefined)
+        return nodePath(key);
+    const named = value?.executionPath ?? value?.execution_path;
+    return typeof named === "string" ? named : undefined;
+}
+/** A node attempt's conversation and path, from an `agentrun.nodes` document: its value names the conversation the
+ *  attempt runs in, its key the step's path. */
+function nodeConversation(key, value) {
+    const path = key === undefined ? undefined : nodePath(key);
+    return typeof value?.conversation === "number" && path !== undefined ? [value.conversation, path] : undefined;
+}
+/** A line in a node's conversation (an entry, a conversation's document, a task) takes the node's path when it names
+ *  none of its own, so a branch's view holds its agent's turns. */
+function stampPaths(placed, conversations) {
+    for (const at of placed) {
+        const path = at.line.conv === undefined || at.line.path !== undefined ? undefined : conversations.get(at.line.conv);
+        if (path !== undefined)
+            at.line = { ...at.line, path };
+    }
+}
+/** A document revision: `key` is the family key (absent for a singleton), `conv` the conversation the document
+ *  belongs to (its scope's, or its task's). */
+function documentLine(id, kind, key, value, version, conv, commit) {
+    const path = pathOf(kind, key, value);
+    return { commit, rank: 0, id, line: {
+            channel: "durable", source: sourceOf(kind), kind, commit, ...(path !== undefined ? { path } : {}), ...(conv !== undefined ? { conv } : {}),
+            data: { doc: kind, ...(key !== undefined ? { key } : {}), value, version },
+        } };
+}
+const entryLine = (entry, commit) => ({ commit, rank: 1, id: Number(entry.id), line: {
+        channel: "durable", source: "pi", kind: String(entry?.kind ?? "pi.entry"), commit, conv: Number(entry.conversationId), data: entry,
+    } });
+const taskLine = (task, commit) => {
+    const kind = String(task.kind);
+    return { commit, rank: 2, id: Number(task.id), line: { channel: "durable", source: sourceOf(kind), kind, commit, conv: Number(task.conversationId), data: task } };
+};
+/** Lines in `(commit, order)` order, each with the generation `genAt` gives its commit. */
+function numbered(placed, genAt, extra = {}) {
+    placed.sort((a, b) => a.commit - b.commit || a.rank - b.rank || a.id - b.id);
+    const lines = [];
+    for (let i = 0; i < placed.length; i += 1) {
+        const { commit, line } = placed[i];
+        const order = i > 0 && placed[i - 1].commit === commit ? lines[i - 1].order + 1 : 0;
+        const gen = genAt(commit);
+        const { data, ...rest } = line;
+        lines.push({ ...rest, ...(gen !== undefined ? { gen } : {}), order, ...extra, data });
+    }
+    return lines;
+}
+/** Each node attempt's conversation and path, from every `agentrun.nodes` document's latest value. */
+function nodeConversations(db) {
+    const out = new Map();
+    for (const doc of db.prepare("SELECT id, key_value FROM documents WHERE kind = ? AND family = 1").all(JSON.stringify("agentrun.nodes"))) {
+        let value;
+        for (const rev of db.prepare("SELECT kind, content FROM document_revisions WHERE document_id = ? ORDER BY seq").all(doc.id)) {
+            value = rev.kind === "base" ? JSON.parse(rev.content) : apply(structuredClone(value), JSON.parse(rev.content));
+        }
+        const found = nodeConversation(JSON.parse(doc.key_value), value);
+        if (found)
+            out.set(found[0], found[1]);
+    }
+    return out;
+}
+/** Every surviving `agentrun.driver` revision as `[commit, generation]`, in commit order. */
+function driverGenerations(db) {
+    const out = [];
+    for (const { id } of db.prepare("SELECT id FROM documents WHERE kind = ?").all(JSON.stringify("agentrun.driver"))) {
+        let value;
+        for (const rev of db.prepare("SELECT seq, kind, content FROM document_revisions WHERE document_id = ? ORDER BY seq").all(id)) {
+            value = rev.kind === "base" ? JSON.parse(rev.content) : apply(structuredClone(value), JSON.parse(rev.content));
+            if (typeof value?.generation === "number")
+                out.push([rev.seq, value.generation]);
+        }
+    }
+    // Two journals' revisions in one commit: the higher generation.
+    return out.sort((a, b) => a[0] - b[0] || a[1] - b[1]);
+}
+/**
+ * Every change the store `file` committed after `after` (default: all), as durable recording lines in `(commit, order)`
+ * order, and `last`, the highest commit returned (`after` when nothing is). For a store no process holds (a disk run's
+ * store admits one connection): read-only, in one read transaction.
+ *
+ * - A document revision is a line of the document's kind, with the whole value after it (each delta applied over its
+ *   base); `key` is the family key as stored, absent for a singleton.
+ * - A conversation entry is a line of the entry's own kind, source `pi`, `conv` its conversation, the entry as stored
+ *   (image blocks included: the recorder moves them to blobs).
+ * - Every task's current record is a line of the task's kind, at the store's last commit, after that commit's other
+ *   lines, by task id: the state at export, since the store keeps no commit for a task's change. Its memos ride in the
+ *   record; there are no memo lines.
+ * - `gen` is the generation of the latest surviving `agentrun.driver` revision at or before the line's commit (it
+ *   counts journal opens, not processes), and absent before the earliest surviving one. No line has `t`: the store
+ *   keeps no commit time.
+ *
+ * This is the store's surviving history: pi deletes a current-only document's older revisions when it writes a new
+ * base. The full history is `recordCommits`', written inside the run's process as each commit lands.
+ */
+export function recordingLines(file, options = {}) {
+    const after = options.after ?? 0;
+    return withDurableFile(file, (db) => {
+        const placed = [];
+        const taskConversation = new Map(db.prepare("SELECT id, conversation_id FROM tasks").all().map((task) => [task.id, task.conversation_id]));
+        const docs = db.prepare("SELECT DISTINCT d.id, d.kind, d.family, d.key_value, d.scope_kind, d.owner_id FROM documents d JOIN document_revisions r ON r.document_id = d.id WHERE r.seq > ?")
+            .all(after);
+        for (const doc of docs) {
+            const kind = JSON.parse(doc.kind);
+            const key = doc.family === 1 ? JSON.parse(doc.key_value) : undefined;
+            const conv = doc.scope_kind === "conversation" ? doc.owner_id : doc.scope_kind === "task" ? taskConversation.get(doc.owner_id) : undefined;
+            let value;
+            for (const rev of db.prepare("SELECT seq, kind, version, content FROM document_revisions WHERE document_id = ? ORDER BY seq").all(doc.id)) {
+                value = rev.kind === "base" ? JSON.parse(rev.content) : apply(structuredClone(value), JSON.parse(rev.content));
+                if (rev.seq > after)
+                    placed.push(documentLine(doc.id, kind, key, structuredClone(value), rev.version, conv, rev.seq));
+            }
+        }
+        for (const entry of db.prepare("SELECT commit_seq, record FROM entries WHERE commit_seq > ?").all(after)) {
+            placed.push(entryLine(JSON.parse(entry.record), entry.commit_seq));
+        }
+        const end = db.prepare("SELECT next_seq FROM durable_metadata WHERE singleton = 1").get().next_seq - 1;
+        if (end > after)
+            for (const task of db.prepare("SELECT record FROM tasks").all())
+                placed.push(taskLine(JSON.parse(task.record), end));
+        stampPaths(placed, nodeConversations(db));
+        const generations = driverGenerations(db);
+        let at = 0;
+        const lines = numbered(placed, (commit) => {
+            while (at < generations.length && generations[at][0] <= commit)
+                at += 1;
+            return at > 0 ? generations[at - 1][1] : undefined;
+        });
+        return { lines, last: lines.length ? lines[lines.length - 1].commit : after };
+    }) ?? { lines: [], last: after };
+}
+/** The lines of one commit pi published, as `recordingLines` would give them. A commit that writes driver revisions
+ *  sets the generation to the highest among them, as the file read does; any other commit keeps it. */
+function publicationLines(publication, state) {
+    const commit = Number(publication.seq);
+    const placed = [];
+    let written;
+    for (const change of publication.changes) {
+        if (change.type === "document") {
+            // A retirement adopts no value and the store keeps no revision for it.
+            if (change.value === null || change.version === undefined)
+                continue;
+            const { record } = change;
+            placed.push(documentLine(Number(record.id), record.kind, record.key, structuredClone(change.value), change.version, change.conversationId === undefined ? undefined : Number(change.conversationId), commit));
+            const generation = change.value.generation;
+            if (record.kind === "agentrun.driver" && typeof generation === "number")
+                written = Math.max(written ?? generation, generation);
+            const node = record.kind === "agentrun.nodes" ? nodeConversation(record.key, change.value) : undefined;
+            if (node)
+                state.conversations.set(node[0], node[1]);
+        }
+        else if (change.type === "entry")
+            placed.push(entryLine(structuredClone(change.value), commit));
+        else if (change.type === "task")
+            placed.push(taskLine(structuredClone(change.value), commit));
+        // A conversation's or a submission's record, and a document copy (it carries no value), make no line.
+    }
+    if (written !== undefined)
+        state.gen = written;
+    stampPaths(placed, state.conversations);
+    return numbered(placed, () => state.gen);
+}
+/**
+ * Records the run's commits as durable lines inside its process, on pi's commit publications: each commit adopted
+ * after this call becomes the lines `recordingLines` would give it, with tasks at their real commit, `t` the adoption
+ * time (`clock()`, default `Date.now()`), and `gen` the generation of the latest `agentrun.driver` revision at or
+ * before the commit. `from` is the snapshot this recording continues (`snapshotLines`, written before the run
+ * resumed): its driver generation and its nodes' conversations carry on until this process writes its own. `gen` is
+ * only for a run with no driver revision yet; it never overrides a driver generation.
+ *
+ * The listener only maps and queues: it never throws, blocks or calls the Session. `write` receives one commit's lines
+ * at a time, in commit order, after the listener has returned. A `write` that completes synchronously (an append to a
+ * file) runs before pi adopts the next commit, so a process that dies loses at most the commit in flight; one that
+ * completes later leaves the commits after it queued in memory, and a death loses those too. The next process's
+ * `snapshotLines` restores the documents' state; a lost commit's entries stay missing, a gap the viewer shows. The
+ * returned stop ends the subscription, waits for every queued write, and then throws the first write that failed.
+ */
+export function recordCommits(session, options) {
+    const clock = options.clock ?? Date.now;
+    const fromDriver = (options.from ?? []).reduce((max, line) => {
+        const generation = line.kind === "agentrun.driver" ? line.data?.value?.generation : undefined;
+        return typeof generation === "number" ? Math.max(max ?? generation, generation) : max;
+    }, undefined);
+    const state = { gen: fromDriver ?? options.from?.at(-1)?.gen ?? options.gen, conversations: new Map() };
+    for (const line of options.from ?? []) {
+        const node = line.kind === "agentrun.nodes" ? nodeConversation(line.data?.key, line.data?.value) : undefined;
+        if (node)
+            state.conversations.set(node[0], node[1]);
+    }
+    let chain = Promise.resolve();
+    let failure;
+    const unsubscribe = session.subscribeCommits((publication) => {
+        try {
+            const t = clock();
+            const mapped = publicationLines(publication, state);
+            if (mapped.length === 0)
+                return;
+            const lines = mapped.map((line) => ({ ...line, t }));
+            chain = chain.then(() => options.write(lines)).catch((error) => { failure ??= { error }; });
+        }
+        catch (error) {
+            failure ??= { error };
+        }
+    });
+    return async () => {
+        unsubscribe();
+        await chain;
+        if (failure)
+            throw failure.error;
+    };
+}
+/** Every page of a storage scan. */
+async function scanAll(scan) {
+    const out = [];
+    let cursor;
+    do {
+        const page = await scan(cursor);
+        out.push(...page.items);
+        cursor = page.next;
+    } while (cursor !== undefined);
+    return out;
+}
+/**
+ * Every document of the run as it stands, as whole values marked `snapshot: true` at commit `at`, in document id order:
+ * the state a process records after it opens the run and before it resumes, so the recording is exact after any kill.
+ * `storage` is the store the run's Harness was opened over; `at` is the store's latest commit (pi's `Storage` has no
+ * head query: a disk run reads it with pi-durable-disk's `storeHead`). The reads are of the current state (pi keeps no
+ * past revision of a session or task document), so the snapshot is exact only while nothing commits: take it before
+ * the run resumes. Every line's `gen` is the highest `agentrun.driver` generation in it; `gen` is only for a run with no
+ * driver revision yet, and never overrides one.
+ */
+export async function snapshotLines(storage, options) {
+    const { at, context } = options;
+    const page = 256;
+    const conversations = await scanAll((cursor) => storage.scanConversations({}, page, cursor, context));
+    const tasks = await scanAll((cursor) => storage.scanTasks({}, page, cursor, context));
+    const scopes = [
+        { scope: { kind: "session" }, conv: undefined },
+        ...conversations.map((conversation) => ({ scope: { kind: "conversation", conversationId: conversation.id }, conv: Number(conversation.id) })),
+        ...tasks.map((task) => ({ scope: { kind: "task", taskId: task.id }, conv: Number(task.conversationId) })),
+    ];
+    const placed = [];
+    let driverGen;
+    for (const { scope, conv } of scopes) {
+        for (const record of await scanAll((cursor) => storage.scanDocuments({ scope, at: "current" }, page, cursor, context))) {
+            const stored = await storage.document(record.id, "current", context);
+            if (!stored)
+                continue;
+            placed.push(documentLine(Number(record.id), record.kind, record.key, structuredClone(stored.value), stored.version, conv, at));
+            const generation = stored.value.generation;
+            if (record.kind === "agentrun.driver" && typeof generation === "number")
+                driverGen = Math.max(driverGen ?? generation, generation);
+        }
+    }
+    const nodes = new Map();
+    for (const { line } of placed) {
+        const node = line.kind === "agentrun.nodes" ? nodeConversation(line.data.key, line.data.value) : undefined;
+        if (node)
+            nodes.set(node[0], node[1]);
+    }
+    stampPaths(placed, nodes);
+    const gen = driverGen ?? options.gen;
+    return numbered(placed, () => gen, { snapshot: true });
+}

package/dist/durable/store.d.ts

@@ -0,0 +1,23 @@
+import type { Harness } from "@earendil-works/pi-durable";
+import type { Context } from "@earendil-works/chord";
+import { type RecoveryStore } from "@parcha/agentrun-dsl/recovery";
+/** An effect's key in `agentrun.effects`: its journal key, then its id. The two are joined by NUL, so neither may hold
+ *  one: two pairs could otherwise name the same document. */
+export declare const effectKey: (key: string, id: string) => string;
+/** What a store writes through: a Harness, or the `commit` a running task is handed. */
+export type DocumentStoreHost = Pick<Harness, "commit">;
+export type DocumentStoreOptions = {
+    /** The one owner of the journal across the invocations of a task (its id). An open by this owner takes over a journal
+     *  an earlier invocation left open, whose later writes then fail; an open by another owner is refused while the
+     *  journal is open. The guard is per process, by journal key: an owner is unique to its run, and two Harness files in
+     *  one process that hold one run key under one owner count as one. Without an owner the guard is per host object,
+     *  and a second open of a key is refused until the first is closed. */
+    owner?: string;
+    /** The context every commit runs under; default `BACKGROUND_CONTEXT`. A task passes its invocation's, so the
+     *  invocation's cancellation ends its writes. */
+    context?: Context;
+};
+/** The recovery store for the journal `key` that `host` writes. Opening it takes ownership: a journal already open is
+ *  refused (unless the same `owner` opens it again), a binding that differs from the one the journal was first opened
+ *  under is refused naming the inputs that moved, and the generation advances. */
+export declare function documentStore(host: DocumentStoreHost, key: string, options?: DocumentStoreOptions): RecoveryStore;

package/dist/durable/store.js

@@ -0,0 +1,192 @@
+import { defineDocFamily } from "@earendil-works/pi-durable";
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import { RecoveryError, asRecoveryError, bindingMismatch } from "@parcha/agentrun-dsl/recovery";
+import { storageError } from "./pi-versions.js";
+/** A failed commit as the driver reads it: its own message and code, kept as a RecoveryError. A Session that failed at a
+ *  storage error answers with `SessionFailed` (pi-durable 1.2); the error is then the storage's, as 1.1 gave it, and the
+ *  `SessionFailed` is its cause. */
+function storeFailure(error) {
+    const own = storageError(error);
+    if (own === error || own instanceof RecoveryError)
+        return asRecoveryError(own);
+    const code = own?.code;
+    return new RecoveryError(own instanceof Error ? own.message : String(own), typeof code === "string" ? code : undefined, { cause: error });
+}
+/** An effect's key in `agentrun.effects`: its journal key, then its id. The two are joined by NUL, so neither may hold
+ *  one: two pairs could otherwise name the same document. */
+export const effectKey = (key, id) => {
+    if (key.includes("\u0000") || id.includes("\u0000"))
+        throw new RecoveryError("A journal key and an effect id hold no NUL character");
+    return `${key}\u0000${id}`;
+};
+/** A base every 32 deltas keeps a read of the journal short, however long the run. */
+const checkpointWhen = (_value, _ops, info) => info.deltasSinceBase >= 32;
+const DriverDoc = defineDocFamily({ kind: "agentrun.driver", version: 1, scope: "session", family: true, checkpointWhen,
+    initial: () => ({ binding: null, inputs: null, generation: 0, revision: 0, state: null, notes: [], effects: [] }) });
+const EffectDoc = defineDocFamily({ kind: "agentrun.effects", version: 1, scope: "session", family: true,
+    initial: () => ({ driver: "", name: "", argsHash: "", status: "unknown", session: null, result: null }) });
+/** A value as the journal stores it: plain JSON, every number finite. */
+function json(value) {
+    return value === undefined ? null : JSON.parse(JSON.stringify(value, (_key, item) => {
+        if (typeof item === "bigint" || typeof item === "function" || typeof item === "symbol" || (typeof item === "number" && !Number.isFinite(item))) {
+            throw new RecoveryError("A journal holds finite JSON values only");
+        }
+        return item;
+    }));
+}
+/** The journals open in this process. The run's lock keeps every other process off the run, and the journal's generation
+ *  fences a stale writer; this keeps a second open of one key off it here. Without an owner a host's own keys are
+ *  tracked; with one, the keys by owner. */
+const hostKeys = new WeakMap();
+const ownedKeys = new Map();
+/** Take the in-process hold on `key`: what gives it back, and what undoes the take when the open fails. */
+function hold(host, key, owner) {
+    const refused = () => new RecoveryError("Run already has a live owner");
+    if (owner === undefined) {
+        const keys = hostKeys.get(host) ?? hostKeys.set(host, new Set()).get(host);
+        if (keys.has(key))
+            throw refused();
+        keys.add(key);
+        const release = () => { keys.delete(key); };
+        return { release, undo: release };
+    }
+    const previous = ownedKeys.get(key);
+    if (previous && previous.owner !== owner)
+        throw refused();
+    const token = Symbol(key);
+    ownedKeys.set(key, { token, owner });
+    return {
+        release: () => { if (ownedKeys.get(key)?.token === token)
+            ownedKeys.delete(key); },
+        undo: () => { if (ownedKeys.get(key)?.token !== token)
+            return; if (previous)
+            ownedKeys.set(key, previous);
+        else
+            ownedKeys.delete(key); },
+    };
+}
+/** The recovery store for the journal `key` that `host` writes. Opening it takes ownership: a journal already open is
+ *  refused (unless the same `owner` opens it again), a binding that differs from the one the journal was first opened
+ *  under is refused naming the inputs that moved, and the generation advances. */
+export function documentStore(host, key, options = {}) {
+    return { open: (bound) => openDocumentJournal(host, key, bound, options) };
+}
+async function openDocumentJournal(host, key, bound, options) {
+    effectKey(key, "");
+    const context = options.context ?? BACKGROUND_CONTEXT;
+    const held = hold(host, key, options.owner);
+    const opened = await host.commit(async (tx) => {
+        const doc = await tx.doc(DriverDoc, key, null);
+        const existing = doc.binding !== null;
+        if (existing && doc.binding !== bound.binding)
+            throw bindingMismatch(doc.inputs ? JSON.stringify(doc.inputs) : null, bound.inputs);
+        if (!existing) {
+            doc.binding = bound.binding;
+            doc.inputs = bound.inputs ? { ...bound.inputs } : null;
+        }
+        doc.generation += 1;
+        const effects = [];
+        for (const id of doc.effects) {
+            const e = await tx.doc(EffectDoc, effectKey(key, id), null);
+            effects.push({ id, name: e.name, argsHash: e.argsHash, status: e.status, session: e.session, result: json(e.result), ...(e.intent ? { intent: json(e.intent) } : {}), ...(e.args !== undefined ? { args: json(e.args) } : {}), ...(Array.isArray(e.calls) ? { calls: json(e.calls) } : {}) });
+        }
+        return { existing, generation: doc.generation, revision: doc.revision, state: json(doc.state), notes: json(doc.notes), effects };
+    }, context).catch((error) => { held.undo(); throw storeFailure(error); });
+    const effects = new Map(opened.effects.map((effect) => [effect.id, effect]));
+    const notes = [...opened.notes];
+    let revision = opened.revision;
+    let closed = false;
+    /** Writes run one at a time, in the order they were asked for, each with its checks. A failed write does not stop
+     *  the next, and one asked for before `close` still lands. */
+    let queue = Promise.resolve();
+    const inOrder = (write) => {
+        if (closed)
+            return Promise.reject(new RecoveryError("The journal is closed"));
+        const done = queue.then(write).catch((error) => { throw storeFailure(error); });
+        queue = done.catch(() => undefined);
+        return done;
+    };
+    /** One Session commit on the journal's record: it checks this open's generation is the record's, advances the
+     *  revision, and lets `write` change the record (its state computed with that revision) and the effect documents. */
+    const commit = async (write) => host.commit(async (tx) => {
+        const doc = await tx.doc(DriverDoc, key, null);
+        if (doc.generation !== opened.generation)
+            throw new RecoveryError("Run owner generation is not acquired");
+        const next = doc.revision + 1;
+        const value = await write(doc, next, tx);
+        doc.revision = next;
+        return { revision: next, value };
+    }, context).then((done) => { revision = done.revision; return done; });
+    return {
+        existing: opened.existing, generation: opened.generation, state: opened.state,
+        get revision() { return revision; },
+        effects: () => [...effects.values()],
+        effect: (id) => effects.get(id),
+        notes: () => [...notes],
+        save: (state, note) => inOrder(async () => {
+            let entry;
+            const done = await commit((doc, next) => {
+                doc.state = json(typeof state === "function" ? state(next) : state);
+                if (note) {
+                    entry = { revision: next, kind: note.kind, detail: json(note.detail), at: new Date().toISOString() };
+                    doc.notes.push(entry);
+                }
+            });
+            if (entry)
+                notes.push(entry);
+            return done.revision;
+        }),
+        note: (kind, detail) => inOrder(async () => {
+            const entry = { kind, detail: json(detail), at: new Date().toISOString() };
+            const done = await commit((doc, next) => { doc.notes.push({ revision: next, ...entry }); });
+            notes.push({ revision: done.revision, ...entry });
+            return done.revision;
+        }),
+        admit: (id, name, argsHash, state, session = null, intent, args) => inOrder(async () => {
+            effectKey(key, id);
+            const known = effects.get(id);
+            if (known)
+                return known;
+            const stored = json(state);
+            const kept = intent === undefined ? undefined : json(intent);
+            const keptArgs = args === undefined ? undefined : json(args);
+            await commit(async (doc, _next, tx) => {
+                Object.assign(await tx.doc(EffectDoc, effectKey(key, id), null), { driver: key, name, argsHash, status: "unknown", session, result: null, ...(kept ? { intent: kept } : {}), ...(keptArgs !== undefined ? { args: keptArgs } : {}) });
+                doc.effects.push(id);
+                doc.state = stored;
+            });
+            effects.set(id, { id, name, argsHash, status: "unknown", session, result: null, ...(kept ? { intent: kept } : {}), ...(keptArgs !== undefined ? { args: keptArgs } : {}) });
+            return "new";
+        }),
+        complete: (id, result, state = opened.state) => inOrder(async () => {
+            const known = effects.get(id);
+            if (!known)
+                throw new RecoveryError(`Effect ${id} completes without an admission`);
+            if (known.status === "completed")
+                throw new RecoveryError(`Effect ${id} completes once`);
+            const value = json(result);
+            const next = json(state);
+            await commit(async (doc, _next, tx) => {
+                const effect = await tx.doc(EffectDoc, effectKey(key, id), null);
+                effect.status = "completed";
+                effect.result = value;
+                doc.state = next;
+            });
+            effects.set(id, { ...known, status: "completed", result: value });
+        }),
+        called: (id, calls) => inOrder(async () => {
+            if (!effects.has(id))
+                throw new RecoveryError(`Effect ${id} records calls without an admission`);
+            const value = json(calls);
+            await commit(async (_doc, _next, tx) => { (await tx.doc(EffectDoc, effectKey(key, id), null)).calls = value; });
+            effects.set(id, { ...effects.get(id), ...(Array.isArray(value) ? { calls: value } : {}) });
+        }),
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            await queue;
+            held.release();
+        },
+    };
+}

package/dist/durable/task.d.ts

@@ -0,0 +1,129 @@
+import type { Extension, Harness, TaskId, TaskRuntime } from "@earendil-works/pi-durable";
+import { runWorkflow, type Workflow, type WorkflowDeps } from "@parcha/agentrun-dsl";
+import { type EscalationRow, type RecoveryAdapters, type RecoveryDriver, type RecoveryOptions } from "@parcha/agentrun-dsl/recovery";
+type Context = Parameters<Harness["commit"]>[1];
+/** What one run is: its key (the same key reaches the same task and journal), the workflow as authored, its input, and
+ *  what else must not change between two opens of it. */
+export type WorkflowRequest = {
+    key: string;
+    workflow: Workflow;
+    input: Record<string, unknown>;
+    bind?: Record<string, unknown>;
+};
+/** How a run ended, as the host reads it. A pause is not an outcome: a paused run's task stays pending. */
+export type WorkflowOutcome = {
+    status: "complete";
+    output: unknown;
+    state: unknown;
+} | {
+    status: "escalated";
+    escalation: unknown;
+    state: unknown;
+    continuation?: unknown;
+} | {
+    status: "refused";
+    code: string;
+    message: string;
+    detail?: unknown;
+} | {
+    status: "stopped";
+    stop: "cancelled";
+    source?: string;
+};
+/** One invocation of a run's phase, as the host's adapters see it: a node runner that opens conversations owns them by
+ *  `runtime.taskId`, so a cancel aborts them before the task. */
+export type WorkflowInvocation = {
+    key: string;
+    taskId: TaskId;
+    runtime: TaskRuntime<WorkflowRequest, TaskCheckpoint, WorkflowResult, object>;
+    context: Context;
+};
+/** The host's part, asked once per invocation. */
+export type WorkflowTaskHost = {
+    /** The driver's host options, beside the run's key and binding: asked before the driver opens, by the run's phase and
+     *  by its abort handler. A host settles an effect a killed process left unknown with `reconcile`: the driver calls it
+     *  once, through its own open of the run, with the unknown effects and a `complete` that records one's result. An
+     *  effect it completes is answered from that result and not dispatched again; one it leaves is refused at resume. Do not
+     *  open the run's journal here: that open is a generation of its own. The task's abort handler opens the driver too, to
+     *  record a cancel, so `reconcile` also runs then; `phase` is `"abort"` there and `"run"` for the run's own open, and a
+     *  host that wants no reconcile during a cancel returns none for `"abort"`. */
+    options?(invocation: WorkflowInvocation & {
+        phase: "run" | "abort";
+    }): Omit<RecoveryOptions, "key" | "bind"> | Promise<Omit<RecoveryOptions, "key" | "bind">>;
+    /** What the interpreter runs with, asked once the driver is open, so a host that composes its own couplings over the
+     *  driver (its spend, its sessions, its escalation rows) builds them here. */
+    run(invocation: WorkflowInvocation & {
+        driver: RecoveryDriver;
+    }): WorkflowHostParts | Promise<WorkflowHostParts>;
+    /** The host's ladder: a run that did not complete and was not refused continues here, inside the task's invocation,
+     *  so what the host opens (its continuation) is owned by the task, and a cancel aborts it before the task. The host
+     *  commits the escalation row through `invocation.driver.escalate` before anything acts on it; a run reopened after
+     *  that commit comes here again with the row, and the interpreter does not run. `invocation.signal` ends with the
+     *  run's stops: a pause leaves the task pending, and the next open comes here again with the row. What it returns
+     *  rides on the escalated outcome as `continuation`; a throw is the run's failure. Absent, an escalated run ends with
+     *  the interpreter's escalation and any failure is the run's. */
+    escalated?(ending: WorkflowEnding, invocation: WorkflowInvocation & {
+        driver: RecoveryDriver;
+        signal: AbortSignal;
+    }): Promise<unknown>;
+};
+/** Why a run continues on the host's ladder: a gate that fired (`escalation`), a failure that is not a refusal
+ *  (`error`), a refusal found before any step (`refusal`), or an escalation an earlier invocation committed (`row`).
+ *  `state` is the run's state at that point. */
+export type WorkflowEnding = {
+    escalation?: unknown;
+    error?: unknown;
+    refusal?: NonNullable<RecoveryDriver["preStepRefusal"]>;
+    row?: EscalationRow;
+    state: Record<string, unknown>;
+};
+/** The host's adapters, which the task wraps with `withRecovery` (`durableNodes`: the node runner answers a delivered step
+ *  again from its own record), or the dependencies the host built over `invocation.driver` itself, which the task runs as
+ *  they are, stopped by the run's signal too, with the host's own `interpret` when it runs its documents under its own
+ *  policy (its view of the document, its lint): it is called as `runWorkflow` would be, and answers as it does. */
+export type WorkflowHostParts = {
+    adapters: RecoveryAdapters;
+    durableNodes?: boolean;
+} | {
+    deps: WorkflowDeps;
+    interpret?: (workflow: Workflow, input: Record<string, unknown>, deps: WorkflowDeps) => ReturnType<typeof runWorkflow>;
+};
+/** A started run. `wait` resolves with the run's outcome once its task is terminal, and rejects with the storage's error
+ *  when the Session failed at one. */
+export type WorkflowRun = {
+    key: string;
+    taskId: TaskId<WorkflowResult>;
+    /** `created`: this start made the task; `attached`: it was live; `settled`: it was terminal and is returned as it is. */
+    started: "created" | "attached" | "settled";
+    wait(context: Context): Promise<WorkflowOutcome>;
+};
+/** What a stop reached. A pause reaches a run only where it is live, in this process: `paused` once the run's work has
+ *  stopped with the pause in its journal, `ended` when the run ended otherwise, `not-live` when it is not running here. A cancel is `abortTask`'s
+ *  answer: `marked` (the task ends aborted later) or `terminal` (it already was). */
+export type WorkflowStop = "paused" | "ended" | "not-live" | "marked" | "terminal";
+type TaskCheckpoint = {
+    phase: "run";
+};
+/** A completed task's result: the outcomes that end a run without a refusal. */
+type WorkflowResult = Extract<WorkflowOutcome, {
+    status: "complete" | "escalated";
+}>;
+/** The task definition, the extension that carries it, and the host's three operations on a run. */
+export declare function createWorkflowExtension(host: WorkflowTaskHost): {
+    extension: Extension;
+    start(harness: Harness, request: WorkflowRequest, context: Context, options?: {
+        conversationId?: number;
+        background?: boolean;
+        stop?: {
+            action: "pause" | "cancel";
+            source?: string;
+        };
+    }): Promise<WorkflowRun>;
+    read(harness: Harness, key: string, context: Context): Promise<{
+        taskId: TaskId<WorkflowResult>;
+        status: string;
+        outcome?: WorkflowOutcome;
+    } | undefined>;
+    stop(harness: Harness, key: string, action: "pause" | "cancel", context: Context, source?: string): Promise<WorkflowStop>;
+};
+export {};