# Donto — the Epistemic Operating System for Agents (iteration 5, 2026-06-10)

> **Status: CANONICAL direction document** (supersedes-but-includes the abundance framing as its
> substrate layer). Captured verbatim from the operator's direction of 2026-06-10. The execution
> order is explicit: **infrastructure and versioning first, documented end-to-end**, then the
> agent-native / science-native / discovery-native layers.

> **The thesis in one line:** *Donto is not a knowledge graph. Donto is the operating system for
> contested reality.*

---

## The direction: make Donto the **epistemic operating system for agents**

The biggest insight from the docs is that Donto should **not** become "the best ontology." That is
too small and too brittle. It should become the substrate where many ontologies, claims, agents,
instruments, simulations, memories, papers, experiments, contradictions, identities, and
explanations can coexist without being prematurely collapsed.

The phrase to use internally:

> **Donto is not a knowledge graph. Donto is the operating system for contested reality.**

That is the sci-fi version. Agents do not merely "query a database." They bind themselves to a
living epistemic substrate: they emit claims, attach evidence, test contradictions, fork identity
lenses, time-travel belief states, run experiments, and gradually let reality prune the graph.

The current docs already point there. The overview defines Donto as a contradiction-preserving,
evidence-first claim substrate where everything is a cheap claim, contradictions are kept, every
claim is anchored or honestly marked, and truth is computed at query time rather than normalized
at write time. The homepage thesis makes the same move more aggressively: large models invert the
old knowledge-graph economy, so the bottleneck becomes trust rather than extraction.

---

# 1. What Donto already has that is genuinely important

Donto's core atom is strong: `donto_statement` is a narrow bitemporal claim row with subject,
predicate, object, context, transaction time, valid time, flags, and content hash; metadata lives
in sparse satellite tables instead of widening the hot ledger. That is the right design for scale
because the claim ledger stays simple while evidence, confidence, arguments, identity, extraction
level, modality, and audit trails can grow around it.

The evidence model is also close to the right primitive for AI-era knowledge. A Donto claim can be
walked through an evidence link to a span, document revision, document, and content-addressed
blob; the docs explicitly treat wrong anchors as worse than no anchors, which is exactly the right
epistemic posture for agent systems. The presence of non-text anchor vocabularies such as page
boxes, image boxes, media time, table cells, CSV rows, JSON pointers, XPath, CSS, token ranges,
and whole-source anchors is important because the future substrate must ingest papers, video,
tables, lab notebooks, simulations, sensor logs, and instrument outputs, not just prose.

The embedding fabric is correctly framed as a derived cache, not a destructive merge mechanism.
Predicates, entity fingerprints, and memory chunks become vectors, but those vectors propose
alignments, identity candidates, and recall rankings without mutating the source claim ledger. The
alignment system then uses hybrid lexical/semantic candidate generation, LLM adjudication, typed
relation verdicts, safety flags, and a query-time predicate closure. That is a good architecture
because it lets Donto say: "we can fold `killedBy`, `murderedBy`, `birthplaceOf`, and `bornIn` for
this query without pretending they were always the same thing."

The identity model is philosophically correct. Donto never merges entities; identity is a
reversible hypothesis resolved under a chosen lens. That is not a minor feature. It is the
difference between a database that corrupts reality and a substrate that can represent contested
reality. The contradiction machinery is also on the right track: polarity is data, conflict is an
argument edge rather than invalidation, and contestedness is pre-aggregated so it can steer
discovery.

The solving page shows the most important product pattern: every consumer is an overlay over the
same substrate. Memory recall, substrate-wide search, genealogy, investigative lenses, and
benchmark work all reuse the same claim/evidence/alignment/bitemporal/paraconsistent core. That is
the correct shape for a platform.

---

# 2. The key conceptual upgrade: from "knowledge substrate" to **reality interface**

A physicist would say: Donto is currently excellent at storing observations and disputes, but to
become sci-fi it must become excellent at **closing loops with the world**.

A philosopher would say: Donto is already ontologically pluralist. Its next step is to formalize
pluralism without relativism: many lenses, but every lens must expose provenance, constraints,
contradictions, and consequences.

A computer-theory engineer would say: Donto needs a precise semantics. Not just tables and
services. A calculus.

The future version should have this loop:

> **Observe → Extract → Anchor → Claim → Contest → Predict → Act → Measure → Re-rank → Explain**

Right now Donto is strongest from **Observe → Claim → Anchor → Contest → Explain**. To become the
future substrate for agents solving hard problems, it needs to own **Predict → Act → Measure**.

That means Donto should not merely answer "what do we know?" It should answer:

