A team defends its data-access interfaces by saying the store can be swapped underneath. How would you evaluate that claim?

## What the claim actually promises "The store can be swapped underneath" means: an implementation of these interfaces could be written against a different store, and the code above would keep working unchanged. It is worth taking seriously, because a boundary that really delivers it is cheap insurance, and worth interrogating, because most boundaries deliver much less than the claim implies. Start by separating the two things a caller depends on. The **syntax** of the boundary is its method names, parameters and return shapes. The **semantics** is everything the calling code assumes about what happens when it calls: when the write lands, what is atomic, whether the result is live, what error arrives on a conflict, how long an operation takes. Swapping implementations preserves the syntax by construction. It preserves the semantics only where somebody made that a requirement. ## What travels, and what does not | Caller-visible property | Survives a swap? | Why | |---|---|---| | Method names and parameter lists | Yes | The interface is the artefact being reimplemented | | Transfer model shapes | Yes | Plain values the new implementation can also produce | | Lookup by key returns at most one | Usually | A property of the model, not the store | | Write-back of changes to returned objects | Rarely | Needs a unit of work the new store may not have | | Multi-call atomicity | Rarely | Depends on the store's transaction support and reach | | Conflict and constraint failures | Rarely | Different stores detect them at different moments | | Ordering and paging stability | Rarely | Follows the store's ordering and concurrency model | | Statement count and latency shape | No | A property of the implementation, always | | Filter and sort expressiveness | No | What one store can answer, another cannot | The row that ends most portability arguments is write-back. If callers mutate returned objects and rely on the change being written at commit, they depend on a unit of work. A store without one cannot offer that, and there is no adapter that fakes it convincingly. Every such caller has to be rewritten to make its writes explicit, which is the change the boundary was supposed to prevent. The second most expensive row is atomicity. Code that quietly relies on two boundary calls landing together assumes a transaction that spans both. Whether a replacement store can honour that - or honour it across the same span - is a property of the store, not of the interface. ## When portability is a real requirement It usually is not the scenario people imagine. Whole-store migrations are rare and are rarely made easier by an interface. What does happen: - **Moving one graph to a different store** while everything else stays put - a search index, an archive, a queue-backed write path. - **A read replica or an alternate read path** for reporting. - **A second implementation for tests**, useful, though it introduces a divergence problem of its own. All three are partial. They argue for a boundary shaped around *one* graph or *one* read, not for a uniform layer justified by a migration nobody has scheduled. ## What you actually pay to get it 1. **Return snapshots, not tracked objects.** No caller may depend on a scope watching a returned value, so writes become explicit calls. 2. **Keep the layer's own query types off the interface.** The moment callers compose filters in the layer's vocabulary, the vocabulary is the contract. 3. **Make the transaction boundary explicit and coarse.** One boundary call per unit of change is portable; a scope quietly spanning six calls is not. 4. **Write contract tests once and run them against every implementation**, including ordering, conflict behaviour and empty-result semantics - the parts that silently differ. 5. **Restrict yourself to the intersection of what the candidate stores can do**, and accept that this leaves capability on the table in the store you actually use. ## How to answer the team The honest evaluation is: the boundary is worth having, but not for this reason. It earns its keep by giving each query a name and a single owner, by putting the fetch plan in one place, by keeping query mechanics out of business code, and by making call paths testable. Those benefits are collected every week. Portability is collected once, if ever, and only if the five costs above were paid in advance. So keep the boundary, drop the justification, and if portability really is a requirement, name which store and which graph - then design for that swap specifically rather than for a generic one.