Chapter 10 — Structural Engineering: Parnas and the Harnessable Codebase

"We propose instead that one begins with a list of difficult design decisions or design decisions which are likely to change. Each module is then designed to hide such a decision from the others."

— D. L. Parnas, On the Criteria To Be Used in Decomposing Systems into Modules, CACM 15(12), 1972

Fifty-four years old, and it turns out to have been about something Parnas did not name.

10.1 The most radical answer

Part II has been circling one problem. An agent must act on a repository it cannot hold in view.

Chapter 6 tried to solve it by designing the payload, and found a ceiling: the whole file scored 12.7% against 18.0% for a window of it. Chapter 9 tried to solve it by making the repository navigable rather than resident, and got real gains — 92.7% file-level localisation, an 86% cost reduction — but hit a ceiling of its own. A graph over four hundred mutually dependent modules with no layering faithfully reports a tangle. It makes the tangle navigable. It does not make it small.

This chapter's move is the one nobody reaches for first, because it is the most expensive: change the codebase so that less has to be known.

Chapter 8 already supplied the theoretical warrant. Ashby's constraint forces variety reduction — a regulator cannot regulate more variety than it has a model of, so either the harness grows without bound or the space of what may be produced shrinks. And harnessability, in that chapter's formulation, is variety reduction already banked. This chapter asks what happens when a team banks it deliberately.

The answer turns out to be that a fifty-four-year-old paper was right for a reason its author did not state.

10.2 The property Parnas did not name

Parnas's 1972 criterion is one of the most-cited and least-followed results in software engineering. Decompose a system not by the steps of its processing but by information hiding: each module conceals a design decision likely to change, and its interface reveals as little as it can.

The benefits he argued for were changeability, independent development, and comprehensibility. All three are about humans — about limiting how much a person must understand and how far a change propagates through a team.

Now state information hiding as a formal property rather than a design heuristic:

Encapsulation is the guarantee that a module's interface is a complete description of what a client may rely upon.

And notice what follows immediately. If that guarantee holds, then a client reasoning only from the interface reasons correctly. Everything relevant is visible; nothing relevant is hidden elsewhere.

An agent working through a bounded context window is a client reasoning from a partial view. So:

Information hiding is precisely the condition under which local inference is sound.

That is the property. Parnas did not name it, and I do not think he could have, because for fifty years it was masked. Humans compensated for leaky abstractions constantly and invisibly — with institutional memory, with a colleague who said "careful, that thing also mutates the cache," with a sense developed over years of which parts of the system lie to you. The epistemic failure was real and it was absorbed by people.

Remove the people and the property becomes load-bearing.

This is the Lindy payoff Chapter 0 promised, and it is worth being precise about what kind of payoff it is. Parnas's criterion did not survive fifty years because it was fashionable. It survived because it was a claim about structure, and Chapter 5 established the distinction that matters: claims about structure survive regime changes, claims about cost do not. "A pull request is a checkpoint" was just as old and did not survive, because it was a claim about the price of producing one.

There is a provocation available here that the book's research notes proposed as a chapter title: design patterns were always for the machine, we just did not have one yet. It is nearly right and I think the accurate version is more interesting. Many patterns were never about local soundness at all — a good number of the classical catalogue are workarounds for the limitations of specific languages, and a good number are ceremony. What the machine provides is not vindication but discrimination: it separates the patterns that made local reasoning sound from the patterns that merely made code look organised. The machine does not prove we were right. It tells us which of our habits were load-bearing.

10.3 A leaky abstraction is invisible from the inside

Take the contrapositive of §10.2, because it is where the damage happens.

Where encapsulation leaks — where a client depends on something the interface does not express — partial observation is insufficient. That much is obvious. What is not obvious is the second half:

The insufficiency is undetectable from the partial view. The agent sees an interface that looks complete. There is no signal distinguishing a module that tells you everything from a module that tells you most of it.

Chapter 5 named the characteristic failure mode of this era: plausible-but-wrong output at machine speed. Figure 10.1 is its mechanism at the structural level. The agent is not guessing. It is reasoning correctly from evidence that was silently incomplete, and producing a confident, well-formed, wrong change.