1. **What would disambiguate this?**
2. **Which experiment, source, theorem, simulation, or observation would reduce uncertainty most?**
3. **Which contradiction is load-bearing for a goal?**
4. **Which agent, instrument, model, or proof engine should be invoked next?**
5. **What changed after the action?**

That is how Donto becomes useful for science, engineering, philosophy, and autonomous agents.

---

# 3. The formal core to publish: **The Donto Calculus**

A crisp formal object that makes researchers take Donto seriously.

A Donto statement:

```text
s = ⟨subject, predicate, object, context, valid_time, tx_time, polarity, maturity⟩
```

A lens:

```text
L = ⟨scope, policy, as_of_tx, valid_window, identity_hypothesis,
     predicate_closure_threshold, maturity_floor, contradiction_policy⟩
```

A query result:

```text
Q(D, L) → ⟨claims, evidence_chains, argument_edges, derivations, loss_report⟩
```

The point is that **truth is not a scalar**. A claim has a standing vector:

```text
standing(s, L) =
  ⟨evidence_maturity, corroboration, contradiction_pressure,
    source_policy, temporal_fit, identity_stability,
    inference_depth, review_state, downstream_utility⟩
```

This makes Donto legible to philosophers, logicians, database people, scientific-computing people,
and AI-agent engineers. The docs already contain most of the raw ingredients: bitemporal claims,
maturity levels, evidence chains, predicate alignment, identity hypotheses, argument edges,
policies, proof obligations, shape reports, rules, and audit logs. What is missing is the single
formal paper that says: "Here is the semantics of the substrate."

Call it:

> **The Donto Calculus: A Paraconsistent, Bitemporal, Evidence-Anchored Semantics for Agentic
> Knowledge**

That paper matters as much as the product.

---

# 4. The biggest engineering gap: the "future" tables exist but are not yet load-bearing

The schema reference is very revealing: 127 tables, ~111M rows, with the hottest tables being the
claim ledger, extraction overlays, modality overlays, audit log, revision lines, evidence links,
trace logs, memory records, FTS rows, predicate closure, spans, predicate embeddings, predicates,
label cache, and entity embeddings.

But the "sci-fi" layer is still underused. Several important tables are present but empty or
barely populated: dataset releases, release artifacts, multi-context membership, claim-kind
overlays, literal canonicalization, review decisions, claim frames, inference derivations,
property constraints, and rule agendas.

That is not a criticism. It is the roadmap. The strongest next move is to make these dormant
capabilities load-bearing:

| Dormant / thin capability    | Why it matters                                                                                   |
| ---------------------------- | ------------------------------------------------------------------------------------------------ |
| `donto_dataset_release`      | Makes Donto publish reproducible knowledge views, not ad hoc exports.                            |
| `donto_review_decision`      | Turns human/expert review into citable substrate state.                                          |
| `donto_claim_frame`          | Lets Donto represent n-ary events, experiments, measurements, transactions, and causal episodes. |
| `donto_literal_canonical`    | Needed for scientific quantities, dates, units, uncertainty, and normalization.                  |
| `donto_property_constraint`  | Needed for formal validation, domain/range/cardinality, and scientific invariants.               |
| `donto_inference_derivation` | Needed for explainable derived claims and machine-checkable reasoning.                           |
| `donto_rule_agenda`          | Needed for incremental reasoning when new evidence, alignments, or identity edges arrive.        |

The future does not require throwing anything away. It requires promoting the latent schema into
the actual product.

---

# 5. Physics lens: make Donto a scientific instrument, not just a memory

From a physicist's perspective, ontology is not primarily a taxonomy. It is a compression of
observations that predicts future observations. So Donto needs a first-class **measurement and
model layer**. A scientific Donto claim should distinguish:

```text
Observation: instrument X measured value Y at spacetime/event context C
Interpretation: model M maps observation Y to latent variable Z
Law/constraint: relation R must hold under assumptions A
Prediction: model M predicts observable O in interval T
Residual: observed O - predicted O = Δ
Experiment: action A was performed to disambiguate hypotheses H1/H2
```

To become physics-grade, add or fully activate:

- **Observables.** Measurements as first-class event frames: value, unit, uncertainty, instrument,
  calibration state, environment, method, operator/agent, time, location, evidence anchor.
- **Dimensional analysis.** Use the existing unit registry and literal canonicalization path
  (`donto_unit` exists; zero-row `donto_literal_canonical` is exactly where this becomes real).
- **Invariant detectors.** Conservation laws, dimensional constraints, monotonicity, type
  constraints, symmetry expectations → `property_constraint`, `shape`, `detector_finding` flows.
- **Prediction markets for hypotheses.** Every major hypothesis exposes predictions and residuals.
  A claim does not just "have confidence"; it survives contact with the future.
- **Experiment selection.** Expected information gain: rank contradictions by "which next
  observation would maximally reduce entropy or improve downstream task performance?"

