compatibility.md

Compatibility and stability

Surface	Supported / tested contract
Core runtime	Node.js 22+, ESM imports, TypeScript declarations, no runtime dependencies
Pi package	Node.js 22.19+, Pi 1.2.0 is the pinned validation target
DSH package	Node.js 22.19+, DeepSeek Harness 0.2.0-rc.2 is the pinned developer-preview host target; native Web panel
CI	Core minimum Node 22.0; all three packages on Node 22.19 and 24 on Linux, macOS, Windows
OpenAI-compatible runner	Chat Completions text and function-tool calls; decisions and merge/integrate nodes require tool calling
Browsers / CommonJS	No standalone core browser build or CommonJS entry point in 0.4; the DSH ./client export is loaded by DSH's Web host

The CI matrix describes configured checks; see actual workflow results for each commit. Offline HTTP fixtures validate the adapter contract. They do not prove that every provider advertising OpenAI compatibility supports its tool schema. Run a small opt-in live test with your chosen provider before relying on it.

Pi's upstream packaging guide requires * peer dependencies for packages the host provides. Braid follows that convention and pins dev dependencies to 1.2.0. The wildcard is a loader/distribution convention, not a claim that every Pi version works. Test the whole Pi suite before updating the supported target. The offline host compatibility test loads the extension into a real Pi session with an in-memory model provider. It checks worker prompt/tool normalization and reminder delivery between model steps after the current tool batch, idle continuation, and acknowledgement, including retrieval of a node output while its job still runs. These fixtures run without provider credentials or network model calls. Version 0.1.0 was originally validated with Pi 0.85.1; the current checkout's pinned validation target is 1.2.0. The Pi npm package declares an exact dependency on the matching @chrok/braid release. npm installs the core automatically; Pi does not bundle another copy of its runtime and does not need a source checkout.

The DSH integration starts at 0.3.1 and pins host peers to DSH 0.2.0-rc.2 because the host is in developer preview. It installs the exact matching core version and uses DSH's model, tool, and job services. Its browser entry is a native DSH Web plugin, not a standalone browser runtime. See the DSH guide for installation and host requirements. Existing 0.3.0 core and Pi users need no migration for 0.3.1.

Git must be installed for workspace execution inside a Git checkout. Non-Git text-only runs do not require Git workspace management.

Migrating from 0.1 to 0.2

Version 0.2 deliberately changed the execution and workspace contracts:

• Replace old source-checkout merge nodes with integrate. The new merge combines inputs in a fresh isolated worktree.
• Add explicit integrate nodes where a graph previously relied on automatic final integration. Runs no longer append __braid_merge__.
• Treat node IDs as definition identities. Read exact historical instances from executions[executionId]; nodes[nodeId] returns the latest instance.
• Key workspace lookups and finish_merge dispositions by executionId. Source workspaces remain reusable; target dispositions records selections.
• Read-only nodes now use isolated predecessor snapshots in Git. They receive checkpoints and cleanup events. All non-Git allocations also report metadata.
• Set requireSuccess: true on nodes whose failures must fail the whole job. Optional failures now retain their error and artifacts while allowing recovery.
• Handle repeated instance events and the new revision/loop/gate events. Use braid_status({jobId, executionId}) for precise Pi result retrieval.
• Set finite maxExecutions (default 1000) and per-loop maxIterations. Deadlines and execution limits span live graph updates and paused gates.

Use startBraid for live updates or pause/resume. Existing braid callers can still await a static graph result. See execution control for the full scheduling and update contract; there is no old-behavior mode.

Graph submissions may include promptTemplates and template-reference prompts. BraidInput.nodes uses BraidInputNode, whose NodePrompt accepts a string or PromptTemplateReference. Code inspecting unrendered input prompts must narrow that union; use satisfies BraidInput to preserve the inferred types of a literal graph. Runner-facing BraidNode and ModelRequest.node retain string prompts, so existing runners need no template support. Rendering happens in core before execution, including for Pi submissions. Older versions reject template inputs.

