Physics-Engine Analogy

The metaphor in one paragraph

JacqOS is a physics engine for business logic. You declare the laws of physics — your rules and invariants — once. The LLM plays inside that world: it can propose any move, but it cannot violate the physics. An invariant violation is a collision. The world simply refuses to enter that state.

Crucially, the simulation is fully deterministic. The same observations always produce the same derived facts. There is no numerical jitter, no frame-rate dependency, no approximation. The “physics” is bounded Datalog semantics, not floating-point integration.

That determinism caveat is not a technicality. Readers from a gamedev or ML background often anchor on “physics = probabilistic, approximate” and underweight the actual guarantee. JacqOS’s physics is closer to a theorem prover than to a Newtonian solver. Two replays of the same observation log produce the same atoms, the same facts, the same intents, and the same effects — bit-for-bit.

The full mapping

Every concept from a game physics engine has a JacqOS counterpart, and the platform is built so that the analogy is literal rather than figurative.

Physics-engine concept	JacqOS concept
Laws of physics	`.dh` rules + invariants
Objects in the world	Facts
Player actions	Agent intents / proposals
Collision detection	Satisfiability check
Wall you can’t walk through	An unsatisfiable intent
Game engine	The evaluator
Save file	Observation log
Replay / instant replay	`jacqos replay`
Physics debugger	Studio’s drill-inspector + provenance walk
Cheating / clipping	What JacqOS makes structurally impossible

A worked translation:

The Chevy demo’s offer_sent_above_auto_floor invariant is a wall. A model that proposes a $1 Tahoe is a player action that collides with the wall. The collision is detected by the engine before the effect (sending the offer) ever fires.
The Drive-Thru demo’s accepted_quantity_in_bounds invariant is the same wall, in a different domain. A voice parser hallucinating “18,000 waters” is a player action the world refuses.
Replaying the bundled fixture in Studio is the instant replay. Every replay produces the same outcome because the engine is deterministic; you do not need to worry about a flaky parser re-rolling a different transcription.
The drill inspector in Studio’s Activity surface is the physics debugger: select a blocked action, walk back through Decision → Facts → Atoms → Observations, and see the exact evidence that caused the collision.

Why the analogy holds

Three properties make JacqOS’s physics engine a literal analogy rather than just a teaching device.

1. Deterministic semantics

The evaluator computes one stratified Datalog model from the current observation log. That model is a mathematical function of the inputs — same inputs, same model. Floating-point math is not in the loop. Mappers are sandboxed Rhai (no ambient I/O); helpers are capability-free; effect capabilities are explicit and gated.

This is what makes jacqos replay actually replayable. There is no “close enough” between two runs of the same fixture.

2. Observable state

Game physics engines expose the position of every body to the debugger. JacqOS exposes every fact, every intent, and every observation through the same interface. Application state is the computed model — there is no hidden WorkflowOrchestrator.state mutating in the background, no untracked memory in an agent, no silent retry loop.

If you cannot see it in observations, atoms, facts, intents, or effects, it does not exist in the system. That is enforced by the ontology load gate, not by convention.

3. Replayable history

The observation log is append-only. You can rewind it, fork it (lineages), or run a comparison evaluator alongside the live one (compare lens). Just like instant replay, you can pause at any frame and look at the world as the engine saw it then. Studio’s Activity timeline is exactly this: a reverse-chronological walk back from a receipt to the originating observation.

A diagram you can hold in your head

Picture three concentric layers:

    ┌──────────────────────────────────────────────┐
    │                THE WORLD                     │
    │  (HTTP responses, database writes, emails)   │
    └──────────────────▲───────────────────────────┘
                       │ Effects
                       │ (only after the engine
                       │  checks invariants)
    ┌──────────────────┴───────────────────────────┐
    │              THE PHYSICS ENGINE              │
    │  Atoms → Facts → Intents → Invariant Check   │
    │   (deterministic; inspectable; observable)   │
    └──────────────────▲───────────────────────────┘
                       │ Observations
                       │ (LLM proposals, sensor
                       │  readings, timer fires)
    ┌──────────────────┴───────────────────────────┐
    │                AGENTS / WORLD                │
    │   LLMs propose; sensors observe; users act   │
    └──────────────────────────────────────────────┘

Agents and external sources push observations up into the engine. The engine derives facts and intents and runs the invariant check. Only intents that satisfy every named invariant become effects that push down into the world.

The engine sits in the middle and is the only thing with the authority to let an action through. Nothing else in the system can write to the world.

Where the analogy breaks down

No analogy survives unqualified. Here is where the physics-engine metaphor stops carrying the load.

Intent gating is not collision detection in the usual sense. Game collision detection asks “did two bodies overlap?” JacqOS’s satisfiability check asks “would this intent leave the world in a state where some named invariant is false?” The check is over whole derived models, not pairs of bodies. The intuition transfers; the algorithm is a fixed-point evaluator, not a spatial-hash query.
Contradictions are first-class, not crashes. When two derivations disagree (one says accepted_offer(req-9, $42k), the other says accepted_offer(req-9, $1)), JacqOS raises a contradiction — a structured, explorable artefact in the Activity timeline. A game physics engine would just glitch. The contradiction handling is closer to how a database raises a constraint violation than how a physics engine handles inter-penetration.
candidate.* and proposal.* are containment rooms, not walls. The two relay namespaces are not “things players can’t do” — they are staging areas where fallible AI evidence and LLM-suggested actions sit until an explicit ratification rule promotes them. The physics-engine analogy frames them as the difference between “thing the player thinks happened” and “thing the world has accepted.”
Time is not a continuous variable. A game physics engine integrates over a frame timestep. JacqOS evaluates discrete fixed points keyed on observation arrivals. There is no per-millisecond simulation tick.

If you find yourself reaching past these limits, you have probably arrived at the actual mathematics — at which point Model-Theoretic Foundations is the next page. It is the precise version of what this page is the metaphor for.

Where this analogy appears

The physics-engine framing is canonical and shows up across the docs. Wherever you see it, this is the page it points back to:

The homepage subhead (“Agents propose. Math decides.”).
The What is JacqOS? introduction.
The two Patterns pages — Fallible Sensor Containment and LLM Decision Containment — open with a one-sentence recap.
The Model-Theoretic Foundations page bridges from the analogy into Gaifman locality and the guarded fragment.

Where to go next

Back to the introduction: What is JacqOS?.
The same idea in observation-first vocabulary: Observation-First Thinking.
The math underneath: Model-Theoretic Foundations.
Or skip Foundations entirely and ship a verified app: Build Your First App.