> "Reality is not a pile of facts. Reality is the process that penalizes bad compressions."

That should become a product primitive.

---

# 6. Philosophy lens: Donto's killer idea is **ontological pluralism without chaos**

Most knowledge systems secretly assume there is one correct ontology. Donto's docs point to a
better metaphysics: identity, predicate meaning, and truth are lens-relative, but evidence and
provenance keep the system from dissolving into relativism.

The identity page is the strongest philosophical page in the docs: Donto never merges entities;
"same referent" is a reversible proposal, an edge, and a hypothesis-specific cluster cache. Donto
can represent "same person under legal identity," "same person under social identity," "same
place under historical boundary changes," "same concept under two research traditions" — without
corrupting the source claims.

The next philosophical upgrade: make **lenses** explicit product objects. A Donto lens bundles:

```text
scope · identity hypothesis · predicate closure · policy · time · maturity threshold ·
modal stance · source preference · contradiction treatment · export/inference safety
```

Then agents can say:

> "Under the strict biomedical lens, this claim is unsupported."
> "Under the exploratory materials-science lens, this analogy is promising."
> "Under the legal-historical lens, these two entities must remain distinct."
> "Under the engineering lens, this contradiction is irrelevant because both values lie within tolerance."

Classical ontologies force sameness too early. Raw vector search finds "similar stuff" without
committing to what kind of similarity it found. Donto does better: every alignment has a relation
type, scope, confidence, provenance, and safety flags.

The philosophical thesis — probably the project:

> **Ontology is not a static schema. Ontology is a reversible, governed, evidence-bearing lens
> over claims.**

---

# 7. Computer-theory lens: denotational semantics, complexity discipline, protocol gravity

Donto's architecture is promising because it separates immutable-ish base facts from derived
caches, overlays, lenses, alignments, and policies. To become infrastructure for all agents it
needs three more things:

**First, a stable formal contract.** The substrate API is a read-only discovery surface with
OpenAPI, plus memory/genealogy example consumers. Agent adoption requires a stable WRITE protocol
too: assert claims, attach evidence, propose alignment, propose identity, create argument edges,
run query, request review, publish release, report loss.

**Second, complexity-aware query semantics.** DontoQL must make cost and approximation explicit.
Every result should know whether it is exact, bounded, approximate, partial, sampled, or degraded.
(The solving page already shows bounded candidate sets, expression indexes, timeout degradation,
and RRF fusion — make those visible in the language.)

**Third, protocol gravity.** Donto should not compete with existing standards; it should absorb
and extend them: RDF (triples), OWL 2 (ontology semantics), SHACL (shape validation), PROV-O
(provenance), RO-Crate (research packaging), nanopublications (assertion + provenance + pubinfo).

> "Bring RDF, OWL, SHACL, PROV-O, nanopubs, RO-Crates, SQL, JSON-LD, PDFs, Git commits, lab
> notebooks, simulations, and agent memories. I will preserve their claims, evidence, time,
> contradictions, policies, losses, and lenses."

That is how it becomes the substrate rather than another silo.

---

# 8. Agent future: the memory, evidence, and dispute layer for MCP/A2A agents

donto-memory already ships an MCP server with recall, search, and memorize. Too small. Expose:

**MCP surface — Donto as tool substrate:**

```text
donto.search · donto.recall · donto.memorize · donto.assert_claim · donto.attach_evidence ·
donto.query_dontoql · donto.explain_claim · donto.find_contradictions · donto.propose_identity ·
donto.propose_alignment · donto.request_review · donto.publish_release · donto.run_detector
```

