Every plugin platform starts clean and ends muddy. The core begins as a neutral engine, and then — under deadline pressure — a little domain knowledge leaks in. A special case for the flagship feature here, a direct import of a plugin's model there. Each leak is individually reasonable and collectively fatal: eventually the "core" knows about half the plugins, cannot be reasoned about in isolation, and cannot be extended without fear. VBWD prevents this with an automated oracle — a test that fails the build if the core learns anything it should not. This post explains what the oracle checks, how it works, and why mechanical enforcement is the only kind that survives contact with a real schedule.
VBWD's architecture rests on one principle: the core is agnostic; only plugins are gnostic. The core provides mechanism — accounts, tokens, invoices, the CMS engine, the plugin system, the event bus, the registries. It knows nothing about any product domain. It does not know what a subscription, a dataset, a booking, a shop product, or a tarot reading is. All of that vocabulary and logic lives in plugins. The core offers general seams; plugins supply specific meaning.
Stated as a rule for humans, this is a convention, and conventions rot. Someone new does not know it; someone experienced forgets it at 6pm before a release. So VBWD does not rely on humans remembering. It encodes the rule as a test that runs in CI, and if the core violates it, the build goes red. The principle stops being aspirational and becomes a gate.
The oracle has two complementary jobs, and it is worth being concrete about both.
1. The core must not import from plugins. The oracle walks the core's source as an abstract syntax tree and looks for any import that reaches into the plugins package. A direct dependency from core to a plugin is the most obvious violation — it means the core cannot resolve without that plugin present, which breaks the entire premise that plugins are optional and additive. If the core imports from plugins.something, the oracle catches it. Because it works on the parsed AST rather than a naive text search, it sees the real import structure, not just strings that happen to look like imports.
2. The core must not speak plugin vocabulary. A subtler leak is the core containing domain words even without importing plugin code — a variable, a comment, a string, a column named after a specific product concept. A separate guard scans the core's Python for banned domain vocabulary: the names of plugin concepts that have no business appearing in a neutral engine. Data files are exempt (fixtures and seed data legitimately contain domain words), but core logic is not. If core code mentions a plugin's domain term, the guard fails.
Together these catch both the structural leak (an import) and the semantic leak (a concept). You cannot make the core depend on a plugin, and you cannot make the core secretly know what a plugin is about.
The oracle forces a genuinely useful discipline about what belongs in core. The test is not "does core ever touch this value?" — it is "does core route through it, or merely read it?" A port belongs in core only if the core routes behaviour through it generically. The moment core code reads a domain-specific field to make a domain-specific decision, that is a leak, even if no import is involved.
The practical consequence is that when you feel the urge to add a plugin concept to core, the oracle makes you find the general version of it instead. Instead of teaching the core about "vendor id," you add a neutral extension mechanism — a registry, an event, a typed seam — that the plugin populates with its specific meaning. The core iterates over the seam without knowing what any entry means. This is more disciplined than the quick hack, and it is why the platform's second year is cheaper than its first: the seams accumulate, and each new plugin reuses them.
The reason to automate this rather than trust code review is that architectural rules decay in exact proportion to how much they depend on vigilance. Code review is human, inconsistent, and busy. A reviewer catches the obvious import but misses the domain word in a comment; a rushed release skips the careful read entirely; a new contributor never knew the rule. Every missed violation lowers the bar for the next one, and erosion compounds.
An oracle does not get tired, does not have a deadline, and does not make exceptions "just this once." It applies the same rule to every commit forever. That consistency is worth more than a smarter but occasional check, because the failure mode of architecture is not one catastrophic breach — it is a thousand small, individually-defensible compromises. Only something mechanical stops the thousandth one.
There is a legitimate escape hatch. The licensing/security layer is an intentional, documented exception — a narrow place where core is allowed a specific coupling because the alternative is worse. The important thing is that the exception is explicit and bounded, not an ad-hoc bypass. The oracle is strict by default and permits exactly the exceptions that were reasoned about on purpose.
The payoff of a mechanically-clean core is concrete, not aesthetic:
This discipline is not free, and pretending otherwise would undersell how deliberately it is chosen. Sometimes the general seam is more work than the quick special case would have been — you add a registry where a direct field read would have shipped faster. Occasionally you have to stop and design an extension point that does not yet exist, which is slower in the moment than reaching into core. And the oracle will reject changes that a human might wave through as "obviously fine," which can feel pedantic under pressure. The bet VBWD makes is that these local costs are far smaller than the compounding global cost of a core that slowly learns about everything. Every platform that skipped this bet is now maintaining a core it is afraid to touch.
VBWD keeps its core clean by refusing to rely on anyone remembering to. An oracle walks the core's AST and fails the build on any import from plugins; a companion guard fails it on any plugin domain vocabulary in core logic. The rule it enforces — mechanism in core, meaning in plugins; route through ports, never read domain fields — is what makes the core resolve standalone, keeps plugins independent, and gives extension a single known shape. Mechanical enforcement is the whole point, because architecture does not die from one bad decision; it dies from the thousandth small one, and only a machine reliably stops that.
The oracle and the vocabulary guard run in the standard pre-commit and CI gate; read them to see exactly which imports and terms the core forbids.