An Ontology That Holds

I have a confession about TypeGraph’s ontology. For a long time, a fair amount
of it was decoration. You could declare that a Section is part of a
Document, and it read beautifully in a code review. Then you deleted the
document, and its sections stayed right where they were, loyal parts of a whole
that no longer existed. A subclass only showed up in a supertype query if you
remembered to ask. A custom meta-edge was metadata that no read or write ever
looked at. The ontology described your domain the way a poster describes a
company’s values.
Why would you want an ontology?
Section titled “Why would you want an ontology?”Fair question, and the word doesn’t help. It sounds like something you’d need a philosophy degree and a committee for, or pay Palantir to build for you.
Here’s the plain version. Your domain already has rules. A runbook is a kind of document. A section belongs to one document. Dependencies don’t loop. Everyone on your team knows them, and they’re written down nowhere the database can see. So they get enforced in application code: once in the API, again in the import script, differently in the background job, and not at all in the one-off migration someone ran on a Friday.
An ontology is those rules, declared once, next to the schema. The database then applies them on every read and every write, including the ones you forgot about and the ones written by someone, or something, that never read your wiki. If you have agents writing to your graph, that last part is most of the point: a rule the store enforces is the only kind an agent reliably follows.
That’s the promise. Until now TypeGraph kept about half of it. 0.75 is the release where it keeps the rest: every relation the ontology declares now has a defined effect on reads, writes, schema changes and merges, and the store refuses the writes that would break one. If you say a section is part of a document, the database behaves as though you meant it.
It’s the biggest release I’ve shipped, and it breaks more than any release before it, so this post is part tour and part apology. The tour comes first: the pieces you’ll touch soonest, on a small documentation graph with documents, runbooks (a kind of document) and the sections they’re made of. The outputs below come from running this code on SQLite.
const Document = defineNode("Document", { schema: z.object({ title: z.string() }),});const Runbook = defineNode("Runbook", { schema: z.object({ title: z.string(), service: z.string() }),});const Section = defineNode("Section", { schema: z.object({ heading: z.string() }),});
const sectionOf = defineEdge("sectionOf");const dependsOn = defineEdge("dependsOn");const supersedes = defineEdge("supersedes");const linksTo = defineEdge("linksTo");
const graph = defineGraph({ id: "docs", nodes: { Document: { type: Document }, Runbook: { type: Runbook }, Section: { type: Section }, }, edges: { sectionOf: { type: sectionOf, from: [Section], to: [Document], cardinality: "one", }, dependsOn: { type: dependsOn, from: [Document], to: [Document], acyclic: true, }, supersedes: { type: supersedes, from: [Document], to: [Document], targetCardinality: "one", }, linksTo: { type: linksTo, from: [Document], to: [Document] }, }, ontology: [ subClassOf(Runbook, Document), partOf(Section, Document, { via: sectionOf }), ],});The graph holds one plain document, doc-architecture, and two runbooks,
rb-failover and rb-cache-flush.
Supertypes include their subtypes
Section titled “Supertypes include their subtypes”Here’s a question with an obvious answer: if a runbook is a kind of document, and you ask for every document, do you get the runbooks? Before 0.75 the answer was “only if you opted in”, which is how you end up with a search page that quietly leaves out a whole category of content and a bug report titled “search is broken (sometimes)”.
const titles = await store .query() .from("Document", "d") .orderBy("d", "title") .select((ctx) => `${ctx.d.kind}: ${ctx.d.title}`) .execute();
const documentsOnly = await store .query() .from("Document", "d", { expansion: "exact" }) .select((ctx) => `${ctx.d.kind}: ${ctx.d.title}`) .execute();[ 'Document: Architecture overview', 'Runbook: Cache flush', 'Runbook: Database failover'][ 'Document: Architecture overview' ]A query over Document now returns runbooks too, because a runbook is a
document. When you do want only the plain ones, you say so. One option,
expansion: "exact" | "subclasses" | "narrower", replaces includeSubClasses
on from(), to() and search(), and the same answer drives endpoint
admission, uniqueness scope, merge reconciliation and search. Notice that the
sectionOf edge above never mentions Runbook, yet a runbook can hold
sections, as the next section shows. You declare the relationship once and it
applies everywhere, which is the whole point of having declared it.
All of that only makes sense if a runbook really is a document, and I no longer
take your word for it. subClassOf is now checked: the child’s Zod schema has
to accept only values the parent’s schema accepts, both at compile time and
when the registry is built. If your Runbook has drifted away from Document,
you find out when you define the graph, not when a query hands a runbook to
code expecting a document. isStructuralSubtype(child, parent) exposes the
same verdict, and equivalentTo between two registered kinds is now
subsumption in both directions.
Parts go with their whole
Section titled “Parts go with their whole”Every app that models containment by hand eventually grows the same cleanup job: the one that sweeps up comments on deleted posts, line items on deleted invoices, steps of deleted runbooks. It runs nightly, it’s nobody’s favorite code, and it exists because the database was never told that those things belong to each other.
Now you can tell it. partOf(Section, Document, { via: sectionOf }) declares a
composition, and via names the edge that stores it. A part has at most one
whole, enforced by a claim across every edge that realizes the relation. You
attach a part when you create it:
const steps = ["Detect the failure", "Promote the replica", "Repoint clients"];for (const [index, heading] of steps.entries()) { await store.nodes.Section.create( { heading }, { id: `failover-${index + 1}`, partOf: { whole: failover } }, );}Deleting a whole deletes its parts in the same transaction, leaf-first, so the
cleanup job can retire. But “this delete is bigger than it looks” is a sentence
that should make anyone nervous, me included. So planDelete shows what a
delete would remove before you run it, computed by the same planner the delete
uses:
const plan = await store.nodes.Runbook.planDelete(failover.id);if (plan === undefined) throw new Error("Runbook not found");for (const part of plan.cascadedParts) { console.log( `${part.kind} ${part.id} (part of ${part.whole.id} via ${part.viaEdgeKind})`, );}console.log(`${plan.removedEdgeIds.length} edges removed`);Section failover-1 (part of rb-failover via sectionOf)Section failover-2 (part of rb-failover via sectionOf)Section failover-3 (part of rb-failover via sectionOf)3 edges removedThat’s your “Are you sure?” dialog, with real contents for once. Show the plan to a person, and pass it back as a guard when they confirm. If a colleague adds a step while the dialog is open, the delete refuses instead of removing a section nobody saw:
await store.nodes.Section.create( { heading: "Verify replication lag" }, { id: "failover-4", partOf: { whole: failover } },);await store.nodes.Runbook.delete(failover.id, { expect: plan });NodeDeletePlanMismatchError: Delete of Runbook/rb-failover no longer matches the expected plan: 1 part(s) added, 0 dropped; 1 edge id(s) added, 0 dropped.Planning again and confirming deletes all four:
4 sections deleted, 0 leftThe delete reports the same parts as cascadedParts on its receipt and on
onOperationEnd. reparent moves a part to another whole at one instant,
parts() and wholes() walk the closure, and subgraph({ composition: true })
returns a whole with everything it owns. On a oneActive relation, the
one-whole rule holds at every point in valid time, so an asOf read never sees
a part in two wholes at once.
Relations that can’t close a loop
Section titled “Relations that can’t close a loop”Everyone has a relation that must never loop: dependencies, reporting lines, folder trees, “this replaces that”. And everyone discovers the loop the same way, when a job that walks the relation doesn’t come back. The usual fix is a depth limit and a comment that says “should never happen”.
acyclic: true makes it not happen. It declares that an edge kind never forms
a cycle. Every write that could add an edge to it is checked first, and a batch
is checked as a whole before its first row is written:
await store.edges.dependsOn.create(overview, incident, {}, { id: "dep-1" });await store.edges.dependsOn.create(incident, cacheFlush, {}, { id: "dep-2" });try { await store.edges.dependsOn.create(cacheFlush, overview, {}, { id: "dep-3" });} catch (error) { if (!(error instanceof EdgeAcyclicityError)) throw error; const witness = error.details.witness; console.log(error.message); console.log(witness?.nodes.map((node) => node.id).join(" -> ")); console.log(witness?.edges.map((edge) => `${edge.edgeId} (${edge.source})`));}Acyclicity violation: "dependsOn" edge dep-3 would close a cycle in the "dependsOn" relation (Document/doc-architecture already reaches Runbook/rb-cache-flush).doc-architecture -> rb-incident -> rb-cache-flush[ 'dep-1 (stored)', 'dep-2 (stored)' ]A database that only says “no” is a database you end up arguing with. So the
refusal carries a witness: the path the new edge would close. You can show
someone exactly which dependency is in the way. Graph merge
runs the same check while it builds a plan and reports a cycle the plan would
close as an AcyclicityMergeConflictError with the same witness.
This isn’t free, and I’d rather you hear the cost from me. The check walks the
edges reachable from the new edge’s target. On a relation of 100,000 edges, a
typical insert costs about as much as a cardinality: "one" insert (0.2 ms on
SQLite, about 4 ms on PostgreSQL). The worst case is an edge pointing at the
head of a long chain, where the walk visits every reachable edge: about 220 ms
on SQLite for a chain of that size. If your relation is one enormous chain,
measure before you turn this on.
Bounds on both ends
Section titled “Bounds on both ends”cardinality has always limited the edges leaving a node. But half of the
rules people actually have point the other way: a seat has one occupant, an
invoice is paid by one payment, a document is superseded at most once. Until
now those lived in application code, guarded by a read-then-write that two
requests could both pass.
targetCardinality limits the edges arriving at a node, so the rule becomes a
declaration:
await store.edges.supersedes.create(overviewV2, overview);await store.edges.supersedes.create(overviewDraft, overview);CardinalityError: Cardinality violation: "supersedes" targeting Document/doc-architecture allows "one" but 1 edge(s) already existIt’s enforced atomically on every write path, through the same claims as the source side, so the two-requests-at-once case is refused too, not only the polite sequential one above.
Tightening a schema checks your data first
Section titled “Tightening a schema checks your data first”Everything so far is easy on an empty graph. The interesting day is the one when you add a rule to a database that has been running without it for a year and has developed opinions. The question then is whether the rows you already have satisfy the rule, and the worst possible answer is finding out later.
Here two documents link to each other, and a new release of the graph declares
linksTo acyclic:
await store.edges.linksTo.create(overview, incident, {}, { id: "link-1" });await store.edges.linksTo.create(incident, overview, {}, { id: "link-2" });
try { await createStoreWithSchema(graphWithAcyclicLinks, backend);} catch (error) { if ( error instanceof MigrationError && error.details.reason === "ontology-tightening-violated" ) { console.log(error.details.violations); }}[ { family: 'edgeAcyclicity', relation: 'linksTo', edgeIds: [ 'link-1', 'link-2' ] }]The commit is refused, nothing is published, and you get a list of the exact rows in the way. Remove the back-link and the same call migrates:
[ 'Edge "linksTo" declared acyclic: true' ]The ontology change classifier calls this kind of change a warning: a
tightening that is checked against live data inside the schema-commit
transaction. Adding disjointWith, subClassOf, equivalentTo or a
partOf pair, narrowing an edge’s endpoints, and declaring a stricter
cardinality, targetCardinality or acyclic: true are all checked the same
way. One refusal lists every violated family, in the same shape
store.verifyConstraintFences() returns, so you can fix the rows and retry
once. Adding or reshaping a unique constraint on a kind that already holds rows
is refused outright, because a schema commit doesn’t rebuild the claims that
enforce it.
Identity history
Section titled “Identity history”“Why does the system think these two records are the same person?” is a
question you’d like to answer with something better than a shrug. On a graph
with operational identity and history: true, the store now keeps
an append-only log of every change to a node’s identity class.
Say the architecture overview also exists as a page in the old wiki. Someone marks the two records as the same document, then thinks better of it:
const joined = await store.identity.assertSame(overview, wikiCopy);await store.identity.retractAssertion(joined.assertion.id);
const history = await store.identity.replay(overview);const lines = history.steps.map((step) => { const ids = (members: typeof step.before) => members.map((member) => member.id).join(", "); return `${step.transition.cause}: [${ids(step.before)}] -> [${ids(step.after)}]`;});console.log([...new Set(lines)].join("\n"));assert: [doc-architecture] -> [doc-architecture, wiki-architecture]retract: [doc-architecture, wiki-architecture] -> [doc-architecture]That’s the whole story of the belief, in order: joined, then split. (A split
is logged once for each class it leaves behind, so the Set folds the two
entries that read the same from this document’s side.) Each step also carries
when it happened in both valid and recorded time and, for a change a merge applied,
the branch, plan and review that produced it. transitionsOf(ref) returns the
same changes without the before-and-after membership. Replay reconstructs
membership through the same historical reader as asOfRecorded, so it can’t
disagree with a read.
Graph merge carries identity through branches with fixed rules: a three-way
classification of every staged assertion, a hard conflict when two branches
assert opposite relations for one pair, and a veto that drops a scored match
between two entities a different assertion holds apart. Conflicts that are
certain to fail at apply (two branches filling one targetCardinality slot,
moving one part to different wholes, closing a cycle) are now refused while
the plan is built, not halfway through the commit.
Putting it together
Section titled “Putting it together”Look back at the graph definition at the top of this post. The ontology is two lines, and the edge rules are three options. Here’s what those five declarations bought:
| You declare | You stop writing |
|---|---|
subClassOf(Runbook, Document) |
the opt-in flag on every query, and the search bug when someone forgets it |
partOf(Section, Document, { via }) |
the nightly job that sweeps up orphans |
acyclic: true |
the depth limit and the “should never happen” comment |
targetCardinality: "one" |
the read-then-write check that two requests can both pass |
| a tighter rule on a live graph | the data audit you run after the migration, hoping |
Five declarations, five pieces of code nobody enjoyed owning. And none of it is specific to documentation. The same shapes turn up wherever the rules are about how things relate:
- An org chart. Reporting lines can’t loop, and everyone has one manager, however many people would like to be it.
- A bill of materials. Components go with their assembly, and a revision supersedes exactly one predecessor.
- Permissions. A group can’t contain itself, directly or through four other groups, and a service account is a kind of principal.
- Agent memory. An agent can’t file a fact under a type it doesn’t fit, or attach a part to two wholes, no matter how confident it sounds.
The whole tour is one runnable file, An Ontology, End to End, with every output in this post asserted, so it can’t drift from what the library does.
The rest of 0.75: fewer ways to be quietly wrong
Section titled “The rest of 0.75: fewer ways to be quietly wrong”While I had the patient open, I fixed a pile of things that had nothing to do with ontology and everything to do with the library giving you a plausible answer where it should have given you an error.
orderBynow knows your fields.orderBy("u", "createdAt")on a kind with nocreatedAtproperty used to compile, run, and sort by nothing at all. The field name is now typed, so a typo is a red squiggle, and the system timestamp is spelled the way a selected row spells it:"meta.createdAt".- Pagination that paginates.
stream()andpaginate()over full nodes ordered by a system field returned the first page forever. I’d love to say this was subtle. It wasn’t; it just needed someone to read past page one. like()means the same thing on both databases. It was case-sensitive on PostgreSQL and case-insensitive on SQLite, which is a fun thing to discover in production. It’s case-sensitive on both now;ilike()is there when you want the other one.- Listings on PostgreSQL stop sorting the whole table.
nodes.find()on a kind with two million rows went from about 285 ms a page to under a millisecond in my benchmark, thanks to one new index that should have been there all along. - A package root you can read.
@nicia-ai/typegraphexported 911 names, most of which only a backend author would ever want. It now exports 86: the graph DSL, the store, the query helpers and the errors you’d catch. Everything else still exists, behind an entrypoint named for what it is (/store,/query,/errors,/identity,/maintenance). Your autocomplete will thank me. Your import statements will not, which brings us to the apology.
Upgrading (the apology)
Section titled “Upgrading (the apology)”This release asks more of you than any before it. I batched the breaking changes on purpose, so you pay once instead of in five installments, but it’s still a real upgrade. The short version:
- It’s one-way. Upgrade every reader of a shared database together. Base
schema goes to version 9. A privileged open (
createStoreWithSchema) orbackend.adoptBaseSchema()adopts it in place, and earlier releases refuse the database afterwards. Take a backup first; you were going to anyway. - Imports move. Names that left the package root are importable from their
new entrypoint, with no aliases. There’s a machine-readable map of every
move, shipped in the package at
etc/root-export-moves.json, so the rewrite is a script and not an afternoon. orderBysystem fields are renamed."created_at"becomes"meta.createdAt", and so on. The old names throw an error that tells you the new one.- Supertype queries return subtypes by default. Pass
queryDefaults: { expansion: "exact" }tocreateStoreto keep the old behavior in one place.includeSubClassesis replaced byexpansion. - Deleting a whole deletes its parts. A graph that declared
partOfwithoutviamust name the realizing edge before it opens. like()on SQLite may return fewer rows. Swap inilike()where you were relying on the old case-insensitive matching.zodpeer range is now^4.5.0, which the structural subtype check needs.- Custom
metaEdge()is gone, along with theInferenceTypeunion and the deprecatedsameAs/differentFromfactories. Move free-form vocabulary todefineGraph({ annotations })and runmigrateSchema()once. - Stored merge plans and reviews must be planned again. Plans move to format 3 and reviews to formats 3 and 4.
- On PostgreSQL, a role that writes into an
acyclicor composition relation needsINSERTandUPDATEontypegraph_fences. If your tables are large, build the two new listing indexes before you deploy so your first boot doesn’t wait for them; the indexes guide has the statements.
That list is the highlights. The changelog has every breaking change with its migration, grouped by who it affects, and it’s the thing to read before you upgrade anything you care about.
Try it
Section titled “Try it”- An Ontology, End to End: the runnable source behind this post
- Composition and previewing a delete
- Acyclic edges and target cardinality
- Subclass expansion
- Ontology tightenings are checked against your data
- Replay and identity history
- Base-schema version 9
- GitHub
Stay in the loop
Occasional updates on new features, guides, and releases. No spam.