Contributing

Contributions should be small, source-backed, and explicit about CRDT semantics. Read AGENTS.md and codemap.md first. Preserve ESM imports with .js extensions, strict TypeScript, category:verb action names, type:name events, immutable tokens, and one canonical Chronicle session.

Development

npm install
npm run build
npx tsc --noEmit
npm run test:quick

Use the relevant focused commands for changes:

npm run test:unit
npm run test:network
npm run test:persistence
npm run test:cuttle:sync
npm run test:cuttle:crypto
npm run test:cuttle:hardening
npm run test:watershed:rules
npm run test:watershed:sync

The repository uses a custom test runner, not Jest or Vitest. Use fixed seeds for randomness and the ESM loader for individual TypeScript tests, for example: node --loader ./test/ts-esm-loader.js test/testSync.ts.

Source conventions

All persistent state mutations go through engine.dispatch(); use game:setState for game-specific keys. Registered handlers should use their execution context's mutate() for internal registry writes. Do not relax strict, change protected interfaces, or edit security-critical E2E code without review. Additive actions are safer than renaming existing ones. Update documentation when behavior changes, and never commit secrets or generated artifacts.

Use conventional commit prefixes such as fix:, feat:, test:, or docs:.