The validator robot that learns — living documentation in action

The truck that arrived on Tuesday

Last week I signed off with a truck. It pulled up one Tuesday in March at Objectville's north branch with five thousand liters of crushed tomato nobody had ordered. Mixed in with the good goods. Batch MZ-7842-IT. Supplier BLUE-LINE.

I left you three questions: do you send it back? Do you put it in quarantine with a visible label? Do you accept it marked “rejected” so that six months from now you can reconstruct what happened?

The short answer is: it's none of the three. It's all three at once, governed by a single policy. And the policy isn't signed by a committee — it's enforced by a piece of the platform I haven't named yet but that's been leaving its fingerprints all over this series.

Today I'm answering. And I'll start with the doctrinal principle that holds up everything that follows, and with the first concrete example of that piece at work. The trail the BLUE-LINE truck leaves — and where it ends up — we'll see next Tuesday. Today we get to know the engine.

Thursday in the kitchen

Let's jump from the loading dock to the kitchen. Thursday afternoon, an Objectville branch in a small coastal town on the Mediterranean. The usual delivery comes in and, inside it, a new box: “San Marzano DOP tomatoes — regular supplier — new batch from the March harvest”. The box carries its DOP seal in plain sight, its certification number, and the label of the Consorzio del San Marzano dell’Agro Sarnese-Nocerino — the official body that certifies the designation of origin.

The chef sees the box. He smiles. “Good harvest. Let's try it.” He pulls out a tomato, slices it open, smells it. And the smile fades.

— This doesn't smell like San Marzano — he says, handing the tomato to the prep cook. — Taste it.

The prep cook tastes it. Frowns. “You're right. It's sweet. San Marzano is never this sweet at this time of year.”

The chef picks up the DOP seal from the box. Looks at it. The number is there. The Consorzio label is there. But something doesn't add up. He calls the branch's logistics lead.

— The certification number on this box — do we check it against the Consorzio's registry, or do we just trust that it's printed on the box?

Silence on the other end of the line.

— Uh… We check it when the delivery comes in. That the number was there, yes.

— That's not what I asked. I asked whether we call the Consorzio or look up their online registry to confirm that certification number matches a real batch of San Marzano DOP from March 2026.

— No. We don't do that.

— Well, today we do. Call them and send the box back. And let headquarters know this one slipped past them.

Turns out the certification number was valid — it belonged to a real Consorzio batch. But to a batch from last year, already used up. The supplier — knowingly or not, it made no difference — had put an old number on a new box. Real San Marzano tomatoes, yes. Real DOP, no.

In January, Objectville headquarters had signed a common contract that says things like this: “In this chain, tomatoes labeled DOP must come from Campania, be of the San Marzano variety, and carry a current DOP certification with the number visible on the box”. Three lines. Fine. Until that Thursday.

That Thursday the chain is going to learn that three lines weren't enough. That it was going to need a fourth: “Cross-check the certification number against the official Consorzio registry — it's not enough for it to be printed on the box”.

And here's the question that organizes everything that comes in this article and the next: how does a chain of forty branches learn that fourth line without each branch having to learn it on its own the day it happens to them?

The answer isn't an updated PDF. The answer isn't an email from headquarters' quality committee. The answer is that piece. And it has a very specific name.

Axis 1 — Shift left applied to the model: validate before, not after

For two decades, the data industry has been solving the volume problem at the expense of quality. Big data made ELT popular: load first, clean later. Ingestion speed became the metric. Quality became the problem of whoever consumes the data. The result is well known: bad data that gets in unflagged, gets joined with other data, gets served to five consumers, and turns up on an executive dashboard six months later. By then there's no way to know where the error started or which tables it contaminated.

