Skip to content

Lineage Impact Analysis Report

Impact-analysis artifact — instantiates Controlled Inheritance Propagation

Traces a proposed ancestor change forward to every descendant it would touch, so the blast radius — and the inherited risks it disturbs — is known before the change ships.

Lineage Impact Analysis Report is the look-before-you-leap mechanism. Before an ancestor changes — a base class, a root config value, a parent policy, a base image — it traces the change forward through the inheritance graph and enumerates every descendant that would inherit it, then records the risk each inheritance carries. Its defining idea is that it is directional and predictive: where an effective-state diff looks backward ("where did this value come from?"), this report looks forward ("if I change this ancestor, who breaks?"). The result is a blast-radius map paired with a register of the inherited exposures the change would disturb — a review artifact the change-approval decision hangs on.

Example

A platform team maintains a base container image, base-runtime:v3, that about 180 service images build FROM. Security asks them to bump the embedded TLS library and drop an old certificate authority. Before merging, they generate a lineage impact report. It walks the built-from graph, lists all 180 descendants, and classifies each: 12 services pin the old CA explicitly and will break, roughly 40 exercise TLS in integration tests and need re-verification, and the rest inherit cleanly. Alongside the descendant list it carries an inherited-risk register — "old-CA removal → 12 services lose a trusted root; 3 of them are external-facing (high severity)."

The report makes no change; it turns "this should be fine" into a named, sized, owned list of who is affected and how badly. That is what lets the rollout stage the 12 breakers first and ship to the clean majority afterward, instead of discovering the breakage in production.

How it works

  • Trace downward. Start from the proposed ancestor change and walk the lineage toward the leaves, collecting every descendant that inherits the affected property or behavior.
  • Classify exposure. For each descendant, mark it inherits-cleanly, inherits-and-breaks, overrides-so-shielded, or needs-re-verification.
  • Register the risk. Compile what exposure each inheritance creates, its severity, and who owns the descendant.
  • Deliver as a review artifact. Attach the blast-radius map plus risk list to the change for a go / stage / hold decision.

Its distinguishing move is that it reasons forward and hypothetically, over the whole descendant set, about a change that has not happened yet — which is what separates it from a diff (backward, actual) and a linter (structure, no specific change).

Tuning parameters

  • Trace depth — how many generations downstream to follow: stop at direct children (fast, may miss transitive breakage) or trace to the leaves (complete, expensive).
  • Exposure classification — how finely to bucket descendants (clean / shielded / breaks / re-verify). Finer buckets guide staging; coarser ones are quicker to produce.
  • Risk-scoring basis — how severity is judged (external-facing? data-touching? owner-critical?), which decides what floats to the top of the register.
  • Override-awareness — whether the trace accounts for descendants that already override the changed property and are therefore shielded — essential to avoid crying wolf.
  • Refresh trigger — one-shot before a change, or re-generated as the lineage evolves so the blast radius stays current.

When it helps, and when it misleads

Its strength is converting "this base change should be safe" into an enumerated, owned, risk-ranked list before the change lands — the single best defense against an ancestor edit rippling into a hundred silent breakages. It also makes staging obvious: fix the known breakers first, ship to the clean majority after.

Its failure mode is that the trace is only as complete as the graph it can see. Dynamic or undeclared inheritance — runtime config, reflection, dependencies discovered at deploy — escapes a static forward trace, so a clean report can breed false confidence. An exhaustive trace over a huge descendant set can also bury the real risks in noise, tipping into analysis paralysis. And it is easily run backwards — produced after a change has already been decided, to paper the file with due diligence rather than to inform the choice. The discipline is ordinary change-impact-analysis hygiene: trace before deciding, credit the overrides that shield descendants, rank by real exposure, and treat an empty blast radius as a prompt to check the graph's completeness, not a certificate of safety.[1]

How it implements the components

Lineage Impact Analysis Report realizes the foresight side of the archetype — predicting how far a change travels and what it disturbs:

  • ancestor_change_impact_trace — its core: the forward walk from a proposed ancestor change to every descendant that inherits it, classified by exposure.
  • inherited_risk_register — the ranked log of the exposures each inheritance creates, with severity and owner, that the trace surfaces.

It does NOT resolve or display a node's current effective state — that's Effective Configuration Diff; it does not enforce structural limits on the graph — that's Inheritance Lint or Static Analysis; and it does not carry out the migration it may recommend — that's Override Expiry Workflow and its backfill plan.

Notes

The report predicts; it does not gate. It sizes and ranks the blast radius, but approving, staging, or blocking the change is a separate governance step that consumes this artifact. Keeping the analysis distinct from the decision is what lets a team improve the trace — deeper graph coverage, better risk scoring — without re-litigating who has authority to ship.

References

[1] Change impact analysis is an established software-engineering practice: identifying the set of artifacts a proposed change would affect before making it. Its value depends entirely on the dependency information being complete, which is why undeclared or dynamic dependencies are its blind spot. ↩