Design notes
Why Twinstate is shaped the way it is: what was considered, what was rejected, and the research behind each choice. Read this before proposing to change a rule — the alternative has probably been weighed already.
The shape: a synced collection, not an event feed
Rejected: hand-written per-field events ("title changed", "busy changed"). Each event is a promise that one field stays live, with its own code on both ends. Any field nobody wrote an event for silently goes stale, and an event lost during a disconnect cannot be recovered without a replay mechanism for each one.
Chosen: track every change, broadcast the patches. A record changes only through update, which records exactly which fields changed, so a field cannot go stale by omission — nothing per-field is written by hand. The order and delivery model follows Linear's sync engine (one global lastSyncId, delta packets in total order) and Replicache's global-version strategy.
Change tracking: tracked updates
How the server knows what changed. Doctrine's ORM documentation names the three classic policies, and each maps to an option we weighed:
| approach | per write | per flush | extra memory | a change can be missed? | knows the field |
|---|---|---|---|---|---|
| full re-diff ("deferred implicit") | nothing | every record, deep-compared — grows with all data | a deep copy of every record as last sent (~2×) | no | via diff |
explicit mark, changed(kind, id) ("deferred explicit") | one call | marked records, deep-compared | the same ~2× copies | yes, if forgotten | via diff |
| tracked update (Immer's copy-on-write draft with patches) | proxy overhead, ~2–3× a plain write | none: the recorded patches | only the changed path; the last-sent value is the previous immutable one | no | exactly |
| ambient proxies (Valtio, MobX) | a trap per write — and per read in MobX | none | highest: an observable per property (MobX) or proxy per object | no | yes |
| generated setters (Hibernate bytecode enhancement) | a flag | dirty fields | a dirty bitmask | no | yes |
Chosen: tracked updates. Flushes stop scaling with data, memory stays near 1×, and a missed change to a record is impossible by construction rather than caught by tests (state kept outside records is not synced at all). It also gives every change one place that sees before, after and the patches — where validation, derived fields, history and custom diffs hang. The cost accepted: Twinstate holds the in-memory records, and the application supplies a store adapter instead of writing its state directly. Immer's auto-freeze stays on in development and tests (it catches accidental mutation) and off in production (in Immer's benchmark it roughly doubles a large update: 305ms vs 149ms for 10,000 of 100,000 items).
Last write wins, by arrival, per field
One writer per record at a time (the server's queue) means there is nothing to merge: each change is a set of field patches, applied in the order the server receives them, and the last to arrive wins, field by field. So a late edit touches only the fields it changed; a named mutation carries intent, not values (a late increment still adds one to the current count); and the 24-hour hold keeps a week-old offline edit from overwriting today's without being confirmed.
Rejected: the newest by the client's clock. Clients' clocks drift and can be set at will, so "newest" would be whoever's clock runs ahead (Logux's trade).
Merging, where a field needs it, is the field's own encoding. CRDTs (Yjs, Automerge, TinyBase's mergeable store) solve many writers editing the same value concurrently, and that is the cost to accept: two devices typing into the same text field at the same instant overwrite each other rather than interleaving keystrokes. The door stays open per field, not per app: appendable is already a field whose changes travel in their own encoding (the new suffix), and a CRDT text encoding (a Yjs value the server merges in any order) would make arrival order irrelevant for that field alone. Encodings are the framework's, not the app's: a custom merge must be deterministic, pure, identical on every replica and agree with the client's optimistic display, which is easy to get subtly wrong; and what apps usually want from one ("add a tag without erasing others") is a named mutation, whose handler applies the intent to the current value. Until a CRDT encoding exists, a Yjs server beside Twinstate handles co-edited text, with Twinstate holding everything around it.
(epoch, rev), in memory
Rejected: a persisted revision counter. It still breaks on a restored backup or a client pointed at a different server — the number is valid but belongs to another history. Chosen: a new epoch per boot (its boot time, then a random suffix); revisions only compared within an epoch; a new epoch always resets. Nothing about synchronisation is persisted, and the cost is one snapshot per client per restart.
Resume within a process, reset across processes
Rejected: a checkpoint (the epoch, revision and rings, saved when a partition closes and restored by its next owner, so clients resume across a deploy). It carries the persisted counter's flaw across processes: resuming trusts that a client's copy plus the ring equals what the new process would send, and that stops being true if anything between the two changed — a restored backup, a script, changed kinds, changed policies. Guarding it took a marker in the store and fingerprints of the registry and the policies, and still missed writes behind Twinstate's back. Chosen: a ring resumes a client within one process; any new process starts a new epoch, and clients reset from the store, which is right however the store got there. Figma does the same: after a deploy its clients download the file again. The cost is bounded by the snapshot budget, windows and jittered reconnects, and the upgrade is a reset that sends only what differs, which compares the data itself and so stays correct where a checkpoint was not.
Nothing in memory crosses processes, then. Memory-only state is for derived values (rebuilt by the new process) and the current process's activity (which a new process is not doing), so it never needs to travel. Durable Objects puts it the same way — memory for "caching", "active connections" and "temporary state during request processing", while "important state" goes to storage — as does Phoenix LiveView, which keeps per-connection state in memory and asks for "other relevant state in the database". Moving memory between machines is the exception, for state too big to reload: Discord copies a guild's members list ("multiple GB of data") at a handoff.
Resuming after a disconnect: a ring, or a record per client
How a reconnecting client catches up decides what the server keeps. The four ways in use, and when each wins (2026-10):
| a ring per topic (Twinstate) | a full reset | a client view record (Zero) | hash comparison (Merkle trees in Dynamo and Cassandra, block hashes in rsync) | |
|---|---|---|---|---|
| how | each topic keeps its recent changes (1,000 by default, bounded by size and age too), shared by every client; the client sends its position, the server replays what followed | the server sends the topic's whole (projected) contents | the server stores, per client group (a browser profile's tabs), the rows it holds and their versions, and sends what differs | the client sends one hash per bucket of records it holds; the server sends the buckets that differ |
| a short drop | cheapest: only the missed changes | everything | a re-run of the client's queries, then a diff | a few KB up, then a diff |
| longer than a topic's ring (that topic only), or a server restart (a new epoch: every topic) | falls back to a reset | — | an exact diff (the records are persisted) | an exact diff |
| what a viewer may see changes (per-viewer access, designed separately) | a reset | — | an exact diff | an exact diff |
| server state per client | none | none | rows × versions per client group, persisted, cleaned up when they vanish | none |
| fits | many clients sharing topics, data in memory | small topics | per-client queries over a database | large topics with little changed |
Chosen: a ring, falling back to a reset, because the common case is a short drop, where a ring is cheapest, and it keeps no state per client. A reset costs what any page load costs, a payload sent once, and is bounded: the instant topic by the snapshot budget, and a long thread by its windows, so a reset sends a conversation's first window, not its whole history — the paginated reset is the window. Why Zero needs a record per client (our reading): its clients sync the results of their own queries, which no two share, so there is no common log to replay; its clients keep large local datasets; and its server is a cache in front of Postgres whose instances restart. The upgrade, when snapshots grow: let the client be the record — on a reset it sends bucketed hashes of the records it holds, and the server sends only what differs, still with no state per client. Rings are sized in changes, not time: edits, reactions and streamed text all count (a stream at about 50 tokens a second fills one entry per flush, so about 50 a second, and 1,000 entries cover some 20 seconds of it), and the instant topic carries everyone's activity, so it is the first to run short; sizing rings by time is the simple adjustment if it does.
Typed keys, one id at most
Rejected: string key paths ("conversation/abc") matched by prefix — ids containing /, prefixes of prefixes, typos. Rejected: tuple keys of any length — generality with no current use. Chosen: a kind has one opaque id or none; relations are declared (ref, link, belongsTo), never encoded in keys for Twinstate — an id may still encode what a store needs to find a record (tx.childId), and Twinstate never parses it.
Writes: an outbox, and a durable record of what was applied
The requirement that decided this: nothing in progress may be lost when iOS kills the app. Options, in order of machinery:
- Online only, display the server's value. Simplest, but a field being typed into cannot display the server's value, and nothing survives a kill.
- Sync the latest value per field. Small, but it cannot express actions (send, create), so it needed a second write path for those.
- An operation queue with conflict detection (Linear, Replicache): per-field versions, conflict policies, rebasing, transactional storage for "effect + mutation id". Complete, and far more than needed.
- Chosen: a durable outbox. One write path for everything. No conflict detection: entries are applied last-write-wins, and the 24-hour hold covers the stale-device case.
The server's memory of applied mutations is durable. It was first kept in memory, per epoch, with client-chosen create ids as the safety net across a restart. An audit showed that net has a hole: create-if-absent keeps no record of deletions, so a create resent after a restart — or released from a day-long hold, which almost always outlives a restart — brought back a record deleted in between, and a resent patch could land over a newer write. Chosen: the highest applied id per client, and the rare non-ok results, are stored among Twinstate's own records (one key-value adapter, twinstate, beside the kinds), written after each turn's data and inside its transaction when there is one. It is one small write per mutation turn. It is exact with a transaction; with plain files a crash between the two writes lets one resend run again — harmless for updates and merges through idempotent handlers (still required), and for creates except in the one residual case left: another device removed the record before the resend arrived (hours later, or days for a held entry), and the re-run create brings it back. An application that cannot accept even that keeps its own record of applied ids beside its data, written with it.
The 24-hour hold
Research on queued-write lifetimes: Workbox background sync's maxRetentionTime (its examples use 24 hours; expired requests are dropped); Replicache removes clients without pending mutations after 24 hours but keeps those with pending work; Stripe idempotency keys live 24 hours; Firestore caps pending writes by count (500), with offline persistence meant "to cover temporary connection discontinuity". Twinstate takes the window and Replicache's instinct: hold, never drop.
Confirmation by reply, on one ordered stream
Rejected: acknowledgements inside the broadcast (Replicache's lastMutationIDChanges). Needed only when replies and broadcasts travel on different connections. Chosen: the reply to the request is the confirmation, sent after the flush that contains its result, on the same ordered stream. It covers no-op mutations and carries rejection reasons for free.
One queue, fast handlers
Researched patterns for concurrent writes:
- Serialise, keep handlers fast — Cloudflare Durable Objects (input gates; ~1,000 requests/s per object; "keep handlers fast"), Replicache's global version (~50 pushes/s at 20ms).
- Partition coarsely — Replicache's per-space version (a lock per space, at the cost of cross-space atomicity); one Durable Object per room.
- Optimistic concurrency with retries — Convex (read sets checked at commit, automatic retries); Replicache's row-version strategy ("increased implementation complexity").
Chosen: the first. Rejected: per-record lanes declared by each mutation — the complexity of the third without its benefits. If one queue is ever too slow, partition coarsely.
Each turn commits before the next
A turn waits for its own write, and nothing it produced (a reply, a broadcast, a snapshot) leaves before that write is durable. A failed write loses nothing confirmed: the server stops (fail-stop), and the turn's mutations, never answered, are resent after the restart. How engines that never lose a confirmed write batch:
| engine | batches | the next command waits for the previous write |
|---|---|---|
| Zero | the network: a push carries many mutations, each run in its own transaction | yes |
| Replicache | a push, optionally in one wider transaction (one client, all or nothing) | yes, per push |
Akka, persist (the default) | one command's events; later commands are stashed until the write completes | yes |
| Akka.NET batching journals | writes from many actors on one connection | yes, per actor |
Akka, persistAsync (opt-in) | across commands; replies wait in callbacks; a failed write stops the actor | no |
| Durable Objects | across requests; outgoing messages are held until the writes are durable | no |
The last two still confirm nothing early: they let the next command run, and hold its messages instead. Engines that publish before a write is durable (Figma's journal, Hocuspocus's debounced saves, tldraw's periodic snapshots) accept losing recent work on a crash, which a confirmed write in Twinstate may not.
Chosen: batching only where it changes nothing a client sees:
- several mutations in one message: the client may send many outbox entries together, and each still runs as its own turn;
- one turn, one commit: however many records a turn writes;
- commits from different partitions grouped by the store, which Twinstate never sees (see the transaction).
Rejected: batching turns within a partition (persistAsync, Durable Objects' output gates): the next turn runs while a commit is pending, and its messages wait at a gate. It needs the gate, a restart from storage when a write fails, and a store that commits strictly in order; and the slowest write still holds back every message behind it, so it raises throughput, not latency. Durable Objects can afford it because their storage is local; a Twinstate store may be a remote database. A partition too busy for one write per turn gets a faster store write or is split.
Loading: declared, delivered together, started where navigation starts
- Linear tags each model with a load strategy (
instant,lazy,partial) and loads a delta packet's dependencies before applying it. - Zero declares relationships in the schema and syncs a
related()tree as one query;useQueryresults stay cached for a TTL after unmount. - JSON:API compound documents include related resources under a full-linkage rule: every included resource is referenced from the document.
- Relay composes each component's data needs into one query per route and starts it before rendering ("render as you fetch"); entry points load a modal's data and code on the event that opens it.
Twinstate combines them: load per kind; ref delivered with its referrer (full linkage); link for navigation; entries that declare their loads, and preload with a TTL, called from wherever navigation starts. An earlier design made routes Twinstate "surfaces" and kept a router in sync with them; it was dropped because it made Twinstate do a router's job — deriving what is open from the router's state, cancelling superseded navigations — which the TTL-plus-mounted model of Relay, TanStack Query and Zero makes unnecessary. Code splitting from Relay's entry points is not adopted — the data half is what prevents waterfalls.
Plain data, not classes
Records are plain objects typed from their zod schemas; behaviour lives in pure functions (selectors, helpers). Immer's tracked updates are designed for plain data (classes need opting in and complicate copy-on-write and freezing); records travel as JSON, so a class would be rebuilt for every record on every client; and the schema stays the single source of the shape. Linear's models are classes because each property is a MobX observable — the approach this design chose not to take. A store adapter may be written as a class; its types are structural.
No owner on a kind
Rejected: owner: 'client' | 'server', which decided whether a kind got a generic patch. The registry already says it: a kind is field-editable by clients exactly when a patch(kind, { fields }) is declared for it, naming those fields. owner was a second place to say the same thing. Its one real rule — clients never send appends — is now "a patch never covers an appendable field".
Core and utilities
The core is what syncing depends on, plus what proves you use it correctly: the registry, the server, the protocol, the client (replica, outbox, cache), the React bindings, and the test kit. Device state and the WebSocket transport are utilities — optional entry points nothing in the core imports. Device state was in the core at first; it moved out because a theme or a scroll position has nothing to do with syncing, and keeping it in blurred what the package is for. The test for anything new: does syncing, or proving it, depend on this?
| part | entry points |
|---|---|
| core | twinstate, twinstate/server, twinstate/client, twinstate/react, twinstate/testing |
| utilities | twinstate/device, twinstate/ws/server, twinstate/ws/client |
Inside the core, the server and the client never import each other, so an app's browser bundle never carries server code and its server never loads client code; React builds on the client, and the test kit drives the server and the client (not React, an optional peer an app without React must not need). Lint enforces each boundary (eslint.config.js). zod is the one required peer dependency; react is needed only for twinstate/react and ws only for twinstate/ws/server (the client end uses the browser's own WebSocket, so a browser bundle never carries Node code), so both are optional peers.
The persisted cache: per tab, newer position wins
Replicache keeps one IndexedDB cache per client group shared by all tabs, kept in step over a BroadcastChannel; Firestore shares one IndexedDB across tabs with a primary-tab lease and coordination through localStorage events — and its issue tracker shows the handoffs are where the bugs live (a non-leader tab emitting stale data after a mutation). Rejected: sharing live state between tabs through the cache. Chosen: every tab stays live on its own connection; the cache is only a starting point, resumed or reset against the server like any reconnect; any tab may write a topic, but only when its position is newer than the stored one, checked in the same transaction. No leader, no lease, no channel; the cost is one socket per tab.
The rest follows from treating the cache as untrusted: a topic saved under another cache key is simply refetched; eviction only means a fresh snapshot. (In Safari the browser, script-writable storage is deleted after seven days of Safari use without a visit to the site; a home-screen web app counts only its own days of use, so it is not purged for being unused. Either may be evicted under storage pressure, which navigator.storage.persist() makes rarer.) The outbox is in IndexedDB too, with strict durability, flushed when the page is hidden: an earlier design kept it in synchronous localStorage to guarantee the last keystroke, at the cost of main-thread serialization of large text and a small shared quota (see the client).
Rejected: a per-entry render: 'cached' | 'fresh' policy (Relay's store-and-network / network-only). It only guarded against stale data at startup from the cache, while a disconnect makes a screen just as stale — so it half-protected, and was a second concept for one question. Chosen: one signal, useSyncStatus(handle).stale, whatever the cause; a screen that must not mislead reads it and annotates, disables or waits.
AI-first: every rule where an agent will see it
Most code in an app built on Twinstate will be written by coding agents, and an agent learns a rule only from a signal it cannot miss. Anthropic's first advice for Claude Code is to give the agent a way to verify its work — a test, a build, a linter, anything that answers pass or fail. Tools built for agents draw the same line between advisory guardrails (instructions and docs, which an agent may ignore) and enforced ones (a failing check, which it cannot). So every rule in Twinstate is placed as high on this ladder as it will go:
| layer | seen when | used for |
|---|---|---|
| 1. the type | as the code is written; the editor and tsc fail | everything expressible: which methods an adapter has, which mutations need handlers, where writes can happen, what an entry needs before it renders, which field names exist |
| 2. a lint rule | on save and in CI | what types cannot express but the code's shape shows: preloading during render or after an await, a tx escaping its turn, impure effects, unstable selectors, casts that forge ids |
| 3. a generated test | on every test run | behaviour: convergence, resends across a restart, ordering, the store round trip, your own invariants |
| 4. a production throw | by a user | only for untrusted input at the protocol boundary — a malformed frame, an id with ../ in it — never for a programmer's mistake |
| 5. a log | rarely, by anyone | nothing that matters |
| 6. docs | if read | explanation, never enforcement |
Rules we follow because of it:
- No production checks for programmer mistakes. What the types prove is not checked again at run time (production must be the fastest path); what they cannot prove is a lint rule or a test. The one exception is a write through a turn handle whose turn has ended: skipping that check would corrupt state silently, and it is a single branch.
- Error messages carry their fix. Branded types are named so that the compiler's message reads as an instruction (an entry without
fromsays to callclient.preloadwhere navigation begins); every lint message names the fix and links to the doc section. - Exhaustive by type. Where a list must stay complete as an app grows — fixtures per mutation, which kinds may be cached — it is a mapped type over the registry, so a new mutation or kind fails to compile until it is covered.
- Every claim is tested. Each compile-time guarantee in these docs has a
@ts-expect-errortype test; a claim no test proves is a docs bug.
The audit that shaped this pass went through every "must", "never", "throws" and "warns" in these docs. It moved about seventy rules up the ladder: the turn handle, entries that need a preload, lazy reads through handles, exact store types, nominal ids, typed field names and relations, JSON-only schemas, required defaults, typed events and rejections, the required outbox UI, and the exhaustive test kit. A few rules stay where they are, deliberately:
- rejecting untrusted input (layer 4);
- "keep synced state in records", and "a field changing meaning is a breaking change" (layer 6). No tool can see what a value means.
Writes through a turn handle, not an ambient server
Rejected: server.update callable anywhere, guarded by AsyncLocalStorage. It worked, but "writing outside a turn" and "awaiting a commit inside one" were only caught at run time — a production throw and a five-second watchdog log. Chosen: every write is a method of tx, the handle a handler receives. Code without a tx cannot write, which is a compile error, not a throw; lint rules catch a tx escaping into a callback, and a mutation sent from inside a turn. The write path no longer looks anything up. It is the model of Convex's mutation ctx, and of the transaction callbacks in Prisma and Drizzle. The cost is that a helper that writes takes tx as a parameter, which also makes it visible at a glance which code can change state.
A handler's tx cannot mint ids, only take them from its arguments, from records, or derive them. So every create is recognisable on a resend by construction, and the idempotencyKey option — which an author had to remember, and which the docs never fully defined — is gone. For the same reason a mutation's handle has no plain afterCommit: follow-up work hangs off a create that happened (onCreated), or says in its name that it repeats (afterEveryCommit).
Work outside the queue: results come back as mutations
Async work (a payment, an agent run, a webhook, a timer) runs outside the queue, and its result comes back as a mutation: declared, from: 'server', sent with server.mutate. There is no other way for server code to write; server.commit (a function run in the queue) is gone, with its handle's afterCommit and newId. Precedents: Akka's pipeToSelf — touching an actor's state from an async callback "introduces the risk of accessing internal state of the actor that is not thread-safe", so the result becomes "a message"; Convex, where every write is a named mutation, internal ones (internalMutation) included, and its scheduler calls mutations by name; Durable Objects, reached by a call on a stub. Being data rather than code, a result can be applied by whichever process holds the partition, versioned by the lock file, deduplicated by key and generated into tests like a client's mutation.
How the work survives a crash is the app's choice among three standard answers: a plain follow-up when losing it does not matter; the provider first, with its webhook as the durable path (Stripe: "webhooks are required for fulfillment", and your function "might be called multiple times, possibly concurrently"); a durable job queue, enqueued by a record's adapter in the turn's transaction. server.close() refuses client mutations, finishes the queue and closes, at once; the app waits for its own async work, and whatever that work reports afterwards is saved in the server's outbox, for the partition's next owner to apply (kept in Twinstate's own records on one server, an adapter on several) — Akka's sharding buffers messages during a handoff the same way, and Socket.IO splits its adapters the same way (in memory by default, Redis or Postgres for several servers).
What changes in what is built: mutation() gains from: 'server', and registry() reserves the kind name twinstate. The rest is new server API (server.mutate, server.close, the server's outbox, saveToOutbox) and new client API (client.until), none of it built yet.
Rejected, in the order they came up:
- A task API (named tasks declared on the server, started with
tx.start, saved in their own table): it moved work away from its handler and added an API to learn, to save state the record already holds. - A
preparephase (an async step before the turn, as Zero has): a second way to do what a follow-up does. - Resuming interrupted work from saved progress (Temporal's heartbeat details, Orleans' dehydrate): every consumer would write resume code.
- On several machines, a handoff that waits for work to finish, up to a maximum (Durable Objects' deferred code updates): another process could already be serving, a busy partition never goes idle, and Discord's voice outage of 25 March 2026 began when "a safety check designed to wait for other events in progress to complete meant the termination grace period in Kubernetes elapsed before handoffs could begin".
- Routing results to the owner through the load balancer with a server-side client: Kubernetes has no directory of owners, so every app would build one.
- A sweep (a timer re-checking records stuck in a pending state): out of place, easy to forget, and repeated on every pod. Putting the provider first, or the work in a job queue, leaves nothing to sweep.
- Twinstate tracking follow-up work and
close()waiting for it (with afollowUps()to await on several machines): framework-tracked background promises (waitUntil) belong where the platform owns the process's lifetime; in a Node server the app started the work and knows how long to wait for it. - A checkpoint (see above).
Entries need a preload; lazy reads need a handle
Rejected: useShared(kind, id) checked at render, which threw when no enclosing entry had declared the load, and a development warning for a nested entry that loaded on mount. Both were correct, but they were only visible at run time: the throw reached users, and the warning was a log. Chosen: Relay's answer, in types. A component rendered with Relay's usePreloadedQuery needs a reference only loadQuery makes, and a fragment's data is readable only through a reference its parent passes down; Apollo 3.12 added the same data masking. Here an entry renders only with the from that client.preload returns, and a lazy record is read only through the handle its entry received. Forgetting to load, or loading late, stops compiling. Rendering during render is left, which the no-preload-in-render lint rule catches, the way rules-of-hooks works; indirection it cannot see fails checkEntries.
Routes pair the preload and the render soundly, or not at all. React Router data mode's useLoaderData<typeof loader>() is a type assertion — its own maintainers and users say so — and would make "rendering needs a preload" a claim the compiler cannot back. So each router is paired the way its sound pattern does it: TanStack Router's route object, React Router's typegen, Relay-style entry points (a small twinRoute helper the app writes), or a single navigation function for routers without loaders. The guarantee is stated with those conditions, plus casts and any banned by typescript-eslint's no-unsafe-* rules.
client.preload(Entry, props), not Entry.preload(props). Statics on components have precedent (react-loadable, @loadable/component), but wrappers such as memo and HOCs drop them, and a static needs a global client, which tests with many simulated clients cannot have. Relay passes its environment explicitly (loadQuery(environment, …)), and so does this.
Entries are named (entry('note', …)) because TypeScript compares types by shape: two entries with the same props would otherwise accept each other's preloads. Kinds are named for the same reason — Id<'note'> and Id<'draft'> must not mix.
Removed after a second audit
A holistic pass, each proposal then checked by an independent reviewer against the first application's migration plan, removed these — nothing in it depended on them:
load: 'embedded'as a load strategy, and a child'sbyas alink. A kind now reaches a client exactly one way — a root (load), a child (belongsTo) or embedded (delivered only byref) — and a child'sbyis a plain parent id, since a child is always removed with its parent (alinkthat could be cleared there was a contradiction).reftoinstantkinds, which stored a second copy of an instant record inside a lazy topic.ref= owned and delivered with me;link= another root.- Relations as thunks (
link(() => note)), found when building them: TypeScript cannot type a kind that refers to itself (a folder's parent) or two kinds that refer to each other, since each one's type needs the other's (TS7022), and a type argument does not help. Relations name their target instead (link('note')), as Convex'sv.id('users')and InstantDB's links do, andregistry()checks every name against every kind. (Drizzle and Zero avoid the cycle the other way: relations declared apart from the tables, after both.) - The
outdatedanswer, and the registry fingerprint in everymutateframe. Thehellohandshake already turns away other registries, so the server only hears from its own bundle; the client checks old outbox entries itself, and strictly — a lenient parse could silently drop typed text. - The client's
screenoption. It was not part of the preload key, so a rotated phone reused the wrong loads. A column only some screens show is a sibling entry, preloaded by the navigation code that knows the layout. tx.enqueue. Nothing used it; follow-up work plusserver.mutatecovers it.render: 'fresh'(above).
One proposal was rejected on review: making records written by newer code read-only to older code after a rollback. A rolled-back application could then not set busy — silently dropping its "no second send" guard — nor save resume tokens, nor send. The stamp it would have replaced (_w, "the oldest writer") went anyway, replaced by something simpler: retired field names in the lock, which can never be reused, so newer code can always delete them on load.
Roadmap: designed to be possible, not planned
- Server-side rendering. Not supported, and not needed by an installed web app. The model does not block it: on the server, a route's loads would be read straight from the in-process Twinstate server — records and each topic's position — the page rendered with them and the snapshot embedded; the client would fill its replica from it and subscribe from those positions, which is the persisted cache's resume path ("a cache that came with the page"). It would need a server-side read API, loaders that finish before rendering, and a client core that never touches
window— a discipline worth keeping anyway. - Code splitting per kind. See scalability.
fileTransaction(), a redo journal that makes a turn over plain files atomic (see transactions).- Field selection, a subscription asking for only some fields of a kind (see concepts).
- Field encodings.
appendableis one way a field's changes travel (the new suffix); a CRDT text (a Yjs value the server merges in any order) is the next. Both sit behind one internal interface (how a change is encoded, applied and replayed), so adding one is contained; none is written by apps, whose own combining logic is a named mutation. - Scaling and integration (see scalability):
server.mutate(m, args, { key })andserver.changes(from)for bridges and change feeds;(partition, topic)addressing and a gateway; serveroutboxadapters (a Postgres table withLISTEN/NOTIFY, a Redis stream) for running on many machines; relays that project for their own connections; resets that send only what differs. - Durable streaming with batched writes: an
appendablefield kept durable, its appends broadcast from memory and written to the store in batches (every few hundred milliseconds, or per paragraph), so a crash or a move loses at most the last batch, never what was already settled. Convex's persistent text streaming works this way: it "queues chunks in memory and persists them efficiently without blocking the streaming UI updates". - A splice encoding for single-writer text: a change carries only the edited range, not the whole string, so a long text costs what was typed. It answers bandwidth for one writer at a time; concurrent editing remains the CRDT encoding's.
- Twinstate on Durable Objects: a partition per object, so the platform supplies routing, activation and single ownership (see comparison).
memoryStore()replacingmemoryOnly: memory as one more store, and a part that must not survive a restart as its own kind (see sessions and access).twinstate/postgres, a ready bridge from Postgres's change log intoserver.mutate, for apps with many writers to Postgres.- A TanStack DB collection, giving live client queries over the replica (see comparison).
No middleware
Express-style middleware (a chain of functions every request passes through) is implicit: what a handler may assume depends on what ran before it, and the chain is hard to type. Its usual jobs each have one explicit, typed place instead: authentication and request details in connect, once per connection; per-write rules in the handler, or a helper it calls; who may read and write what in the policies on every field and record, which no new mutation can forget; logging in the existing hooks (onError, onSlowTurn). Convex and Zero take the same line: a context in every function, checks written in the function.
Not a library we adopted
Many good sync engines exist; each is built around a different set of constraints. Twinstate's were: no database to replicate, one WebSocket already in place, and state in files and processes. The engines below were each built for other constraints — replicating a Postgres, bringing their own database, merging on the client — which is why none of them fit these. The honest cost of the choice: owning a sync engine, which is why the invariant suite is as heavy as it is.
| option | why not |
|---|---|
| Replicache | closest in spirit, but in maintenance mode; HTTP push/pull plus a poke; no declared lazy loading |
| Zero, ElectricSQL, PowerSync, Strata Sync | built around replicating your Postgres, most with a separate service |
| Convex, InstantDB, Triplit | bring their own database |
| Logux | an action log ordered by client timestamps (clock skew) |
| Meteor | proved the model (methods with client simulation, publications) but tied to its stack and MongoDB |
| TinyBase, Yjs, Automerge, LiveStore | CRDT or event-sourced, client-centric |
Twinstate is not a database
Twinstate keeps records in memory, sends their changes and checks their shapes; it does not decide how they are stored. Early designs grew database features — link actions on delete, cascades, reference counts for embedded records, moving unreadable files aside — and each one either assumed a storage layout (a folder per record, one file-based server) or became a second source of truth next to the store. They were removed. What stays:
- A link is a typed id. It resolves for display (an
instanttarget to the record ornull, alazytarget shown as the entry'sabsentwhen gone); what happens to it when its target is deleted is the handler's decision. - A parent's removal drops its children from memory and from every client; removing them from storage is the parent adapter's job — a folder deleted, a database cascade.
- Unreadable data is not served, is reported, and is never overwritten; repairing it is the store's business.
- Versions are Twinstate's, storage is the store's. The state version is the contract with clients, so migrating a record from one to the next is Twinstate's; where and how it is written is not.
Deliberately not built
Per-field versions and conflict policies; an operation log; transactional storage (a store may bring one); CRDTs; code splitting (see the roadmap); translating records for older clients (see running clients); per-record queue lanes; batching turns within a partition (see above); a job system, since durable job queues exist (see above). Each can be added later without changing the model.
Sources
Change tracking — Doctrine change tracking policies, Doctrine Unit of Work, Immer patches, Immer performance, Understanding Immer, How Valtio works, Hibernate dirty tracking
Replicache — how it works, global version, per-space version, row version, poke, options
Linear — reverse-engineered sync engine, How's Linear so fast?
Zero — ZQL relationships, queries, self-hosting
Work outside the queue — Akka: send future result to self, Akka cluster sharding, Convex scheduled functions, Stripe: fulfill orders, Socket.IO adapters, Discord: Maxjourney, Discord: the 25 March 2026 voice outage, Durable Objects lifecycle, Temporal: activity heartbeats, Orleans live grain migration
Memory and deploys — Rules of Durable Objects, Phoenix LiveView: deployments, Figma: making multiplayer more reliable, Convex persistent text streaming, Railway variables, Railway volumes, Fly.io configuration, Render zero-downtime deploys, Heroku dyno shutdown, Vercel WebSockets
Batching writes — Akka persistence, Akka
persistAsyncand batch writes, Akka.Persistence.SqlServer, Zero's push processing, Replicache remote mutations, Figma: making multiplayer more reliable, Hocuspocus configurationCloudflare — Durable Objects: easy, fast, correct, rules of Durable Objects
Convex — OCC and atomicity
Relay — Relay-style GraphQL
Workbox background sync, Stripe idempotent requests, Firestore offline data
AI-first — Anthropic: Claude Code best practices, Factory: using linters to direct agents, CodeRabbit: guardrails for agentic coding
Pairing routes — TanStack Router type safety, React Router type safety, Remix: useLoaderData inference, Relay loadEntryPoint, react-router-relay, typescript-eslint no-unsafe-type-assertion
Loading and masking — Relay usePreloadedQuery, Relay useLazyLoadQuery, Relay fragments, Apollo data masking, React Router type safety
WebKit tracking prevention (home-screen storage exemption), WebKit: updates to storage policy, MDN: storage quotas and eviction, web.dev: storage for the web
Multi-tab caches — Firestore local persistence, firebase-js-sdk #6511 (stale data from a non-leader tab), Replicache API
Relay — fetch policies