@chrok/braid 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -2,7 +2,26 @@
 
 ## Unreleased
 
-No changes yet.
+## 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.
+- Group routine dependency updates and reserve Node/TypeScript major upgrades
+  for deliberate compatibility changes across both packages.
+- Clarify Pi tool and context guidance for parallel implementation and merge
+  nodes; describe read-only filesystem access by the node's assigned workspace
+  instead of assuming its directory is outside Git.
+- Trim OpenAI-compatible base URL trailing slashes in linear time, avoiding
+  excessive regular-expression backtracking on long internal slash sequences.
+- Protect the main branch and version tags; document repository governance,
+  CodeQL checks, Actions restrictions, and immutable releases.
 
 ## 0.1.0 — 2026-09-27
 

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,
@@ -29,6 +36,12 @@ calls a model. `npm test` is the fast core-only loop; `npm run test:pi` tests Pi
 
 ## Changes and reviews
 
+Submit changes to `main` through a pull request, including maintainer changes.
+Keep the branch up to date, pass the required CI and CodeQL checks, and resolve
+review conversations before squash merging. See the
+[repository policies](docs/repository-settings.md) for the complete settings and
+the current single-maintainer review policy.
+
 - Keep the TypeScript strict checks passing. Follow nearby code and the
   repository's two-space formatting; use explicit public types.
 - For behavior changes, add a regression test that fails before the change.

package/README.md

@@ -73,7 +73,7 @@ before running a custom adapter against a repository.
 
 ## Install in Pi
 
-With Pi 0.85.1 and Node.js 22.19+:
+With Pi 0.87.1 and Node.js 22.19+:
 
 ```sh
 pi install npm:@chrok/pi-braid

package/ROADMAP.md

@@ -18,6 +18,10 @@ Published versions are listed in [GitHub releases](https://github.com/Epsirom/br
 
 ## Next candidates
 
+- Migrate both packages from TypeScript 5 to 7 in one dedicated change. Explicitly
+  load Node types, review compiler default changes, and validate public declaration
+  consumption, package builds, and the complete Node/platform matrix. Keep Node
+  declarations on 22.x while Node 22 remains the minimum supported runtime.
 - Measure real applications before changing scheduler data structures.
 - Discuss optional per-run node/output limits and host-wide admission controls.
 - Define budget semantics that account for missing usage and in-flight calls

package/dist/adapters/openai.js

@@ -65,7 +65,11 @@ function parseCompletion(value) {
 export function createOpenAICompatibleRunner(options = {}) {
     const { apiKey, defaultModel } = options;
     const fetchImpl = options.fetch ?? globalThis.fetch;
-    const url = `${(options.baseURL ?? "https://api.openai.com/v1").replace(/\/+$/, "")}/chat/completions`;
+    const baseURL = options.baseURL ?? "https://api.openai.com/v1";
+    let end = baseURL.length;
+    while (end > 0 && baseURL[end - 1] === "/")
+        end--;
+    const url = `${baseURL.slice(0, end)}/chat/completions`;
     return async (request) => {
         const model = request.model ?? defaultModel;
         if (!model)

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

@@ -3,7 +3,7 @@
 | Surface | Supported / tested contract |
 | --- | --- |
 | Core runtime | Node.js 22+, ESM imports, TypeScript declarations, no runtime dependencies |
-| Pi package | Node.js 22.19+, Pi 0.85.1 is the pinned validation target |
+| Pi package | Node.js 22.19+, Pi 0.87.1 is the pinned validation target |
 | CI | Core minimum Node 22.0; both packages on Node 22.19 and 24 on Linux, macOS, Windows |
 | OpenAI-compatible runner | Chat Completions text and function-tool calls; decisions and merge nodes require tool calling |
 | Browsers / CommonJS | No supported browser build or CommonJS entry point in 0.1 |
@@ -14,11 +14,18 @@ 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 0.85.1.
+host provides. Braid follows that convention and pins dev dependencies to 0.87.1.
 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 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 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
+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 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.
@@ -30,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,16 +1,23 @@
 # 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
 
-1. Update both `package.json` versions and both lockfiles. Use a minor version
+Version tags (`v*`) cannot be moved or deleted. New GitHub releases are immutable:
+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, 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`.
@@ -18,6 +25,11 @@ source so its installed extension never reaches outside its own package.
 
 ## First publication
 
+Enable two-factor authentication in the npm account's web settings before the
+first publish. An emailed login code does not replace enrolling a security key
+or passkey for publishing. Complete credential enrollment yourself and keep
+recovery codes private.
+
 Log in locally with `npm login --registry=https://registry.npmjs.org`; confirm the
 account with `npm whoami`. Publish the core with `npm publish --access public`,
 then run `npm publish --access public` from `integrations/pi`. Complete npm's
@@ -25,7 +37,12 @@ interactive account/2FA checks if requested. Never put credentials in source,
 issues, shell history, or CI logs. An npm registration alone does not guarantee
 ownership of a previously used package name.
 
