2.1 From Context to Engineering Models

A foundation model knows Python, React, queues, databases, and common architectural patterns. It does not acquire your service boundaries, deployment topology, ownership rules, yesterday's migration, or local engineering conventions from pretraining. Those facts live in the engineered environment — in source, configuration, registries, documentation, history, and the people who maintain the system — and each reasoning episode has to recover the subset the task needs.

An agent can reconstruct much of that knowledge from raw artifacts. Point it at the repository and it can often discover what calls what, where a service runs, and who appears to own which piece. The problem is cost and scale. Once the task requires more state than the reasoner can keep usefully active, exploration becomes selective and repeated; the next agent may pay much of the same reconstruction cost again.

The first modeling move is therefore modest: externalize engineering knowledge that should not have to be rediscovered. Name the services, modules, APIs, queues, owners, requirements, policies, and tests; name the relations among them. The agent then retrieves the connected slice its task touches instead of rebuilding that slice from raw files every time.

The Modeling Principle: externalize engineering knowledge and intent into explicit, structured models that both engineers and agents can reason through. In other words: once a system outgrows what anyone can hold in mind, stop rebuilding its meaning from raw files for every question, and give each question a purposeful representation—selected context, connected knowledge, or an invariant-bearing model—instead.

This Part begins with the lightest form—externalized context—and progressively adds semantics, explicit properties, and stronger correspondence to the system. This chapter defines what counts as a model and the questions used to choose one.

2.1.1 A Model Is a Purposeful Reduction

A model is a purposeful reduction of a system. It preserves the information one engineering question needs and suppresses the detail that question does not. Its value is not completeness but selective omission. A reduction an engineer or agent can reason through is more useful than a faithful copy too large to hold in view.

Tolerance and degrees of freedom

The suppressed detail has a realization-side consequence. Engineering obligations rarely determine a single acceptable realization. They constrain some variation and leave other choices open. This book uses two engineering terms for that distinction. A tolerance bounds the variation that an obligation permits; a degree of freedom is a realization choice left open because the governing obligations do not distinguish among its acceptable alternatives. Purposeful reduction therefore does two things at once: it represents the distinctions the engineering question requires while declining to settle choices that do not matter to that question. MAGE does not seek to close those degrees of freedom merely because they could be specified.

In software engineering, a tolerance can be numeric but is often qualitative. A latency budget may set a numerical bound: a response must complete within 200 ms. Coupling admits an intermediate form: an architecture may tolerate dependencies up to a measured threshold while also distinguishing kinds of coupling that are acceptable or prohibited. Other architectural tolerances are primarily qualitative: one component may depend on another through a declared interface but not reach directly into its implementation. This range follows partly from the engineering medium. Many physical engineering problems work with continuously valued properties such as length, voltage, pressure, or temperature, for which tolerances naturally take numerical form. Software is built from code, whose structures and behaviors owe more to discrete mathematics: types, sets, relations, graphs, states, and transitions. Its tolerances therefore often describe sets of acceptable realizations rather than intervals around a target value.

The realization space can also be extraordinarily large. A bridge must satisfy its functional obligations through a physical structure whose geometry, materials, loads, and environment tightly constrain what can work. Software is different. As Brooks put it, software is "pure thought-stuff," extraordinarily malleable rather than constrained primarily by the resistance of physical material.¹1. Frederick P. Brooks, “No Silver Bullet: Essence and Accidents of Software Engineering,” Computer 20, no. 4 (1987): 10–19. For many information-processing systems, the consequential obligations concern what information is accepted, produced, preserved, or exchanged, together with selected properties of how that processing occurs. Those obligations can leave enormous freedom in the realization itself. Programs with very different decomposition, control flow, data structures, algorithms, or internal architecture may nevertheless satisfy the same governing obligations.

This unusually large acceptable realization space makes degrees of freedom central to software engineering. Engineering need not choose one point in that space merely because it could. It can instead specify the properties that distinguish acceptable from unacceptable realizations and leave the remaining choices open. Commodity intelligence changes the economics of exercising that freedom: once realization becomes cheap, an autonomous reasoner can construct and revise implementations inside a space that would previously have been expensive for human engineers to explore. Modeling identifies the consequential distinctions; Alignment can give selected boundaries authority. The rest remains available to realization.

Figure 2.1-1 draws the relationship: obligations bound a region without selecting a point inside it.

Not every unmodeled choice is free

