Living Documents

I have built microservices. I have debugged microservices at 3 AM. I have watched cascading failures take down an entire product because one service in the mesh decided to return 503s and every dependent service dutifully propagated the misery. After enough of these experiences, I started asking a different question: what if each unit of backend state was a tiny, self-contained virtual machine that processes messages sequentially, persists automatically, and sleeps when idle?

That is the living document model. It eliminates the microservice coordination problem not by solving it, but by making it structurally unnecessary.

The First Experience of Writing Code

Think about the first time you wrote a program. You took inputs, did things, produced outputs. It was joyful. Then you hit persistence: how do I save this state to disk? Suddenly you are marshalling data, handling partial failures, managing connection pools, thinking about ORM impedance mismatches. The joy evaporates.

The living document model returns to that first experience. You write code that manipulates state directly. The runtime handles persistence. You never call save(). You never think about transactions. You never manage a database connection. The entire document -- code plus data -- is a single unit:

record Todo {
  public int id;
  public string text;
  public bool completed;
  public principal owner;
}

table<Todo> todos;

channel create(CreateTodo msg) {
  todos <- { text: msg.text, completed: false, owner: @who };
}

This is both the schema and the logic. There is no separate database. There is no ORM. There is no connection pool. The state lives alongside the code that manipulates it.

The Sleeping VM Model

Each Adama document is a virtual machine with a specific lifecycle:

1. Sleep: The document exists as a snapshot on disk. It consumes zero CPU, zero memory. It could stay here for years.
2. Wake: When the first user connects, the runtime loads the snapshot into memory and restores the state.
3. Process: Messages arrive -- user actions, timer events, connection events. Each message is processed sequentially, state changes are captured as differentials, differentials are persisted to a write-ahead log, and per-viewer deltas are sent to connected clients.
4. Sleep: When all users disconnect (or after an idle timeout), the document returns to disk.

This is not an analogy. It is the actual architecture. The lifecycle is managed through hooks: @construct runs when a document is created (initialize state, validate creator access), @load runs when a document wakes from disk, @connected fires when a viewer connects (return true to accept, false to reject), and @disconnected runs cleanup when a viewer leaves.

The questions that matter all have good answers: How many documents can a server host? Thousands -- sleeping documents cost nothing. How fast does a document wake? Milliseconds -- it is loading a JSON snapshot. How much does persistence cost per operation? One append to a WAL -- the same cost as a database write, because it is a database write.

Sequential Processing: The Freedom of Constraints

Each document processes messages one at a time. If three clients send messages simultaneously, those messages queue and execute sequentially:

This is the actor model. No locks. No concurrent access to document state. No race conditions. No deadlocks. I cannot overstate how much pain this single design decision prevents. Every distributed systems bug I have ever debugged at 3 AM involved some form of concurrent state mutation.

The constraint is obvious: a single document cannot process more than one message at a time. But human input rate is measured in messages per second, not millions. A board game, a chat room, a collaborative editor -- these generate maybe 10-100 messages per second at peak. A single thread can handle thousands. The bottleneck is never CPU; it is the speed of human thought.

Every message is an atomic transaction. If anything goes wrong -- a validation failure, an abort -- the entire transaction rolls back. Clients never see partial state. The code is simple because it executes in a simple context:

channel complex_operation(ComplexMsg msg) {
  score += 10;

  if (score > max_score) {
    abort; // ROLLBACK -- score is unchanged
  }

  achievements <- { name: "High Score" };
}

Either all changes commit, or none do. You do not appreciate this until you have spent a week debugging a partially-committed transaction in a system that does not provide this guarantee.

Why This Eliminates the Microservice Problem

The microservice architecture solves a people problem: how do you let independent teams ship code independently? It solves this at a steep technical cost. Every inter-service call can fail. Every failure must be handled. Retries create duplicates. Timeouts create ambiguity. Distributed transactions are either unavailable or horrifically complex.

Microservice Architecture

#player_turn {
  future<DrawCount> request = how_many_cards.fetch(current_player);
  DrawCount response = request.await();
  // execution pauses until the player responds
  transition #play_phase;
}