Two consequences worth drawing out.

Review does not catch this reliably, because the reviewer is also reading a diff against an interface. Unless the reviewer happens to be the person who remembers the hidden coupling, the same incomplete evidence is available to both parties. This is a failure mode where an extra pair of eyes adds little, which is precisely the class of failure Chapter 3 said organisations cannot afford, since review is the constraint.

And it explains something in Ozkaya's observation that architecture knowledge encodes why, which is not recoverable from what [D] 🔴. The hidden couplings in Figure 10.1 usually exist for a reason — a performance requirement, a transaction boundary, a vendor quirk. The why is what makes them intelligible, and Chapter 9's decided_by edge is the only mechanism in this book for delivering it at the moment of the change.

10.4 Bounded contexts are context boundaries

Evans's bounded context is a strategic pattern: divide a domain into semantically consistent parts, each with its own model and vocabulary, and make the boundaries explicit.

The observation for our purposes is almost too neat: a bounded context is a natural context-window boundary. Inside one, the vocabulary is consistent, the invariants are local, and the information needed to make a correct change is co-located. Across one, terms mean different things — the Order in fulfilment is not the Order in billing — and an agent that carries assumptions across the boundary is committing exactly Figure 10.1's error at a larger scale.

So domain-driven design's most strategic pattern turns out to double as a scoping instrument for delegation: a task that fits inside one bounded context is a task where local inference can be sound. A task that spans two is a task where it cannot be, and which therefore needs either a human or a much more careful decomposition.

That is a usable rule, and Chapter 13 uses it: cross-context tasks belong at a lower autonomy level than within-context tasks of the same apparent size, regardless of how many lines they touch.

10.5 The bounded-context proposition, and its flaw

Now the idea this chapter was expected to celebrate, and a necessary correction first.

The proposition, as it circulates: if modules have bounded size, bounded interfaces, and bounded fan-out, then the context required to modify any module is bounded regardless of the total size of the codebase. The book's research notes call it the most elegant single idea in the space and give it a name — "Constant Context Architecture."

I could not locate a primary source for it. Searching for the name returns discussions of bounded contexts and fan-out in domain-driven design, but no paper, article, or author proposing this as a named architecture. It may exist somewhere I did not find; it may be a synthesis by whoever wrote my research notes; it may be a name attached to an idea that never had one. Either way, this book does not attribute unverified claims, so the proposition is examined here on its merits and named nothing.

And on its merits, it is half right, in a way that matters.

Ask what you actually need to know to change a module M.

The distinction the proposition misses:

Bounded module size, interfaces, and fan-out bound the context for an implementation change. They do not bound the context for an interface change, which requires enumerating fan-in — and fan-in is unbounded for exactly the modules that are most reused.

This is not a quibble. Interface changes are where the expensive work lives: signature changes, migrations, deprecations, and — critically for this book — extraction, which is Chapter 4's entire subject. A utility used in two hundred places has, by construction, unbounded fan-in, and no architectural constraint can fix that without forbidding reuse.

So the honest version of the proposition is narrower and still valuable:

Bounded size, interfaces, and fan-out make the common case — changing a module's behaviour without changing its contract — independent of codebase size. The uncommon and expensive case remains proportional to fan-in.

Which raises the obvious question: can you bound fan-in too? Only by not reusing things. And that puts the two goods in direct opposition, which is the subject of the next section and the reason Chapter 4's hardest question can finally be answered.

10.6 Chapter 4's question, answered

Chapter 4 ended with an open question I said I did not find obvious, and promised this chapter would return to it:

Is duplication actually debt in an agentic codebase? If regenerating a variant is cheaper than understanding an abstraction, some duplication may be correctly priced, and the metric may be measuring a human-era virtue.

Figure 10.2 provides the machinery to answer it. Re-examine Chapter 4's two correct options in terms of fan-in.

For a human-maintained codebase, extraction is still clearly right, and the reason is amortisation. A human reads the abstraction once and carries the understanding across the whole codebase and across years. The cost of comprehending the abstraction is paid once; the benefit accrues at every call site. Duplication, conversely, multiplies the places a bug must be fixed by someone with finite attention.

