1 · the method
A knowledge graph compiled from source, invariants written on it, meaning written over it
An architectural compiler has three layers with different authorities. The extractor reads the tree into a typed graph. Rules are checked against that graph, and this is where a team's own rule sets enter. A model then writes the enriched graph: what each component is for, what each interface takes and returns, and how a request moves through the system.
- the whole repository
- read lexically: no code is executed
- every fact keeps its file and line
- a small set of node kinds and edge relations
- generic rules produce them
- each node and edge carries its rule and its evidence
- checks over the ontology, each with a rung, a reason and pseudocode
- custom rule sets are injected here, as declarations
- the only layer that fails CI; a ratchet keeps it from loosening
- component definitions: purpose, responsibilities
- a record over every node, interface types included
- input and output definitions per route
- system flows: articulated paths, a detail and citations per step
- one drawing, 2D and 3D
- code view, extraction map, CI gates
- flows read step by step
- history: the compiler replayed over every commit
The extractor overfits a shape
It asserts the code has certain forms and reads anything else as absence, silently. So every call it saw but could not read is counted and gated (unparsed routes and commands, unresolved paths and store calls), every idiom it learns becomes a generic rule with a test, and the mechanical layer stays minimal and typed: structure only, no meaning.
Meaning is written over the graph, never into it
Purpose, input and output semantics, and the story of a flow are the model's to write, from bounded excerpts of the code at each hop. The graph bounds what it may say: every identifier must exist, every step must be an edge, every citation a line it was shown. It cannot add a node or an edge, and it cannot fail the build except by going stale.
2 · the approach
A mechanical architecture, compiled from source on every change, and enforced at CI time
Not a diagram someone draws. The architectural compiler reads the tree and derives the system map from lexical facts: an HTTP application being constructed, an app.get(, a table declaration, a .references(() => table.id), a setInterval( in a process entry, an import of a vendor package, a path template that names an API route. Each rule is a generic shape; none names a feature.
Observed
What the grammar reads from the code: routes, tables, foreign keys, imports, signatures, poll loops, the collections a process keeps in memory. Every node links to a file and line.
Declared
What the code cannot say about itself: which container holds what, which zone a route segment belongs to, which vendor is a system and which a library, where the API's contract document lives.
Checked
Invariants over the observed map. A declaration that stops matching the tree fails the build with a sentence saying what moved.
Explained
A model writes the prose over the facts: why a module exists, what a type represents, how a request travels. Validated against the map, never a gate.
3 · the invariants · mechanical
Invariants on three rungs, every one mechanical, every one with a reason
These are what CI enforces. Each is a check over the observed map; none consults a model. Each declaration names its rung and carries its check as pseudocode, which the site shows beside it. Whether the code gave the right map is a fourth rung: the compiler's own tests, not a declaration.
| extraction shape the code stays readable by the compiler; a deviation fails instead of vanishing | |
| single-http-app | Exactly one HTTP application in each declared core. |
| namespaces-reachable | Every routes file is registered by the core, by a registered router, or through a registry the core loops over. |
| routes-declared-literally | Every route declaration names a path the grammar reads: a literal, a template, a one-valued constant, or a conditional between two literals. Its first run found routes the map had been missing. |
| commands-declared-literally | Every CLI command is named as a literal or a name the enclosing loop enumerates. |
| client-paths-resolve | Every API path a browser client or CLI command spells matches a declared route, verb included. |
| store-calls-resolve | Every store call names a method a store class defines, including stores handed in as dependencies. |
| tables-declared-in-schema | Every table is declared where tables live, and the census may not fall below a floor. |
| externals-observed | Every declared external system is observed by a signature in source. |
| vendors-declared | Every third-party package imported is a declared system or a declared library. |
| clients-declared | Every browser module that opens a connection belongs to an identified client. |
| enrichment consistency the model's words stay bound to the map and the code | |
| flows-traceable | Every system flow is a path over edges the map draws; its citations are lines of files on that path, hashed, so it goes stale when they change. |
| architectural policy rules about the system itself, chosen by the team | |
| namespaces-zoned | Every API module sits under a declared zone by its first path segment. |
| pages-zoned | Every page in the browser apps sits under a declared route group. |
| browser-apps-never-reach-storage | No page or client of a browser app touches the database or object storage directly; every row and file goes through the HTTP API. |
Fail-closed declarations
A file that doesn't exist, a signature that matches nothing, an external system with zero hits: each fails the compile with the missing declaration named.
The ratchet
A second gate refuses a change that drops an invariant, grows an exception list, removes a gate step, deletes a specification, or leaves a record or flow stale that the base had fresh. Tightening always passes.
The contract
The compiled model is checked against a pinned schema, so the map's shape can't drift either.
What it caught as the main branch moved under a long-lived branch
namespaces-reachable until the compiler learned the shape. A new page failed pages-zoned until it was declared. Routes declared with an unfamiliar verb helper and tab-indented store classes read as nothing until the grammar admitted both. A new vendor package failed its declaration. Records and flows went stale on lines that had moved, and the ratchet refused the merge until they were rewritten. In every case the build said which declaration to change, in the same change.4 · two authorities in one artifact
What is read mechanically, and what a model wrote on top of it
Every number, node and wire is mechanical. Every sentence that explains them is synthesized by a model from a bounded packet of those facts, then checked against the map. The artifact labels which is which, and so should any reading of it.
mechanical The map nodes · edges · every commit
- Nodes: modules, routes, CLI commands, tables, pages, clients, entry points, periodic tasks (registered intervals and the poll loops a process starts), the in-memory collections a process keeps (one copy per process), external systems, principals, and the types the API's contract document declares. Each from a match at a file and line.
- Edges: registration, page→client→route, route→store→table with read or write, table→table foreign keys with the columns and the delete rule, route→in-memory collection with the exact call chain, route→principal, process→system. Each carries the rule that produced it.
- Contracts: each route joined to the operation the API's own contract document declares, parameters and schemas inlined; routes it does not mention are marked.
- Zones, containers, hosts: declared by people, checked mechanically against the tree.
- Invariants, gates, ratchet, contract: the only things that can fail CI.
- History: today's compiler re-run over every commit; the slider is replay, not inference.
- Evidence: every node and edge deep-links to source; the extraction map shows the exact lines each rule fired on; the code view opens any construction to its files and functions.
synthesized The prose summaries · records · flows
- Component summaries: what each source component is for, its responsibilities, open questions.
- Construct records: one per module, route group, table, page, client, entry and system: a purpose (why it exists, for whom, what it unlocks), a summary of what it does, typed fields, open questions. One per contract type too: what an instance represents, its identity and lifecycle, a note on every property.
- System flows: stories over edges the map draws; every step carries a detail written from the code at that hop, with citations.
- How it is bounded: a record is written from excerpts of the node's own files; a type from the source that declares it; a flow from excerpts of every hop on its path. The graph bounds the path, the code supplies the words. A citation outside the excerpts shown is discarded.
- Provenance: the lines around every citation are hashed. Edit those lines and the record or flow goes stale; move an edge and the flow is broken. The ratchet refuses a change that leaves new staleness behind.
- What it can't do: fail the build on its own, add a node or an edge, or be trusted as fact. Its one hook into CI is that a flow's edges must still exist.
One request's path through the artifact
5 · beyond the route list
The parts of a running system that a route list leaves out
Keep asking "why isn't that on the map?" Each answer is a new generic rule, not a special case, and each lights up things nobody had been asked to declare.
What a process keeps, and its loop
A written Map, Set or array in a module the process loads is a node. A setInterval, or a while (!stopped) loop the entry starts, is a periodic task, with the steps of one round and the collection each step touches. Routes reach a collection through their exact call chain, even when the store arrives as an injected dependency.
How the tables relate
Every foreign key in the schema is an edge between tables, with the column, the target column and the delete rule. Select a table and its keys light up; before, the tables stood alone inside the database.
What each route promises
If the API serves a contract document, the compiler joins each route to the operation at its method and path shape and inlines every schema. Routes with no operation are marked undocumented; an operation naming a route that does not exist is an error.
What each type means
Each schema in that document is a construct. The model reads its declaration and the routes that carry it, and writes what one instance represents, its identity and lifecycle, and a note per property. A note on a property the schema does not declare is rejected.
The code behind a construction
Where the environment allows, the language's own compiler draws a class diagram per construction and resolves calls by name. This sits on top of the lexical map and is marked as such; the gates never depend on it.
Reading it
The same drawing in two and three dimensions: containers on their hosts, one bundle of wires per container at rest and a node's own wires on hover. A flow can be walked one step at a time.
6 · the problems with a mechanical graph
It is fitted to a shape, it checks a snapshot, and it is only as true as its grammar
Overfitting
The compiler asserts the code has a certain shape: one web framework's apps and routes, store methods, one page convention. A new idiom doesn't fail loudly; it reads as nothing. "Anyone can call this route" can mean "the declaration named no credential the grammar knew". A contract join is only as complete as a hand-written document: a route it never mentions reads as undocumented, which is true, and says nothing about whether it validates its input.
It checks, it doesn't understand
CI says every route is registered, not that it is authorised correctly. It says a table is used, not that the query is right. It says a route reaches a Map, not that the Map is safe across two machines. The invariants are about shape, and shape is necessary, not sufficient.
The prose is plausible, not proven
Records and flows are checked for consistency with the map, never for truth. A summary that calls one app by another app's name can pass every check when the schema uses that word. Some journeys never get a traceable flow: the model keeps starting at the API client, and the validator refuses a path that never left the page.
Every one of these was a real idiom that read as absence until the grammar learned it
registerXRoutes(app, …)
a registry the core loops over
routes declared through named constants
clients written as classes, or as modules of functions
a wrapper that supplies the API prefix
a store two hops away through a re-export
a store handed in as a dependency, called through a private wrapper
a poll loop started one import away from the process entry
a handler that verifies the bearer itself
store classes indented with tabs
Concretely, what would drift past it
7 · next
Make the compiler stateful: check the shape against its own history, and against what actually ran
Shape diffs per pull request
The history already derives the map at every commit. Compile the change, compile its base, and show the delta: modules gained and lost, routes that changed principal, tables no route reaches any more, a route whose contract changed. A reviewer reads a sentence, not a map. Built since these slides were first given.
Trend budgets, not floors
Floors catch cliffs. Budgets catch slopes: routes admitting anyone may not grow, undocumented routes may not grow, tables unreached by any route may not grow, over a window of commits. The history walk is the time series; the ratchet is the enforcement point.
Confirm the graph with runtime evidence
Tracing already sees every request and the store every query. Join traces to the static edges: an edge the map draws that never fires in a week is a question; a request path that fires with no edge on the map is a grammar gap, surfaced automatically instead of by a reader noticing.
The technique travels
The same compiler shape (layered rules, purpose on every record, a call index, extraction counters, a freshness ratchet) has been ported to two other repositories in other languages, one with a different grammar front end entirely.
What stays the same
Every gate stays mechanical and explainable. A failure names the file, the line, the declaration and the reason. The model's prose stays labelled, bounded and advisory. The team edits declarations, not the compiler, and loosening stays a labelled, reviewed act.
8 · what's next?
Put the architectural compiler into the loop, then learn to measure it
Into the loop
Inside the change that caused it
The compile, the gates and the prose refresh run inside the change: as a pull request check, and as a step an autonomous coding pipeline takes, so the map never lags the tree.
Peer validation and feedback as a system flow
A record or flow a reader disputes becomes a tracked correction: who objected, to which claim, resolved by a rewrite or an upheld open question. The feedback path is itself a flow on the map.
Diffs in the review of agent-written changes
The shape diffs are posted into the review an agent pipeline already runs, so an agent's change is judged on what it did to the system's shape as well as to its tests.
Measuring and hardening
Charting overfitting
The extractor reads a shape, so its coverage has to be measured, and the first question is the boundary: per file, per module, per container, per rule family? The counters exist (unparsed, unresolved, undocumented); the chart over time and over boundaries is the next step.
Ratchets defined on the code
The first ratchet protects declarations. The next ones sit on the code itself: coverage per rule family may not fall, undocumented routes may not grow, the call index's unresolved share may not rise.
Common invariants for the chain shapes
The same request chain recurs in every repository: surface → client → route → store → table, entry → task → collection. A shared invariant set for those shapes ships with the engine, and a repository adds only what is particular to it.