@chrok/braid 0.1.3 → 0.2.1

package/dist/types.d.ts

@@ -3,7 +3,13 @@ export interface ExecuteNode {
     id: string;
     prompt: string;
     model?: string;
-    /** Read the live cwd without a worktree; defaults to worktree in Git, read-only elsewhere. */
+    /** Ask the parent adapter for a completion reminder on success or failure. Default: false. */
+    notifyOnCompletion?: boolean;
+    /** Optional failures remain in history; true aborts the entire run on failure. */
+    requireSuccess?: boolean;
+    /** Hold this execution's outgoing dependencies until explicitly resumed. */
+    pauseAfter?: boolean;
+    /** Fresh predecessor snapshot in Git; read-only disables writes. Read-only outside Git. */
     workspace?: "read-only" | "worktree";
 }
 export interface DecisionNode {
@@ -12,20 +18,52 @@ export interface DecisionNode {
     prompt: string;
     choices: readonly string[];
     model?: string;
-    /** Read the live cwd without a worktree; defaults to worktree in Git, read-only elsewhere. */
+    /** Ask the parent adapter for a completion reminder on success or failure. Default: false. */
+    notifyOnCompletion?: boolean;
+    /** Optional failures remain in history; true aborts the entire run on failure. */
+    requireSuccess?: boolean;
+    /** Hold this execution's outgoing dependencies until explicitly resumed. */
+    pauseAfter?: boolean;
+    /** Fresh predecessor snapshot in Git; read-only disables writes. Read-only outside Git. */
     workspace?: "read-only" | "worktree";
 }
 export interface MergeNode {
     type: "merge";
     id: string;
-    /** Defaults to reviewing and integrating all predecessor workspaces. */
+    /** Defaults to combining selected predecessor checkpoints in a new worktree. */
     prompt?: string;
     model?: string;
+    /** Ask the parent adapter for a completion reminder on success or failure. Default: false. */
+    notifyOnCompletion?: boolean;
+    /** Optional failures remain in history; true aborts the entire run on failure. */
+    requireSuccess?: boolean;
+    /** Hold this execution's outgoing dependencies until explicitly resumed. */
+    pauseAfter?: boolean;
 }
-export type BraidNode = ExecuteNode | DecisionNode | MergeNode;
+export interface IntegrateNode extends Omit<MergeNode, "type"> {
+    type: "integrate";
+}
+export type BraidNode = ExecuteNode | DecisionNode | MergeNode | IntegrateNode;
+/** A reference to a template in this graph submission; values are inserted literally. */
+export interface PromptTemplateReference {
+    template: string;
+    variables: Readonly<Record<string, string>>;
+}
+export type NodePrompt = string | PromptTemplateReference;
+/** Submission nodes may use templates; ModelRequest.node always has a string prompt. */
+export type BraidInputNode = (Omit<ExecuteNode, "prompt"> & {
+    prompt: NodePrompt;
+}) | (Omit<DecisionNode, "prompt"> & {
+    prompt: NodePrompt;
+}) | (Omit<MergeNode, "prompt"> & {
+    prompt?: NodePrompt;
+}) | (Omit<IntegrateNode, "prompt"> & {
+    prompt?: NodePrompt;
+});
 export interface NodeWorkspace {
     nodeId: string;
-    mode: "read-only" | "worktree" | "merge";
+    executionId?: string;
+    mode: "read-only" | "worktree" | "integrate";
     workingDirectory: string;
     worktreeRoot?: string;
     sourceRoot?: string;
@@ -35,11 +73,13 @@ export interface NodeWorkspace {
     checkpointCommit?: string;
     /** Source checkout snapshot captured before a merge agent receives write access. */
     backupRef?: string;
+    /** Agent decisions for this merge/integrate invocation; sources remain reusable. */
+    dispositions?: MergeDisposition[];
     state: "preparing" | "ready" | "integrated" | "discarded" | "archived" | "failed";
     reason?: string;
 }
 export interface MergeDisposition {
-    nodeId: string;
+    executionId: string;
     disposition: "integrated" | "discarded" | "archived";
     reason: string;
 }
@@ -48,7 +88,7 @@ export interface GitPreview {
     truncated: boolean;
 }
 export interface MergeSource extends NodeWorkspace {
-    /** Inspection-only summaries relative to snapshotCommit; omitted by custom runners. */
+    /** Inspection-only summaries relative to the job’s initial snapshot; omitted by custom runners. */
     changes?: {
         files: string[];
         filesTruncated: boolean;
@@ -70,11 +110,23 @@ export interface Edge {
     to: string;
     /** Omit for an unconditional edge, including from a decision node. */
     choice?: string;
+    /** Explicit feedback edge into the named loop's entry. */
+    feedback?: string;
+    /** Pin a dependency to a historical execution rather than the current round. */
+    executionId?: string;
+}
+export interface LoopDefinition {
+    id: string;
+    entry: string;
+    maxIterations: number;
 }
 export interface BraidInput {
     goal: string;
-    nodes: readonly BraidNode[];
+    nodes: readonly BraidInputNode[];
     edges: readonly Edge[];
+    /** Named {{variable}} templates, expanded and validated before execution. */
+    promptTemplates?: Readonly<Record<string, string>>;
+    loops?: readonly LoopDefinition[];
 }
 export type NodeStatus = "pending" | "runnable" | "running" | "completed" | "skipped" | "failed";
 export interface TokenUsage {
@@ -88,14 +140,19 @@ export interface NodeOutput {
 }
 export interface PredecessorOutput extends NodeOutput {
     nodeId: string;
+    executionId?: string;
     /** Failed predecessors remain available on unconditional edges. */
     error?: ExecutionError;
     workspace?: NodeWorkspace;
 }
 export interface ExecutionContext {
     runId: string;
-    /** Equal to runId in v0.1; reserved identity for future shared-root accounting. */
+    /** Equal to runId; reserved identity for future shared-root accounting. */
     rootRunId: string;
+    executionId?: string;
+    revision?: number;
+    loopId?: string;
+    iteration?: number;
 }
 export interface ModelRequest {
     goal: string;
@@ -114,7 +171,7 @@ export interface ModelRequest {
     workspace?: NodeWorkspace;
     /** Rejects read-only writes; adapters must wrap mutating file tools so cleanup waits for in-flight writes. */
     withWorkspaceWrite?: <T>(operation: () => Promise<T>) => Promise<T>;
-    /** Local Git operations: inspection for workers, integration commands for merge nodes. */
+    /** Local Git operations: inspection for workers, integration commands for merge/integrate nodes. */
     git?: (args: string[], input?: string) => Promise<GitResult>;
     /** Merge nodes must account for every source before returning their final answer. */
     merge?: {
@@ -133,10 +190,14 @@ export interface ModelResponse {
 }
 /** Each call starts a fresh conversation and exposes only the adapter’s declared capabilities. */
 export type ModelRunner = (request: ModelRequest) => Promise<ModelResponse>;
-/** Frozen snapshots in emission order. Creation means admission of the submitted DAG, not mutation. */
+/** Frozen snapshots in emission order, including graph revisions and execution identities. */
 export type ExecutionEvent = Readonly<{
     sequence: number;
     timestamp: number;
+    executionId?: string;
+    revision?: number;
+    loopId?: string;
+    iteration?: number;
 } & ({
     type: "graph_created";
     nodeCount: number;
@@ -146,11 +207,23 @@ export type ExecutionEvent = Readonly<{
     nodeId: string;
     nodeType: BraidNode["type"];
     model?: string;
-} | {
+} | ({
     type: "edge_created";
-    from: string;
-    to: string;
-    choice?: string;
+} & Edge) | {
+    type: "graph_updated";
+    graph: BraidInput;
+} | {
+    type: "execution_paused";
+    nodeId: string;
+} | {
+    type: "execution_resumed";
+    nodeId: string;
+} | {
+    type: "loop_started";
+    entry: string;
+} | {
+    type: "loop_completed";
+    entry: string;
 } | {
     type: "workspace_updated";
     workspace: Readonly<NodeWorkspace>;
@@ -163,6 +236,7 @@ export type ExecutionEvent = Readonly<{
     to: string;
     output: string;
     decision?: string;
+    fromExecutionId?: string;
 } | {
     type: "node_started";
     nodeId: string;
@@ -193,7 +267,7 @@ export type ExecutionEvent = Readonly<{
 export interface BraidOptions {
     runner: ModelRunner;
     defaultModel?: string;
-    /** Source checkout. Nodes may opt into live read-only access; outside Git, all nodes are read-only. */
+    /** Source checkout for the initial snapshot and explicit integrate nodes. */
     cwd?: string;
     /** Positive integer. Defaults to 4. */
     maxConcurrency?: number;
@@ -205,30 +279,36 @@ export interface BraidOptions {
     signal?: AbortSignal;
     /** Live observer. Throws/rejections are ignored; returned work is not awaited. */
     onEvent?: (event: ExecutionEvent) => void;
+    /** Total admitted executions across loops and graph updates. Default: 1000. */
+    maxExecutions?: number;
 }
 export interface ExecutionError {
-    code: "MODEL_ERROR" | "INVALID_RESPONSE" | "DECISION_REQUIRED" | "INVALID_DECISION" | "NODE_TIMEOUT" | "GRAPH_TIMEOUT" | "CANCELLED" | "MERGE_FAILED" | "CLEANUP_FAILED";
+    code: "MODEL_ERROR" | "INVALID_RESPONSE" | "DECISION_REQUIRED" | "INVALID_DECISION" | "NODE_TIMEOUT" | "GRAPH_TIMEOUT" | "CANCELLED" | "MERGE_FAILED" | "CLEANUP_FAILED" | "CHECKPOINT_FAILED" | "WORKSPACE_MERGE_REQUIRED" | "EXECUTION_LIMIT" | "LOOP_LIMIT" | "REQUIRED_NODE_FAILED" | "SCHEDULING_ERROR";
     message: string;
 }
 /** Output is absent if no valid response was received; status determines success. */
 export interface NodeResult extends Partial<NodeOutput> {
     id: string;
+    executionId?: string;
     status: NodeStatus;
     usage?: TokenUsage;
     startedAt?: number;
     finishedAt?: number;
     latencyMs?: number;
     error?: ExecutionError;
-    skipReason?: "inactive" | "upstream_failed" | "graph_timeout" | "cancelled";
+    skipReason?: "inactive" | "upstream_failed" | "graph_timeout" | "cancelled" | "run_failed";
     workspace?: NodeWorkspace;
 }
 export interface BraidResult {
     status: "completed" | "failed";
-    /** Completed nodes with no active outgoing edges in this execution. */
+    /** Latest output per node among completed, unconsumed executions; exact IDs are in terminalExecutionIds. */
     terminalOutputs: Record<string, NodeOutput>;
-    /** Immutable execution log, including graph construction and runtime handoffs. */
+    /** Immutable execution log, including graph revisions and runtime handoffs. */
     events: readonly ExecutionEvent[];
     nodes: Record<string, NodeResult>;
+    executions: Record<string, NodeExecution>;
+    terminalExecutionIds: string[];
+    revision: number;
     workspaces?: Record<string, NodeWorkspace>;
     error?: ExecutionError;
     metadata: ExecutionContext & {
@@ -240,3 +320,42 @@ export interface BraidResult {
         usageReportedNodes: number;
     };
 }
+/** One immutable invocation definition, with a result updated only by that invocation. */
+export interface NodeExecution extends NodeResult {
+    executionId: string;
+    node: BraidNode;
+    revision: number;
+    predecessorExecutionIds: string[];
+    loopId?: string;
+    iteration?: number;
+}
+export interface GraphUpdate {
+    expectedRevision: number;
+    upsertNodes?: readonly BraidInputNode[];
+    removeNodeIds?: readonly string[];
+    addEdges?: readonly Edge[];
+    removeEdges?: readonly Edge[];
+    promptTemplates?: Readonly<Record<string, string>>;
+    loops?: readonly LoopDefinition[];
+    /** Resume these completed executions atomically with this update. */
+    resume?: readonly string[];
+}
+export interface BraidSnapshot {
+    runId: string;
+    status: "running" | "waiting" | "finalizing" | "completed" | "failed";
+    revision: number;
+    graph: BraidInput;
+    nodes: Record<string, NodeResult>;
+    executions: Record<string, NodeExecution>;
+    pausedExecutionIds: string[];
+    /** Present as soon as a run-wide failure or cancellation starts draining work. */
+    error?: ExecutionError;
+}
+export interface BraidRun {
+    runId: string;
+    result: Promise<BraidResult>;
+    snapshot(): BraidSnapshot;
+    update(update: GraphUpdate): BraidSnapshot;
+    resume(executionIds: readonly string[], expectedRevision: number): BraidSnapshot;
+    cancel(): void;
+}

package/dist/validate.d.ts

@@ -1,4 +1,4 @@
-import type { BraidInput, BraidNode, Edge } from "./types.js";
+import type { BraidInput, BraidNode, Edge, LoopDefinition } from "./types.js";
 export declare class GraphValidationError extends Error {
     constructor(message: string);
 }
@@ -10,6 +10,12 @@ export interface Graph {
     edges: Edge[];
     incoming: Map<string, Edge[]>;
     outgoing: Map<string, Edge[]>;
+    loops: Map<string, CompiledLoop>;
+    membership: Map<string, string>;
+}
+export interface CompiledLoop extends LoopDefinition {
+    feedback: Edge;
+    members: Set<string>;
 }
 /** Throws before execution for malformed graphs, references, choices, or cycles. */
 export declare function validateGraph(input: BraidInput): void;

package/dist/validate.js

@@ -19,35 +19,103 @@ function fields(value, allowed, label) {
         requireValid(allowed.includes(key), `${label}: unsupported field '${key}'`);
     }
 }
+function compileTemplates(value) {
+    const templates = new Map();
+    if (value === undefined)
+        return templates;
+    requireValid(isRecord(value), "Graph promptTemplates must be an object");
+    for (const [name, source] of Object.entries(value)) {
+        requireValid(text(name), "Prompt template name must be a non-empty string");
+        const label = `Prompt template '${name}'`;
+        requireValid(text(source), `${label} must be a non-empty string`);
+        const parts = [];
+        const variables = new Set();
+        let offset = 0;
+        while (offset < source.length) {
+            const open = source.indexOf("{{", offset);
+            const close = source.indexOf("}}", offset);
+            requireValid(close === -1 || (open !== -1 && close > open), `${label} has an unmatched '}}'`);
+            if (open === -1) {
+                parts.push(source.slice(offset));
+                break;
+            }
+            requireValid(close !== -1, `${label} has an unclosed '{{'`);
+            const variable = source.slice(open + 2, close).trim();
+            requireValid(/^[A-Za-z_][A-Za-z0-9_]*$/.test(variable), `${label} has invalid variable '${variable}'`);
+            parts.push(source.slice(offset, open), { variable });
+            variables.add(variable);
+            offset = close + 2;
+        }
+        templates.set(name, { parts, variables });
+    }
+    return templates;
+}
+function renderPrompt(value, nodeId, templates) {
+    const nodeLabel = `Node '${nodeId}'`;
+    if (typeof value === "string") {
+        requireValid(text(value), `${nodeLabel} needs a non-empty prompt`);
+        return value;
+    }
+    requireValid(isRecord(value), `${nodeLabel} needs a non-empty prompt or template reference`);
+    fields(value, ["template", "variables"], `${nodeLabel} prompt`);
+    requireValid(text(value.template), `${nodeLabel} prompt needs a non-empty template reference`);
+    const label = `${nodeLabel} prompt template '${value.template}'`;
+    const template = templates.get(value.template);
+    requireValid(template, `${label} is unknown`);
+    requireValid(isRecord(value.variables), `${label} variables must be an object`);
+    const variables = new Map();
+    for (const [name, variable] of Object.entries(value.variables)) {
+        requireValid(typeof variable === "string", `${label} variable '${name}' must be a string`);
+        requireValid(template.variables.has(name), `${label} has unused variable '${name}'`);
+        variables.set(name, variable);
+    }
+    for (const name of template.variables) {
+        requireValid(variables.has(name), `${label} is missing variable '${name}'`);
+    }
+    // One pass over the parsed template: inserted values are never parsed or evaluated.
+    const rendered = template.parts.map(part => typeof part === "string" ? part : variables.get(part.variable)).join("");
+    requireValid(text(rendered), `${label} renders an empty prompt`);
+    return rendered;
+}
 /** Throws before execution for malformed graphs, references, choices, or cycles. */
 export function validateGraph(input) {
     compileGraph(input);
 }
 export function compileGraph(input) {
     requireValid(isRecord(input), "Graph must be an object");
-    fields(input, ["goal", "nodes", "edges"], "Graph");
+    fields(input, ["goal", "nodes", "edges", "promptTemplates", "loops"], "Graph");
     requireValid(text(input.goal), "Graph goal must be a non-empty string");
     requireValid(Array.isArray(input.nodes) && input.nodes.length > 0, "Graph needs at least one node");
     requireValid(Array.isArray(input.edges), "Graph edges must be an array");
+    const templates = compileTemplates(input.promptTemplates);
     const byId = new Map();
     for (const node of input.nodes) {
         requireValid(isRecord(node), "Node must be an object");
-        requireValid(node.type === "execute" || node.type === "decision" || node.type === "merge", "Unknown node type");
+        requireValid(node.type === "execute" || node.type === "decision" || (node.type === "merge" || node.type === "integrate"), "Unknown node type");
         fields(node, node.type === "decision"
-            ? ["type", "id", "prompt", "model", "choices", "workspace"]
+            ? ["type", "id", "prompt", "model", "choices", "workspace", "notifyOnCompletion", "requireSuccess", "pauseAfter"]
             : node.type === "execute"
-                ? ["type", "id", "prompt", "model", "workspace"]
-                : ["type", "id", "prompt", "model"], "Node");
+                ? ["type", "id", "prompt", "model", "workspace", "notifyOnCompletion", "requireSuccess", "pauseAfter"]
+                : ["type", "id", "prompt", "model", "notifyOnCompletion", "requireSuccess", "pauseAfter"], "Node");
         requireValid(text(node.id), "Node id must be a non-empty string");
         requireValid(!byId.has(node.id), `Duplicate node id '${node.id}'`);
-        requireValid(text(node.prompt) || (node.type === "merge" && node.prompt === undefined), `Node '${node.id}' needs a non-empty prompt`);
+        const prompt = (node.type === "merge" || node.type === "integrate") && node.prompt === undefined
+            ? (node.type === "merge" ? "Merge selected predecessor results into this new isolated worktree. Resolve conflicts and account for every source with finish_merge." : "Integrate selected predecessor results into the invoking checkout. Preserve user changes and account for every source with finish_merge.")
+            : renderPrompt(node.prompt, node.id, templates);
         requireValid(node.model === undefined || text(node.model), `Invalid model on '${node.id}'`);
-        const workspace = node.type === "merge" ? undefined : node.workspace;
+        const workspace = (node.type === "merge" || node.type === "integrate") ? undefined : node.workspace;
+        requireValid(node.notifyOnCompletion === undefined || typeof node.notifyOnCompletion === "boolean", `Invalid notifyOnCompletion on '${node.id}': expected a boolean`);
         requireValid(workspace === undefined || workspace === "read-only" || workspace === "worktree", `Invalid workspace on '${node.id}'`);
+        for (const field of ["requireSuccess", "pauseAfter"]) {
+            requireValid(node[field] === undefined || typeof node[field] === "boolean", `Invalid ${field} on '${node.id}': expected a boolean`);
+        }
         const common = {
             id: node.id,
-            prompt: node.prompt ?? "Review all predecessor changes, decide how to integrate them into the source repository, and account for every source with finish_merge.",
+            prompt,
             ...(node.model !== undefined ? { model: node.model } : {}),
+            ...(node.notifyOnCompletion !== undefined ? { notifyOnCompletion: node.notifyOnCompletion } : {}),
+            ...(node.requireSuccess !== undefined ? { requireSuccess: node.requireSuccess } : {}),
+            ...(node.pauseAfter !== undefined ? { pauseAfter: node.pauseAfter } : {}),
             ...(workspace !== undefined ? { workspace } : {}),
         };
         if (node.type === "decision") {
@@ -71,39 +139,94 @@ export function compileGraph(input) {
     }
     for (const edge of input.edges) {
         requireValid(isRecord(edge), "Edge must be an object");
-        fields(edge, ["from", "to", "choice"], "Edge");
-        requireValid(text(edge.from) && byId.has(edge.from), `Missing source node '${edge.from}'`);
+        fields(edge, ["from", "to", "choice", "feedback", "executionId"], "Edge");
+        requireValid(edge.executionId === undefined || text(edge.executionId), "Invalid edge executionId");
+        requireValid(edge.feedback === undefined || text(edge.feedback), "Invalid edge feedback");
+        requireValid(!edge.feedback || !edge.executionId, "Feedback cannot pin an execution");
+        requireValid(text(edge.from) && (byId.has(edge.from) || edge.executionId !== undefined), `Missing source node '${edge.from}'`);
         requireValid(text(edge.to) && byId.has(edge.to), `Missing target node '${edge.to}'`);
-        if (edge.choice !== undefined) {
+        requireValid(edge.choice === undefined || text(edge.choice), "Invalid edge choice");
+        if (edge.choice !== undefined && edge.executionId === undefined) {
             const source = byId.get(edge.from);
             requireValid(source.type === "decision", `Choice edge from non-decision '${edge.from}'`);
             requireValid(text(edge.choice) && source.choices.includes(edge.choice), `Undeclared edge choice '${edge.choice}' on '${edge.from}'`);
         }
-        const key = JSON.stringify([edge.from, edge.to, edge.choice ?? null]);
+        const key = JSON.stringify([edge.from, edge.to, edge.choice ?? null, edge.feedback ?? null, edge.executionId ?? null]);
         requireValid(!seen.has(key), `Duplicate edge '${edge.from}' -> '${edge.to}'`);
         seen.add(key);
         const snapshot = {
             from: edge.from,
             to: edge.to,
             ...(edge.choice !== undefined ? { choice: edge.choice } : {}),
+            ...(edge.feedback !== undefined ? { feedback: edge.feedback } : {}),
+            ...(edge.executionId !== undefined ? { executionId: edge.executionId } : {}),
         };
         edges.push(snapshot);
         incoming.get(edge.to).push(snapshot);
-        outgoing.get(edge.from).push(snapshot);
+        outgoing.get(edge.from)?.push(snapshot);
     }
     // Kahn's algorithm is iterative, including for very deep graphs.
     const nodes = [...byId.values()];
-    const remaining = new Map(nodes.map((node) => [node.id, incoming.get(node.id).length]));
+    const remaining = new Map(nodes.map((node) => [node.id, incoming.get(node.id).filter(edge => !edge.feedback && !edge.executionId).length]));
     const topologicalOrder = nodes.filter((node) => remaining.get(node.id) === 0);
     for (let i = 0; i < topologicalOrder.length; i++) {
         for (const edge of outgoing.get(topologicalOrder[i].id)) {
+            if (edge.feedback || edge.executionId)
+                continue;
             const count = remaining.get(edge.to) - 1;
             remaining.set(edge.to, count);
             if (count === 0)
                 topologicalOrder.push(byId.get(edge.to));
         }
     }
-    requireValid(topologicalOrder.length === nodes.length, "Graph contains a cycle");
+    requireValid(topologicalOrder.length === nodes.length, "Graph contains a cycle without a declared feedback edge");
+    const loops = new Map();
+    const membership = new Map();
+    requireValid(input.loops === undefined || Array.isArray(input.loops), "Graph loops must be an array");
+    const reachable = (start, reverse = false) => {
+        const visited = new Set();
+        const queue = [start];
+        while (queue.length) {
+            const id = queue.pop();
+            if (visited.has(id))
+                continue;
+            visited.add(id);
+            for (const edge of (reverse ? incoming : outgoing).get(id) ?? []) {
+                if (!edge.feedback && !edge.executionId)
+                    queue.push(reverse ? edge.from : edge.to);
+            }
+        }
+        return visited;
+    };
+    for (const loop of input.loops ?? []) {
+        requireValid(isRecord(loop), "Loop must be an object");
+        fields(loop, ["id", "entry", "maxIterations"], "Loop");
+        requireValid(text(loop.id) && !loops.has(loop.id), "Loop ids must be non-empty and unique");
+        requireValid(text(loop.entry) && byId.has(loop.entry), `Unknown loop entry '${loop.entry}'`);
+        requireValid(typeof loop.maxIterations === "number" && Number.isSafeInteger(loop.maxIterations) && loop.maxIterations > 0, `Loop '${loop.id}' needs a positive maxIterations`);
+        const feedback = edges.filter(edge => edge.feedback === loop.id);
+        requireValid(feedback.length === 1, `Loop '${loop.id}' needs exactly one feedback edge`);
+        const back = feedback[0];
+        const decision = byId.get(back.from);
+        requireValid(back.to === loop.entry && decision.type === "decision" && back.choice !== undefined, `Loop '${loop.id}' feedback must route a decision choice to its entry`);
+        requireValid(decision.choices.some(choice => choice !== back.choice), `Loop '${loop.id}' needs an exit choice`);
+        const ancestors = reachable(back.from, true);
+        const members = new Set([...reachable(loop.entry)].filter(id => ancestors.has(id)));
+        requireValid(members.has(loop.entry) && members.has(back.from), `Loop '${loop.id}' entry must reach its feedback decision`);
+        for (const id of members) {
+            requireValid(!membership.has(id), "Nested or overlapping loops are unsupported");
+            membership.set(id, loop.id);
+        }
+        for (const edge of edges) {
+            if (edge.feedback || edge.executionId)
+                continue;
+            requireValid(!(!members.has(edge.from) && members.has(edge.to) && edge.to !== loop.entry), `Loop '${loop.id}' has multiple entries`);
+            requireValid(!(members.has(edge.from) && !members.has(edge.to) && edge.from !== back.from), `Loop '${loop.id}' must exit through its feedback decision`);
+        }
+        loops.set(loop.id, { id: loop.id, entry: loop.entry, maxIterations: loop.maxIterations, feedback: back, members });
+    }
+    for (const edge of edges)
+        requireValid(!edge.feedback || loops.has(edge.feedback), `Unknown feedback loop '${edge.feedback}'`);
     return {
         goal: input.goal,
         nodes,
@@ -111,5 +234,7 @@ export function compileGraph(input) {
         edges,
         incoming,
         outgoing,
+        loops,
+        membership,
     };
 }

package/dist/workspaces.d.ts

@@ -1,5 +1,5 @@
 import type { GitResult, MergeDisposition, MergeSource, ModelRequest, NodeWorkspace, SourceCheckoutStatus } from "./types.js";
-/** Writable workers share a snapshot; explicit read-only workers inspect the live cwd. */
+/** Each execution owns a fresh worktree derived from immutable predecessor checkpoints. */
 export declare class GitWorkspaces {
     private readonly cwd;
     private readonly onWorkspace?;
@@ -7,17 +7,23 @@ export declare class GitWorkspaces {
     private records;
     private locations;
     private allocated;
+    private mergeParents;
     constructor(cwd: string, onWorkspace?: ((workspace: NodeWorkspace) => void) | undefined);
     private report;
     private sourceRoot;
     private snapshot;
-    prepare(request: ModelRequest): Promise<NodeWorkspace>;
+    /** Freeze the job's root snapshot before any invocation can write to the checkout. */
+    initialize(runId: string): Promise<void>;
+    private id;
+    private inputCommit;
+    prepare(request: ModelRequest, merge?: boolean): Promise<NodeWorkspace>;
+    /** Seal before releasing any downstream execution, including failures with partial writes. */
+    seal(request: ModelRequest): Promise<void>;
+    private sealCheckpoint;
     all(): Record<string, NodeWorkspace>;
     pending(): string[];
     /** Checkpoint every file, including ignored node outputs, before releasing a worktree. */
     private checkpoint;
-    /** Run only after declared nodes settle, so consumers retain their source paths. */
-    discardUnchanged(): Promise<void>;
     private release;
     /** Only archive/remove here. Choosing merge/cherry-pick/apply always belongs to the agent. */
     archivePending(reason: string): Promise<void>;
@@ -30,3 +36,7 @@ export declare class GitWorkspaces {
         complete: (success: boolean) => Promise<void>;
     }>;
 }
+export declare class WorkspaceInputError extends Error {
+}
+export declare class WorkspaceCheckpointError extends Error {
+}