Nuthatch: the book

This is the long-form companion to the Nuthatch documentation. The reference manual tells you which command and setting to use. This book explains why the machine is shaped as it is, what invariants it protects, and what each boundary buys you when something goes wrong at three in the morning.

It describes Nuthatch 2.7.0. It is deliberately grounded in the running implementation, not a design sketch for a future product. Where the system has a limitation, it is named. A system that is honest about its edge is more useful than one that claims to be a universal solvent.

How to read it

Read the chapters in order if you are learning the architecture. If you already operate a nest, start with the cursor and data that survives a restart. If you are deciding whether to port a subgraph, begin with the data problem and then use the practical subgraph fallback guide.

Each chapter links outward to the corresponding reference material. The book gives the reasoning; the manual gives you the precise TOML, route and command spelling.

Contents

1. The data problem - what a nest is for, and what it is not.
2. The authored nest - making a small, reproducible description of chain data.
3. The cursor - following a chain without confusing a temporary tip for history.
4. Storage and sealing - hot data, cold data, finality and SQL.
5. Reading the index - tables, views, APIs and the boundary of event-derived truth.
6. Identity, upgrades and reuse - why package identity and data identity are separate things.
7. The runtime - many nests, tenants, cursors and scaled workers.
8. Operating a truthful index - verification, security, failure isolation and the questions worth asking before trusting a number.

The appendices slow the camera down over three mechanisms which are easy to describe quickly and quite another matter to implement correctly:

9. One log, end to end - from an RPC response to a durable query result.
10. A reorganisation, walked through - rollback at the hot boundary, and why a finality violation halts rather than guesses.
11. A lease handover, walked through - the fencing rule that makes two scaled workers safe.

The chapters are intended to stand up to a close read. The RFC archive and implementation internals remain the primary material for contributors who want every last moving part.