@chrok/braid 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -2,7 +2,18 @@
 
 ## Unreleased
 
-No changes yet.
+## 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

@@ -29,6 +29,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/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,9 +14,15 @@ 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 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 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.
 

package/docs/releasing.md

@@ -6,6 +6,10 @@ source so its installed extension never reaches outside its own package.
 
 ## Prepare a release
 
+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 and both lockfiles. 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`.
@@ -18,6 +22,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 +34,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,6 +53,15 @@ 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`.

package/docs/repository-settings.md

@@ -0,0 +1,82 @@
+# 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 manifests weekly. 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.1",
   "license": "MIT",
   "description": "A small, framework-agnostic DAG runtime for isolated model invocations",
   "type": "module",
@@ -47,7 +47,7 @@
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
-    "tsx": "^4.0.0",
+    "tsx": "^4.23.15",
     "typescript": "^5.0.0"
   },
   "repository": {