Skip to content

Compatibility Bridge or Shim

Migration shim — instantiates Layer-Appropriate Capability Placement

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.

A Compatibility Bridge or Shim is a stopgap layer that lets code written against an old, local facility keep working while it is redirected onto a newly promoted host capability — for the duration of a migration only. Its defining trait, and the thing that separates it from an adapter, is that it is born to die: it exists so that a duplicate local facility can be switched off without a flag-day rewrite of every caller, and it carries an expiry — a date, a traffic threshold, a ticket — after which it is removed. It is the mechanism that makes retiring a shadow platform safe and gradual instead of a risky all-at-once cutover, precisely by absorbing the old semantics until the callers have moved.

Example

A large codebase has a team-local feature-flag library that duplicates what the company's shared host flag service now does better. A Capability-Promotion Review has decided to retire the local library and consolidate on the host. But two hundred call sites use the old library's API — flags.isOn("x") — and rewriting them all at once is exactly the risky big-bang that keeps teams from ever retiring anything. So the team ships a shim: flags.isOn(...) still exists, but its body now calls the host flag service underneath, translating the old boolean-only call into the host's richer evaluation and mapping flag names across.

Now callers keep compiling and running unchanged while the local flag storage is drained and the library's own logic is deleted. Teams migrate call sites off the deprecated flags.isOn shape at their own pace — and, crucially, the shim carries an expiry: removed once fewer than 5% of calls route through it, and no later than the next major release. When that threshold is hit, the shim is deleted, the old API is gone, and the duplicate facility is fully retired. The bridge did its one job — carrying callers across — and then got out of the way.

How it works

What distinguishes a shim from a permanent translation layer is that everything about it is aimed at its own removal:

  • Preserves the old face, redirects the body. The deprecated local API keeps its exact signature so callers don't change, but underneath it now delegates to the promoted host capability.
  • Maps old semantics onto new. It translates the narrower old behavior into the host's contract, filling gaps with safe defaults, so callers see continuity while the real work moves.
  • Carries a hard expiry. A date, a traffic threshold, or a release boundary is attached at creation — the shim is scheduled for deletion, not left to become permanent scaffolding.
  • Drains and measures. Traffic through the shim is tracked so retirement of the duplicate facility is triggered by evidence that callers have moved, not by assumption.

Tuning parameters

  • Expiry trigger — a fixed date, a usage threshold, or a release boundary. Date-based expiry is predictable but can arrive before callers are ready; usage-based expiry waits for reality but can drift forever if nobody enforces the ceiling.
  • Semantic-gap handling — how the old, narrower behavior is mapped onto the richer host contract. Faithful mapping minimizes surprises but is more work; default-filling is cheap but can subtly change behavior for edge-case callers.
  • Visibility of deprecation — silent pass-through versus loud warnings on every call through the shim. Loud warnings accelerate migration but annoy; silent shims are painless and therefore never create pressure to leave.
  • Scope — one narrow deprecated call versus a broad compatibility surface. Narrow shims retire cleanly; broad ones risk becoming a permanent second interface — the very duplication being retired.

When it helps, and when it misleads

Its strength is that it de-risks the hardest part of consolidation — turning off the duplicate — by making the cutover gradual and reversible instead of a flag day. It is what lets a promotion decision actually complete, because callers keep working throughout and migrate on a human schedule rather than in a single terrifying commit.

Its signature failure is the immortal shim: the temporary bridge that quietly becomes permanent infrastructure, so now there are three things — the old callers, the shim, and the host — and two competing sources of truth the migration was supposed to eliminate.[1] A shim with no enforced expiry doesn't retire the shadow platform; it adds a layer to it. The classic misuse is reaching for a shim when no migration is actually underway — using "temporary compatibility" as a permanent excuse to avoid committing to the host. The discipline that keeps it honest is to attach the expiry at creation, make the shim's own usage visible so its death is measurable, and treat a shim that outlives its window as a bug with an owner, not a fixture.

How it implements the components

A shim realizes the safe-retirement slice of the archetype — it is the machinery that carries callers off a duplicate facility onto the host:

  • duplicate_facility_retirement_path — it is the path: the temporary bridge that lets the local duplicate be switched off gradually rather than in a single break, and it is complete only when the duplicate is gone.
  • portability_and_compatibility_contract — for the migration window it upholds the promise that old callers keep working unchanged, translating the deprecated semantics onto the host so compatibility holds until callers have moved.

It does not decide that a facility should be retired — that judgment is Capability-Promotion Review — and unlike Adapter Layer, whose translation is permanent, the shim's whole design is to expire. It provides no standing versioned contract; coexisting long-lived versions are API Versioning.

Notes

A Compatibility Bridge is the near-twin of Temporary Local Shim with Expiry; the difference is direction. This bridge carries callers toward a promoted host capability during consolidation — retiring a duplicate. A temporary local shim buys a subsystem a short-lived local stand-in while waiting for a host capability to arrive. Both are expiring by design, but one is completing a migration onto the host and the other is holding the line until the host is ready.

References

[1] The bridge is the enabling tactic of the strangler fig approach to migration — routing existing callers through a compatibility layer so an old system can be dismantled incrementally rather than replaced in one cutover. The pattern's own warning is that the strangler must actually finish: a migration left half-done leaves the compatibility layer as permanent added complexity. ↩