How GenOS works

How GenOS works

GenOS models execution as a sequence of immutable checkpoints and explicit state transitions around an Agent–World Capsule.

1. The capsule is the execution boundary

Conceptually:

C = <G, S, W, H, B>

Symbol	Component	Meaning
G	Genome	Stable agent blueprint: role, drives, permissions, objectives, policies
S	State	Working memory, beliefs, goals, cursors, and other evolving cognitive state
W	World	The logical, directory-backed, or Git-worktree environment the agent can affect
H	History	Append-only events describing state transitions and tool activity
B	Budget	Remaining steps, time, tokens, or cost constraints

This separation is important. A prompt alone cannot explain which filesystem was mutated, which events were already observed, or how much execution budget remained.

2. A snapshot freezes a meaningful baseline

A snapshot binds the relevant capsule state to an immutable identifier and parent relationship. Local stores use content-addressed artifacts and integrity digests where supported.

active capsule C0 ── snapshot ──> immutable snapshot S0

Snapshots make restore, fork, diff, lineage, and offline state replay possible. They also make it explicit which data was not captured—for example, an uncontrolled network service or a provider-side model implementation.

3. Fork creates sibling futures

Forking creates branches with distinct identities and event streams, starting from common ancestry:

                       ┌─ capsule A: hypothesis “minimal patch”
snapshot S0 ── fork ───┼─ capsule B: hypothesis “refactor boundary”
                       └─ capsule C: hypothesis “invalidate assumption”

For directory or worktree worlds, each branch receives its own mutable world substrate. Shared immutable ancestors can be deduplicated; writes remain branch-local within the implemented world boundary.

4. Run executes under a budget and records events

Each bounded step can:

• invoke an allowed tool or command;
• mutate branch-local state or world files;
• append a structured event;
• consume execution budget;
• produce tainted or verified output;
• trip a circuit breaker or terminate the branch.

The resulting branch is not just an answer. It is an outcome plus a history of how that outcome was produced.

5. Evaluation compares evidence

Candidate branches can be scored by one or several objectives. Examples in the repository cover test outcomes, structured candidate scores, Pareto selection, explicit winner promotion, and recursive budget allocation.

candidate outcomes
      │
      ├─ correctness gate
      ├─ safety invariants
      ├─ cost / token / time observations
      ├─ semantic or structural divergence
      └─ human or policy review
      │
      └─ selection decision

GenOS does not require every experiment to collapse into one scalar score. A Pareto frontier can preserve non-dominated trade-offs for later judgment.

6. Diff explains divergence

A diff may include several dimensions rather than only files:

• world-tree changes;
• agent-state changes;
• belief confidence shifts;
• goal transitions;
• execution outcomes and receipts;
• ancestry and branch metadata.

This makes “branch B won” less opaque: the system can show what was different and which evidence mattered.

7. Replay verifies supported state reconstruction

GenOS replay folds recorded events over a known starting state:

S0 + [E1, E2, E3, …, En] ── reducer ──> Sn

Replay does not need to call the model again when reconstructing supported recorded state. This is not the same as rerunning every external side effect. See Isolation, replay & provenance for the boundary.

8. Promotion or merge creates the next accepted state

There are two distinct outcomes:

• Winner promotion: accept one branch after its replay and gates match.
• Cognitive merge: synthesize selected evidence or compatible state under an explicit merge manifest.

Neither should be an unreviewed union of every branch. The merge keeps lineage and records why information moved into the accepted state.

The ten canonical operations

init → snapshot → restore → fork → mutate → run → diff → merge → lineage → replay

These operations form the core lifecycle exposed through the Rust runtime, CLI, and initial MCP surface. Continue with Core concepts for the vocabulary and Architecture for the implementation layers.