The four-layer architecture

Every sound ontology separates four kinds of knowledge, because they have different authority, different writers, different change dynamics, and different consumers:

Layer	Question it answers	Character
1 — Grounding	What did source X publish, and when?	Faithful, in source language, provenance to versioned canonical semantic snapshots; written only by a producer authorized for that grounding namespace
2 — Identity	What records, across sources, refer to the same real-world thing?	Established authority identities or independently resolved thin canonical anchors + evidenced, method-classed resolution assertions; unresolved records stay explicitly unresolved
3 — Domain knowledge	What reusable knowledge can be composed from grounded sources + resolved identity?	Normalizes resolved identity and grounding in a common language through observations, traceable and rebuildable from its sources
4 — Beliefs	What does someone conclude, predict, or decide on the evidence?	Interpretations, forecasts, and judgments concluded from graph data with ownership and attribution

In one word per layer: Captures → Connects → Composes → Concludes.

Layers 1–3 capture the world; layer 4 interprets it

Layers 1–3 exist to ground the best available understanding of the facts of the world, organization-neutrally. Layer 4 is where an owner goes beyond the evidence to a conclusion — and layer 4 is not inherently private. Visibility is a repo property; belief is an epistemic class. All of these are layer-4:

• A public belief: an analyst publishes “based on recent ammonia readings, demographics, and violation history, the xyz region will likely need a wastewater-expansion project within six months” — attributed, evidence-cited, openly contestable.
• A private belief: a firm’s forecast of its own capacity and capability to serve that need, built from its private knowledge.
• A decision: combine the two — the public prediction of demand with the private forecast of capacity — to decide whether and how to bid. Decisions are beliefs whose evidence spans stacks.

A belief may also be withheld rather than published — the same prediction shared only with chosen counterparties. See the curator economy, which describes where composition naturally leads rather than capability available today.

What separates layer 3 from layer 4 is the observational line: layer 3 states what is supportably observed (“recurring warm-season ammonia elevation across three reporting years”); layer 4 concludes, diagnoses, predicts, or prescribes. Correlation is never laundered into causation on the public side of that line; causal, diagnostic, prescriptive, or legal conclusions carry an owner who stands behind them.

The mirror: world-model and self-model

Any organization that acts on the world runs the stack twice: a world-model (usually consuming public layers 1–3) and a self-model — its services, people, capacity, margins, licenses, equipment — built with identical discipline from its own systems of record. The self-model deserves the same rules: no source identifier is silently assumed canonical; an established system-of-record identity is evaluated for semantic fit, lifecycle, and stewardship and may then be adopted deliberately; conflicts are preserved; contracts exist per Shape; and competency questions and golden cases govern the model. Its most decision-relevant beliefs live at the interface, for example: which work to pursue (world-need × self-capability), how to price it (public funding context × private margin history), where to grow (world demand − self capacity). A decision-grade belief has pedigree feet in both stacks — and that is a checkable property of the evidence graph, not a metaphor.

Layers are epistemic classes; producers and repos have different jobs

The layer boundary is enforced by Shape catalogs, namespaces, and write authority — and all three work within one repo as well as across repos. Name-scoped write tokens can give one producer authority to write grounding Shapes only; namespace globs scope queries, subscriptions, and tokens to one layer.

• A knowledge producer is any reviewed implementation that maps external source data or upstream WarmHub knowledge into an authorized Shape and namespace surface. It may be a scheduled service, an event-driven worker, a one-time migration, or a human-supervised process.
• A mapping policy is the stable semantic name/version for how that producer maps its inputs. The implementation and deployment that execute the policy live in source control and operational records, not as required ontology Things.
• A repo, like an organization, is an organizational unit for ownership, visibility, and governance.

One producer and mapping policy may serve several targets without becoming durable graph identity. Choose repo boundaries primarily by ownership, visibility, and governance. An independent release/correction lifecycle, or materially different correction cadence, supports a split; source agency, entity subclass, row count, producer code location, orchestration code location, or deployment unit does not by itself justify one. A separate repo should be an independently meaningful knowledge product that can be chartered, released, discovered, and consumed. Cross-repo wrefs preserve composition, but every split adds authorization, discovery, release-coordination, and dependency costs.

• Use several repos when those benefits outweigh the costs: a per-source grounding product with distinct writer authority; an independently governed identity provider; or per-organization belief repos with different owners or visibility.

• Use one repo when one steward can govern several layers at compatible visibility and lifecycle. Layer-based names are one optional way to preserve useful packaging inside it:

  Source/grounding/{authority}/{source-system}
  SourceArtifact/grounding/{authority}/{source-system}/{dataset-stream}
  SourceRecord/grounding/{authority}/{source-system}/{source-grain}
  CanonicalThing/identity/{stable-navigation}
  DomainThing/water/{stable-navigation}
  OntologyThing/ontology/{contract-name}

  These are patterns, not prescribed Shape names or platform-fixed paths; SourceRecord, CanonicalThing, DomainThing, and OntologyThing stand for the concrete Shapes selected by the ontology. When a layer segment is used, put it immediately after the Shape and require it to buy useful query, subscription, or token scopes. A per-source grounding repo may reasonably use the compact Source/{system-slug}, SourceArtifact/{dataset-stream}, and source-grain record names because the repo already supplies the grounding and source boundary. Select concrete domain segments such as water from competency questions; do not add a generic domain/** segment merely for symmetry.

Write each repo’s charter into its description and Content/Readme / Content/Agents — agents read them.

Flow between layers

Grounding writes trigger identity re-resolution; identity changes trigger recomposition; composition changes trigger belief review — note the last verb: beliefs are re-examined by their owners, never mechanically rebuilt. Flow is one-way: an upstream layer never reads or cites a downstream one. Subscriptions are an optional event bridge and a freshness optimization, never the source of truth: every downstream producer must be able to rebuild its outputs from current upstream state. Make event handlers idempotent, never depend on delivery order, and treat a Shape revision as an ontology event that may require targeted recomposition.

Write authority is ontology governance

For every repo, declare — and enforce with repo-scoped, name-restricted tokens — each writer’s contract: what initiates it, what it reads, the one place it writes, the Shapes it may create, and the Shapes it may not (the tempting mistakes, named explicitly — a grounding writer that can mint canonical Facility Things eventually will). The contract is where epistemic layering becomes enforceable. Every WarmHub write remains attributable to the human whose valid PAT authorizes it; exact execution, deployment, and retry history stays in the producing system’s operational audit records.