For an agent with no memory across sessions, the amortisation does not happen. Each session re-derives what it needs from what it can see. The abstraction's comprehension cost is paid every time, and the risk of a wrong contract inference — Figure 10.1 — is paid every time as well. Meanwhile the benefit of duplication rises: two independent copies each satisfy the soundness condition of §10.2, and neither can break the other.

So Chapter 4's uncomfortable possibility is real. The optimal amount of duplication may genuinely be higher for agent-maintained code than for human-maintained code, because abstraction's central benefit is amortised understanding and amortisation requires a persistent understander.

But that is not the end of the analysis, and the resolution is the most satisfying thing in Part II.

What makes extraction expensive for an agent is not the abstraction. It is the fan-in enumeration problem — knowing every caller, which Chapter 9 showed lexical search answers with recall and no guarantee. Give the agent a reliable callers_of and the calculus inverts: fan-in becomes enumerable, the interface change becomes safe, and the cost that made duplication rational disappears.

Whether duplication is correctly priced depends on whether you built Chapter 9's graph. Without reliable reference tooling, high duplication is a rational adaptation to unreliable instruments. With it, duplication is straightforwardly debt again.

Three things follow, and I think they are the chapter's most useful output.

The GitClear signature is evidence about tooling, not about agents. Moved code falling from 24.8% to 9.5% while copy-paste rose [C] is what you would predict from agents working without reliable fan-in enumeration. It is not evidence that agents cannot refactor. It is evidence that nobody gave them the instrument that makes refactoring safe.

This is a testable prediction, and it is the same test Chapter 9 proposed from the other side: repositories with graph-backed reference tooling should show less of the duplication signature. Two chapters now converge on one unrun study, which is a good sign that it is the right study.

And it explains why the two pillars are not independent. Chapter 9 makes structure navigable; Chapter 10 makes it small. But Chapter 10's central practice — extraction, the thing that creates abstraction — is only safe because Chapter 9 exists. Structure and graph are not parallel options. The graph is what makes structural improvement affordable.

10.7 An unrepresentable state needs no sensor

Now the argument that puts this chapter at the top of a hierarchy rather than fourth in a list.

Chapter 8 established the ordering rule: use the cheapest deterministic sensor that can detect the failure class, and reserve inferential sensors for what genuinely needs judgment. It also established that every control has an ongoing cost — maintenance, false positives, budget, drift — and must be periodically drilled to prove it still fires.

Structure escapes all of that.

A state that cannot be represented needs no sensor, no drill, and no maintenance. It is not detected; it is impossible.

If your type system makes an unvalidated order unrepresentable, there is no lint rule to write, no hook to wire, no false positive to triage, no drill to schedule, and no chance the control silently stops working. The failure mode is not caught late or caught early. It never occurs.

That extends Chapter 8's ordering rule from two tiers to four, ordered by cost of ownership rather than by speed:

This is Taleb's via negativa in its strongest form in this book, and it is the third time the same shape has appeared: removal is more reliable than addition, because you can be certain about what you have eliminated and only hopeful about what you have introduced. A type that forbids a state has eliminated it. A guide that discourages it has introduced a hope.

It also reframes what an API is for. The conventional view is that an interface exposes capability. The agentic view, which is really the old view taken seriously, is that an interface's most valuable property is what it makes unsayable. An API where the bad call does not compile is a permanent, zero-maintenance control. This is the MicroSkill principle in its general form — make correct behaviour the path of least resistance [B] 🔴 — and the more aggressive version is available: make incorrect behaviour unavailable.

Practical translations, all cheap and all under-used:

• Newtypes and branded types instead of primitives, so an unvalidated value cannot reach a function expecting a validated one.
• Constructors that cannot produce an invalid instance, rather than validators that check afterwards.
• Enforced layering, so a forbidden import does not build.
• Narrow tool permissions, so an agent cannot reach the production database rather than being instructed not to.

That last one is worth noticing, because it shows the principle is not confined to code: capability scoping is structural engineering applied to the agent's environment, and it is Chapter 11's main instrument.

