@chrok/braid 0.1.3 → 0.2.1

package/docs/execution-control.md

@@ -0,0 +1,160 @@
+# Execution control
+
+Braid 0.2 separates mutable node definitions from execution instances. This is a
+breaking change from 0.1, covering bounded loops (#30) and live graph updates (#31).
+
+## Definitions and instances
+
+A node is a reusable definition identified by `id`. An execution has a unique
+`executionId`, a captured node definition, graph `revision`, predecessor execution
+IDs, and, within a loop, `loopId` and a one-based `iteration`. Editing or deleting
+a definition never changes or cancels an already admitted execution. Failure,
+notification, pause, model, prompt, and workspace policies are captured at admission.
+
+`result.executions` retains every instance, including earlier rounds and deleted
+nodes. `result.nodes` is a convenience projection of the latest instance per node.
+Workspace records are keyed by execution ID. `terminalExecutionIds` identifies
+successful instances whose outputs were not consumed by another admitted instance;
+`terminalOutputs` provides their latest outputs keyed by node ID. Failed instances
+remain available separately, even when the overall job completes.
+
+## Structured loops
+
+```ts
+const graph = {
+  goal: "Refine until the review passes",
+  nodes: [
+    { type: "execute", id: "edit", prompt: "Implement the feedback." },
+    { type: "decision", id: "review", prompt: "Review the result.",
+      choices: ["again", "done"], workspace: "read-only" },
+    { type: "integrate", id: "apply" },
+  ],
+  loops: [{ id: "refinement", entry: "edit", maxIterations: 3 }],
+  edges: [
+    { from: "edit", to: "review" },
+    { from: "review", to: "edit", choice: "again", feedback: "refinement" },
+    { from: "review", to: "apply", choice: "done" },
+  ],
+};
+```
+
+Each loop declares one entry, one decision feedback edge, and a finite positive
+iteration limit. Ignoring feedback and historical references, the graph must be
+acyclic. Loop bodies may fork and join; external edges enter only through the
+entry and leave only through the feedback decision. Nested/overlapping loops and
+arbitrary cycles are rejected. Sequential and independent loops are supported.
+
+The first round uses external predecessors or the job's root snapshot. A feedback
+choice creates another round only after all admitted instances in the current
+round have settled and their pause gates have been released. The next entry also
+receives the previous feedback execution. External inputs remain available in
+subsequent rounds. Exits wait for the loop to finish and use the final round.
+Choosing feedback at `maxIterations` fails the job with `LOOP_LIMIT`.
+
+Loops do not overlap their own rounds. Live updates can change definitions,
+edges, and loop topology during an iteration; no boundary pause is required.
+Already admitted instances drain normally. Updates do not replay a completed
+activation just because its definition or incoming edges changed. Use a new node
+ID for new work outside a subsequent loop round.
+
+## Live updates and gates
+
+```ts
+import { startBraid } from "@chrok/braid";
+
+const run = startBraid({
+  goal: "Inspect, then decide the next steps",
+  nodes: [{ type: "execute", id: "inspect", prompt: "Find the problem.", pauseAfter: true }],
+  edges: [],
+}, { runner });
+
+// After execution_paused (or after obtaining a snapshot from your host):
+const state = run.snapshot();
+const executionId = state.pausedExecutionIds[0];
+run.update({
+  expectedRevision: state.revision,
+  upsertNodes: [{ type: "execute", id: "fix", prompt: "Implement the fix." }],
+  addEdges: [{ from: "inspect", to: "fix", executionId }],
+  resume: [executionId],
+});
+const result = await run.result;
+```
+
+`startBraid` returns synchronously with `runId`, `result`, `snapshot()`,
+`update(patch)`, `resume(executionIds, expectedRevision)`, and `cancel()`.
+`braid(input, options)` is the convenience API for awaiting the result.
+
+Updates require the current `expectedRevision` and commit atomically. A successful
+update increments the graph revision once. A stale revision or invalid candidate
+changes nothing, including pause gates. `upsertNodes` replaces whole definitions;
+`removeNodeIds` also removes incident edges. `addEdges` and `removeEdges` use full
+edge identities, including choice, feedback, and execution ID. `promptTemplates`
+and `loops` replace their respective collections when supplied. Template edits
+are rendered for future admissions; running prompts remain unchanged.
+
+Completion routes through the latest graph. If A is running and A→B is replaced
+with A→C, A's completion can admit C. A previously admitted B continues with its
+captured inputs. A historical dependency pins `edge.executionId` and matching
+`from` to a settled execution, even if its definition was removed. Initial
+submissions cannot reference history from another job.
+
+`pauseAfter` holds an execution's outgoing scheduling and keeps the job alive,
+even at a leaf. Independent branches continue. Pi sends a pause reminder;
+`notifyOnCompletion` alone only sends a reminder. Resume specific execution IDs,
+either on its own or in the same transaction as a graph update. Removing a paused
+node definition does not discard its gate: explicitly resume or cancel it.
+
+A job accepts updates while running or waiting. Once no work or gates remain,
+it enters finalization and rejects further updates. Completed jobs cannot be
+reopened. These are in-memory controls; there is no restart or crash recovery of
+the scheduler itself.
+
+## Workspaces and merge operations
+
+Every execution gets a new Git worktree, including read-only executions and
+later loop visits. Root worktrees derive from one initial snapshot; successors
+derive from predecessor checkpoints. Read-only is a capability restriction,
+not a live view of the caller. Outside Git, filesystem tools remain read-only.
+
+If inputs have identical trees, or one checkpoint contains all the others in its
+ancestry, an ordinary worker can use that snapshot. Independent changed inputs
+require an explicit `merge`; the worker fails with `WORKSPACE_MERGE_REQUIRED`
+instead of silently selecting or combining them. All active predecessors still
+provide text/error context.
+
+| Type | Target | Result |
+| --- | --- | --- |
+| `merge` | New isolated worktree based on the initial job snapshot | Selected predecessor changes combined into a reusable checkpoint |
+| `integrate` | Invoking source checkout / working branch | Selected changes applied to the caller and captured as a checkpoint |
+
+Neither operation applies changes automatically. The runner chooses Git/file
+operations, resolves conflicts, and calls `finish_merge` once with one
+`{ executionId, disposition, reason }` per source. Sources are immutable and
+reusable by multiple consumers. Dispositions are recorded on the target
+workspace; source worktrees remain available until job cleanup. Integration
+captures a `backupRef` first and serializes source-checkout access within the
+process. It must preserve unrelated staged, unstaged, and untracked caller edits.
+
+There is no implicit final integration. Each instance is checkpointed before
+successors are released, including partial work on optional failure. Finalization
+archives/removes owned worktrees while retaining checkpoint refs. Cancelled or
+failed integration may leave partial source edits or conflicts for inspection;
+it does not reset the caller's checkout.
+
+## Failure and budgets
+
+`requireSuccess` defaults to false. Optional failures keep their errors and partial
+artifacts; unconditional successors can recover. A failed decision never activates
+a choice edge. A job can complete with failed optional executions.
+
+A captured `requireSuccess: true` failure immediately stops admission, aborts
+running siblings, waits for tracked writes and cleanup, and fails the job with
+`REQUIRED_NODE_FAILED`. Editing the definition's policy later has no effect on
+that instance. Infrastructure, checkpoint/cleanup, cancellation, graph deadline,
+loop limit, and total execution limit failures always fail the job.
+
+`maxExecutions` defaults to 1000 and must be a positive safe integer. It bounds
+all materialized execution records, including skipped branches, across all rounds
+and graph updates. `maxIterations` bounds each loop. The graph deadline includes
+waiting at gates and is never reset by an update or resume. Usage sums all
+instances once; Pi only claims job usage on the first terminal job retrieval.

package/docs/releasing.md

@@ -4,6 +4,34 @@ Core and Pi are separate public npm packages built from one commit. Both use the
 same version. The core has no runtime dependencies. Pi declares an exact
 `@chrok/braid` dependency and includes only its own compiled integration code.
 
+## Registry and source association
+
+The public packages are [@chrok/braid](https://www.npmjs.com/package/@chrok/braid)
+and [@chrok/pi-braid](https://www.npmjs.com/package/@chrok/pi-braid) on npmjs.
+Keep `publishConfig.registry` set to `https://registry.npmjs.org`. Both manifests
+link to `Epsirom/braid`; Pi's `repository.directory` is `integrations/pi`.
+The repository About website and README badges provide the reverse links.
+GitHub Packages is a separate registry and is not a mirror in this release flow.
+
+Package descriptions, keywords, source links, and README content are uploaded
+with the package release. A commit on `main` does not update the published npm
+metadata. Keep development-version notices accurate until publication, and link
+users of the current npm release to its tagged documentation.
+
+To inspect the public release without npm account credentials:
+
+```sh
+npm view @chrok/braid dist-tags description repository homepage gitHead dist.attestations --json
+npm view @chrok/pi-braid dist-tags description repository homepage gitHead dist.attestations --json
+```
+
+For a release, query the exact `@X.Y.Z` versions too. Confirm both `gitHead`
+values match the release commit, the source links point to this repository, and
+provenance identifies this repository's release workflow. The successful
+[Publish runs](https://github.com/Epsirom/braid/actions/workflows/release.yml)
+and public npm attestations provide release evidence; inspecting or changing
+the trusted-publisher account settings requires npm authentication.
+
 ## Prepare a release
 
 Version tags (`v*`) cannot be moved or deleted. New GitHub releases are immutable:
@@ -18,10 +46,47 @@ corrections require a new version. See [repository settings](repository-settings
    licenses, and Pi registration in a temporary consumer outside the checkout.
    A temporary local registry serves the unpublished core tarball; installing
    only the Pi tarball must fetch core transitively through its version dependency.
-3. Update the changelog and supported Pi version. Commit and review the changes;
+3. Update the changelog, migration guidance, package descriptions/keywords, and
+   supported Pi version. Reconcile README/Pi development notices and ROADMAP
+   status with the release being prepared; mark publication complete only after
+   both packages are available. Commit and review the changes;
    require the CI matrix to pass before tagging that commit `vX.Y.Z`.
 4. Inspect `npm pack --dry-run` and `npm pack --dry-run` from `integrations/pi`.
    `prepack` rebuilds each package. Never publish stale prebuilt output.
+5. Prepare the GitHub release draft using the release-note policy below. After
+   publishing, verify both registry versions, `latest` tags, provenance, and a
+   clean install before reporting the release complete.
+
+## Release notes and contributor credit
+
+Every release must describe user-visible features, fixes, and breaking changes
+in both `CHANGELOG.md` and the GitHub release notes. For each item, link the
+implementing pull request and credit its author by GitHub handle, for example:
+`Add graph-local prompt templates ([#33](https://github.com/Epsirom/braid/pull/33)) — @Epsirom.`
+Use the PR author, not the person who merged it. Issue links can add context but
+do not replace PR links. Credit each relevant PR/author when an item combines
+several contributions; credit direct-commit authors with commit links if no PR
+exists. Keep dependency and release maintenance separate from feature summaries.
+
+Compare the previous release tag with the exact candidate commit. Inspect the
+merged PRs in that range and their authors; GitHub's generated release notes
+are a useful starting point, not a substitute for checking the actual changes.
+Keep the changelog and GitHub notes consistent, include migration guidance for
+breaking changes, and link the full tag-to-tag comparison.
+
+Mark a human author's first contribution to this repository with
+`**First-time contributor**` next to their credit. Also add a **New Contributors**
+section that thanks them and links their first included PR (or direct commit).
+Verify this against all earlier merged PRs and commit history through the
+previous release, not just the latest release notes. An existing contributor's
+first PR in this release is not their first repository contribution. Exclude
+bot accounts from newcomer thanks, while retaining their maintenance credits.
+If there are no first-time human contributors, say so in that section; do not
+infer newcomer status from a missing credit in an older release.
+
+Before publishing the draft, check that every feature/fix has its implementing
+PR link and author, newcomer labels match the history, and version, date,
+comparison, and migration links refer to the release being published.
 
 ## First publication
 

package/docs/repository-settings.md

@@ -6,6 +6,40 @@ copies of the API payloads; committing a change to them does not apply it to
 GitHub automatically. Update the existing ruleset in Settings or through the
 REST API after reviewing a policy change, then verify the live settings.
 
+## Repository identity and npm links
+
+The GitHub About section describes the current `main` capabilities:
+
+> TypeScript runtime for LLM agent graphs with bounded loops, live updates,
+> isolated Git worktrees, and explicit integration. Framework-agnostic core,
+> OpenAI-compatible runner, and Pi extension.
+
+The repository website points to
+[@chrok/braid on npm](https://www.npmjs.com/package/@chrok/braid). The root README
+links both published packages and displays their npm version badges. Topics are
+`llm`, `ai-agents`, `agent-runtime`, `agent-orchestration`, `multi-agent`,
+`graph-execution`, `bounded-loops`, `git-worktree`, `parallel-execution`,
+`typescript`, `nodejs`, `openai-compatible`, and `pi-package`.
+The old DAG-only and workflow-engine labels do not describe the 0.2 scope.
+
+Both packages publish to `https://registry.npmjs.org`:
+
+| Package | Repository location |
+| --- | --- |
+| [@chrok/braid](https://www.npmjs.com/package/@chrok/braid) | Repository root |
+| [@chrok/pi-braid](https://www.npmjs.com/package/@chrok/pi-braid) | `integrations/pi` |
+
+Each manifest declares `repository`, `homepage`, and `bugs`; Pi additionally sets
+`repository.directory`. These fields link npm pages back to the correct source
+and issue tracker. Descriptions and keywords take effect on npm when a new
+version is published; editing `main` does not change existing registry versions.
+
+GitHub's **Packages** section represents its separate registry. It does not list
+an npmjs package just because that package points to this repository. The project
+uses npmjs only; no GitHub Packages mirror or additional package scope is
+maintained. See [GitHub's npm registry guide](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry)
+and the [release guide](releasing.md#registry-and-source-association).
+
 ## Main branch
 
 [Protect main](https://github.com/Epsirom/braid/rules/24072177) applies to `main`,

package/docs/resource-limits.md

@@ -1,16 +1,24 @@
 # Resource limits and deployment responsibility
 
 Braid targets small reasoning graphs. Graph size, prompt/output size, event-log
-size, and the number of simultaneous graph submissions have no hard cap in 0.1.
+size, and the number of simultaneous graph submissions have no hard cap. Total materialized executions, including skipped branches,
+are capped at 1000 by default; loops also require a finite iteration limit.
 The scheduler rescans the graph as work settles. Consult the
 [benchmark](benchmark.md) for measured local overhead rather than treating the
 validator's deep-graph tests as a production capacity guarantee.
 
+Submission-local prompt templates reduce graph/tool-call argument size, not
+worker context size. Core expands them before execution and checks rendered
+prompts are non-empty. There is no raw or rendered prompt length/token cap;
+hosts imposing their own size budgets must account for expanded prompts as
+well as the compact definition.
+
 | Control | Core default | Pi default |
 | --- | --- | --- |
 | Active runtime-managed invocations per graph | 4 | 4 |
+| Materialized executions across loops/updates | 1000 (`maxExecutions`) | 1000 (`maxExecutions`) |
 | Node timeout (starts at admission) | 60 seconds | Unlimited |
-| Graph timeout (includes queueing) | 5 minutes | Unlimited |
+| Graph timeout (includes queueing and paused gates) | 5 minutes | Unlimited |
 | Caller cancellation | `AbortSignal` | `braid_cancel` / panel `c` |
 | Worker tool loop | Decision continuation / merge Git-tool loop, bounded by deadlines | Unlimited by default; optional `maxToolRounds` and `maxToolCalls` |
 | Result preview | Full result | 50 KB / 2,000 lines, then temporary full-result file |
@@ -43,9 +51,9 @@ after exporting needed results. Reloading also cancels outstanding work.
 
 Git worktree preparation, checkpointing, tracked writes, and cleanup add disk,
 Git-process, and elapsed-time overhead. Cleanup may extend wall time beyond a
-model deadline. Automatically appended merge agents are additional model calls
-and share the graph's remaining time; unchanged worktrees are released without
-an automatic merge call, but still incur workspace and checkpoint overhead.
+model deadline. Every loop visit creates a new invocation and worktree. Explicit merge/integrate
+nodes count toward the same limits; no final integration call is appended.
+Updates/resumes never reset the graph deadline or execution counter.
 Benchmark results measured outside Git do not include this lifecycle. Recoverable
 refs retain Git objects until removed.
 

package/examples/execution-control.ts

@@ -0,0 +1,38 @@
+import assert from "node:assert/strict";
+import { startBraid, type BraidRun } from "../src/index.js";
+import { inTemporaryDirectory } from "./support.js";
+
+await inTemporaryDirectory(async cwd => {
+  let run!: BraidRun;
+  run = startBraid({
+    goal: "Refine a proposal, then add the next step using its exact result.",
+    nodes: [
+      { type: "execute", id: "draft", prompt: "Refine the proposal." },
+      { type: "decision", id: "review", prompt: "Review it.", choices: ["again", "done"], pauseAfter: true },
+    ],
+    loops: [{ id: "refinement", entry: "draft", maxIterations: 2 }],
+    edges: [{ from: "draft", to: "review" }, { from: "review", to: "draft", choice: "again", feedback: "refinement" }],
+  }, {
+    cwd,
+    runner: async request => {
+      request.decide?.(request.execution.iteration === 2 ? "done" : "again");
+      return { output: `${request.node.id}: iteration ${request.execution.iteration ?? "outside loop"}` };
+    },
+    onEvent: event => {
+      if (event.type !== "execution_paused") return;
+      if (event.iteration === 1) run.resume([event.executionId!], run.snapshot().revision);
+      else run.update({
+        expectedRevision: run.snapshot().revision,
+        upsertNodes: [{ type: "execute", id: "next", prompt: "Summarize the accepted proposal." }],
+        addEdges: [{ from: "review", to: "next", executionId: event.executionId! }],
+        resume: [event.executionId!],
+      });
+    },
+  });
+  const result = await run.result;
+  assert.equal(result.status, "completed");
+  assert.equal(Object.keys(result.executions).length, 5);
+  assert.equal(result.revision, 1);
+  console.log(`${Object.keys(result.executions).length} executions; revision ${result.revision}`);
+  console.log(result.terminalOutputs.next!.output);
+});

package/examples/failure-handling.ts

@@ -20,10 +20,10 @@ const result = await inTemporaryDirectory(cwd => braid({
     return { output: "Known local facts are still available." };
   },
 }));
-assert.equal(result.status, "failed");
+assert.equal(result.status, "completed");
 assert.equal(result.nodes.join!.status, "completed");
 assert.match(result.terminalOutputs.join!.output, /remote: unavailable \(MODEL_ERROR\)/);
 // Unconditional successors receive failed predecessors as explicit error context.
-// A recovered answer does not erase the graph's original failure status.
+// The graph completes while the optional node failure stays in execution history.
 console.log(`status: ${result.status}; join: ${result.nodes.join!.status}`);
 console.log(result.terminalOutputs.join!.output);

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@chrok/braid",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "license": "MIT",
-  "description": "A small, framework-agnostic DAG runtime for isolated model invocations",
+  "description": "TypeScript runtime for LLM agent graphs with bounded loops, live updates, and isolated Git worktrees",
   "type": "module",
   "engines": {
     "node": ">=22"
@@ -33,6 +33,7 @@
     "build": "node scripts/build.mjs",
     "check": "tsc --noEmit",
     "test": "tsx --test test/*.test.ts test/*.test.mjs",
+    "audit:dependencies": "node scripts/audit-dependencies.mjs",
     "demo": "tsx examples/basic.ts",
     "check:pi": "npm run build && npm run check --workspace @chrok/pi-braid",
     "test:pi": "npm run build && npm test --workspace @chrok/pi-braid",
@@ -40,7 +41,7 @@
     "build:pi": "npm run build --workspace @chrok/pi-braid",
     "test:package": "node scripts/package-smoke.mjs",
     "verify": "npm run check && npm test && npm run check:pi && npm run test:pi && npm run examples && npm run test:package",
-    "examples": "tsx examples/basic.ts && tsx examples/code-review.ts && tsx examples/failure-handling.ts && tsx examples/custom-runner.ts",
+    "examples": "tsx examples/basic.ts && tsx examples/code-review.ts && tsx examples/failure-handling.ts && tsx examples/custom-runner.ts && tsx examples/execution-control.ts",
     "bench": "npm run build && node --expose-gc scripts/benchmark.mjs",
     "demo:panel": "tsx scripts/panel-demo.ts",
     "test:pi:live": "npm run build:pi && node integrations/pi/test/live/run.mjs"
@@ -61,9 +62,15 @@
   },
   "keywords": [
     "llm",
+    "ai-agents",
     "agents",
-    "dag",
+    "agent-runtime",
+    "agent-orchestration",
+    "graph",
+    "bounded-loops",
+    "git-worktree",
     "orchestration",
+    "openai-compatible",
     "typescript"
   ],
   "publishConfig": {