Usage Guide

The Usage Guide collects the practical, day-to-day patterns for writing applications on top of causl. Where the SPEC is normative — it tells you what the engine must do — these pages are advisory: they explain what experienced causl users have learned about how to wire a graph so that it stays small, observable, and easy to evolve.

Each page in this section is independent. You can read top to bottom if you are new to causl, or jump straight to the topic that matches the bug you are chasing. The code examples are real TypeScript against current @causl/core, @causl/react, and the rest of the published surface; they would compile and run as written.

Where to start

If you have not yet built anything with causl, read Getting Started first and step through the Tutorial. The Usage Guide assumes you understand createCausl(), graph.input / graph.derived, the transactional graph.commit(intent, fn) contract, and that derivations are pull-based Behavior a = GraphTime → a values rather than push-based event streams.

If you have built a feature or two and are now asking "how should I organise this as the product grows?" — start with Structuring Causl Graphs. That page is the longest in the section and the one most likely to save you a refactor a year from now.

Pages in this section

• Structuring Causl Graphs

  Anti-patterns to avoid (the “god-graph”), how to decompose a graph per feature, how to mount and unmount subgraphs cleanly with useCauslFamily, and the honest trade-offs between one shared graph and many isolated instances.

• Writing Derivations

  The mechanics of graph.derived(id, compute): dependency inference via the tracked get, determinism requirements (SPEC §5.4), the commit-metadata tag, and how to debug a derivation that recomputes more than you expect.

• Commits and Subscriptions

  The Phase A–H pipeline in user-visible terms, graph.subscribe versus graph.subscribeCommits, ordering guarantees, and how to write an observer that does not re-enter the engine.

• Using Causl with React

  useCausl, useCauslNode, useCauslShallow, the typed-array zero-copy variant, suspense-aware reads, and the MVU useDispatch runner.

• Async Resources with @causl/sync

  The composite statechart for fetched data — launch, version-stamp, abort, settle — together with the conflict registry that turns "two writers, one row" into a first-class outcome rather than a race.

• Persistence and Hydration

  graph.snapshot / graph.hydrate, the @causl/persistence adapter, storage backends, and how to survive a schema migration without losing inputs.

• Testing Strategies

  graph.simulate for dry-run prediction, deterministic harnesses, snapshot comparison with the readAt retention window, and the @causl/checker Rust-backed lint suite as a CI gate.

• Inspecting Live Graphs

  graph.explain(node), the live materialisation, and the @causl/devtools-bridge zero-cost Redux DevTools Extension protocol — how to navigate a 10,000-node graph in production without rebuilding it.

How this section is organised

The pages above are ordered roughly by how often you will reach for them on a typical day. Structuring and Derivations are foundational — you will read them once and re-read them when an architecture decision feels hard. Commits, React, and Async Resources are everyday material: you will return to specific snippets as you build. Persistence, Testing, and DevTools become important the week you ship.

For the reverse direction — the SPEC sections, race-class catalogue, and per-package TypeDoc — see the documentation index.