deprecation-and-migration

name	deprecation-and-migration
description	Manages deprecation and migration. Use when removing old systems, APIs, IPC methods, or features. Use when migrating consumers from one implementation to another, evolving the wire protocol or DB schema, or deciding whether to maintain or sunset existing code.

Deprecation and Migration

Overview

Code is a liability, not an asset. Every line of code has ongoing maintenance cost — bugs to fix, dependencies to update, security patches to apply, and new engineers to onboard. Deprecation is the discipline of removing code that no longer earns its keep, and migration is the process of moving consumers safely from the old to the new.

Most engineering organizations are good at building things. Few are good at removing them. This skill addresses that gap.

When to Use

• Replacing an old system, IPC method, module, or crate with a new one
• Sunsetting a feature that's no longer needed
• Consolidating duplicate implementations
• Removing dead code that nobody owns but everybody depends on
• Evolving the wire protocol (PROTOCOL_VERSION) or the conversation DB schema
• Planning the lifecycle of a new system (deprecation planning starts at design time)
• Deciding whether to maintain a legacy path or invest in migration

Core Principles

Code Is a Liability

Every line of code has ongoing cost: it needs tests, documentation, security patches, dependency updates, and mental overhead for anyone working nearby. The value of code is the functionality it provides, not the code itself. When the same functionality can be provided with less code, less complexity, or better abstractions — the old code should go.

Hyrum's Law Makes Removal Hard

With enough consumers, every observable behavior becomes depended on — including bugs, timing quirks, and undocumented side effects. This is why deprecation requires active migration, not just announcement. Consumers can't "just switch" when they depend on behaviors the replacement doesn't replicate. On a wire protocol this is acute: any attached client may rely on a field's exact shape or presence.

Deprecation Planning Starts at Design Time

When building something new, ask: "How would we remove this in 3 years?" Systems designed with clean interfaces (typed params, trait boundaries, additive serde fields), feature flags, and minimal surface area are easier to deprecate than systems that leak implementation details everywhere.

The Deprecation Decision

Before deprecating anything, answer these questions:

1. Does this system still provide unique value?
   → If yes, maintain it. If no, proceed.

2. How many consumers depend on it?
   → Quantify the migration scope (attached clients, callers, integrations).

3. Does a replacement exist?
   → If no, build the replacement first. Don't deprecate without an alternative.

4. What's the migration cost for each consumer?
   → If trivially automated (a schema migration, a renamed method), do it.
     If manual and high-effort, weigh against maintenance cost.

5. What's the ongoing maintenance cost of NOT deprecating?
   → Security risk, engineer time, opportunity cost of complexity.

Compulsory vs Advisory Deprecation

Type	When to Use	Mechanism
Advisory	Migration is optional, old system is stable	Warnings, documentation, nudges. Consumers migrate on their own timeline.
Compulsory	Old system has security issues, blocks progress, or maintenance cost is unsustainable	Hard deadline. Old system will be removed by date X / protocol version N. Provide migration tooling.

Default to advisory. Use compulsory only when the maintenance cost or risk justifies forcing migration. Compulsory deprecation requires providing migration tooling, documentation, and support — you can't just announce a deadline.

Binding decisions are recorded, not rewritten. When a deprecation changes an accepted decision, amend it with a new ADR in docs/zynk/decisions/ rather than editing the old one. The decision history is the migration record.

The Migration Process

Step 1: Build the Replacement

Don't deprecate without a working alternative. The replacement must:

• Cover all critical use cases of the old system
• Have documentation and migration guides
• Be proven in real use (not just "theoretically better") — dogfood it in the live runtime first

Step 2: Announce and Document

## Deprecation Notice: `pane.legacy_update`

**Status:** Deprecated as of protocol v14 / 2025-03-01
**Replacement:** `pane.update` (partial update — see migration guide below)
**Removal:** Advisory — no hard deadline yet
**Reason:** `pane.legacy_update` requires the full pane object on every call and
            races concurrent writers. `pane.update` accepts partial params.

### Migration Guide
1. Replace `pane.legacy_update` calls with `pane.update`, sending only changed fields.
2. Drop the now-unused full-object construction in callers.
3. Run the verification: `just check` plus the protocol round-trip test
   (`cargo nextest run pane_update`).

Step 3: Migrate Incrementally

Migrate consumers one at a time, not all at once. For each consumer:

1. Identify all touchpoints with the deprecated system
2. Update to use the replacement
3. Verify behavior matches (tests, integration checks)
4. Remove references to the old system
5. Confirm no regressions

The Churn Rule: If you own the infrastructure being deprecated, you are responsible for migrating its consumers — or providing backward-compatible updates that require no migration. Don't announce deprecation and leave consumers to figure it out. For the wire protocol this means: keep the old method working until you've migrated every attached client, or carry both behind a single negotiated PROTOCOL_VERSION.

Step 4: Remove the Old System

Only after all consumers have migrated:

1. Verify zero active usage (metrics, logs, dependency analysis, `rg` for callers)
2. Remove the code
3. Remove associated tests, documentation, and configuration
4. Remove the deprecation notices
5. Celebrate — removing code is an achievement