There's an old software principle that solves exactly that. It's shift left: validate at the entrance, don't audit at the end. Coerce before loading, instead of chasing errors after the data has already spread. But it isn't “block everything that isn't perfect” either — that brings loading to a halt. The middle ground is: a few door rules, clear and non-negotiable — this record cannot get in — plus a catalog of warning signs that alert without blocking. The difference between those two kinds of rule is what lets the model load fast and be auditable at the same time. One image nails it: if you ordered fresh tomatoes and they bring you canned ones, anyone on the dock can spot it without knowing a thing about cooking — that's a door rule, and the batch doesn't get in. If you ordered San Marzano and they bring you another variety, you need someone who knows how to taste it — that's a quality signal: the batch gets in flagged, and someone reviews it. The door rule blocks the obvious. The signal records what calls for judgment. Both are necessary. But only one stops the load.

Everything we've described so far — hubs, satellites, links, an executable Shared Kernel, rules attached to the model that run on every load — is exactly shift left applied to the data model. The difference from most traditional implementations isn't about technology — it's about where you validate. If validation lives in an audit process downstream, it arrives too late — the bad data has already gotten in, already been joined with other data, already been served to a consumer, already landed on an executive dashboard. If validation lives attached to the hub/satellite/link and runs on every load, the bad data doesn't get in. And if it does, it leaves an immediate structural trace.

Same common enemy: bad data silently accepted and discovered six months later. Same architectural answer: coerce at the entrance, leave a trace, don't chase errors through old logs. That's the shift-left doctrine brought down to the model. And that's exactly the question that shapes the rest of the article: what does the data enforcer actually look like when a box of tomatoes arrives on Thursday at a branch on the Mediterranean? Not in the abstract. Operationally, what is there in the factory that decides whether it gets through or not? That face has a name.

Axis 2 — The validator robot that learns: living documentation in action

If I had to pick a single piece of the whole platform we're describing — just one, the one that sets us apart most from any traditional implementation — it wouldn't be the Data Vault methodology. It wouldn't be the executable Shared Kernel either. Or the catalog of canonical hubs. It would be the piece that sits beneath all of them and makes them actually work: living documentation.

And this is where I have to cut through a misunderstanding the industry has been dragging around for twenty years.

In most companies, “documentation” means this: a Confluence space with pages someone wrote in 2019, capturing a domain's quality rules in natural language, that nobody updates. Reality changes. The rules change. The documentation stays the same. Three years later, the documentation describes a system that no longer exists. A PDF saying “cancelled contracts must have a zero balance” coexists with operations the business changed long ago: rounding off residual balances of up to five euros has been approved since Q2 of last year. Documentation and reality drift apart for good. And nobody notices until an auditor opens the PDF and starts asking.

Living documentation is the exact opposite. And the word that defines it is the one already in its name: living. Not descriptive — operational. Not read — executed. Not maintained by hand — derived from the code.

Concretely, living documentation has three pieces that travel together, all three in the domain's repository, all three versioned:

1. The domain contract — the Recipe — written in declarative JSON, with the entities, the attributes, the relationships, and the rule catalog with its severity levels.
2. The generated models — the SQL/dbt code the platform generates from the Recipe, which loads the data into the hub/satellite/link following the contract.
3. The executable tests — the same ones in the rule catalog, derived automatically from the Recipe, which run every night before the data is published and answer the question every chain needs to answer every single day: “does what's in the model meet what the contract says it has to meet?”

The three pieces are the same thing expressed in three languages. The business signs the Recipe in its own language. The platform executes the models in SQL. The orchestrator fires the tests every night. All three say the same thing. All three move together. When one changes, the other two change with it — automatically, not out of some team's good will.

That's the operational difference. When someone updates the contract — adds a new rule, refines a severity, modifies an attribute — the change propagates to the other two sides without asking permission. The documentation can never drift from reality because reality is the documentation, executed.

And this is where the validator robot in the title comes in. It's not a literal robot. It's that piece — living documentation as an active mechanism — seen in operation. A process that every night reads the rule catalog, runs it against the day's data, and leaves a structural trace of every decision. A piece that doesn't get tired, doesn't forget a rule, doesn't skip a validation because it was in a hurry that day. And that learns — every time the business refines the catalog, the robot learns without anyone having to reinstall anything.