This distinction also separates a tacit obligation from a genuinely free choice. An unmodeled choice can look open even when engineers would reject some realizations of it. In that case the choice was never wholly free; some boundary on acceptable variation was already being applied in human judgment. What was missing was an explicit representation of the obligation or its tolerance. A genuinely free choice is different. Once the governing obligations are accounted for, engineering has no reason to distinguish among the remaining alternatives. A useful diagnostic follows: if a realization would provoke not that, some consequential boundary remains, whether or not anyone has written it down.

Unmodeled choices can therefore occupy several states. Sometimes engineering does not yet know whether or how the variation matters. Sometimes the obligation is tacit: people recognize unacceptable cases but the relevant boundary remains in judgment. Sometimes the obligation has become explicit enough for engineers, agents, or tools to reason about it. And sometimes the choice is deliberately free. These states can change as the system changes and as engineers learn from it. A region explored as free may expose recurring costs or interactions that reveal a previously tacit obligation; another may be modeled during investigation and turn out to contain no consequential distinction at all.

ENGINEERING

Inset — Uncertainty and unknown unknowns

Engineering distinguishes a choice deliberately left open from one whose consequences are not yet understood. The first is a degree of freedom. The second is uncertainty. In the harder case—sometimes called an unknown unknown—engineering has not yet recognized the consequential property, interaction, or failure well enough to ask the right question about it. An unmodeled region therefore should not be assumed to be free merely because no obligation has been stated.

A model cannot directly represent what engineering has not yet recognized. It can, however, make uncertainty more inspectable. By reducing a complicated system to selected entities, relations, states, quantities, or alternatives, a model can make variation and interaction easier to compare and trace. Unexpected behavior can then expose distinctions that were difficult to see in the realized system directly. A degree of freedom is known freedom; uncertainty is not.

This is one reason modeling can precede specification. Sometimes engineers construct a model because they know which property must hold. Sometimes they construct one to discover which properties matter.

That is why modeling can begin before specification is complete. Early in a design, variation may be the evidence from which the useful distinctions emerge. Several realizations may have to be tried before recurring failures, coordination costs, or invariants show which choices deserve a boundary. But a region can also become too complicated to explore directly from implementation before those obligations are settled. A purposeful reduction can then make the variation itself tractable: engineers can compare realizations, trace interactions, and name the regularities they discover. The trigger for modeling is therefore not only we know what must be true. Sometimes it is we need a representation to discover what must be true. Authority should follow that discovery selectively; representing a choice does not by itself create a reason to constrain it.

The question is the design input. Ask whether two workers can process the same job at once, and the color of the web interface falls away; you need who can own work, how ownership is acquired, when it expires, and what happens after a crash. Ask instead whether one service may bypass another, and the ownership details fall away; now you need components, communication edges, and the seams a call must pass through. The system did not change. The question did.

Hold the system constant. Change the engineering question. Watch the model change.

There is no single "model of the system," only reductions built to expose particular properties. A model earns its place by the question it settles, not by how much of the system it draws. What should I model, and what will the model let me know? — that is the question this Part asks of every system, and asks again at every turn.

The reduction comes first even when the representation is later made to run. Some models in this Part participate directly in execution or analysis: machines query them, derive artifacts from them, generate from them, or check properties over them. Executability changes what you can do with a model; it does not eliminate the abstraction that created it. That is why the examples ahead are drawn as reductions before their implementations are discussed: the abstraction should remain visible apart from its encoding.

2.1.2 Structure Makes Representations Machine-Operable

Externalizing knowledge saves reconstruction only if a machine can read it back. Machines can read externalized knowledge more reliably when its important entities and relations are structured — given a declared shape — rather than recoverable only from prose. Schemas, registries, graphs, and typed records expose entities and relations that tools can traverse, validate, and join reliably.

A common useful form is a graph of engineering entities and relations. Its nodes are engineering entities: services, modules, endpoints, queues, databases, requirements, tests, owners. Its edges name the relations: calls, depends on, deployed to, owned by, verified by. The graph need not live in a graph database; assemble it from YAML, registries, and schemas joined on stable identifiers and you have the same graph. The word graph names the structure, not the storage. Relevance then follows relationships: start at the entity a task names, and its neighbors come with it, so the agent reasons over a connected slice instead of a document dump.

Many of these representations can be interpreted as graphs of entities and relations. Their shape is not what distinguishes them; their semantics are. A knowledge graph exposes what exists and how facts relate. A representation becomes an engineering model when it is structured to answer an engineering question and carries the semantics or intent needed to reason about that question. Authority is a separate dimension: a sandbox can govern an action from a locally encoded conception of what is permitted, while a validator can use an explicit model to check an obligation neither the sandbox nor the raw artifact expresses.

