What is JacqOS?

The metaphor

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 the evaluator refuses any transition that violates the declared invariants. An invariant violation is a collision; the world simply refuses to enter that state.

Unlike a game physics engine, 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 a bounded Datalog semantics over a finite, ordered observation history.

That is the whole product in three sentences. The physics-engine analogy page takes the metaphor end-to-end with a full mapping table. The rest of this page tells you what it means for the apps you build.

What it means for your app

You write three things and only three things:

Invariants — declarative constraints that must always hold. “No double-booking.” “No refund above $500 without a manager approval.” “No offer below the auto-floor price.”
Mappers — short Rhai functions that turn raw observations (HTTP webhooks, LLM responses, voice parses) into structured atoms.
Rules — Soufflé-flavored Datalog that derives facts and proposes intents from those atoms.

The platform handles the rest. Every observation flows through one deterministic pipeline:

Observation → Atoms → Facts → Intents → Effects → (new Observations)

Agents query the same derived facts. They never share hidden state, never mutate each other through orchestration graphs, and never execute an action without the engine first checking that the fixed evaluator and current lineage satisfy every named invariant.

Two containment patterns the platform is built around

JacqOS handles AI fallibility through two structural patterns. They are not best practices; they are enforced at load time.

Fallible sensor containment. Voice parsers mis-hear. Vision models mis-label. LLM extractors hallucinate. The platform routes every fallible-sensor output through a candidate.* staging area. Nothing downstream that depends on accepted truth can fire until a promotion rule — written in plain Datalog — explicitly accepts it.
LLM decision containment. An LLM proposes an action — a refund, an offer, a remediation. The proposal lands in the reserved proposal.* namespace. Only an explicit domain decision rule that ratifies the proposal can derive an executable intent.*. Models cannot drive effects on their own.

If a rule tries to derive a fact or fire an intent that bypasses either relay, the platform rejects the program at load time. The boundary is mechanical, not cultural.

What humans review, what the AI writes

AI agents are excellent at generating Datalog rules. Humans are bad at reviewing dense AI-generated logic line by line. JacqOS realigns the review surface around two artefacts that humans can meaningfully review:

Invariants. A handful of named declarative constraints. Anyone on the team can read invariant accepted_quantity_in_bounds(order) and know what it asserts. The engine checks the derived model against every named invariant after each fixed point; if a transition violates one, that transition is rejected before effects execute.
Golden fixtures. Concrete scenarios with expected derived state. JacqOS replays them deterministically against the current ontology and exports a verification bundle.

This puts the authoring loop on a familiar footing. Fixtures map directly onto Behavior-Driven Development (BDD) scenarios:

Given → prior observations in the fixture
When → the new observation under test
Then → the expected derived facts, intents, or invariant state

If you have written BDD scenarios before, you have written JacqOS golden fixtures. The golden fixtures page documents the format.

Invariants and fixtures are complementary halves of the authoring loop. Invariants assert what must be true across every scenario. Fixtures assert what the system must produce in specific scenarios. The platform reviews both for you on every change. You review the specifications, not the generated code.

What you actually see in JacqOS Studio

Studio ships three destinations in V1: Home, Activity, and Ontology. It is not yet a visual rule-graph IDE.

Home. A workspace identity header and a list of bundled scenarios you can replay against the loaded evaluator.
Activity. The operator’s working surface. Three tabs — Done, Blocked, Waiting — over a dense list of recent agent actions in domain language. Click any row to open the drill inspector — a three-section surface (Action, Timeline, Provenance graph) that walks you backward through the receipt, the events that led to it, and the rule-and-observation chain that produced them.
Ontology. A strata browser that groups your relations by evaluation stratum and surfaces a relation-detail inspector. The visual rule-graph view is on the V1.1 roadmap, alongside dedicated mapper and schema inspectors.

When the bundled Drive-Thru or Chevy demo blocks an action in Studio, the Blocked tab shows the blocking invariant and the drill inspector walks you back to the exact observation that tried to produce it. That is the whole “AI proposed something dangerous; the math refused; here is the receipt” loop, in product.

The precise version

Every JacqOS app is a stratified Datalog program over an append-only observation log. The platform evaluates one ordered finite model and exposes its provenance. Names with intuitions:

Observations are immutable evidence — the only canonical truth surface.
Atoms are the deterministic flattening of one observation into semantic evidence (a tiny tuple per fact).
Candidates and Proposals are reserved relay namespaces (candidate.*, proposal.*) for non-authoritative model output that requires explicit ratification before it can support facts or intents.
Facts are the stable model of the program — the least fixed point under the program’s stratified Datalog semantics.
Intents and Effects form the execution lifecycle: intents are derived requests for action; effects are intents the shell actually executes through declared capabilities.
Invariants are named integrity constraints checked after every fixed point. A transition whose resulting model does not satisfy those constraints is rejected before any effect fires.

That formal foundation is what makes the physics-engine analogy literal rather than figurative: collisions are unsatisfiable transitions for a fixed evaluator and lineage, replay is determinism, and “follow provenance” is a walk through the witness graph the evaluator already maintains. The Model-Theoretic Foundations page covers rule shapes, Gaifman locality, namespace reducts, and composition analysis — with optional pointers to the formal treatment in MODEL_THEORY_REFERENCE.md.

Now go see it run

Reading is one thing; watching JacqOS reject a $1 Tahoe offer is another. Three branches from here, all optional, none required for the others.

Try the demo. Getting Started installs the binary and walks you through the bundled scenarios in Studio. No API keys, no configuration. After the demo, What You Just Saw recaps it in plain language.
Pick a pattern. Each containment pattern is documented end to end with the real-world failure, the structural guarantee, and the code: Fallible Sensor Containment, LLM Decision Containment.
Understand why. The physics-engine analogy page extends the metaphor end-to-end and links into Model-Theoretic Foundations for the precise math.

When you are ready to ship your own, Build Your First App scaffolds a verified agent in one command — pattern-aware, fixture-backed, and ready to hot-reload.

The Glossary defines every JacqOS term in one page — handy when something on this site uses a word you have not seen before.