Appendix B — Models-bridge patterns

Appendix B - 5. Control↔substrate dependency (computed blast-radius)

The Structure of Control↔substrate dependency (computed blast-radius) — its shape at a glance:

Each substrate-reading mechanism declares its stance in a typed field. A query joins those declarations against the substrate model and, given a migration target, prints exactly which mechanisms a change puts in scope — the blast radius, computed before you touch the substrate.

flowchart LR
  C1[Control A<br/>stance: plane-X] --> Q{Blast-radius query}
  C2[Control B<br/>stance: agnostic] --> Q
  Sub[(Substrate model)] --> Q
  Q -->|join on target| Table([in-scope mechanisms])

Accessible description: two mechanisms each declare a substrate stance. A query joins those declarations against the substrate model and, for a migration target, emits the table of mechanisms that change puts in scope. The table is derived, not hand-maintained.

Projected from the catalogue entry system-models / Control↔substrate dependency (computed blast-radius).

On this page: Intent · Motivation · Applicability · Structure · Sample Code · Consequences · Example use within DocAble · Related Patterns

Intent

Intent — Make each control declare the substrate assumption it bakes in as typed metadata, so "which controls depend on which part of the substrate, and what will break when I change it" is a computed query, not a grep-and-read. Before a cross-cutting substrate change, the static-analysis blast radius is known up front (our instance: each lint that reads the deployment-topology model declares a typed plane-assumption (GKE-only / Cloud-Run-only / plane-aware / plane-agnostic) joined against the topology to print exactly which lints a migration puts in scope).

Motivation

A control (a lint, a gate, a validator) usually bakes an assumption about the substrate it checks against: "a service is a Kubernetes Deployment under this directory," "the scaler exposes this method," "the manifest carries this field." The assumption sits buried in the control's body. It is invisible until you change the substrate.

Then the change lands and the fleet fails in two silent ways at once:

The engineer planning the migration cannot see this coming. "Which of our checks assume the old substrate?" is answerable only by grepping for who imports the substrate model, then reading each body to judge whether it bakes the old shape. The entanglement that decides the whole refactor's blast radius lives in prose and grep: exactly the invariant-that-lives-only-in-code smell, and the failure is near-certain the moment someone migrates a service without knowing which controls will misfire.

Applicability

Structure

The Structure diagram appears at the top of this page.

Sample Code

Each mechanism carries a typed stance toward the substrate. A join reads every declaration and, given a migration target, returns the mechanisms that assume the old shape — the blast radius, computed from declarations rather than grepped and read body-by-body.

from dataclasses import dataclass

# A small closed enum keeps the stance exhaustive and typed.
STANCES = {"assumes_plane_a", "assumes_plane_b", "branches_per_plane", "agnostic"}

@dataclass(frozen=True)
class Control:
    name: str
    stance: str      # one of STANCES; a topology-reading control MUST declare it

def blast_radius(controls: list[Control], migrate_to: str) -> list[str]:
    """Controls put in scope by a migration to `migrate_to` (they assume a different plane)."""
    hits = []
    for c in controls:
        assumes_other = c.stance.startswith("assumes_") and c.stance != f"assumes_{migrate_to}"
        if assumes_other:
            hits.append(f"{c.name}: stance '{c.stance}' misfires on migration to {migrate_to}")
    return hits

def undeclared(controls: list[Control]) -> list[str]:
    return [c.name for c in controls if c.stance not in STANCES]   # declaration lint

if __name__ == "__main__":
    import sys
    controls = load_controls()          # reads each control's declared stance metadata
    for line in blast_radius(controls, migrate_to="plane_b"):
        print(f"IN-SCOPE: {line}")
    sys.exit(1 if undeclared(controls) else 0)

Consequences

Example use within DocAble

Contents
⇐ Beginning of this partNext part ⇒Next chapter ›⇤ BeginningEnd ⇥Index
© James C. Davis, 2026–present