0
Kai Detmers
← Project index
Simulation R&D · native iOS + backendRelease gated

Civils— probabilistic citizens, deterministic world.

A living-world architecture where models can author citizens, memories and cultural material but cannot bypass canonical state transitions. The world remains replayable and server-authoritative while the native client tries to make a complex simulation feel inhabited rather than administered.

Stack

Canonical backendPython · FastAPI · pure WorldKernel
PersistencePostgreSQL · pgvector · Alembic
Derived stateRedis · rebuildable projections
Native clientSwiftUI · RealityKit · iOS 18 target
AI / memoryOpenAI Responses · local / Mem0 adapter
Qualityreplay · fault tests · culture/memory evals · soak

How it evolved

Reconstructed from commits, quality reports and the current release matrix. Some product rationale is inferred from the sequence of implementation changes.

01
Build a deterministic world before intelligent characters.

The foundation is a typed command → pure kernel → replayable transition loop. That makes simulation correctness independent from whichever model or memory provider happens to be active.

02
Put AI behind adapters, not inside the state machine.

Citizen authorship and memory became provider capabilities that can propose logical effects. They are deliberately denied a second mutation path around canonical state.

03
Make citizens and institutions programmable.

Behavior programs and institution/meta-program capabilities pushed the system beyond generated dialogue. Citizens could participate in a world whose rules and social structures are inspectable system state.

04
Redesign the client around the world, not the backend.

A major UI pass changed test IDs and design-system expectations because the native surface needed to foreground the planet, citizens and current activity rather than mirror simulation tables.

05
Multi-planet ownership changes navigation.

Once accounts could own several independent worlds, planet switching and creation became a dedicated information-architecture layer rather than another button inside one world view.

06
Turn quality into release evidence.

Replay, fault injection, culture/memory evals, dynamic type checks, capture manifests, thermal/performance gates and the release matrix make “blocked” an explicit engineering state rather than an embarrassing footnote.

World UI rationale

Show life before controlsThe primary screen should answer “what is happening in my world?” before exposing management actions. Chronicles, citizens and construction/activity state carry the simulation emotionally.
Progressive disclosureA simulation this deep cannot put economy, memory, culture, institutions and diagnostics on one dashboard. World-level state stays legible while detail lives behind contextual drill-down.
Planet is a top-level objectMulti-world ownership means switching worlds is equivalent to switching workspaces, not switching tabs. Creation/capacity belong beside the planet selector.
Fixed-seed captureGenerative worlds make random screenshots poor regression evidence. UI tests and capture paths use fixed seeds so a changed composition can be compared meaningfully.
Accessibility before cinematic polishDynamic Type, stable identifiers and semantic structure are release concerns. RealityKit spectacle is secondary if the underlying world state cannot be navigated or tested reliably.

Canonical mutation loop

CommandTyped envelope carries expected version and idempotency context.
KernelPure WorldKernel validates and decides a replayable transition using integer ticks and keyed deterministic seeds.
CommitEvents, normalized state, projection delta, snapshot and idempotency result are persisted together.
ProjectionClients receive privacy-limited views; derived Redis state remains rebuildable.
ProvidersAI and memory are non-authoritative adapters with provenance and deletion semantics.

Why no product screenshot yet

There is real screenshot/capture infrastructure in the repository, including fixed-seed UI tests and a capture manifest. The project's own quality gates still mark the supported device capture path as incomplete. I keep that status visible instead of publishing a simulator/mock image and calling it release evidence.

Replayablecanonical state survives retry and bounded catch-up
Evalledculture and memory behavior have explicit evaluation paths
Blockeddevice, provider and Apple-environment gates remain honest release blockers