Contributing
Use Node.js 22 or 24 and Git. package-lock.json is the authoritative dependency baseline, so use npm for an installation matching CI:
npm ci --ignore-scripts
npm run build
npm test
npm run docs:build
npm run package:smokeFor local development, Yarn Classic and pnpm can also install dependencies without writing a second lockfile:
yarn install --ignore-scripts --no-lockfile
yarn run build
yarn run test
yarn run docs:build
yarn run package:smokepnpm install --ignore-scripts --no-lockfile
pnpm run build
pnpm run test
pnpm run docs:build
pnpm run package:smokeThese alternatives resolve dependencies independently of package-lock.json; they do not reproduce the exact CI dependency tree. Use one package manager per checkout. Do not commit a second lockfile. Build Rivet explicitly after installation because dependency lifecycle scripts are disabled.
Add focused behavioral tests for new functionality, run the existing relevant regressions, and update the user-facing documentation. Keep generated distribution assets in sync with the build script.
Use the existing workflow service and validation boundaries. Prefer native harness tools or existing project scripts when they already solve the problem. New model descriptors must distinguish registration, implemented execution, and live qualification.
CI and reproducing a shard
CI runs every test on Linux and macOS with Node 22 and 24. Each combination uses four balanced shards, with two test files running at a time inside a shard. Package installation checks run once per combination. The dedicated documentation workflow builds the site once for a PR or main push.
To reproduce one shard with the matching Node version:
npm run build
node scripts/verify-tests.mjs --shard=2/4Without --shard, this command verifies the complete suite and evaluation catalog. npm test and npm run evals -- --mode=fixture remain available for separate local runs. Test files and their evaluation scenarios always belong to the same shard. New test files are discovered automatically; they do not need a manifest entry.
scripts/test-durations.json contains approximate scheduling weights from observed macOS Node 22 test durations, used as scheduling hints. These hints affect balance only, never coverage. Refresh them when the slowest shard consistently dominates; do not remove expensive tests to improve the timing. CI executes each test once in a temporary home with credentials and user configuration stripped. It scores evaluation criteria from the native test events, matching both the source file and exact test name. Missing, duplicate, skipped or failed criteria fail the shard, as does any suite failure. The standalone evaluation command still runs selected scenarios independently. macOS fixtures resolve the native Apple Git executable once to avoid repeatedly launching its system shim; executable-discovery tests retain their explicit paths.
The existing check (OS, Node) statuses aggregate all shards and fail if any shard fails, is cancelled, or is unexpectedly skipped.
The public repository is Agilno-Tech/rivet. Rivet uses Apache License 2.0 and the package name @agilno-tech/rivet. Registry publication is a separate maintainer step. Never include client code, credentials, or private work history in contributions.