It sounds like a small change: add translation files and switch the strings shown on screen. Then you switch to English, and the return button disappears. The business logic was checking a Japanese display string.

In this fictional order-management system, an AI agent has handled much of the development. How do we make the internal state independent of the display language while preserving the business rules and the behavior of the existing API? What do we need permission to change, and what do we need to find out first?

Reviewing every line of AI-generated code is a substantial burden. I want us to be able to establish, on mathematical grounds, that the requirements we care about are preserved—without rereading the entire codebase.

Algebraic Architecture Theory (AAT) is the theory I am developing to study operations and the relationships they must satisfy as mathematical objects. This article introduces the Ariadne Boundary Repair Theorem and results about the observations needed to carry out a repair, starting with a small model we can calculate by hand.

Translate a status label, lose a return button

The first implementation displays the order's status directly. The Japanese string "発送済み" means “Shipped.”

const order = { status: "発送済み" };
statusElement.textContent = order.status;

A new requirement arrives: show the return button for shipped orders. This is a simplified business rule for our example.

The developer has been asking the AI agent to “keep the diff small and follow the existing patterns.” They check that each feature works on screen, but spend less time reading the generated code in detail.

The agent adds a condition that reuses the display string. The change takes only a few lines, and the button appears as expected.

const canReturn = order.status === "発送済み";
returnButton.hidden = !canReturn;

Later, the agent follows the same pattern in the return API's eligibility check and a batch job that selects orders eligible for return. Each change meets the requirement at the time. With attention focused on visible behavior, the growing dependence on Japanese text goes unnoticed.

Now multilingual support arrives. The code translates status before passing the order to the view, so the English view receives "Shipped".

const orderForView = { ...order, status: "Shipped" };

// The existing UI condition expects the Japanese string.
const canReturn = orderForView.status === "発送済み"; // false

Fixing the UI condition leaves the same assumption in the API and batch job. Changing the value at its source to English would affect those checks and existing API consumers.

A label intended for display has become a shared assumption across the system. Small changes that followed existing patterns carried that assumption further.

The design we want separates the internal status ID from its display text:

type StatusId = "pending" | "shipped";
type Order = { statusId: StatusId };

const labels = {
  ja: { pending: "未発送", shipped: "発送済み" },
  en: { pending: "Pending", shipped: "Shipped" },
};

function canReturn(order: Order): boolean {
  return order.statusId === "shipped";
}

function statusLabel(order: Order, locale: "ja" | "en"): string {
  return labels[locale][order.statusId];
}

// Preserve the representation expected by existing API consumers.
function toLegacyApi(order: Order): { status: string } {
  return { status: labels.ja[order.statusId] };
}

Internally, "shipped" is a stable identifier. Changing the English label to "Dispatched" no longer changes return eligibility. At the legacy API boundary, we convert the status back to the Japanese value that consumers expect.

Reaching this design requires coordinated changes to data creation, business checks, display logic, and API conversion. The available solutions depend on whether we may change only the UI or also the internal representation and the API conversion.

“Can we fix it?” depends on what we may change

There are three things to specify:

Only then does “Can we fix it?” become a precise question. The requirements may be achievable with one set of permitted changes and impossible with a narrower set.

The Ariadne Boundary Repair Theorem studies whether permitted changes can satisfy the required conditions while preserving a fixed part. Its central setting is a model in which corrections can be calculated linearly over a finite field.

We can explore the question behind our multilingual example using reversible operations on just three values. In this small model, we can write out every operation and calculate exactly what each correction does.

A three-value model of what needs to change

Arithmetic with 0, 1, and 2

Our values are 0, 1, and 2. After each calculation, we take the remainder modulo 3, so 2 + 1 = 0 and 1 - 2 = 2. This number system is the finite field F₃.

Imagine a location p holding one of these values. An operation changes the value at that location. Start with two operations: “add x” and “add y.” Writing the input as t, we have

$$r_x(t)=t+x,\qquad r_y(t)=t+y.$$

Both x and y belong to F₃. These two operations must stay fixed during repair. We will adjust other operations so that their combined results match them.

There are four operations available for adjustment:

The subscripts u, h, z, and v are the correction values we will choose. Initially, all four are 0. Each may be reset to 0, 1, or 2, subject to the permissions: if we cannot change b, then z stays 0; if we cannot change c, then v stays 0.

Repair adjusts the amounts added. The sign reversal in a_h stays in place.

Holonomy: a loop can change what comes back

Following a loop brings us back to the starting location, but it need not bring the state back unchanged. The transformation obtained by composing operations around a closed path is called holonomy.

Here, a_h is a single arrow that loops from p back to itself. With h = 0, it acts as a_0(t) = -t: 0 stays 0, while 1 and 2 swap places.

It also reverses the sign of a correction. If we add z before applying the operation, then

$$a_h(t+z)=-(t+z)+h=a_h(t)-z.$$

Adding z before the operation corresponds to subtracting z afterward. This propagation of a correction along an operation is called transport. Around this loop, the holonomy on corrections is multiplication by −1.

Top: returning to the same location swaps 1 and 2. Bottom: +1 before the operation corresponds to −1 afterward. All arithmetic is modulo 3.

Turn the required behavior into equations

We want two sequences of operations to match the fixed operations:

The first sequence adds z, then u, so it matches when u + z = x.

In the second sequence, focus on b_z between the two occurrences of a_h. Substitution gives

$$\begin{aligned} a_h\bigl(b_z(a_h(t))\bigr) &=-(-t+h+z)+h\cr &=t-z. \end{aligned}$$

The two occurrences of h cancel, and the effect of adding z changes sign. Adding v before this sequence and u after it gives t + u - z + v.

The two sequences match their targets for every input t exactly when

$$\boxed{u+z=x,\qquad u-z+v=y.}$$

We can now solve these equations under different change permissions.

Which permissions make repair possible?

If neither b nor c may change, then z = v = 0. The equations reduce to u = x and u = y. A repair exists exactly when x = y.

We may always change e and a, but h disappears from the equations, and u adds the same amount to both sides. Neither can make up a difference between x and y.

What if we allow changes to c? Keep z = 0, choose u = x, and set v = y - x. Both conditions are satisfied: the correction at c makes up the difference between the targets.

Allowing changes to b also works. Write the difference as d = y - x. Subtracting the equations gives d = z + v, because −2 equals 1 modulo 3. Even with c fixed and v = 0, we can repair by choosing z = d and u = x - d.

Each point is a pair (x, y). The target (0, 1) is unreachable with neither optional operation permitted, and reachable when b may change. There are no intermediate values between these points.

When x ≠ y, permitting just b, or just c, gives a set of permissions that cannot be reduced further while retaining a repair. Such a set is inclusion-minimal.

But permitting one additional operation does not mean only one operation will actually change. For example, take (x, y) = (0, 1) and choose the unrestricted value h = 0:

• Using b, we set u = 2 and z = 1, changing both e and b.

• Using c, we set v = 1, changing only c.

All other correction values are 0. A permission set that cannot be reduced further is different from a repair that changes the fewest operations or lines of code.

The same connections can require different repairs

For comparison, replace a_h(t) = -t + h with a_h(t) = t + h, which does not reverse the sign. Keep the same arrows and permissions. Transport on corrections changes from multiplication by −1 to multiplication by 1.

The two additions of h now accumulate instead of canceling. The difference between the targets becomes d = 2h + v, which we can match using h alone. As h ranges over 0, 1, and 2, 2h takes the values 0, 2, and 1, covering every possible difference.

In the original network, a nonzero difference required permission to change b or c. In this network, no additional permission is needed. By changing how corrections propagate, holonomy affects which operations we need permission to change.

Ariadne: combine local conditions to repair the whole

To extend this example to a larger network of operations, we need a way to combine the repair conditions for its parts.

In our example, one part could handle u + z = x while another handles u - z + v = y. Their shared values u and z must agree when we put the parts together. A correction that works for one part may be incompatible with the other.

Meanwhile, h does not appear in the shared equations, but we still need it to determine the actual operation a_h. Each part must retain both its shared conditions and the information needed to reconstruct its own operations.

The Ariadne Boundary Repair Theorem provides a way to build this information locally and combine it into repairs of the whole. Once constructed, it can answer, for each permitted change scope: Does a repair exist? What repairs are available? If none exists, what prevents one? The construction also takes us from numerical corrections back to the original operations.

The name comes from Ariadne in Greek mythology, who gave Theseus a thread so that he could find his way back out of the labyrinth. It reflects the idea of tracing a route to repair through a network of interdependent operations.

The difference that no permitted change can remove

What can serve as evidence that repair is impossible? With neither b nor c permitted to change, the only reachable right-hand sides are (u, u). Their components always differ by 0. The target (0, 1) has difference 1, so it cannot be reached. That difference proves impossibility without trying every correction.

Now group together pairs that can be transformed into one another by permitted corrections. For example, (0, 1), (1, 2), and (2, 0) are related by adding the same amount to both components. All have difference 1. The reachable pairs (0, 0), (1, 1), and (2, 2) form the group with difference 0.

A quotient space groups together values in this way, removing distinctions that permitted corrections can change and retaining those they cannot. Here, we can decide whether a repair exists by looking at the remaining difference y - x.

In larger finite, linear models, we similarly account for all changes that permitted corrections can produce and ask whether the target has a residual difference. When repair is impossible, we can extract a linear functional that detects a difference no permitted correction can eliminate. The same calculation that searches for a repair can therefore produce evidence of impossibility.

Ariadne connects this calculation with assembly from local parts and reconstruction of the original operations. Its mathematical foundations include relative cohomology, which handles the requirement to preserve a fixed part, and a construction that glues repairs together by making them agree on shared parts.

Knowing a repair exists is different from knowing the repair

So far, we have calculated repairs assuming we know x and y. What if we have not obtained those values yet?

Return to the original network, with a_h(t) = -t + h. The structure and equations are known, but the values of x and y are not. Only two observations are allowed:

$$r_x(0)=x,\qquad r_y(0)=y.$$

Evaluating either operation at 0 costs one query. Other computation does not count toward this cost. A numerical repair must return four concrete values (u, h, z, v).

Zero queries to say “yes,” two to say how

Suppose changes to c are permitted. We leave b unchanged, so z = 0.

A repair exists for every x, y. We can therefore answer “Is repair possible?” with “yes” without inspecting either value. That takes zero queries.

What about returning an actual repair? We can use

$$(u,h,z,v)=(x,0,0,y-x).$$

But this is still a formula containing unknown values. To return four specific numbers, we need to obtain both x and y.

Changes to c are permitted. Each observation narrows the possible inputs. All of them admit a repair, but they do not share a single numerical correction.

The illustration also shows why one query is insufficient. After learning x = 0, we still have three possible values for y. Each requires a different v, so we cannot choose a single number yet.

Choosing a different repair does not avoid this problem. Any complete correction tuple determines exactly one pair x, y through u + z = x and u - z + v = y. Querying y first leaves the same uncertainty about x.

Two queries suffice, and one does not. Under these observation rules, the optimal worst-case query count for returning a correct repair on every input is exactly two.

This measures the cost of evaluating the specified operations. It does not measure lines of code read or execution time. The information requirement also changes if we may return a program that calls the unknown operations later, rather than returning concrete values now.

Use what is already known

If at least one of b or c may change, the number of additional queries is:

We count additional observations. If another part of the system has already supplied a concrete value, we do not need to query it again. Knowing the form of an equation, however, does not mean we have obtained its values.

If neither optional operation may change, feasibility depends on x = y. With both values unknown, deciding feasibility and producing a numerical result each require two queries in the worst case. Here, the numerical result is either a concrete repair or an answer that repair is impossible.

Could the remaining uncertainty change the answer?

The repair–observation duality results extend this reasoning to more general models. The key is to consider which inputs remain possible after the observations.

For a yes-or-no answer, it is enough that all remaining inputs are repairable, or that all are impossible to repair. To return a concrete repair, a single correction must work for every remaining input. If all are impossible to repair, we can report that instead.

The theorems consider families of inputs with shared structure and correction transport, where the unknown values vary affinely. In our example, the operations keep the same form while the added values x and y vary. For finite-dimensional models over a finite field, with linear known information and permitted observations, the repair equations determine which input differences must be distinguished. When sufficient observations are available, we can choose a smallest set.

The resulting query count is optimal in the worst case, even among procedures that choose their next query based on earlier answers. The procedures considered are deterministic, terminate on every input, and always return a correct answer. The results also determine when the permitted observations cannot distinguish inputs well enough to produce the required answer.

What the model tells us

The calculations lead to three conclusions.

1. Once we specify what may change, we can find repairs or establish why none exists.

With neither optional operation permitted, a nonzero difference y - x proves that repair is impossible. Allowing changes to b or c gives us a way to make up that difference.

2. Connections alone do not determine what must change. The operations matter too.

With the sign-reversing loop, the correction h cancels. Without the sign reversal, that correction alone is enough. Holonomy affects the required change permissions.

3. Deciding that a repair exists can require less information than producing one.

In the original network, permitting either optional operation makes the feasibility decision possible with zero observations. A numerical correction still requires x and y: two additional queries if both are unknown, one if either is already known.

For networks satisfying their assumptions, Ariadne and the repair–observation duality results connect these questions through the same repair equations.

Where dependency analysis and program repair fit

Software engineering has a long history of studying the effects of change.

Weiser's program slicing focuses on a variable at a chosen point in a program and retains statements needed to preserve its value. Its treatment of data and control dependencies is relevant to tracing the checks that use our Japanese status string. Program Slicing, 1984.

Automated program repair also handles changes at multiple locations. Angelix, for example, derives repair constraints through symbolic execution and synthesizes patches across interdependent locations. Angelix: Scalable Multiline Program Patch Synthesis via Symbolic Analysis, 2016.

Rothenberg and Grumberg's Must Fault Localization for Program Repair studies sets of locations such that every repair must modify at least one location in the set. These sets depend on the chosen repair scheme and the changes it permits. The question “Can this be repaired while leaving this entire region untouched?” is already explicit in existing research. Must Fault Localization for Program Repair, 2020.

The AAT construction described here starts from local representations, obtains repairs and impossibility evidence for every permission scope, and provides a correspondence back to the original operations. It also derives the required observations from the same equations. Connecting this with existing techniques is a next research step: use dependency analysis to identify the relevant behavior, establish its correspondence with the model, and check the resulting code changes through repair tools and testing.

The multilingual refactoring workflow I want ArchSig to support

Return to the order-management system. Ariadne, the repair–observation duality results, and the small model in this article have been proved in the research Lean formalization. Using them in development requires a way to map real code to models satisfying the theorems' assumptions and translate the resulting corrections back into code changes.

Verifying the correspondence between code and model, implementing the results in ArchSig, and evaluating them in practice are work ahead. The workflow I want to build would look like this.

1. Tell the agent what must be preserved.

“I want to add multilingual support to the site. Internal order states should be independent of the display language. Return eligibility and the values returned by the existing API must stay the same.” Start by giving your usual AI agent the goal and the constraints.

2. Have the agent trace where the status is used.

The agent follows order creation, return-button visibility, the return API's eligibility checks, and the batch job's selection criteria. It records which operations expect "発送済み", together with their source locations. ArchSig receives both these facts about the implementation and the requirements to preserve.

3. Compare repairs under different change permissions.

ArchSig analyzes the model under progressively broader permissions: from UI-only changes to changes in the internal state representation and business checks, with a conversion at the legacy API boundary. For scopes that cannot satisfy the conditions, it identifies the obstruction. For those that can, it provides concrete repair options. You use that evidence to decide how far the change should extend.

4. Obtain the missing information needed to decide or implement the repair.

For example, building the compatibility conversion may require a complete list of status values in existing API responses. ArchSig identifies the information required by the model, and the agent checks the corresponding code or specifications. Information already obtained is reused.

5. Change the code and verify the preserved behavior.

Following the chosen repair, the agent moves internal checks to status IDs, translates labels for display, and converts back to legacy values at the API boundary. It updates the model from the changed code and reruns the analysis. Tests also check that the return button appears under the same conditions in Japanese and English, and that existing API responses remain unchanged.

Runtime concerns such as races, I/O behavior, and performance are checked with appropriate methods, including end-to-end and load tests.

A request that initially looked like a UI change can then be evaluated as a refactoring that spans business logic and API behavior. The developer uses the evidence to choose the change scope, and the agent implements and checks the change within those conditions.

In my AAT research, “Rising Sea” names the direction of connecting descriptions of operations, repairs, and required observations within one mathematical construction. These results let us move from “What must change to make this work?” to “What must we know to make that change?”

By verifying the correspondence between code and model and integrating this approach into development, I want to make it possible to refactor with checkable evidence that the requirements we care about are preserved, without having to reread every line of code. A request as ordinary as “add multilingual support” should come with a reasoned account of what to change and what to verify. That is the development workflow I want ArchSig to support.

The mathematical definitions and Lean formalizations are available in the AAT repository, including the accounts of relative boundary repair and repair–observation duality and their proofs.

We divide design work across teams, implement features, and migrate systems that are already running. Throughout that work, we need to make judgments: Will this update break another feature's assumptions? Will the same operations still work after the data migration? Will the designs for these services fit together? As AI accelerates development, we need clearer accounts of what must stay intact, what may change, and why we can trust the system to remain consistent.

Algebraic Architecture Theory (AAT) is the theory I am developing to make these questions mathematical. It provides a way to state what must be preserved and describe, in a form that can be checked, how parts fit together and how structures relate before and after a change.

I have published a paper laying out its foundations:

Foundations of Algebraic Architecture Theory: A Rising Sea of Geometry, Transport, Comparison, and Reconstruction

The paper runs to 285 pages. AAT is a new theory I am building, so presenting individual results also requires establishing the objects they concern and the definitions and assumptions behind them. I chose to develop the foundations and the main theorems together as a coherent whole.

I also wanted a mathematical reference for future papers: a place to look up definitions, theorems, and proofs, rather than rebuilding the foundations every time I address a particular problem or application.

Five questions that recur in software development

Change a data representation. Extract shared functionality. Split a system into services. Across different technologies and projects, the same questions return: What survives the change, and how do the parts remain consistent? The paper organizes these concerns around five questions.

1. Can individually correct parts form a consistent whole?

Each part may satisfy its own requirements while disagreeing with another part about shared data or assumptions. What conditions and corrections would let us assemble a whole? (Chapter 2)

2. Can a summary reveal the same inconsistencies?

When we summarize a complex system or examine it at a different level of detail, which information and relationships must remain for the diagnosis to stay the same? (Chapter 3)

3. Can different migration paths and task orders preserve the same behavior?

We might migrate in one step or in stages. We might select the relevant design documents before transporting a model, or transport it first and then select the corresponding documents. When do these routes preserve the operations and conditions we care about? (Chapters 4–5)

4. If changes look the same, can we tell which ones preserve the required behavior?

Two changes may produce the same visible output but behave differently when we perform an operation. What would we need to enumerate every candidate that preserves the required behavior? And when can we judge a candidate from visible output alone? (Chapters 6–7)

5. Can separate teams' designs determine the overall design and migration?

When teams divide up the work, what must each team specify, and what must agree where their responsibilities meet? Can their specifications determine a unique migration of the whole system? (Chapter 8)

A running example: migrating an e-commerce system

Consider an e-commerce system with three services:

All three services refer to the same order by its ID. Canceling a paid order requires an order status change, a refund, and the release of its inventory reservation.

Take order 42: it ships to the customer's home, costs $12.33, has been paid for, and has inventory reserved. As the teams revise their data formats and divide up the processing differently, we still need to be able to change its shipping address and cancel it with the appropriate refund and reservation release. We will follow this order through the article.

Chapter 1: Decide what to preserve, then build the model

Do we only need to preserve the displayed shipping address? Or must we also preserve how address updates behave and how they interact with payment information? We cannot judge a change until we decide. AAT starts by making the model's contents, operations, and required conditions explicit.

For our example, we include a state containing a shipping address and payment information, an operation that reads the address, and an operation that updates it.

AAT calls a typed basic fact—such as the existence of a component or a named operation—an Atom. Here are some Atoms we could describe:

We also specify how those operations must behave. A requirement expressed as an equation is called a Law.

Let s be an order state and a a shipping address. Then read(s) is the current address, and update(s, a) is the state after setting the address to a.

Reading the address after an update should return the address we just supplied:

$$\operatorname{read}(\operatorname{update}(s, a)) = a$$

If we change an order from a home address to a work address, reading it should return the work address. This is the familiar expectation that a getter returns the value supplied to a setter.

We can also require that writing back the current address leaves the order unchanged:

$$\operatorname{update}(s, \operatorname{read}(s)) = s$$

The right-hand side is the entire order state, not just the address. An operation that changes payment information when we set an already home-bound order to “home” again would violate this Law. These equations must hold for every order state s and every address a to which they apply.

Expressing the structure and conditions we want to analyze through Atoms and Laws makes the analysis independent of a particular programming language or framework. Different implementations can be described in a common language: which components and operations exist, and what they must satisfy.

From software requirements to geometry

Let x be the refund expected by the order service and y the refund recorded by the payment service. The requirement that they agree is x - y = 0. The pairs (x, y) satisfying that equation form a line in the plane. We have moved from checking one order to studying the space of states the requirement permits.

The idea extends to more values and more conditions: represent states with variables, express requirements as equations, and study their solutions. This is the entry point from software descriptions to algebraic geometry. AAT makes explicit both this interpretation and how operations act on states.

No single service holds the entire state of our e-commerce system. Orders holds cancellation status and the expected refund; Payments holds the refund amount; Inventory holds the reservation status. We treat these as parts, linked through shared order IDs and amounts. Now we can ask: Is there a state that satisfies all their conditions at once? Studying solutions lets us move from checking individual orders to asking whether the requirements themselves can coexist.

Chapter 1 establishes the foundations for moving from facts to models equipped with operations, Laws, and relationships between parts. Later chapters use that geometry to study consistency and migrations.

Chapter 2: Can the records fit together?

Suppose an order cancellation triggers a refund. What happens if the order service and the payment service handle the amount differently?

For this example, a cancellation refunds 80% of the purchase price. For order 42:

12.33 × 0.8 = 9.864 dollars

The actual payment must be rounded to cents. But suppose the revised processes follow these rules:

Both processes follow their own rules, yet they disagree by $0.004 about the same refund. The discrepancy is a rounding difference smaller than one cent.

What changes would reconcile them?

The last approach retains the difference but accounts for it. Whether reconciliation is possible depends on which repairs we allow.

Shared information about orders and amounts forms an overlap between processes. Combining partial data according to the agreed relationships on those overlaps is what mathematics calls gluing. A sheaf captures the relationship between reading parts of a whole and uniquely assembling a whole from compatible partial data.

Each pair can be reconciled, but all three cannot

Now apply the second repair: Payments also uses the rounded amount, $9.86. Orders and Payments agree. Then introduce a reconciliation ledger on the payment side, so that we compare the cancellation record, the refund record, and the ledger.

Assign one adjustment to each record. Every comparison involving that record must use the same adjustment.

Suppose two comparisons use rounded amounts, while the third requires the ledger to account for the difference from the unrounded amount. They impose the following requirements:

Any one requirement can be satisfied on its own. But adding the first two gives “Ledger adjustment − Orders adjustment = 0,” contradicting the third. We can choose adjustments for each pair separately, but no single choice satisfies all three pairs.

Follow the comparisons around the loop: Orders → Payments → Ledger → Orders. The last step traverses the Orders–Ledger comparison backward, so we subtract its required difference. The total is 0 + 0 − 0.004 = −0.004 dollars. Changing the adjustment at any record cannot change this total: its contributions cancel around the loop.

Examples 2.19 and 2.27 in the paper study this kind of residual around a loop. In this model, adjustments may take any value, and the comparison data consists of the three pairs in the table. We do not add a separate three-way comparison.

Cohomology treats differences removable by the allowed adjustments as equivalent, and records what remains. Here, the loop total is an obstruction that those adjustments cannot remove. If we revise the third comparison to use the rounded amount as well, the loop total becomes zero, and setting every adjustment to zero works. That repair changes a reconciliation rule; it does more than choose new adjustments under the existing rules.

Chapter 2 states conditions connecting such an obstruction to the existence of a whole. For example, adjusting an order record and then reading its shared refund amount must give the same result as applying that adjustment directly to the shared amount. When adjustments are compatible with reading partial data in this way, and states form a sheaf, the following are equivalent (Theorem 2.22):

• The obstruction is zero.

• The local states can be adjusted in the allowed ways and glued into a global state.

A nonzero obstruction means there is no such global state within the fixed model and allowed adjustments. When corrections are possible, the corrected partial data determines a unique whole. The choice of corrections itself need not be unique.

Chapter 3: Can a summary preserve the diagnosis?

Suppose we summarize service records to review a change to cancellation processing. Omitting a full street address and rounding a refund amount have different consequences. Displaying both refund values for order 42 as “$9.86” would hide the discrepancy we started with. Which information must survive the summary?

Preserving Law values is not yet preserving the diagnosis

Chapter 3 begins by fixing the Laws we want to examine and their evaluation values—for example, the difference between the two sides of an equation. Put states in the same group exactly when all the selected Laws evaluate to the same values. Keep states with different values in separate groups. This retains precisely the distinctions needed to preserve those evaluations (Theorem 3.4).

But evaluating a Law within each part and diagnosing disagreement between parts are different tasks. Keeping 9.86 and 9.864 is not enough if we accidentally compare amounts from different orders. We also need to know that these are the expected and recorded refunds for order 42.

The paper therefore gives conditions relating which records we read, which pairs we compare, and how we calculate differences before and after summarization. In the three-record example, this includes the comparison loop and the treatment of adjustments, as well as the values in the records. Under these conditions, the diagnoses correspond one-to-one, and one is zero exactly when the other is (Theorem 3.17). Summarizing neither hides an existing obstruction nor invents a new one.

When the necessary values and comparison relationships can be enumerated and computed as finite data, the preservation condition can itself be decided by a finite computation. This concerns Laws evaluable from both summaries: the criterion determines whether diagnosis is preserved for every finite selection of those Laws (Theorem 3.22 and Proposition 3.23).

For code review in the age of AI, this suggests a concrete research question: What must a reviewer retain to reduce the reading burden without overlooking inconsistencies? Turning the mathematical preservation conditions into practical review methods remains future work.

Chapters 4–5: Comparing migration paths and task order

Next, change the order data format. The old version stores the address in a top-level shipping_address field. The new version groups shipping information in a shipping object, with the address in shipping.address. An intermediate version that merely renamed the field to shippingAddress is already in use.

We can migrate directly, or chain existing migrations through the intermediate version:

Order 42 should retain the same address along either route. Address updates must also move to the new field, and must continue to leave payment information unchanged.

The rest of the migration is not a free choice

Chapter 4 constructs transport: a way to carry operations, Laws, and relationships between parts together along a change that satisfies conditions including a one-to-one correspondence between extracted Atoms.

Fix the overall migration from old to new, and fix the underlying schema mappings from old to intermediate to new. Transport the old structure to the intermediate version. Then there is exactly one migration from that transported model to the new model that realizes the overall migration we specified (Theorems 4.5 and 4.11).

Adding an intermediate version seems as though it should introduce more choices. But when we construct it by this transport, there is no further choice of a continuation compatible with the overall migration. The factorization preserves the modeled update operations and Laws, not just the location of the address field. The uniqueness concerns the migration between mathematical models; it does not mean there is only one way to write the implementing program.

We can also compare a model transported directly to shipping.address with one transported through shippingAddress. The paper constructs a correspondence that lets us move between the two while preserving operations and Laws. Adding more intermediate versions does not introduce ambiguity: comparing one stage at a time or grouping stages together produces the same final correspondence (Theorem 4.15).

Independently specified migrations can still disagree. If one swaps the shipping and billing addresses, the route changes the resulting address. For a finite collection of paths, the paper shows that the transformations can be reselected to satisfy all the specified comparisons exactly when the obstruction to their agreement vanishes (Theorem 4.23).

Combining documents need not lose the structure they describe

Now choose which design documents to review. Suppose the old web and mobile app cancellation specifications both map to a shared cancellation specification in the new design.

Once two documents map to one, the new document's name cannot tell us whether we started from the web or app specification. Must the model derived from those documents also become impossible to recover?

Suppose both cancellation specifications yield the same Atoms and are equipped with the same operations and Laws. Losing the distinction between their origins need not lose those structures. The paper shows that even when the mapping of source documents is not invertible, models built from a selected document can still be related by a reversible, structure-preserving correspondence (Proposition 5.8 and Example 5.9). What we recover is the structure of types, operations, and Laws, rather than the history of the documents.

If we select the shared cancellation specification in the new version, we must therefore pick up both the web and app specifications on the old side. Picking only one would give us a mismatched scope.

A model is built by reading types, operations, and Laws from the documents. Chapter 5 constructs pairs of corresponding sources and gives a way to read model structure over the selected sources.

It compares two routes:

• Select the old web and app cancellation specifications, then transport the model built from them to the new version.

• Transport the old structure to the new version, then read the structure over the shared cancellation specification.

Under the specified conditions on source mappings, extracted Atoms, operations, and Laws, these routes yield models connected by a reversible, structure-preserving correspondence (Theorem 5.11). Separating how documents are consolidated from which model structure is preserved lets us explain why different task orders can still retain the same operations and Laws.

Chapters 6–7: What remains after we leave information out?

The remaining structure can still correspond

So far, we have transported structure while preserving it. Now, to focus on addresses and their updates, set every payment code in the comparison data to “unset.” We can still read and update addresses, but we cannot recover whether the payment code was originally 1 or 2.

Running this process twice has the same effect as running it once. That property is called idempotence. The paper uses normalization for a process that puts objects into a standard form while preserving the required structure. This is a different use of the word from database normalization.

For order 42, set payment information to “unset” and match the old shipping_address with the new shipping.address. Changing the old address to work corresponds to changing the new address to work. The payment information cannot be recovered, but the address and its update behavior can still be related in both directions.

Chapter 6 constructs an idempotent normalization of the full structure under conditions that preserve operations, Law evaluation values, and other required data (Theorem 6.14). The comparison studied here can be understood as a composition of transporting structure and then normalizing it to leave information out.

The interesting result is that losing information irreversibly can still leave a reversible correspondence between the structures that remain (Theorem 6.12). Starting from an invertible correspondence, define the normalizations so that both sides retain matching structure. The remaining parts are then isomorphic: we can move between them in both directions while preserving structure.

By contrast, the comparison constructed here is invertible on the original full structures if and only if normalization changes nothing (Theorem 6.16). The distinction makes explicit how much of the original structure the comparison preserves.

The same display does not imply the same update behavior

Chapter 7 returns to migrations of the complete order. Even if addresses and updates correspond after excluding payment information from the comparison, the migration of the full order may still be unsuitable.

Write the addresses as “home” and “work,” and focus on the internal payment code. In both the old and new systems, editing the address leaves payment information unchanged. But suppose the migration converts payment codes differently depending on the address:

Start from the same order: home, payment code 1. Now compare when we change the address to work.

1. Migrate, then update. The home order migrates with code 1. Updating only its address leaves us with work, code 1.

2. Update, then migrate. We first change the old order's address to work. It then migrates as a work order, giving work, code 2.

The displayed address agrees, but the payment information does not. What we want is the same order state whether we migrate before or after the update.

Four candidates become two

Restrict addresses to home and work, and payment codes to 0, 1, and 2. Keep 0 fixed as the “unset” value used in Chapter 6. For codes 1 and 2, either keep them as they are or swap them. The mapping between old and new codes is itself a design choice.

All four preserve the displayed address and the unset value. Only A and D preserve updates. Because an update can take us between home and work, both must use the same code mapping. D is valid because it relabels the codes consistently. If code 1 must literally remain code 1, we must state that as an additional requirement.

Chapter 7 generalizes this for systems whose operations preserve internal state. With the visible state fixed and internal states relabeled bijectively, view visible states as vertices and operation-induced connections as edges. Each connected component must use one consistent relabeling; different components can choose independently. These choices describe all changes of this kind that preserve the operations (Theorem 7.24). In the finite case, we can also count them. The four-candidate example is based on Example 7.28 in the paper.

Judging a candidate and constructing one are different tasks

The display cannot distinguish A from B. Add “swap codes 1 and 2 only for work orders” to A, and we get B. The displayed address stays the same, but preservation of updates is lost.

More generally, if an invisible modification can change whether a candidate is acceptable, observation alone cannot decide the question. The paper proves a necessary and sufficient condition: adding changes invisible to the observation must leave acceptability unchanged (Theorem 7.9).

To construct an acceptable candidate, however, we can start with A. Add “swap codes 1 and 2 for both home and work,” and we get D. An invisible modification that preserves updates gives us another acceptable candidate.

The paper provides a way to start with a migration of normalized models and supply mappings for the information that was left out. Here, that means adding a payment-code mapping to an address-only migration to obtain a migration of the complete order. It constructs one migration satisfying the requirements and describes all the other candidates from there (Theorems 7.19 and 7.21).

This requires the original models to be related by an invertible, structure-preserving comparison. It also requires the normalization—which determines what is retained and what is hidden—and its associated data to admit a common representation on both sides.

Constructing an acceptable candidate with this information is a different problem from judging a supplied candidate by its display alone.

Chapter 8: Building the whole from separate teams' designs

Finally, divide the design and migration work among three teams.

Agreeing on order IDs is not enough. Adopt the Law that a cancellation is complete only when the required refund has been made and the inventory reservation released. All three teams might map order 42 to the same new order, yet map its states to “cancellation complete,” “refunded,” and “still reserved.” That migration would not preserve the Law.

Operations need to correspond too. Releasing a reservation in the old system and then migrating must agree with migrating first and performing the corresponding release in the new system. Each team specifies its types, values, operations, and Laws, together with how shared information is mapped.

The paper's main result, the local reconstruction theorem, shows that we can assemble the whole from descriptions of its parts without assuming a completed whole in advance. Give the parts' descriptions separately, and check their compatibility on shared data, operations, Laws, and the other required structure. Two results follow.

First, the whole structure can be recovered up to isomorphism. Names or representations may differ, but the objects, operations, and other structure correspond in both directions.

Second, once the old and new structures are fixed, compatible local migrations determine a unique structure-preserving migration of the whole. With the required descriptions in place, there is no room for two different global migrations that look identical on every specified part.

Chapter 2 asked whether amounts and their comparison rules fit together into a consistent whole. Here, the things we assemble include data types, operations, and the migration itself.

This conclusion requires a complete description of the model's data: types, values, operations, Laws, which values are read from which parts, and the rest of the specified structure. The descriptions must agree where they overlap. The main result is Theorem 8.18; Section 8.6 applies it to design work divided among teams.

Returning to the five questions

What answers did we get by following the e-commerce example?

1. Can individually correct parts form a consistent whole?

Following each process's own rules did not make order 42's refund records agree. Under the theorem's conditions, the existence of allowed corrections that reconcile the whole is equivalent to the gluing obstruction being zero.

2. Can a summary reveal the same inconsistencies?

Rounding away digits can hide a refund discrepancy. Losing the link to the order can lose the comparison partner. The paper provides conditions for preserving diagnosis across changes in values and relationships, along with a decision criterion for the finite setting.

3. Can different migration paths and task orders preserve the same behavior?

We compared direct and staged migrations, and selecting cancellation specifications before or after transport. Under the conditions that preserve structure and the mappings between sources, these routes can be compared coherently. Disagreements among specified paths can also be studied as obstructions.

4. If changes look the same, can we tell which ones preserve the required behavior?

The address display could not distinguish the four payment-code mappings. Examining updates reduced them to two. The paper separates classification and construction of acceptable changes from the conditions for judging them by observation.

5. Can separate teams' designs determine the overall design and migration?

Orders, Payments, and Inventory supplied types, operations, shared order references, and completion conditions. With all the required design data and compatibility conditions, the whole structure is recoverable up to isomorphism, and a migration between fixed old and new structures is uniquely determined.

Beyond the Rising Sea

The title Rising Sea expresses an approach: develop a common theory broad enough to bring individual problems within reach. This paper establishes foundations for studying consistency, migration comparisons, and reconstruction within the same mathematics.

The next step is research on extracting structures and Laws from real code and specifications, working at the scale of software development, and testing whether this helps engineering judgment in practice. As AI produces changes faster, I want to give us stronger grounds for taking responsibility for them.

What does this change preserve—and how can we establish that?

Finding your way through the paper

The paper's arXiv page provides PDF and HTML versions. Chapter numbers in this article refer to the paper; Chapters 4–5 and 6–7 are grouped here. The theorem references lead to the precise assumptions and proofs.

The four address-update candidates appear in Example 7.28 in Section 7.8. The application of reconstruction to designs developed by separate teams is in Section 8.6. Appendices A and B document the correspondence with Lean declarations and the verification procedures.

“Move email delivery to a shared asynchronous queue.”

The request fits in a sentence. The understanding needed to carry it out is scattered across more than 200,000 lines of code.

The sending function is easy to find. Follow its callers, though, and authentication codes and newsletters turn out to use the same implementation. One has expiration rules; the other has unsubscribe requirements. Queue delays and retries affect the conditions under which each feature works.

In an environment where the entire codebase cannot fit into context at once, an AI agent alternates between searching and reading. It cross-checks authentication flows, delivery settings, tests, and design documents to reconstruct dependencies and assumptions. Before it can judge the change, it uses a substantial number of tokens to recover meaning distributed across the code.

