The observation-first pipeline
Observations are the only canonical evidence of what happened, and everything Tarski believes or does is computed from an observation history under one evaluator.
Tarski is organized around one rule: observations are the only canonical evidence of what happened. There is no hidden workflow graph that owns truth. Workflow-like views in the CLI or Studio are read models over observations, atom batches, derived tuples, intents, effects, and provenance.
observations → typed atom inbox → deterministic evaluator → intent outbox → effects → new observations
Because every stage is computed from recorded observations, you can replay, audit, and check AI-assisted behavior.
The durable surfaces
- Observations: append-only evidence that something happened. The observation log is the canonical truth surface.
- BlobRefs: content-addressed handles for large raw payloads, referenced from observations. See Storage.
- Typed atom batches: deterministic mapper output for one observation. Atoms are the ontology’s inbox. They are not trusted facts by themselves.
- Derived tuples: evaluator output in one fixed point, including candidates, proposals, decisions, trusted facts, intents, inspection relations, and retractions.
- The intent outbox: the committed
intent.*relations that effect admission may read. - Effects: admitted request and attempt lifecycle records for committed intents, plus receipts that re-enter the lineage as observations.
Reserved namespaces
The Tarski language reserves namespaces that enforce the separation between evidence and
truth:
| Namespace | Role |
|---|---|
source.* |
Base evidence extracted from observations by mappers |
candidate.* |
Fallible fact-domain evidence; requires decision.accepted.* before it can support trusted facts |
proposal.* |
Fallible action-domain evidence; requires decision.approved.* before it can support world-facing intents |
decision.* |
Deterministic adjudication: accepted, refuted, approved, rejected, requires_review |
intent.* |
Committed action requests, derived only through decision gates |
helper.* |
Capability-free pure helper calls |
queryresult.* |
Runtime-populated agent read evidence, gated like relay evidence |
The loader enforces this with relation-level graph cuts. Every positive path from fallible
relay evidence to a trusted fact must cross decision.accepted.*, and every positive path
from fallible relay evidence to a reviewed world-facing intent must cross
decision.approved.*. The loader checks this at load time, before anything runs.
Facts, decisions & intents describes the full model.
Reads follow the same pipeline
An agent that wants to read the worldview proposes a declared query
(proposal.query_requested), a decision rule ratifies it, intent.query_execute admits
it, and the worldview.query effect executes it. The result re-enters as an observation.
Spectator reads (API, MCP, Studio, CLI) do not touch the lineage at all; they are recorded
in a separate access-audit plane. See the agent query relay and
Declared queries.
Where every behavior lives
When you build an app, decide where each behavior lives in the pipeline. You can use the same table to debug:
| Question | Pipeline answer |
|---|---|
| “What happened?” | An observation, or a blob referenced by an observation |
| “What did the mapper understand?” | A typed atom batch derived from one observation |
| “What is provisional evidence?” | candidate.* or proposal.* awaiting deterministic decision |
| “What does the system believe?” | A trusted app-defined fact derived by the evaluator |
| “What was decided?” | A canonical decision.<outcome>.<domain>.<subject> relation |
| “Why does it believe that?” | Provenance traces it back to observations |
| “What does the system want to do?” | A committed intent.* outbox relation |
| “What touched the world?” | An effect attempt and receipt tied to an admitted intent |
If a user-facing behavior looks wrong, find the surface that is wrong first. A bad observation is an ingestion problem. A missing atom is a mapper problem. A wrong fact or decision is an ontology or helper problem. A missing intent is usually a decision graph-cut, review-routing, invariant, or policy problem. A wrong external action is an effect admission or authority problem.
Why this shape exists
Tarski is a platform for building expert systems. Your domain expertise runs as rules on a deterministic engine, and every decision traces back to the inputs that caused it. The people who review your app inspect invariants, fixtures, and provenance; they do not have to read AI-generated rule code line by line. That review works only if truth is derived from deterministic evidence and every action has a visible route back to observations, so the observation-first pipeline is both the runtime architecture and a product promise. Tarski computes state from observations and never mutates it.