10.8 The same argument, applied to the agents

One reflexive turn before the admission, because it is genuinely the same argument.

Everything in this chapter concerns bounding what must be known to make a correct change. Apply it not to the code but to the workforce, and you get modular delegation.

MASAI does exactly this: a modular architecture in which distinct LLM-powered sub-agents are instantiated with well-defined objectives and strategies tuned to those objectives [B] ✅. Its stated advantages read like Parnas transposed: tuning different problem-solving strategies per sub-agent, letting sub-agents gather information from sources scattered through a repository, and — the one that matters most here — avoiding unnecessarily long trajectories which inflate costs and add extraneous context. It reported 28.33% on SWE-bench Lite, the highest at the time.

That third advantage is Chapter 6's dilution problem solved structurally. A sub-agent with a bounded objective has a bounded context by construction; it cannot accumulate the irrelevant history that Chapter 2 measured at −3.0 points. Information hiding applied to tasks yields the same benefit as information hiding applied to modules, for the same reason.

So Chapter 12's Decompose phase and Chapter 13's autonomy ladder are not project management. They are this chapter's principle applied to delegation: a task scoped so that local inference is sound.

And Chapter 7's evidence says the field has not done this. Subagents appear in 131 of 2,853 repositories, median 2, and no repository used the persistent memory feature [A]. The structural move that a 2024 paper showed to be effective remains, two years later, almost entirely unadopted — which is Chapter 7's cost gradient again, since defining sub-agents with distinct objectives is far more work than writing a paragraph.

10.9 The admission

Now the section this book has been promising since Chapter 4, and the one I would most like a critic to attack.

There is no strong causal evidence that modular, well-encapsulated codebases produce better agent outcomes.

Not weak evidence pointing the right way. Not contested evidence. As far as I can establish, the experiment has not been run. What this chapter has offered is:

• A mechanism (§10.2–10.3): information hiding is the condition under which local inference is sound, and leaky encapsulation is invisible from the partial view.
• Consistency with the observed duplication signature (§10.6), which the mechanism predicts.
• Analogy to a result about agent architecture (§10.8) rather than code architecture.
• A theoretical warrant from Ashby (Chapter 8), which says variety reduction is forced but says nothing about which variety reduction works.

That is a well-formed hypothesis with a plausible mechanism. It is not a finding, and everything in this chapter should be read at that grade. Chapter 8's harnessability argument inherits the same status: I claimed harnessability is banked variety reduction, and that strongly typed, well-layered codebases are cheaper to harness. The first half is definitional. The second half is unmeasured.

Being unfalsifiable would be worse than being wrong, so here is the experiment. It is small, cheap, and I am surprised nobody has run it.

Two further predictions, both observational and both cheap:

1. Repositories with stronger static typing should show a smaller duplication increase under agent adoption than matched weakly-typed repositories.
2. Repositories with mechanically enforced layering should show a smaller complexity increase.

Both are runnable on the datasets that already exist — the difference-in-differences design of the Cursor study would extend to either with modest work.

Until someone runs these, the correct posture is the one this book asked for in its preface: state the mechanism, state the absence, and prefer a falsifiable claim to a persuasive one. Chapter 27 keeps all three open.

10.10 Where Part II leaves us

The four rings are built, and they are not four options.

Read outward, each ring exists because the one inside it saturates: the payload has an interior optimum, the harness is bounded by Ashby, the graph reports the structure it is given. Read inward, each ring makes the one inside it cheaper: structure reduces what the graph must index, the graph reduces what the payload must carry, the harness catches what remains.

One thing is missing, and it cuts across all four. Every ring in Figure 10.6 assumes the agent's inputs are information. Chapter 5 established that they are not — every artefact an agent reads is potential instruction, and OWASP ranks goal hijacking first among agentic risks. A context payload can be poisoned. A graph can launder provenance, as Chapter 9 showed. A guide can be injected. And structure — capability scoping, as §10.7 noted — turns out to be the primary defence rather than an afterthought.

Chapter 11 takes up verification and security as the fifth concern that runs through all four rings, and it is the chapter where this book's argument is least speculative and most urgent.