Ontology
One description of the world.
Every layer binds to it.
Most agent stacks describe their domain four times: in a system prompt, in a database schema, in an agent card typed by hand, and in a playbook that names things the model has never heard of. They drift, and the drift is invisible. Here the domain is described once — as an ontology — and the conversation, the harness, the card, the vault, the receipt and the chain all bind to that one description by IRI. A term the ontology does not declare cannot be a field of a record, an argument of a tool, or a word on a screen.
01Two ontologies
An upper ontology of agentic systems. A domain ontology of a card room. The second imports the first.
Agentic Trust says what every agentic system has: agents in PROV-O’s three kinds, delegation and its caveats, intents, endorsements, deployments, situations. Texas hold’em says what this domain has — tables, hands, coaching, chips — and grounds each class on one above it. Below: the Agent module of the upper ontology, and the Coaching module of the domain, as the skills registry renders them.
How the coaching module grounds — three tiers, real subsumption
A coaching service a person custodies — its own card, endpoint and playbook; the only language model on the clock. Never the table’s addressee, never a seat.
The signed, scoped, revocable authority one person gives ONE service to read her study records and append a note — no spend, no seat, no poker.act. Revoking it on chain fires the coach at the next hand.
Her own agent asking its coach: the same seat payload the table sent, plus the grant, one hop, no model call on her agent. Refused when the grant is missing or revoked.
Asked for in her own words, in her own time, through th:ReviewRequest ⊑ at:SkillInvocation. Never sent at hand end by the table: a review is asked for, or it is a bill.
Her records, in her vault. The coach reads them under the grant and writes exactly one kind of thing back — its own notes — into hers, never its own.
The person naming her own agent as adviser at a table — a role bound for a while, with a start and an end, not a flag on a row.
The middle tier, card-room (cr:), is what hold’em shares with canasta: a coach, a study grant, a consultation, a review are the same things at either table. Hold’em adds the hand. Where the correspondence is alignment rather than identity the T-box says rdfs:seeAlso, not subClassOf — the ontology is honest about what it does not know.
02Every layer
The ontology is not a documentation layer. It is the spine.
Seven layers of the architecture ask the ontology a question, and each binds to the answer by IRI from a module in @agenticprimitives/ontology. The same T-box grounds on the upper ontologies and is extended by the domain. Nothing re-describes the domain; a gate fails the build when code tries.
Who is "alice"? Which account pays? What is "20 USDC"?
check:ontology-bindings · check:ask-truth
Binds: party-roles.ts · arg-types.ts · decisions.ts — a party is a KIND plus a RELATION to follow (ap:charteredUnder), never a name match
The bug it replaced: The Ask looked for a treasury whose NAME resembled the person’s — alice → alice.treasury. Hers is alice2.treasury. A payment that should have worked dead-ended on a rule nobody wrote down.
What may this agent mean? What may a plan fan out over?
the skills compiler refuses an unknown class · check:interaction-coverage
Binds: SKILL.md knowledge.requires names T-box classes; plan-shapes.ts says which relations are bounded and owner-recorded
The bug it replaced: A planner improvised "pay every member" over a public search result — an unbounded list of strangers, array-shaped. Nothing could refuse it because the difference lived nowhere.
What does the world see? What can it ask?
check:capability-vocabulary · SHACL on the KB
Binds: profile.capabilities[] is the record; A2A skills[] and ARD capabilities[] are projections; the KB is RDF and a question is a generated CONSTRUCT query
The bug it replaced: A card editor titled a section "Capabilities" and filled it with protocol flags, next to "Skills" holding what the agent could do. Backwards twice, in the one screen where a steward decides what the world sees.
What is this record? Which of mine answer this question?
check:no-cross-subject-vault-reads · check:privacy-lint
Binds: vault-records.ts binds every record key to a T-box class; a question compiles to a selector evaluated INSIDE the store
The bug it replaced: A Home listed an organization’s vault faithfully and uselessly — coordination.endeavor:end_05b… · show. Every key was already a class; nothing had said so.
What situation are we in? Who committed to what?
cbox/interaction-shapes.shacl.ttl · check:coordination-coverage
Binds: apix:Interaction / Exchange with a pinned profile version; apcoord:Endeavor / CoordinationPlan; SHACL shapes constrain STRUCTURE only
The bug it replaced: An unauthorized command must stay shape-valid — refusing to record overreach deletes the evidence. Shapes that encoded permission would have hidden the incident.
What ran, under whose authority, and what did it touch?
the context and the T-box are tested byte-for-byte against each other
Binds: run-provenance.jsonld — a run is an ep-plan:ExecutionTraceBundle; a span IS a prov:Activity and names it (ap.prov.activity.id)
The bug it replaced: Spans, log lines and attestations joined by ids somebody invented. Three evidence formats; no one graph a stock RDF stack could load.
What kind of agent is this? What does its name say?
a mismatched suffix fails closed · check:demo-person-org-distinct
Binds: prov:Person / prov:Organization / prov:SoftwareAgent — mirrored by AgentType in code and atl:agentType on chain; a typed name suffix (.me .org .svc .treasury) names the derived type
The bug it replaced: A demo person pointed at as his own organization. The operator check compared one address to itself and went green; the workspace switcher walked a person as if he were a parent org.
03From ontology to a running agent
Upper → domain → archetype → signed card. Meaning flows down. Authority never does.
An archetype bundles the classes, capabilities and SKILL.md packages one kind of agent needs; its knowledge.requires is a list of T-box classes, and a package that names one the ontology lacks fails to compile. From the archetype, the A2A agent card is projected and signed — its skills[] are the capability ids the ontology names. The coach can then mean exactly fourteen things about hold’em, and may do none of them until Alice signs a Study Grant at her Home.
04What it is not
The ontology says what a thing is. Only a grant says what may happen.
ap:charteredUnder says a treasury is chartered under the person who holds it. A resolver may follow that to find her treasury. A verifier may not read it as permission to pay from it — that is a delegation with a Value caveat, checked on chain at redemption.
A planner prompt is the most tempting place to write a domain rule and the worst place to keep one: invisible to every gate, drifting silently, applied confidently to cases it was never meant for. Prompts say how to BEHAVE; the ontology says how the world is SHAPED; prompt text is rendered from the binding.
A lookup table is simpler once. From then on it is a second opinion about the domain, and this page exists because one of those was wrong in production. If the term is missing, adding it to the T-box is the work.
A string-similarity heuristic standing in for a modelled relationship is the specific failure this exists to prevent.
05Who authors the domains
The substrate ships the upper ontology. Rich Canvas designs the domains.
Agentic Trust (at:) and the substrate modules (ap:) are in the repository. The domain ontologies an application actually binds to — commerce, faith communities, family offices, the everyday domains people live in — are authored by Rich Canvas on top of them and compiled into skill artifacts the registry pins by digest.
Rich Canvas authors the shared, machine-checked vocabulary for a domain: who the parties are, what counts as an act, what an approval is, what a receipt proves — then binds it to the substrate by IRI.
A commerce ontology for the agentic era — offers, orders, fulfilment and settlement as classes an agent can be granted authority over, with the treasury relationship modelled rather than guessed.
The DID method for agent accounts: the anchor is an ERC-4337 account, the DID names it, and every projection — card, name, registry entry — carries a proof the anchor signed.
More from Rich Canvas: Why semantic metadata · Muses of an architect · richcanvas3.com
Browse the namespaces. Then build a domain.
Every T-box module is published with its IRI. The skills registry at skills.faithnet.io renders every module of Agentic Trust and of each domain as a graph, signed in as a demo person.