​

Why NodalMerge

NodalMerge is a local-first distributed state engine built around immutable operations — replayed deterministically into programmable projections. While NodalMerge uses CRDTs, synchronization, and local-first replication, those are implementation techniques rather than the product itself — much like describing Git as “a SHA-1 database” explains part of how it works but not what it enables. Most systems revolve around mutable state: a document or row that gets overwritten in place, with conflicts patched heuristically after the fact. NodalMerge instead treats operations as the primary primitive. State changes are appended as immutable, hash-linked nodes; state itself is a projection materialized from replaying those operations — deterministically, verifiably, and on demand at any point in history. From that single model come snapshots, branching, replay, auditing, replication, and deterministic synchronization — not as separate subsystems, but as natural consequences of representing state as immutable operations. That gives developers one consistent model for collaboration, offline operation, synchronization, historical replay, and verification, instead of stitching together separate technologies for each concern. NodalMerge is built for products that need low-latency collaboration without giving up deterministic correctness. If your team is building editors, operational consoles, multiplayer workflows, or AI-assisted workspaces, NodalMerge gives you a replayable state graph instead of fragile last-write snapshots.

​

Where it fits best

NodalMerge is a strong fit when you need:

• Multi-writer collaboration with frequent concurrent edits
• Local-first UX with offline writes and later convergence
• Replayable history for debugging, audit, and deterministic recovery
• Fine-grained room and path capability controls

It is usually not the right first choice for:

• Simple request/response CRUD apps with no collaboration
• Workloads where eventual consistency is unacceptable
• Teams that do not want to run stateful sync infrastructure

​

Decision shortcut

Use this fast rule:

• If your product requires collaborative correctness, offline-first UX, and replayable trust, NodalMerge is likely a strong fit.
• If your product is primarily single-writer CRUD with no collaboration pressure, a simpler real-time stack is often faster to ship.

​

Core advantages

​

Deterministic convergence

NodalMerge resolves identical history into identical state on every peer. You reconcile history, not ad-hoc snapshots. This makes divergence easier to reason about and test.

​

Local-first by default

Clients can accept writes locally, then sync and merge when connectivity returns. This improves perceived performance and resilience in unstable networks.

​

Replayable DAG history

Transactions form a directed acyclic graph. You can:

• Reconstruct historical states
• Debug merge outcomes from first principles
• Verify behavior across runtime and host implementations

​

Speculative and authoritative lanes

You can separate optimistic intent from canonical accepted state, then converge both lanes in one model. This is useful when policy validation or server-side simulation decides final outcomes.

​

Capability-scoped access

Room tokens can encode path-scoped capabilities such as read:world/** and write:intent/**. That lets you keep collaboration broad while still controlling who can mutate sensitive namespaces.

​

How it compares to simpler sync models

Many systems replicate a mutable document snapshot and patch conflicts heuristically. NodalMerge instead persists immutable operations in a graph, then deterministically materializes state. You trade some conceptual complexity for stronger replay, audit, and merge guarantees.

​

Typical adoption path

Most teams adopt in stages:

1. Start with one room and core map/text/list workflows
2. Introduce intent/canonical separation for sensitive flows
3. Add capability-scoped governance where needed
4. Add operator lifecycle and replay tooling before scale

This staged approach reduces risk and keeps complexity proportional to product needs.

​

Operational posture

Running NodalMerge in production means planning for:

• Room lifecycle and persistence policy
• Blob storage and garbage collection windows
• Metrics, SLOs, and replay tooling for incident response
• Token minting and capability policy management

If your product requires those controls anyway, NodalMerge gives you an explicit architecture instead of hidden complexity.

​

Decision checklist

Choose NodalMerge when most answers are “yes”:

• Do you need concurrent multi-user editing?
• Do you need offline-capable writes?
• Do you need deterministic replay for debugging and trust?
• Do you need policy-scoped collaboration across namespaces?
• Do you expect product complexity to grow over time?

If the answers are mostly “no,” a simpler real-time stack may be faster to ship.

​

Next steps

• Run quickstart for an end-to-end baseline
• Read architecture/overview for system-level understanding
• Read operators/server-setup for production posture
• Review operators/security-and-auth for deployment hardening
• Review api-reference/websocket-commands for command-level integration