Architecture–Implementation Gap

1. What is the actual failure?

Suppose an architecture diagram says billing must not reach persistence directly and must use a declared port. The import graph is clean, yet runtime registration injects a raw persistence writer into BillingService. The boundary looks correct on paper while execution bypasses it. An Architecture–Implementation Gap is a disagreement between valid architecture intent and the path actually implemented or executed, not merely a difference between two documents.

2. Intent and implementation are separate artifacts

Architecture intent states the valid rule, responsibility owner, dependency direction, and authorized exceptions. Implementation evidence is different: imports, runtime wiring, registrations, call paths, data flow, and architecture tests. Neither artifact silently overrides the other. When they disagree, build an evidence chain first and then determine whether the documentation is stale, the evidence is incomplete, or the implementation actually violates the boundary.

3. What makes an architecture rule testable?

A useful rule needs at least a subject, an allowed or forbidden relationship, a boundary or owner, and a decision authority. For example: “billing may depend on BillingRepositoryPort, but it must not import or call a concrete storage implementation directly.” A vague statement such as “keep the layers separate” is too weak for an auditable divergence record.

4. An import graph is only part of implementation

A direct import can expose obvious accidental coupling, but the absence of a direct import does not prove the architecture is healthy. A dependency-injection container, service locator, callback registration, plugin loader, or generated wiring can create a runtime path that is invisible in the source import graph. Architecture Implementation Divergence Record v1 therefore keeps observed_structure and runtime_path separate.

5. Locate the first supported divergence

Do not start from the final symptom and invent a root-cause story. Write the rule, capture observed structure, reconstruct the runtime path when available, and locate the first point where evidence departs from valid intent. A direct billing -> persistence.sql_repo import with no authorized exception can be that first divergence. If imports are clean but runtime registration injects a forbidden writer, the divergence is in wiring rather than the source import graph.

6. Not every cross-boundary edge is a violation

A bounded, authorized exception may exist. A read-only reconciliation path, for example, may be allowed to consume one persistence read model directly. The edge is real, but when its scope, authority, and materiality match the exception, it must not be reported as accidental coupling. A rule without exception_authority is incomplete. “This edge looks unusual” is not evidence of a violation.

7. Sometimes the code is right and the documentation is stale

An old diagram can still show legacy_store as the owner even after a valid ADR moved ownership to platform_storage and the implementation follows that newer decision. Changing the code to match the old picture would be the wrong repair. The bounded problem is stale documentation, so the repair target is the architecture view or documentation. Distinguish valid current intent from a merely older artifact.

8. A material gap changes the governed boundary

Not every difference is material. Renaming a box or traversing an authorized generated adapter may leave the architecture rule intact. Materiality rises when ownership, dependency direction, data access, runtime call path, or a required control is bypassed. The record ties impact to the lesson's rule instead of declaring every structural difference a failure.

9. Negative evidence and OPEN

A defensible diagnosis rejects at least one competing explanation with a bounded probe. If no direct import exists, that negative evidence weakens direct-import coupling, but runtime bypass is still possible. If runtime registration or decision authority is unavailable, do not convert the unknown into fact. Preserve OPEN_BOUNDARY_UNRESOLVED and state exactly which evidence is required for closure.

10. Containment is not repair

Containment can disable a hotfix path, limit rollout, or temporarily redirect a problematic binding to a supported route. Repair restores the governed boundary: remove the direct import, route through the port, correct runtime registration, or update stale documentation to the current decision. Containment reduces blast radius; repair restores the architecture contract.

11. A green rerun without a recurrence sensor is not closure

After removing an import, a functional test can turn green. That only shows that the current symptom was not reproduced. If nothing can independently detect the same architecture violation when it returns, the claim “repair is closed” exceeds the evidence. The sensor may be a static architecture test, a runtime binding assertion, or a review-based rule. For this lesson, closure requires a sensor capable of detecting recurrence of the same boundary violation.

12. Worked case: do not confuse the hotfix with the exception

The main fixture contains billing, service_boundary, and persistence. A hotfix introduces one unauthorized direct path while a read-only reconciliation edge has a valid exception. The learner must classify the direct path as the material gap and preserve the authorized edge. Reporting both as violations means topology was used as the decision rule instead of intent, authority, and evidence.

13. Transfer: capability packages and generated adapters

The transfer moves ownership from modules to capability packages and explicitly permits generated adapters. A cross-package edge into an authorized generated adapter is therefore not a violation by itself. The same fixture also contains another capability that reaches internal storage directly without an exception. Rebuild the record from scratch: keep the allowed generated path, evaluate the direct internal path, and interpret the rule in the changed context.

14. Lab and 64 assertions

FLR002-LAB1 is fully local, deterministic, and synthetic with eight fixtures. The evaluator checks eight dimensions per case: intent rule, observed structure, runtime path, exception authority, materiality, repair target, recurrence sensor, and bounded unknowns. Eight cases times eight dimensions yields 64 assertions. Learner-visible fixtures expose observations but not the hidden expected classification.

15. Exit checklist

To exit independently, state the rule and owner explicitly; keep structure separate from runtime path; inspect exception authority before a violation verdict; distinguish stale documentation from code violation; reject at least one alternative with negative evidence; preserve OPEN when evidence is missing; separate containment from repair; and define a recurrence sensor that can be exercised by reintroducing the mutation. This lesson proves only the bounded synthetic mechanism and makes no claim about any real production repository.