How much of that understanding will survive into the next task? Unless the relationships and the reasoning behind its decisions are retained in a reusable form, another session will repeat much of the investigation.

I want the understanding gained from reading code to persist as a structure that people and AI can share and use for the next change. Ontologies offer a starting point by making concepts and relationships explicit. I am developing a vision for a semantic layer that also captures meaning in context, supports consistency analysis, and lets us reason about what changes preserve.

The foundation for this work is AAT, Algebraic Architecture Theory, a theory I originated and continue to develop through mathematical research and software tools. AAT approaches architectural meaning through geometry. I want to turn that foundation into a way to understand a codebase and reason about how it can change while preserving what matters.

The Same Email Function Can Mean Different Things

Consider this function:

sendEmail(to, subject, body)

It sends a subject and a body to a recipient. Its role in the system emerges from its relationship to the code that calls it.

Put authentication emails in the same queue as a bulk mailing, and they may wait behind thousands of messages. Delivery can succeed while authentication fails because the code has already expired.

For newsletters, a subscriber may unsubscribe after a message enters the queue. Consent when the audience was selected and consent when the message is sent are distinct states. The system needs an explicit rule about which state governs delivery.

To assess the change, we need more than a label identifying each use. We need the relationships between the authentication request, code generation, delivery, and verification, as well as the point at which subscription status is checked.

The meaning of sending an email lies in its relationships with other operations and the requirements of its use.

By a semantic layer, I mean a layer through which we can access components, relationships, contexts, and the laws they must satisfy, together with references to their sources. An AI agent would retrieve the information relevant to a task, then follow those references to the original code wherever implementation details are needed.

AAT: Toward a Geometry of Meaning

I am building AAT as a theory of pure mathematics, starting from Atoms and Laws. An Atom is a basic unit of architectural fact. A Law is an equation over a family of Atoms. To apply the theory to code, we express observed facts in this vocabulary and choose laws for the properties we want to examine.

In the email example, we might record that authentication requests code delivery, or that delivery uses a queue, along with the context and source of each fact. We then specify the conditions we want to examine, such as those governing expiration and delivery times.

The perspective I take in AAT is that software architecture is a large system of simultaneous equations. The laws within each part and the conditions connecting those parts must hold together. A solution describes a consistent configuration under the selected laws.

The solutions to a system of equations form a space. Algebraic geometry studies such spaces. We can ask whether a configuration satisfying the conditions exists, whether configurations built separately can form a coherent whole, and what becomes possible when the conditions change. My aim with AAT is to treat architectural consistency and change as questions about this geometry.

Authentication, delivery, and subscription management can each have configurations that satisfy their own conditions. To form a working system, they must also agree where they meet, for example on which authentication code is being delivered and when delivery takes place.

In mathematics, assembling local configurations into a whole on the basis of agreement on their overlaps is called gluing. In this framework, we study failures of global consistency as obstructions to gluing, and changes in configuration as problems of deformation.

I call this research program Semantic Geometry of Architecture. It studies the space of consistent realizations of meaning: their existence, obstructions, deformations, and relationships across different ways of reading an architecture.

Once our understanding of an implementation connects to such mathematical objects, we can move from asking what is present to asking what is consistent and how it can change. That is the scope I want the semantic layer to support.

The Atlas Theorem: Choosing How Much Detail to Read

To use this layer across a 200,000-line codebase, we must choose both the scope and the level of detail appropriate to the question. For asynchronous email delivery, expiration and retry rules deserve early attention. Does every styling detail in the HTML template need the same scrutiny?

Yet omitting the logic that inserts the authentication code into the message could discard something essential. What we can leave out depends on what we need to establish. AAT treats this choice mathematically.

We begin by grouping together things that the selected laws cannot distinguish. AAT provides a construction of a canonical reading that preserves the evaluations of those laws. In an expiration analysis, for example, the idea is to retain the information needed to evaluate the relevant conditions.

We then ask whether preserving information within each part also preserves the diagnosis of the whole. This is the question addressed by the Atlas Theorem.

Atlas Theorem: A change in resolution preserves diagnostics when the required conditions hold.

If both the finer and coarser readings retain enough information for the selected laws, and their comparison satisfies the specified conditions, their diagnostic classes in first cohomology correspond one to one.

Here, first cohomology is a mathematical tool for studying discrepancies that satisfy specified consistency conditions and identifying the obstructions that remain after local adjustments. A one-to-one correspondence of classes means that, under the theorem's conditions, a coarser reading neither loses diagnostics nor introduces new ones. The parts, their overlaps, and the data on those overlaps must all be appropriately related.

Applied to code comprehension, this would let us say, with mathematical justification: “For this property, reading at this resolution preserves the diagnosis.” Once a model extracted from the code is shown to satisfy the Atlas Theorem's conditions, omitting detail preserves the diagnostics associated with the selected laws.

An AI agent could use that guarantee to choose a reading resolution, then inspect finer detail when it needs to investigate another property or edit the implementation. Reliable model extraction and a way to select laws appropriate to the question are the tools needed to make this workflow possible.

The SAGA Theorem: A First Realization of Semantic Geometry

Once we know what to read, we need to determine whether the requirements we find can hold together.

Suppose an authentication code expires five minutes after issuance, but the shared queue can take ten minutes to deliver it. The authentication service rejects expired codes, and the delivery service sends the message. Both follow their own rules, yet the user cannot complete authentication.

An engineer can approach this problem from two directions. One is to consider changes that restore consistency, such as separating the authentication email queue. The other is to express the required relationships as equations, such as those relating expiration and delivery times.

The SAGA Theorem establishes a mathematical correspondence between two independently constructed ways of describing obstructions, one based on each perspective.

On the semantic side, the construction starts from the repairs allowed within each part and the ways those repairs combine. On the geometric side, it starts from the law equations and the algebra describing their obstructions. Because the constructions have different starting points, their agreement requires proof.

SAGA Theorem: Semantic and geometric accounts of obstruction correspond.

Choose finitely many parts covering the subject of analysis. When their local data satisfy the required correspondence and consistency conditions, the cohomology constructed from semantic repairs is isomorphic to the cohomology constructed from the equations and obstruction algebra. The obstruction classes correspond as well.

An isomorphism here allows us to move between the two descriptions while preserving the mathematical structure used to study obstructions.

The power of the SAGA Theorem is that we can take a semantic question about what prevents local repairs from fitting into a consistent whole and bring it into algebraic and geometric computation. For a model satisfying the theorem's conditions, the correspondence between the computed obstruction and the semantic obstruction is mathematically guaranteed. People and AI can use that result as evidence when evaluating repair proposals.

For the email system, I want to model the allowed repairs and the data shared between operations, then connect the problem of making authentication and delivery consistent to this analysis. The SAGA Theorem connects reasoning about meaning with geometric computation. It is the first realization of the Semantic Geometry of Architecture program.

Annapurna: Preserving Relationships Through Change

Moving to asynchronous delivery may involve a dedicated authentication queue, invalidating old codes when a new one is sent, or checking subscription status immediately before delivery. The change extends beyond the sending function into relationships between operations.

Identical “delivery succeeded” records before and after a change do not establish that authentication and subscription requirements have been preserved. We need to know whether the recorded information captures the property we want to compare.

In the research series I call Annapurna, I have studied how comparisons can be carried through changes in viewpoint and structure. Its later results include the following.

Annapurna results: Classify changes that preserve a comparison, and establish distinctions that observation alone cannot detect.

Within the specified structures, we can classify which changes to the two objects preserve their comparison. This classification carries over when the presentation of the inputs changes. There are also examples in which two changes produce identical observations through specified coefficients, yet only one is compatible with the comparison.

In the latter case, processing the observed values afterward cannot recover the distinction. The information needed for that decision is absent from those values.

The email delivery log is an illustration of the problem these results address. To assess a change, we need records that let us compare structural relationships as well as outcomes.

I want to use the Annapurna results to examine a practical question mathematically: “If we change one side, how must we change the other to preserve their relationship?” Classifying the changes compatible with a comparison provides a mathematical basis for that analysis within the specified structures.

For asynchronous email, the application would be to ask how code issuance and resend rules should change alongside the delivery mechanism. What does the proposed modification preserve, and which changes must be made together to preserve it? To support that analysis, the semantic layer would record how operations correspond before and after the change, which requirements must carry over, and the information needed to check the theorem's applicability.

The Major Theorem Ahead: Representing Meaning Geometrically

The results so far answer particular questions within semantic geometry. Beyond them, I am working toward a major theorem that represents realizations of meaning as a geometric object.

A realization of meaning is a consistent configuration for the chosen Atoms and laws. In the email example, this would be a configuration in which authentication, delivery, and subscription management satisfy their local conditions and agree where they interact.

The goal is first to define these realizations independently, then show that they are naturally described by maps into a geometric object. This property is called representability. It would let us study questions about configurations satisfying the conditions as properties of the corresponding space.

Proving this major theorem remains a research goal. I want it to connect engineering questions to geometric ones:

Computing actual repair proposals will also require algorithms that work with finite inputs. I want to pursue both the theorem and the implementation work needed to turn its consequences into computations, so that refactoring and repair can be treated as geometric problems.

The Workflow I Want to Build with ArchMap, ArchView, and ArchSig

I am developing ArchMap to record observed structure, ArchView to visualize it, and ArchSig to analyze it under selected laws. LawPolicy specifies the laws, which are combined with the observations for computation. Here is the future workflow I want to build on that foundation.

Return to the 200,000-line codebase and the original request:

“Move email delivery to a shared asynchronous queue.”

The AI first queries ArchMap for the contexts in which email delivery is used. It retrieves the operations involved in authentication and newsletters, their requirements, and their source references, together with the shared data and relationships needed for the decision.

In ArchView, a person examines the same structure. They follow code issuance through delivery and verification, checking which operations the AI selected for modification and why. Eventually, linking changes in the level of visual detail to mathematical reading resolutions could make it clear which information each view preserves.

ArchSig analyzes the selected scope under the selected laws. I want to extend it to check the conditions for comparisons across resolutions and to handle structural correspondences before and after a change. The results and supporting evidence would serve both the AI's explanation and human review.

With that information, the AI reads the implementation details it needs: code issuance, queue submission, resend handling. After making the change, it updates the relevant observations and repeats the diagnosis and comparison for the same objective.

The semantic structure used to reach the decision remains available to the person reviewing it and to the AI in the next session.

Putting the Geometry of Meaning in the Hands of People Who Build Software

What I want to create with AAT is a development environment in which people and AI share an understanding of software's meaning and explore the changes that understanding makes possible.

Faced with 200,000 lines of code, we trace the relationship between authentication and delivery. We introduce a proposal for asynchronous processing and inspect the requirements it must preserve and the operations it needs to adjust. One repair leaves an obstruction; another configuration is consistent. We can explain why using both the original code and mathematical evidence. That is the development experience I want to build.

In that environment, a codebase is both an implementation to read and a geometric object through which to reason about what can remain and what can change. Refactoring becomes a question about correspondences that preserve semantic structure. Repair becomes a question about the existence and deformation of configurations satisfying the conditions. I want the individual difficulties of everyday engineering to become approachable through a shared body of mathematics.

Through the SAGA Theorem, the Atlas Theorem, and Annapurna, I have been building that foundation in theorems and counterexamples. We already have verifiable results on comparisons between meaning and geometry, changes in resolution that preserve diagnostics, and structural comparison and information loss. I am also pursuing formal verification in Lean so that others can check the foundations themselves. The work toward the major theorem continues from those results.

There is still substantial tooling work ahead: reliable extraction and updates, usable ways to query meaning, and evaluation in actual development. I want to measure not only how much code and how many tokens an agent consumes, but whether it retains the requirements that matter and carries its understanding into the next session. Each of these is part of bringing the mathematics into the hands of people who build software.

In this future, using the tools would not require every developer to learn algebraic geometry. People and AI would express what they want to build and what they want a change to preserve. The theory and tools would connect those questions to semantic structure, perform the computation, and return results with evidence. As AI becomes capable of proposing more changes, mathematics can help us explore those possibilities with greater confidence.

Treat software's meaning as geometry, and put that geometry in the hands of the people building it. That is the ambition behind Semantic Geometry of Architecture. From understanding 200,000 lines of existing code to exploring configurations that have yet to be implemented, I want people and AI to be able to reason about the same space of meanings.

Repository: AlgebraicArchitectureTheoryV2

There are pairs of changes that the observations of AAT (Algebraic Architecture Theory) cannot tell apart — even though one keeps the system coherent and the other breaks it. And the difference cannot be recovered by any post-processing of the same observed values. This summer, that limit became a theorem, machine-checked in Lean 4.

In five weeks starting August 2, 2026, we proved sixteen theorems and refuted two claims. An AI agent loop did the implementation; I set the goals, reviewed the proofs, and made the calls. This article is a record of what we found, and of the road that led there.

1. AAT: Algebraic Architecture Theory

AAT is a research program that analyzes software architecture with the tools of algebraic geometry. It starts from observing source code. Implementations are abstracted into components called Atoms; the specification is written as a family of equations called laws. Design coherence then becomes a mathematical question: does local correctness glue into a consistent whole?

A running example from earlier articles is the one-cent drift. Three modules of a commerce service — checkout, payment, and ledger — each pick a rounding rule that passes review on its own, and the card gets charged one cent more than the screen displays. Each module follows its own rules. The whole still doesn't add up.

In this example, each module's implementation is an Atom, and an equation like "the amount displayed equals the amount charged" is a law. A quantity that aggregates the local mismatches into a global one, like that one cent, is a cohomology class, and reading it off to point at the inconsistency is what we call diagnosis. The earlier work — the SAGA and Atlas theorems, each with its own article — made all of this measurable.

A view is the result of reading the code at a particular resolution and from a particular angle; a service-level view and a module-level view are different views. Carrying an analysis result from one view to another is transport, and swapping out the base the analysis stands on is base change. In the one-cent example, adding settlement as a new context changes the very ground of the analysis; that is one instance of base change. When an operation survives such a swap, we say it is closed under the swap.

Every theorem in this article is machine-checked in Lean 4, a proof assistant that mechanically verifies whether a proof establishes the statement written down.

The question of these five weeks: when you change how you look, or the ground you stand on, how much of your analysis and your comparisons survives the move?

2. Five things we can now say about software design

1. Observation alone cannot always tell a sound change from a breaking one.

Take two candidate changes. Test results, metrics, every value in AAT's observations: identical. Yet one preserves global coherence and the other destroys it. Such an example has been constructed, and no aggregation or post-processing of the observed values can distinguish the two (Section 5). The practitioner's intuition — "you can't manage architecture by numbers alone; you have to look at the structure" — is now a theorem inside the model.

The information you need lives not in the numbers but in the correspondence that connects the before and after of a change. So the next move is not to inspect change proposals after the fact; it is to derive the required companion change directly from that correspondence.

2. The degrees of freedom in a fix are now known exactly.

You change one side of an interface. How can the other side be fixed so the two still agree? The theorem describes the full space of compatible fixes (Section 5). Find one, and every other fix can be derived from it — none missing. A design review can move on from "is this fix acceptable?" to "how much freedom does this fix have, and does the choice matter?"

3. Harmless-looking normalization stays in your design.

Some formatting and normalization passes are not supposed to change meaning, and as far as observation goes, they don't. Even so, there are cases where the local normalizations scattered across a system cannot, in principle, be merged into one globally consistent operation (Section 4). Fixing a convention for "what counts as the same meaning" does not end the design question; which operations remain sound under that convention is itself part of the design. So normal forms deserve to be first-class citizens of the design, not an afterthought.

4. We now know exactly when divide and conquer is honest.

Analyze each module, then combine the results into a conclusion about the whole. The condition for this to be sound is now a theorem, in necessary-and-sufficient form (Section 3). We also proved that analysis results do not depend on how the code happens to be written down. Together, the two mean analysis need not start over on every change: there are precise conditions under which re-checking only the changed part and its overlaps is enough. That matters at scale — for large codebases, and for fleets of AI agents developing in parallel.

5. A change of meaning cannot pass through the label layer.

On a fixed base, relabeling alone — types, tags, and other metadata — cannot move observable meaning. A change of meaning can live only on the side where the base itself moves. This, too, is a theorem (Section 8). There is now a structural reason why metadata edits preserve meaning.

The one-cent drift connects here as well. That example showed that the failure of locally correct modules to glue can be measured. The new results establish where the limits of that measurement lie. The boundary between what can be measured and what in principle cannot is now drawn as a theorem.

3. Three layers of theorems

The sixteen theorems answer three questions.

Can analysis results be carried between views of different resolution and level? Yes, and by any route: the result of a service-level analysis and the result of a module-level analysis can be traded back and forth without loss, and moving across levels loses nothing either. Catch the one-cent drift at service granularity or at module granularity; either way, it can be matched up as the same inconsistency.

When the base of the analysis is swapped, which operations survive as theorems? The answer is a table of conditions, direction by direction: classifying the operations that vary with the base; base change along refinements that carve the base finer; and lifting, which extends a partial result one level up. Each stands as a theorem with its scope pinned down. The point is that not every direction holds unconditionally. That dividing line — which direction holds under which condition — is what this layer establishes.

When may a conclusion about the whole be drawn from finitely many parts? A necessary and sufficient condition is now settled for when partwise analysis lifts to the whole, and for how far diagnosis survives transport. The negative side is proved as well: an arbitrary choice of covering can change the diagnosis of the very same system (Section 7). Unconditional divide and conquer fails, which is exactly why a condition is needed — and the condition is exact, nothing extra and nothing missing.

All three are classifications, not conjectures. The boundary — which operations are closed, and where closure fails — is drawn with proofs.

4. The normalization factor that cannot be removed

The strangest finding is an invisible factor lodged inside comparisons.

AAT generates comparison morphisms between two views: before and after a change, a fine view and a coarse view. Ideally a comparison is invertible; then the two views can be traded back and forth without losing information.

A comparison is a family of maps, one per object. For the comparison β that the system actually generates, each component provably factors as

$$\beta = E \circ \alpha$$

first through α, then through E. Here α is the ideal comparison prescribed by the theory, and it is provably invertible. And β is the concrete comparison assembled from actual input. How does the concrete deviate from the ideal? The deviation is exactly E, and this factor has three properties at once.

First, it is idempotent:

$$E \circ E = E$$

Applying it twice is the same as applying it once, like running a code formatter twice.

Second, it is invisible to observation. E moves no observable quantity; under the observations considered here, it cannot be told apart from a map that does nothing.

Third, it is nevertheless not invertible. Wherever E actually fires, it cannot be undone, and therefore β as a whole is not invertible either.

So what breaks the invertibility of comparisons is a normalization factor that appears, to observation, to do nothing at all. And invertibility does recover — if you restrict where you stand. In the raw world, β is not invertible. Restricted to the image — the values that actually remain after E — it becomes invertible. And on observable quantities, β and α agree exactly. The failure is not monolithic; it splits into these three stages. That recovery on the image will matter later: it is the doorway to the next stage of the research (Conjecture A, Section 11).

Then why not simply remove E? Bundle it into one natural operation running through every object, and subtract it from the system uniformly.

That is impossible, and this too is a theorem. From the same starting point, compare normalizing at A and then moving to B, against moving to B first and normalizing there. A concrete counterexample exists where the two disagree. Compatibility with movement between objects is what mathematics calls naturality: E is a perfectly usable normalization at each object, yet it cannot be bundled into one natural operation compatible with movement.

A structure invisible to the observations at hand, one that decides whether comparisons succeed, and that cannot be removed: it was there all along.

5. Degrees of freedom, and the limits of observation

The strongest result is a classification of the freedom in changes. The subject is compatibility of changes across an interface.

The setup: two sides joined by a single comparison, and a change applied to each side. We consider reversible changes here. Which pairs of changes preserve the comparison? In other words, when you change one side, which companion changes on the other side keep the whole consistent?

"Preserve" means this: changing one side and then comparing gives the same result as comparing first and then changing the other side. When that holds, the pair of changes is compatible with the comparison.

The theorem settles four things at once.

First, the compatible pairs of changes form a group: operations that can be chained and undone, with "do nothing" as a member. Integer addition is the model case.

Moreover, once one compatible companion change is found, every other one can be expressed as a difference from it. Any of them could serve as the reference; none is privileged from the start. This structure is called a torsor. The space of compatible companion changes has exactly that shape.

Second, for the comparisons the system actually generates, source-side changes can always be carried across, and the companion options on the other side form a coset: one solution multiplied by the elements of a subgroup. That subgroup is characterized by concrete conditions on the input data.

Third, the classification does not depend on presentation. The same design can be written in many forms: different file splits, different orders of definition. Rewrite first and then generate the comparison, or generate and then transport: the classification lands in the same place. What this analysis measures is not the style of the writing but the structure of the meaning — and that is what the proof establishes.

Fourth, observation cannot decide this classification. In a fixed example, compare two options.

The correct companion change is uniquely determined. Yet from the observations alone there is no telling whether that change was made or nothing was done — and provably, no post-processing recovers the difference. The information that singles out the one required companion change is lost by observation.

6. The plan: turning a metaphor into theorems in five stages

The rest of this article is the record of the five weeks that led there. In hindsight, it was a climb up a mountain whose map was wrong.

The early theory notes described AAT's construction as "Grothendieck-like." Grothendieck rebuilt algebraic geometry in the twentieth century; much of the machinery connecting the local and the global goes back to him. But "Grothendieck-like" was only a metaphor. How far does analysis survive moving between views and swapping bases? The road from metaphor to theorem was laid out as a five-stage plan:

Gr0 Metaphor: said, not shown
Gr1 Formalization: the claims written as mathematical statements
Gr2 Constructed instance: an object that actually satisfies them
Gr3 Pseudofunctorial coherence: transport between views agrees along any route
Gr4 Base-change completeness: every operation closes, base swaps included

The first two stages were already done in the theory notes. To climb the rest with theorems, eighteen research cards were issued starting August 2. A card is a document that pins down the theorem to prove, its scope, and its completion criteria.

7. The climb: from the foothills to Gr4

The first summit fell on day one. On August 2, the construction of Atom transport was proved: Gr2 reached. On August 8, the Atlas theorem. On August 18, transport across levels of views was proved to agree along any route: Gr3 reached. Four of the five stages, in under three weeks.

On the way, on August 11, came the first refutation. The plausible claim "changing the structural covering (a way of covering the whole with finitely many parts) does not change the diagnosis" turned out to be false. The refutation was not wasted. Its counterexample revealed where the residual — the quantity measuring a failure to glue — can appear and where it never can, and that distinction fed straight into the design of later counterexamples. A refutation becomes reconnaissance for the next route. That pattern would repeat for all five weeks.

Only Gr4 remained, and this was the real mountain. The foundation is a construction that takes two bases and builds a new one from the pairs that agree over a common base (the fiber product; call it crossing bases). The foundation theorem was proved on August 25, but it took 111 cycles (a cycle is one loop iteration: the agent adds one step of proof and records evidence and an audit trail). Most earlier cards had finished in a few to a few dozen cycles. That is the gradient of this mountain.

Standing on the foundation, we could finally see the terrain: this mountain has no single route, because it has no single summit. The work was split into six cards, one responsibility each, and between August 26 and September 4 all six were settled by proof, one of them taking 84 cycles and nine revisions of its card. The full record of all eighteen cards is in the appendix.

8. The mountain in the plan did not exist

All six cards were settled by proof. And yet Gr4 itself — the original goal: swap the base, analyze there, carry the results home, every step of the round trip a theorem — turned out to be false as stated. The content of the proved theorems itself showed that the mountain in the definition does not exist. On September 4, we decided not to write a completion record for Gr4. You do not file a summit report for a mountain that was never there.

What failed comes down to two things.

First, vertical rigidity. Call vertical the direction in which only extra labels are swapped while the base stays fixed. No meaning-moving transformation can be placed in that direction; such transformations have to be handled horizontally, where the base itself moves.

Second, the comparisons the system generates are not invertible, because, as Section 4 explained, the invisible factor E sits inside them.

So where did this conclusion come from?

9. The turning point: refutations became the harvest

The turning point came right after the hardest pitch, the lift to the upper level (84 cycles, nine revisions). That climb left behind not only its summit theorem but a pile of counterexamples, because every revision had deposited refutation theorems in Lean — each one saying, in effect, "not in this form."

Surveying the pile after the pitch, we noticed the counterexamples fell into three families.

• Attempts to place a meaning-moving transformation in the vertical direction had failed independently on two cards, and both were resolved by moving the transformation to the horizontal side.

• Lossy collapses were never going to yield invertibility. Identify two objects that differ only in decoration, and the map sends different things to the same place — no longer one-to-one, and a correspondence that is not one-to-one can never serve as part of an invertible comparison.

• Fix all the route data and swap only the comparison component joining the two sides, and glueability flips, while to observation nothing appears to change at all.

Line the three up and a common trait appears: something observation cannot see, yet which decides the strict properties — invertibility, glueability — and lurks in both the vertical and the horizontal directions. And none of these refutations had been designed to show this. They are the traces of the structure pushing back in the middle of proofs aimed elsewhere. If so, one structure must be behind them all. That structure was exactly the normalization factor E of Section 4.

So the sixth card, originally the summit card that was to close out Gr4, was redesigned into the card that would hunt down the structure behind the counterexamples. The redesigned card was settled by proof on September 4 (the 9/4 row in the appendix): the identification of E. The counterexamples had not been wrecking the mountain. They had been teaching us that there was a mountain that no one-dimensional map — no single yes-or-no ruler — could capture.

Beyond that identification, the refutation of September 5 (Section 4: the impossibility of bundling) turned E from something to erase into something to classify, and that decision shaped the final theorem of September 6 (the classification of Section 5). In hindsight, this change of course led to the highest summit of the five weeks.

The same pattern runs through all five weeks. The August 11 refutation supplied the method for designing counterexamples; on the cards of August 28 and 29, the content of a refutation directly became the design of the next revision, which was then proved. Individual refutations shaped the next card, and their accumulation rewrote the plan itself. In the Atlas article, I wrote that the four refutations were the best part of the climb. This time the same thing happened not inside one theorem but across the whole series. The map being wrong about the mountain: that itself was the harvest.

10. The descent was the real test

The work after standing on a summit was the real test, because declaring a proof complete and being able to trust that declaration are two different things.

Here is how the loop runs. The agent works cycle by cycle toward the claim and completion criteria fixed on the card, recording evidence and an audit trail as it goes. Completion requires, in order: a full completion report, four independent reviews of the same proof target (two mathematical, two Lean), and a cross-check of the evidence records. Only then is a card settled.

Over the five weeks, the procedure stopped exactly where it should have.

• Two cards halted at the first step (writing the claim down in rigorous types) when defects in the claims surfaced; I revised the cards before the loops resumed.

• One card halted at the provenance check of its evidence.

• Two cards had "proof complete" declared, after which the audit found defects in the records and rolled the state back; completion was then redone. In both cases the defect was in the evidence records, never in the theorem itself.

Those last two matter most. The summit had been declared, and the descent checks rejected it. Checking the evidence with the same rigor as the theorems is what makes the declarations trustworthy.

Over the five weeks, the Lean code grew to 791 files and roughly 300,000 lines, and the agent loop consumed about 24 billion tokens. Through all that volume, the policy of stopping on doubt was never relaxed — and I believe it is precisely because the system was built to stop that sixteen theorems in five weeks could be delivered without burning trust. Mathematics aside, the speed itself is an empirical result: a formalization that starts from observing source code can run this fast.

11. Higher peaks beyond

From a summit, you see the next mountains. The harvest of the traverse includes three conjectures. None are proved, but for each, the object to construct next is already in view.

Conjecture A (making normal forms first-class). Section 4 noted that invertibility recovers on the image, the world of values that remain after E. The next construction promotes that world to a first-class citizen of the analysis. There, the founding claim of the theory — that AAT's conclusions factor through the layer of Atoms — is expected to become a theorem of the form "the two worlds carry essentially the same analysis." Mathematics calls the construction a Karoubi envelope, and this kind of equivalence a Morita equivalence.

Conjecture B (an invariant finer than the cohomology class). Swap the base, and the obstruction's cohomology class stays fixed; yet glueability can change. So there are differences the cohomology class cannot see. The next construction defines a finer invariant — a quantity that stays fixed no matter how things are presented — that captures those differences. The torsor classification of Section 5 is constructive evidence that such a quantity exists.

Conjecture C (capturing the whole in finitely many parts). The condition of Section 3 for concluding from finitely many parts looks like an instance of what topology calls compactness. The next construction carries the covering classification into topological language.

And beyond the three conjectures stands the summit theorem of the whole program: that the space of meanings is representable as what algebraic geometry calls a scheme, a space glued together from solution sets of equations. The calculus settled over these five weeks tells us what can be carried, which changes preserve comparisons, and what observation loses. The route to that summit will be drawn on this map.

12. Why "the Goddess of Plenty"

We named this family of theorems Annapurna.

On June 3, 1950, a French expedition led by Maurice Herzog stood on the summit of Annapurna in the Himalayas: the first ascent of an 8,000-meter peak in history. But Annapurna was not the mountain the expedition had set out to climb. That was Dhaulagiri, next door. After long reconnaissance, the team concluded there was no route up Dhaulagiri and switched objectives. The maps of the day were wrong; even the glaciers were misplaced. They had to begin by searching for the mountain they would climb. The price was paid on the way down, where severe frostbite cost the climbers fingers and toes. And Annapurna, in Sanskrit, means "she who is filled with food": the goddess of plenty, of harvests.

The mountain drawn on our map did not exist either. We navigated by the actual terrain instead, and turned refutations into the harvest. For these five weeks, no name could fit better.

Five weeks ago, the goal stood on the map. Now it is the map that has been redrawn, and the mountain actually climbed bears the name. The goddess smiled, not because the climb went according to plan, but because the map's mistake was turned into a harvest.

Appendix: the full five-week record

Cycles is the number of loop iterations to completion.

Related: Atlas Theorem: How Far Can You Zoom Out? / The SAGA Theorem

Repository: AlgebraicArchitectureTheoryV2

• I want to hand an AI agent a multi-day job and have it run to completion. This post collects the rules for that — thirteen of them. Never let the loop rewrite its own spec. Enumerate up front what counts as evidence of "done." Review in independent parallel, never by majority vote. If verification didn't run, the answer is unknown, not pass. Nine more inside

• The rules run in my repository. In fifteen days of August 2026, this loop proved seven theorems and refuted one. About 104 cycles, roughly 67,000 lines of Lean 4. All seven proofs cleared four independently running adversarial review lanes

• The theorems are the main results my research program (AAT) set as its goals — nothing like famous open problems. But each was a multi-day proof target where refutation and revision were live possibilities. The outcomes were genuinely unknown

• A three-way division of labor: Claude (Fable) drafts the goal cards and runs adversarial reviews, Codex (GPT-5.6 Sol) drives the proof loop, and a human makes the rulings

• I make no claim that these thirteen rules are optimal. This is an N=1 record, with no controlled comparison

Introduction

When you hand an AI agent a multi-day job, the hard part is not getting it to work. It is deciding whether to believe the output.

The stage is my monorepo, AlgebraicArchitectureTheoryV2. It hosts AAT (Algebraic Architecture Theory), a research program that analyzes software architecture with the tools of algebraic geometry and machine-checks its claims in Lean 4.

This record is N=1. One team, one problem domain, fifteen days without sinking — that is all it is. But every one of the rules below has a logged incident where it fired.

A proof starts from a goal card pinned down by a human, and moves through this loop.

The thirteen rules pin down the load-bearing points of this loop.

Part 1: The Thirteen Rules

Rules of preparation

Rule 1 — Split the state three ways

Keep the spec, the execution state, and the evidence in different places. The spec says what to achieve, as a static document. The execution state says where we are. The evidence says what is done. Mix them, and you open a path for the AI to achieve the spec by rewriting it.

In this repository, the spec lives in a goal card, the execution state in a GitHub Issue, the evidence in a report file. The loop reads the card. It cannot write to it.

Rule 2 — Never let the loop rewrite the spec

Revising the spec always means stopping the loop and getting a human ruling. The AI may propose a revision; that is as far as it goes. When a refutation or a dead end hits, the easiest exit is to fix the goal instead of the proof — and sometimes that is even the right call. Which is exactly why this one decision lives outside the loop.

Rule 3 — Design failure as a deliverable

"The target turned out to be false" is not an error. It is one of the legitimate exits. Before departure, decide what a failure should leave behind: the counterexample itself, the mechanism of the failure, the parts worth reusing. Fix that format up front, and failures become raw material for the next spec.

Every goal card in this repository must carry a failure policy section, fixing in advance what gets recorded when a refutation lands.

Rule 4 — One obligation per cycle

At the top of each cycle, before any work, the loop writes down "the one obligation I will close this cycle" — the single remaining task — together with why it chose it. Working on a little of everything creates the illusion of progress, and when something fails, you can no longer tell what caused it. This prevents both.

Here, the cycle ledger opens with the chosen obligation. All 104 cycles carry this record.

Caveats

This group assumes the work can be cut down to a granularity where the spec fits in a static document. Exploratory work needs a separate stage that produces the spec itself. Here, a human and Claude did that, putting each draft through several rounds of adversarial review before handing it to the loop. Run the loop on a weak spec, and refutations and revisions will cost you several times over. And Rule 3's "format of failure" has to be designed per domain. Mathematics has the counterexample, a beautifully reusable form. What plays that role in your domain is not obvious.

Rules of verification

Rule 5 — Enumerate what counts as evidence of "done"

Enumerate, up front, the forms of evidence you will accept as completion, and accept nothing else, whatever the reason. The AI's "it's done" is judged one way only: does the evidence match one of the forms?

In this repository there are exactly three ways to close a proof obligation: a machine-checked theorem; a concrete example or counterexample pinned as finite data; a derivation from a previously proved result pinned by hash. And the inverse rule: moving the thing-to-be-proved into a typeclass or a structure field, so that it arrives as an assumption — however elegant — closes nothing.

Rule 6 — "The tests pass" is not done

CI is green. The PR is merged. Something with the right name exists. None of these is evidence of completion. Verification has to touch the conclusion itself.

This repository's acceptance contract carries that prohibition as one line of its verdict table.

Rule 7 — Review in independent parallel, never by majority

Run several reviewers with the same passing bar, in parallel, without showing them each other's output. Do not split them into a lead and assistants; a reviewer demoted to assistant stops hunting. Do not tally by majority; one fatal finding from one lane is enough to block. And keep a mechanism that can reject even a unanimous pass, on fixed mechanical rules.

Reviews here run four lanes: two mathematical, two Lean. The power to reject sits with a fixed rule that detects claim weakening.

Rule 8 — Pin every review to a commit SHA

"I fixed it" means nothing on a moving target. Pin the review to a specific commit, and define narrowly when a light re-check after a fix is allowed. If a change touches the spec, the light check is off the table, and you go back to full review.

Here, any of the following instantly disqualifies the light check: a statement change, a definition-body change, adding or deleting declarations, changing an import direction, changing a ledger status.

Rule 9 — Write it down: "no findings" is a rare pass

A review whose default outcome is pass is dead. This repository's review protocol contains one sentence: "No major findings is a rare pass." That single sentence changes how deep a reviewer AI digs.

Rule 10 — Name the cheats, audit for them every cycle

AI cheating comes in recurring shapes. Vacuous success: the condition holds because the set is empty. Playing to the grader: a construction shaped to the goal's wording. Claiming an equivalence while proving one direction. Smuggling the thing-to-be-proved into the setup. Reinterpreting the goal or the report. Give each shape a name, and you can audit for all of them mechanically, every cycle. Leave them nameless, and you will miss them every time.

The cycle ledger here has an audit field for each of the five.

Rule 11 — Fail closed

If verification did not run, the result is unknown, not pass. When a reviewer fails to start, the worst possible move is for the parent agent to fill in a pass on its behalf. Record undecidable as undecidable, and do not proceed.

The judges are audited too. Even the decision to stop a search can be overturned by an independent review.

Caveats

The biggest assumption in this group is an oracle: something that objectively decides "done." Here it is Lean, type-checking a proof. In domains with type checkers, reproducible tests, or deterministic measurements, this group transfers as is. Where judgment is subjective — prose quality, design — Rule 5's enumeration gets hard, and more of the weight lands on Rule 7's multiple lanes. One more thing. Rule 10's names come from your own incident log. The five shapes above are the ones this voyage actually met; yours will wear different faces.

Rules of rulings and cost

Rule 12 — Never automate the decision to stop

How many review rounds before cutting it off. After a failure, push on or retreat. When to pivot. Design these as human rulings, and confine them to a few explicit points — precisely so that everything else can be automated. What you delegate to the loop is the execution of rules already decided.

Rule 13 — Engineer the cost of verification

Explicitly ban whole-project verification — full builds, full test suites — inside the loop, and design the scoped checks that replace it, in advance. The pairing is the point: the ban and the replacement together. Just cutting verification collides with Rule 11.

Here, a hard rule forbids full research builds inside the loop. In their place: per-module checks, direct axiom audits, and a scan for placeholders, the markers of unproven holes.

Caveats

Run this group, and the bottleneck moves to the humans. In our measurements, after the cost reductions, the limiting factor was not tokens but the supply of specs and the bandwidth of human rulings. And since Rule 13 deliberately lowers verification coverage, record what you gave up. Whole-project verification moves outside the loop, to CI and post-merge audits. It does not disappear.

