Happier Compatibility

Happier Compatibility

Preserve real released and prospective predecessor behavior at system seams without preserving undeployed internal architecture or creating speculative compatibility debt.

Read docs/compatibility.md before acting. Also read the owning package instructions and the domain document for the affected protocol, feature, encryption, provider, installer, or persistence surface.

1. Classify the surface

Name the observable contract and classify it as wire, semantic, persistence, operational/installer, or internal-only.

If the change is internal-only and leaves external readers, writers, artifacts, and rollout behavior unchanged, stop the compatibility workflow. Do not create a matrix, shim, migration, or compatibility test merely because code moved.

2. Establish evidence-backed baselines

• Resolve active stable and preview baselines independently for every affected component. Record immutable version tag, commit, and artifact/deploy evidence; do not use a rolling tag alone as the final basis.
• Include older versions only when explicitly supported.
• Exclude dev builds, undeployed internal paths, and abandoned intermediates from lasting obligations.
• Apply any repository-specific predecessor rule in docs/compatibility.md. When it requires a live sibling worktree, inspect committed, staged, and unstaged code without modifying it and label observed versus inferred behavior.

Do not proceed from a vague claim such as “the old client probably sends this.” Inspect the released/predecessor producer, reader, serializer, artifact, or pinned golden vector.

Before building against an external or another-program-owned contract, characterize its success, failure, cancellation, and recovery behavior as provenance-pinned RED fixtures or runtime observations. Freeze the exact contract basis for the implementation/review slice; do not repeatedly review line-level adapters against a moving producer.

3. Map the corridor and close split-brains

Inventory the canonical owner and all affected producers, consumers, readers, writers, parsers, serializers, registries, decisions, persistence shapes, tests, and adapters.

Search the touched corridor for same-concept split-brains and similar-but-different logic. Reuse, extend, refine, extract, consolidate, migrate, or remove at the canonical owner. A compatibility adapter may translate a historical shape, but it must delegate domain decisions to that owner rather than becoming another active implementation.

Do not unify coincidental similarity across distinct bounded contexts. Name and verify the distinction when similar logic remains separate.

4. Build only the affected skew matrix

For each old/new direction that can occur, record:

• producer/writer version and component;
• consumer/reader version and component;
• upgrade, coexistence, rollback, or persisted-data reason;
• required, unreachable, or intentionally unsupported, with rationale;
• deciding contract/vector test and any risk-selected end-to-end flow.

Cover new-reader/old-writer by default. Cover old-reader/new-writer only when independent rollout, coexistence, or rollback makes it reachable. New-client/old-server behavior must negotiate capabilities or degrade safely; old-client/new-server behavior preserves released wire and semantics.

For every new request header reachable from a cross-origin web client, treat browser preflight as part of the compatibility seam. Capture the exact Access-Control-Request-Headers, verify it against the supported predecessor relay's Access-Control-Allow-Headers, and exercise that predecessor's real OPTIONS response. Changing only the new server allowlist is insufficient. Prefer CORS-safelisted headers, query/URL negotiation, or typed request bodies; emit a necessary custom header only after peer capability negotiation unless supported predecessors already allow it. Custom response headers additionally require Access-Control-Expose-Headers before browser code can read them.

Do not expand unaffected roles into a Cartesian product. Broaden only when a shared protocol, persisted shape, installer/service state, or deployment order couples them.

5. Choose the narrowest safe transition

Prefer additive compatible evolution. When that is insufficient, use prepare/expand → activate/migrate → contract:

1. deploy readers that accept old and new while writes remain old;
2. verify every supported reader that can see the new shape is ready;
3. activate canonical new writes;
4. migrate or backfill historical data when required;
5. remove old support only after its explicit support/removal condition is proven.

Keep feature/capability decisions fail-closed and canonical. Do not add dual writers, fallback domain logic, or multiple registries to simulate compatibility.

For remote-dev → dev, port the proven observable contract after its source vertical has passed the required automated and live gates. Re-derive ownership and surrounding assumptions in dev; port intent and fixtures, not dirty-tree topology, dormant scaffolding, or unreleased intermediate migrations.