Topology Preserving Transformation¶
Change a system's shape, scale, organization, or representation while preserving the connectivity relationships that matter.
The Diagnostic Story¶
Symptom: A migration moves the objects but loses references, ownership paths, dependencies, or history. A reorganization creates cleaner reporting lines but breaks informal communication and escalation routes. A refactor passes isolated tests but breaks downstream consumers because relation contracts changed silently. Planners focused on visible form, ownership categories, or efficiency while severing the connections that made the system function.
Pivot: Identify the relationship invariants that must survive — dependencies, adjacency, lineage, permissions, service routes, handoff sequences — map the current topology at the necessary level of detail, define which transformations are permitted around those invariants, execute the change, and verify that connectivity has been preserved.
Resolution: Transformation becomes safer and breakage is caught before it propagates. Design tradeoffs are visible because required relationships are explicit before the change starts. Continuity is auditable, and any broken links are deliberately documented rather than silently lost.
Reach for this when you hear…¶
[data platform engineer] “We migrated everything to the new schema and the tables look great, but three dashboards broke because the foreign key relationships were never documented and nobody mapped them before the move.”
[organizational designer] “The restructure cleaned up the org chart but killed the informal escalation path that everyone actually used — now complaints go nowhere because the formal channel was never how it worked.”
[cloud infrastructure architect] “The refactor passed all unit tests but we broke two downstream services because we changed an interface contract that was never in the spec — we needed to map dependencies before touching the code.”
When This Archetype Applies¶
Complete catalog groundingAt least one sufficient condition set is fully represented by existing primes or domain-specific abstractions.
Diagnostic problem
A transformation is underway or needed, but planners are focusing on visible form, ownership, categories, components, or efficiency while risking the loss of the connectivity relationships that make the system function.
What this problem means
The structural problem is relation loss under form change. A system can be transformed in a way that looks cleaner, faster, or more modern while silently destroying the paths that carried work, meaning, accountability, service, or risk control.
A migration can copy objects but lose references. A reorganization can produce a simpler chart while breaking collaboration paths. A refactor can preserve function locally while breaking downstream consumers. A workflow simplification can remove a step that looked redundant but actually preserved context or authority.
Show the applicability expression
Applicability expression4 distinct conditions
groundedpartly groundedopen
4 conditions, all required.
4Required in every casenumbered 1–4
These hold no matter which pattern applies.
Structural transformation need · grounded
A system must be migrated, reorganized, refactored, simplified, scaled, compressed, or represented differently.
This is a load-bearing situation condition in the diagnostic expression. The condition is: A system must be migrated, reorganized, refactored, simplified, scaled, compressed, or represented differently. If it does not hold, this particular condition set is incomplete.
Relation-defined elements · grounded
The things being moved or changed are meaningful because of their relations: dependencies, adjacency, lineage, permissions, communication paths, service routes, or handoff sequences.
The archetype is strongest when the relevant relationships can be named: adjacency, reachability, dependency, lineage, ownership, permission, handoff, interface, sequence, or continuity. The narrower requirement in this condition set is: The things being moved or changed are meaningful because of their relations: dependencies, adjacency, lineage, permissions, communication paths, service routes, or handoff sequences.
Unspecified preserved relations · grounded
A proposed change optimizes local boxes, labels, or components but does not state which relationships must survive.
Use it when a migration, reorganization, refactor, simplification, redesign, or representation change might break important relationships. The narrower requirement in this condition set is: A proposed change optimizes local boxes, labels, or components but does not state which relationships must survive.
Valuable legacy topology · grounded
The old form is costly or obsolete, but some of its relation structure remains valuable and must be carried forward.
The structural problem is relation loss under form change. The narrower requirement in this condition set is: The old form is costly or obsolete, but some of its relation structure remains valuable and must be carried forward.
Other requirements and context (1)
Why these sit outside the expression
Supporting context — it may accompany or help interpret the situation, but it is not a load-bearing condition in a sufficient diagnostic set.
Supporting contextStakeholders worry that a redesign will orphan users, records, teams, services, interfaces, or responsibilities.
Typical warning signs include orphaned records, broken handoffs, isolated teams, lost dependency context, incompatible interfaces, or a plan that reorganizes components without stating which paths must remain connected. In this archetype, the relevant contextual consideration is: Stakeholders worry that a redesign will orphan users, records, teams, services, interfaces, or responsibilities. It helps interpret the situation or strengthens the practical case for examining the archetype.
Coverage
4 of 4 conditions grounded.
Mechanisms / Implementations¶
- Graph Difference Review: Lays the before and after topology side by side as nodes and edges and computes the delta — the connections lost, added, weakened, or rerouted — so a transformation's structural changes are seen rather than assumed.
- Reachability Test: Checks that every required endpoint pair can actually reach each other over a usable path, turning 'looks connected' into a pass/fail verdict against a stated spanning criterion.
- Relational Data Migration Check: Validates that the links between migrated records — ownership, references, permissions, lineage, hierarchy — still resolve in the target system, because copying the values is not the same as preserving the relationships, and routes every broken link to a reconciliation queue.
- Interface Contract Test: Turns the promises a delegated host interface makes — permissions, isolation, error and capacity behavior, and what happens when the host is unavailable — into automated pass/fail checks, so delegation is verified rather than assumed.
- Handoff Continuity Walkthrough: Follows a single real case step by step through a redesigned workflow and checks that at every handoff the context, authority, timing, and responsibility the case needs still travel with it.
- Organizational Path Preservation Review: Maps a reorganization's informal social pathways — communication, escalation, expert-consultation, decision — as real topology and scopes which of them must be treated as load-bearing, so a cleaner org chart does not quietly sever the routes that actually carried the work.
- Compatibility Bridge or Shim: A deliberately temporary layer that makes old local callers keep working against a newly promoted host capability during a migration — carrying them across so the duplicate facility can be retired, then expiring itself.
- Topology Regression Suite: A standing, automated battery of key-path and dependency checks that re-runs on every transformation iteration, so relation breakage a one-time review would miss is caught the moment a later change reintroduces it.
Related Abstractions¶
Abstractions this archetype builds on — directly (a source ingredient) or as a related pattern. Links follow the typed catalog namespace.
Built directly on (3)
- Invariance: Properties unchanged under transformation.
- Network: Models interactions between components.
- Topology: Studies properties preserved under deformation.
Also references 6 related abstractions
- Continuity: Smooth change without jumps.
- Interoperability: Systems function together.
- Modularity: Breaks systems into smaller units.
- Relation: Describes associations or dependencies.
- Representation: Model complex ideas.
- Robustness: Maintain functionality under stress.
Variants¶
Narrower or domain-specific specializations that share this archetype's core structure. Recognized variants are established; candidate variants are provisional.
Network-Preserving Redesign · domain variant · recognized
A redesign that changes visible structure while preserving the critical links, routes, and reachability that make the network work.
Relationship-Preserving Migration · implementation variant · recognized
A migration that moves data, processes, accounts, or responsibilities while preserving the relationships that give them meaning.
Interface-Preserving Refactor · mechanism family variant · recognized
A refactor that changes internal structure while preserving externally relied-upon interfaces and dependency relations.
Editorial Notes¶
Problem Classification¶
Classification: Correctness, Conformance & Formal Validity Failure → Mapping, Rewrite & Structure Preservation
Problem kernel: transformation preserves visible objects but destroys functional topology
Rationale: Earliest causal condition: A transformation is underway or needed, but planners are focusing on visible form, ownership, categories, components, or efficiency while risking the loss of the connectivity relationships that make the system function.
Independent corroboration: The earliest necessary condition in the frozen evidence is: A transformation is underway or needed, but planners are focusing on visible form, ownership, categories, components, or efficiency while risking the loss of the connectivity relationships that make the system function. That is a mapping rewrite and structure preservation problem because Translation, replacement, inversion, lowering, or transformation changes meaning, reachability, connectivity, correspondence, or invariants that were required to survive.
Review outcome: Independent reviewer agreement; high confidence.