When every consumer must rewrite integration logic because an internal platform changes its engine, the migration has become an organization-wide change program.
Some consumer work may be necessary. A new guarantee, domain model, security boundary, retention policy, or supported version can change the contract in a way that consumers must address.
The rest is different. It exists because implementation details crossed the platform boundary. Engine clients, deployment assumptions, operating procedures, and internal topology became part of each consumer's product.
Before funding a migration, separate those two kinds of work. The distinction shows whether the organization is paying for a real capability change or paying again for an old boundary decision.
The hidden migration budget
Platform migrations are often estimated inside the platform team. That estimate may cover the new engine, data movement, infrastructure, reliability work, and the platform's own cutover.
It may exclude the larger coordination surface:
- product teams changing clients or adapters;
- consumers revising deployment and configuration logic;
- duplicated regression testing across several roadmaps;
- temporary support for old and new operating procedures;
- incident risk while ownership is split between versions; and
- sequencing work when every consumer cannot move at the same time.
Those costs do not disappear because they sit in other teams' plans. They are part of the migration.
A platform can therefore complete its infrastructure work while the organization remains halfway through the change. The engine is new, but the company still carries two contracts, two support paths, and a queue of consumer dependencies.
Consumer work is diagnostic evidence
List every action a consumer must take for the proposed migration. Do not begin by deciding that the action is reasonable. First identify its cause.
For each action, ask one question:
Would this work still be required if the platform preserved the same outcome, guarantees, ownership boundary, and supported behavior?
If the answer is yes, the work may reflect an actual contract change. The platform should name that change, explain why it is necessary, and govern its adoption.
If the answer is no, the work exists because machinery leaked through the existing boundary. That work is evidence about the product design of the platform, not merely an inconvenience for consumers.
Consider an illustrative durable-event capability. Replacing one transport engine with another may require internal data movement and operating changes. Consumers may still need work when the new design changes delivery guarantees, event semantics, security controls, or supported versions.
Consumers should not need synchronized rewrites only because the platform changed its internal client, topology, deployment model, or operational tooling while preserving the same promise.
A wrapper is not automatically a stable boundary
Adding an API, SDK, portal, or adapter can reduce visible complexity. It does not by itself create implementation freedom.
The boundary remains coupled when consumers still depend on engine-specific failure modes, deployment rules, configuration concepts, upgrade sequences, or operating tasks. The wrapper may centralize access while leaving the migration contract distributed.
Test the boundary with a credible replacement, not with the current implementation running normally. Ask what would happen if the engine, vendor, runtime, or hosting model changed while the consumer outcome remained stable.
The answer should identify which consumer responsibilities are intentional and which are historical leakage.
Some coordinated migrations are legitimate
Zero consumer work is not the standard.
A platform may deliberately change a guarantee because the old one is too expensive or unsafe. A domain model may need a new version. A security boundary may require stronger identity or authorization. A retention policy may change because of legal or operating constraints.
These are contract decisions. They need an owner, evidence, communication, compatibility rules, and an exit condition for the old behavior.
Calling all consumer work leakage would hide those decisions. The useful standard is narrower: implementation change should remain inside the platform unless the capability contract itself changes.
Review the migration at portfolio level
Before approving the work, ask for one migration ledger with four fields:
- the consumer action;
- the capability or implementation change that causes it;
- the team that owns the action and the decision; and
- the coordination, testing, support, and timing cost it creates.
The ledger does not need false precision. Its purpose is to expose work that would otherwise be distributed across roadmaps and support queues.
It can also change the investment decision. A more expensive platform-side compatibility layer may be cheaper than coordinated work across many consumers. A staged contract version may preserve reversibility. A proposed feature may be less urgent than repairing the boundary that makes every future migration costly.
The migration test is therefore a product and portfolio review, not only a technical design check.
Classify the consumer work before approving the migration. Necessary contract change deserves a governed program. Work caused only by exposed machinery is the cost of a boundary that should be repaired.
Capability contracts are a conceptual operating model. This field note does not assess a named product, vendor, or organization.