RiverGen

A backend change can succeed while the interface remains stale. A field may disappear between an event and its cache update, or an optimistic item may never reconcile. RiverGen grew out of Sodium, the collaborative workspace where that route was built and kept under a CI gate.

Its central decision is to give updates one route: mutation, event publication, listener, broadcast, WebSocket, dispatcher, projection, and cache. That makes it easier to identify where a change belongs and where data went missing.

A domain specification generates twelve connected files, covering backend handlers, frontend projections, shared definitions, and a Witness scaffold. Developers fill in the application logic within that structure. A planning command lets them inspect the proposed files before generation.

The current scaffold targets TypeScript applications using Express, Socket.IO, React, and TanStack Query. It provides conventions and checks around those tools while leaving the application’s business logic to its developers.

The verification command runs twelve gates. They look for specific architectural problems: a mutation bypassing event publication, an event with no dispatcher, a missing schema, an unrestricted broadcast, or a cache write outside the expected path.

Failures identify the relevant file and the rule it breaks. These checks make conventions actionable during development, but their scope matters: detecting a recognised code pattern is not the same as proving every possible runtime behaviour.

A connected pipeline can still lose data. Witness adds declared fields, example payloads, and assertions for each domain. It combines schema and broadcast checks with projection assertions that seed a query cache, apply an update, and inspect the result.

The generated file is a starting point. Developers must supply meaningful assertions before it can check their projection behaviour. This makes the distinction between a present scaffold and an exercised data contract explicit.

RiverGen Witness is also published as @rivergen/witness. It supplies TypeScript contracts such as DomainWitness and WitnessAssertion without adding runtime code. The CLI performs verification; the companion package gives application code a shared vocabulary for describing the evidence.

Those contracts cover lifecycle checks and additional signal events, including assertions about create, update, delete, and optimistic-item reconciliation. Together, the CLI and Witness turn the intended architecture into something a developer can describe, inspect, and check.