The principle behind Vivarium fits on one line. The AI controls expression. The application controls reality. This post is what that line means in code, for one turn.

The problem with letting the narrator decide

In most AI roleplay, one model does everything. It reads your message, decides whether you picked the lock, decides how the guard feels about it, and writes the paragraph. Those are three different jobs, and a language model is only good at the last one. It wants the scene to go well. It has no memory of the lock’s rating because there is no lock, only the word “lock” somewhere above in the text.

So Vivarium takes the first two jobs away from it.

Five stages

A turn runs through five named stages in the application.

Prepare. The application loads the scene as it stands: where your character is, who is present, what they carry, what each character in the room knows. This comes from the database, not from the transcript.

Interpret. You write in your own words, so something has to work out that “I lean on the door until the frame gives” is an attempt to force a lock. That is a model call, but a narrow one. It must answer in a strict format, and the answer is validated like any other untrusted input before the application acts on it.

Decide. This stage has no model in it. A pure function takes the inputs, which are your character’s skill, their conditions, the difficulty, and for another character their goals, fears and how they feel about you. It rolls, and it produces a result: success, a failure with a complication, a refusal, and so on. Then the application writes down what changed. An item moved. A condition appeared. An opinion shifted. Every change goes into a ledger in the same transaction, with its cause and with what is needed to reverse it.

Narrate. Only now is the narrator called. It receives the decided outcome and the state changes as reference data. It does not receive the roll, the threshold or the odds, so it has nothing to argue with. Its job is to write what happened, well, in every character’s own voice.

Judge. For outcomes that bind, such as an attack, a refusal or a failure, a third model call reads the prose and answers one question: does this contradict the outcome. If it does, the narration is rejected and never stored. The decision, its consequences and the ledger all stand. You can ask for the narration again. You cannot get a different result by asking.

One detail I am glad I got right early: no database transaction ever spans a model call. The world is never left half-written while the application waits on a provider.

What falls out of this

You can take a turn back. The ledger is the single way state changes are reversed, so retracting a turn is not a guess about what to undo. It replays the recorded reversals. The coin goes back in the purse, the bruise disappears, the guard’s opinion returns to what it was.

Nothing the model writes becomes true on its own. If the narrator mentions a sword nobody owns, there is still no sword. Prose is output. It is never input to the state of the world.

Numbers are authoritative and labels are presentation. Underneath, a skill is a number. On the screen you see a band with a name. The narrator sees the band too, and never the number, which keeps digits out of the story.

Failure makes story. A failed check is a result with consequences, often a complication, not a dead end. Even the death of your character with no companion left does not end a story irreversibly, because the killing turn can be retracted.

What it costs

A turn that carries a decision makes three model calls: interpret, narrate, judge. A turn that is only talk makes fewer. That is more than a single-call chat, and it runs on your own provider key, so I would rather say it plainly. It is the price of a world that holds together, and the application records the token usage of every call so you can see it.

When the judge itself returns something unreadable, the narration stands and the audit trail says so. A broken referee should not stop the game.

The full list of what is built, phase by phase, is on the roadmap.