Migration Patterns

Strangler Pattern

Run old and new systems in parallel. Route traffic incrementally from old to new. When the old system handles 0% of traffic, remove it.

Phase 1: New system handles 0%, old handles 100%
Phase 2: New system handles 10% (canary)
Phase 3: New system handles 50%
Phase 4: New system handles 100%, old system idle
Phase 5: Remove old system

Adapter Pattern

Create an adapter that translates calls from the old interface to the new implementation. Consumers keep using the old trait while you migrate the backend. The old trait stays stable; only the impl changes.

// Adapter: old trait, new implementation underneath.
pub struct LegacyPaneServiceAdapter {
    inner: NewPaneService,
}

impl OldPaneApi for LegacyPaneServiceAdapter {
    // Old signature (numeric id, old shape); delegates to the new service.
    fn get_pane(&self, id: u64) -> OldPane {
        let pane = self.inner.find_by_id(&PaneId(id.to_string()));
        self.to_old_format(pane)
    }
}

Feature Flag Migration

Use a runtime flag/config to switch consumers from old to new one at a time:

fn pane_service(cfg: &Config, scope: &Scope) -> Box<dyn PaneApi> {
    if cfg.feature_enabled("new-pane-service", scope) {
        Box::new(NewPaneService::new())
    } else {
        Box::new(LegacyPaneServiceAdapter::new())
    }
}

Schema Migration (Conversation DB)

The SQLite store evolves via append-only, numbered, forward migrations (migrations/zynk/NNNN_name.sql, run by the embedded migrator). Never edit a migration that has shipped — add the next one. Backfill and expand-then-contract instead of rewriting in place.

-- migrations/zynk/0004_add_message_trace.sql
-- Expand phase: add the new column as nullable so old rows and old writers still work.
ALTER TABLE messages ADD COLUMN trace_id TEXT NULL;

-- Backfill existing rows from an existing source where possible.
UPDATE messages SET trace_id = id WHERE trace_id IS NULL;

CREATE INDEX idx_messages_trace ON messages(trace_id) WHERE trace_id IS NOT NULL;
-- A later migration may add the NOT NULL/contract phase, once all writers populate it.

Illustrative shape only. zynk's real message trace_id is indexed out of messages.meta_json (see migrations/zynk/0003_trace_index.sql), not a dedicated trace_id column — match the actual table you're migrating rather than copying this verbatim.

Editing an already-applied migration breaks the migrator's checksum on any existing DB. Treat shipped migrations as immutable; deprecate a column or table with a new migration.

Zombie Code

Zombie code is code that nobody owns but everybody depends on. It's not actively maintained, has no clear owner, and accumulates security vulnerabilities and compatibility issues. Signs:

• No commits in 6+ months but active consumers exist
• No assigned maintainer or team
• Failing/ignored tests that nobody fixes
• Dependencies (crates) with known advisories that nobody updates
• Documentation that references modules or commands that no longer exist

Response: Either assign an owner and maintain it properly, or deprecate it with a concrete migration plan. Zombie code cannot stay in limbo — it either gets investment or removal.

Common Rationalizations

Rationalization	Reality
"It still works, why remove it?"	Working code that nobody maintains accumulates security debt and complexity. Maintenance cost grows silently.
"Someone might need it later"	If it's needed later, it can be rebuilt. Keeping unused code "just in case" costs more than rebuilding.
"The migration is too expensive"	Compare migration cost to ongoing maintenance cost over 2-3 years. Migration is usually cheaper long-term.
"We'll deprecate it after we finish the new system"	Deprecation planning starts at design time. By the time the new system is done, you'll have new priorities. Plan now.
"Consumers will migrate on their own"	They won't. Provide tooling, documentation, and incentives — or do the migration yourself (the Churn Rule).
"We can maintain both methods indefinitely"	Two methods doing the same thing is double the maintenance, testing, documentation, and onboarding cost.
"I'll just fix that old migration in place"	Editing a shipped migration breaks every existing DB's checksum. Always add the next numbered migration.

Red Flags

• Deprecated systems with no replacement available
• Deprecation announcements with no migration tooling or documentation
• "Soft" deprecation that's been advisory for years with no progress
• Zombie code with no owner and active consumers
• New features added to a deprecated system or method (invest in the replacement instead)
• Deprecation without measuring current usage
• Removing code without verifying zero active consumers (no rg sweep, no logs)
• Editing an already-shipped migration instead of adding a new one
• A wire-format change without a PROTOCOL_VERSION bump or a parallel-support window

Verification

After completing a deprecation:

• Replacement is proven in real use and covers all critical use cases
• Migration guide exists with concrete steps and examples
• All active consumers have been migrated (verified by metrics/logs/rg for callers)
• Old code, tests, documentation, and configuration are fully removed
• No references to the deprecated system remain in the codebase
• Schema changes are new forward migrations; no shipped migration was edited
• Wire-format changes carry the correct PROTOCOL_VERSION handling
• Any changed accepted decision is amended via a new ADR, not a rewrite
• Deprecation notices are removed (they served their purpose)