**A2A surface — Donto as agent commons:** capability cards ("I can resolve contradictions in
climate literature", "I can verify Lean proofs against Donto shapes", "I can adjudicate identity
hypotheses in genealogy"), and every agent interaction produces substrate state:

```text
agent A asks agent B to investigate contradiction C
B emits claims · attaches evidence · proposes an argument edge · records uncertainty
A reviews or contests · Donto logs the full interaction
```

This is the future: not agents chatting ephemerally, but agents leaving behind an inspectable
epistemic trail.

---

# 9. The product to build next: **The Donto Observatory**

Four canonical surfaces (the mockups were circling exactly this):

1. **Substrate Observatory** — live ingestion, contexts, statements, evidence links, predicate
   growth, contradiction pressure, alignment health, identity-review queue, policy warnings,
   agent activity, benchmark deltas. *"Is the organism healthy?"*
2. **Evidence & Contradiction Explorer** — a workbench for one claim: source spans, evidence
   anchors, supports/rebuts/undercuts, identity lens, predicate lens, bitemporal scrubber,
   maturity ladder, review obligations, downstream consequences. *"Why might this be true or false?"*
3. **Alignment & Identity Lab** — controlled review of predicate folds, inverse relations,
   identity hypotheses, safety flags, value mappings, lens comparisons. *"What should count as the
   same under this lens?"*
4. **DontoQL / Nebula Studio** — claim nebula, contradiction clusters, DontoQL editor, result
   table, explain plan, evidence chain, cost estimate, partial/degraded flags. *"What can agents
   discover when they reason over the substrate?"*

---

# 10. The grand-challenge roadmap

## Phase 1: Make Donto formally legible
```text
Donto Calculus paper · DontoQL formal semantics · Donto lens specification ·
Donto claim/release/loss-report JSON schemas · Conformance tests
```

## Phase 2: Make Donto agent-native
```text
Public MCP server with full epistemic toolset · A2A capability cards · Agent action ledger ·
Agent reputation/reliability overlays · Permissioned write API · Sandboxed tool execution provenance
```

## Phase 3: Make Donto science-native
```text
Measurement frame · Experiment frame · Simulation frame · Prediction/residual frame ·
Dimensional-analysis engine · Unit/literal canonicalization live · Instrument calibration metadata ·
Scientific contradiction queues
```

## Phase 4: Make Donto standards-native
```text
RDF/OWL/SHACL import/export with loss reports · PROV-O export · Nanopublication export ·
RO-Crate release export · JSON-LD context system · SPARQL-to-DontoQL compiler maturity
```

## Phase 5: Make Donto discovery-native
```text
Expected information gain ranking · Contradiction pressure × downstream utility ranking ·
Hypothesis tournament system · Agent review market · Automated experiment proposal ·
Benchmark arena for scientific discovery · Cross-domain analogy engine
```

At this point, Donto is no longer just "memory" or "knowledge." It is a machine for deciding what
the next useful question is.

---

# 11. The killer demo

Not "ask Donto a question." The killer demo is:

> **Give Donto a field full of contradictions and have it design the next experiment, proof,
> source search, or simulation that would most reduce uncertainty.**

```text
Goal: Resolve why two materials papers report incompatible superconducting behavior.

Donto:
1. Extracts all claims from both papers.
2. Anchors every claim to figures, tables, methods, and text spans.
3. Canonicalizes units, temperatures, pressures, sample prep, measurement techniques.
4. Finds contradictions not just in conclusions but in experimental conditions.
5. Identifies hidden identity/predicate mismatches.
6. Ranks which missing measurement would disambiguate the hypotheses.
7. Assigns agents: literature, simulation, dimensional-check, methods-review.
8. Produces a reproducible release with evidence, uncertainty, and the proposed next experiment.
```

Not one giant model hallucinating an answer. A society of agents operating over a shared,
evidence-anchored, contradiction-preserving substrate.

---

# 12. The main danger

The danger is that Donto becomes a very impressive private database instead of a public epistemic
protocol. Three things must be boringly easy:

1. **Bind a consumer** — a 10-minute developer experience.
2. **Inspect a claim** — "why do you believe this?" is one click to evidence, arguments, time,
   policy, and identity lens.
3. **Contribute work** — add evidence, propose/contest/review a claim, or publish a reproducible
   release without understanding the entire schema.

The schema can be deep. **The protocol must be simple.**

---

# 13. The positioning

Not "a better knowledge graph." Instead:

> **The substrate where agents turn the world into evidence-bearing claims, preserve
> disagreement, and let reality decide what survives.**

> **A bitemporal, paraconsistent, evidence-anchored substrate for agentic world models.**

> **The memory of civilization, but with receipts, contradictions, and time travel.**

And on ontology:

> **Donto is where ontologies compete, compose, fork, and earn standing.**

---

## Final answer

Do **not** build the one true schema of the universe. Build the substrate where every possible
schema, claim, model, identity, proof, observation, experiment, agent memory, contradiction, and
source can coexist under reversible lenses.

1. Formalize the **Donto Calculus**.
2. Turn lenses into first-class product/API objects.
3. Promote dormant schema: releases, reviews, frames, canonical literals, constraints, inference
   derivations, rule agendas.
4. Make Donto agent-native (MCP + A2A).
5. Make it science-native (measurements, experiments, simulations, predictions, residuals, units,
   uncertainty, invariant detectors).
6. Make contradiction pressure and expected information gain the steering wheel.
7. Build the Observatory, Evidence Explorer, Alignment Lab, and Nebula/DontoQL Studio.
8. Make every answer explainable from evidence, every disagreement preserved, every identity
   reversible, every export loss-reported, every agent action auditable.

> **Donto becomes the world model substrate agents use when they need to know not just what was
> said, but what was evidenced, what conflicts, what changed over time, what lens was used, what
> remains uncertain, and what action would make reality answer next.**