Before going on, let me put down the first card from the factory notebook.

Card 1 — Signed Recipe for San Marzano DOP tomatoes (version 1, signed January 12)

INGREDIENT          : San Marzano DOP tomatoes
CONTRACT SIGNED BY  : Chain Quality Management
IN FORCE SINCE      : 2026-01-12
DOOR RULES          :
  R1 — origin           = Campania (Italy)                · severity: CRITICAL
  R2 — variety          = San Marzano                     · severity: CRITICAL
  R3 — certification    = DOP visible on the box          · severity: CRITICAL
ACTION if CRITICAL  : return the batch to the producer with a reason
ACTION if WARNING   : accept and flag for human review
ACTION if INFO      : accept and leave a trace in QSAT

That card lives in the Products domain repository. It's code. You can read it on a screen. It's the human-readable version of the JSON contract. And when, on Monday, January 12, a supplier delivers the first batch of the year with the DOP seal, that card runs — the platform checks R1, R2 and R3, and leaves a trace in the QSAT (the piece we'll see next Tuesday). If they all pass, the data gets in. If any of them fails with CRITICAL severity, the batch is sent back with a reason.

Until Thursday, March 18, that card works. It runs every night on every batch that arrives from every supplier at every branch. It comes up green on thousands of checks.

And then along comes the chef on the Mediterranean with his phone call.

— It's not San Marzano DOP — my palate tells me so, and the seal says it is. Something about the seal isn't being checked.

The chef is right. The card checks that the seal is on the box, but it doesn't check that the seal is valid against the Consorzio's official registry. The existing rule is correct — but incomplete. And here's the doctrinal pattern I want to nail down before wrapping up today: the rule catalog isn't installed perfect on day one. It's built complaint by complaint. It's refined against reality. It grows with the business, not against the business.

And translated into data.

In Week 5, when we talked about the chef's pass — the spot in the kitchen where the chef checks the dishes before they go out to the dining room — I gave an example from the Accounts domain: “If a cancelled contract has a balance of €500,000, I don't buy it”. The business signs the living rule. Three words: “if status = CANCELLED, then balance = 0”. The platform runs it every night against all the contracts cancelled that day. If it finds one with a non-zero balance, the system fires — the dish doesn't go out to the dining room until someone looks into it.

It's the same piece. The same living documentation. The same mechanism. Only the domain changes: in the kitchen it's San Marzano DOP tomatoes; in banking it's a cancelled account with a balance. The validator robot is the same.

And the original card — “if status = CANCELLED, then balance = 0” — is version 1 of that rule in the Accounts domain. Three words. It runs every night. It works. Until the day reality puts it to the test.

What's next

What happens when a branch discovers the rule was incomplete — the chef on the Mediterranean on Thursday, March 18 — and what happens when a supplier sends a duplicated batch mixed in with the good goods — Tuesday's BLUE-LINE truck — are the two questions that organize next Tuesday.

The questions are concrete:

• How does the catalog learn when a branch detects something the rules didn't account for? V1 was correct but incomplete — how do you update it without stopping the chain, without convening a committee, without emailing 40 branches? And where does the trace of what the rule said before March 18 stay, so an auditor can reconstruct it?
• Where does the structural trace stay when a hard rule rejects a record — the BLUE-LINE truck with its five thousand liters — so that six months from now you can reconstruct what was rejected, for what reason and under what severity? A logs folder? A separate table? Or is there another piece of the model we already know without realizing it, one that's also a satellite, also Data Vault vocabulary, and that records quality events like any other piece of the machinery?

And behind both there's an intellectual doctrine you can't skip — because it settles the false dilemma of “either we validate everything and the business grinds to a halt, or we validate nothing and anything gets in” with three different severities that any quality lead recognizes instantly. That doctrine has an author with a name and a book from almost two decades ago that's still the operational standard in the field. I'll name him on Tuesday.

We're going to see what happens to the rule when reality puts it to the test. Until then.