Chapter 15: Contracts That Keep Services Independent¶
Shared Infrastructure Without Shared Fate¶
1. Independence Is a Contract, Not a Boundary¶
The three structures scale by staying separable. Two services can share a database, a cluster, a network — and remain independent — only if each owns something the other cannot change. The moment they share a table, an upgrade or a bad migration takes both down together, and the failure is not the migration's: it is the ownership model's.
Shared infrastructure is a cost decision. Shared fate is an architecture decision, and it is usually made by accident.
💰 Cost Check: a shared schema saves a migration and costs an outage that two teams argue about. A destructive statement saves a review and costs the tables it removed. Expand/contract costs three deploys instead of one and buys the ability to release in any order. The expensive choice is the one that looks like speed and is paid by someone else's release.
🎯 What You'll Learn¶
- Why shared infrastructure is fine and shared fate is not
- The per-service ownership model: schema, version range, applier
- Expand/contract migrations, and the ban that makes them safe
The Two Failures¶
| Failure | The cause | The shape of the fix |
|---|---|---|
| one migration breaks a neighbour | nobody owned the schema | a schema per service, an applier per owner |
| one deploy needs another's release | a shared contract with no version | version ranges, contract tests |
flowchart LR
S1["service A"] --> SA["schema A<br/>range 1000–1999"]
S2["service B"] --> SB["schema B<br/>range 2000–2999"]
SA --> D["shared platform"]
SB --> D
SA -.->|"never"| SB
What this shows: one platform, two owners — the dashed edge is the one that must not exist.
The Configuration Seam¶
The seam you have already met sits between two systems; it also sits between logic and environment. A contract between services also applies to how automation interacts with different environments. We enforce a configuration seam: a strict boundary where the immutable automation logic meets the environment context. By routing all environment variables, secrets, and endpoints through this validated seam, we ensure that the automation behaves predictably whether it is provisioning a local development sandbox or a production cluster. The logic never changes; only the environment context injected at the seam does. This is how we prevent configuration drift and guarantee idempotent, reversible deployments.
✅ What to Check¶
- Which of your services share a schema? That is shared fate, whatever the diagram says.
- Does any migration apply without verifying that a neighbour's objects still exist?
2. Per-Service Ownership¶
A schema of its own. Not a table prefix — a schema, so the boundary is structural rather than a naming convention.
A migration version range. Disjoint ranges mean two services never write the same version number, and an applier can apply "mine" without guessing.
An applier that verifies its own objects and its neighbours' presence. The migration that drops a sibling's table is the failure this exists to prevent, and it is caught by a post-condition: my schema is complete, and every sibling schema still exists.
The Applier's Post-Conditions¶
apply migrations in my range, in order
assert: my schema contains the objects my migrations declare
assert: every sibling schema declared in the manifest still exists
fail loudly, at the applier, if either assertion is false
A destructive statement — drop, truncate, an unbounded delete — is refused by the gate unless it is declared, reviewed and owned. The ban is not caution; it is the difference between a migration and an outage.
✅ What to Check¶
- Does each service own a schema and a disjoint version range?
- Does your applier assert that siblings still exist? A reset that fails hours later as someone else's outage is the failure here.
3. Expand/Contract¶
A live deploy runs old and new code together for a window. A migration that renames a column in one step breaks the old code during that window — so the change is split:
| Phase | The change | What is true |
|---|---|---|
| expand | add the new column; write to both | old code works, new code works |
| migrate | backfill | both columns agree |
| contract | drop the old column | only the new code exists |
Each phase is a separate deploy, with its own verification. The compatibility window is not an inconvenience; it is the design, and it is what makes a migration independent of the order services deploy in.
Verify against a snapshot in CI. A migration that has never run against a realistic dataset has been reviewed, not tested.
✅ What to Check¶
- Does any migration both add and remove in one step? That is a break waiting for a window.
- Has the last migration run against a production-shaped snapshot?
4. Least Privilege and Contract Tests¶
Least-privilege per-service roles. A service's credential can reach its own schema and nothing else. Anything wider is an incident waiting for a mistyped query.
Contract tests between services. Each service tests against the contract its neighbour publishes — the fields it promises, the errors it returns — not against the neighbour's implementation.
Registries for ports, surfaces and environment variables. A port is a contract with a number; a surface is a contract with an address; an environment variable is a contract with a name. Each needs one home.
What Agents Write, What a Human Signs¶
- Agents write: migration code within the range, tests, contract updates that follow the pattern.
- A human signs: anything destructive, anything crossing an ownership boundary, any change to a shared contract.
The line is not about capability. It is that a destructive change and a cross-ownership change are the two where a wrong answer is expensive and irreversible, and those are the ones a human should own.
✅ What to Check¶
- Can a service's role reach anything outside its schema?
- Does each cross-service call have a contract test, or an assumption?
5. Build the Workbench¶
Artefacts¶
| Artefact | What it is for | Where it lives |
|---|---|---|
| ownership manifest | service · schema · version range | the suite manifest |
| applier | applies its range, asserts its objects and its siblings' | the repository's scripts |
| contract set | the promises each service makes | contracts/<service>/ |
| destructive gate | refuses an undeclared destructive statement | the gate |
The ownership manifest, as a shape — one row per service:
# suite manifest — the ownership record
services:
- name: <service>
schema: <schema name>
versions: <1000-1999>
applier: <path>
destructive_statements: <declared ids, reviewed>
Decisions¶
| Choice | Default | What changes if you choose otherwise |
|---|---|---|
| schema per service | yes | a shared table is shared fate |
| version ranges | disjoint, per service | two services writing the same number |
| migrations | expand/contract, phase per deploy | a rename that breaks a running version |
| destructive statements | declared, reviewed, gated | an outage that passed review |
✅ Checks¶
- The applier fails when a sibling schema is missing.
- A destructive statement without a declaration is refused.
- A cross-service call has a contract test.
Sequence¶
- Declare ownership — schema and range per service. Checkpoint: no two services share a schema.
- Write the applier's post-conditions. Checkpoint: a planted drop of a sibling fails it.
- Split the next migration into expand · migrate · contract. Checkpoint: each phase is a deploy.
- Add the destructive gate. Checkpoint: an undeclared drop is refused.
🎯 Done When¶
- Every service owns a schema and a disjoint range.
- A migration cannot remove a sibling's objects without failing.
- A live deploy runs two versions without a migration breaking either.
6. 🔑 Chapter Summary¶
Shared infrastructure is affordable; shared fate is not.
- Independence is a contract — a schema, a version range, an applier that verifies.
- The applier asserts its own objects and its siblings' presence — a reset fails where it happens.
- Expand/contract is the only pattern that survives two versions running at once.
- Least privilege and contract tests make the boundary enforceable.
- Agents write the migrations and tests; a human signs the destructive and the cross-ownership change.