@chrok/braid 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## 0.1.2 — 2026-09-27
+
+- Make Pi depend on the exact `@chrok/braid` version instead of bundling core.
+  Export shared model-adapter helpers from the existing root entry point.
+- Use one npm workspace lockfile and a development-only local core link; test
+  Pi-only installation against the unpublished core tarball outside the checkout.
+- Wait for core registry metadata and tarball availability before publishing Pi.
+
 ## 0.1.1 — 2026-09-27
 
 - Validate the Pi integration against Pi 0.87.1; update GitHub Actions and tsx.

package/CONTRIBUTING.md

@@ -12,13 +12,20 @@ Use Node.js 22.19+ and npm. From a fresh checkout:
 git clone https://github.com/Epsirom/braid.git
 cd braid
 npm ci
-npm ci --prefix integrations/pi
 npm run verify
 ```
 
-There are two packages and two lockfiles. The core has no runtime dependencies;
-Pi's dependencies belong in `integrations/pi`. Update and commit the corresponding
-lockfile when changing a dependency. Do not commit generated `dist` directories,
+The root npm workspace lockfile covers both packages. A development-only
+`@chrok/braid: file:.` dependency links the core checkout into `node_modules`;
+Pi's manifest still declares the exact release version. This lets CI test a
+new core before it is published. `check:pi`, `test:pi`, and `build:pi` rebuild
+core so package imports resolve current JavaScript and declarations. Consumers
+installing either published package do not install this development dependency.
+Use `npm install --workspace @chrok/pi-braid <dependency>` for Pi dependency
+updates; do not create a separate lockfile in `integrations/pi`.
+
+The core has no runtime dependencies. Pi's dependencies belong in its workspace
+manifest. Update and commit the root lockfile when changing a dependency. Do not commit generated `dist` directories,
 tarballs, credentials, or provider output containing private data.
 
 `verify` type-checks both packages, runs deterministic tests and offline examples,

package/dist/index.d.ts

@@ -1,3 +1,5 @@
 export { braid } from "./runtime.js";
 export { validateGraph, GraphValidationError } from "./validate.js";
 export type { BraidInput, BraidNode, BraidOptions, BraidResult, DecisionNode, Edge, ExecuteNode, ExecutionContext, ExecutionError, ExecutionEvent, ModelRequest, ModelResponse, ModelRunner, MergeNode, MergeDisposition, MergeSource, GitPreview, SourceCheckoutStatus, NodeWorkspace, GitResult, NodeOutput, NodeResult, NodeStatus, PredecessorOutput, TokenUsage, } from "./types.js";
+export { formatBudgetReminder } from "./budgets.js";
+export { gitToolDefinition, finishMergeToolDefinition, mergeInstructions, parseGitToolArguments, parseFinishMergeArguments, } from "./merge-tools.js";

package/dist/index.js

@@ -1,2 +1,5 @@
 export { braid } from "./runtime.js";
 export { validateGraph, GraphValidationError } from "./validate.js";
+// Shared helpers for model adapters, including the Pi integration.
+export { formatBudgetReminder } from "./budgets.js";
+export { gitToolDefinition, finishMergeToolDefinition, mergeInstructions, parseGitToolArguments, parseFinishMergeArguments, } from "./merge-tools.js";

package/docs/compatibility.md

@@ -23,8 +23,9 @@ exactly one automatic continuation when a job finishes during `agent_settled`.
 This covers the Pi 0.86/0.87 transcript and settling changes 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 0.87.1.
-The Pi npm package compiles and includes the same core source as the matching
-core release, so it does not need another installed copy of Braid or a checkout.
+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.
 
 Git must be installed for workspace execution inside a Git checkout. Non-Git
 text-only runs do not require Git workspace management.
@@ -36,8 +37,13 @@ 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`. Internal
-files and Pi helper classes are not stable public APIs. Documented result/error
+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,

package/docs/releasing.md

