Braid v0.2.0

Braid 0.2.0 adds bounded refinement loops, live graph updates, reusable prompt templates, and intermediate completion reminders. This is a breaking release; review the migration guidance before upgrading existing graphs.

Features

• Bounded loops and live execution control. Separate editable node definitions from captured execution instances. Use startBraid for revision-checked graph updates, pauseAfter gates, and atomic update/resume; loops receive finite iteration limits and fresh worktrees per visit. Pi adds braid_update, braid_resume, execution-specific result retrieval, iteration-aware reminders, and live topology updates (#35) — @Epsirom.
• Graph-local prompt templates. Define shared promptTemplates once and reference them with explicit string variables. Core validates and expands literal {{name}} placeholders before execution; Pi accepts the same compact input and runners continue to receive rendered strings (#33) — @Epsirom.
• Opt-in node completion reminders. Set notifyOnCompletion: true for selected intermediate outputs or failures. Pi acknowledges delivery, retries dropped reminders, and exposes full results through braid_status({jobId, nodeId}) or exact executionId retrieval. Skipped nodes stay silent and whole-job reminders remain enabled (#34, #35) — @Epsirom.

Breaking changes and migration

The execution/workspace changes below come from #35 — @Epsirom:

• Replace source-checkout merge nodes with integrate. The new merge combines inputs in a fresh isolated worktree. Add explicit integration nodes where a graph previously relied on automatic final integration.
• Treat nodeId as a definition identity and use executions[executionId] for historical instances. Workspace lookups and finish_merge dispositions now use execution IDs; source checkpoints remain reusable until cleanup.
• Read-only Git executions inspect isolated predecessor snapshots instead of the live source checkout.
• Failures are optional by default. Set requireSuccess: true where a failure must abort siblings and fail the job after writes and cleanup drain.
• Handle repeated execution events and new revision/loop/gate events. Set finite loop limits and maxExecutions (default 1000); deadlines and execution budgets span live updates and paused gates.

Full 0.1 → 0.2 migration guide · Execution-control contract.

Maintenance

• Refresh package/repository metadata, discovery keywords, documentation, and roadmap for the 0.2 execution contract (#36) — @Epsirom.
• Update @types/node from 22.20.2 to 22.20.4 (#17) — @dependabot[bot].
• Standardize PR/author credits and first-time contributor acknowledgements, backfill historical release notes, and prepare 0.2.0 documentation (#39) — @Epsirom.

New Contributors

No first-time human contributors in this release. Thanks to everyone who contributed to earlier releases as well.

Installation and validation

Both packages use 0.2.0; Pi installs the exact matching core dependency. Core requires Node.js 22+; Pi requires Node.js 22.19+ and remains tested against Pi 0.87.1.

npm install @chrok/braid@0.2.0
pi install npm:@chrok/pi-braid@0.2.0

Validation: 218 core tests, 66 Pi tests, strict type checks, offline examples, isolated Pi-only installation/public imports/declarations/background execution, package-content inspections, CodeQL, and the Linux/macOS/Windows CI matrix on Node 22/24. Pi host compatibility tests use an in-memory provider; paid live provider scenarios were not rerun for this release.

See the changelog and full comparison.