latest tag. This policy
defines their runtime and dependency contract. CI configuration alone does not establish that
an unrun platform has passed; releases require a green supported matrix. See the
published-package verification for recorded results.
Supported versions
Node support is declared as
^24.20.0; Bun as >=1.4.4 <2, in every library.
The root manifest describes development requirements. It is not a substitute for
published package metadata. support-policy.json records the approved floors
and ranges; packed-install checks reject missing or inconsistent library ranges.
These declarations describe each runtime separately, not a requirement to run
both Node and Bun. Package engines are advisory in npm unless the consumer uses
engine-strict; they are not a runtime guard.
The initial Bun 1.3.14 runtime proposal failed the new disconnect test: its
node:http server did not emit the response/socket close events needed to abort
an in-flight handler. Bun 1.4.0 also failed the disconnect test; 1.4.4 passed it.
The application runtime floor is therefore 1.4.4, while repository tooling
remains pinned at 1.3.14. Earlier Bun example checks established only their tested subset, not the
complete adapter contract. See Bun 1.4’s Node compatibility changes.
The initial release uses a Zod floor of 4.6.6 because earlier
versions are affected by GHSA-mrhx-c7xc-m3w5.
Strict TypeScript 5.5.4 remains the compiler minimum.
Node 26 has a non-blocking preview job. Its upstream LTS transition is scheduled
for 2026-10-28. Promotion requires a reviewed policy/manifest/CI change after LTS
and successful verification; the date alone does not promote it. Node 24’s
scheduled EOL is 2028-04-30. Node 22 is outside the initial matrix; its scheduled
EOL is 2027-04-30. See the upstream Node schedule.
Deno, Workers, browsers, other package managers, and untested OS/architecture
combinations have no support commitment. Runtime-independent modules may be
usable there. Framework examples retain their own pinned framework/runtime
requirements; an example is not a promise to support every framework version.
Required CI
.github/workflows/ci.yml retains the complete Linux/Node 24.20.0 baseline for
runtime, dependency, packaging-contract, verification, workflow, and unknown changes:
formatting/lint, type checks, 95% coverage floors, framework examples, builds,
compiled consumers, minimum Zod checks, package exports, clean installs, sizes,
dependency audit, and repository-tooling tests. Manual runs and legacy v* tags
also request the complete baseline.
Documentation and artwork take a lighter formatting/audit/source-validation path.
Packaged documents and editorial metadata additionally require library builds,
archive contents/size checks, and fresh npm/Node functional consumers. Only
description, homepage, and keywords can change in a light package manifest.
Unknown paths, missing Git history, and mixed changes retain full verification.
See the development guide for the profiles.
.github/workflows/support.yml runs the supported matrix for full-profile PRs,
main changes, legacy v* tags, weekly checks and manual runs:
- Latest Node 24 on Linux, macOS and Windows with npm consumers.
- Bun 1.4.4 on Linux and latest stable Bun 1.x on all three OSes with Bun consumers.
- Node 26 on Linux as an explicitly non-blocking preview, on weekly/manual runs only.
skipLibCheck: false, and minimum/development Zod.
Each library retains its own isolated installation and import checks on every
supported runtime/platform. The functional consumer verifies both protocol eras, Web/Node
HTTP, the managed listener, actual stdin/stdout, contexts, rich results, input
validation, stdio cancellation, HTTP disconnects and cleanup. Auth checks cover
signed RS256/ES256 JWTs, audience rejection, frozen identities, Clerk OAuth JWTs
and Clerk’s opaque-token path using synthetic fetch responses. No live keys,
OAuth login, consent flow or provider network calls are involved.
Bun runs the functional consumer suite itself, including its subprocesses.
Node runs its own suite; invoking scripts through Bun alone is not runtime
coverage. The existing Node source-map stack assertion remains required. On
Bun 1.3.14, that assertion reports compiled JS locations; mapped TypeScript
stacks are currently a Node-specific guarantee. This does not waive functional
checks on Bun or alter the package’s maps/sources.
Every Monday, and on manual workflow dispatch, additional jobs run:
- The latest patch of every TypeScript minor between the approved minimum and development compiler minor, against latest Zod 4. Registry lookup errors fail the plan instead of silently reducing coverage.
- Stable upstream dependency drift within jose 6, Clerk backend 3 and Clerk shared 4, latest stable TypeScript, and latest Zod 4. Only disposable CI manifests/lockfiles change. This job must pass before a release.
- A non-blocking Bun canary/TypeScript-next probe. Prereleases are not supported merely because this probe passes.
Package checks and
Support checks, rather than individual matrix jobs. The support gate checks
planning and every applicable supported job, rejecting failures, cancellations,
and unexpected skips. An editorial skip makes no new runtime/platform claim.
When adopting these scoped workflows, first let a full-profile PR produce both
stable check names successfully, then replace the previous per-platform required
contexts with those two gates before merging. Preserve strict up-to-date checking
and the GitHub Actions app binding. No protection setting changes automatically.
The manual Release verification workflow reuses
both workflows at the selected source commit, including weekly stable dependency
and intermediate TypeScript checks. It does not produce candidate archives.
Reports are retained as separate job artifacts with runtime/package-manager
identity. Linux/macOS/Windows hosted results are required before claiming those
specific combinations verified. Local runs cannot stand in for another OS.
Upgrade and deprecation rules
- Review dependency updates monthly; handle urgent security fixes sooner. Keep direct runtime/development dependencies exactly pinned and commit a reviewed lockfile. Weekly floating probes never change normal installation policy.
- Runtime dependencies, especially jose and Clerk, must pass the supported runtime and declaration floors, auth regressions, exports and packed installs. Development compiler/tool upgrades must also preserve emitted declaration compatibility. A transitive requirement increase counts too.
- Add new runtime/dependency majors explicitly after stable upstream release
and successful CI/interoperability checks relevant to the change. Do not
infer support from a broad
>=range or a successful preview job. - Raising a Node, Bun, TypeScript or Zod minimum, dropping a supported major,
or removing public behavior is a breaking change: use a minor release during
0.xand a major release from1.0. Updating the development pin alone is not a consumer minimum increase. - Announce removals at least 90 days and one published release beforehand, whichever is longer, with a migration path and affected package versions. A documented security emergency may shorten notice; never hide the change. The initial unpublished baseline does not need a deprecation period.
- Review runtime retirement around upstream EOL. An EOL date does not silently change already-published package ranges or authorize indefinite old-branch maintenance. State the last supported Toolgrain release when retiring a target.
- Protocol revisions and vendored schemas require their own explicit review, provenance/checksum updates, conformance and interoperability verification. Dependency automation must not rewrite them. Renew client checks for protocol, transport/auth behavior changes and new runtime-major support.