Externalizing knowledge this way is the lightest form of Modeling, and much of current practice already stands on it. Spotify's public account describes a retrievable service catalog. Cloudflare's describes standards externalized under stable identifiers. Shopify's describes a different form, in which agent sessions are mined into reusable skills. DocAble assembles its graph from registries, schemas, and YAML joined on stable identifiers. Each makes selected engineering knowledge durable outside a single reasoning episode, allowing later agents to retrieve rather than reconstruct it.

2.1.3 Representations Support Accumulating Capabilities

Structured representations can support progressively different capabilities: externalized knowledge, typed relationships, explicit semantics, stated properties, derivation, generation, traceability, and checking. A representation may acquire additional capabilities as engineers ask more of it, but they are not a required sequence or a maturity model.

Authority is a separate dimension. A system may have strong permissions, sandboxes, compilers, or tests while representing little system-level intent explicitly. Conversely, a rich model may remain advisory. Add structure to the representation when the environment cannot answer a recurring engineering question cheaply and reliably with what it already exposes.

The practical rule is selective modeling. Model facts that are repeatedly reconstructed, and properties that are repeatedly adjudicated. A service catalogue may end repeated ownership discovery; an invariant may retire a recurring class of judgment. The cost is justified by the engineering question, not by a desire to climb a hierarchy.

Modeling does not create authority by itself, and authority does not require Modeling. Modeling expands the semantic surface over which authority can operate. Part III returns to that boundary.

One worked example makes the move concrete before the ontology names its classes. The same system yields different models as the question changes; the representation chosen determines which analyses become tractable, without prescribing the technique. The analysis produces evidence to interpret, and only afterward does engineering decide what deserves authority (Figure 2.1-2).

2.1.4 Six Classes of Engineering Question

MAGE uses six model classes as a working classification. The classes are organized by the engineering question a model helps answer, not by notation or implementation form. They are useful rather than exhaustive, and they can overlap: one represented object may participate in several classes.

The six classes (Figure 2.1-3) name the questions the rest of the Part is built around:

• Structural — what exists, and how the parts relate?
• Behavioral — what may happen, and in what order?
• Ownership — who controls what, and for how long?
• Decision — what is allowed, or which alternative should be selected?
• Measurement — how much, and against what envelope?
• Provenance — what happened, and what evidence records it?

These are views, not boxes. The in-flight lease we reach in the ownership chapter supports Ownership, Behavioral, and Measurement models at once. The classification tells us which question we are asking of it, not which drawer it lives in. A class suggests the questions to ask and the relationships worth preserving; it does not prescribe one notation, and a useful model may cross class boundaries.

System knowledge is not a seventh class. It is the connected substrate in which the six meet — where a service named in a structural model is the same service a decision model references, and a work item in an ownership model resolves to the measurements associated with it. The final chapter of the Part treats that substrate directly.

The classes expose different kinds of acceptable variation. A behavioral model can distinguish legal from illegal executions; a decision model can delimit a set of permitted alternatives; a measurement model can place a quantity against an envelope. Structural, ownership, and provenance models can likewise expose obligations that constrain some realizations while leaving others open. Tolerance names the permitted variation under an obligation; it is not a seventh class of model.

2.1.5 Purpose Comes First; Representation Follows

The class names a model's purpose. Its representation form — graph, registry, state machine, contract, table, quantitative relation — is a separate axis. A state machine is useful when states and legal transitions are the right reduction for the question at hand. Structured YAML does not become a model merely because it is structured.

Purpose comes first; representation follows. The engineering question determines what the model is for; several forms may be suitable for representing it, and one form — a registry, say — may serve structural, ownership, and measurement questions in turn. This keeps representation form subordinate to engineering purpose: the question selects the view, and the view keeps only the entities, relations, and properties that question needs. An agent planning a structural change need not carry every lock and user journey in its window. Represent shared facts once where practical; project or join the view the question requires.

2.1.6 The Six Model Classes

Each of the next six chapters takes one class through one production model from DocAble:

• Structural — the document-processing architecture and its sanctioned mutation seam.
• Behavioral — a recovery ordering whose most important fact is an edge that does not exist.
• Ownership — an in-flight lease with an owner, an epoch, and a lifetime.
• Decision — a service-flow model that declares which services may communicate.
• Measurement — a generation-cost model relating usage, capacity, and budget.
• Provenance — an attribution model that records actions and derives the explanations.

The final chapter steps back to the connected substrate — how a family of structured models joins on shared identity rather than collapsing into one universal graph.

A model does not govern the system merely by existing. Modeling makes an engineering property explicit; Alignment gives selected properties consequence. Part III begins at that boundary.