All node types accept optional notifyOnCompletion: boolean (default false). Core captures this preference per execution; Pi implements parent reminders for successful and failed executions. Skipped nodes do not notify. Pi's optional braid_status nodeId parameter requires jobId and retrieves full intermediate node results. Whole-job queries and reminders remain available. Paused executions send a separate gate reminder; when both preferences are enabled it supplies the single completion reminder for that instance. Cancellation still sends failure reminders for opted-in running instances.

Migrating from 0.2 to 0.3

Version 0.3 changes workspace capabilities and checkpoint contents:

• Writable Pi nodes now receive bash and, on Windows, powershell, allowing dependency installation, builds, and tests within a node. If a graph relies on workers having no shell, set execute/decision nodes to workspace: "read-only" (which also disables file writes), or use a custom runner with the required capability policy. Writable shell access uses host permissions and prompt-based cooperation rules; worktrees are not a security sandbox. Parent extension/MCP tools and their hooks are not inherited.
• Core checkpoints now follow git add --all semantics instead of force-adding every output. Move artifacts needed by successors or for recovery to non-ignored paths, or deliberately track them. Already tracked files, including files explicitly staged with git add --force, remain tracked even when they match ignore rules. Untracked ignored outputs are discarded when worktrees are removed, including after failed or cancelled executions. This applies to every adapter.
• Shell commands must run in the foreground. On POSIX, Braid stops remaining children in the command's process group even on normal completion; Windows uses best-effort process-tree cleanup. Run a temporary server and its checks within one foreground command and clean it up before returning. Detached daemons and external services are not contained by this lifecycle.

No graph field, result shape, or event schema migration is required. Pi now delivers completion/pause reminders after the current assistant response and tool batch, before the next model step, rather than waiting for the entire foreground task to finish. Fetch current status before updating or resuming a paused execution because the reminder describes the state when it was queued.

Migrating from 0.3 to 0.4

Version 0.4 changes how the Pi extension behaves in print and JSON modes:

• Pi print mode (pi -p) and --mode json now stay open until every Braid job reaches a terminal status and its reminder is delivered. No change is needed for CLI use; runs that previously exited early now finish their graphs.
• Pi SDK sessions created with createAgentSession default to extension mode "print", which the extension cannot tell apart from the CLI. In such sessions, session.prompt() now returns only after outstanding Braid jobs drain. Hosts that stay running and rely on reminders starting new runs after the agent settles should bind with another mode, for example session.bindExtensions({ mode: "rpc" }).
• In print and JSON modes, ending a turn while only paused executions remain produces one warning; ending the next turn without resuming them cancels those jobs and sets exit status 1. Resume or cancel paused executions before the parent finishes. --braid-ci-timeout and a final braid_finish failure also exit 1.
• Blocking mode (--braid-blocking, /braid:blocking) still works but is deprecated and will be removed in 0.5.0. Drop it: print and JSON runs now wait for background jobs without blocking each tool call.

No graph field, result shape, or event schema migration is required, and DSH behavior is unchanged.

Versioning

Core, Pi, and DSH release together with matching versions. During 0.x, patch releases preserve documented behavior; breaking API or semantic changes require a minor version bump, a changelog entry, and migration guidance. New optional fields or fixes that restore the documented contract may ship in a patch.

Supported core entry points are @chrok/braid and @chrok/braid/adapters/openai. The root @chrok/braid entry point also exports adapter helpers: formatBudgetReminder, gitToolDefinition, finishMergeToolDefinition, mergeInstructions, parseGitToolArguments, and parseFinishMergeArguments. These helpers share the core's compatibility policy; Git workspace implementation classes remain internal. Internal files and Pi helper classes are not stable public APIs. Documented result/error fields, routing behavior, ModelRunner, and existing event meanings are part of the public contract. Consumers should ignore new diagnostic fields and provide a fallback for new event types; event sequence numbers order events within a run, but concurrent nodes need not finish in a fixed order.

There is no cross-version serialized job/checkpoint format. Pi jobs are scoped to one host session and are lost on exit, reload, switch, or fork. The project is experimental and maintained on a best-effort basis.