Thirteen rules, one principle

The thirteen rules are not a bag of tricks. Each is a different cross-section of one principle.

Don't trust the AI's output — and enforce that distrust with structure, not human attention.

Saying "we don't trust it" is easy. Doing it is not. Human attention is finite; nobody stays suspicious for 104 cycles. So the suspicion itself gets fixed into specs, ledgers, review lanes, and acceptance contracts, and the AI and the loop carry it for you. Almost every accident in these fifteen days was caught by structure.

Part 2: The Ship's Log

This voyage is one leg of an ongoing research program: AAT, Algebraic Architecture Theory. Its history is in earlier posts on this blog; the most recent is the Atlas theorem article.

On an earlier voyage, the theory reached the SAGA theorem. Whether a broken consistency can be repaired is decided by whether an obstruction class — a quantity measuring the twist that blocks repair — vanishes. That is what the theorem says. It went on to detect a one-cent accounting drift in a real open-source system. The point where theory touched the real sea is what we call our Cape of Good Hope. These fifteen days are the waters beyond that cape. There are pilots: algebraic geometry since Grothendieck teaches the seamanship — universal properties, descent, cohomology. But nobody holds a chart of this sea. Over software architecture, which claims stand as theorems and which fall to counterexamples — you find out by sailing.

On this ship, Claude draws the charts, Codex holds the helm, and a human makes the rulings, all under the same thirteen rules. Numbers like G-101 are serial numbers assigned to goals.

Day 1 — Setting sail on uncharted waters

The first theorem, G-101. The claim: swap the rewriting rules for parts, and there is exactly one canonical way to carry the entire analysis across. In engineering terms, a guarantee that switching modeling conventions does not mean redoing the analysis. For a long time, this theory had described its own construction as "Grothendieck-like." That was a metaphor. On this day, the mathematical condition the name demands — a universal property — was proved, and the metaphor became the name of a device.

Not a day of fair winds. Attempt 1 of the final review: three lanes demanding revisions, one rejecting outright. Nothing passed. Only on attempt 3 did all four lanes clear. This is what "a pass is rare" looks like as daily life (Rule 9).

Days 2–3 — Fair winds and a fake completion

Two theorems in two days. G-102: if structural bugs are zero, every coupling bug is caught on the semantic side — grounds for narrowing the search. G-103: the coarsest decomposition that can express a given family of laws exists and is computable — the minimum module granularity your spec requires, delivered by an algorithm.

It looks smooth. The review record says otherwise. G-102's pinned-commit review caught defects on runs 1 through 4, back to back. Run 3's catch was the worst kind: a shell with the right shape and an empty core. It passed on run 5 (Rules 6, 8).

Days 3–7 — The first storm

G-104. The claim: the conditions under which an architecture diagnosis does not depend on reading resolution. Put differently, the guarantee that the same defects appear in the same places whether you look at service granularity or module granularity — a guarantee about review granularity, in an era where AI writes the code and humans read it coarsely. This would later be named the Atlas theorem, one of the theory's main results.

In these five days, the target was refuted four times. The calibration condition grew to seven clauses. Three of them were beaten into existence by counterexamples; the rest were rebuilt through refutation and search. After the third refutation, the human called it: stop adding clauses, stop the loop, switch to a search campaign (Rule 12). A brute-force enumeration of 6,086 candidate conditions, plus a structural argument on top of it, delivered the verdict: no amount of clauses in this vocabulary can ever reach the target. That negative survey forced a rebuild of the coefficients themselves — the vocabulary of observations the diagnosis computes over (Rule 2). The loop set sail again, and summited on cycle 31.

Along the way, one cycle smuggled in a hidden premise. The audit caught it, and the artifacts were removed wholesale (Rule 10). The full story of these five days is in the Atlas theorem article.

Day 8 — The shipwreck becomes a chart

G-105. The claim: the space spanned by the supports of structural parts is invariant under pragmatic change — the shape drawn by the layout of parts survives a change of interpretive convention. Cycles 1 through 6 went smoothly. Then, on cycle 7, the last remaining obligation — constructing a firing witness, a concrete example where the premises actually hold and the conclusion is non-trivially true — was proved impossible in principle. The voyage's only refutation.

Read the record, though, and this is no sinking. The content of the impossibility was itself a theorem: the chosen coefficient generation rule swallows information indiscriminately, so the diagnostic geometry vanishes universally. The theorem-version of a dashboard with everything on it that tells you nothing. Because the failure policy existed in advance, the counterexample and its mechanism went straight into the ledger. The theory later repositioned this refutation as its first machine-checked evidence that observation must be chosen, not hoarded (Rule 3). The site of the shipwreck became the chart of the shallows.

Days 8–12 — The ship that lost its mast twice

G-107. The roughest five days of the voyage.

The target statement died twice. Version 1 — "agreement of diagnoses is characterized by condition C*" — met an exact counterexample. Version 2's sufficiency direction met another. Both were found by the out-of-loop search campaign and the reviews. Within that campaign, the decision to stop searching was itself overruled twice, by independent review, as premature. The judges were being audited (Rule 11). Version 3 rebuilt the claim on new pillars. Agreement of diagnoses is decidable by a finite computation — and yet that decision cannot be recovered from radius-1 local observation. Decidable in CI, unreachable by any pile of local lint rules. Codex proved the pair in a 27-cycle, 49-hour solo run.

The ending is on record too. The spec's adversarial review ran four rounds; mathematical counterexamples hit zero for three consecutive rounds, and the last two rounds' findings were wording-level refinements of the completion criteria. The human called it: the review is saturated. Cut it off (Rule 12). Knowing when to stop a review takes as much design as the review itself.

One more line from the record: the precedent search found no known prior example of a property that is decidable yet locally unobservable, pinned all the way down to a machine-checked proof. Uncharted waters was not a figure of speech.

Day 14 — A mountain in a single night

G-106. The claim: the mismatch that accumulates under repeated transport is measured by a two-stage obstruction, and its vanishing is equivalent to the whole cohering. Whether a multi-step refactoring or migration hangs together is measurable, and decidable. Drafted on day 2, this chart had matured for twelve days under rounds of review.

The loop set sail before dawn and finished five cycles while I slept. Cost: 9% of the weekly API limit (Rule 13). And not merely fast. Cycle 4, while closing its own obligation, detected a defect in the evaluator that cycle 2 had built — a wrong order in a non-commutative composition — replaced it, and logged the correction in the ledger. On the first cycle, one lane had passed a result, and the fixed anti-weakening rule overruled it (Rule 7). The ship repaired itself while under way.

Day 15 — A mirage, and the next chart

G-108. The theory is built as a tower of abstraction layers, and G-101 had proved transport at the ground floor. The claim here: transport at the upper floors is canonical too, and the only place it can fail is pinned to a single spot. If a migration fails, the cause is here — the endpoint of fault isolation, proved before the work begins. Seven cycles in half a day.

The day belonged to the reviewers. The firing witness submitted on cycle 5 looked, at first glance, like it met the requirements. The pinned-commit review established that its firing depended not on a genuine structural difference, but only on a settings difference and a coefficient swap — and sent it back (Rules 8, 10). The lookout stopped the ship a moment before a mirage was logged as land. After the fix, all eight lanes passed: the usual four, plus four independent formal-review lanes.

The same day, the chart for the next goal, G-109, was finished. Drafted by Claude, hammered through seven rounds of Codex's adversarial review, every finding fixed. The two ships do not trust each other's work. That is what trust looks like in this fleet.

Epilogue — The sea with no name

Fifteen days. Seven theorems and one refutation. About 104 cycles, about 67,000 lines. And the last chart is still out on the water.

This sea has no name yet. When we cross it, the chart will be complete — and the sea will receive its name, together with the theorem's.

Related: Atlas Theorem: How Far Can You Zoom Out? / Repository: AlgebraicArchitectureTheoryV2

• Does software architecture have a denotational semantics? Yes. But it differs from the classical one in three ways. Syntax is generated from observation. The meaning of a whole system does not exist automatically: its existence is itself a theorem. And broken meaning is not an error but a measurement.

• The existence theorems (global gluing, descent, torsor structure, resolution invariance) are machine-verified in Lean 4 inside AAT (Algebraic Architecture Theory).

• Beyond existence lies one more question. What is the shape of the space of meanings? I name the geometry that studies this question Semantic Geometry of Architecture, and announce it here as a research program.

• The summit is scheme representability: the conjecture that an architecture carries its own space of meanings. A roadmap closes the article.

The Commutative Diagram in the Meeting Room

I once watched a design argument end over a single diagram.

The dispute was about two processing paths. Should the data flow in this order, or that one? Neither side was budging. So we drew it out on the whiteboard. Four corners. Four arrows. Should this square commute — should both paths land on the same result?

The moment it was drawn, the argument changed character. The places that had to commute became equations to agree on. The places that were allowed not to commute became decisions to own. The former were agreed in minutes. The latter were settled as judgment calls. The shouting match about which path was "right" ended there.

On the way home I kept turning it over. What exactly had happened?

Programming languages have denotational semantics: a theory that assigns mathematical meaning to syntactic objects called programs. Does architecture have one? Wasn't the thing we executed by hand in that meeting room exactly that?

This article answers the question by drawing the map of a research program. Its name is Semantic Geometry of Architecture.

The Staircase of Semantics

The history of denotational semantics reads as a history of meaning acquiring structure.

At first, meaning was sets and functions. A program is a function from inputs to outputs. Not much could be said.

Dana Scott gave meaning order and topology. Sequences of approximations acquired limits, and it became possible to speak about recursion. "The meaning of this loop is the limit of its approximations" became, for the first time, a mathematical sentence.

Category theory gave meaning the structure of composition. In Lawvere's functorial semantics, a theory is a category, a model is a functor out of it, and semantic equations are commuting diagrams. The square on that whiteboard stands at the far end of this tradition.

