Observation-First Thinking

Note

What this corresponds to in the product. Every row in Studio’s Activity surface, every layer of the drill-down inspector, and every line of your .dh rules is a read of the same underlying observation log. If you ran the bundled demo, you have already seen the pipeline in action. This page names the parts.

If You Followed The Start Section, You Already Understand JacqOS

Foundations is for going deeper. Nothing here is a prerequisite. You can ship a verified, pattern-aware app without loading a single Foundations page.

That said — if you want to understand why the containment holds, this is where it lives.

The Single Pipeline

Every JacqOS app flows through one pipeline:

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

Each stage is explicit, deterministic, and traceable.

• Observations are append-only evidence that something happened. A webhook arrived. A timer fired. An LLM returned a completion. A sensor produced a reading. Once written, an observation never changes.
• Atoms are structured evidence extracted from each observation by a Rhai mapper. The mapper is a pure function of one observation — it cannot call the network, read files, or remember previous observations.
• Facts are derived truth. Datalog rules read atoms and other facts and produce new facts with full provenance back to the supporting observations. Facts can be asserted or retracted, and every retraction records exactly which rule withdrew the truth.
• Intents are derived requests to act on the world. An intent.* fact means the ontology wants the shell to perform an external action. Intents are not the action — they are the declarative request.
• Effects are the shell’s execution of intents. Effects use declared capabilities: HTTP fetch, LLM completion, blob storage, timer scheduling. Each effect produces new observations, closing the loop.

The critical property: you can replay any observation log on a clean database and get the exact same facts, intents, and effect receipts. Reproducibility is not an aspiration; it is a structural guarantee of the logic fragment the platform accepts.

Why This Enables Containment

The pipeline is useful on its own. It is transformative when combined with two reserved namespaces:

• candidate.* for fallible-sensor evidence that requires acceptance before becoming accepted truth.
• proposal.* for fallible-decider output that requires ratification before becoming an executable intent.

These two namespaces are the subject of the Patterns section. They are enforced mechanically at load time: any rule that tries to derive accepted truth or executable intents from requires_relay-marked atoms without routing through the appropriate relay is rejected. The safety boundary is not a policy layer on top of the platform; it is built into the logic fragment.

What To Read Next (Optional)

Every Foundations page back-references the UI, so you can see where you already met each concept.

• Atoms, Facts, Intents — detailed walk-through of each plane with provenance examples
• Invariant Review — how invariants replace code review of AI-generated rules
• Golden Fixtures — deterministic input timelines as cryptographic evidence for behaviour
• Lineages And Worldviews — observation histories and evaluator identity
• Model-Theoretic Foundations — Gaifman locality, CALM, stratified fixed-point semantics
• dh Language Reference — the exact Datalog fragment the platform accepts