TarskiTarski/ docsJoin the waitlist

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.