Version control for world models

Enterprise models change constantly, and most graph stacks have no answer. What version control looks like when the artifact is a schema rather than a codebase.

Alexander Belikov, Founder · · 10 min read

Relational teams have had schema migration tooling for over a decade. Alembic, Flyway and Liquibase are unglamorous, and they are the reason a relational schema can change on a Tuesday without anyone treating it as an event. Graph and ontology stacks have had almost nothing equivalent, and the consequence is predictable: the model gets built once, carefully, and then quietly calcifies because nobody can establish what changing it would do.

This paper is about what version control looks like when the artifact being versioned is a model of a business rather than a codebase.

The model that cannot change

A knowledge graph that describes a real organisation is never finished. Sources change, systems are replaced, two departments merge and their two notions of “customer” have to become one. Ownership shifts. A field that was free text becomes an enumeration.

A mistake in the model does not break one feature — it propagates to every consumer of the graph at once, and it does so silently, because a graph with a wrong edge still answers queries. That blast radius is what makes teams stop touching the model.

So the requirement is not “support schema changes”. It is: make a proposed change reviewable before it happens, make what happened recoverable afterwards, and make the dangerous cases refuse to proceed on their own.

Why a computed diff is not enough

The common approach is to diff two versions of a schema and show the result. This is better than nothing and structurally insufficient, because a diff is a reconstruction rather than a record.

Consider a model where the type Vendor is gone and a type Supplier has appeared with similar fields. A diff can only report the disappearance and the appearance. It cannot distinguish between three quite different events: the type was renamed; the type was deleted and an unrelated one added; or two types were folded together and this is the survivor. Those have different consequences for every downstream consumer, and the information that separates them existed at the moment the change was made — the diff just did not capture it.

The same gap explains why diff-based tooling cannot generate a trustworthy rollback. To reverse a change you need to know what it was, not what it looked like afterwards.

Operations: the change is the artifact

The alternative is to make the change itself the recorded thing. In GraFlo the unit of change is an operation — a typed, named modification drawn from a closed vocabulary of dozens: adding, renaming, splitting and combining types and properties, retargeting edges, replacing identity policies, changing field types, declaring semantics.

A change between two versions of the model is therefore not a picture to be interpreted. It is an explicit list of operations which, applied to the old model, reproduces the new one exactly. Reviewing a change means reading that list. Approving it means approving that list. Storing the history means storing those lists.

An operation list is data — an ordinary YAML document you author, review and check into a repository. Here is the change billing makes when it decides the account number identifies a customer:

the change set — skip if you only want the argument
- op: replace_identity
  replacements:
    customer:
      to:
        mode: natural
        identity:
        - account_no
      retire: demote
      endpoints: follow_new
- op: add_vertex_properties
  additions:
    customer:
    - payment_terms

Note what is carried besides the intent. retire: demote says the previous key is not dropped but becomes a secondary identity, so a source that still carries only the old key can still find the customer. endpoints: follow_new says edges that found the customer by its old key during ingestion now find it by the new one. Those are precisely the decisions a reviewer needs to see and a textual diff cannot express — and they are what makes the change replayable rather than merely described.

Because the operations are typed rather than textual, three things follow that are not available to a diff:

  • A reviewer sees intent. “Rename Vendor to Supplier” and “fold Vendor into Supplier” are different entries, not the same shape of text.
  • The plan exists before the change does. The operation list can be written out, circulated and approved while the model is still untouched.
  • Reversal is computable where it is possible at all. Each reversible operation carries a generated inverse — and an inverse is offered only after it has been replayed and shown to land back on the previous model, fingerprint for fingerprint.

That last point needs its qualifier stated plainly, because the temptation to overclaim is strong. Some operations genuinely destroy information: folding two types into one does not record which source each property came from, and changing a field's type does not record the type it replaced. For those, no inverse can exist, and a rollback that merely appears to restore the prior state would be worse than refusing. They are marked irreversible instead, with the reason stated. A system that claims everything is reversible has not thought about the cases where it is not.

