Skip to content
All posts

An Ontology That Holds

A field of muted dependency nodes with one chain lit in blue from left to right, and a red dashed arc running from the chain's last node back toward its first, stopped by a red refusal mark before it lands

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.

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.

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.

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 removed

That’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 left

The 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.

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.

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 exist

It’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.

“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.

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.

  • orderBy now knows your fields. orderBy("u", "createdAt") on a kind with no createdAt property 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() and paginate() 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/typegraph exported 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.

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) or backend.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.
  • orderBy system 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" } to createStore to keep the old behavior in one place. includeSubClasses is replaced by expansion.
  • Deleting a whole deletes its parts. A graph that declared partOf without via must name the realizing edge before it opens.
  • like() on SQLite may return fewer rows. Swap in ilike() where you were relying on the old case-insensitive matching.
  • zod peer range is now ^4.5.0, which the structural subtype check needs.
  • Custom metaEdge() is gone, along with the InferenceType union and the deprecated sameAs/differentFrom factories. Move free-form vocabulary to defineGraph({ annotations }) and run migrateSchema() 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 acyclic or composition relation needs INSERT and UPDATE on typegraph_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.

Stay in the loop

Occasional updates on new features, guides, and releases. No spam.