@@ -1,8 +1,8 @@
 # Releasing
 
 Core and Pi are separate public npm packages built from one commit. Both use the
-same version. The core has no runtime dependencies. Pi bundles compiled core
-source so its installed extension never reaches outside its own package.
+same version. The core has no runtime dependencies. Pi declares an exact
+`@chrok/braid` dependency and includes only its own compiled integration code.
 
 ## Prepare a release
 
@@ -10,11 +10,14 @@ Version tags (`v*`) cannot be moved or deleted. New GitHub releases are immutabl
 prepare a draft and attach any assets before publishing. Published tag/asset
 corrections require a new version. See [repository settings](repository-settings.md).
 
-1. Update both `package.json` versions and both lockfiles. Use a minor version
+1. Update both `package.json` versions, Pi's exact `@chrok/braid` dependency,
+   and the root workspace lockfile (`npm install --package-lock-only`). Use a minor version
    for breaking 0.x changes, and describe migrations in the changelog.
-2. Run `npm ci`, `npm ci --prefix integrations/pi`, and `npm run verify`.
+2. Run `npm ci` and `npm run verify` from the repository root.
    The package check verifies clean builds, public ESM imports, declarations,
    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;
    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`.
@@ -64,7 +67,11 @@ npm trust list @chrok/pi-braid
 
 Publishing a non-prerelease GitHub release triggers `.github/workflows/release.yml`.
 It validates the tag/version relationship, repeats all checks, and publishes
-core then Pi using short-lived OIDC credentials. It does not require `NPM_TOKEN`.
+core then Pi using short-lived OIDC credentials. After each publish (or retry
+of an existing version), it waits for matching version/commit metadata and a
+successful tarball download. Pi is not published until core is available. npm
+processing is polled every 15 seconds for up to 10 minutes; a timeout fails the
+workflow with retry instructions. It does not require `NPM_TOKEN`.
 The workflow installs npm 11 and uses Node 24. See
 [npm's trusted publishing documentation](https://docs.npmjs.com/trusted-publishers/).
 

package/docs/repository-settings.md

@@ -68,7 +68,8 @@ sign-off nor a CLA is required for contributions.
 
 ## Dependency maintenance
 
-Dependabot checks both npm manifests weekly. Pi host packages stay in a separate
+Dependabot checks both npm workspace manifests through the root lockfile weekly.
+The internal `@chrok/braid` dependency is updated by the coordinated release process. Pi host packages stay in a separate
 group because even 0.x minor releases can change extension contracts. Other npm
 minor/patch updates are grouped; GitHub Actions updates are grouped monthly and
 retain full commit SHA pins. Grouping does not enable automatic merging.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrok/braid",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "license": "MIT",
   "description": "A small, framework-agnostic DAG runtime for isolated model invocations",
   "type": "module",
@@ -32,12 +32,12 @@
   "scripts": {
     "build": "node scripts/build.mjs",
     "check": "tsc --noEmit",
-    "test": "tsx --test test/*.test.ts",
+    "test": "tsx --test test/*.test.ts test/*.test.mjs",
     "demo": "tsx examples/basic.ts",
-    "check:pi": "npm --prefix integrations/pi run check",
-    "test:pi": "npm --prefix integrations/pi test",
+    "check:pi": "npm run build && npm run check --workspace @chrok/pi-braid",
+    "test:pi": "npm run build && npm test --workspace @chrok/pi-braid",
     "prepack": "npm run build",
-    "build:pi": "npm --prefix integrations/pi run build",
+    "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",
@@ -48,7 +48,8 @@
   "devDependencies": {
     "@types/node": "^22.0.0",
     "tsx": "^4.23.15",
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "@chrok/braid": "file:."
   },
   "repository": {
     "type": "git",
@@ -68,5 +69,8 @@
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
-  }
+  },
+  "workspaces": [
+    "integrations/pi"
+  ]
 }