Claims like these are only as good as their tests, so they are tested as laws rather than as examples: a property-based suite generates models and operations from the closed vocabulary and checks, for every kind of operation, that applying it leaves a loadable model, that an offered inverse restores the previous one by content hash, and that a computed diff replays to its target.

Identity and verified replay

A recorded history is only worth having if you can trust that it still describes the model in front of you. Two mechanisms make that checkable rather than assumed.

Content addressing. A version is identified by a fingerprint of the model's own content, computed over a canonical form so that irrelevant ordering differences do not change it. Two models are the same version when they say the same thing, regardless of who produced them, in what order, or through which route. This is what makes “is production running the model we approved?” a question with a mechanical answer. The canonical form is itself versioned; when it is refined, stored histories are rehashed in one step rather than left to fail verification.

Verified replay. Each recorded change carries the fingerprint of the model before it and after it. Replaying the history recomputes those fingerprints and compares. A history that no longer describes the model it was generated from fails loudly at the point of divergence, rather than producing a plausible and wrong reconstruction. Loud failure is the entire value: a silent one is indistinguishable from correctness until an auditor asks.

When two teams advance at once

This is where a world model differs most from a codebase, and where single-line versioning breaks down.

A business modelled by twenty teams does not evolve in one line. Sales owns customers, billing owns accounts and invoices, logistics owns shipments, and the platform needs the combination of them. Each advances on its own schedule.

A history that can only be a line has to treat that as an error. It is not an error — it is what actually happened, and a record that cannot represent it is not a record. So parallel work is a first-class recorded fact, and bringing two lines together is reconciled against the point where they last agreed: changes touching different parts of the model combine automatically, and only genuine collisions are put to a person.

commit historyrecipe b7b1f475722afb1bancestore310bf62sales · key by email972b5bccbilling · key by account no.c2e30946merge · 2 parentsa5271f2b+ country732faa86re-mergegraph schemaat 722afb1borderorder_noplaced_byfinds customer by idcustomeridkeyaccount_noemailsigned_up_atpayment_terms+ billingemail_verified+ salescountry+ billing
Figure 1. Left, the history of a graph schema; right, the schema at that point. Two teams change the key of the same vertex type, and both readings are recorded rather than resolved at write time. Reconciliation happens later, against the shared ancestor, and asks only about the one slot that collides. When one team moves on, the recorded decision is replayed rather than asked again.

The unit of collision is the slot — the addressable location an operation touches, such as the identity of the customer type. This is what makes reconciliation precise rather than file-shaped. In the history above, both teams re-keyed the customer, so both changes land on the same slot and collide. Each also added a property of its own, and those land on different slots, so they combine with no question asked.

Writes are not the only way two changes collide. An edge added on one side depends on its endpoint types without writing them; if the other side removes one of those types, no write overlaps, and a merge that compared writes alone would come out clean with the new edge silently gone. So each operation declares what it reads as well as what it writes, and a change that depends on something the other side removed is held back and reported. Where one side made a change that no operation can express, the merge refuses outright rather than report a clean result with that change missing.

A conflict is reported with the ancestor's state alongside both sides, because “what did this look like before either change?” is the question a resolver actually needs answered — and the one a two-way diff structurally cannot express:

reconciling the two branches
left  : 972b5bcc  key customers by account number
right : e310bf62  key customers by email
base  : 722afb1b

1 conflict(s):
  slot   : vertex/customer/identity
  reason : both sides changed this slot differently
  left   : ['replace_identity']
  right  : ['replace_identity']
  base   : identity ['id']

merged (took left):
  identity  : ['account_no']
  properties: ['id', 'account_no', 'email', 'signed_up_at',
               'payment_terms', 'email_verified']
  hash      : 6f5128e9fcd0