The abstract model theory of specifications (Goguen and Burstall's Institutions) coined a slogan: Truth is invariant under change of notation.

Every step up the staircase enlarged what could be said. So: what is the next step?

Architecture never got to climb this staircase. Not even the first step.

No On-Ramp

Denotational semantics starts from syntax. For programs this worked because syntax was given from the start, by the language definition. Whatever the parser accepts is a program; semantics could then be defined as its interpretation.

Architecture has no given syntax.

There was a road that invented syntax first: architecture description languages, formal specifications, design documents. That road carries a curse — double bookkeeping of description and implementation. You write the spec, you write the code, and you chase their divergence by hand. The divergence always comes, and the description always loses. Every working engineer knows how that story ends.

Building the On-Ramp

Syntax is not written. It is observed.

There is a theory that has been building this on-ramp: AAT (Algebraic Architecture Theory). It takes source code as the source of truth, diagnoses architecture with the weapons of algebraic geometry, and keeps its mathematical core formally verified in Lean 4.

A typed fact extracted from code by observation is called an Atom. "This module writes this state." "This operation emits this event." "This value denotes this meaning." Small grains of fact. Atoms are the generators of syntax: from their combinations, the syntax of an architecture — a category of parts, a structure of coverings — is generated.

Generation does not stop at syntax.

Specifications are written as laws — that is, as equations. "Replay reconstructs the state." "These two operations commute." And the place where meaning lives (what mathematicians call the coefficients) is generated from the same Atoms, through the laws. The denotation function is not a bridge between two independently given worlds. It is a factorization of a single generative process out of Atoms.

That the whole semantics needs no input beyond the Atoms and the chosen laws is not a slogan. It has been proved, step by step, in Lean 4 — from the coefficient generation contract up to resolution invariance.

Turn 1: Syntax Is Observed, Not Written

In classical denotational semantics, humans write terms and the semantics interprets them. Here the order reverses. Syntax rises out of observation of the implementation, and the semantics stands on top of it.

As a consequence, semantics stops being a design-time document and becomes a measuring instrument. You do not write a spec first and bend the implementation to it. You observe the implementation, state equations over the observation, and measure whether they hold. Double bookkeeping cannot arise, in principle: the description to be managed is generated from observation.

Turn 2: The Existence of Global Meaning Is a Theorem

In the classical picture, the denotation function is total. The meaning of a whole program exists by definition. For architecture, this premise collapses.

Meaning is given locally first: a state where meaning is pinned down only over an individual context — a service, a module, an aggregate. Mathematics calls this a section. Choose a family of parts that covers the system (a cover), glue the local meanings over the overlaps, and if you reach one coherent meaning for the whole, that is a global section. The principle of reconstructing the global from glued local data is called descent.

"The meaning of the whole system" does not exist automatically, by definition. Its existence is a theorem, not a given.

And that existence theorem is already proved inside AAT. Call the algebraic fingerprint that aggregates the disagreements on overlaps the obstruction class. Over semantic coefficients:

$$\text{a global meaning exists} \iff \text{the obstruction class is zero}$$

$$\mathrm{Nonempty}, P_{\mathrm{sem}}(W) \iff [r_{\mathrm{sem}}] = 0$$

Here (P_{\mathrm{sem}}(W)) is the space of global semantic states over the chosen cover (W), and ([r_{\mathrm{sem}}]) is the obstruction class computed from that cover. A second theorem of the same shape stands on the repair side. Call a state where a law's violation has been fixed part-by-part a lift. Each part is fixed. Can all of them be fixed at once? The family of local lifts (s) determines a class

$$\partial_U(s) \in \check{H}^1(U, \mathrm{ConDef})$$

((\mathrm{ConDef}) is the coefficient of repair directions), and (\partial_U(s) = 0) is equivalent to the existence of a global lift. The distance between "fixable locally" and "fixable globally" is concentrated into this one class. What the symbol (\check{H}^1) actually contains, we will compute by hand later — counting one-cent coins.

If meaning exists, is it unique? That, too, is a theorem. Global meaning is not unique. The set of solutions moves freely along a single orbit under the action of a group (H^0) — the group of degrees of freedom coherent across the whole cover (a torsor structure). In place of uniqueness, the freedom of choosing a meaning is measured exactly, as a group.

Where did classical denotational semantics go? It did not disappear. It sits inside this picture as the degenerate case where the cover is trivial and the obstruction class always vanishes. Architecture lives outside that degeneracy.

Turn 3: Breakage Is a Measurement, Not an Error

In the classical picture, if a diagram that ought to commute does not, the semantics is simply wrong; the only move is to fix the definition until it commutes.

Architecture is different. Eventual consistency. The application order of concurrent operations. Data read differently by different teams. A broken commutativity is sometimes a defect to eliminate — and sometimes a decision the design has deliberately taken on.

So AAT treats breakage as first-class data. When the residual of an equation does not vanish, it is defined as an obstruction, presented as finite data, and measured as a cohomology class. Not merely "there is breakage": on which cover, on which overlap, as which class it breaks is localized.

It also explains what happened in the meeting room. The argument raged because the participants were assuming different commutativity, implicitly. Externalize the diagram, and the equations to agree on separate from the breakages to own. "Which path is right" is a question that does not converge. "Do we own this breakage" is a question that gets decided.

There are more theorems on AAT's shelf. Add a measurement axis, and two designs that had been identical come apart (Period Separation). This is the architectural version of the phenomenon program semantics has called full abstraction. The term carries historical weight. Plotkin posed the problem for the language PCF in 1977. Whether a semantics captures observational equivalence exactly stood for nearly twenty years as the hardest open problem in program semantics, falling only to game semantics in the 1990s. Period Separation is advance notice that the same question returns at the level of architecture.

Meanwhile, change the granularity of measurement within one axis — the resolution of the reading — and under calibration conditions the diagnosis matches exactly (the Atlas theorem). Coarsening loses no defect; refining fabricates none. That both accidents really do happen once the conditions are broken is included in the same theorem package, with finite counterexamples. There is no contradiction here: adding an axis genuinely refines the diagnosis; changing resolution within an axis does not. The two theorems divide those two directions between them. The Atlas theorem is the well-definedness theorem of this semantics. It turns the Institutions slogan — "Truth is invariant under change of notation" — into a theorem, complete with the conditions under which it holds and counterexamples for when it fails. Classical denotational semantics has no counterpart.

An existence theorem. The freedom of uniqueness. Well-definedness. Full abstraction. The chapters of the textbook are all there. Yet none of these theorems was proved for the sake of a semantics. Global gluing came out of repair theory. Conormal descent, out of the search for repair directions. The torsor structure, to quantify the failure of uniqueness. Resolution invariance, for the trustworthiness of diagnosis. Theorems stacked up for separate reasons were re-read, all at once.

Everything we had built was, all along, converging into one semantics.

The Geometry of Meaning

Back to the staircase. After order and topology, after categories — what is the next step?

Geometry.

The existence theorems answered "is there a meaning?". Beyond them lies a question the tradition never posed.

What is the shape of the space of meanings?

The algebraic geometry of AAT builds this question into the substance of diagnosis.

Failure carves out space. A failed equation generates an obstruction ideal, which carves out the range of lawful designs (the lawful locus). "How far does legality extend" exists not as a verdict value but as a region of space.

Breakage can be dissected. Obstructions are not only measured as classes; they are dissected in the vocabulary of singularities and monodromy. The same "non-commuting" can be an isolated gluing mistake or a torsion that winds through the whole design. Different pathologies; different surgery.

Repair is deformation theory. The dual of the coefficient (I/I^2) attached to the obstruction ideal (I) (this is what (\mathrm{ConDef}) was) gives the tangent space of first-order deformations that move a design toward legality. Repair candidates are not an ad-hoc list of patches. The space of repair candidates is itself a geometric object.

Evolution is geometry in the time direction. The history of design changes reads as a family of spaces of meaning.

And, at the far edge of the view:

If meanings form a moduli space — a space whose points are the meanings — then development is a trajectory in that space. Refactoring is motion within the space; repair is a step along a tangent direction; an architecture that feels stable is a trajectory that has entered a basin of attraction. A singularity becomes, literally, a point where the flow does not extend smoothly.

Statics and dynamics. The shape of the space of meaning is the statics; the motion of development on it is the dynamics. The commutative diagram tells you where it breaks. The geometry tells you the type of the break, and the surgery.

The Record of Cliffs

The Atlas theorem did not stand up on the first try. In AAT, proof search is carried by a loop of AI agents; humans adjudicate. That loop refuted its own target four times. State the claim, fall to a counterexample, sharpen the conditions, fall again. Along the way a no-go emerged — piling on shape-only conditions can never reach the goal, in principle — and the definition of the coefficients themselves had to be rebuilt. Each of the four refutations remains in the Lean codebase as a finite counterexample.

How the theorem finally stood can be read directly in the Lean code.

theorem generatedComparisonH1Map_bijective [Fintype Source]
    (M : TargetSupportedNerveMorphism coarseReading fineReading hcoarser
      coarse fine)
    (laws : FiniteLawFamily Source)
    (hcoarse : laws.Adequate coarseReading)
    (hfine : laws.Adequate fineReading)
    (hC : M.ConditionC laws hcoarse hfine) :
    Function.Bijective
      (M.generatedComparisonH1Map laws hcoarse hfine)

Read it line by line. M is the comparison morphism connecting a coarse reading and a fine one. laws is a finite family of laws. hcoarse and hfine say that both readings are adequate — able to speak that family. The conclusion: the comparison map between the two diagnoses (H^1) is a bijection. That is the exact form of "coarsening loses no defect; refining fabricates none". And the hypothesis hC — calibration condition C — is precisely what the four refutations carved out. Each refutation added a condition; the no-go forced the coefficients to be rebuilt; then the theorem closed in this form. The scars remain as the hypotheses of the theorem.

A second hunt ran alongside the theorem itself: the attempt to carve out, with finite syntactic conditions, the exact boundary where invariance holds. That one is still open. Three generations of candidate definitions fell to counterexamples in succession, and what remained was a negative result: within the registered observation vocabulary that sees no further than adjacent parts, that boundary is indistinguishable in principle. The separation proof is anchored by Lean counterexamples; pinning it down at theorem level is the current target of the climb.

Why tell the cliff stories? Because only a map with cliffs drawn on it is a map of real terrain.

A record of refutations is not a record of failures. It is the proof that the terrain this theory touches is real, not metaphorical. Cliffs do not appear on maps drawn from wishes. Every time the mathematics pushed back, the map became more accurate.

Touching the Rock

After the cliffs, the rock face. Let us verify by computation — once, concretely — that an obstruction class is not a metaphor.

The AAT repository contains a runnable example called "the one-cent drift". A pull request lands on a roughly 3,000-line commerce service written in Rust. Unit tests are green in every configuration. Every hunk of the diff can be justified in review. And the PR charges the customer's card one cent more than the checkout page displays.

Money flows through three modules. After the PR, they speak three different rounding conventions. In the demo basket the subtotal is 33,990 cents and the loyalty discount is 2.5%, so the exact discount is 849.75 cents.

The actual demo measures over a somewhat larger complex; we extract the skeleton. A part, together with the declaration of the range it is responsible for, is called a chart. Our three modules are three charts. The overlaps — the interfaces between modules — are also three, and they form a ring. Measure the disagreement on each overlap:

$$r(\text{display} \to \text{payment}) = 849 - 850 = -1$$

$$r(\text{payment} \to \text{ledger}) = 849.75 - 849 = +0.75$$

$$r(\text{ledger} \to \text{display}) = 850 - 849.75 = +0.25$$

This is the raw data of the obstruction.

Can it be repaired? A repair means moving each chart's value within what that chart's law allows. Display and payment can move only in whole cents — screens and cards live in the world of integer cents. The ledger cannot move at all — being exact is the ledger's law. Moving chart (X) by (c(X)) changes each disagreement to

$$r'(X \to Y) = r(X \to Y) + c(Y) - c(X)$$

And here arithmetic decides everything. (c(\text{display})) and (c(\text{payment})) are integers; (c(\text{ledger})) is 0. So no repair can change the fractional part of any disagreement. The (+0.75) and the (+0.25) survive every local repair.

(H^1) is a quotient: the space of measured disagreements, divided by the space of disagreements that local repairs can produce. The fractional parts that just survived are a nonzero class in that quotient. What produces the residue is not the shape of the ring as such. It is the poverty of the moves the laws allow: two parties that can move only in integers, and one that cannot move at all. The moment you take the quotient under this constraint system, a residue that no local repair can erase stands as a global invariant. Try minimizing it yourself. Set (c(\text{payment}) = 1) and the residual shrinks to ((0, -0.25, +0.25)) — but since the fractional part of (+0.75) cannot be erased, some overlap must always retain a quarter of a cent. That is the size of this design's obstruction class. In the demo, a CI gate detects the class and blocks the PR; after a repair that unifies the conventions, it passes. The whole pipeline runs as an example in the repository.

In passing, the classical embedding also becomes a proposition. If the cover has a single chart, there are no overlaps. The place where disagreements would live is zero, so the obstruction vanishes by definition. Classical denotational semantics — where whole-program meaning always existed — is the degenerate special case of this arithmetic. (This is degeneracy in the choice of cover, a different axis from the reading resolution that the Atlas theorem protects.) The claim of Turn 2 is not rhetoric; it is the generalization of this computation.

This (H^1) is not some exotic import. Linters, contract tests, consistency checkers — what they measure are local conditions: inside single files, on single interfaces. The moment you try to measure "the disagreement that no local fix can remove", you are computing this quotient, by definition. Your consistency tools have been approximating (H^1) without knowing its name.

And the shape has a pedigree. Bell's theorem of quantum mechanics, in sheaf language, says this: all local observations are pairwise consistent, yet no global section explains them simultaneously (the sheaf-theoretic contextuality of Abramsky and Brandenburger). The skeleton — a presheaf, and the absence of a global section — is the same as the computation we just did. The ring of three rounding conventions is locally correct everywhere; only the global ledger fails to exist. The mathematics that showed quantum mechanics admits no classical global explanation is measuring why your microservices cannot reconcile one cent. The scale differs. The shape does not.

The Summit: Semantic Scheme Representability

This map has a summit. No one has reached it.

Algebraic geometry has an operation called (\operatorname{Spec}). From a commutative ring (R) — an algebraic system in which you can add and multiply — it builds a space (\operatorname{Spec} R) that geometrizes the ring's equational content. Seeing systems of equations as spaces: the founding move of algebraic geometry.

The conjecture. For the collection (\mathrm{Sem}{A,r}(R)) of coherent realizations of meaning over coefficients (R), generated from Atoms and laws ((A) is the architecture, (r) the choice of reading), there exists a geometric object (M{A,r}) and a natural bijection

$$\mathrm{Sem}{A,r}(R) \simeq \operatorname{Hom}(\operatorname{Spec} R,, M{A,r})$$

An architecture (A) carries its own space of meanings (M_{A,r}). To choose a realization of meaning is to choose a map into this space. If it holds, the space of meanings stands as an intrinsic geometric object, independent of the choice of reading and of the convenience of observation. The existence theorems, the freedom of choice, the tangent space of repairs — all of them line up again as properties of this one space.

The shape of this conjecture is not an accident. Algebraic geometry contains a turn of perspective called the functor of points (Grothendieck's relative point of view). A space is not given directly as a set of points; it is known by the totality of maps into it, from all coefficients. To know a space and to know the maps into it are the same thing (the Yoneda lemma). So the conjecture — the collection of realizations of meaning coincides with the maps into some space — traces the legitimate way of defining a space of meaning. And the history of moduli problems teaches how steep this road is. The moduli of elliptic curves fails to have a fine moduli scheme because its objects have automorphisms, a failure that forced the invention of stacks. If architectural realizations carry automorphisms, this summit too rises from scheme to stack. The terrain, branch point included, is already mapped in the classics.

The greatest enemy of this conjecture is not an external counterexample but circular definition. Define realizations from the start as maps into (M_{A,r}), and representability holds vacuously. Only by defining the collection independently — as solutions of equations out of Atoms and laws — and then proving that it coincides with maps into a space, does the claim deserve the name of a theorem. The local part is expected to follow almost by definition, as a matter of solution spaces of equations; the substance of the claim concentrates in the gluing. The heart of this conjecture, too, is descent.

How the conjecture can die has also been designed. If representability fails to close at the scheme level, the obstruction — automorphisms of realizations, higher gluing obstructions — is not a failure: it is cashed in as evidence that the ascent to stacks is necessary. If the affine level trivializes, the independent definition of the functor gets rebuilt. What happens upon refutation is decided in advance. The discipline of the cliffs applies to the future as well.

This is a conjecture. But a map on which the summit is visible and a map on which it is not are different maps.

On the Name

I call this research program Semantic Geometry of Architecture.

The word order is the content. This is not geometric semantics — geometry used as a tool to explain meaning. It is geometry whose subject is the space that meaning itself forms.

The overall position:

• AAT — the pure mathematical foundation: the statics of the space of meaning

• Semantic Geometry of Architecture — the research program opening on top of AAT — this article

• The SAGA theorems — a proved theorem series inside it (gluing, repair, descent)

• The Atlas theorem — a proved solitary peak inside it (resolution invariance; well-definedness)

• SFT (Software Field Theory) — the dynamics on the space of meaning: development as trajectory

One rule attaches to the name. It is never abbreviated. The acronym would collide with Grothendieck's Séminaire de Géométrie Algébrique, a monument of algebraic geometry. Out of respect for that SGA, this program is always written out in full. If you are not prepared to write a long name every time, you have no business hanging "geometry" over your door.

Where We Stand

Where do we stand now?

Looking back, every stretch of road behind us is paved. Global gluing, conormal descent, the torsor structure, Atlas, Period Separation, the single-source generation completeness series. Every theorem up to this point has passed machine verification in Lean 4. Under the road lies bedrock fixed in the theory's canonical text: syntax generated from Atoms, laws as equation systems, the coefficient generation contract, the denotation functor.

Looking up, a slope with no footprints. The moduli of meaning. The summit of Semantic Scheme Representability. The promotion of breakage to 2-cells (lax denotations). Normal forms of the resolution hierarchy. The return of full abstraction. Not one line of proof exists yet.

The route is drawn. The first technical gate is base change of coefficients — widening coefficient generation from a fixed number field to general coefficient algebras. From there the climb runs through the moduli of meaning to representability. The ridge conjectures get picked up along the way.

The scaffolding is all public.

• Theory and Lean formalization

• The SAGA paper (Zenodo)

• The Atlas theorem

Coming Back Down

Time to come down. What the theory brings back to the meeting room is a two-phase structure. At design time, choose the equation system. At observation time, measure the residuals. Agreeing on a commutative diagram is choosing an equation system. After implementation, compute the residuals of the chosen system from observation and measure whether the agreement holds. The measurement is mechanized — AAT's tooling implements it. The design-time agreement becomes, unchanged, the observation-time measuring standard.

What happened in that meeting room at the start of this article was a manual execution of the first phase of this semantics. That the argument converged the moment the diagram was drawn was neither luck nor a victory of rhetoric. That diagram was a component of a semantics. The theory executes it, not by hand, but as a measuring instrument.

Meaning forms a space. The survey of that space has just begun.

• A veteran reviewer does not read every line. They switch reading resolution to match the property they are checking. Is there a guarantee that reading coarsely misses no bugs? This article is the record of proving the conditions under which there is.

• AAT (Algebraic Architecture Theory) treats source code as the source of truth, abstracts implementations into Atoms, turns specifications into equations called laws, and analyzes architecture with the weapons of algebraic geometry. Defects appear as cohomology classes — algebraic fingerprints.

• Within AAT, an AI agent loop proved in Lean 4 what we call the Atlas theorem: for two adequate readings, one a coarsening of the other, satisfying a calibration condition C, the diagnostic fingerprints coincide exactly — zooming out loses no defects, zooming in fabricates none. Break the conditions and both failure modes really occur, with finite counterexamples.

• The agent refuted its own target statement four times before the summit. A no-go argument then showed that no shape-only condition can ever suffice, forcing the coefficient definition itself to be rebuilt. Five working days, 31 modules / 13,028 lines of Lean, four-lane adversarial review.

• The article walks from pixel art and the sampling theorem, through the four refutations and the discovered condition C, to what this means for code review in the era of AI-written code.

A photorealistic portrait and a 16×16 pixel-art sprite can show you the same face. Comics theorist Scott McCloud called this amplification through simplification: removing lines doesn't discard information, it sharpens the essence.

Can we say the same about software architecture diagnostics? Look at your system at service granularity or at module granularity, and the same bugs show up in the same places — not as a feeling, but as a proven guarantee.

This article is the record of proving that guarantee — we call it the Atlas theorem — in Lean 4. The AI agent that set out to prove it refuted its own target statement four times. Those four refutations turned out to be the best part. The protagonist here is not any proof technique. It is the discipline that accumulated refutations as results instead of writing them off as failures.

Everything below happened between August 4 and 8, 2026 — five working days.

The project

The subject is AlgebraicArchitectureTheoryV2. Take the source code as the source of truth; abstract the implementation into parts called Atoms; turn the specification into equations called laws. Treat architecture as geometry, and analyze it with the weapons of algebraic geometry. That is AAT (Algebraic Architecture Theory), and this monorepo is its formal verification in Lean 4.

The theory had a weak point that everyone had been politely ignoring: granularity.

Whenever you analyze an architecture, you implicitly choose a resolution. Services? Modules? Methods? If the diagnosis changes with that choice, then what is the diagnosis actually measuring — a property of the architecture, or a convenience of the observer?

There is a precedent for this problem: the Nyquist–Shannon sampling theorem. Sample too coarsely for the signal's bandwidth and frequencies that don't exist appear (aliasing) while signals that do exist vanish. The moiré stripes in a photograph are the visible face of the former. The granularity problem is the sampling problem of architecture diagnostics.

Glossary

The claim — the Atlas theorem

If a coarsening preserves enough information, then looking finely and looking coarsely detect exactly the same defect fingerprints — nothing appears, nothing disappears.

The Atlas Theorem (formally: the Diagnostic Resolution Invariance Theorem) Given two adequate readings, one a coarsening of the other, satisfying the calibration condition C, the comparison map is an isomorphism. The choice of resolution does not change the diagnosis. Measuring finer adds no diagnostics (the No-New-Diagnostics corollary); measuring coarser loses none. The counterpart: a coarsening that violates the conditions really does produce defects that don't exist or hide defects that do — with finite counterexamples.

In Lean, this is pinned down as a bundle of five claims: (i) the construction of the comparison map, (ii) its bijectivity, (iii) the corollary (measuring finer creates no new diagnostics), (iv) three counterexamples for broken conditions, and (v) a firing witness where all conditions hold and a nonzero diagnostic actually flows across the map. "Claims (i)–(v)" in the table above are these five.

The stage — nerves, readings, coefficients

An observation of an architecture is represented as a nerve, a finite combinatorial structure. The vertices are charts: a part together with a declaration of the region it covers (its support). A dependency or overlap between two charts is an edge; a declaration that three charts have been checked consistent is a face (a triangle). The axioms demanded of a nerve are minimal: each face's three edges (its boundary triple) must meet at matching endpoints — for some charts (A, B, C) they line up as (e_0 : A \to B), (e_1 : A \to C), (e_2 : B \to C). That is all.

The choice of resolution is a reading. When one reading is a coarsening of another, a factor map (\pi) sending fine values to coarse values exists uniquely (the coarseness order and this factorization are imported wholesale from a theorem proved earlier in the same repository). The fine and coarse nerves are connected by a nerve morphism (\varphi) whose chart / edge / face correspondences commute with endpoints and boundaries. This is the formalization of "the sprite corresponds to the original portrait."

Coefficients are generated from laws. Each law in the law family is pushed through the reading (descended), and from the descended evaluation values, a generation contract called K0 / K1 (given in full below) builds a coefficient space over each cell, assembling a three-term complex:

$$C^0\ \text{(on charts)} \xrightarrow{\ d_0\ } C^1\ \text{(on edges)} \xrightarrow{\ d_1\ } C^2\ \text{(on faces)}$$

(d_0) takes "the difference of values at an edge's two endpoints"; (d_1) takes "the alternating sum over a face's three edges, (e_0 - e_1 + e_2)." Since (d_1 \circ d_0 = 0) (this too is a theorem derived from the endpoint matching of faces, not an axiom), the first cohomology

$$H^1 = \frac{\text{1-cochains killed by } d_1}{\text{image of } d_0}$$

is defined. This is what "diagnostic class (fingerprint)" means. The intuition: every pair of adjacent parts is locally consistent, yet going around a loop, the books don't balance. Only that "twist" survives the quotient into (H^1). That is why a defect's fingerprint lives not inside any single file but in the gluing structure.

Finally, the comparison map. From the nerve morphism (\varphi) and the descent-compatibility of the coefficients, a map of complexes (a cochain map) arises, inducing a map between the (H^1)s. The core claim (ii) of the Atlas theorem says: under condition C, this induced map is a bijection. Surjectivity means "coarsening hides no diagnostics"; injectivity means "coarsening fabricates no diagnostics."

The pixel-art metaphor from the opening is not decoration. It matches this structure part for part.

The art historian Ernst Gombrich argued that a picture is only half drawn — the viewer supplies the rest — and called that contribution the beholder's share. Translated into AAT: what stays invariant across resolutions is not the picture (the code) itself, but what the beholder evaluates from it — formalized, the law family. That is exactly why the invariance is law-relative.

And you have met this "beholder" before: a veteran engineer doing code review. An experienced reviewer does not read every line at the same magnification. Checking API compatibility, they read at interface granularity; hunting a race condition, they drop to individual lines. They switch reading resolution according to the property they are checking. Choosing the right review granularity is, today, a skill that lives in experience and intuition. The Atlas theorem is a first step toward making that granularity mathematically tractable: it gives the question "how coarsely can I read without losing information about this property?" a rigorous footing for the first time.

But the human eye — and the veteran's intuition — does all of this without a guarantee. That is why clouds have faces in them, and why reviews miss things. The question this theorem asked was: under what conditions does the guarantee hold? And the identity of that condition — calibration condition C — was unknown to everyone at the start. The requirements document (the research card that froze the proof target) said so from day one: "If C holds trivially, the theorem is a restatement. If C is too strong, the theorem is empty. The identity of C is the substance of the theorem."

So it proved. Four times.

Refutation rounds 1–3: whack-a-mole

The proof ran as an autonomous AI agent loop. The human (me) froze the requirements document and did nothing but adjudicate. The agent does not stop until it has pinned either a proof or a refutation in Lean. The three rounds below are what the loop brought back early on. All three are refutations.

Refutation 1: the forgotten filling

The first candidate conditions, C0–C3 (the original four), looked only at the correspondence of points (charts) and lines (dependencies). The counterexample the agent found: on the coarse map, some loop is a filled-in triangle — a face declaring "checked, no problem" has been glued over it. Lift it to the fine map, and there is only the outline. No filling. A defect fingerprint that vanishes on the coarse side survives on the fine side. The comparison map has no way to be an isomorphism.

The counterexample was pinned as 937 lines of Lean, and a condition was added: fillings must lift too (C4).

Condition gained, C4 (plain form): every coarse face has at least one fine face mapping to it under the nerve morphism's face correspondence.

Refutation 2: parallel lifts

C0–C4, with the new C4, was broken next. A single road on the coarse map can correspond to two parallel roads on the fine map. All of C0–C4 hold, yet the thin loop between the two parallel roads leaves a new fingerprint that exists only on the fine side. Nothing constrained multiple lifts landing on the same coarse road. Uniqueness of lifts (C5) was added.

Condition gained, C5 (plain form): at most one fine edge maps to each coarse edge (together with the existing existence clause C2: exactly one).

Refutation 3: the displaced loop

C0–C5 fell as well. This time, a loop on the coarse map — a road that returns to its own starting point. Its unique lift connected two different intersections on the fine map. A nonzero fingerprint on the coarse side then vanishes on the fine side. Refutations 1 and 2 broke surjectivity (the coarse side misses diagnostics); this one breaks injectivity (the coarse side alone sees a phantom diagnostic). What was needed: a road that returns to itself must lift to a road that returns to itself (candidate C6).

Condition gained, C6 (plain form): every fine edge mapping to a coarse self-loop (an edge whose two endpoints are the same chart) is itself a self-loop.

Three rounds in, a bad feeling was taking shape. Every added clause exposed another hole. Would this ever converge?

One decision made at the very start was paying off. Every refutation is pinned as a finite counterexample in a Lean file, not spent as a one-off rebuttal. These files would later be incorporated into the theorem's counterexample part — the proof that "break the conditions and this is how it fails." Not one refutation was wasted.

The pivot — a no-go that stopped the loop

Here the human's turn came. The ruling: stop the clause-adding loop. Instead, dispatch a separate computational search (a "hunt") to test candidate conditions exhaustively — with three stopping conditions fixed in advance.

• A (success): a condition is found that excludes the three known counterexamples and admits no new ones within the search range

• B (structural negation): it is shown that no such condition can exist in principle

• C (stall): progress stops in either direction

The result was B. And not as a product of the search itself, but through a single argument discovered while designing it. The conditions were not lacking. The language for writing conditions was. That is what came to light.

The argument is called two-point separation. On one and the same shape (the same configuration of points, lines, and faces — the same incidence), you can build three worlds that differ only in their coefficient data.

But every condition candidate considered so far — C0–C5, C6, even candidates imported from category-theory textbooks — was a predicate computed from the shape alone. Same shape, no way to distinguish. So any shape-only condition that accepts even one genuine positive example must also accept its impostors with the same face. No matter how cleverly you keep adding clauses, the answer is not in this language.

In sampling-theorem terms: arrange your sampling grid however ingeniously you like — without declaring the signal's bandwidth (the coefficients), no guarantee against aliasing can even be written down.

From this point, a coefficient generation contract (K0/K1) was introduced — coefficients must be generated from law evaluation values by a unique rule — and condition C was relativized to per-coordinate sub-maps (subnerves) of the coefficients. What matters is that this redefinition was not a matter of taste. Given the no-go, there was no other way. The definition was not designed. It was discovered.

The discovered language — the coefficient contract K0 / K1 and condition C in full

The coefficient side first.

K1 (derived supports). Only charts may declare a support (a covered region). An edge's support is derived as the intersection of its two endpoint charts' supports; a face's support as the intersection of its three boundary edges'. Allow independent support declarations per cell, and the no-go's "support hole" — zeroing out just one edge's coefficients by hand — becomes constructible. So the freedom to declare is itself removed.

K0 (generated coefficients). The coefficient field is fixed to (\mathbb{Q}). Each cell's coefficient coordinates are pairs ((\text{law}, \text{value})), where the values are the distinct values the descended law evaluation takes on the cell's support, each with multiplicity one. Indexing by occurrence counts or support sizes is not permitted — this kills the no-go's "duplication." The spaces in each degree are

$$C^0 = \mathbb{Q}\text{-valued functions on } {(\text{chart}, \text{law}, \text{value})}$$

$$C^1 = \mathbb{Q}\text{-valued functions on } {(\text{edge}, \text{law}, \text{value})}$$

$$C^2 = \mathbb{Q}\text{-valued functions on } {(\text{face}, \text{law}, \text{value})}$$

and the differentials are generated coordinate-wise: the ((\text{edge}, \text{law}, \text{value})) component of (d_0) is the difference of the two endpoint charts' matching ((\text{law}, \text{value})) components; the ((\text{face}, \text{law}, \text{value})) component of (d_1) is the alternating sum (e_0 - e_1 + e_2) over the boundary triple. Matching labels correspond identically; absent labels give zero. No other coordinate correspondence is generated. (d_1 \circ d_0 = 0) is derived as a theorem by per-label computation from the endpoint matching of faces, never assumed. The comparison map's coefficient part is likewise not declared but generated, as the identity on ((\text{law}, \text{value})) from the (\pi)-compatibility of descent. Adding, duplicating, or omitting coordinates is forbidden across the board. The word "contract" is meant literally: the substance of this language is how little it lets you declare.

Coordinate subnerves and relativization. For each coefficient coordinate ((\text{law}, \text{value})), the cells carrying that coordinate (the cells on whose derived support the descended evaluation takes that value) form a sub-nerve, the coordinate subnerve. Under K0/K1, (H^1) and the comparison map decompose as direct sums over coordinates, and each block reduces to a one-dimensional constant-coefficient comparison over its subnerve. This decomposition is the mathematical justification for relativizing: the geometric conditions C1–C4 need only be imposed per coordinate subnerve, while the global C0, C5, C6 are imposed on the whole nerve.

With that, condition C in full:

• C0 (cover-image agreement): each coarse chart's support equals the union of the (\pi)-images of the supports of the fine charts in its fiber

• C1 (fiber connectivity): in each coordinate subnerve, each coarse chart's fiber graph (the fine charts mapping to it, plus the fine edges staying within the fiber) is nonempty and connected

• C2 (edge-lift existence): in each coordinate subnerve, every coarse edge has a lift within the subnerve

• C3 (local fiber acyclicity): in each coordinate subnerve, every rational 1-cycle on a fiber graph is spanned by (\mathbb{Q})-linear combinations of boundaries of fine faces whose boundary edges all lie in the fiber. A local condition, equivalent to the vanishing of the fiber's first homology

• C4 (coarse-face lift): in each coordinate subnerve, every coarse face has at least one fine face mapping to it — the spoils of refutation 1

• C5 (unique coarse-edge lift): each coarse edge's (\varphi)-fiber has at most one element; with C2, exactly one — the spoils of refutation 2

• C6 (self-loop endpoint reflection): every fine edge mapping to a coarse self-loop is itself a self-loop — the spoils of refutation 3

Finally, the condition list carries a prohibition rule. C may not contain any clause equivalent — or close to equivalent, even one-directionally — to "the comparison map is an isomorphism" or "one side's (H^1) vanishes." That would smuggle the conclusion into the hypotheses. The single explicit exception is C3, a local condition that sees only the internal data of individual fibers, the analogue of the Leray-type local acyclicity assumptions imposed on covers in classical Čech theory. The boundary between legitimate assumption and smuggling is itself fixed as part of the condition list — because the prover is an AI agent. Escape routes are closed at the specification.

Refutation 4, and the summit

The loop restarted on the revised specification and, after a few cycles of groundwork, the agent attacked a spec hole in the revision itself (refutation 4). A nerve morphism may declare fine edges and faces with no coarse counterpart as "unmapped (degenerate)." The declaration rule had a hole: the condition for declaring a face unmapped did not require the same declaration of the three edges around it. In the counterexample exploiting the hole, the construction of the comparison map (claim (i)) itself fails. Pinned in 433 lines, repaired by making the declaration hereditary: a face may be declared unmapped only if its three boundary edges are already declared unmapped.

From there it was a straight run. Restarted once more after the repair, the loop reached the top in 24 iterations (cycles).

The route to the top — structure of the proof

Stage one: block decomposition. Under the K0/K1 generation rules, prove as theorems that the complexes, (H^1), and the comparison map decompose as direct sums over the coefficient coordinates ((\text{law}, \text{value})). Each block reduces to a one-dimensional constant-coefficient comparison over its coordinate subnerve. The global problem splits into a direct sum of the simplest possible pieces. From here on, attack block by block.

Stage two: injectivity. Analyze the kernel of the block comparison map and show that a nonzero coarse diagnostic class cannot die on the fine side. This is where C6 earns its keep — it closes the accident path found by refutation 3, where a nonzero coarse class evaporates below. (Refutation 4's hereditarity works earlier still, underwriting the very constructibility of the comparison map.)

Stage three: surjectivity (the crux). Show every fine diagnostic class comes from a coarse one. Four moves:

1. A discrete Stokes theorem translating C3 into "the vanishing of periods around fiber loops." Local face-filling becomes an analysis-flavored statement about loop integrals vanishing

2. From vanishing periods, construct a primitive on each fiber — the finite-graph version of "a curl-free field has a potential"

3. Express the primitive-normalized residue as a coarse 1-cochain, using the "exactly one lift" channel provided by C2 / C5 (descent)

4. Use C4's face lifts to check the 1-cochain is a cocycle on the coarse side, and promote it. Surjectivity closes

Stage four: main theorem and corollary. Bundle the block bijections along the direct-sum decomposition into the global bijection — claim (ii). As a consequence, measuring finer creates no new diagnostic classes: the No-New-Diagnostics corollary, claim (iii).

Stage five: counterexamples and firing. The three counterexamples of inadequate coarsening — fabricated diagnostics, hidden diagnostics, and broken condition C (claim (iv); the legacy of the refutation rounds becomes the material here) — plus a single firing witness where every condition holds simultaneously and a nonzero diagnostic class actually flows across the comparison map (claim (v)). Without (v), the theorem could be hollow — "no example satisfying condition C actually exists" — and the concrete Lean data forecloses that.

The division of labor among the conditions is clean. C3 kills local loops; C2 / C5 provide the unique communication channel for lifts; C4 carries the consistency of faces; C6 and hereditarity prevent the self-loop and degenerate-declaration accidents; C0 / C1 lay the ground. Every clause won through refutation is used at a specific step of the injectivity or surjectivity proof. There are no ornamental clauses.

The final artifact: 31 Lean modules, 13,028 lines. Every new declaration depends on standard axioms only — no sorry, no added axioms. Acceptance ran through an independent adversarial review in four lanes (two mathematics, two Lean), all reporting "no major findings," plus a separate completion audit that includes checks for proof cheat-routes.

Operating discipline for AI agents

This project's operating principle for AI has been constant: give the AI no cheap way out. For mathematical research, it became this division of roles: the human only adjudicates (freezing the spec, approving revisions, designing stopping conditions); an implementation agent runs the proof loop; a review agent runs adversarial review.

Six rules carried those five days.

1. Refutations are first-class. "A refutation is a legitimate result" was written into the requirements document in advance. So four refutations became accumulation rather than demoralization, and the counterexamples were incorporated into the theorem itself

2. Declare the crux up front. "The identity of C is the substance of the theorem" was written at the start — so each refutation read as "one more piece of the substance unearthed," not as failure

3. Freeze the specification. The requirements document does not change while the loop runs; revisions go through human adjudication and independent review. Because the goalposts cannot move, a refutation means what it says

4. Pair every clause with a firing requirement. Each added condition brings a matching witness requirement that the condition actually does work somewhere. This closes the path where a theorem hollows out under layers of protective clauses

5. Switch to diagnosing the language. After three rounds of clause-adding, the question changed from "which clause is missing?" to "can this language express the answer at all?" The no-go is the product of that switch

6. Multi-lane adversarial review. Agents other than the implementer review the work in independent mathematics and Lean lanes, structurally removing the incentive to declare victory

We stepped on every one of these traps, repeatedly. The rules are what came out.

Honest limits

• The result stands at machine verification in Lean plus internal multi-lane review. External peer review (journal submission) is ahead; a paper is in preparation

• The theorem is a statement about finite models over a fixed coefficient field. Condition C is sufficient; a general characterization of necessity is explicitly left open

• "The diagnosis is invariant," not "the observation is invariant." A coarse reading does not make the raw observations look the same; the claim is that the fingerprints of what the laws evaluate coincide

Why "Atlas"

An atlas is a book of maps drawing the same world at different scales. Open any page and the same country is there. That is what this theorem says.

The name comes from inside the theory, not from marketing. AAT's canonical text has long had the vocabulary chart atlas — a cover as a collection of charts — including the very phrase "when the chart atlas changes." The Atlas theorem is, literally, the invariance of diagnosis under change of chart atlas. There is a mathematical coincidence too: that a manifold's identity does not depend on the choice of atlas is the first invariance principle you meet in differential geometry.

The next step is already fixed. Re-measure a real microservice system at three granularities — service, module, method — and observe that diagnostics stay stable within the adequate range, and that fabricated and hidden defects really appear when adequacy breaks. A resolution sweep: the theorem and its counterexample pairs replayed on real data. The guarantee that the sprite shows the same face as the portrait — this time on a production codebase.

One last thing: why this theorem, now. In the era of AI-written code, the bottleneck of development has moved from generation to review. AI agents write faster than humans can review line by line, and "how coarsely can we afford to read?" has become the question that sets the throughput of a development pipeline. The only way review scales is to read at coarser resolution — and until now there was no guarantee that coarseness doesn't distort the diagnosis. The Atlas theorem is a first step toward that guarantee, asked and answered as a theorem. And not by coincidence, the theorem itself was proved in the middle of the same problem — "how do humans accept AI output produced at full speed?" — held up by the operational answer of multi-lane review and audits. Operations and mathematics are digging at the same bottleneck from opposite sides.

The full history — theory, proofs, counterexamples, audits — is in the public repository: AlgebraicArchitectureTheoryV2

As of this writing, the theorem's Lean proofs, counterexamples, and completion audits are all reproducible from the repository. Questions and objections welcome.

This article records the improvement in three rounds, each written in the same shape: problem → hypothesis → verification → fix. Spoiler up front: all three times, the first hypothesis — the culprit our intuition pointed at — turned out to be innocent. The hero of this story is not any individual trick. It is the profiling that kept calmly rejecting our hypotheses.

Lean-specific concepts are explained as they appear, so you should be able to follow without knowing Lean.

One more thing. Nearly all of the measurement and implementation in these three rounds was done by AI agents (Rounds 1 and 2 in interactive sessions with a human present; Round 3 by an autonomous loop driven by a requirements document). The human — me — did two things: approve the numeric targets and accept the results. The second half of the article covers that operation, in particular the machinery that keeps an AI from converging on cheap solutions.

Background: the project

The subject is AlgebraicArchitectureTheoryV2, the same monorepo my previous articles have covered — a formal verification of a theory of software architecture in Lean 4.

Here is the complete list of Lean machinery this article needs — five items:

For scale: the audit covers 4,000+ declarations, and among them sits one heavyweight file — a construction of schemes from algebraic geometry — that took 38 minutes to build on its own.

CI runs on GitHub Actions. Alongside lake build, every PR runs a kernel axiom audit — a machine check that every theorem is genuinely proved, with no cheating in the proofs. That gate is non-negotiable; Round 1 explains what it actually does.

Round 1: The axiom audit, 7m 11s → 11s

Problem

In Lean, every theorem is derived from axioms, and the derivation is machine-checked by the kernel (a small, trusted checker). "The proof went through" means it passed this check. The important wrinkle is that Lean has an escape hatch called sorry. Writing sorry means "I'll prove this part later," and it does not fail on the spot (your editor does show a warning). Internally, it silently assumes an axiom called sorryAx. Users can also add arbitrary unproven propositions as axioms with the axiom keyword.

In other words, "CI is green" alone cannot distinguish "everything is proved" from "someone plugged the gaps with axioms." So for each declaration, we walk its dependencies all the way down and compute the set of axioms it reaches, then check that this set stays within the three standard axioms accepted across Lean and mathlib — propext, Quot.sound, and Classical.choice (the axiom of choice is that last one). This is the axiom audit. A hidden sorry or a smuggled-in axiom cannot survive it. If you call yourself a formal verification project, you don't get to skip this gate.

Lean exposes this walk-and-collect operation as a function called collectAxioms (it is the same machinery that runs when you type #print axioms my_theorem). Our CI ran it over every declaration — 1,207 at the time, over 4,300 today — and that step took 7 minutes 11 seconds on every run. The audit was heavier than the build itself.

Hypothesis

The audit's entry point is a giant file, 5,000+ lines, listing every audited declaration. Intuition speaks up: "A file this big must be expensive to elaborate. Split it and it'll get faster."

Verification

Before splitting anything, we measured where the time went. The result flatly contradicted the intuition:

• Resolving imports: ~10 seconds

• Elaborating the 5,000-line listing: zero difference (changing the line count substantially didn't move the audit time)

• collectAxioms × 1,207 declarations: ~5 minutes

The culprit was not the big file. It was how the audit was being called. To find the axioms a declaration reaches, you must walk the dependency graph to its roots — the theorems it uses, the theorems those use, and so on. collectAxioms performs this walk from scratch for every declaration. But every declaration in the project shares the same enormous foundation, mathlib — so 1,207 declarations were walking essentially the same graph 1,207 times. In complexity terms: O(declarations × graph). Splitting the file touches neither factor of that product. It was ineffective even on paper, but having the measurement in hand is what let us reject it in one line and move on.

Fix

We made the audit two-phase:

1. Success path: share a visited set — "never walk the same node twice" — across all declarations, and traverse the graph exactly once. Since the question is "does the union of reached axioms stay within the standard three?", one shared walk gives the same verdict as per-declaration walks

2. Failure path: only when a non-standard axiom shows up, fall back to the classic per-declaration walk to attribute which declaration is guilty, with error messages in exactly the original format

That collapses O(declarations × graph) to O(graph) on the success path without giving up any error quality. It is the textbook visited-set move from graph traversal — no Lean-specific magic anywhere. Measured in CI, the audit went from 7m 11s to 11s, and the whole lake build job at the time went from about 9.5 minutes to 2m 12s.

Round 1's lesson: suspect "heavy operation × repetition count" before "heavy file." And record the rejected hypothesis (file splitting: no effect) as a result in its own right — so nobody after you re-digs the same hole with the same intuition.

Round 2: Every PR took 41 minutes — the cache was saved before the build

Problem

Round 1 happened in mid-July, when the lake build job had shrunk to a bit over two minutes. Over the following two weeks, a series of heavyweight algebraic-geometry implementations landed (Round 3's protagonist grew fat in this period), and at some point every PR — even one touching a single file — was running a full cold build of the entire tree: about 41 minutes.

Lean builds are incremental, in the same spirit as C++ or Rust. If the build artifacts (.olean files, stored per module under .lake/build) are still around, only the changed files and their downstream need rebuilding. For that to work in CI, the previous run's artifacts have to be carried over as a cache. The cache was configured. It just wasn't working.

Hypothesis

When a cache "doesn't work," the usual suspects are a key mismatch or eviction. Is the toolchain hash off? Are old generations being evicted?

Verification

Before auditing keys, we read the CI log timestamps top to bottom. Two lines sat one second apart:

23:19:35  Cache save   (final internal step of lean-action)
23:19:36  lake build +Formal.AG starts

The cache was being saved. Before the project was built.

We set up Lean with lean-action — a composite action (a reusable bundle of steps) — configured with build: false, running the build ourselves in a later step. But lean-action saves .lake (the build artifact directory) to the cache in its own final internal step, and a composite action's internal steps always run before your subsequent steps. So the 2.15 GiB being saved contained only dependency artifacts (mathlib); the project's own .olean files had never been cached at all. No wonder every PR took 41 minutes — each one rebuilt all of our own code from a blank slate.

There was a bonus discovery. mathlib is too big for individual users to build, so the community distributes prebuilt artifacts from Azure (lake exe cache get; about 15 seconds in our measurements, environment-dependent). The cached 2.15 GiB was therefore something you could fetch in 15 seconds anyway — worthless in the GitHub cache. Worse, at 2.15 GiB × 4 generations, it was nearly exhausting the repository's 10 GiB cache quota. A useless cache was crowding out the useful one.

Fix

We separated the cache responsibilities:

• Disable lean-action's GitHub cache (use-github-cache: false); mathlib artifacts keep coming from the Azure cache

• Explicitly restore (before build) and save (right after build) only the project's own .lake/build

• Prefix the key with a hash of lean-toolchain + lake-manifest.json, so toolchain or mathlib bumps fall back to a proper cold build

• Save with always(), so failed builds still persist partial artifacts — every push to a red PR reuses everything built up to the failure point, making iteration fast

The actual workflow looks like this (excerpt). The one thing that matters: put the save after the build yourself.

- name: Restore Formal build cache
  uses: actions/cache/restore@v5
  with:
    path: .lake/build
    key: formal-build-${{ runner.os }}-${{ hashFiles('lean-toolchain', 'lake-manifest.json') }}-${{ github.sha }}
    restore-keys: |
      formal-build-${{ runner.os }}-${{ hashFiles('lean-toolchain', 'lake-manifest.json') }}-

- name: Build
  run: lake build +Formal.AG

- name: Save Formal build cache
  if: always()
  uses: actions/cache/save@v5
  with:
    path: .lake/build
    key: formal-build-${{ runner.os }}-${{ hashFiles('lean-toolchain', 'lake-manifest.json') }}-${{ github.sha }}

With this, PRs that don't touch the heavyweight geometry files settle into cache hit + incremental build: a few minutes.

In fairness to lean-action: its cache works correctly in the standard usage where you let the action run the build too. It was our configuration — build: false with the build held outside — that stepped on the trap.

Round 2's lesson: when "the cache isn't working," read the timestamps before you audit the keys. Composite actions are convenient, but their internal step order is orthogonal to your workflow's step order. "Is the save actually after the build?" is worth checking with your own eyes.

Round 3: The 38-minute Geometry.lean — splitting it didn't make it faster

Problem

The largest remaining bottleneck was a single file: Geometry.lean, 5,129 lines, 108 declarations. It constructs actual schemes — the central objects of algebraic geometry, heavyweight abstractions even by modern mathematics standards — on top of mathlib, and it alone took 38.3 minutes in CI, 46% of the project's total CPU time. Even with Round 2's cache, any PR touching this file's upstream paid the full 38 minutes.

This time we fixed numeric targets before starting: longest module ≤ 600 seconds, total across the target modules ≤ 1,800 seconds, judged by the module times reported in one and the same GitHub Actions full build. Measurement method included, approved by the human before implementation began.

Hypothesis

It's a giant 38-minute file — split it into modules along its dependency structure and rebuilds will shrink and speed up. This is the "splitting makes it faster" hypothesis that Round 1 already rejected once, now in its build-time incarnation. Since elaboration runs per declaration, this time the reasoning looks sound.

Verification

First, a per-declaration profile. Lean ships with a built-in profiler; one command tells you which processing step of which declaration took how many seconds. Here is what we used:

lake env lean --profile --json \
  -Dprofiler.threshold=10 \
  -Dtrace.profiler=true -Dtrace.profiler.threshold=10 \
  -Dtrace.profiler.output=geometry-before-trace.json \
  Formal/AG/Examples/StandardGeometryReference/Geometry.lean

The breakdown: kernel type checking 57%, defeq (deciding whether two terms are definitionally equal) 39%, with the time massively concentrated in a dozen or so declarations. Following that center of gravity and the dependencies, we split the file into a 7-module DAG:

RawGeometry
└─ SectionRings
   ├─ LeftRestriction
   ├─ RightRestriction
   ├─ OverlapLeftRestriction
   └─ OverlapRightRestriction   * these four import nothing from each other → build in parallel
      └─ Scheme

We proved mechanically that the split broke nothing. Lean's #check prints a declaration's statement — the theorem's actual claim. We took the #check output for all 168 public declarations of the old file (794 lines), before and after the split, under the same toolchain and the same printing settings, and confirmed the SHA-256 hashes match. Not one character of any theorem statement changed. Being able to certify "the mathematical content is preserved" with a hash instead of eyeballs, even for a mechanical refactor, is one of the quiet joys of a formal verification project.

Then we measured the after in CI — and missed the targets. Longest module 770 seconds (target 600), total 2,483 seconds (target 1,800). Splitting shrinks rebuild scope and buys parallelism, but it does not remove a single second of elaboration. With module-boundary overhead, the total actually grew.

Digging deeper into the profile exposed the real culprit. The time was not spread thinly in proportion to line count. It was concentrated in the cost of definitional unfolding around specific definitions.

A short detour on definitional unfolding. In Lean, a definition is a pair of a name and a body, and the body can be unfolded in place when needed — much like a compiler inlining, except Lean does it during type checking. When deciding "do these two expressions have the same type?", Lean matches two superficially different terms by peeling definitions open (unification). Normally this is what lets proofs stay short. But when large-bodied definitions get involved, each peel exposes more definitions, and the terms balloon.

In our file, that ballooning happened while checking the functions that actually compute the scheme's components (large-bodied definitions) and the lemmas stating those computations are correct. The 96% of profile time in kernel checking and defeq was exactly the cost of checking these bloated terms: individual operations of 15–104 seconds each, stacked up inside single commands.

Line count was never the crime — the same shape as Round 1. The file wasn't heavy because it had 5,129 lines; it was heavy because of how specific definitions were being referenced.

For the record, we also tried two pieces of "standard-issue optimization" at this stage (switching to CommRingCat.hom_ext; using congrArg CommRingCat.ofHom — both established mathlib idioms). Neither improved the measurements; both were rejected. An idiom failing to help is also a data point, once you have a profile.

Fix

Surgery at the one point the profile indicated. The policy was uniform: rewrite so that the type checker never needs to peel the definitions.

• Separate a value's definition from the proofs about that value. When they are entangled, checking the proof part drags in unfolding of the value's entire body

• Pin lemma statements to named functions rather than unfolded expressions. If the match succeeds on the name, unification has no reason to open the body

• Consolidate the proof pattern duplicated across four theorems into a shared lemma, so the same expensive check isn't paid four times

The effect was dramatic. In a focused build (measuring just the one file), the heaviest module, RawGeometry, went from 291 seconds to 11. The operations that used to top the chart at 15–104 seconds max out at 57.5 milliseconds after.

The final CI measurement (full build of the merge commit): total across the 7 modules 1,750 seconds (29.2 min) ≤ target 1,800, longest module 468 seconds ≤ target 600. Both targets met. Done.

And that merge commit's CI run is a group photo of all three rounds. From the log:

Twelve minutes with the heaviest files fully rebuilt. That is the current worst case.

Round 3's lesson: splitting is not a tool for making things faster; it is a tool for parallelism and smaller rebuild scope. What reduces the total is surgery at the one point the profile indicates. And since these are two different improvements, measure them separately and judge them separately.

The improvements were driven by AI agents

As mentioned at the start, nearly all measurement and implementation across the three rounds was agent work. Rounds 1 and 2 ran inside interactive sessions, from measurement through implementation; Round 3 was an autonomous loop that took a requirements document (PRD) and drove everything from profiling to PR authoring to review response. During implementation, the human had exactly two jobs:

1. Approve the numeric targets and the measurement method up front (for Round 3: "longest ≤ 600s, total ≤ 1,800s, judged by module times in one and the same GHA full build")

2. Accept or reject based on measured CI values

To be honest, there is a third job upstream: writing the PRD. But that too is a collaboration with another AI; the human's actual work is choosing the direction and reviewing.

The PRD Loop

We call the autonomous loop from Round 3 the PRD Loop. It is handed to the agent (Codex) as a SKILL — an instruction document for agents. The skeleton:

• The input is a single PRD, with a guiding question and numeric Acceptance Criteria at the top. A human starts it with one command ($prd-loop <path-to-PRD>)

• One iteration is "gap analysis → file an issue → implementation PR → adversarial review → merge → ledger sync." It runs in small units: one iteration = one issue = one PR (one goal spanning several iterations is normal operation)

• A separate review gate (also an AI) judges each PR — never the implementer itself. After two rounds of "needs changes," the third escalates to a stricter, specialized gate (for Lean, a dedicated mathematical review gate); if that still fails, the item is marked stalled and returned to the human

• Loop state lives in GitHub issues, not in the agent's memory. If the session dies, the next session resumes from the same spot

• When every condition looks satisfied, an independent completion audit re-reads the PRD from scratch and verifies everything against reality. Until it passes, nothing gets to call itself "done"

Round 3's "profile → split → miss → dig deeper → hit" ran on this wheel as three PRs (split / reduction / closeout). Start to finish took just under a day. Human intervention along the way: approving the targets and confirming the measurement standard — a handful of GitHub comments.

Incidentally, our convention is that a completed PRD is deleted from the repository. A requirements document starts drifting from reality the moment implementation ends, so the permanent record is pinned to issues, PRs, and CI logs — and the document itself goes.

Closing off the cheap paths

Run such a loop naively, though, and one thing reliably happens. Agents are faithful to the incentives you give them, so left alone they converge on the cheapest path to a merged PR. Change the documentation instead of the implementation. Satisfy an unsatisfiable condition by "interpreting" it. Quietly defer the hard items. None of these is exactly a lie — but compounded, they settle into an equilibrium where "done" can be claimed at minimum effort. Call it the corner-cutting equilibrium.

So our SKILL reads less like a procedure and more like mechanism design: a set of rules that seals off the cheap paths one by one.

• No docs-only check-offs: a condition that demands implementation or verification can never be marked satisfied by a PR that only edits documents or ledgers

• No reinterpretation, no downgrading: a condition the agent cannot meet is escalated to the human as blocked, not read more weakly. The SKILL states it in so many words: "stopping is not failure; stopping is part of the loop's specification"

• The PRD is invariant during the loop: the agent cannot rewrite its own passing bar. If it finds a defect in the PRD, it stops and reports rather than fixing it (you don't get to edit the exam paper mid-exam)

• Checklists are not evidence: a checkmark means only "a past iteration claimed this." The final audit re-extracts the conditions from the PRD independently and verifies them against reality — code, tests, CI logs

• No self-grading: the completion auditor receives only the PRD path and issue numbers — never the loop's own "I believe everything is satisfied." If a review gate cannot run, the main agent does not stand in for it; the loop fails closed

These rules were not designed at a whiteboard, by the way. Each one was added after actually observing early loops try the corresponding move — settling a condition with a ledger entry, quietly shrinking scope in the name of safety. We were never smart enough to write all the guardrails in advance.

There is one design principle underneath all of it: make stopping honestly cheaper than pushing through dishonestly. Don't count on the agent's good will; move the equilibrium itself.

The best moment: the miss report

The best moment of this whole operation was Round 3's miss report. At the split PR, the agent wrote, in its own PR description: "Longest 770 seconds, total 2,483. Targets missed; this PR does not claim completion. Profile-driven reduction continues in the next PR." No human issued any instruction in response. The loop filed the reduction issue itself on the next iteration and merged the PR that met the targets the same day.

Declaring "done" and walking away is the cheapest move available at exactly that point, and the agent instead wrote missed and kept going. I credit that less to the agent's honesty than to the structure around it. When the passing bar is fixed in advance, reinterpretation is banned, and an independent audit will check every claim against measured values, then whenever declaration and measurement disagree, it is the declaration that has to move. Set the bar afterwards instead, and the temptation to fit the bar to the result appears — on the human side too.

If you are planning to hand optimization work to an AI, the most practical thing to take from this article is probably this: hand over the passing bar and the measurement method before you hand over the code. And make honest stopping the cheapest move on the board.

Conclusion

• Axiom audit, 7m 11s → 11s. The culprit was not the giant file but the unshared traversal walking the graph once per declaration

• Every PR at 41 minutes → incremental builds in minutes. The culprit was not the cache key but a cache save running before the build

• One 38-minute file → 29 minutes total, 8 minutes longest, 12-minute worst-case run. Splitting removed nothing; the culprit was definitional unfolding cost

All three first hypotheses were wrong. Progress happened anyway, because each wrong hypothesis was rejected by measurement and the rejection itself was passed forward as a result. "No effect" is a finding. File splitting rejected (Round 1), two standard idioms rejected (Round 3) — without those records, someone, human or AI, would have dug the same holes again.

On the AI side: Round 3's loop ran start to finish in under a day, across three PRs, with human intervention limited to a handful of GitHub comments.

Don't guess, measure. It's an old maxim, but in the era of AI-written code I think it needs a sequel — let the AI measure, and hand it the passing bar first.

• We have published a paper on Zenodo (DOI: 10.5281/zenodo.21603761, CC BY 4.0) that formalizes the "locally correct, globally broken" phenomenon of software architecture as mathematics, proves its central theorem, and measures it on a real open-source system.

• The central claim is a single sentence. Build two ways of measuring brokenness — one in the language of "how can this be repaired", one in the language of "which equations are violated" — without either referring to the other, and they turn out to carry the same scale. This is proved as a comparison theorem.

• On top of that, under a gluing condition, "the obstruction is zero" and "a repair of the whole system exists" are equivalent. The sentence "without this fix, the whole would have broken" — until now folklore — becomes a consequence of a theorem.

• The paper presents three layers — the mathematical proof, the Lean 4 verification status, and a reproducible measurement on a real microservice system — pinned to one and the same snapshot.

0. The story so far

The goal of this series is to move software architecture from something discussed with diagrams, folklore, and review-time taste to a mathematical object studied with definitions, theorems, counterexamples, and proofs. For readers new to the series, here is the cast.

Two articles ago I told the story of proving the theorem; last time I reported dogfooding it on a real OSS codebase. Today's protagonist is the first paper, which binds those results into one document. You do not need the earlier articles; everything required is introduced below.

1. No file has a bug, yet the system is broken

A real microservice system (train-ticket, 42 services) contains the following spot.

• order stores the order price as a raw string (private String price)

• inside-payment parses that string into a BigDecimal and computes exactly

• cancel parses the same string into a double, multiplies by 0.8, and rounds to two decimal places

Each of the three services follows its own convention perfectly. Each pairwise handoff succeeds on its own terms. And yet, follow the refund computation around the loop and the books do not balance.

original price:            12.33
cancel's convention:       0.8 × 12.33 = 9.864 → rounded → "9.86"
inside-payment's:          exact arithmetic → 9.864
remaining difference:      0.004 (less than one cent)

This sub-cent drift is booked in no service's ledger. And nowhere in the source is there any code that reconciles the three services' amounts at once. The paper calls this instance the one-cent obstruction. No file has a bug, yet the system is broken.

The paper is a report of building the mathematics that measures this phenomenon, proving its central theorem, machine-checking it in Lean, and — on the example above — walking the full circle from measuring the obstruction, through a CI gate blocking, to pre-validating a repair plan, to the gate passing, all reproducibly.

2. Two ways of measuring

Here is the heart of the paper. We construct two ways of measuring "how broken it is" — from two entirely different principles.

Ruler A — the language of repairs. Each service (from here on, a chart) comes with the repair moves permitted there. In the one-cent example these are operations like "unify the money reading to scale-2 BigDecimal" or "create a place where the rounding remainder is booked". Combinations of moves are called repair words, and we identify words that produce the same result. This gives each chart a space of meaningfully distinct repair options. The obstruction is measured as the amount by which neighboring charts' repair choices disagree around a loop without canceling out.

Ruler B — the language of equations. This side never looks at repairs. The conventions that should hold are stated as a system of equations — equalities like "both charts determine the refund as the same currency value". The obstruction is measured as the residue of equation violations that survives around the loop.

What matters is that the two constructions are independent — neither refers to the other. No equation appears in the definition of Ruler A; no repair appears in the definition of Ruler B. Think of two thermometers, one built from the expansion of mercury and one from the color of radiation. That two instruments built on different principles agree on their scale is guaranteed by nothing — merely building them proves nothing.

The SAGA comparison theorem (Theorem 5.1 of the paper) proves the following, over a chosen finite cover, whenever a finite list of conditions matching up the two rulers' local data (spelled out as a checklist in the paper) is satisfied.

1. The scales the two rulers use (the coefficients) are naturally isomorphic.

2. That isomorphism identifies the quantities they measure (the cohomology classes in H^1). The obstruction class measured by Ruler A is carried exactly to the obstruction class measured by Ruler B.

3. If, moreover, the family of repair states satisfies the gluing condition (the sheaf condition), then "the obstruction class is zero" ⟺ "a repair that glues the whole system exists".

In one sentence: semantic diagnosis (how to fix it) and geometric computation (which equations broke) translate into each other, in both directions.

3. Why this matters

"Two measurements agree — so what?" The value of the paper lives in the answer.

First: a round-trip ticket between diagnosis and computation. The language of repairs is the language of humans (and LLMs). "Unify the money reading across these three services and it's fixed" is a sentence in repair language. The language of equations is the language of machines: it reduces to finite linear algebra and computes deterministically. The comparison theorem is the round-trip ticket between the two worlds. A diagnosis posed on the semantic side can be computed on the geometric side; a result computed on the geometric side can be read back in repair language. In practice, the measurement tool ArchSig computes on the equation side, while what people want to receive is the repair side. The theorem's claim is that this bridge is not "these presumably correspond" but a proved isomorphism.

Second: "without this fix, the whole would have broken" becomes sayable. In the vocabulary of testing, a failure that never happened cannot be observed. "That fix prevented an outage" has always been a counterfactual with nowhere to stand. The third part of the theorem (zero class ⟺ existence of a global repair) gives that sentence a mathematical status. Hand the measurement a candidate repair, compute that the obstruction class vanishes, and you have pre-implementation validation that this particular fix makes the whole glue — as a consequence of a theorem, not as folklore.

Third: the nature of the obstruction becomes visible. A nonzero obstruction class means: no matter how any single chart re-chooses its own baseline, the discrepancy does not vanish. Re-paper one service's convention and the mismatches on its adjacent edges merely shift; the residue around the loop remains. A nonzero obstruction belongs to no file. Fixing it requires not a convention swap but a structural change — such as creating a place where the remainder is booked. "This is the kind of bug that a culprit hunt cannot find" becomes a computable verdict.

4. How the paper is built: three layers, one snapshot

The paper presents this mathematics in three layers of different character. Proof, machine verification, and measurement each answer a different kind of "really?".

Layer one: mathematics (Chapters 3–5). The full proof of the comparison theorem: the two independent constructions, the coefficient isomorphism, the H^1 isomorphism, the correspondence of obstruction classes, and the global-repair equivalence.

Layer two: Lean (Chapter 6). The central theorem's conclusion bundle, the lemmas of each stage, and concrete nonzero and zero examples (witnesses) are proved in Lean 4. Every row of the status table is proved, there is no sorry, and the only dependency axioms are Lean/mathlib's three standard ones — confirmed by a kernel-level axiom audit that runs in CI.

Layer three: measurement (Chapter 7). On the one-cent obstruction of §1, the diagnostic staircase runs its full circle.

And the three layers are pinned to one and the same snapshot by a tuple of identifiers — the Lean source tag, the ArchSig version, and the digests of the measurement inputs (the paper calls this the release identity). From any claim in the paper you can trace what kind of claim it is (proved / machine-checked / measured) and where its primary evidence lives. The correctness of the mathematics is carried by the proof, the correctness of the proof by Lean, the reproducibility of the measurement by pinned inputs and procedures. The design policy is to make the part you must take on faith as small as possible.

5. What the paper does not claim

Following the custom of this series, here is what the paper explicitly does not claim. These boundaries are fixed by the paper itself, in §5.7 and §7.5.

• The theorem is a theorem over a chosen finite cover. No identification with cover-independent cohomology is claimed.

• The theorem is not unconditional. The correspondence between the two rulers requires a finite list of conditions, and the paper's appendix pins down which proof consumes which condition. Finite counterexamples showing that removing any one condition breaks the isomorphism are also proved in Lean.

• The measurement does not claim to have discovered a new fault. Detecting the mismatch itself is the job of the lower rungs of the staircase. What the SAGA stage adds is chaining "each part is locally lawful", "the discrepancy survives the loop", and "this repair plan would glue" into one sequence of machine verdicts.

• The drift's frequency and monetary scale are not measured. Runtime measurement is future work, and not speaking numbers we did not measure is this project's discipline.

6. Where this goes next: SAGA is the first theorem

The SAGA comparison theorem is the first theorem of AAT's local-to-global capability to reach a full proof. If the theory is a tower, the first floor is now built. Chapter 9 of the paper describes the floors planned above it — explicitly as outlook, kept separate from the proved results (the two below are on the outlook side).

Architecture schemes. This paper measured whether one architecture glues. The next direction treats an architecture itself as a geometric object — the vanishing locus of its system of convention equations, a scheme — and develops morphisms, base change, and fibers between architectures as theorems. If this grows well, everyday judgments like "does this refactoring preserve the structure?" or "is the architecture the same shape before and after this PR — and if not, where did it change?" may acquire a geometric meaning: a verifiable map between architectures.

SFT (Software Field Theory). AAT is the statics of architecture: the consistency of one moment in time. SFT is the research program that builds the dynamics of change, branching, and merging on top of that geometry. A merge in version control is a gluing of local changes, and SFT reads it as descent theory. The target proposition has the shape "a software architecture is modular exactly when its future evolution satisfies descent" — and the static comparison SAGA proved is the ground this dynamics stands on at every instant.

7. How to read it, and where to get it

A suggested route for a first pass:

1. Abstract and Chapters 1–2: the problem and the AAT approach.

2. Chapter 7: the one-cent measurement.

3. The opening of §5.1: a plain-prose summary of the central theorem. You can follow the claim without the formulas.

4. Chapter 9: the research outlook — including the picture of what a theorem-grounded, deterministic measurement is for in an era when code is written by AI.

• Paper: SAGA: A Comparison Theorem for Local-to-Global Software Architecture (Zenodo, CC BY 4.0, PDF + reproduction bundle)

• Source: AlgebraicArchitectureTheoryV2 (MIT license — the Lean proofs, ArchSig, and all measurement inputs live here)

• Target codebase: FudanSELab/train-ticket

8. Closing

"Locally correct, globally broken" has long gone by the name integration hell, handled by folklore. What this paper shows is that the phenomenon has a precise mathematical name; that under that name the obstruction is computable; and that the two ways of measuring it — the language of repairs and the language of equations — are joined by a proved isomorphism.

A voyage that began from an abstract comparison theorem passed through machine verification and arrived at one cent in real code. That one cent is the smallest, most concrete witness to the fact that the sum of local correctness does not reach global correctness.

Questions, objections, and "I think my codebase has one of these triangles" stories are all welcome.

• This is the sequel to the SAGA theorem article. Last time, I gave the "locally correct, globally broken" phenomenon a theorem, proved in Lean 4. This time I took that theorem out into the real world.

• In a real microservice system that nobody wrote with the theory in mind — the research benchmark train-ticket — the exact structure required by the theorem's hypotheses turned out to exist.

• Every service follows its own money convention perfectly. Yet a sub-cent refund remainder vanishes without being booked anywhere in the system. The measurement returns both verdicts at once, and a repair plan flips the CI gate from BLOCKED to PASS.

• The find itself is almost comically mundane. But the value was never the find. It is the confirmation that the sea route exists.

0. The story so far

For readers new to the series: the goal of this project is to move software architecture from something discussed with diagrams, folklore, and review-time taste to a mathematical object studied with definitions, theorems, counterexamples, and certificates.

The previous article ended with the proof of the SAGA theorem. The theorem is true. One question remained: does the structure its hypotheses describe exist in real code? This article is that report. If you have been following the series, feel free to skip ahead.

1. The Lean proof is done. But does it apply to real software?

The SAGA theorem is proved in Lean 4. No sorry (Lean's placeholder for an unfinished proof), and the only axioms are Lean's standard ones. Whether the theorem is correct is no longer a question.

The question that remained is this one: does the structure its hypotheses require exist in real software?

However correctly proved, a theorem whose hypotheses are satisfied only inside mathematics quietly swings at nothing in the real world. Here is the bundle of hypotheses, in plain words. From now on I will call each service a "chart" and the convention a service imposes on itself its "law". Every chart obeys its own law. Values are handed between charts. And yet, when you follow the handoffs around a closed loop, a discrepancy remains that has nowhere to be reconciled. The quantity that counts this "discrepancy that survives a full loop" is the cohomology H^1 that starred in the previous article.

This bundle could, in the worst case, have been a structure that only assembles in artificial examples. The one-cent demo I published — a small Rust sample deliberately engineered so that a one-cent rounding discrepancy goes missing between modules — demonstrates that this structure produces the obstruction. It does not demonstrate that this structure occurs in reality. Only real data can show that. So I measured an external OSS codebase end to end, using exactly the workflow a real user would. Dogfooding.

What the discovery of the Cape of Good Hope meant was not "we reached India". It meant "the sea route exists". That is precisely what this experiment set out to check. Is AAT a sea that exists only inside mathematics, or does it connect to the sea of real code? Hence the name of this report: SAGA's Cape of Good Hope.

2. The experiment: measuring an external OSS the regular way

The target is FudanSELab/train-ticket, a standard benchmark for microservice research, built from surveys of industrial systems. It consists of 40-plus Java microservices with ordering, payment, refund, and consignment flows. The repository is roughly 500,000 lines including frontend assets; the measured target is the Java implementation proper, about 28.5 kLOC. What mattered was that this codebase knows nothing about my theory.

The measurement had two stages.

Stage 1 (a full build of the observation data). From the Java sources of 42 services plus a shared module, I built an ArchMap — the map of minimal observed facts (Atoms) read from the code — through the regular workflow: two independent reading passes, full adjudication of every disagreement, then an audit. The result: 2,118 Atoms across 43 observation units (contexts). All reading was done by lightweight-model subagents (Claude Sonnet), at a measured supply cost of about 4.1 minutes/kLOC (wall clock, parallel runs included).

Already at this stage, the map showed 8 distinct styles of carrying money coexisting across the 24 services observed for that convention: double fields, strings passed through untouched, BigDecimal parsed at the point of use, string concatenation. Each works fine on its own.

Stage 2 (SAGA). On top of the full build, I extended the laws to the full SAGA diagnostic stack and walked the staircase end to end. This is the main act.

3. The discovery: the vanishing-cent structure exists in real code

Digging through the real call graph of the full build, this structure emerged.

Three services — cancel (refunds), inside-payment, and order — form a triangle of actual calls, and the money convention disagrees on all three edges.

The three conventions can be confirmed in the sources (commit 313886e9).

First, order. The price is stored as a raw string.

// ts-order-service: Order.java
private String price;

Next, inside-payment. Balance arithmetic parses that string into BigDecimal and computes exactly.

// ts-inside-payment-service: InsidePaymentServiceImpl.java
totalExpand = totalExpand.add(new BigDecimal(order.getPrice()));

And cancel. The refund computation parses the same string into a double, multiplies by 0.8, rounds to two decimals, and stringifies again.

// ts-cancel-service: CancelServiceImpl.calculateRefund
double totalPrice = Double.parseDouble(order.getPrice());
double price = totalPrice * 0.8;
DecimalFormat priceFormat = new java.text.DecimalFormat("0.00");
String str = priceFormat.format(price);

So one and the same "order price" travels through three different worlds: untouched string / exact decimal arithmetic / floating point plus rounding. Whenever 0.8 × price does not land on two decimal places (say 91.33 × 0.8 = 73.064), the sub-cent remainder created by rounding appears in no service's books.

And here is the decisive part. Nowhere in the measured Java sources is there code that reconciles the three services' money at once. The pairwise handoffs exist: cancel reads the price from order, cancel sends the refund to inside-payment, inside-payment reads the price from order. But there is no place where all three are checked together.

In the language of the previous article: the three mismatched edges form a closed loop, and the face that would fill it — the membrane sealing the inside of the triangle, i.e. a site where the three are reconciled simultaneously — is missing. This is the SAGA theorem's bundle of hypotheses, verbatim. I did not plant it. Ordinary developers, each making reasonable implementation choices, produced this shape.

4. The measurement: the diagnostic staircase fires end to end

The diagnostic staircase is a series of diagnoses stacked from simple to strong. At the bottom, the raw mismatch measurement (Čech); above it, grounding (does each chart obey its own law?), descent (does the discrepancy survive a full loop?), comparison (is the before/after comparison mathematically legitimate?), and finally the CI gate. I assembled the laws over this structure and ran the staircase. Here are the results (monospace tokens are the instrument's verbatim output).

Reading it in order:

grounding = measured_zero. This is the trap part of SAGA. cancel, inside-payment, and order each follow their own money convention perfectly. A per-service review — human or AI — has no grounds to reject the mismatch as that service's violation. Locally, everything is lawful.

descent = measured_nonzero. And yet the discrepancy around the triangle is not zero. Moreover it is the kind of discrepancy that no service can eliminate by re-choosing its own convention: re-labeling one chart only shifts the mismatch along its adjacent edges, and one loop's worth of discrepancy survives. That is what the computation returned. Eliminating it requires a structural change — creating a place where the remainder is booked — not a re-labeling. This is "no file contains a bug, yet the system is broken", as a measurement.

Gate = BLOCKED. Placed in CI, this PR stops. Even if every module's tests are green, the state "the system can drift by a cent" gets stopped from inside the sea of green — the live version of what the previous article called "a class of analysis beyond linting".

Repair → gluing restored → PASS. Supply a hypothetical repair — "unify the three services' shared reading on scale-2 BigDecimal and book the rounding remainder explicitly" — and, within the selected complex, the discrepancy becomes zero, the comparison reports the obstruction is no longer recorded, and the gate flips to PASS. The repair can be verified to glue before anyone implements it.

The story designed into the one-cent demo (nonzero obstruction → BLOCKED → repair → PASS) replayed in the same order, on a real codebase instead of a synthetic one. That the minimal failure the theory predicts showed up at its minimal size — under one cent — reads to me as evidence that the theory's resolution matches reality.

5. What was established

First, the hypotheses are inhabited. The SAGA theorem moved from "proved, with synthetic examples only" to "proved, with an instance reproduced in real code". The risk of vacuity died with this one example.

Second — and this is the real prize — the faithfulness contract survived. Between the theory and the instrument stands a contract: the instrument speaks only where the theorem can speak. This was the instrument's first contact with adversarial real data, and the chain of implications (locally lawful → loop discrepancy nonzero → repair glues) fired in the same order, under the same conditions, as the theorem chain on the Lean side. The contract never broke. Every refusal was legitimate too: declare, falsely, that the drifting triangle has a reconciling face, and the bookkeeping arithmetic rejects the contradiction.

6. Couldn't static analysis or LLM review find this?

A fair question. "Show three files to an LLM that can read whole codebases — surely it would flag this?"

Honestly: finding this particular instance is probably within an LLM's reach. In fact, in this very pipeline, the money conventions were read by LLM subagents (Claude Sonnet). The difference lies in the form of the output after the finding.

• Non-locality as a verdict. An LLM can say "these three are inconsistent". The measurement returns "this is the kind of discrepancy no service can remove by re-choosing its convention" — as a computation. Narration carries no such guarantee.

• Separating benign from structural. In the full build, mismatches were measured on 5 of the 6 observed handoffs — and the verdict was zero: benign drift that glues after local re-labeling. Nonzero stood only on the triangle. A flood of findings versus one structural point: in the age of review fatigue, that difference is the practical value.

• Zero as a statement, and reproducibility. An LLM cannot assert "no problems found" with a warranty, and its findings shift run to run (our own two independent passes agreed mechanically on only 9.4% of raw observations — see §8). The measurement returns the same verdict from the same input, with provenance traceable to the sources.

• Pre-verification of repairs. Both can propose fixes. Only the measurement can decide, before implementation, "this repair glues".

The cost structure differs too. Whole-codebase review loads the entire codebase into context at every review: you pay O(codebase) every time, and both token cost and misses grow with size.

Building the ArchMap is paid once, and a lightweight model sufficed. Afterwards only diffs need updating (the reproducibility engineering that underwrites this is in progress — §8), and the obstruction computation itself runs on the Rust side at effectively no cost. Pay O(codebase) once, then O(diff). The bigger and longer-lived the codebase, the wider the gap.

So the true relationship is division of labor, not rivalry. The LLM does local observation (reading per-file facts — the shape LLMs are good at); the mathematics does globalization (gluing observations and computing obstructions on loops — the shape that collapses if you lean on long-context attention). ArchSig is best described as an apparatus that gives LLM observations a mathematical spine.

The grounding = measured_zero result is itself the demonstration: within what per-service review can see, everything was lawful. The obstruction lived outside the unit of review, on the overlaps.

One more fair question: "couldn't type systems or static analysis catch it?"

This is where the difference in kind shows most clearly. In this triangle, the price order stores and the refund cancel returns are both typed String. To a type system or a static analyzer, they look identical. What disagreed was not the types but the semantic conventions: "this string is an unparsed money amount" versus "this string is an already-rounded refund". The obstruction lived where neither syntax nor types can see.

This is why ArchSig's input is not an AST or type information but Atoms — typed minimal observed facts abstracted away from code and language. Atoms treat structural facts (dependencies, calls) and semantic facts (conventions, responsibilities, state, authority) as the same basic unit. Observing a money convention is the job of a semantic atom: an analysis outside the vocabulary of static analysis.

Putting Atoms in the middle has one more consequence: independence from language and framework. The one-cent demo is Rust; train-ticket is Java; the instrument, the law vocabulary, and the diagnostic staircase are exactly the same. For polyglot systems — which microservices usually are — one map suffices.

7. What this report does not claim

Per series custom, the section for not saying what cannot be said.

• The instrument did not find this on its own. The raw mismatch was captured by the bottom stair, and "which handoffs the discrepancy appears on" is observation data I supplied after reading the sources. The staircase's contribution is not discovery but the diagnostic procedure: certifying that each service is lawful, certifying that the discrepancy survives the loop, verifying the repair in advance, stopping CI — as one machine-decided chain.

• The repair is not implemented. PASS states a pre-verification result — "this fix would restore consistency" — not that fixed code exists.

• No damage figure was measured. That the rounding remainder is booked nowhere is certain from the code; how much and how often it actually drifts requires running the system. Not quoting numbers we did not measure is also part of the discipline.

• No criticism of train-ticket is intended. It is a research benchmark, not a production system. Read this as an observation that an everyday mix of coding styles realizes the theorem's hypotheses — which also suggests the structure is not rare in real code.

8. The sea beyond the cape: a chart of the headroom

Incidentally, the Cape of Good Hope was first named the Cape of Storms by its discoverer, Dias, and later renamed for the hope of the route. Discovery sites being unglamorous is apparently a tradition. And from the cape to the opening of the India route took ten more years; the hardest part lay beyond the cape, where crossing the Indian Ocean demanded techniques coastal navigation could not provide.

This research stands at the same point. The route exists; what lies ahead is not theory but supply engineering. The headroom comes in three parts.

First, reproducibility of observation. This is ArchMap's lifeline. When two independent LLM passes read the same code, only 9.4% of raw observations matched mechanically. The breakdown matters: of 2,819 adjudicated disagreements (full source re-reads by subagents), only 29 were rejected as wrong. Correctness reproduced; what diverged was mostly naming (about nine tenths), then granularity, plus observations only one pass caught. With convergence conventions for naming, granularity, and notation plus a normalized matching key, re-extraction experiments raised key convergence from 0.32 to 0.74. The target is 0.8. Until then, the heavy safety net of dual passes plus full adjudication guarantees quality; once reached, the diff-update economics of §6 kick in properly. I will keep reporting these numbers as they move.

Second, abstraction of supply. To satisfy SAGA's supply contract this time, I read the evaluator's source code. That is not a procedure real users can be asked to follow. The goal is to give SAGA supply the same abstraction ArchMap supply already has — point at the loop you want repaired, and the required observations assemble.

Third, the next measurements. Runtime measurement to speak about damage (money-weighted analysis), and a second and third external OSS.

The flag is planted on the cape. "Locally correct, globally broken" is observed — as a measurement — in a real OSS codebase. The mathematics grown from axioms, as the previous article ended, connects to the sea of real code.

References

• Repository: AlgebraicArchitectureTheoryV2 (MIT license)

• The one-cent demo (synthetic, reproducible): tools/archsig/examples/practical-rust-service/

• Target codebase: FudanSELab/train-ticket (commit 313886e9)

And here is the other daily experience: no matter how much you invest in tests and CI/CD, end-to-end failures still happen. Every unit test passes. Integration tests pass. CI is green. Production breaks anyway.

I have come to believe this is not a problem of test coverage or pipeline speed. It is a problem of software engineering itself not having caught up — and this article is the record of a climb that begins with that diagnosis: one summit reached (the SAGA theorem), the view seen from it, and the mountains still ahead.

For first-time readers, here is a map of the names that appear in this article:

I wrote about the SAGA Theorem in this article.

The SAGA Theorem: The Day Software Architecture Became Genuine Algebraic Geometry

One promise up front: this article contains three kinds of statements — things that are proved, things that are vision, and things that are unproven. I will keep them separate. Not claiming unproven things as results is the core discipline of this project, and this article follows it.

The foothills — E2E failures have a mathematical name

Start with the diagnosis.

What tests and CI guarantee is local correctness. A unit test verifies one cross-section of one module. Even an integration test only verifies a finite, chosen set of paths.

But E2E failures have a very specific shape: every part is correct, and the whole breaks anyway. Fragments that are locally consistent fail to fit together globally.

Mathematics — sheaf theory in particular — has a precise name for this situation: all local sections exist, but no global section does. And it has a tool that counts the obstructions to gluing: cohomology, starting with H^1.

The phenomenon we call "all tests green, production on fire" — the thing the industry has named integration hell and fought with folklore — turns out to have an exact mathematical name. The crucial point is that the obstruction does not live in any single part. It lives on the overlaps between parts: implicit interface assumptions, shared state, temporal ordering. None of these exist inside a single module. That is why 100% test coverage does not remove them. As long as what you measure is local, you cannot reach them — not in practice, but in principle.

Classical software engineering is built on an unstated composition principle: improve the quality of the parts, and the quality of the whole improves. The gluing problem says precisely that this composition is not automatic. The sum of the local is not the global.

Why AI-driven development makes this worse

It is no accident that AI-driven development is aggravating the problem.

AI is extraordinarily good at local generation, and each generated fragment is individually correct. The faster generation gets, the faster inconsistencies accumulate on the overlaps.

Here is the thing worth noticing: what human review was actually doing was never primarily "checking that the code is correct." It was mentally re-deriving the gluing — "does this change still fit the assumptions of that other module?" That invisible computation is what can no longer keep up.

There are, in principle, exactly two ways to close the gap:

1. Make the reviewer an AI too.

2. Make review a matter of decidable mathematics.

The first inherits an infinite regress — who watches the watchers? In a world where generated artifacts inspect generated artifacts, no agent's judgment carries more authority than any other agent's. I chose the second.

The Rising Sea — the method

Grothendieck approached hard problems in algebraic geometry not by cracking the shell with a hammer and chisel, but by raising the water level of abstraction until, one day, the shell was simply open. In his own words: la mer qui monte — the rising sea.

The history of software engineering has been a history of hammers. E2E breaks? Write more tests. Integration breaks? Make CI faster. Boundaries break? Add contract tests. Each tool is individually correct, and the problem persists — not because the tools are bad, but because the problem is stated at too low a level of abstraction. We have been attacking a local-versus-global problem with local tools.

My research program, AAT, is that raising of the water. Stop handling the underwater rocks — code, modules — directly, and rise to the level of atoms (the theory's axiomatic primitives), sheaves, covers, and gluing. At that altitude, "tests pass but production breaks" stops being an enemy to fight and becomes an ordinary object with coordinates: a class in H^1.

This raising of the water has a practical by-product, too. Because atoms are abstracted away from code, neither the theory nor the measurement depends on any particular language, framework, or library. A Rust microservice fleet and a legacy Java monolith are, given their observations, subject to the same theorems and the same obstructions. There is no rebuilding the tool for every ecosystem, the way linters and architecture tests must be rebuilt — and the theory does not age as technology stacks turn over. Abstraction, in this sense, is also portability.

The problem does not disappear. But it stops being a mystery. What is no longer a mystery can be measured. What can be measured becomes a job for tooling.

Lifted to the right level of generality, a hard problem is not so much solved as rendered trivial. That is the point of the rising sea, and it is the method of this project.

One difference from Grothendieck's own sea: his settled into thousands of pages of prose (EGA/SGA), and later generations struggled to keep the water level up. My sea has its level guaranteed by Lean, a proof assistant. As long as the theorems are formally verified, the water does not recede. The central theorem of this sea is named the SAGA theorem — an homage to Serre's GAGA, the landmark work that established the correspondence between algebraic and analytic geometry. As GAGA bridged two geometries, SAGA is a comparison theorem bridging architecture semantics and algebraic geometry — plus the one layer neither had: machine verification.

And one thing that must not be forgotten: the rising sea was never abstraction as escape. Grothendieck always kept a concrete problem — the Weil conjectures — at the center, as the thing to be submerged. This project has the same shape. The concrete pain of E2E breakage is the shell at the center, the thing the water is meant to close over. The abstraction exists not to leave reality behind, but to trivialize it.

So much for the method. The method is a sea — raise the water, submerge the problem. But the journey of the research itself resembles a climb more than a tide: which peaks have been reached, what could be seen from the summit, which peak comes next. What follows is the record of that ascent.

The ascent — a summit called SAGA (proven)

This section respects claim boundaries strictly. The following already stand.

• The AAT canon — the mathematical text of AAT as pure mathematics, axiomatized on atoms, written with no apologies to tooling or formalization: the mathematics speaks only its own language.

• The SAGA theorem — a comparison theorem: the H^1 grown on the architecture-semantics side coincides with the genuine Čech H^1 on the site generated by atoms. Proved in Lean 4. The ascent took 352 cycles of an automated AI research loop — 347 of them spent stacking impossibility theorems, walls that said this vocabulary cannot reach the summit. In the last 5 cycles, a shift of vocabulary — an architectural law is not a predicate but an equation — broke the bedrock.

• The Lean tower — under the discipline of "formalize only what can be honestly stated," definitions, theorems, and examples are stacked without sorry.

• ArchSig — a measurement tool written in Rust. It takes an observation of the architecture (ArchMap), the laws to uphold (LawPolicy), and an evidence contract, and its H^1 obstruction detection is operational. One design principle matters above all: it speaks only what the given contract lets it speak, and stays silent about everything else. It never completes, guesses, or extends its inputs.

• SFT (Software Field Theory) — the dynamical side. If AAT is statics (the consistency of an architecture at a moment), SFT describes how change propagates through software over time — and it, too, has begun producing theorems.

• The development process itself is the experiment — this repository is developed by AI agents implementing at speed, adversarial reviews and a Lean gate judging consistency, and a human holding only the questions and the acceptance criteria. In other words: AAT and ArchSig are themselves being developed in exactly the style of development they are meant to protect. That self-applicability is, I think, the first evidence that the theory survives contact with real development.

The view from the summit, 1 — a quiet future

From here on, vision. Two views seen from the summit of SAGA.

The first:

An engineer starts the day. She finishes a change and says, "analyze it with ArchSig." A few obstructions are detected. She fixes the code. An E2E failure has been prevented before it ever existed.

What deserves attention in this scene is its quietness. No categories, no sheaves, no cohomology appear in it. The engineer says "analyze," receives one word — obstruction — fixes the code, and moves on. Behaviorally it is indistinguishable from running a linter.

Engineers should never need to learn algebraic geometry — that has been a founding principle of this project, and it is the blueprint of this scene. The closer the theory gets to completion, the less visible it becomes. When the sea has risen far enough, all you can see is the surface.

There is a deeper shift hidden in that scene. The sentence "an E2E failure was prevented" is a counterfactual. A failure that never happened cannot be observed. Today's software engineering has, in principle, no vocabulary for prevented failures — which is why tests can only prove their worth after the fact, and why the quality of an architecture hangs in the air until an incident lands.

Only when obstructions are grounded in theorems does "without this fix, the gluing would have failed" become not folklore but a consequence. That quiet scene is a world in which counterfactuals have become mathematics.

The view from the summit, 2 — a fixed point for a society of agents

There is a more extreme future.

The engineer only watches from outside. Multiple AI agents coordinate dynamically and build software at ferocious speed. Mid-stream, an ArchSig alert fires — ArchSig sits at the deployment gate. The agents read its output and correct the code.

In that future, the code, the tests, the reviews, and the fixes are all AI-generated. Everything stands on the same shifting ground — and the only thing that does not shift is a gate grounded in theorems. Its verdict is nobody's opinion; it is the consequence of formally verified theorems on a chosen contract. In the vortex of high-speed generation, there is exactly one rock that does not move. Only things with that property belong at a deployment gate. ArchSig stops being a human's tool and becomes the fixed point of a society of agents.

In that future, the principle of staying silent about what cannot be said stops being a luxury and becomes a safety device. A human reader will charitably interpret a vague warning; an agent reads output literally and acts literally. A checker that emits "this looks suspicious somehow" will make an agent loop diverge. The discipline of silence turns out to be the interface specification of the multi-agent era.

So where do the humans go? "Watching from outside" means, precisely, moving to the legislature. Who writes the LawPolicy? Who decides which vocabulary may be spoken, and what deserves to be called SAFE? The agents are the executive; the verified gate is the judiciary; humans write the law. You may give up the hands that write code — you have not given up deciding what must be protected. If anything, that becomes the purified human job.

A future in which engineers only watch is not a future in which humans have exited. It is a future in which humans have finished building the grounds for trust.

There is an economic tailwind too. Verification is orders of magnitude cheaper than generation. ArchSig is deterministic computation — effectively free next to LLM inference; a Lean proof, once established, is cheap to re-check. The scarcer compute becomes, the less affordable "LLMs reviewing LLMs" gets, and the more the economics favor cheap deterministic gates that kill bad generations early. It is the same story as type systems paying for themselves when memory was scarce: resource constraints always raise the value of catching mistakes before execution. In the age of ferocious generation, the most expensive thing is discovering a mistake after you generated it.

The way down — the next theorem is literally called descent (unproven)

Mountaineers say the summit is only halfway: a climb is complete only when you are safely down. The ascent of SAGA, too, leaves a way down. And by an almost too-perfect coincidence, the first theorem on that route is literally called the descent theorem.

So that aspiration is never dressed up as achievement, here is what remains unproven:

• The descent theorem (the citadel) — under what conditions does local correctness imply global correctness? This would give, for the first time, explicit validity conditions for the composition principle software engineering has always believed and never proved. The detection direction (a global repair exists ⇒ the obstruction vanishes) is accumulating; the true descent direction (the obstruction vanishes ⇒ a global repair exists) is still open.

• H^2 and above — there is not yet a language for higher obstruction structure. The derived extension is deliberately deferred.

• Fidelity of the observation layer — ArchSig's verdicts can never be more trustworthy than ArchMap's fidelity to the real code. This is the engineering weak point, not the mathematical one, and the defensive line — purifying observation, keeping raw values, excluding judgment from the observation layer — is being built ahead of need.

• Validation on real codebases — H^1 detection finding, on a real project, a gluing failure that humans had missed. The truth of the theory is one question; the value of the tool is decided here.

What changes when descent is proved? ArchSig can turn it into a checkable condition: "this architecture satisfies the hypotheses of descent, therefore passing local tests implies global consistency." And conversely, exactly where the hypotheses fail is where E2E testing should concentrate — the theory gets to point. The view from the summit reaches the valley of the real world only once this way down has been safely walked.

Speaking only what can be spoken

Finally, let me be explicit about what this tool does not say.

What ArchSig can say goes exactly this far: "this change is safe within the given vocabulary and laws." It does not say "this change is good design" — because it cannot. Between the two, there is a deliberately drawn line of silence.

I consider this a condition of trust, not a weakness. A tool that judges beyond what it can judge will, somewhere, inevitably lie. A tool that judges only what it can judge never lies within that range. In an era when AI wants to talk about everything, a tool that speaks only what it can speak is rare — and only such tools belong at a deployment gate.

This article was written under the same discipline: a proven section, a vision section, an unproven section — never mixed.

Closing

Software engineering has not failed to catch up. The necessary mathematics simply had not been imported yet. This research program is that import — and not smuggling, either: it clears customs through Lean.

The open problems are real: descent, higher obstructions, fidelity of the observation layer, validation on real codebases. None of them is light. But the difference between an unclimbable mountain and a climbable one was never the altitude. It is whether you can draw the route.

The water is rising. And a sea, once it starts rising, rises fast.

It can be done. And this is not an unclimbable mountain.

References

• Repository: AlgebraicArchitectureTheoryV2 (MIT license)

• Website: AAT/SFT Research Notes

• Every module passes review, yet the system as a whole is broken. This "locally correct, globally inconsistent" phenomenon has a name in mathematics: cohomology, specifically H^1.

• AAT (Algebraic Architecture Theory) treats software architecture as a geometric object: generated from axiomatized facts called Atoms, cut out by laws, with obstructions appearing as cohomology classes.

• Within AAT, I proved in Lean 4 a theorem that I call the SAGA theorem (SAGA Grounding Theorem). It is a comparison theorem: the H^1 grown on the architecture-semantics side coincides with the genuine Čech H^1 of the site generated from Atoms.

• The proof took 352 cycles. For 347 of them, an automated AI loop accumulated impossibility theorems saying "this vocabulary cannot prove it" — until a single vocabulary shift, laws are equations, not predicates, broke the rock face in the final 5 cycles.

• This article starts from a minimal map of algebraic geometry, then explains what the SAGA theorem says and why it matters for computer science.

1. Locally correct, globally broken

You have probably seen this before.

• Every team's code satisfies its own review standards. Integrated, the system fails.

• Each microservice honors its contract. The system-wide invariant is still violated.

• Every refactoring step was safe. Stacked together, the original design intent is gone.

Linters, static analysis, and dependency graphs are good at finding local violations. But none of the situations above contain one. The problem lives not in any individual part but in how the parts are glued together.

Mathematics has studied exactly this phenomenon — locally consistent data that fails to glue globally — for the better part of a century. The theory of sheaves and cohomology. The obstruction to gluing a family of local data into global data appears as an element of a cohomology group called H^1. If the class is zero, the pieces glue. If it is nonzero, you are facing the kind of failure whose cause cannot be found by inspecting any single part.

AAT is a theory that takes this mathematics and runs it, seriously, on software architecture.

2. A minimal map of algebraic geometry for engineers

Before the main story, let me lay out the algebraic-geometry ideas this article relies on. Algebraic geometry is advanced mathematics, but to read this article you do not need rigorous definitions — just three ways of seeing, and a small glossary.

Way of seeing 1: equations and shapes are two faces of the same thing

In one sentence, algebraic geometry is the study of the shapes formed by solutions of equations, through the algebra of the equations themselves. The equation x² + y² = 1 and the circle in the plane are two faces of one object. Operations on the equation side correspond to operations on the shape side — this "algebra ⇄ geometry" dictionary is the heart of the subject.

Way of seeing 2: not "is it satisfied?" but "how is it imposed?"

As solution sets, x = 0 and x² = 0 are indistinguishable — both are "just the origin." But as equations they differ: x² = 0 carries the extra information of being "zero twice over." Modern algebraic geometry took off precisely by studying not the predicate-level information (satisfied / not satisfied) but the structural information of the equations themselves. In engineering terms: instead of only checking whether the tests pass, you carry around by what margin and for what reason they pass. This distinction becomes decisive later in the article.

Way of seeing 3: study locally, then glue

You cannot map the whole Earth onto one flat sheet, but you can make an atlas — a family of local maps. Algebraic geometry covers a shape with a family of local views, studies each view, and glues the results back into a global understanding. And sometimes everything works locally, yet the gluing fails. The tool that measures that failure is cohomology.

A small glossary

You do not need to memorize any of this. Keep the map at hand and read on. Now, the main story.

3. What is AAT? Architecture as relative geometry

The starting point of AAT (Algebraic Architecture Theory) is its choice of object. AAT does not study the raw codebase itself.

C : Codebase
V : AtomVocabulary   (which facts you choose to observe)
U : LawUniverse      (which laws you choose to impose)
J : CoverageTopology (how you cover the architecture with local views)
k : coefficient ring (what you measure obstructions in)

X_C^{V,U,J,k} : AAT geometry   (this is the object of the theory)

Instead of asking "is this codebase good?", AAT asks: given this observation vocabulary, these laws, and this way of covering the system with local views, what geometry arises? The vocabulary and the laws are explicit, and all mathematics is relative to them. This relativization is also where AAT's discipline of boundaries comes from — internally the project calls it "silence about what cannot be spoken": the theory does not make claims outside its declared inputs.

4. The Atom axioms — the minimal facts of architecture

The smallest unit of AAT is the Atom: a typed architectural fact that we choose not to decompose further. An Atom has five components:

a = (kind, axis, subject, predicate, payload)

• kind: what species of fact this is (component, relation, contract, semantic fact, ...)

• axis: which structural axis it concerns

• subject: what it is about

• predicate: what holds

• payload: the content — values, names, types, evidence

"Service A depends on service B." "This module owns the compensation logic for payments." "This API requires authentication." All of these are Atoms. Syntactic facts and semantic responsibilities live on the same footing.

Atoms are governed by an axiom system (A0–A8). The most important ones:

• A0 Primitive Existence: the type of Atoms exists; everything is generated from it.

• A2 Single Fact: one Atom states one fact. Compound claims are families (configurations) of Atoms.

• A3 Predicate Stability: Atom identity is determined by the five components.

• A4 Composition: finite families of Atoms generate configurations, from which architecture objects arise.

• A5 Law Non-Generation: laws do not generate Atoms. A law is a constraint over facts, never a source of facts.

A5 is quietly crucial. It separates "what should be" (laws) from "what was observed" (Atoms) at the axiom level, so wishful thinking can never leak into observation.

5. Making laws into equations — the algebraic-geometry dictionary

On top of Atom families we impose laws: "no dependency cycles," "every compensation handler must be paired," and so on.

Naively, a law is a predicate — it holds or it does not. And indeed, that is how AAT first defined laws, too.

But algebraic geometry discovered a better viewpoint 150 years ago: treat constraints not as predicates but as equations. This is where the glossary from Section 2 goes to work:

a set of equations        →  an ideal (the algebraic object the equations generate)
points satisfying them    →  the zero locus V(I) (the geometric object)
functions visible under
the constraints           →  the quotient ring O/I

The key point: a predicate (satisfied / not satisfied) cannot recover the equations. As Hilbert's Nullstellensatz made precise, the equation side (the ideal) carries strictly more structure than the solution set — multiplicities, infinitesimals, deformations. And that extra structure is exactly what you need to compute cohomology. No coefficients, no cohomology; predicates have no coefficients.

AAT transplants this dictionary to architecture:

a law                      →  the witness ideal I_L generated by its violation coordinates
the failure of all laws    →  the obstruction ideal I_Ob = Σ I_L
readings under the laws    →  the quotient O/I_Ob (the coefficients of the obstruction sheaf)
the law holds              ⟺  pulling the reading back kills the ideal (s*I_Ob = 0)

Note that the last line has exactly the shape of Hilbert's Nullstellensatz: the semantic fact "the law holds" becomes equivalent to the algebraic fact "the ideal vanishes." This is why AAT is algebraic geometry, not merely algebraic-geometry-flavored.

Then we add coverings. Cover the architecture with a family of contexts and observe locally in each. A Grothendieck topology is generated from the Atoms on the category of contexts, giving a site. Sheaves live on it, and Čech cohomology. The obstruction to gluing the local readings into a global one appears as a class in H^1.

6. Before SAGA — the lower floors of the tower

I have been turning this picture into Lean 4 theorems, one floor at a time.

• The finite descent theorem: a family of local repairs glues into a global repair exactly when a finite obstruction class vanishes. The first theorem ever attached to "local-pass / global-fail."

• The true H¹ theorem: that obstruction class is not an H^1 in name only, but a genuine quotient H^1 = Z^1/B^1 — cocycles modulo coboundaries.

At this point AAT was a theory that measures architectural gluing failures with H^1. But one fundamental weakness remained.

That H^1 was a purpose-built finite construction. The general theory of sites and sheaves was formalized in the very same repository — yet the semantic-repair H^1 stood next to it as a separately grafted tower. The claim "AAT is doing algebraic geometry" rested on "AAT owns a construction shaped like algebraic geometry." In principle, that is indistinguishable from calling any ad hoc finite quotient an H^1.

7. The SAGA theorem — two worlds coincide

This is the gap I set out to close — the goal that would later be named the SAGA theorem. In one sentence:

The semantic repair H^1, grown on the architecture-semantics side, is an instance of the general theory's Čech H^1 (the computable version relative to a chosen cover), on the site generated from Atoms, with coefficients generated from laws. The two zero-tests are equivalent.

The name honors Serre's GAGA (Géométrie Algébrique et Géométrie Analytique), the landmark comparison theorem showing that the cohomologies of two worlds — algebraic and analytic geometry — coincide. SAGA (Sémantique Architecturale, Géométrie Algébrique) is a comparison theorem in that tradition, for architectural semantics and algebraic geometry. And the name carries a second meaning: the proof was, quite literally, a saga.

With SAGA proved, the whole chain connects:

Atoms (axiomatized facts)
  → laws as equations (witness ideals)
  → obstruction coefficients as the quotient O/I_Ob
  → the site and covers generated from Atoms
  → the general theory's Čech H^1
  = the semantic repair H^1 (the one from the true H¹ theorem above)

AAT's cohomology grows out of AAT's own axioms. No grafting.

8. The story of the proof — 347 impossibility theorems and one decision

The proof of SAGA is a research record worth telling in its own right.

It ran for 352 cycles of what is now fashionably called loop engineering: an automated AI agent loop discharged small proof obligations in Lean, one per cycle. Every cycle passed adversarial audits designed to reject the classic cheat of formalization: smuggling a conclusion-equivalent premise into the assumptions. The design emphasis was not on making the loop run fast, but on auditing what the loop can legitimately claim to have proved.

Compression and blockade

The first hundred or so cycles built the comparison skeleton. Then, for roughly 250 cycles, something strange happened: instead of advancing, the loop began sealing off every detour, with counterexamples. "This input surface cannot prove it." "Adding this auxiliary data does not help either." Thirty-six families of impossibility boundaries accumulated as theorems, until the entire goal had been compressed into a single proposition. And in cycles 320–347, the loop proved that this one point was underivable, in principle, from the current vocabulary.

The cause was fundamental. Laws had been formalized as holds : Prop — an opaque predicate. Predicates do not determine equations. Cohomology does not grow where there are no coefficients. "Way of seeing 2" from Section 2, and the lesson of Section 5, had come back as a family of impossibility theorems in Lean.

Were those 347 cycles wasted? The opposite. The theory established the limits of its own vocabulary, as theorems, before extending it. The fix was narrowed from "somewhere" to "exactly here." There are not many formalization projects that have done this.

The vocabulary decision

At this point I made the call: laws are equations. That is precisely why AAT can become algebraic geometry.

Remarkably, the mathematics needed for the extension already existed in the repository. The AAT canon had contained the toolkit for treating laws as equations — violation coordinates, witness ideals, the lawful locus — all along; the formalization simply had not used it yet. The decision was not the invention of new mathematics; it was letting the formalization catch up with the editorial intent of the text.

Once the vocabulary changed, things moved fast. Generate the obstruction coefficients as the quotient by the ideal; generate each local reading as the quotient class of its defect. Then the proposition that had been sealed for 347 cycles — if the required laws hold locally, the restrictions of the readings agree on common refinements — fell as a theorem. Five cycles later, everything was in place: the comparison, the equivalence of zero-tests, and a concrete instance where a nonzero class demonstrably lives on both sides.

A review that produced theorems

The final act was the review. Just before completion, one of the four adversarial review lanes vetoed: "the H^1-zero part of this composed theorem is constructively trivial, and the law semantics only acts at cohomological degree 0 — the statement invites over-reading." The objection was correct.

The response was not to weaken the claim but to prove new theorems: a positive boundary theorem ("the law semantics contributes exactly degree-0 vanishing") and a negative one ("the higher conclusions hold independently of the laws"). The theory deepened its knowledge of itself through the review. The re-review lifted the veto, and the theorem was accepted.

9. Why this matters for computer science

This looks like a mathematics story, but SAGA has several CS implications.

(1) A class of analysis beyond linting. Detecting local violations (lint, static analysis, contract checking) and detecting global gluing failures are mathematically different classes of problems. Let us return to the three examples from the opening.

• "Every team's code passes review, yet integration breaks." Each team's area of ownership corresponds to a local view of the cover. Among the mismatches along team boundaries (the cocycle), the ones that no team can eliminate by fixing its own code — those read as a nonzero H^1 class. There was a structural reason the cause could never be found inside any single team.

• "Every microservice honors its contract, yet the system invariant is violated." Contracts correspond to local laws; the system-wide invariant corresponds to a global section. All services can be locally lawful while the global section gluing them together simply does not exist. That existence is exactly what H^1 decides.

• "Every refactoring step was safe, yet the design intent is gone." Each step corresponds to a local re-adjustment (a coboundary). But stack a full loop of re-adjustments, and a residue can survive that never cancels. In fact, the concrete nonzero-class instance used in the SAGA proof was literally a construction where going once around a circle leaves you off by 1. Every step safe, yet you return changed — that déjà vu now has a mathematical identity.

After SAGA, AAT owns, for this class of failures, an obstruction with a proved-sound detector: a nonzero H^1 class certifies which law fails over which observed facts, with traceability back to the displayed law support. It is a principled path toward detecting the failure mode where "no file contains a bug, and yet the system is broken."

(2) It matters most in the era of AI writing code at full speed. From day one, AAT's research goals carried a "rival" field: static analysis, dependency graphs, ADLs (architecture description languages), and AI code review with near-unlimited context — every cycle had to answer what AAT can produce that they cannot. The answer is this H^1. In an era where AI agents mass-produce pull requests, CI can run local checks — tests, lint, contract verification — at high speed. But an H^1-class failure appears in no diff and in no file. Every PR is green, every module is lawful, and yet the global section does not exist — this failure mode slips through diff-level and file-level checking in principle. ADLs can describe structure and conformance with great sophistication, but they have no machinery for proving semantic gluing failures as cohomology classes. Even an AI reviewer that reads the entire codebase can articulate unease, but it cannot pin the existence of the obstruction down as a theorem, backed by detector soundness and counterexamples. The faster code gets written, the faster gluing failures accumulate, silently. What can give this class of failure a theorem-level detector is a theory that treats the gluing itself as mathematics.

(3) A methodology for vocabulary evolution in formalization. Every large formalization eventually hits the "our original definitions were wrong" problem. The SAGA proof demonstrates one pattern: first pin down the limits of the old vocabulary as a family of impossibility theorems, so that the extension becomes a forced, minimal move — and afterwards, the old no-go theorems keep serving as audit machinery. Definition change becomes accretion, not restart.

(4) A working example of human–AI division of labor. 347 cycles of automated exploration and blockade by AI agents; one vocabulary decision made by me, the human in the loop; adversarial multi-agent review with a veto and a re-review. Remove any one of the three and this theorem does not exist in this form. As a template for doing mathematics with AI, the record is arguably as valuable as the theorem.

(5) Everything is machine-checked. Every theorem in this story — the comparison, the impossibility boundaries, the nonzero-class instance — compiles in Lean 4 and depends only on Lean's standard axioms (propext, Classical.choice, Quot.sound). There are no sorrys.

10. Honest boundaries — not everything, but enough to stand on

Finally, in keeping with AAT's own discipline, here is what the SAGA theorem does not claim. The bullet points are unavoidably technical, so each comes with a plain-language gloss.

• The theorem is relativized to finite or small sites, selected covers, and vocabularies equipped with an equational realization of their laws. No unconditional generalization to arbitrary Grothendieck sites is claimed.

  • In plain terms: the theorem holds for finitely many parts, an explicitly chosen decomposition, and laws you can write as equations. It does not claim to cover every infinitely complex situation mathematics can imagine.

• No unconditional identification of cover-relative Čech H^1 with full sheaf cohomology is claimed — in fact, "this cannot be said unconditionally" is itself a boundary theorem with a counterexample.

  • In plain terms: cohomology comes in a computable version relative to your chosen decomposition and a decomposition-independent theoretical version; SAGA works with the former. That the two cannot be unconditionally identified is itself pinned down as a theorem, with a counterexample.

• The completeness of extracting Atoms from a codebase, and "quality judgments about real code as a whole," are outside the theory. AAT does mathematics relative to observed Atoms and selected laws.

  • In plain terms: whether you extracted every fact from the code is the observation tool's job; mathematics does not guarantee it. What AAT guarantees is the correctness of everything downstream of the facts you gathered and the laws you imposed.

Is this boundary a weakness of the theory? I do not think so. Analyzing software architecture is an inherently finite activity: finitely many modules, finitely many observable facts, finitely many rules imposed in review. The "finite, explicitly-voiced" world in which the SAGA theorem holds is exactly the world architecture analysis actually lives in. It is not a theory of everything. But as a foothold for analyzing software architecture, it is more than wide enough.

Not saying what cannot be said. Making the boundary explicit is itself part of the theory.

11. Closing

Anyone can say "let's apply algebraic geometry to software architecture" as a metaphor. What the SAGA theorem did was stop it being a metaphor. From the Atom axioms, through laws as equations, obstruction coefficients as quotients, sites, sheaves, and up to H^1 — everything is connected by a single chain of machine-checked theorems.

That old phenomenon — locally correct, globally broken — now has mathematics that grows out of axioms.

References

• Repository: AlgebraicArchitectureTheoryV2 (MIT license)

• Proof record of the SAGA theorem: docs/note/aat_saga_theorem_proof_record.md

• The AAT mathematical canon: docs/aat/algebraic_geometric_theory/

• Research goal ledger: research/goals/G-aat-quality-surface-06.md; proof-state ledger: research/reports/G-aat-quality-surface-06.md (inside the repository, the SAGA theorem is tracked under the research-goal ID G-aat-quality-surface-06)

• Lean artifacts: research/lean/ResearchLean/AG/QualitySurface/ (for SAGA, see SemanticRepairCechGrounding.lean and SemanticRepairLawEquation*.lean)

TL;DR

In the AI era, architecture analysis cannot stop at reading code as files, functions, imports, and dependency graphs.

We need to observe the smallest units that carry architectural meaning. I call those units Atoms.

By extracting Atoms from a codebase and reading the algebraic structure they generate, we can analyze architecture beyond ordinary dependency relationships.

The workflow looks like this:

codebase
  -> Atom observations
  -> ArchMap
  + LawPolicy
  -> ArchSig analysis packet
  -> architecture reading

This lets us see design pressure, semantic coupling, missing evidence, and review focus that ordinary linting, static analysis, and dependency graphs often miss.

We built a new tool for this workflow: ArchSig.

The repository is public and MIT licensed, so you can try it on your own codebases.

The key idea is simple:

Architecture analysis does not need a bigger natural-language summary.

It needs the right unit of observation.

Why We Need an Architecture Analyzer

AI agents can write code fast.

But writing code fast is not the same thing as evolving a system well.

For an AI agent, the codebase is the largest prompt.

If the existing codebase contains shortcuts, those shortcuts become examples. If boundaries are vague, new code naturally lands in vague places. If responsibilities are mixed, that mixing becomes part of the next implementation context.

Traditional tools often look at the current shape of code:

• import graphs

• dependency cycles

• layer violations

• lint rules

• complexity metrics

• test coverage

• security rules

All of these matter.

But in AI-era architecture review, we often want to ask deeper questions.

Imagine a business backend where users select input data, run automated processing or generation, persist the result, receive events from external systems, run async jobs, call external providers, and save generated artifacts back into business state.

The important questions are not only:

Are the dependencies pointing in the right direction?

We also want to know:

• Who is allowed to use which input for which operation?

• Through which validation path does generated output become persisted state?

• Where is an external provider failure recorded as durable state?

• Do two workflows that produce the same artifact actually have the same effect order?

• Do entrypoint-level permissions match the intended business scope?

• Are privileged operations separated from ordinary workflow authority?

These are difficult to read from a dependency graph alone.

We need to read code not only as a collection of files and functions, but as a set of observations that carry architectural meaning.

That unit is the Atom.

Atom: The Smallest Unit of Architectural Meaning

An Atom is the smallest observation unit I want to use when reading architecture.

It is not necessarily a function, class, module, or file.

In practice, it is the thing you point at during review and say:

This is a boundary.

This is state.

This is an effect.

This is a contract.

This is where trust changes.

Examples of Atom families include:

• component atom: an architectural unit exists

• relation atom: two units or atoms are related

• capability atom: a unit provides a specific capability

• state atom: something is persisted or held as state

• effect atom: an external call or side effect occurs

• authority atom: someone is allowed to do something

• trust relation atom: some output or provider is trusted up to a boundary

• contract atom: inputs, outputs, preconditions, or failure behavior are promised

• semantic atom: something has architectural meaning beyond its code location

The important point is that an Atom is not small in the syntactic sense.

It is small in the architectural sense.

For example, the observation:

Only an authorized actor may update this resource.

may cross multiple files.

The observation:

Generated output must pass through a service-level contract before persistence.

may cross a route, service, validation layer, job state, and repository.

Still, each observation is one meaningful unit in architecture review.

That is what an Atom records.

A Small Code Example

Even a tiny function can contain multiple Atoms.

def publish_artifact(actor, artifact_id, repository, gateway):
    artifact = repository.load_for_actor(actor.id, artifact_id)
    gateway.publish(artifact.payload)
    artifact.mark_published()
    repository.save(artifact)

If we only say "this is one function," we miss most of the architectural content.

Read as Atoms, we can observe at least:

• component: repository and gateway are architectural units

• relation: the handler flows into both the repository and the gateway

• capability: the repository provides load/save, while the gateway provides publish

• state: the artifact's published state is persisted

• effect: gateway.publish changes external state

• authority: the actor must be allowed to publish this artifact

• trust_relation: the gateway response and failure behavior must be trusted only through a boundary

• contract: publish success, save failure, and retry behavior need explicit promises

• semantic: published is not only a flag; it means externally visible

These nine Atom schemas are the basic vocabulary for treating primitive architectural facts as generators of an architecture object.

ArchMap: Turning a Codebase into an Atom Map

An ArchMap is a map of these observations.

It is not a full copy of the codebase. It is not an AST dump. It is not only a dependency graph.

It is a source-grounded map of architectural observations.

source code
  observed as
Atom / Molecule / Semantic observations
  recorded as
ArchMap

If an Atom is one observation, a Molecule is a finite composition of Atoms that acts as one responsibility boundary.

For example, an ArchMap of a backend might contain Molecules such as:

• authenticated request boundary

• credential lifecycle

• repository transaction boundary

• interactive processing workflow

• input-to-artifact pipeline

• external integration ingress

• job-managed generation surface

• input-backed artifact boundary

• edge policy and observability boundary

• privileged governance boundary

The important point is not that the codebase has folders such as api, services, repositories, and models.

The important point is that architectural meaning sits on top of those folders:

• authority

• generation

• external effect

• durable state

• artifact lifecycle

• semantic contract

ArchMap records that meaning in a machine-readable form.

AAT: Reading Structure from an Atom Map

Once we have an ArchMap, we can ask a different kind of question:

Under which laws does this architecture object have pressure?

AAT, Algebraic Architecture Theory, reads software architecture as an algebraic structure generated from Atoms.

It studies architecture through objects, operations, laws, invariants, obstructions, and signature axes.

I will leave the detailed theory to Algebraic Architecture Theory.

For this article, the intuition is enough:

• law: a design property we want to preserve

• witness: observed evidence related to that property

• obstruction: a structure that blocks the law

• signature axis: the direction in which pressure appears

• operation: a design operation such as split, move, protect, or refactor

• path / homotopy: whether two change paths preserve the same structure

• curvature / holonomy: when something looks locally natural but becomes inconsistent around a loop

In ordinary review, engineers often process these ideas in their heads:

This responsibility is mixed.

This external call should not be inside the transaction.

These two job statuses look the same, but the failure paths differ.

This generated output must be validated before it becomes domain state.

AAT tries to move this review vocabulary toward something we can compute.

The important step is to treat Atoms not as labels, but as primitive facts that generate architecture objects.

Once Atoms carry relation, state, effect, contract, and semantic axes, we can see things a dependency graph cannot show:

• a locally natural change that changes effect order through another path

• a split that moves complexity to another boundary

• two workflows that look statically similar but differ under a semantic contract

These are non-trivial architecture readings.

They should not live only in a senior engineer's intuition.

They should be tied to a selected law universe and a selected set of witnesses.

That is the role of AAT.

ArchSig: Reading Structure from ArchMap + LawPolicy

ArchSig takes an ArchMap and a LawPolicy, then produces an AAT-style analysis packet.

ArchMap
  + LawPolicy
  -> ArchSig
  -> analysis packet

LawPolicy is the interpretation profile.

It selects the law universe, witness rules, signature axes, measurement policy, and coverage requirements for the analysis.

The same ArchMap can be read in different ways depending on what you care about:

• authority boundaries

• state/effect consistency

• generated output mediation

• domain cohesion

• permission coverage

• repair preconditions

ArchSig does not collapse all of this into one "good / bad" score.

It reports pressure and semantic coupling along different axes.

The output can include readings such as:

• nonzero pressure by law axis

• workflow risk

• transfer bridge pressure

• state/effect reconciliation pressure

• operation squares

• axis-wise monodromy defects

• architectural holes

• boundary holonomy

• repair precondition blockers

• review focus

This is not a code quality score.

It is a measurement surface for reading where design pressure and semantic coupling appear.

Case Study: Analyzing a Backend Repository

So far, the discussion has been conceptual.

Now let us look at the shape of one backend repository through ArchSig.

This repository has multiple users, authority boundaries, business data, external effects, async jobs, and generated outputs.

Users select input data and run analysis, generation, extraction, or transformation workflows. External systems send events. Async jobs call providers. Results are persisted as business artifacts.

From the ArchMap, ArchSig could read structures like:

• a backend split into API, service, repository, model, schema, and task layers

• authority boundaries across users, organizations, and resources

• a domain model where multiple artifacts derive from input data

• generated output mediated by service contracts and job state

• external provider effects paired with durable job state

• privileged operations separated from ordinary workflows

This is already different from a dependency graph.

ArchSig reads the repository as a business backend with authority boundaries, generated outputs, external effects, and durable state.

The Design Pressure It Found

The strongest pressure appeared at the intersection of authority and generation.

The system is not merely saying:

An authenticated actor can run generation.

The real architectural question is:

Who can use which resource as input, and which generated output can become which domain state?

That is a central boundary.

Reviewing only authorization is not enough. Reviewing only the generation job is not enough. The two boundaries are bridged.

The next large pressure was state/effect reconciliation.

The repository has external providers, async jobs, event handlers, retries, roundtrips, and compensation paths.

In this kind of system, not everything can live inside one transaction.

The architecture needs durable intermediate state, external effect recovery, explicit failure finalization, and retryable paths.

ArchSig reads this through the relation between state atoms and effect atoms.

The third pressure was generated output mediation.

Generated output is useful, but it should not become domain state without mediation.

You need input construction, structured output, filtering, validation, job failure handling, and persistence gates.

In this repository, the mediation appeared across multiple workflows:

• interactive workflows

• analysis execution

• content extraction

• generated artifact creation

So the design question is not:

Does the system use generation?

The real question is:

Through which contract does generated output pass before it becomes domain state?

This is not just dependency analysis.

It is a reading of where authority, state, effect, contract, and semantic meaning overlap.

Same Destination, Different Path

One of the most interesting ArchSig readings is the monodromy defect.

The intuition is:

Two paths may appear to arrive at the same place.

But do they preserve the same structure?

In the repository, several workflows looked similar from the outside.

They produced artifacts or updated state.

But the order of provider calls, repository commits, job state transitions, and status finalization could differ.

A dependency graph may not show that.

Even if the static dependencies point in the same direction, the workflow path can change failure behavior.

Does the system create state before calling the provider? Does it call the provider first? Where is failure finalized? Does retry use the same idempotency key?

ArchSig reads this kind of path difference as operation squares and axis-wise defects.

This is practical in review.

When someone says:

This follows the existing pattern.

ArchSig helps ask:

Does it really?

It may look like the same endpoint. It may create the same kind of artifact.

But if the effect order differs, the operational behavior differs.

That difference often becomes incident cost or future refactoring cost.

Architectural Holes: Loops That Do Not Close

Another important result was the architectural hole.

ArchSig found holes around paths such as:

• API -> service -> repository

• async provider jobs

• generated output -> domain state promotion

• semantic contracts

This does not mean "there is a bug."

It means the evidence is not enough to say the architectural loop is closed.

For example, the path from generated output to domain state may involve:

• input data

• context construction

• structured output

• validation

• job state

• repository persistence

To say this loop is closed, source reading alone is not enough.

You may need test evidence, runtime traces, provider logs, and entrypoint-by-entrypoint permission audits.

ArchSig does not treat missing evidence as zero.

It preserves it as a hole.

That matters because one of the dangerous failure modes in architecture review is to read "unknown" as "fine."

ArchSig keeps the gap visible.

And the gap becomes a review proposal.

gap:
  - permission evidence is incomplete
  - runtime trace is missing
  - provider failure path is not covered

review proposal:
  - human reviewer: check authority boundary and failure handling
  - LLM reviewer: compare the generated output path with the declared contract
  - test reviewer: add evidence for retry and finalization behavior

In other words, ArchSig does not hide uncertainty.

It turns uncertainty into review focus.

Spectral Analysis: Where Pressure Comes Back

One of the most interesting parts of ArchSig is ArchitectureSpectrumReport.

Ordinary review often ends with a list of issues.

But in architecture, pressure does not always appear once and disappear.

An authority mismatch can show up in generated output persistence. From there it can move into job state. Then it can come back through retry behavior or provider failure handling.

Spectral analysis reads this recurrence.

curvature support
  -> transfer edge
  -> recurrent mode
  -> hotspot / witness cluster
  -> review focus

Again, the point is not a single score.

The interesting questions are:

• Where does pressure concentrate?

• Which obstructions recur?

• Which witness clusters cross multiple law axes?

• Which coverage gaps block a zero reading?

• Which boundary should be reviewed before a repair candidate is trusted?

From a dependency graph, a workflow may look cleanly separated.

But spectral analysis may show remaining transfer between effect order, semantic contract, job state, and authority boundary.

That is not simply "there is a cycle."

It is a more structural reading:

Locally separate pressures return to the same support inside the architecture object.

ArchSig can surface that as a hotspot.

Repair Candidates Are Not Automatic Fixes

ArchSig can also produce repair candidates.

In this repository, many candidates were stopped by precondition blockers.

That is important.

Seeing pressure does not mean the system should immediately be split or rewritten.

If you cut one boundary, complexity may move somewhere else. Fixing authority may increase runtime effect pressure. Strengthening generated output mediation may change job state and retry paths.

ArchSig does not treat repair as an automatic safe edit.

It checks preconditions, witnesses, coverage, and transfer risk.

This is close to how experienced engineers review architecture:

This looks risky.

But before fixing it, we need this evidence.

That difference matters.

How This Differs from Existing Tools

So what exactly is different?

Existing tools are good at reading the current shape of code:

• Does a dependency cycle exist?

• Is there a layer violation?

• Is test coverage missing?

• Is a security rule violated?

• Is complexity too high?

ArchSig is trying to read something else:

• Where are responsibility boundaries composed?

• On which law axis does pressure appear?

• Do two paths with the same destination preserve the same effect order?

• Where do generated output, external providers, authority, and durable state intersect?

• Would a repair candidate move complexity to another boundary?

• Which evidence is missing, and therefore should become review focus?

This is not a code quality metric.

It is an instrument for reading architectural state.

Another important point is that review can happen around the ArchMap artifact.

The source-grounded observation still has to be produced from real code.

But after that, sharing, reviewing, and comparing can happen around ArchMap and the analysis packet.

That matters for teams and companies that cannot freely share full codebases.

There is also an AI angle.

If you simply ask an LLM to review a large codebase, the full context will not fit.

Even if it does fit, it is hard to make the model consistently focus on:

• the right boundary

• the missing evidence

• the relevant law axis

• the path where effect order differs

ArchMap and ArchSig change the shape of the context.

Instead of handing the model all code and asking for a huge summary, you hand it Atoms, Molecules, law axes, holes, and review focus.

Then the model can reason around the architecture boundary that actually matters.

Atom Is All You Need

Trying to understand a large codebase all at once breaks down quickly.

There are too many files. Too many functions. Too many dependencies. Too many external providers. Too much code added by fast AI agents.

So start with Atoms.

component
relation
capability
state
effect
authority
trust_relation
contract
semantic

Observe them. Record them as an ArchMap. Choose a LawPolicy. Run ArchSig.

This lets us read meaningful architecture boundaries without pretending we can understand the entire codebase at once.

What AI-era architecture analysis needs is not a larger natural-language summary.

It needs the right unit of observation.

Atom is all you need.

The Review Experience This Enables

Future review could look like this.

First, generate an ArchMap delta from a codebase or pull request.

Then run ArchSig using the team's selected LawPolicy.

The reviewer no longer has to read the entire diff as a flat pile of changes.

They can focus on the boundaries that require design judgment.

This change touches:
  - authority boundary
  - generated output mediation
  - state/effect reconciliation
  - async provider job path

Measured pressure:
  - nonzero on permission coverage axis
  - positive path continuation defect on effect axis
  - architectural hole on output promotion path

Review focus:
  - entrypoint-level permission evidence
  - job finalization behavior
  - provider failure handling
  - persistence gate before domain promotion

AI agents can read the same packet.

They can implement with more than a request like:

Just add the feature.

They can receive architectural constraints:

Preserve this Atom.

Do not cross this boundary.

Do not increase pressure on this law axis.

Do not treat these paths as equivalent; their effect order differs.

That matters because AI agents are strongly shaped by context.

If you give them only the codebase, you also give them every existing shortcut.

If you give them the ArchMap and the ArchSig analysis packet, you also give them the architecture's structural pressure and semantic coupling.

Closing

ArchSig is not a tool for grading code.

It is an architecture analyzer for reading a codebase as an Atom map, then using AAT to surface design pressure, semantic coupling, holes, and repair preconditions.

It does not replace dependency graphs, lint, coverage, or security tools.

Those are still important.

But there are questions they do not answer:

• Where do authority and generated output intersect?

• Where does state/effect order diverge?

• Are two paths that create the same artifact really the same architecture operation?

• Would this repair candidate transfer complexity to another boundary?

Those are the questions ArchSig is built to make visible.

Start from Atoms. Record them in ArchMap. Read them through AAT. Analyze them with ArchSig.

That is the architecture analysis shape I wanted to introduce.

What Comes Next: SFT and FieldSig

We are also working on the next layer of this research.

AAT makes software architecture locally algebraic.

ArchSig becomes an observation instrument for that local algebra: it takes Atom observations and law-relative structure from a codebase and turns them into an analysis packet.

Beyond that is SFT, Software Field Theory.

SFT is about software evolution.

It does not only ask about the current architecture state.

It asks how review, AI agents, CI, operational feedback, and organizational decisions change the space of possible future software states.

FieldSig is the next measurement surface.

It reads ArchSig analysis packets and workflow evidence in order to make software evolution more computable.

ArchSig is the entrance.

That said, ArchSig is still at v0.3.1.

I do not want it to be judged as a finished product yet.

I want people to try it on many different repositories and tell us what it reads well, what it misses, and where the model feels wrong.

Good reads and bad reads are both valuable for the research.

You can get the ArchSig release bundles here:

AlgebraicArchitectureTheoryV2 Releases

TL;DR

This article starts from the ForecastCone in Software Field Theory (SFT), then reads modularity, technical debt, review, governance, and learning as parts of one research program.

The goal is simple to state:

Make it possible to see what futures a change opens, close dangerous futures early, and shape the development environment so good futures become easier to reach.

If this theorem-shaped program works, architecture, technical debt, review, governance, and AI coding safety can all be reread around the same object: the ForecastCone.

We are also formalizing this direction in Lean by breaking concepts such as ForecastCone and ConsequenceEnvelope into small records and theorem packages.

For the Bigger AAT / SFT Picture

I introduced the broader AAT / SFT framing here:

• Software Architecture as a Field: Asking Better Questions About Software Evolution

• Algebraic Architecture Theory

• Software Field Theory

The Problem: Fast Code Is Not the Same as Healthy Evolution

For an AI agent, the codebase itself is the largest prompt.

If the existing code contains many shortcuts, the agent can easily learn those patterns. If boundaries are vague, the agent will naturally add the next change in the vague place. A good structure attracts good changes. A bad structure repeatedly makes bad shortcuts look natural.

PRDs, issues, review policies, and CI rules do not only decide "this change." They shape what the next PR tends to look like, which modules feel natural to touch, which boundaries are easy to miss, and which shortcuts are likely to pass.

In vibe coding, for example, an AI agent can quickly produce a plausible implementation from an underspecified PRD.

A PRD that only says "make coupons usable" may turn into a small if inside the checkout flow. The first demo works. But if that change leaves pricing policy, refunds, usage limits, and audit logs as vague boundaries, the next PR will often build on the same shortcut.

The problem is not that AI writes bad code. The problem is that vague artifacts plus fast generation can open bad future paths very quickly. A bad field can be amplified by AI into larger technical debt.

Traditional review, CI, and metrics often look at the current diff or at outcomes that already happened. In the AI era, that is not enough.

The question is no longer only:

Does this PR pass right now?

The deeper question is:

What future does this PRD, this agent, this codebase, and this review rule open next?

SFT needs ForecastCone in order to ask that question. It gives us an object for making software evolution computable, not as a mere sequence of changes, but as a space of reachable futures.

The Grand Theorem: A Fundamental Theorem of Software Evolution

Modularity
  = ForecastCone descent

Technical debt
  = descent obstruction

Review
  = minimal decision-preserving envelope

Governance
  = desired-cone-preserving obstruction cutting

Learning
  = closed-loop boundary-explicit fixed point

In this article, I will call this theorem-shaped picture the Fundamental Theorem of Software Evolution.

In everyday engineering language, it says something like this:

A good architecture boundary lets teams and AI agents work separately, then combine their changes safely later.

Technical debt is the ability to explain, with a concrete cause, why integration keeps breaking at the same place.

In review, we do not want every diff line or every possible future. We want the dangerous futures that matter for the decision.

Governance should not just add rules that stop development. It should close bad shortcuts and make good implementation paths easier to choose.

Learning means using actual PRs, incidents, and review outcomes to update the next forecast and the next rule.

In more mathematical language:

A good architecture boundary is not merely a static dependency cut. It is a boundary across which future evolution paths can be computed locally and glued into a global future under compatibility conditions.

Technical debt is an obstruction that appears when that gluing fails.

Review is not the act of seeing the entire ForecastCone. It is the act of seeing an envelope that preserves the distinctions needed for a decision.

Governance is a support transformation that removes bad futures while preserving desired futures.

Learning is a closed-loop update that moves a field estimate toward a boundary-explicit fixed point using PRs, incidents, reviews, and operational outcomes.

If such a theorem can be proved, the way we reason about software evolution changes.

Whether an architecture is good, where technical debt sits, what a reviewer needs to see, which governance rule is effective, and how the field model should be updated next can be studied over the same computational object.

That object is the ForecastCone.

ForecastCone: The Range of Reachable Futures

SFT reads the development environment as a field.

codebase
  + artifacts
  + practices
  + agents
  + governance
  + feedback
  -> reachable software futures

The range of futures reachable under that field is what SFT calls a ForecastCone.

A ForecastCone is not a prophecy.

SFT does not say:

This PRD will definitely produce this PR.

Instead, it asks:

Under this field model, operation support, policy, observation boundary, and horizon, which future paths are reachable?

Imagine an e-commerce service receives a PRD: "Add limited-time coupons."

That PRD does not open just one future.

• One future adds a small branch to the checkout flow.

• One future adds a discount policy to the pricing service.

• One future introduces an independent coupon domain.

• One future expands into campaign rules and audit logs.

• One future adds a database column for now and leaves cleanup for later.

All of these are, in some sense, "coupon support." But they open very different next futures.

The ForecastCone is the object that lets us look at that difference. The same PRD can make different futures easy or hard to reach depending on the current codebase, module boundaries, past workarounds, review rules, CI, and AI agent behavior.

Modularity = ForecastCone Descent

Modularity
  = ForecastCone descent

The intuition is:

The global future of a software system can be computed by gluing compatible local futures.

Traditional modularity is often described in terms of APIs, dependency direction, and responsibility separation. SOLID, Layered Architecture, Clean Architecture, and Design Patterns have often been used as ways to help humans understand responsibilities, localize change, and control dependencies.

SFT extends that line of thought by asking:

Do the futures glue?

If a boundary is truly modular, we should be able to reason about the future of Pricing and the future of Checkout locally, then glue them into one checkout future under the right compatibility conditions.

The boundary is not just a line. It is a place where future evolution should cross without breaking.

In practice, following SOLID and Layered Architecture already gets us a lot of the way toward this kind of modularity.

Technical Debt = Descent Obstruction

Technical debt
  = descent obstruction

The intuition is that technical debt can be read as a failure of futures to glue.

local tests pass. local reviews pass. the AI proposal looks reasonable. then integration breaks.

SFT does not want to stop at "the design is bad." It wants to record the failure as an obstruction.

DescentFailure:
  missing interface invariant

Witness:
  Pricing returns a discounted total,
  but Checkout treats it as a tax-included final charge.

Now technical debt is no longer just a feeling.

Each team-local change looks reasonable, but the whole system cannot combine them into a valid global future. The reason is that the boundary rule that should have been preserved was never defined.

That is the role of the Descent Obstruction Theorem.

Review = Minimal Decision-Preserving Envelope

Review
  = minimal decision-preserving envelope

A ForecastCone can be large. A reviewer cannot look at every future path. But a diff alone is often too small.

Suppose an AI agent produces a PR like this:

if coupon_code.present?
  total = total - discount
end

The diff is small. But the reviewer does not only care about these three lines.

Will this add an unobserved branch to the refund path? Will usage limits collide with retry behavior? Is the tax boundary between Pricing and Checkout still undefined?

What we need is not the whole ForecastCone, but the part needed for a review decision. SFT calls this a ConsequenceEnvelope.

The goal for review tooling is not to show everything. It is to show the future-relevant differences needed for the decision, no more and no less.

Governance = Desired-Cone-Preserving Obstruction Cutting

Governance
  = desired-cone-preserving obstruction cutting

When a risky future appears, the simplest response is to add another rule.

Anything coupon-related must be reviewed by a senior engineer.

That is a guardrail. But it is often heavy, and it may not say what future it is actually closing.

The kind of governance SFT wants is more specific: close bad futures while preserving desired ones.

• Introduce separate DiscountedTotal and FinalCharge types across the Pricing / Checkout boundary.

• Make coupon usage updates idempotent.

• Require coupon invariant checks when touching the refund path.

• Guide AI agents away from ad hoc discount branches under checkout and toward policy objects.

We want to close the future where discount logic spreads across checkout. We still want to preserve the future where coupon policy can evolve independently.

That difference is what the Governance Synthesis Theorem is about. It is not just about adding guardrails. It is about shaping the field.

Learning = Closed-Loop Boundary-Explicit Fixed Point

Learning
  = closed-loop boundary-explicit fixed point

SFT is not a theory where we compute one ForecastCone and stop.

Predicted future paths are compared with actual PRs, incidents, review comments, CI failures, and runtime observations. When the forecast is wrong, that is not just a failure. It becomes evidence for updating the model.

• Was the field estimate too coarse?

• Was the observation boundary too narrow?

• Did the policy model fail to represent actual review behavior?

• Should the unknown remainder have been made explicit?

As this closed loop progresses, an SFT workbench becomes more than an analyzer. It becomes a system for continuously calibrating the field model of software evolution.

Attractor Engineering and ArchSig

This grand theorem becomes practical only when it connects to AAT and ArchSig.

AAT gives us a local theory for reading what a change preserves and what it breaks. ArchSig gives us a signature layer for observing preservation and breakage from repositories, PRs, reviews, CI, and incidents. SFT uses those observations to compute reachable futures and connect them to governance and learning.

AAT
  -> local laws / invariants / obstruction witnesses

ArchSig
  -> observed signatures / measured axes / evidence boundaries

SFT
  -> ForecastCone / ConsequenceEnvelope / governance update

Attractor Engineering fits here as well.

A good architecture attracts good changes. A bad architecture repeatedly makes the same shortcut look natural.

In SFT language, this means the shape of reachable futures changes. Governance interventions close bad future paths, type boundaries make good local evolution more natural, and review rules make risky paths observable.

Attractor Engineering is the practice of shaping the ForecastCone. ArchSig is a tool for observing that change. SFT connects those observations back to the theorem family.

A Sketch of a Future Development Workflow

SFT is not trying to build a system that decides the future instead of developers. It is trying to make a development environment where developers, AI agents, reviews, and CI can see the future opened by a change on the same map.

An ambiguous PRD arrives. An AI agent quickly proposes an implementation. At the same time, a workbench sketches the futures that change seems to open and shows only the differences needed for review.

PRD
  -> implementation candidates
  -> reachable future range
  -> review-relevant differences
  -> review / CI / governance
  -> observed outcome
  -> next forecast update

Before reading every line of the diff, the reviewer sees which futures look risky. CI checks not only whether tests pass, but whether a risk we wanted to close is still present. The AI agent prioritizes implementation candidates that open better futures instead of copying the nearest shortcut.

Actual PRs, incidents, and review comments then become evidence for the next forecast.

That is the development workflow SFT is aiming toward.

Impact on Computer Science and Software Engineering

Lehman raised a core question of software evolution: long-lived software keeps changing as it adapts to its environment, and that change tends to increase complexity.

SFT revisits that question in the age of AI-assisted development.

Software engineering has long developed design and architecture theory around human cognition.

That makes sense. Software is complex, and if humans cannot read it, they cannot maintain it. So we developed ideas such as separation of concerns, information hiding, cohesion, coupling, layering, Clean Architecture, and bounded contexts to make complexity manageable for people.

That axis remains important.

But once AI coding agents enter the loop, the bottleneck shifts. When code can be produced faster, the question is no longer only:

Can humans understand the current structure?

The next question is:

What futures does this structure make reachable?

A good design is not only one that makes the current code easier to read. It is also one that makes good futures easier to reach and bad futures harder to reach.

From this point of view, architecture expands from human comprehensibility to future reachability.

• Can this boundary glue future paths locally?

• Which direction does this PR make the next change more likely to take?

• Does this metric preserve distinctions that matter for future evolution?

• Does this review rule close bad futures while preserving good ones?

• Which gluing failure does this technical debt represent?

These questions already exist in practice. They are just scattered across experience, intuition, review comments, incident memory, and organizational culture.

SFT tries to move them toward computable theory.

If this direction works, software engineering moves from:

techniques for making complexity understandable to humans

toward:

a science for observing, computing, and governing software evolution

The central concepts begin to look different:

architecture
  -> shape of reachable futures

modularity
  -> descent of future paths

technical debt
  -> obstruction to future gluing

review
  -> minimal consequence envelope

metrics
  -> cone-conservative observations

governance
  -> support transformation

refactoring
  -> evolutionary invariance

AI coordination
  -> agentic confluence

lifecycle
  -> bifurcation of repair feasibility

Lean Formalization

We are also formalizing this research program in Lean.

The point is to keep SFT vocabulary from remaining only a metaphor.

Terms such as field, ForecastCone, ConsequenceEnvelope, and governance update are being broken into small objects that can become records, types, and theorem packages. The big research picture gradually becomes something we can touch formally.

Current formalization work includes:

SoftwareFieldEstimate
OperationSupport / StepRelation
ForecastCone / ClockedForecastCone
ConsequenceEnvelope
FieldUpdate

For example, ForecastCone is treated as a supported path within a finite horizon. ClockedForecastCone introduces a shared clock and idle / stutter steps for descent. ConsequenceEnvelope treats review output as a projection from a cone family.

The final grand theorem is also being assembled from components: descent, obstruction, review, governance, calibration, and agentic confluence. Under those explicit components, the Lean-side assembly has the shape:

computably governed
  or
typed boundary failure

This formalization makes SFT a research program where we can track what is a theorem, what belongs to modeling, and what remains on the tooling or empirical side.

Closing

ForecastCone is not a tool for predicting the future.

It is a way to make reachable software futures computable under explicit modeling boundaries, operation support, policies, observation boundaries, and horizons.

SFT's bet is that we can rebuild central software engineering concepts from there.

Architecture is not only the shape of present code.
It is the shape of reachable futures.

Architecture is not only the shape of the code we have now.

It is also the shape of the futures that codebase makes reachable.

But writing code faster is not the same as helping software evolve in a healthy way. The faster we stack up changes, the more important it becomes to ask what each change leaves behind in the codebase, and how it changes what can be changed next.

Traditional tooling usually looks at things that have already happened. Code state, PR diffs, test results, static dependencies, and runtime errors are all important objects of observation.

But in an era where AI coding agents can generate pull requests one after another, we need to ask one step further.

• What kinds of changes does this change make possible next?

• What kinds of pull requests does this PRD make more likely?

• What kinds of shortcuts does this review rule make expensive?

• What observation axes should this incident leave behind?

At that point, we are no longer interested only in the current state of software. We also want to reason about software evolution itself.

In this article, I introduce AAT, or Algebraic Architecture Theory, and SFT, or Software Field Theory, as theories for asking questions about software evolution. I will start by drawing a rough map of how AAT/SFT tries to look at software that keeps changing.

Software Keeps Changing

Software is not something that is completed and then slowly decays. It connects to the real world through use, and as that real world changes, the software continually drifts out of alignment.

Users, business processes, organizations, operations, regulations, libraries, and infrastructure all keep changing. Today, AI coding agents are also changing the development flow itself.

This view is not new. Lehman's laws of software evolution formalized the view that software connected to real-world problems, often called E-type software, requires continual adaptation as long as it is used. They also observed that evolving software tends to become more complex unless explicit work is done to control that complexity. And the process of evolution should not be seen as a mere sequence of changes, but as a multi-layered, multi-loop, multi-actor feedback system.

The important point here is not to jump immediately to a prescription. The answer is not simply "so we should refactor," or "so we should strengthen design review," or "so we should control AI more strictly."

The question after Lehman is a little deeper:

If software keeps changing,
what can we ask about that change?

AAT/SFT starts from this question.

Decomposing the Question of "Good Design"

In design discussions, we often encounter questions like these:

• Is this design good?

• Is this change safe?

• Should we accept this PR?

• Is this AI agent's proposal risky?

• Should we still repair this system, or should we migrate?

All of these are natural questions. But as they stand, they are too large.

• What does "good" mean we are preserving?

• What range of future changes does "safe" refer to?

• On which observation axis, and through which kind of failure, is something "risky"?

• When we say "we should migrate," which change paths are we closing, and which ones are we opening?

In AAT/SFT, we break the question down a little further.

• What object are we cutting out for analysis?

• What do we want to preserve?

• Which invariant failed?

• How is that failure observed?

• What kinds of changes does this change make more natural next?

This is not about turning design review into a checklist. It is about taking the judgments we already make implicitly in practice and reframing them as theoretical objects, so we can reason about changing software.

AAT (Algebraic Architecture Theory): Reading Changes Locally

AAT is a theory for reading software architecture locally.

Here, architecture is not treated as the entire codebase all at once. First, we cut out the object needed to answer the question at hand, and call it an ArchitectureObject.

We do not have to handle a huge codebase all at once. We can focus on one boundary, one dependency relation, one runtime interaction, or one semantic contract. What matters is making explicit what we chose as the object.

Next, for that object, we ask which property we want to preserve. This is called an Invariant.

What do we want to preserve? Dependency direction? A boundary? An abstraction? Substitutability? Runtime protection? Consistency of state transitions?

The phrase "good design" mixes together many such invariants. AAT separates them so that we can inspect them one by one.

If a property we wanted to preserve fails, we need evidence explaining that failure. This is called an Obstruction.

An obstruction is not just an error. It is structural evidence, a witness, showing why the property does not hold. Hidden dependencies, boundary crossings, abstraction leaks, mismatched operation orders that ought to commute, and runtime exposure can all be read as obstructions.

Finally, instead of collapsing those observations into a single score, we read them across multiple axes. This is the role of ArchitectureSignature.

In short, the AAT way of reading looks like this:

• Which object is this change operating on?

• Which invariant do we want to preserve?

• Which obstruction has appeared?

• On which signature axis does it appear?

• Within what boundary can we make that claim?

AAT does not reduce "architectural quality" to a single number. It decomposes design judgment into object, preserved property, violation, observation axis, and boundary.

What Does It Mean to See Architecture Algebraically?

Why call this algebraic?

In AAT, we do not only look at architecture as a static diagram. We treat it as an object that can be operated on. There is an architecture object, and there are operations such as split, replace, abstract, protect, migrate, and repair. We ask what those operations preserve, what they fail to preserve, and how they compose with other operations.

The object of interest has this shape:

object
  + operation
  + preservation
  + obstruction
  + composition

AAT is not merely evaluation. There is an object, there are operations, there is structure that is preserved, there are obstructions where preservation fails, and there are sequences of operations. To study that structure, AAT treats architecture algebraically.

For example, one change may preserve dependency direction. Another change may preserve an abstraction boundary.

• If we apply those two changes in sequence, does their preservation compose?

• Does an obstruction appear in the middle?

• If two change paths appear to reach the same result, do they have the same signature trajectory?

This is the kind of structure AAT wants to study.

What Do Design Principles Preserve?

From this point of view, familiar design principles in software engineering look a little different.

For example, SOLID is not an all-purpose design principle in AAT. It is better read mainly as a family of principles for preserving local contracts.

• SRP tries to preserve responsibility boundaries.

• OCP asks for extension without breaking existing contracts.

• LSP asks that an abstraction be observable in the same way regardless of which concrete implementation is substituted.

• ISP tries to separate unnecessary dependencies from interfaces.

• DIP tries to map dependencies on concrete details into dependencies on abstractions.

What SOLID mainly deals with are invariants such as local contracts, abstractions, substitutability, and interface separation.

Layered Architecture deals with a different layer. What Layered Architecture tries to preserve is not so much the responsibility of each individual class, but the dependency direction of the whole system.

• Is there a ranking between upper and lower layers, and do dependencies follow that direction?

• Are there dependencies that skip across layers?

• Are cycles being introduced?

• Is the system kept in a decomposable form?

In AAT terms, SOLID mainly handles invariants in the local contract layer, while Layered Architecture handles invariants in the global structure layer.

SOLID
  -> local contract / abstraction / substitutability

Layered Architecture
  -> dependency direction / ranking / acyclicity / decomposability

The advantage of this classification is that we do not have to treat design principles as competing single answers.

A system can follow SOLID and still fail to decompose cleanly as a whole. Conversely, Layered Architecture can be preserved while individual abstractions fail to be substitutable.

If the invariants they preserve are different, then their failure modes are different, and the signature axes we should observe are different as well.

• For Clean Architecture, we look at boundary preservation, inward dependencies, and abstraction consistency.

• For Event Sourcing, we look at replay, projection, and the relation between history and current state.

• For Circuit Breaker, we look at runtime protection and failure locality.

AAT does not rank design principles by asking which one is correct. It classifies which invariant family each principle carries, which obstructions it prevents, and which signature axes it appears on.

The Architecture Zero-Curvature Theorem: Connecting Good Design to Measurement

AAT takes this idea one step further and expresses it using the vocabulary of curvature.

Here, curvature means the obstruction that remains relative to a selected invariant. If there is a structure we want to preserve, and a witness that violates that structure remains, then there is curvature.

Intuitively, we can read it this way:

There is curvature
  = somewhere, the structure we wanted to preserve is violated

Curvature is zero
  = within the selected scope, no required obstruction witness remains

Up to this point, this is almost definitional. The important part comes next.

AAT is not trying to restate "good design is design without violations." Here, a law should be read as an explicit rule describing a property we want to preserve. The goal is to connect lawfulness with respect to selected laws to finitely observable obstruction witnesses and to the required axes of an ArchitectureSignature being zero.

lawfulness for the selected laws
  <-> no required obstruction witness
  <-> required signature axes are zero

AAT calls this connection the Architecture Zero-Curvature Theorem.

The point is that three layers become connected.

semantics:
  lawful under the selected law universe

witness:
  no required obstruction is finitely detected

measurement:
  required signature axes are observed as zero

In ordinary design reviews, phrases such as "the boundary is preserved," "responsibilities are separated," or "this is easy to extend" are often used ambiguously. The zero-curvature theorem offers a bridge: relative to which law, which witness, which observation, and which signature are we making that judgment?

Good design in AAT is not merely design that looks elegant. It is design where, within the selected laws, required obstruction witnesses are absent, and this can also be observed as zero on the signature axes.

The value of the theorem is not the slogan "if there are no violations, it is good." Its value is that it lets us move a design judgment between semantics, witnesses, and measurable signature axes.

SFT (Software Field Theory): Making Software Evolution Computable

If AAT asks, "What did this change preserve, and what did it fail to preserve?", SFT goes one step further and asks, "What kinds of changes does this change make more natural next?" On top of the local algebra built by AAT, SFT builds a framework for reasoning about software evolution.

AAT looks at the local structure of one change. It asks which object the change operates on, what it preserved, where obstructions remain, what can be said on which observation axes, and where those claims stop.

SFT looks at the field in which that change is placed. It asks how the change guides the next changes, which paths it makes cheaper, which paths it makes harder to see, which feedback remains as memory, and which futures become reachable.

In SFT, this whole context is called a field.

A field is not only the codebase. It includes requirements, design documents, PRDs, issues, review rules, CI, type checkers, runtime feedback, AI agent policies, and everything else that acts on the codebase. It determines which changes look natural, which changes become difficult, what becomes observable, and which feedback remains for the next judgment.

field
  = codebase
  + artifacts
  + practices
  + agents
  + governance
  + feedback

SFT is not a theory of the codebase alone. It is a theory of the whole development organization that writes requirements, designs systems, creates issues, opens PRs, reviews them, runs CI, and receives operational feedback.

Then what is a force?

In this article, I use force for the bundle of candidate updates that artifacts such as PRDs, specs, issues, AI proposals, and incident reports create in the field. A single PRD does not determine exactly one PR. But that PRD changes which issue decomposition feels natural, which PRs are likely to be created, and which architecture regions are likely to be touched.

force
  = candidate updates that an artifact gives to the field
  = changes in operation support / observation boundary / selection policy

Here, operation support means which operations are possible, natural, and low-cost. Observation boundary means what is visible and what is not. Selection policy means which choices are likely to pass through the process.

The field is the state. Force is artifact-mediated change. Future is the range of paths reachable from that field.

Even if two codebases have the same module graph, their next natural changes can differ if their fields differ. Past incidents, old workarounds, implicit ownership boundaries, and local patterns that an AI agent can easily mimic all change future operation support and selection policy.

What Does "Computation" Mean in SFT?

Computable here does not mean that we can predict the future of software as one exact outcome. It means that, under an explicit field model, operation support, observation boundary, and horizon, we can treat the range of reachable futures as a bounded problem.

For example, when an artifact enters a field, SFT views questions like the following as computational problems.

input:
  current field
  + artifact
  + operation support
  + observation axes
  + horizon

output:
  reachable path classes
  + affected architecture regions
  + changed signature axes
  + obstruction witness candidates
  + missing invariants / boundaries
  + review / CI recommendations

On the theoretical side, this set of reachable paths is called a ForecastCone. On the practical side, the readable report summarizing it is called a ConsequenceEnvelope.

The important point is that SFT does not claim, "this PRD will necessarily produce this PR." What SFT wants to see is which paths become closer in this field, which paths become farther away, and which obstructions become visible.

PRDs Shape Future PRs

The intuition of SFT is easier to grasp if we look at the flow from PRD to PR.

A PRD is not merely a requirements document. It is an artifact that partially shapes the form of future pull requests. Even for the same request, "add this feature," the PRs that become likely differ depending on whether the PRD states boundaries, responsibilities, and properties that should be observed. And in many cases, PRDs are written by people who do not directly write code, such as product managers, designers, and domain experts. Non-engineers also apply force to the codebase through artifacts.

PRD
  -> possible issue decomposition
  -> possible PR shapes
  -> possible architecture changes
  -> possible signature changes

In SFT, we ask what force this PRD applies to the codebase and what kind of ForecastCone it opens. But that cone does not represent one predetermined future. It is closer to the cone of uncertainty in a weather forecast: it represents the range of futures that may become reachable.

• What kinds of PRs are likely to emerge from this PRD?

• Which architecture regions are those PRs likely to affect?

• Which invariants might they preserve, and which obstructions might they create?

• Within the ForecastCone, which future paths become closer and which become farther away?

For this reason, SFT asks questions in the following form:

• Which ForecastCone opens in this field?

• Which paths become natural, and which paths move farther away?

• What is observable, and what remains unobserved?

In this sense, SFT is a theory that tries to treat software evolution as a computable object.

Conway's Law: Systems Reflect Organizational Communication Structures

Conway's Law can be read naturally in the vocabulary of SFT. As is well known, Conway's Law is usually described as the empirical rule that the design of a system reflects the communication structure of the organization that built it.

In SFT, we read this not merely as a metaphor, but as a phenomenon where an organization field shapes the architecture future.

The organizational structure does not directly command the codebase to have a particular architecture. But team boundaries, ownership, review routes, approval flows, on-call boundaries, and issue decomposition all change which modifications look natural, which PRs are low-cost, and which changes are likely to pass review.

organization structure
  -> communication paths
  -> ownership boundaries
  -> issue decomposition
  -> PR shape
  -> operation support
  -> architecture future

Organizational structure changes operation support, and operation support changes day-to-day design changes. Through repetition, that pattern settles into the codebase as architecture.

For example, if an organization is split into Frontend Team, Backend Team, Data Team, and Infra Team, issues and PRs are likely to follow those boundaries. As a result, the architecture is also likely to split along those boundaries. On the other hand, if the organization is structured around product capabilities such as Search, Checkout, and Billing, changes that preserve those capability boundaries become more natural.

In SFT terms, Conway's Law can be read as follows:

organization field
  -> recurrent PR shape
  -> recurrent architecture operation
  -> architecture structure

If we want a desirable architecture to become a natural future, we need to design the organization field so that changes preserving that architecture are low-cost and repeatable.

Conway's Law is not a story about system structure accidentally resembling organization structure. It is a story about organizations shaping the ease of day-to-day changes, and the repetition of those changes settling into architecture.

ArchSig: A Lens for Observation

To connect AAT/SFT to real development, we need an observation layer. ArchSig is the concept for that layer.

• AAT turns architecture into a local algebra.

• ArchSig makes architecture observable.

• SFT makes software evolution computable.

ArchSig is a lens for reading artifacts such as codebases, PRs, issues, reviews, and incident traces. It asks which signature axes changed, which obstructions appeared, and what becomes input to the next field update.

I plan to discuss ArchSig in a separate article. For now, I only want to emphasize that AAT/SFT is meant to connect to observation and tooling.

Attractor Engineering: Designing Fields Where Good Changes Become Natural

One especially important idea in SFT is attractor engineering.

Here, an attractor is a direction of change that becomes repeatedly likely within a field. Good design decisions, good abstractions, good tests, good review rules, and good PRDs make it easier for the next good change to follow. Conversely, easy shortcuts, ambiguous responsibilities, broken boundaries, and invisible runtime coupling make the next easy shortcut more likely.

A codebase has a bias in how it is likely to be changed next. SFT treats that bias as a property of the field.

Attractor engineering means designing that bias.

Arrange the field so that good changes are:

• easy to find,

• easy to write,

• easy to review,

• protected by CI,

• and updated by operational feedback.

This is somewhat different from the idea of simply placing strong restrictions on AI agents. Of course, prohibitions and guardrails are necessary. But by themselves, they only keep piling rules on top of an undesirable field.

The goal of attractor engineering is to build a field where good paths are naturally selected, and bad shortcuts are expensive, observable, and detectable in review.

This becomes even more important in the age of AI coding agents. AI agents tend to choose the path that looks most natural from the existing codebase and surrounding artifacts. In this sense, a codebase is not only an implementation; it is also a prompt for AI agents. If the field is undesirable, AI agents can amplify bad local patterns quickly. If the field is well designed, AI agents can also amplify good structure quickly.

In SFT terms, attractor engineering means designing future operation support.

• Which changes look natural?

• Which changes become low-cost?

• Which violations become observable?

• Which feedback remains in the next field?

This question is not merely quality control. It is the design of the direction of software evolution.

What AAT/SFT Is Trying to Do

AAT/SFT is trying to do three main things.

The first is to change the question.

Is this design good?

Instead of trying to answer that question as-is, we decompose it:

• What object are we talking about?

• What do we want to preserve?

• Which invariant failed?

• What are we failing to observe?

• What kinds of changes does this change make more natural next?

This is not meant to make practical design judgment lighter. It is meant to make implicit judgment more tractable.

The second is to formalize the core of the theory in the Lean theorem prover.

We do not need to formalize all of AAT/SFT at once. The first step is to make the foundations of AAT, such as local algebra, invariants, obstructions, signatures, and the zero-curvature theorem, verifiable in Lean.

architecture object
  + operation
  + invariant
  + obstruction
  + signature
  + theorem boundary

Once this core is formalized, we can mechanically check what follows from which assumptions, and where the consequences stop.

The third is to connect the theory to practical tools and methods.

AAT reads design judgment in terms of invariants and obstructions. ArchSig makes those observable from codebases, PRs, issues, reviews, and incident traces. SFT uses those observations to reason about which ForecastCone opens and which paths become natural.

AAT
  -> theoretical core

Lean
  -> formalization of the core

ArchSig / tooling
  -> observation of real artifacts

SFT
  -> computation of software evolution

The eventual goal is to have tools for observing, questioning, and improving requirements, design, issues, PRs, review, CI, operational feedback, and the behavior of AI agents on top of the same theory.

Closing

Lehman saw that software keeps changing. Software connected to the real world continues to drift from its environment as long as it is used. It is changed to close that gap, and through being changed, it gains complexity and creates new feedback loops.

AAT/SFT sits on the same line of concern.

AAT asks about the local structure of that change. What object are we looking at, what do we preserve, which invariant failed, and on which axes can we observe it?

SFT asks how that change shapes the next change. It asks which futures are pulled closer, and which futures are pushed farther away, by requirements, design, issues, PRs, review, CI, operational feedback, and AI agents.

A good theory does not necessarily give all the answers immediately. But it gives us better questions, and it tells us how far those questions can be answered.

As Lehman showed, software keeps changing. If so, we should not merely accept that change. We should make it something we can ask about.

AAT/SFT is an attempt to define questions for software that keeps changing.

Further Reading

If you want to read more about the mathematical definitions of AAT/SFT, theorem boundaries, and the connection to SFT, see the following primary documents:

• Algebraic Architecture Theory

• Software Field Theory

For a practical example of attractor engineering, and as an example of a multi-agent system for automatically maintaining a codebase, you may also want to read the article on Gotanda Style:

• AI Agents Don't Need Meetings: Gotanda Style for Stigmergic Software Maintenance

We tried something different: our agents do not talk to each other at all.

They leave traces in a shared environment. Other agents read those traces later, combine them with new evidence, turn the right ones into GitHub issues, and sometimes produce pull requests.

This pattern is called stigmergy: coordination through changes left in the environment rather than direct communication between individuals. In this article, I will call our version of the pattern Gotanda Style.

This is not just a thought experiment. We already use this workflow to maintain a Python repository with roughly 200,000 lines of code. Sentry alerts deposit "pheromones." Aggregated signals become issues. Some of those issues are small and well-scoped enough for an implementation agent to turn into pull requests.

The result is a multi-agent maintenance loop that is asynchronous, leaderless, token-efficient, and built for real software operations rather than demo-friendly agent conversations.

TL;DR

• Faster coding agents increase maintenance pressure: production errors, performance regressions, test gaps, and architectural drift all grow with change velocity.

• Gotanda Style coordinates agents through a shared pheromone field instead of direct agent-to-agent conversation.

• Observer agents deposit structured positive and negative signals; an integrator turns only the right clusters of evidence into issues.

• This lets maintenance agents run asynchronously, spend fewer tokens, avoid supervisor bottlenecks, and route only safe, well-scoped work to implementation agents.

Why maintenance matters more as coding agents get better

AI coding agents are making it much faster to write code.

That is a real shift. But when code creation gets faster, the maintenance burden grows too. More code reaches production in less time. More changes need monitoring, debugging, refactoring, testing, and design review.

It is like doubling the speed of a car. Higher speed is useful, but only if the tires, brakes, suspension, and safety systems can handle it. Otherwise, speed just turns small failures into bigger ones.

In AI-assisted development, speeding up implementation is not enough. The maintenance system has to scale with the new velocity.

Software work is not just "writing code." Over the long run, a large share of the cost comes from work like this:

• Investigating production errors

• Detecting performance regressions

• Filling test gaps

• Finding architectural drift

• Repairing broken boundaries between modules

• Converting small improvement opportunities into reviewable pull requests

The faster AI helps us produce code, the more important these loops become.

If we want AI-driven development to scale, we need more than automated code generation. We need agentic maintenance.

Gotanda Style came from that problem. The goal is not to hand all product or architecture decisions to AI. The goal is to use multiple agents to continuously support the parts of software maintenance that are repetitive, observable, and evidence-driven.

Why conversational multi-agent systems are hard to scale

When people hear "multi-agent system," they often imagine a group of specialist agents solving a problem by talking to each other.

A typical setup looks like this:

• A planner agent decomposes the task

• A research agent investigates context

• A coding agent implements the change

• A reviewer agent reviews the result

• A supervisor agent decides what happens next

This can work well for small tasks. Many current agent frameworks are built around patterns like supervisors, handoffs, routers, and subagents.

But software maintenance is different. It is continuous, asynchronous, broad in scope, and tied to production evidence. For that kind of work, conversation-centered coordination has several problems:

1. As the number of agents grows, the communication graph gets harder to manage.

2. Agents need to read each other's context, which increases token usage.

3. The supervisor becomes an information bottleneck and a potential single point of failure.

4. In a large codebase, having every agent read the same context is wasteful.

5. Temporary opinions and noisy reasoning can stay in the chat history and bias later decisions.

Human organizations have the same failure mode. A team that keeps everyone in every meeting slows down as it grows.

The same thing happens with LLM agents. After a certain point, coordination itself becomes the cost.

Gotanda Style: coordinate through the environment, not through chat

The core rule of Gotanda Style is simple:

Agents do not talk to each other. They leave traces in a shared environment.

Each agent observes only its own slice of the system. When it finds a signal, it writes that signal into a shared environment.

We call that shared environment the pheromone field.

For example:

• Sentry worker: observes runtime errors

• Datadog worker: observes slow requests, slow SQL, 5xx spikes, and cost spikes

• Quality worker: looks for layering violations, missing exception handling, test gaps, and API contract drift

• Refactor worker: reads the pheromone field, combines related signals, and creates issues

• Code worker: picks up Gotanda-labeled issues and opens pull requests

The important part is that observer workers do not directly create a flood of GitHub issues.

The Sentry worker leaves a trace that says, in effect, "this file is involved in a production error." The Datadog worker leaves a trace that says, "this endpoint is slow." The Quality worker leaves a trace that says, "this function may have an error-handling problem."

They do not negotiate with each other in chat.

Later, the Refactor worker reads the accumulated pheromone field and decides which clusters of evidence are worth turning into issues.

The workflow has three stages:

1. Observer: observes the outside world or the codebase and deposits pheromones

2. Integrator: reads the pheromone field, merges related signals, and creates issues

3. Implementer: turns safe, well-scoped issues into pull requests

Sentry worker   ----+
Datadog worker  ----+-->  Pheromone field  -->  Refactor worker  -->  GitHub Issue  -->  Code worker  -->  Pull Request
Quality worker  ----+

What is a pheromone?

A pheromone is a structured signal that an agent leaves in the shared environment.

A minimal model looks like this:

(scope, location, worker, strength, half_life, metadata)

Each field has a specific role:

• scope: the granularity of the signal, such as file, function, endpoint, or sql

• location: the actual target, such as a file path, function name, API route, or SQL fingerprint

• worker: the agent that deposited the signal

• strength: how strong the signal is

• half_life: how quickly the signal decays

• metadata: supporting details such as error category, environment, evidence, or classification

If the Sentry worker finds a production error, it might deposit a pheromone like this:

{
  "scope": "file",
  "location": "app/services/invoices.py",
  "worker": "sentry-worker",
  "strength": 2.0,
  "half_life_days": 14,
  "metadata": {
    "category": "runtime_error",
    "environment": "production",
    "error_type": "IntegrityError"
  }
}

If the Quality worker finds a test gap in the same file, it might deposit a separate pheromone:

{
  "scope": "file",
  "location": "app/services/invoices.py",
  "worker": "quality-worker",
  "strength": 1.0,
  "half_life_days": 21,
  "metadata": {
    "category": "test_gap",
    "severity": "medium"
  }
}

The Refactor worker does not make decisions from a single deposit in isolation. It reads the aggregated field.

When multiple workers deposit signals around the same location, that location becomes a hotspot worth inspecting.

Positive and negative pheromones

In Gotanda Style, pheromones are not always positive.

A positive pheromone is an attraction signal: "look here."

A negative pheromone is an inhibition signal: "we looked at this, and for now we should not pursue it."

For example, if the Refactor worker investigates a candidate and decides that it is an accepted design exception, it can deposit a negative pheromone:

{
  "scope": "fingerprint",
  "location": "layering_violation:abc123",
  "worker": "refactor-worker",
  "strength": -1.5,
  "half_life_days": 60,
  "metadata": {
    "reason": "accepted design exception"
  }
}

This prevents the same candidate from becoming a new issue every time a worker sees it.

But the negative pheromone is not permanent. It decays over time. If Sentry or Datadog later deposits a strong signal in the same area, the candidate can resurface.

That property matters in maintenance work. "Won't fix right now" is not the same thing as "ignore forever."

Why this scales

1. More agents do not create a communication explosion

In a conversational design, every new agent raises a coordination question: who needs to talk to whom, when, and with how much context?

In Gotanda Style, agents do not need to know about each other. They only need to write signals into the shared environment using a known schema.

Adding a new worker is mostly a contract question: what kind of pheromone does it deposit?

That makes the system plugin-like. If you want a Security worker, it deposits security signals. If you want a Performance worker, it deposits performance signals. The Refactor worker can read both as part of the same field.

2. Large codebases can be explored more efficiently

In a large codebase, reading every file on every run is not realistic.

The real question is how to spend a limited exploration budget.

With a pheromone field, exploration is not purely random, and it is not limited to "recently changed files" either. A worker can prioritize:

• Recently changed files

• A random sample of files

• Hotspots from Sentry or Datadog

• Areas with strong negative pheromones, at a lower priority

• Locations where multiple workers have deposited signals

The search budget adapts to observed evidence.

That is a good fit for continuous AI maintenance over a large codebase.

3. It is token-efficient

Because agents do not have long conversations with each other, they do not need to read each other's full reasoning traces or chat histories.

What gets shared is a small structured signal:

{
  "scope": "endpoint",
  "location": "GET /api/reports",
  "worker": "datadog-worker",
  "strength": 1.2,
  "metadata": {
    "category": "slow_request",
    "p95_ms": 1800
  }
}

That is far cheaper than thousands of tokens of conversation.

Only when the Integrator needs to make a decision does it dig into the code, logs, issues, and previous decisions.

4. It runs asynchronously

Workers do not need to run at the same time.

The Sentry worker can run every 10 minutes. The Datadog worker can run once a day. The Quality worker can run overnight. The Code worker can poll for labeled issues every few minutes.

Each worker observes the environment and deposits pheromones at its own pace.

That is useful in production. External systems like GitHub, CI, Sentry, and Datadog all have different rate limits, failure modes, and latency profiles. Independent workers localize failures instead of turning every dependency hiccup into a global coordination problem.

5. Noise can be handled over time

LLM agents are noisy. A weak signal from one worker should not always become an issue.

In Gotanda Style, pheromones decay.

A one-off weak signal fades away. Signals that recur, signals that come from multiple workers, and signals tied to production impact remain stronger.

This helps the system prioritize persistent problems over one-time noise.

A simple sum is not enough

There is an important catch.

If you simply add pheromones together, you can lose information.

Imagine a location has these two signals:

sentry-worker: +2.0
refactor-worker: -2.0

The simple sum is zero.

But this is not the same as a location where nothing is happening.

It means something closer to: "there is a production error here, but there is also a previous won't-fix decision."

If we treat both cases as zero, we miss an important conflict.

So Gotanda Style tracks positive mass, negative mass, total variation, and conflict separately:

• current_strength: net strength

• positive_strength: total positive signal

• negative_mass: total negative signal

• total_variation: total signal without cancellation

• conflict_ratio: how strongly positive and negative signals disagree

The practical rule is simple:

Distinguish silence from conflict.

This lets the Refactor worker make better decisions:

• Strong positive signal only: possibly safe to turn into an implementation issue

• Strong negative signal only: do not pursue right now

• Strong positive and negative conflict: likely needs human review

• No signal: lower exploration priority

How issues are created in Gotanda Style

Observer workers generally should not create issues directly.

They usually do not have enough context at observation time.

The Sentry worker knows about an error, but it may not know whether the fix is local, architectural, already accepted, or intentionally deferred.

The Datadog worker knows about a slow SQL query, but it may not know whether the query is unacceptable, part of a tolerated batch job, or tied to a product requirement.

The Quality worker may find something that looks like a layering violation, but it may be an intentional design exception.

So observer workers deposit pheromones. Issue creation belongs to the Integrator.

The Integrator reads multiple pheromones, the current code, existing issues, and previous won't-fix decisions. Then it classifies the candidate:

Only B1 goes to the Code worker.

That boundary is intentional. Issues sent to an implementation agent should have a clear intent, a limited scope, and enough evidence that a reviewer can trace the pull request back to the original problem.

Large design decisions stay with humans. Once a human decides the direction, the local follow-up work can be split into smaller issues for the Code worker.

What is already working

Gotanda Style is not just a research sketch.

We are using this pattern on a Python repository with about 200,000 lines of code.

The current loop works like this:

1. The Sentry worker detects a production alert.

2. It classifies the alert and deposits pheromones for cases that appear to need either a local fix or deeper remediation.

3. The Refactor worker reads the pheromone field and combines the alert with other observations and previous decisions.

4. It creates improvement issues at a level of detail that can be implemented automatically.

5. The Code worker reads the issue, creates a branch, makes the change, and opens a pull request.

Not every alert becomes an automated fix. Anything that needs a design decision, has an unclear cause, or has a large blast radius is routed to a human.

But the closed loop from Sentry alert to pheromone deposit to issue to improvement PR is already running in practice.

That is the key point: Gotanda Style did not come from abstract multi-agent theory. It came from operating and maintaining a real large codebase.

What is new here?

Multi-agent systems are not new.

There are many existing patterns: supervisors, handoffs, routers, blackboards, shared memory, and more.

The interesting part of Gotanda Style is the combination:

1. It is specialized for software maintenance.

2. It separates observation, integration, and implementation.

3. Agents do not talk to each other directly.

4. Agents deposit positive and negative pheromones into a shared environment.

5. Pheromones decay over time.

6. Hotspots and conflicts across observers drive issue creation.

7. Only safe, automatable issues are passed to the Code worker.

This is not a general-purpose chatty multi-agent system.

It is an asynchronous, leaderless, token-efficient workflow pattern for continuously maintaining a large codebase.

The hard parts

This pattern has real challenges.

The biggest one is the quality of the pheromone field.

If the field fills with noise, the whole system follows that noise. If inhibition is too strong, the system misses real problems.

Several parts are especially tricky.

Normalizing locations

If workers refer to the same place using different location strings, signals will not aggregate.

For example, these may all refer to the same API:

GET /api/users/{id}
/api/users/:id
app/api/users.py:get_user

Deciding when these should collapse into one location is an important design problem.

Calibrating strength

A Sentry production error with strength +2.0 should not carry the same meaning as a low-confidence Quality worker concern with strength +0.5.

The system needs ongoing calibration across worker reliability, category severity, environment, and production impact.

Defining negative pheromone semantics

Negative pheromones are useful, but they are also dangerous.

"Do not pursue right now" is different from "ignore forever."

Negative pheromones need reasons, fingerprints, half-lives, and resurfacing conditions.

Auditability

As automation increases, the system has to explain itself.

Operators need to trace why an issue was created, why a pull request was opened, which worker run contributed which signal, and which previous decisions were considered.

Without that audit trail, the workflow will not be trusted in production.

What we want to improve next

Gotanda Style is still evolving.

The next areas we care about most are:

• Reliability weights per worker

• Category-specific weights

• Location alias normalization

• Audit logs tied to run_id

• Self-stop conditions

• Canary operation

• Human-in-the-loop boundaries

• Reallocating exploration based on the pheromone field

The last point is especially important. The field should not only be something agents read when making issues. It should also shape what agents inspect next.

For example, instead of letting the Quality worker explore completely at random, it can divide its budget like this:

• Recent files: 40%

• Random files: 30%

• Pheromone hotspots: 20%

• Cooling follow-up: 10%

This keeps some randomness while adapting to what the system has already observed.

Gotanda Style as attractor engineering

Another way to describe Gotanda Style is practical attractor engineering for a codebase.

By "attractor," I mean the structure or state that a codebase naturally drifts toward as changes accumulate.

In a codebase with clear boundaries, good types, good tests, and good examples, the next change is more likely to fit the same pattern. In a codebase with a giant common module, vague services, overly convenient helpers, and bad nearby examples, changes tend to drift in that direction.

AI coding agents amplify this dynamic.

AI does not write code in a vacuum. It reads existing code, neighboring files, names, tests, previous implementations, and docs. The whole codebase becomes part of the prompt.

If the codebase contains bad local grammar, AI will often reproduce it as the natural answer. When development speeds up, the drift toward bad attractors can speed up too.

Attractor engineering means shaping where future changes are likely to land.

Gotanda Style uses the pheromone field to observe signals like:

• Which files or endpoints accumulate production errors

• Where performance regressions show up

• Where tests are missing or boundaries are weakening

• Which locations are repeatedly flagged by multiple workers

• Which candidates were previously marked won't-fix

• Where positive and negative signals are in conflict

This is more than alert aggregation.

It is a way to observe where the codebase is drifting, identify areas that are becoming bad basins, and use issues and repair PRs to change the trajectory.

codebase field
  -> AI / human PR force
  -> pheromone observation
  -> issue / repair PR
  -> updated codebase field

In that sense, Gotanda Style is not a system for making AI write more code.

It is an operating model for directing AI's increased change velocity toward a codebase that remains maintainable and observable.

A mathematical view

Intuitively, the pheromone field is a set of weighted signals per (scope, location).

More formally, each worker deposits a signed weight at (worker, scope, location), and the system aggregates those weights by (scope, location).

Positive weights attract attention. Negative weights inhibit attention.

Over time, each weight decays exponentially:

current = strength * 0.5 ^ (elapsed / half_life)

A simple sum can hide conflicts because positive and negative signals cancel each other out.

So the system keeps positive mass, negative mass, total variation, and conflict ratio:

net = positive - negative
total_variation = positive + negative
conflict_ratio = 1 - abs(net) / total_variation

These additional values let the system distinguish a quiet location from a contested one.

Conclusion

In LLM multi-agent systems, coordination is one of the core design problems.

Conversation-based coordination is easy to understand, but as the number of agents, the size of the codebase, and the duration of operations grow, communication and context-management costs become significant.

Gotanda Style avoids direct agent-to-agent conversation.

Instead, each agent deposits pheromones into a shared environment. Other agents read those pheromones, integrate them with evidence, create issues, and turn only the safe, automatable ones into pull requests.

The pattern has several advantages:

• It is easier to add more agents.

• It supports efficient exploration of large codebases.

• It reduces inter-agent communication and token usage.

• It works asynchronously.

• It handles noise through time decay.

• It can detect hotspots and conflicts that are hard to see in direct conversation.

We think this can become a useful design pattern for LLM-based software maintenance.

And for us, it is not a future idea. It is already running on a Python repository with about 200,000 lines of code, closing the loop from Sentry alert to improvement pull request.

If AI coding agents increase development velocity, maintenance has to become stronger at the same time. We need agents that observe the codebase, detect anomalies, combine improvement signals, create issues at safe granularity, and turn those issues into pull requests.

As more agents continuously observe, maintain, and improve codebases, coordination models that do not depend on constant conversation will matter more.

Gotanda Style is one experiment in that direction.

TL;DR

• A codebase can be read as a field that attracts future changes, and a pull request can be read as a force applied to that field.

• A good field makes good changes easier to make. A bad field repeatedly makes bad shortcuts look natural. In an era where AI can produce PRs quickly, this attraction becomes stronger.

• I call the practice of designing where future changes are pulled Attractor Engineering.

• CI/CD, tests, reviews, and harnesses can be read as dissipative systems: they remove unwanted force and shape the trajectory.

• ArchSig, or Architecture Signature, is a tool for observing that trajectory along multiple axes.

The first half of this article is written for practitioners: it explains the intuition in terms of codebases, PRs, review, CI, and AI-assisted development. The second half is more mathematical: it connects the same intuition to AAT, Architecture Signature, Lean formalization, and finite counterexamples.

The First Discovery

The starting point was a simple thought experiment.

What if we look at software architecture not only as a set of directories, design rules, or conventions, but as an algebraic structure?

From that point of view, everyday changes such as feature additions, refactorings, splits, migrations, repairs, protections, deletions, and integrations become operations acting on the structure we call architecture.

current codebase
  + feature addition
  + refactoring
  + review fix
  + migration
  + repair
  -> next codebase

If we take one more step, we can ask: if these operations are not applied once, but repeated dozens or hundreds of times, can the whole development process be read as a kind of dynamics?

Each individual PR is small.

But after enough PRs, the codebase gradually moves in some direction.

When a good structure already exists, the next change tends to fit into a good place.

When a bad structure exists, a locally natural change tends to take the same bad shortcut again.

Can we treat "where changes tend to go" as something we design?

I decided to call this way of thinking Attractor Engineering.

A Codebase Is a Field, and a PR Is a Force

The central interpretation is this:

codebase = a field that attracts changes
PR       = a force applied to that field
ArchSig  = an observer for the movement

A codebase is not a neutral space that passively receives future changes.

Existing names, types, responsibility boundaries, tests, directory structure, previous implementation examples, and review culture all shape which next change feels natural.

A PR is a force applied to that field. Each one may be small, but repeated PRs create a trajectory of change.

current codebase
  -> a PR is applied
  -> an architectural change is observed
  -> a trajectory of change emerges
  -> this becomes the next codebase

The important point is that a PR changes the codebase, and the changed codebase then changes what the next PR is likely to look like.

People and Systems Create the Field

This field is not created only by engineers.

Product managers, product owners, engineers, reviewers, AI agents, CI, tests, design documents, coding standards, and existing examples all participate in it.

Everyone and everything involved in development affects which changes become likely next.

The way requirements are sliced, prioritized, scheduled, and accepted changes how later PRs are produced. Even people who do not write code apply indirect force to the field of the codebase.

This becomes especially important in AI-assisted development. Vague requirements can quickly become vague PRs. If boundaries and non-goals are clear, an AI system is more likely to produce useful changes within those boundaries.

What Changes in AI-Assisted Development

The essence of AI-assisted development is not simply that code can be written faster.

The more important change is that the distribution of selected change operations changes.

An AI system reads existing code, neighboring files, names, types, tests, previous implementation examples, READMEs, and design documents, and then generates the next proposed change.

In other words, the whole codebase becomes input context for the AI.

the codebase becomes input context for AI
  -> AI proposes a change
  -> the proposal becomes a PR
  -> review / CI / merge process handles it
  -> the codebase is updated
  -> the next input context changes

If a good reference implementation is nearby, the AI is likely to imitate it.

If a bad shortcut already exists, the AI is also likely to treat it as a natural option.

In this sense, AI rapidly reproduces the local style already present in the field. That is why, in the AI era, what matters is not only the capability of an individual AI agent. The design of the field in which the AI participates matters just as much.

What Is an Attractor?

When a codebase contains a huge common module, an overly convenient helper, or an ambiguous service, changes tend to be pulled there.

Conversely, when good responsibility boundaries and clear implementation examples exist, the next change tends to follow them.

This destination toward which changes are pulled is what I call an attractor. When something moves repeatedly, it often tends to approach certain places or states.

The surrounding region from which things are likely to fall into that attractor is what I call a basin.

Technical debt can be read as a bad basin.

Once a codebase falls into it, locally natural changes keep adding to the same place, and the cost of refactoring out of it grows higher and higher.

The important point is that attractors can be good or bad.

A good attractor pulls in good changes.

A bad attractor makes bad shortcuts get selected again and again.

What Is Attractor Engineering?

Attractor Engineering is the idea that we should deliberately design these attractors.

Its target is not just the codebase.

It includes the whole development organization: product managers, product owners, engineers, reviewers, AI agents, CI/CD, tests, design documents, and coding standards.

The goal is not only to block bad changes from the outside. The goal is to create a field where good changes are naturally easier to select.

Attractor Engineering is an integrated design theory for the era of AI-assisted development. It treats the entire development organization as part of the system.

Harness Engineering as a Dissipative System

We cannot simply take changes produced by AI and put them directly into the codebase.

Harnesses, CI, tests, type checking, static analysis, and review divide proposed changes into "accept", "fix and check again", and "do not merge".

In Attractor Engineering, this behavior can be read as dissipation.

Dissipation is the mechanism that removes unwanted components of the force entering the field.

If dissipation is too weak, the fast change force produced by AI enters the codebase directly. If it is too strong, nothing moves. A good harness weakens the force that increases debt while preserving the force that moves the product forward.

In this view, CI/CD is not merely a checklist. It is more like brakes, rails, signals, and safety equipment that convert fast PR generation into safe productivity.

What matters in AI-assisted development is not only making the engine stronger.

It is also preparing the field and the dissipative system that can receive a stronger engine.

What ArchSig Observes

To design the field, we need to observe what is happening.

That is the role of ArchSig.

ArchSig is short for Architecture Signature.

In my repository, I use it to mean an observation framework for reading changes in a codebase or PR along multiple axes. Dependencies, boundaries, abstractions, runtime exposure, semantic drift, and test observability are not collapsed into a single score. They are treated as multiple features.

ArchSig is an observer for seeing which direction a PR moves the architecture.

For example, we may observe axes like these:

The important point is that we do not compress good and bad into one score.

What we want to know is which axes got worse, which axes improved, and what kind of force each change applies.

PR
  -> observe change with ArchSig
  -> observe the trajectory of change
  -> see whether it is moving toward a good or bad region

ArchSig becomes an observer for the AI PR era.

Are AI-generated changes moving toward good attractors?

Are they falling into a pool of technical debt?

Is the harness dissipating enough bad force?

ArchSig gives us shared language for discussing those questions.

PRs Become More Important, Not Less

When AI reduces the cost of generating code, it may look as if PRs become less important.

From a dynamical systems viewpoint, the opposite is true.

A PR is not just a work unit.

A PR has the following roles:

• It cuts continuous change into observable units.

• It lets us separate the directions in which a change acts.

• It embeds the dissipative process of review, CI, and approval.

• It creates a boundary for rollback and reversibility.

• It creates a unit for decision-making and discussion.

What AI lowers is mainly the cost of producing a PR.

But the value of PRs as units of observation, decomposition, dissipation, reversibility, and decision-making increases. In the AI era, PRs do not become unnecessary. They become more important as units for observing and controlling architectural movement.

Future Development Organizations

In future development organizations, the central problem will not be only how fast we can write code. It will be how to design a field that can safely receive that speed.

A fast train cannot run safely just because it has a powerful motor.

It needs rails, brakes, signals, safety equipment, and operations control.

Software development is similar. AI is a powerful motor, but by itself it can create semantic drift, responsibility drift, degradation of design properties we wanted to preserve, merge confusion, and flow toward technical debt.

What we need is a field with properties like these:

• Small and observable PRs.

• Fast feedback.

• Reliable CI.

• A useful type system.

• Architecture tests.

• Carefully selected reference implementations.

• Isolation of legacy code.

• Clear demands, requirements, and design boundaries.

• Human-designed boundaries for value and acceptance criteria.

The safest AI coding environment is not the one with the strongest external harness. It is the one where good changes are natural, easy to imitate, observable, and less likely to fall into bad shortcuts.

Summary So Far

The success or failure of AI-assisted development is not determined only by how fast AI can write code.

The direction of the next PR changes depending on the field created by the codebase, requirements, design boundaries, reference implementations, review, CI/CD, and ArchSig.

A good field attracts good changes. A bad field repeatedly makes bad changes look natural. That is why architecture design in the AI era becomes the design of where future changes are attracted.

So far, this has been Attractor Engineering in practical engineering language. In the second half, I translate the same intuition into the language of AAT, Algebraic Architecture Theory, and dynamical systems.

From Here, in Mathematical Language

The rest of this article uses more mathematical formulation. If you only want the practical view first, it is fine to skip to the conclusion.

Around AI development, there are many heuristics: "this prompt worked", "this workflow made us faster", and so on. These heuristics are valuable. But by themselves, they make it hard to separate why something worked, how far it generalizes, and under what conditions it breaks.

So I decompose the flow: a change is selected, becomes a PR, passes review / CI, is merged, and then the updated codebase changes the distribution of future changes. By separating state, operation, observation, invariant, obstruction witness, and proof obligation, we can turn heuristics into something easier to test.

A Short Introduction to AAT

The background theory for this discussion is AAT, or Algebraic Architecture Theory. Here I introduce only the minimal vocabulary needed for the rest of the article.

The Lean snippets below are excerpts from implemented APIs, adjusted for readability. Namespaces, imports, and some proof bodies are omitted.

AAT treats software development not merely as a sequence of code changes, but as a theory of architectural extension, decomposition, repair, and composition.

Its central proposition does not appear in Lean as one large equation. It appears as packages that combine operations and proof obligations.

structure OperationProofObligation (State : Type u) (Witness : Type v) where
  kind : ArchitectureOperationKind
  obligation : ProofObligation State Witness
  precondition : Prop
  nonConclusion : Prop

Operations are first classified as an operation catalog on the Lean side.

inductive ArchitectureOperationKind where
  | compose
  | refine
  | abstract
  | replace
  | split
  | merge
  | isolate
  | protect
  | migrate
  | reverse
  | contract
  | repair
  | synthesize
  deriving DecidableEq, Repr

The important point is that names such as split or repair prove nothing by themselves. An operation kind is a classification for theorem packages. Claims about preservation, improvement, or repair must be stated separately as proof obligations.

From this viewpoint, a design review is not only the question "is this design good or bad?"

- Is the existing structure embedded after extension?
- Can the new feature be split out from the existing structure?
- Do interactions pass through declared interfaces?
- Which invariants are preserved, and which invariants were broken?
- If a split is not possible, which obstruction witness blocks it?

The smallest object in AAT is ArchitectureCore.

structure ArchitectureCore (C : Type u) (A : Type v)
    (StaticObs : Type w) (SemanticExpr : Type q)
    (SemanticObs : Type r) where
  flatness :
    ArchitectureFlatnessModel C A StaticObs SemanticExpr SemanticObs
  staticUniverse : ComponentUniverse flatness.static
  componentDecidableEq : DecidableEq C
  staticEdgeDecidable : DecidableRel flatness.static.edge
  runtimeEdgeDecidable : DecidableRel flatness.runtime.edge
  boundaryPolicyDecidable : DecidableRel flatness.boundaryAllowed
  abstractionPolicyDecidable : DecidableRel flatness.abstractionAllowed
  runtimeRole : C -> C -> RuntimeDependencyRole
  semanticRequiredDecidable :
    ∀ d : RequiredDiagram SemanticExpr,
      Decidable (flatness.requiredSemantic d)

Here it is important that ArchitectureCore is not the whole real-world codebase itself. It is a finite or bounded object extracted from code, specifications, reviews, and operational observations so that the theory can handle it.

Feature addition is read as an operation that extends an existing architecture into a larger one while preserving the existing architecture.

ExistingCore X
  -> ExtendedArchitecture X'
  -> FeatureView F

In a good feature extension, the existing core is preserved inside the extension, the feature view can be extracted in an explainable way, and interactions from the feature to the core pass through declared interfaces. Conversely, hidden dependencies, boundary policy violations, abstraction leakage, runtime exposure, and semantic mismatch are treated not as impressions, but as ObstructionWitness values.

To count, remove, preserve, or explicitly decline to conclude about these obstructions, AAT makes ProofObligation and Certificate explicit.

structure ProofObligation (State : Type u) (Witness : Type v) where
  formalUniverse : Prop
  requiredLaws : Prop
  invariantFamily : State -> Prop
  witnessUniverse : Witness -> Prop
  coverageAssumptions : Prop
  exactnessAssumptions : Prop
  operationPreconditions : Prop
  conclusion : Prop
  nonConclusions : Prop

An obligation is not discharged merely because it exists. It is discharged only when the visible assumptions imply the conclusion.

def AssumptionsHold (P : ProofObligation State Witness) : Prop :=
  P.formalUniverse ∧
  P.requiredLaws ∧
  P.coverageAssumptions ∧
  P.exactnessAssumptions ∧
  P.operationPreconditions

def Discharged (P : ProofObligation State Witness) : Prop :=
  AssumptionsHold P -> P.conclusion

The same is true for certificates. For example, in repair synthesis, if we say "there is no solution", solver failure alone is not enough. Only when a valid certificate exists do we use soundness to conclude that no satisfying architecture exists.

structure NoSolutionCertificate
    {State : Type u} {Constraint : Type c} (Certificate : Type v)
    (C : SynthesisConstraintSystem State Constraint)
    (cert : Certificate) where
  valid : Prop
  sound : valid -> NoArchitectureSatisfies C
  coverageAssumptions : Prop
  exactnessAssumptions : Prop
  nonConclusions : Prop

theorem sound_of_valid
    (pkg : NoSolutionCertificate Certificate C cert)
    (hValid : ValidNoSolutionCertificate pkg) :
    NoArchitectureSatisfies C

nonConclusions is not decoration. Even if a static split is proved, runtime flatness or semantic flatness does not automatically follow. Even if no obstruction is found in one observation universe, that does not imply there is no obstruction in every universe. Making this boundary explicit is necessary if we want to treat the theory as testable rather than as a collection of engineering anecdotes.

ArchitectureSignature is also not intended to collapse architecture quality into a single score. It is a multi-axis diagnosis for reading multiple invariant and obstruction families axis by axis.

structure ArchitectureSignatureV1 where
  core : ArchitectureSignatureV1Core
  weightedSccRisk : Option Nat
  projectionSoundnessViolation : Option Nat
  lspViolationCount : Option Nat
  nilpotencyIndex : Option Nat
  runtimePropagation : Option Nat
  relationComplexity : Option Nat
  empiricalChangeCost : Option Nat
  deriving DecidableEq, Repr

Some axes are Option Nat because an unmeasured value must not be treated as zero. none does not mean "no problem". It means "not measured in this universe / extractor / bridge".

theorem not_axisAvailableAndZero_of_axisValue_none
    {sig : ArchitectureSignatureV1} {axis : ArchitectureSignatureV1Axis}
    (hNone : axisValue sig axis = none) :
    ¬ axisAvailableAndZero sig axis

From this perspective, a signature is not a convenient bag of metrics. It is a multi-axis invariant relative to a law universe. For selected required law axes, there are also bridge theorems connecting lawfulness and zero signature axes.

theorem architectureLawful_iff_requiredSignatureAxesZero
    {C : Type u} {A : Type v} {Obs : Type w}
    (X : ArchitectureLawModel C A Obs)
    [DecidableEq C] [DecidableEq A] [DecidableEq Obs]
    [DecidableRel X.G.edge] [DecidableRel X.GA.edge]
    [DecidableRel X.boundaryAllowed]
    [DecidableRel X.abstractionAllowed] :
    ArchitectureLawful X ↔
      RequiredSignatureAxesZero (ArchitectureLawModel.signatureOf X)

AAT does not treat every claim at the same level. It separates definitions, proved theorem packages, bounded bridge theorems, tooling-side evidence, and empirical hypotheses. It also records which universe, observation, coverage, and exactness assumptions each claim is relative to.

The dynamics part below follows the same discipline. The important point is that AAT is not using mathematical vocabulary for atmosphere. It is trying to make the assumptions, conclusions, and non-conclusions part of the type-level structure.

So far, AAT gives us vocabulary for a single architectural state and operations acting on it.

But in AI-assisted development, the central issue is not only a single operation. Requirements, existing code, review, CI, and AI agents change which operation is likely to be selected next, and this selection is repeated many times.

So we need to view AAT operations not only as one-time proof targets, but also as transformations repeatedly selected over time. This is where a chaos-game-like reading enters.

Formalizing Attractor Dynamics

From here, I use AAT vocabulary to rewrite "field", "force", "dissipation", and "observation" in a more mathematical form.

This is not merely a metaphor that says "AI development is kind of like a chaos game". It is an attempt to place PR force, operation support, trajectory, and basin candidates on top of the AAT vocabulary of state, operation, invariant, obstruction, proof obligation, certificate, and signature.

At this stage, I should be careful: this is not a finished theorem of real-world software development. It is a way to organize phenomena that practitioners can feel, in a structure that may eventually support measurement and verification.

The minimal loop of the dynamics can be read as follows:

architecture field
  -> operation distribution
  -> accepted / rejected transitions
  -> signature trajectory
  -> updated architecture field

The position is that architecture quality is not only a property of a snapshot. It is also a property of the future operation distribution and the signature trajectory.

1. State, Operation, Observation

Let the architectural state be X_t.

Feature addition, repair, split, protection, migration, and refactoring are operations acting on that state.

X_{t+1} = op_t(X_t)

The operation op_t is not selected uniformly at random.

The current codebase, requirements, prompt, review policy, CI, design boundaries, and organizational judgment all change which operations are likely to be selected.

op_t ~ P(operation | X_t, control_t)

This probability expression is notation for the practical reading. The formal core of AAT is not a probability distribution. It is finite or bounded operation support, bounded scripts, accepted transition predicates, and explicit preservation assumptions.

In Lean, for example, operation support is represented not as a probability distribution, but as a finite list of candidate operations for each state.

structure FiniteOperationKernel
    (State : Type u) (OperationId : Type w) where
  support : State -> List OperationId
  coverageAssumptions : Prop
  weightSourceBoundary : Prop
  normalizationBoundary : Prop
  nonConclusions : Prop

Weights, normalization, and completeness of AI-generated proposals are not mixed into the theorem here. Boundaries such as weightSourceBoundary and normalizationBoundary record what is outside the formal claim, and the probabilistic reading remains outside that core.

Likewise, repeated operation sequences are first treated as bounded scripts.

structure BoundedOperationScript (OperationId : Type w) where
  operations : List OperationId
  operationFamily : OperationId -> Prop
  operationsInFamily :
    ∀ op, op ∈ operations -> operationFamily op
  coverageAssumptions : Prop
  nonConclusions : Prop

This boundary helps avoid confusing probabilistic interpretation with preservation claims over finite support.

Instead of observing the entire state directly, we map it into signature space through an observation function Obs.

sigma_t = Obs(X_t)

This sigma_t is the Architecture Signature.

It contains multi-axis observations such as dependency direction, boundaries, abstraction, runtime exposure, and semantic mismatch.

In Lean, even the observation itself is packaged. The package contains not only the observation function, but also coverage and non-conclusion boundaries.

structure SignatureObservation (State : Type u) (Sig : Type v) where
  observe : State -> Sig
  coverageAssumptions : Prop
  nonConclusions : Prop

When architectural evolution is mapped into observation space, we get a signature trajectory.

def SignatureTrajectory (O : SignatureObservation State Sig) :
    {X Y : State} -> ArchitectureEvolution State X Y -> List Sig
  | X, _, ArchitecturePath.nil _ => [O.observe X]
  | X, _, ArchitecturePath.cons _step rest =>
      O.observe X :: SignatureTrajectory O rest

A change moves the signature.

Delta_t = sigma_{t+1} - sigma_t

This Delta_t can be read as the force applied by the PR or operation.

However, not every axis admits simple subtraction. For numeric axes, we may read it as a signed delta. For other axes, we read it as a before / after comparison, the appearance of a witness, or a change in state classification.

2. PR Force Model

With this structure, a PR becomes more than a diff.

A PR can be read as a force applied to the codebase in the selected Architecture Signature space.

PRForce(PR) = sigma(after(PR)) - sigma(before(PR))

The word force here does not mean physical force. It means an observed change in signature, relative to which axes are observed and which differences are defined.

Delta sequences, like trajectories, are relative to finite paths in Lean.

def SignatureDeltaSequence
    (O : SignatureObservation State Sig) (D : SignatureDelta Sig Delta) :
    {X Y : State} -> ArchitectureEvolution State X Y -> List Delta
  | _, _, ArchitecturePath.nil _ => []
  | X, _, ArchitecturePath.cons (Y := Y) _step rest =>
      D.between (O.observe X) (O.observe Y) ::
        SignatureDeltaSequence O D rest

For selected additive deltas, the sum of step deltas agrees with the endpoint delta. This is proved as a theorem.

theorem netSignatureDelta_telescopes [Zero Delta] [Add Delta]
    (O : SignatureObservation State Sig) (D : SignatureDelta Sig Delta)
    (law : AdditiveSignatureDeltaLaw D) :
    {X Y : State} -> (plan : ArchitectureEvolution State X Y) ->
      NetSignatureDelta (SignatureDeltaSequence O D plan) =
        EndpointSignatureDelta O D plan

But this theorem is finite path calculus under the assumption that the selected delta satisfies an additive law. It does not claim that unobserved axes, incident risk, review quality, or actual PR outcomes can all be added this way.

The force has multiple components.

A good PR has not only feature force, but also stabilizing force.

v_PR = v_feature + v_stabilize

A risky PR moves the feature forward locally while quietly adding small debt force.

v_PR = v_feature + v_debt

In AI-generated PRs, the especially important case is one where tests pass and the specification is satisfied, but small v_debt, v_coupling, v_type_hole, or v_entropy accumulates repeatedly. It may be hard to see in a single PR. But as a trajectory, the system is moving toward a bad basin. I call this the Local Correctness Trap.

3. Three Classes of Force

The earlier discussion about product managers, product owners, review, and CI/CD becomes clearer if we separate force by observability.

Force can be divided into three classes.

This classification makes AI-assisted development more concrete.

If we look only at merged PRs, we see only ObservedForce.

But in an era where AI can generate many proposals, the force that was not merged also matters. Force removed by review, rejected by CI, or reshaped before merge matters.

To understand how well a dissipative system is working, we need DissipatedForce.

To understand what kind of PR distribution is created by upstream requirements or prompts, we need LatentForce.

In Lean, the separation between accepted and rejected changes appears as a damping / control schema.

structure DampingControlSchema (State : Type u) (Sig : Type v) where
  observation : SignatureObservation State Sig
  invariant : SafeRegion Sig
  accepted :
    {X Y : State} -> ArchitectureTransition State X Y -> Prop
  rejected :
    {X Y : State} -> ArchitectureTransition State X Y -> Prop
  acceptedPreservesInvariant :
    ∀ {X Y : State} (t : ArchitectureTransition State X Y),
      accepted t -> StepPreservesSafeRegion observation invariant t
  coverageAssumptions : Prop
  nonConclusions : Prop

What this proves is limited: transitions classified as accepted preserve the explicitly stated invariant. The existence of rejected changes does not prove that the whole future of the codebase is safe.

On top of this schema, it is proved that accepted finite evolutions create trajectories inside the selected invariant.

theorem acceptedEvolution_preserves_selectedInvariant
    (control : DampingControlSchema State Sig) :
    {X Y : State} -> (plan : ArchitectureEvolution State X Y) ->
      StateInSafeRegion control.observation control.invariant X ->
      control.AcceptedEvolution plan ->
        SignatureTrajectoryInSafeRegion
          control.invariant (SignatureTrajectory control.observation plan)

4. A Chaos-Game-Like Correspondence

This is where the chaos-game-like reading appears.

The similarity is that we have multiple transformations, one of them is selected at each step, and a state trajectory is produced.

The difference is that, in software development, neither the set of transformations nor their likelihood is fixed. Requirements, review, CI, design boundaries, existing examples, and AI agent behavior all affect which operation is likely to be selected next.

So the goal is not to claim that software development literally is the classical chaos game. The goal is to use AAT vocabulary to handle the structure where multiple operations are repeatedly selected and the resulting trajectory tends to move toward certain regions.

The correspondence is:

As a formula:

X_{t+1} = f_{i_t}(X_t)
i_t ~ P(. | X_t, control_t)
Y_t = sigma(X_t)

The important point is not to assert probability or attractors as strong theorems too early.

What we should handle in practice is first an attractor candidate or basin candidate relative to a finite observation window, bounded horizon, selected signature axes, and selected operation support.

finite observed trajectory
  + selected signature region
  + bounded operation support
  -> attractor / basin candidate

This is not an escape into weak claims. It is a boundary that makes measurement and falsification possible.

5. Support Shaping

The mathematical core of Attractor Engineering is support shaping.

This is not just about "blocking bad PRs". It is about changing the set of operations that can naturally be selected next, and changing how likely they are to be selected.

In short, Attractor Engineering is a theory of designing the geometry of the operation distribution.

def Supports
    (kernel : FiniteOperationKernel State OperationId)
    (X : State) (op : OperationId) : Prop :=
  op ∈ kernel.support X

For the current architecture state X, the set of operations that can naturally be selected is called operation support.

Good design changes this support.

def SupportOperationsPreserveSafeRegion
    (kernel : FiniteOperationKernel State OperationId)
    (sem : OperationTransitionSemantics State OperationId)
    (O : SignatureObservation State Sig) (R : SafeRegion Sig) : Prop :=
  ∀ {X : State} (op : OperationId),
    kernel.Supports X op -> sem.OperationPreservesSafeRegion O R op

The strong form of support shaping says: operations that remain in support preserve the selected safe region. In practical terms, we reduce bad operations, increase good operations, make correct paths easier to choose, and make dangerous shortcuts less convenient.

This idea is packaged on the Attractor Engineering side as follows:

structure AttractorEngineeringSupportPackage
    (State : Type u) (Sig : Type v) (OperationId : Type w) where
  observation : SignatureObservation State Sig
  kernel : FiniteOperationKernel State OperationId
  semantics : OperationTransitionSemantics State OperationId
  targetRegion : SafeRegion Sig
  supportPreserves :
    kernel.SupportOperationsPreserveSafeRegion semantics observation targetRegion
  coverageAssumptions : Prop
  measurementBoundary : Prop
  nonConclusions : Prop

With this package, if a bounded script uses only operations from finite support, and the starting point is in the target region, then the observed trajectory remains in the target region. This is stated as a theorem.

theorem supportPackage_preserves_targetTrajectory
    (package : AttractorEngineeringSupportPackage State Sig OperationId)
    (script : BoundedOperationScript OperationId)
    {X Y : State} (plan : ArchitectureEvolution State X Y)
    (hStart :
      StateInSafeRegion package.observation package.targetRegion X)
    (hRealizes : script.RealizesEvolution package.semantics plan)
    (hSupport :
      package.kernel.ScriptUsesSupport script.operations plan) :
    SignatureTrajectoryInSafeRegion package.targetRegion
      (package.TargetTrajectory plan)

For example, good APIs, good examples, clear ownership, narrow modules, and domain states represented in types increase the local discoverability of good operations.

Conversely, a huge common module, implicit global context, ambiguous services, and overly convenient helpers increase the local convenience of bad operations.

From this viewpoint, refactoring is not only cleaning up the current structure. It is also a basin-reshaping operation that changes the future operation distribution.

In the measurement layer, one tooling-side metric candidate to watch here is SupportRiskMass.

SupportRiskMass(C) =
  sum over op in support(C) of weight(op) * risk(op, C)

Here again, it is important not to reduce risk to a simple 0 / 1.

In AAT terms, we should distinguish at least:

safe-preserving proved
safe-preserving measured
safe-preserving estimated
unsafe witness measured
unmeasured
unavailable
private
notComparable
outOfScope

Unmeasured must not be read as zero. This is a central principle in both ArchSig and AAT.

6. The Same Signature Does Not Imply the Same Future

An important point is that two states can have the same current Architecture Signature but different future operation distributions.

For example, two modules might show the same number of dependency violations, the same test coverage, and the same complexity. But one may have a good canonical example nearby, while the other may contain many bad shortcuts.

Even if the current observation values are the same, future PRs may be attracted in different directions.

Obs(X) = Obs(Y)
  does not imply
OperationSupport(X) = OperationSupport(Y)

This is why architecture quality should not be judged by snapshot metrics alone. The current value can be the same while the future force field is different. Attractor Engineering treats this future force field as a design object.

7. Accepted Preservation and Support Preservation Are Different

There is another important separation.

Suppose review and CI ensure that merged PRs preserve a safe region.

Even then, unsafe operations may still remain inside operation support.

This separation is not just a warning. It appears on the Lean side as a finite counterexample. Accepted-step invariant preservation can hold, and an accepted safe step can exist, while operations that do not preserve the safe region remain in support.

theorem acceptedPreservation_not_supportPreservation_counterexample :
    (∃ (t : ArchitectureTransition ExampleState safeState safeState),
      control.AcceptedStep t ∧
        StepPreservesSafeRegion control.observation control.invariant t) ∧
    (∀ {X Y : ExampleState} (t : ArchitectureTransition ExampleState X Y),
      control.AcceptedStep t ->
        StepPreservesSafeRegion control.observation control.invariant t) ∧
    (∃ X op,
      kernel.Supports X op ∧
        ¬ semantics.OperationPreservesSafeRegion control.observation
          control.invariant op)

This is the difference between guardrails and attractor engineering.

Strong guardrails may stop bad PRs.

But a field where bad PRs are produced in large numbers every time is still not a good field.

A good field is one where bad operations are less likely to appear in the first place, and good operations are natural, easy to imitate, observable, and low-friction.

8. PRs Are Non-Commutative

PRs are generally non-commutative.

PR_2 o PR_1 != PR_1 o PR_2

Of course, this only makes sense when both orders can be applied. Even then, the same two PRs can produce different final signatures depending on merge order.

This matters in an era where AI agents can generate multiple PRs in parallel.

Even when individual PRs are locally correct, their order can change boundaries, types, tests, and semantic alignment.

I call this merge order sensitivity.

MergeOrderSensitivity(a, b, X) =
  distance(
    sigma(b(a(X))),
    sigma(a(b(X)))
  )

This is not merely a merge conflict issue. It is the non-commutativity of operation algebra branching the signature trajectory. We will need this viewpoint when evaluating teams of AI agents as well.

9. Observe the Shape of the Trajectory

Architecture Signature should be read not only as a current value, but also as a trajectory.

Even if the endpoint is safe, the path may have passed through a bad region.

Even if net delta is zero, there may have been large churn inside the path.

endpoint safe
  does not imply path safe

net force zero
  does not imply no excursion

This is also proved in Lean as a small finite counterexample. In a trajectory such as 0 -> 2 -> 0, both endpoints are the same safe state. The endpoint delta and net delta can both appear to be zero, while the path passed through an unsafe region.

theorem netSignatureDelta_eq_zero :
    NetSignatureDelta (SignatureDeltaSequence observation signedNatDelta
      excursionPlan) = 0

theorem endpointSafe_and_zeroDelta_but_not_pathSafe :
    EndpointSignatureDelta observation signedNatDelta excursionPlan = 0 ∧
      StateInSafeRegion observation safeRegion 0 ∧
      StateInSafeRegion observation safeRegion 0 ∧
      ¬ SignatureTrajectoryInSafeRegion safeRegion
          (SignatureTrajectory observation excursionPlan)

Trajectories have shapes.

What ArchSig really wants to observe is this trajectory.

Not just the evaluation of one PR, but the resulting motion produced by a group of PRs.

10. Expanding Observation Can Suddenly Reveal Badness

With coarse observation, a codebase may look safe.

But if we add more observation axes, a hidden obstruction may suddenly appear as nonzero.

coarse observation:
  safe

refined observation:
  hidden obstruction appears

We can call this an observability expansion shock.

The important point is that this does not necessarily mean the architecture got worse. It may simply mean that an axis that used to be invisible has become visible.

That is why ArchSig must distinguish unmeasured from zero. When something that was not measured becomes visible, we must separate "the architecture got worse" from "the observation became better".

About the Lean Formalization

The structure above is not built only from metaphor. Some of the core vocabulary of AAT has been implemented as Lean definitions and theorems under Formal/Arch.

The repository is AlgebraicArchitectureTheoryV2. The proved API is summarized in the Lean definition and theorem index.

The vocabulary used in the second half of this article mainly corresponds to Formal/Arch/Evolution/SignatureDynamics.lean and Formal/Arch/Evolution/AttractorEngineering.lean.

The role of Lean formalization is not to give this theory an aura of correctness. Its role is to record, with boundaries, what can be said under which universe, observation, coverage, and exactness assumptions.

It is important that counterexamples live in the same place as proved theorems.

proved:
  accepted evolution preserves selected invariant
  bounded sampled support-preserving script stays in target region
  selected additive delta telescopes over finite path

proved counterexamples:
  endpoint safe + zero delta does not imply path safe
  accepted preservation does not imply support preservation
  unmeasured axis is not available-zero evidence

Conversely, the fact that something is proved in Lean does not mean that a real-world code extractor is complete, or that every runtime / semantic obstruction has already been observed. With this boundary, AAT can separate what is formally known, what depends on measurement, and what remains an empirical research question.

Conclusion

The discovery of Attractor Engineering changes how I see software architecture: from a static blueprint to a field that guides future changes.

If software architecture is read as an algebraic structure, feature additions and refactorings become operations.

When those operations are repeated, the architecture state draws a trajectory.

We can then ask where that trajectory tends to go, and where it tends to stay. This is where attractors and basins enter the picture.

Architecture design in the era of AI-assisted development can be described as creating a field where future changes gather in good places and can escape bad places.

Harness engineering becomes the engineering of receiving AI's change force, dissipating unwanted components, and guiding the system toward good attractors.

ArchSig is the tool for observing that trajectory.

The essence of AI-assisted development is not only producing PRs faster.

It is deciding where fast force should converge.

A codebase is a field.

A PR is a force.

CI/CD is a dissipative system.

Product managers, product owners, engineers, reviewers, and AI agents are participants in the field.

ArchSig is an observer of the trajectory.

With this framing, development in the AI era is no longer just automation. It becomes field design.

As a design theory for that purpose, Attractor Engineering may be a useful direction for both practice and research.