Learn / Events, folds and gates

One Message is both request and fact

Some event-sourced architectures separate an incoming command from multiple emitted domain events. In foldkit-sync, the client proposes CreatedTodo and the server commits that exact CreatedTodo Message (or rejects it).

Messages that only the server may originate are marked serverOnly and appended with appendAsServer; follow-up side effects after a commit run as reactions (The server's own writes). If your workflow requires one command handler that emits several distinct domain events or runs a multi-step server process, model that logic on the server instead of foldkit-sync.

Choosing document boundaries

Any fold can produce a read view, but a Sync document can only enforce a law when its own state holds everything needed to check that law:

A rule can be enforced where one document's snapshot is enough to judge it.

A 100-todo limit belongs on the todo list document because the list holds all its todos. A globally unique username does not fit on an individual user's document because checking uniqueness requires reading every other user. See Choosing document boundaries for ways to give cross-record rules a proper owner.

Schema changes and compaction

Because durable Messages and snapshots persist across deploys:

  • The local Model is ephemeral; a fresh build starts cleanly from initial.
  • Durable Message schemas sit in offline outboxes and server journals across releases; evolve them with explicit migrations (Changing a durable Message).
  • Shared slice schemas live in stored snapshots and checkpoints.
  • Compaction discards old Messages: When a journal compacts past an offline replica's cursor, that replica adopts a compacted checkpoint (the folded state) rather than replaying ancient Messages.

Limits

  • The local Model has no gate before update; ignore disallowed UI actions inside update.
  • foldkit-remote rows keep no event log by default; write an explicit audit Entity or edit rows through a journal when history is required.
  • Neither package builds arbitrary new read models by replaying every historical event from scratch on demand.

Background

The rule that a coarse-grained document acts as a self-contained boundary only when its own state closes over its transitions follows Rosas et al., "Software in the natural world: A computational approach to hierarchical emergence" (arXiv:2402.09090).

Next