-After publication, install the registry versions in a fresh project and verify
+New packages may temporarily return `E404` after a successful publish while npm
+runs its [publish-time scan](https://github.blog/changelog/2026-07-28-npm-publish-time-malware-scanning-and-dual-use-metadata/).
+Allow time for the exact versions to become available through `npm view`; do not
+republish or bump versions just to work around this delay.
+
+After availability is confirmed, install the registry versions in a fresh project and verify
 both exported core entry points and the Pi extension. Add the actual publication
 date to the changelog and create the corresponding GitHub release.
 
@@ -39,9 +56,22 @@ For **each** package, configure an npm GitHub trusted publisher:
 - Environment: leave blank (this workflow does not declare one)
 - Allow direct `npm publish`
 
+With npm 11.20 or later, the equivalent CLI setup is:
+
+```sh
+npm trust github @chrok/braid --file release.yml --repo Epsirom/braid --allow-publish
+npm trust github @chrok/pi-braid --file release.yml --repo Epsirom/braid --allow-publish
+npm trust list @chrok/braid
+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

@@ -0,0 +1,83 @@
+# Repository settings
+
+The live [GitHub rulesets](https://github.com/Epsirom/braid/rules) enforce these
+policies. JSON files in [.github/rulesets](../.github/rulesets) are reviewable
+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.
+
+## Main branch
+
+[Protect main](https://github.com/Epsirom/braid/rules/24072177) applies to `main`,
+including administrators, with no bypass actors:
+
+- Changes must go through a pull request. Direct pushes, force pushes, and
+  branch deletion are blocked.
+- All review conversations must be resolved. New commits dismiss previous
+  approvals.
+- The branch must be up to date and all seven CI checks must pass: `core-minimum`
+  and `verify` on Ubuntu, macOS, and Windows with Node 22.19.0 and 24. Checks must
+  originate from the GitHub Actions app.
+- CodeQL must supply analysis results. Code scanning errors and new security
+  findings rated high or critical block merging.
+- Squash is the only merge method, keeping a linear history. The squash commit
+  uses the PR title and description.
+
+There is currently one maintainer with write access. Required approval count is
+therefore zero: GitHub does not allow authors to approve their own PRs.
+[CODEOWNERS](../.github/CODEOWNERS) requests maintainer review for contributions,
+but code-owner approval and approval of the last push are not mandatory. When a
+second maintainer joins, require at least one approving review and consider
+requiring code-owner and last-push approval. CI and PR requirements apply to the
+current maintainer as well.
+
+Automatic merge is available when explicitly enabled for a PR; it still waits
+for the rules above. GitHub offers an Update branch button and deletes merged
+head branches automatically. Do not bypass a failing check to merge a change.
+
+## Releases
+
+[Protect version tags](https://github.com/Epsirom/braid/rules/24072178) prevents
+updates and deletion of `v*` tags, with no bypass actors. New version tags can
+still be created by maintainers.
+
+Immutable releases are enabled for future releases. Prepare a draft and upload
+any assets before publishing; the release tag and assets become immutable when
+published. This setting does not retroactively make existing releases immutable.
+Use a new version for a correction. See [the release guide](releasing.md).
+
+## Actions and security
+
+- Actions use read-only `GITHUB_TOKEN` permissions by default and cannot create
+  or approve PRs through that token. Individual workflows request only their
+  needed permissions; the release job uses `id-token: write` for npm OIDC.
+- External actions and reusable workflows are limited to GitHub-owned
+  repositories; local actions remain allowed. External actions must be pinned
+  to full commit SHAs. Review and explicitly allow any future third-party action
+  before using it.
+- Workflows from all external fork contributors require maintainer approval
+  before running. Inspect workflow and code changes before approving a run.
+- CodeQL default setup scans GitHub Actions and JavaScript/TypeScript with the
+  default query suite and remote threat model, including its weekly schedule.
+- Dependabot alerts/security updates, secret scanning, secret push protection,
+  and private vulnerability reporting are enabled. Dependency updates remain
+  configured in [.github/dependabot.yml](../.github/dependabot.yml).
+
+These are repository settings, not organization-wide changes. Neither commit
+sign-off nor a CLA is required for contributions.
+
+## Dependency maintenance
+
+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.
+
+Keep `@types/node` on 22.x to match the oldest supported Node major. TypeScript
+major upgrades require a coordinated migration of core and Pi, including the
+standalone package/declaration checks; the current migration is tracked in the
+[roadmap](../ROADMAP.md). Automatic major version updates for these two packages
+are ignored until their compatibility policy changes. Minor/patch updates,
+vulnerability alerts, and security-update configuration remain enabled. Review
+any security fix that requires crossing an ignored major version manually.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrok/braid",
-  "version": "0.1.0",
+  "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",
@@ -47,8 +47,9 @@
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
-    "tsx": "^4.0.0",
-    "typescript": "^5.0.0"
+    "tsx": "^4.23.15",
+    "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"
+  ]
 }