merge commit: c2e30946
  parents   : 972b5bcc, e310bf62
  recipe    : b7b1f475b41f

The property list is the part worth reading twice. One side's decision won the contested slot, and both sides' uncontested work survived — both new properties are present. A last-write-wins registry would have silently discarded one of them, and nobody would have known which. That holds because a decision reaches only its own slot: taking the left side on the identity conflict does not take the left side's unrelated edits with it.

The result is a merge commit with two parents, and the written model carries its lineage with it rather than leaving it only in a registry. The recipe on the last line is the part that compounds: it records how the disagreement was settled. When one side later moves on, the combination is re-derived by replaying what was recorded along with the resolutions already agreed, surfacing only the genuinely new conflicts — the last two steps of Figure 1. Without that, every advance of one model means redoing the join by hand — which is the mechanism by which a shared world model quietly becomes one team's full-time job, and then stops being shared.

The same holds when the two lines were never one model and two teams' models are joined by declaring which of their types are the same thing: each declared equivalence is reviewed before either model is touched, and one that cannot be honoured is refused with the rule it broke.

Risk, and refusing by default

Adding an optional property is not the same as replacing the identity policy that determines what counts as the same entity. So when a model change is planned against a live database, each migration step it produces carries a risk rating — low, medium, high or critical, with a change to the key that identifies a vertex or edge always critical — and the executor refuses anything above low unless it has been explicitly authorised. The point is not that dangerous changes are forbidden — sometimes the identity policy genuinely is wrong and must be replaced. The point is that such a change cannot happen by momentum, as a side effect of a routine run that nobody read closely.

Identity changes deserve their own note, because they are the case most often underestimated. Changing what identifies an entity is not a schema edit with a data consequence; it is a data problem wearing a schema edit's clothing, since every existing key and every reference to it has to be reconciled. Treating it as ordinary DDL is how organisations get silently duplicated entities.

This is also why identity is worth declaring richly in the first place, so that the common case never needs a re-key at all. Where sources identify the same entity by different evidence, an identity funnel states the fallback order once — the account number where it is present, otherwise the email address, otherwise name and postcode — and a row is keyed by the strongest evidence it happens to carry. Because the key records which rule produced it, a later argument about why two records did or did not fuse is answerable from the data rather than from memory.

Where the model plane ends

Everything above governs the model — the contract that describes the graph. That is deliberately where the emphasis sits, because it is where the risk concentrates: a mistake in the contract reaches every consumer, while a mistake in one materialised database reaches one database.

Carrying an approved change set further down — compiling it into the exact statements a given backend would execute — is deliberately narrower. It runs as a dry run by default, and a backend it cannot compile for is refused by name rather than guessed at; which backends it covers is in the GraFlo documentation. Model-level evolution is the mature, replayable part, and governing the model is the part that pays first.

The model also describes more than the business types. Provenance, state over time and access are vocabularies every domain needs and none owns, and they arrive on a model the same way as any other change: as operations a reviewer reads, replays and can trace. That is the subject of provenance, time and access as schema changes.

What to ask about model change

Questions worth putting to any candidate, including ours:

  • When two versions of the model differ, do I see a computed diff, or the actual change that was made?
  • Can a change be reviewed and approved before it is applied to anything?
  • Which changes can be undone, and does the system tell me plainly which cannot — or does it claim everything is reversible?
  • If the recorded history no longer matches the model in front of me, does replay fail loudly or produce a plausible answer?
  • What happens when two teams change the model in parallel? Is that an error, or a recorded fact?
  • When one side later advances, do I re-argue the earlier decisions or are they replayed?
  • Is a destructive change refused by default, or applied because nobody read the plan closely?

The model, meanwhile, is a file you own. It is portable across engines — the subject of database independence for knowledge graphs — and servable to agents under policy, the subject of governed context for AI agents. The engine that implements all of it is GraFlo, open source under Apache-2.0.