The failure usually starts when the migration is framed as a single event. Move the application. Move the database. Move all the users. Switch the traffic. Turn the old system off.

That creates a dangerous assumption: the legacy system and the new system need to exchange places all at once.

They usually don't.

If you already understand the legacy behavior, protect it with characterization tests, create migration-friendly boundaries, and compare old and new implementations, you have another option.

You can migrate one capability at a time. That changes the problem completely.

Instead of:

legacy monolith
      ↓
complete rewrite
      ↓
big-bang cutover

you can move toward:

legacy monolith
      ↓
one capability extracted
      ↓
small percentage of traffic
      ↓
observe
      ↓
expand
      ↓
repeat

The goal isn't to make the migration slower. The goal is to make each change smaller, observable, and reversible.

In this tutorial, I'll show you how to migrate a legacy monolith incrementally by:

• choosing a safe first migration slice

• defining a boundary between legacy and new code

• routing requests between implementations

• using the Strangler Fig pattern

• migrating by business capability instead of technical layer

• keeping old and new implementations running together

• introducing progressive traffic

• detecting failures before full cutover

• designing rollback paths

• handling data ownership carefully

• removing migrated legacy behavior

• using AI without turning an incremental migration into an automated rewrite

The examples use TypeScript, but the approach applies to most languages, runtimes, and architectures.

The objective is simple: make migration a sequence of controlled changes instead of one irreversible event.

Prerequisites

To follow along, you should be comfortable with:

• TypeScript or a similar language

• API and service boundaries

• integration testing

• dependency injection

• routing and reverse proxies

• database transactions

• observability

• incremental refactoring

• legacy modernization

You should also already understand the behavior of the capability you want to migrate.

Ideally, you know:

• its inputs

• its outputs

• its important business rules

• its side effects

• its dependencies

• its external contracts

• how you'll detect behavioral differences

If you haven't reached that point yet, migration may be premature.

Table of Contents

• Prerequisites

• Why Big-Bang Migrations Are So Risky

• Think in Migration Slices, Not Applications

• Choose the First Capability Carefully

• Create a Boundary Between Legacy and New

• Use the Strangler Fig Pattern

• Migrate Capabilities, Not Technical Layers

• Keep Legacy and New Implementations Running Together

• Route Traffic Explicitly

• Start with Internal or Low-Risk Traffic

• Progressively Increase Production Traffic

• Use Differential Testing Before and During Rollout

• A Small End-to-End Invoice Migration Example

• Design Rollback Before You Need It

• Treat Data Migration as a Separate Problem

• Be Careful with Dual Writes

• Decide Who Owns the Data

• Observe Business Behavior, Not Just Infrastructure

• Know When a Migration Slice Is Complete

• Remove the Legacy Path

• How to Use AI During an Incremental Migration

• Do Not Let AI Turn the Migration into a Rewrite

• A Practical Incremental Migration Workflow

• What Incremental Migration Does Not Solve

• The Complete Legacy Modernization Workflow

• Conclusion

Why Big-Bang Migrations Are So Risky

Imagine a legacy commerce application.

It contains:

customers
orders
payments
inventory
shipping
invoicing
notifications
reporting

The modernization plan says:

replace the monolith

That sounds like one project.

Operationally, it may mean changing:

runtime
framework
database
deployment model
API contracts
authentication
networking
observability
data model
business logic
external integrations

at the same time.

If the final cutover fails, the number of possible causes is enormous.

For example:

Did pricing change?

Did the database migration lose data?

Is the payment provider failing?

Did authentication behave differently?

Did the new runtime change date handling?

Did a timeout become shorter?

Did an event stop being published?

Did the new deployment configuration fail?

This is one of the central problems with big-bang migration: too many variables change together.

Incremental migration tries to reduce the number of changing variables at each step.

Think in Migration Slices, Not Applications

Instead of asking:

How do we migrate this monolith?

ask:

What's the smallest meaningful business capability we can move independently?

For example:

Calculate Order Total
Generate Invoice
Send Order Confirmation
Create Shipment
Renew Subscription
Approve Customer

A migration slice should ideally have:

clear input
clear output
known side effects
understood dependencies
observable behavior
a rollback path

That gives you something concrete to move.

For example:

Generate Invoice

might become:

input:
orderId

behavior:
load order
calculate taxes
generate invoice number
create invoice

side effects:
store invoice
publish invoice.created

output:
invoice

That's much easier to migrate than:

billing module

or:

src/services/

Business capabilities make better migration units than folders.

Choose the First Capability Carefully

The first slice matters.

I would usually avoid starting with the most critical capability in the system.

You want something meaningful enough to validate the migration approach, but not so dangerous that a mistake creates catastrophic consequences.

A useful first slice often has:

moderate traffic
limited external dependencies
clear behavior
good test coverage
few transactional boundaries
low blast radius

For example:

Generate Customer Statement

may be a better first migration candidate than:

Authorize Payment

The first migration is partly technical work, but it's also a learning exercise.

You're validating:

routing
deployment
observability
rollback
data access
testing
team workflow

before applying the pattern to more critical capabilities.

Create a Boundary Between Legacy and New

Suppose the legacy application has:

async function generateInvoice(
  orderId: string
) {
  // legacy implementation
}

Before migration, introduce a boundary:

interface InvoiceGenerator {
  generate(
    orderId: string
  ): Promise<Invoice>;
}

The legacy implementation becomes:

class LegacyInvoiceGenerator
  implements InvoiceGenerator {
  async generate(
    orderId: string
  ): Promise<Invoice> {
    // existing behavior
  }
}

The new implementation becomes:

class NewInvoiceGenerator
  implements InvoiceGenerator {
  async generate(
    orderId: string
  ): Promise<Invoice> {
    // migrated behavior
  }
}

Now the caller doesn't need to know which implementation is active.

That creates an important capability:

replace implementation
without replacing caller

which is one of the foundations of incremental migration.

Use the Strangler Fig Pattern

A common way to describe incremental replacement is the Strangler Fig pattern.

Instead of replacing the entire application at once, new behavior gradually grows around the old system.

Conceptually:

            incoming request
                   │
                   ↓
                router
              /        \
             /          \
      legacy path     new path

At first:

legacy: 100%
new:      0%

Later:

legacy: 95%
new:      5%

Then:

legacy: 50%
new:     50%

Eventually:

legacy:  0%
new:    100%

At that point, the old implementation for that capability can be removed.

The key is that the replacement happens gradually. The legacy application continues serving parts of the system while the new implementation takes over others.

Migrate Capabilities, Not Technical Layers

One tempting migration strategy is:

move database
then move services
then move APIs
then move UI

That can create long periods where every capability spans both old and new architecture.

For example:

new API
↓
legacy service
↓
new database
↓
legacy event publisher

This is sometimes unavoidable.

But whenever possible, I prefer vertical slices.

A vertical slice might be:

Generate Invoice

request
↓
application logic
↓
persistence
↓
events
↓
response

That capability can move as one coherent unit.

Then:

Create Shipment

can move separately.

Then:

Renew Subscription

and so on.

This gives you working migrated capabilities earlier. It also reduces the number of temporary cross-system dependencies.

Keep Legacy and New Implementations Running Together

During an incremental migration, coexistence is normal.

For some period of time, you may have:

LegacyInvoiceGenerator
NewInvoiceGenerator

both deployed.

That's not duplication by accident. It's part of the migration strategy.

The important question is how requests choose between them.

You may use:

feature flag
tenant
user group
request header
region
percentage rollout
specific account IDs

For example:

class InvoiceRouter {
  constructor(
    private readonly legacy:
      InvoiceGenerator,
    private readonly migrated:
      InvoiceGenerator
  ) {}

  async generate(
    orderId: string,
    useMigrated: boolean
  ) {
    if (useMigrated) {
      return this.migrated.generate(
        orderId
      );
    }

    return this.legacy.generate(
      orderId
    );
  }
}

This is deliberately simple. The important part is that routing is explicit. You know which implementation handled each request.

Route Traffic Explicitly

Avoid migration logic that's difficult to observe.

For example:

try {
  return await newService.call();
} catch {
  return legacyService.call();
}

This may look resilient, but it can hide failures.

Suppose the new implementation fails 40% of the time. If every failure silently falls back to legacy, users may see no problem. But the migration isn't healthy.

The problem is that the first version mixes two decisions together: which implementation should receive the request and what should happen when that implementation fails. Because the fallback happens inside the catch, the migrated path can fail repeatedly without producing an explicit routing signal that you can measure.

A better approach is to make the routing decision first, record it, and then call the selected implementation. That separates migration policy from error handling and gives you a clear record of how much traffic actually reached each path.

For example:

const route =
  migrationPolicy.route(request);

metrics.increment(
  `invoice.route.${route}`
);

if (route === "migrated") {
  return migrated.generate(
    request.orderId
  );
}

return legacy.generate(
  request.orderId
);

Now you can measure:

requests routed to legacy
requests routed to migrated
migration failures
fallback count
latency
business outcomes

Migration should be observable as a first-class system behavior.

Start with Internal or Low-Risk Traffic

Before routing a large percentage of customers to the migrated path, start with safer traffic.

For example:

development
test environments
internal users
staff accounts
test tenants
specific low-risk customers

This lets you validate:

deployment
routing
observability
data access
external integrations
failure handling

with lower risk.

You can then expand.

For example:

internal users
↓
1% production
↓
5%
↓
10%
↓
25%
↓
50%
↓
100%

The exact percentages aren't important, but the principle is.

Each increase should happen because the previous stage produced enough evidence.

Progressively Increase Production Traffic

Suppose you have:

10,000 invoice requests/day

Instead of switching all requests:

legacy → new

at once, route:

1%

first.

That gives roughly:

100 real requests/day

through the migrated path.

Now monitor:

error rate
latency
output differences
side effects
customer-visible failures
business metrics

If the system behaves correctly, increase traffic. If it doesn't, reduce or disable migrated routing.

The migration becomes a controlled experiment. That's very different from a cutover event.

Use Differential Testing Before and During Rollout

The previous article in this series focused on differential testing. That technique becomes especially useful here.

Differential testing means running the legacy and migrated implementations with the same input and comparing their observable behavior. Depending on the capability, that may include return values, errors, state changes, and side effects.

The goal isn't to prove that the implementations are internally identical. It's to detect meaningful behavioral differences before those differences reach all of your production traffic.

Before live routing, you can compare:

same input
↓
legacy result

same input
↓
new result

During rollout, you can also sample real traffic and compare behavior where it is safe to do so.

For example:

real request
      │
      ├────→ active implementation
      │
      └────→ shadow implementation

Then compare:

output
errors
side effects
business state

This gives you evidence before increasing traffic.

A rollout decision can then be based on:

divergence
error rate
latency
business outcomes

instead of:

It seems fine.

A Small End-to-End Invoice Migration Example

The individual pieces are easier to understand when you see them working together.

Here's a deliberately small, in-memory example based on the invoice capability we've been using throughout the article. It doesn't include a real database, reverse proxy, queue, or deployment platform. The point is to show the migration control flow in one place.

Start with a shared contract:

type InvoiceInput = {
  orderId: string;
  subtotal: number;
};

type Invoice = {
  orderId: string;
  total: number;
};

interface InvoiceGenerator {
  generate(
    input: InvoiceInput
  ): Promise<Invoice>;
}

The legacy implementation calculates the invoice total like this:

class LegacyInvoiceGenerator
  implements InvoiceGenerator {
  async generate(
    input: InvoiceInput
  ): Promise<Invoice> {
    return {
      orderId: input.orderId,
      total: input.subtotal * 1.21,
    };
  }
}

Now imagine we've migrated that capability into a new implementation:

class MigratedInvoiceGenerator
  implements InvoiceGenerator {
  async generate(
    input: InvoiceInput
  ): Promise<Invoice> {
    const tax =
      input.subtotal * 0.21;

    return {
      orderId: input.orderId,
      total: input.subtotal + tax,
    };
  }
}

The code is different, but the intended behavior is the same.

Next, define a deterministic rollout function. This example assigns each orderId to a bucket from 0 to 99 so the same order always follows the same route:

function bucketFor(
  value: string
): number {
  const sum = [...value].reduce(
    (total, char) =>
      total + char.charCodeAt(0),
    0
  );

  return sum % 100;
}

function shouldUseMigrated(
  orderId: string,
  percentage: number
): boolean {
  return (
    bucketFor(orderId) < percentage
  );
}

If percentage is 10, roughly 10% of IDs will be assigned to the migrated path.

Now add some tiny in-memory metrics:

const metrics = {
  legacyRequests: 0,
  migratedRequests: 0,
  mismatches: 0,
};

Then put the legacy and migrated implementations behind one migration-aware entry point:

class IncrementalInvoiceService {
  migratedEnabled = true;
  rolloutPercentage = 10;

  constructor(
    private readonly legacy:
      InvoiceGenerator,
    private readonly migrated:
      InvoiceGenerator
  ) {}

  async generate(
    input: InvoiceInput
  ): Promise<Invoice> {
    const legacyResult =
      await this.legacy.generate(
        structuredClone(input)
      );

    const migratedResult =
      await this.migrated.generate(
        structuredClone(input)
      );

    if (
      migratedResult.orderId !==
        legacyResult.orderId ||
      migratedResult.total !==
        legacyResult.total
    ) {
      metrics.mismatches += 1;
    }

    const useMigrated =
      this.migratedEnabled &&
      shouldUseMigrated(
        input.orderId,
        this.rolloutPercentage
      );

    if (useMigrated) {
      metrics.migratedRequests += 1;
      return migratedResult;
    }

    metrics.legacyRequests += 1;
    return legacyResult;
  }
}

This small service combines several ideas from the article.

First, it runs both implementations with the same input and compares their results. Because this example is entirely in memory and has no external side effects, doing that is safe.

Second, it routes only a percentage of requests to the migrated result.

Third, it records how many requests used each path and how many behavioral mismatches occurred.

You can exercise it with a few requests:

const service =
  new IncrementalInvoiceService(
    new LegacyInvoiceGenerator(),
    new MigratedInvoiceGenerator()
  );

for (let i = 1; i <= 100; i++) {
  await service.generate({
    orderId: `order-${i}`,
    subtotal: 1000,
  });
}

console.log(metrics);

You might see something like:

legacyRequests:   89
migratedRequests: 11
mismatches:        0

The exact split may not be exactly 90/10 with only 100 inputs because the bucket function is intentionally simple. The important point is that routing is deterministic, measurable, and controlled by rolloutPercentage.

If the migrated implementation starts producing differences, the mismatch counter gives you an observable signal.

And if you decide the rollout should stop, rollback is explicit:

service.migratedEnabled = false;

From that point forward, all returned responses come from the legacy implementation again.

This is intentionally a simplified example. A production system would need stronger routing, real metrics, error handling, persistent state, and careful treatment of side effects.

In particular, you shouldn't blindly execute both implementations if generating an invoice sends email, writes to two production databases, charges a customer, or publishes externally visible events. In those cases, the shadow path needs recording adapters, isolated infrastructure, or another mechanism that lets you compare behavior without duplicating real effects.

But the control loop is the same:

same input
↓
compare legacy and migrated behavior
↓
route a small percentage
↓
observe
↓
expand or roll back

That is incremental migration in its smallest useful form.

Design Rollback Before You Need It

Rollback shouldn't be invented during an incident. Before moving traffic, ask what happens if the migrated path fails.

For routing-level migrations, rollback may be simple:

migration flag = false

and traffic returns to:

legacy implementation

For example:

if (
  featureFlags.useNewInvoices
) {
  return migrated.generate(
    orderId
  );
}

return legacy.generate(orderId);

If the migrated path behaves incorrectly:

useNewInvoices = false

Rollback is almost immediate.

But rollback becomes more complicated when:

data format changes
new data is written
events differ
external systems are updated
legacy code cannot read new records

In those cases, rollback may require more than flipping a feature flag. You might need backward-compatible schemas so both versions can read the same records, compensating actions for external side effects, replayable events, reconciliation jobs, or a short period where the legacy system remains able to consume data written by the new path.

For higher-risk migrations, it can also help to define a rollback boundary in advance. For example: traffic can return to legacy until a new schema version is written, or after a particular external event is emitted, recovery requires compensation instead of a simple rollback. The important part is knowing when rollback is still reversible and when you've crossed into a different recovery strategy.

That's why rollback design needs to happen before deployment.

Treat Data Migration as a Separate Problem

Application migration and data migration are related, but they aren't the same problem.

Suppose the legacy system stores:

{
  "customer_type": "P",
  "status": 2
}

while the new system stores:

{
  "customerType": "PREMIUM",
  "status": "APPROVED"
}

You now need to answer:

Which database is authoritative?

Can both systems read the same data?

Do we transform on read?

Do we migrate records in batches?

Do we replicate changes?

When does ownership change?

These decisions should be explicit. Otherwise the application migration may appear successful while the data boundary remains ambiguous.

Be Careful with Dual Writes

One common transition strategy is:

write to legacy database
+
write to new database

This is called dual writing, and it looks simple.

For example:

await legacyOrders.save(order);
await newOrders.save(order);

But what happens if:

legacy write succeeds
new write fails

Now the two systems disagree.

Or:

legacy write fails
new write succeeds

Same problem.

Dual writes create a distributed consistency problem.

If you use them, you need to think about:

retries
idempotency
reconciliation
ordering
partial failure
monitoring

Sometimes a safer approach is:

single authoritative write
↓
change event
↓
replication

or a transactional outbox.

There's no universal solution. The important point is not to treat dual writing as a trivial migration technique.

Decide Who Owns the Data

During coexistence, data ownership can become confusing.

Imagine:

legacy system writes customers

new system writes invoices

both systems read orders

That may be perfectly reasonable, but it should be documented.

For each migrated capability, define:

system of record
write owner
readers
replication direction
consistency expectations

For example:

Invoices

Write owner:
new system

Source of truth:
new database

Legacy access:
read-only adapter

Replication:
new → legacy reporting store

Now the architecture has an explicit direction.

Without ownership rules, migrations often create permanent synchronization problems.

Observe Business Behavior, Not Just Infrastructure

During rollout, teams often monitor:

CPU
memory
latency
HTTP 500s
database connections

Those are important. But they're not enough.

Suppose:

HTTP 200 rate = 99.99%

while:

invoice totals are wrong

Infrastructure monitoring says:

healthy

But the business system is not healthy.

Migration observability should include domain signals.

For example:

orders processed
payments authorized
invoices generated
discount distribution
failed renewals
average invoice total
events published

If you know normal business behavior, unusual changes can expose migration defects that technical metrics miss.

Know When a Migration Slice Is Complete

A capability isn't fully migrated just because traffic reached 100%.

Before declaring it complete, I would verify:

100% traffic on new path
acceptable error rate
acceptable latency
behavioral differences resolved
side effects verified
data ownership established
rollback window completed
legacy callers removed
legacy writes stopped
observability in place

Then ask:

Is the legacy implementation still serving any purpose?

If not, remove it.

Leaving both implementations permanently active creates:

maintenance cost
confusion
duplicate bugs
unclear ownership
future migration debt

Incremental migration should eventually simplify the system, not permanently duplicate it.

Remove the Legacy Path

This step is often delayed.

Teams migrate traffic but leave the old path in place:

just in case

Months later:

nobody knows whether it is still used

Before deleting it, verify:

routing metrics show zero traffic
no callers depend on it
data dependencies are removed
rollback period is complete
operational documentation is updated

Then remove:

legacy implementation
legacy feature flags
legacy database access
unused integration code
temporary compatibility layers

Deletion is part of migration.

A migration that only adds new architecture without removing old architecture can increase complexity rather than reduce it.

How to Use AI During an Incremental Migration

AI can help with many parts of this process.

For example, it can inspect the legacy codebase and help answer:

Which modules implement this capability?

Which callers depend on it?

Which database tables does it touch?

Which external services does it call?

Which side effects occur?

Which feature flags already exist?

Which paths need adapters?

A useful prompt might be:

Analyze the Generate Invoice capability.

Identify:

1. entry points,
2. business rules,
3. persistence dependencies,
4. external integrations,
5. side effects,
6. callers,
7. data ownership,
8. possible migration seams.

Do not redesign the system.

Return evidence for each finding using file paths
and relevant code references.

AI can also help compare migration changes.

For example:

Compare the legacy and migrated implementations.

Identify possible behavioral differences in:

- return values,
- errors,
- side effects,
- persistence,
- event ordering,
- retries,
- idempotency,
- transaction boundaries.

Do not assume the new implementation is correct.

This is useful because migration involves a lot of repetitive analysis, and AI can accelerate that analysis.

Don't Let AI Turn the Migration into a Rewrite

There's a common failure mode.

You ask:

Help me migrate this legacy capability.

The model responds with:

new architecture
new domain model
new API
new event model
new database schema
new validation layer
new framework

At that point, you're no longer migrating one capability, you're redesigning it.

Sometimes redesign is necessary, but it should be intentional.

During incremental migration, I prefer prompts with explicit constraints.

For example:

Migrate this capability without intentionally changing
observable behavior.

Preserve:

- inputs,
- outputs,
- errors,
- side effects,
- ordering where relevant,
- transactional behavior.

Only introduce the minimum structural changes required
to run it in the target environment.

List any behavior you cannot preserve with confidence.

That keeps the transformation narrow.

AI should help reduce mechanical effort. It shouldn't silently expand project scope.

A Practical Incremental Migration Workflow

Here's the workflow I would use.

1. Understand the Capability

Identify:

inputs
outputs
rules
side effects
dependencies
unknowns

2. Characterize Existing Behavior

Protect important behavior with:

characterization tests
integration tests
contract tests

3. Refactor for Migration

Create:

seams
adapters
explicit dependencies
clear orchestration

without intentionally changing behavior.

4. Build the New Implementation

Implement the capability in the target environment. Keep its observable contract clear.

5. Differentially Test Old and New

Compare:

outputs
errors
side effects
business state

using representative cases.

6. Introduce Explicit Routing

Allow requests to choose:

legacy
or
migrated

through an observable migration policy.

7. Start with Safe Traffic

Use:

internal users
test tenants
selected customers

8. Increase Traffic Gradually

For example:

1%
5%
10%
25%
50%
100%

only when evidence supports the next stage.

9. Monitor Technical and Business Metrics

Observe both:

system health
business behavior

10. Keep Rollback Available

Make returning to the legacy path fast and understood.

11. Transfer Data Ownership

Explicitly define which system owns:

writes
reads
replication

12. Remove the Legacy Path

After the migration has stabilized:

delete old implementation
remove temporary routing
remove obsolete dependencies

Then choose the next capability.

What Incremental Migration Doesn't Solve

Incremental migration reduces risk, but it doesn't eliminate complexity.

You may still need to deal with:

distributed transactions
shared databases
old schemas
tight coupling
unsupported runtimes
poor test coverage
organizational ownership
regulatory constraints

There are also systems where partial migration is extremely difficult.

For example:

highly stateful systems
strongly coupled desktop applications
large transactional batch systems
systems with shared global state

Sometimes the migration boundary needs to be larger.

The principle remains the same:

Make the smallest reversible change that produces useful migration progress.

Incremental doesn't always mean tiny. It means controlled.

The Complete Legacy Modernization Workflow

This article closes the workflow we've been building throughout this series.

We started with a basic problem:

How do you modernize a legacy application without accidentally turning the project into a rewrite?

The first step was understanding.

Legacy system
↓
investigate
↓
map behavior and dependencies

Then characterization.

observed behavior
↓
tests
↓
behavioral safety net

Then refactoring.

entangled capability
↓
seams and boundaries
↓
migration-friendly structure

Then differential testing.

legacy implementation
        +
new implementation
        ↓
behavior comparison

And finally incremental migration.

Understand
↓
Characterize
↓
Refactor
↓
Migrate
↓
Compare
↓
Route
↓
Observe
↓
Expand
↓
Remove legacy

The sequence matters.

If you skip understanding, you may migrate the wrong behavior.

If you skip characterization, you may not notice behavioral changes.

If you skip refactoring, the migration boundary may remain too large.

If you skip comparison, differences remain hidden.

If you skip incremental rollout, you discover problems at full blast radius.

Each step reduces a different kind of uncertainty.

Conclusion

Modernizing a legacy application doesn't require replacing everything at once.

In many cases, the safer strategy is to create a path where old and new implementations can coexist temporarily.

Move one capability, then compare it.

Route a small amount of traffic and observe what happens.

Increase traffic when the evidence supports it, and roll back when it doesn't.

Transfer ownership explicitly, then remove the legacy path.

And repeat.

The full workflow becomes:

Understand
↓
Characterize
↓
Refactor
↓
Migrate incrementally
↓
Compare behavior
↓
Progressively route traffic
↓
Observe
↓
Remove legacy

AI can make every stage faster.

It can help map code, identify dependencies, generate adapters, compare implementations, analyze failures, and inspect migration diffs.

But speed isn't the same as confidence.

The important decisions still require engineering judgment:

What behavior matters?

What can change?

What should remain compatible?

What is the migration boundary?

What evidence is enough?

When is rollback necessary?

When can the legacy path be removed?

Those aren't code-generation questions. They're migration decisions.

And that's the larger lesson behind this entire series.

AI makes it increasingly cheap to produce new code. But that doesn't make legacy modernization trivial. It makes the quality of the decisions around the code more important.

Because the safest migration is rarely the one that changes the most software. It's the one that lets you change the system while continuously knowing what changed, why it changed, and whether it's safe to keep going.

The code compiles, the tests pass, the architecture is cleaner, and the new service responds faster.

Then everybody starts asking the same question:

Can we switch traffic now?

That's where confidence becomes difficult.

A new implementation can pass its own test suite and still behave differently from the system it is replacing.

Maybe rounding changed, or null values are handled differently, or an error became a successful response.

Maybe records are sorted differently, or a side effect happens in a different order, or a business rule you never documented was lost during the migration.

This is why, during a legacy migration, I like having another source of evidence: run the old and new implementations with the same inputs and compare what they do.

That's the basic idea behind differential testing. Instead of asking only if the new system passes its tests, you also ask: given the same input, where does the new system behave differently from the old one?

Those differences become evidence.

Some are bugs, some are intentional improvements, some are harmless representation differences, and some reveal behavior nobody knew existed.

In this tutorial, I'll show you how to use differential testing during a legacy migration to:

• Compare old and new implementations

• Define what should be considered equivalent

• Normalize outputs before comparing them

• Handle timestamps and other nondeterministic values

• Compare errors and side effects

• Run differential tests automatically

• Introduce tolerances where exact equality doesn't make sense

• Analyze mismatches

• Use shadow traffic in production safely

• Use AI to classify divergences without letting it decide correctness

• Determine when the new implementation is ready for cutover

The examples use TypeScript and Vitest, but the approach applies to most languages and migration strategies.

The goal isn't to prove that two implementations are internally identical. It's to obtain evidence that they are behaviorally equivalent where equivalence matters.

Prerequisites

To follow along here, you should be comfortable with:

• TypeScript or a similar language

• unit and integration testing

• asynchronous code

• API and service boundaries

• legacy modernization

• basic observability concepts

You should also already have some understanding of the capability being migrated.

Ideally, you know its inputs, outputs, important business rules, external contracts, side effects, and known areas of uncertainty.

Differential testing works best after you've already created a boundary around the capability you want to migrate.

Table of Contents

• Prerequisites

• What Differential Testing Actually Tells You

• Start with One Observable Boundary

• Run the Legacy and New Implementations with the Same Input

• Don't Compare Raw Output Blindly

• Normalize Values Before Comparing Them

• Handle Timestamps and Other Nondeterministic Values

• Compare Business Meaning, Not Just JSON

• Compare Errors as Part of the Contract

• Compare Side Effects, Too

• Use Tolerances When Exact Equality Is Wrong

• Build a Reusable Differential Test Harness

• Generate Test Cases from Real Behavior

• Classify Every Difference

• How to Use AI to Investigate Differential Failures

• How to Use Shadow Traffic Safely

• Measure Divergence Instead of Waiting for Perfection

• How to Know When You're Ready for Cutover

• A Practical Differential Testing Workflow

• What Differential Testing Can't Prove

• Differential Testing Turns Migration Risk into Evidence

• Conclusion

What Differential Testing Actually Tells You

Imagine that your legacy application calculates the final price of an order.

The legacy implementation looks like this:

type Order = {
  subtotal: number;
  customerType: "STANDARD" | "PREMIUM";
  country: string;
};

function legacyCalculateTotal(order: Order): number {
  let total = order.subtotal;

  if (order.customerType === "PREMIUM") {
    total *= 0.9;
  }

  if (order.country === "AR") {
    total -= 500;
  }

  return Math.max(total, 0);
}

During the migration, you create a new implementation:

function newCalculateTotal(order: Order): number {
  const premiumDiscount =
    order.customerType === "PREMIUM"
      ? order.subtotal * 0.1
      : 0;

  const countryAdjustment =
    order.country === "AR"
      ? 500
      : 0;

  return Math.max(
    order.subtotal -
      premiumDiscount -
      countryAdjustment,
    0
  );
}

The implementations look different. And that's fine. What matters is whether they produce equivalent behavior.

A simple differential test can run both:

import { describe, expect, it } from "vitest";

describe("order total migration", () => {
  it("matches the legacy implementation", () => {
    const order: Order = {
      subtotal: 10000,
      customerType: "PREMIUM",
      country: "AR",
    };

    const legacy =
      legacyCalculateTotal(order);

    const migrated =
      newCalculateTotal(order);

    expect(migrated).toBe(legacy);
  });
});

For this input:

legacy → 8500
new    → 8500

Good. But one matching example proves very little.

The value comes from systematically asking:

same input
↓
legacy implementation ──→ result A

same input
↓
new implementation ─────→ result B

compare A and B

Every mismatch gives you something to investigate.

Start with One Observable Boundary

Don't begin by comparing entire applications. To start, choose one capability.

For example:

Calculate Order Total
Generate Invoice
Approve Customer
Renew Subscription
Calculate Commission
Create Shipment

Suppose the migration boundary is:

interface OrderProcessor {
  process(order: Order): Promise<ProcessedOrder>;
}

Now you have two implementations:

LegacyOrderProcessor

NewOrderProcessor

That is a useful differential boundary, because both receive the same conceptual input, and both produce the same conceptual output.

You can compare them without requiring their internal architecture to match.

That matters because migrations often change structure intentionally.

The legacy implementation might be:

controller
→ service
→ SQL
→ provider SDK

while the new implementation might be:

use case
→ repository
→ gateway
→ events

Differential testing shouldn't care. It should care about observable behavior.

Run the Legacy and New Implementations with the Same Input

Suppose both implementations expose:

interface OrderProcessor {
  process(order: Order): Promise<ProcessedOrder>;
}

You can create:

const legacyProcessor =
  new LegacyOrderProcessor();

const newProcessor =
  new NewOrderProcessor();

Then:

it("produces the same processed order", async () => {
  const input: Order = {
    id: "order-1",
    subtotal: 10000,
    customerType: "PREMIUM",
    country: "US",
  };

  const legacy =
    await legacyProcessor.process(
      structuredClone(input)
    );

  const migrated =
    await newProcessor.process(
      structuredClone(input)
    );

  expect(migrated).toEqual(legacy);
});

Notice the use of:

structuredClone(input)

That matters if either implementation mutates its input.

Without separate copies, the first execution could influence the second.

You want:

same initial state

not:

new implementation receives state modified by legacy implementation

That kind of contamination can create misleading results.

Don't Compare Raw Output Blindly

The first version of a differential test is often:

expect(newResult).toEqual(legacyResult);

Sometimes that's exactly right. But other times it's wrong.

Imagine the legacy system returns:

{
  "id": "order-1",
  "total": 9000,
  "status": "PROCESSED",
  "generatedAt": "2026-09-09T10:00:01.231Z",
  "requestId": "legacy-f93a"
}

The new system returns:

{
  "requestId": "new-b517",
  "status": "PROCESSED",
  "generatedAt": "2026-09-09T10:00:01.416Z",
  "total": 9000,
  "id": "order-1"
}

A raw object comparison may fail because:

requestId differs
timestamp differs

But the business behavior might be equivalent.

You need to decide which fields are part of the meaningful contract.

Maybe:

id
total
status

matter.

While:

generatedAt
requestId

don't need exact equivalence.

That leads to normalization.

Normalize Values Before Comparing Them

Normalization means transforming outputs into a common representation before comparing them.

The goal isn't to change the business meaning of the data. It's to remove differences that are expected and irrelevant to the comparison, such as generated request IDs or timestamps, so the test can focus on the fields that actually define the behavior you care about.

In practice, that often means creating a canonical representation: a smaller, stable shape that contains only the meaningful fields you want to compare.

For example:

type ProcessedOrder = {
  id: string;
  total: number;
  status: string;
  generatedAt: string;
  requestId: string;
};

function normalizeOrder(
  order: ProcessedOrder
) {
  return {
    id: order.id,
    total: order.total,
    status: order.status,
  };
}

Here, ProcessedOrder contains both business-relevant fields and values that may legitimately differ between executions.

The normalizeOrder() function keeps id, total, and status, while leaving out generatedAt and requestId. That means two results can still be considered equivalent even if they were generated at slightly different times or used different request identifiers.

Now compare:

expect(
  normalizeOrder(migrated)
).toEqual(
  normalizeOrder(legacy)
);

This makes your equivalence rule explicit.

You're saying:

These fields define relevant behavior for this comparison.

Normalization can also handle:

• ordering

• casing

• optional fields

• timestamps

• generated identifiers

• numeric formatting

• provider-specific metadata

But normalization must be deliberate. If you remove too much, you can hide real migration bugs.

Handle Timestamps and Other Nondeterministic Values

Legacy systems contain many nondeterministic values.

For example:

timestamps
UUIDs
random tokens
request IDs
trace IDs
database-generated IDs
unordered collections
provider-generated references

If you compare those values exactly, your differential suite may fail constantly.

One option is dependency control.

Dependency control means moving a nondeterministic source, such as the current time or an ID generator, behind an interface that you can replace during tests.

Instead of letting each implementation read the real clock independently, you inject the same controlled clock into both. That gives them the same value and removes time itself as a source of meaningless divergence.

Suppose the code uses:

new Date()

You can replace that dependency with a clock:

interface Clock {
  now(): Date;
}

Then both implementations receive:

const clock = {
  now: () =>
    new Date(
      "2026-09-09T10:00:00.000Z"
    ),
};

Now time becomes deterministic.

The same technique can work for ID generation:

interface IdGenerator {
  next(): string;
}

Then tests can provide:

const ids = {
  next: () => "fixed-id",
};

If controlling nondeterminism is impractical, normalize it out only when it's not part of the behavior you need to protect.

Compare Business Meaning, Not Just JSON

Two systems can return different representations while expressing the same business state.

Imagine you have this in your legacy system:

{
  "status": 2
}

And this in your new one:

{
  "status": "APPROVED"
}

Raw comparison says:

different

Business comparison may say:

equivalent

You can create a semantic normalizer:

function normalizeStatus(
  status: number | string
) {
  if (status === 2) {
    return "APPROVED";
  }

  return status;
}

Here, the normalizer translates the legacy numeric value 2 into the business meaning used by the new implementation: "APPROVED".

It doesn't claim that every number and string are interchangeable. It encodes one explicit equivalence rule that you've already decided is valid for this migration.

Then:

expect(
  normalizeStatus(newResult.status)
).toBe(
  normalizeStatus(legacyResult.status)
);

This is especially useful when migration intentionally changes:

database schema
API representation
enumerations
provider-specific formats
internal identifiers

The important question becomes:

Does the observable business meaning remain equivalent?

Not:

Are the bytes identical?

Compare Errors as Part of the Contract

Success responses aren't the whole behavior. Errors matter too.

Suppose the legacy implementation rejects a missing customer:

throw new Error("Customer not found");

The new implementation accidentally returns:

return null;

These two implementations behave very differently for the same invalid input.

The legacy version fails explicitly, while the new version silently returns a value that a caller may interpret as a successful result.

If your differential tests only exercise cases where a valid customer exists, both implementations may appear equivalent and this contract change will remain invisible.

That's why failure behavior has to be compared too.

Create cases that capture errors:

async function captureResult<T>(
  operation: () => Promise<T>
) {
  try {
    return {
      type: "success" as const,
      value: await operation(),
    };
  } catch (error) {
    return {
      type: "error" as const,
      error:
        error instanceof Error
          ? error.message
          : String(error),
    };
  }
}

The helper wraps an asynchronous operation and converts both possible outcomes into data.

If the operation succeeds, it returns an object with type: "success" and the returned value. If the operation throws, the catch block converts that exception into an object with type: "error" and a readable error message.

This gives both implementations the same comparison shape, so the test can compare success versus failure explicitly instead of letting an exception stop the test before the two behaviors can be evaluated.

Now:

const legacy =
  await captureResult(() =>
    legacyProcessor.process(input)
  );

const migrated =
  await captureResult(() =>
    newProcessor.process(input)
  );

expect(migrated.type).toBe(legacy.type);

If errors are contractually important, compare:

error category
HTTP status
error code
retryability
validation details

Don't necessarily compare exact wording unless clients depend on it.

Compare Side Effects, Too

One of the easiest migration mistakes is preserving the return value while losing a side effect.

Suppose both implementations return:

{
  "status": "PROCESSED"
}

But the legacy version also:

persists the order
publishes an event
creates a payment
writes an audit entry

and the new version forgets the audit entry.

Response-level differential testing won't catch that. So you'll want to capture side effects.

For example:

type Effect =
  | {
      type: "payment";
      orderId: string;
      amount: number;
    }
  | {
      type: "event";
      name: string;
      orderId: string;
    };

A test adapter can record them:

class RecordingPaymentGateway {
  effects: Effect[] = [];

  async charge(
    orderId: string,
    amount: number
  ) {
    this.effects.push({
      type: "payment",
      orderId,
      amount,
    });
  }
}

Instead of sending a real payment request, this adapter records what the application attempted to do in the effects array.

You can apply the same idea to event publication:

class RecordingEvents {
  effects: Effect[] = [];

  async publish(
    name: string,
    orderId: string
  ) {
    this.effects.push({
      type: "event",
      name,
      orderId,
    });
  }
}

The application still calls its payment and event dependencies as usual. The test doubles simply capture those calls as structured data instead of performing the real external actions.

After running the legacy and migrated implementations with their own recording adapters, you can compare the two recorded effect lists and verify that both systems attempted the same observable side effects.

Now the differential test can compare:

expect(newEffects).toEqual(legacyEffects);

Again, exact ordering should only be required if ordering matters.

Use Tolerances When Exact Equality Is Wrong

Some domains shouldn't use exact equality.

Imagine a migrated calculation produces:

legacy → 34.333333333
new    → 34.333333334

Is that a migration bug? Maybe not.

Floating-point calculations may justify a tolerance.

For example:

expect(newResult).toBeCloseTo(
  legacyResult,
  6
);

Or define an explicit comparator:

function withinTolerance(
  a: number,
  b: number,
  tolerance: number
) {
  return Math.abs(a - b) <= tolerance;
}

Then:

expect(
  withinTolerance(
    migrated.total,
    legacy.total,
    0.01
  )
).toBe(true);

But tolerances should come from domain requirements. Don't use them just to make failing tests disappear.

For financial systems, one cent can matter. For scientific calculations, a much smaller numerical difference may matter.

Equivalence is a business and engineering decision.

Build a Reusable Differential Test Harness

Once you compare more than a few cases, you can create a reusable harness.

For example:

type DifferentialResult<T> = {
  input: T;
  equivalent: boolean;
  legacy: unknown;
  migrated: unknown;
};

async function compareImplementations<
  TInput,
  TOutput
>(
  input: TInput,
  legacy: (
    input: TInput
  ) => Promise<TOutput>,
  migrated: (
    input: TInput
  ) => Promise<TOutput>,
  normalize: (
    output: TOutput
  ) => unknown
): Promise<
  DifferentialResult<TInput>
> {
  const legacyResult =
    await legacy(
      structuredClone(input)
    );

  const migratedResult =
    await migrated(
      structuredClone(input)
    );

  const normalizedLegacy =
    normalize(legacyResult);

  const normalizedMigrated =
    normalize(migratedResult);

  return {
    input,
    equivalent:
      JSON.stringify(
        normalizedLegacy
      ) ===
      JSON.stringify(
        normalizedMigrated
      ),
    legacy: normalizedLegacy,
    migrated: normalizedMigrated,
  };
}

The harness does four things.

First, it runs the legacy and migrated implementations with separate clones of the same input, so one execution can't mutate the data seen by the other.

Second, it passes both outputs through the same normalize() function. That applies the equivalence rules in one place instead of repeating them in every test.

Third, it compares the normalized results and records whether they're equivalent.

Finally, it returns the input and both normalized outputs together. That makes a failed comparison easier to inspect because the test report can show exactly which case diverged and what each implementation produced.

Then:

const result =
  await compareImplementations(
    input,
    legacyProcessor.process.bind(
      legacyProcessor
    ),
    newProcessor.process.bind(
      newProcessor
    ),
    normalizeOrder
  );

expect(result.equivalent).toBe(true);

For real systems, I would usually avoid relying on JSON.stringify() as the final equality mechanism.

The example keeps the harness readable.

In production-quality tooling, use a proper structural or domain-specific comparator.

The important part is that comparison logic becomes centralized.

Generate Test Cases from Real Behavior

Hand-written examples are useful. But migrations often fail on cases nobody thought to write manually.

Useful sources of inputs include:

existing test fixtures
historical incidents
production-safe request samples
database records
boundary values
previous bug reports
known customer scenarios

Suppose production shows these order shapes:

const cases: Order[] = [
  {
    subtotal: 0,
    customerType: "STANDARD",
    country: "US",
  },
  {
    subtotal: 500,
    customerType: "PREMIUM",
    country: "AR",
  },
  {
    subtotal: 10000,
    customerType: "STANDARD",
    country: "AR",
  },
];

The first block is the test data. It captures a small set of representative input shapes that you've observed in real usage or reconstructed safely from production behavior.

The next block is the test itself. it.each(cases) tells Vitest to run the same differential comparison once for every input in that array.

That separates two concerns: defining realistic cases and defining how every case should be evaluated.

Now:

it.each(cases)(
  "matches legacy behavior",
  async (input) => {
    const legacy =
      await legacyProcessor.process(
        structuredClone(input)
      );

    const migrated =
      await newProcessor.process(
        structuredClone(input)
      );

    expect(
      normalizeOrder(migrated)
    ).toEqual(
      normalizeOrder(legacy)
    );
  }
);

Real examples help expose assumptions that synthetic test data often misses. But production data must be handled carefully.

Remove or anonymize:

personal data
credentials
tokens
financial identifiers
confidential business data

The objective is to preserve useful behavioral shapes, not copy sensitive production information into test fixtures.

Classify Every Difference

A differential failure doesn't automatically mean that the new implementation is wrong.

Suppose you find 200 mismatches. Classify them.

I like categories such as:

migration defect
legacy defect intentionally preserved
intentional behavior change
representation difference
nondeterministic difference
test/comparator defect
unknown

For example:

Input:
subtotal = 5000

Legacy:
discount = 0

New:
discount = 500

Classification:
unknown

Investigation reveals that the new implementation changed:

amount > 5000

to:

amount >= 5000

Now you need a decision.

Was that:

accidental migration change

or:

intentional bug fix

Differential testing exposes the decision. It doesn't make the decision for you.

That's one of its greatest benefits.

How to Use AI to Investigate Differential Failures

Large migrations can produce hundreds or thousands of differences. And AI can help triage them.

Suppose you have:

{
  "input": {
    "subtotal": 5000,
    "country": "AR"
  },
  "legacy": {
    "total": 4500
  },
  "new": {
    "total": 4000
  }
}

You can give the model:

• the input

• both outputs

• relevant legacy code

• relevant migrated code

• the comparator rules

Then ask:

Analyze this differential test failure.

Identify the smallest behavioral difference that could
explain the mismatch.

Compare the legacy and migrated implementations.

Return:

1. observed difference,
2. relevant legacy branch,
3. relevant migrated branch,
4. likely cause,
5. evidence supporting the cause,
6. additional test cases that could confirm it.

Do not decide which behavior is correct.
Do not modify the code yet.

That last instruction matters. AI can be very useful for locating why two implementations diverge. It shouldn't silently turn that diagnosis into a business decision.

Don't Let AI Decide Which Behavior Is Correct

Imagine the legacy system does this:

Customer age 65 → no discount
Customer age 66 → discount

The new system does:

Customer age 65 → discount
Customer age 66 → discount

AI may look at the code and say:

The new implementation appears more logical because senior discounts typically begin at age 65.

That's irrelevant.

The business rule might be:

age > 65

for a reason. Or the legacy behavior might contain a bug.

You need evidence.

Use:

requirements
existing tests
production behavior
business owners
historical tickets
commit history
contracts

AI can help gather and summarize that evidence. It shouldn't invent the rule.

Differential testing is valuable because it tells you that there's a difference before you accidentally turn that difference into production behavior.

How to Use Shadow Traffic Safely

Once offline differential tests look good, you can sometimes compare behavior with real traffic. This is often called shadowing or traffic mirroring.

The pattern looks like:

real request
    │
    ├────────────→ legacy system
    │                  │
    │                  ↓
    │             real response
    │
    └────────────→ new system
                       │
                       ↓
                  shadow result

The user still receives:

legacy response

while the new system processes a copy of the request.

Then you compare:

legacy output
vs.
shadow output

This can reveal cases that your test suite never captured.

For example:

unexpected null combinations
rare customer states
unusual international data
old records
large values
unusual sequence patterns

But shadow execution requires careful design, especially when the operation has side effects.

How to Prevent Shadow Execution from Duplicating Side Effects

Imagine shadowing:

POST /payments

If both systems really execute the payment, you have a serious problem.

The same applies to:

send email
create shipment
charge card
modify inventory
publish event
write external record

The shadow implementation shouldn't perform destructive or externally visible effects unless they're safely isolated.

One approach is to replace real gateways with recording adapters:

class ShadowPaymentGateway
  implements PaymentGateway {
  calls: PaymentRequest[] = [];

  async charge(
    request: PaymentRequest
  ) {
    this.calls.push(request);

    return {
      paymentId: "shadow",
    };
  }
}

The new implementation still tries to execute:

payment

but instead of charging a real card, the shadow adapter records:

what would have been sent

You can then compare that intent with the legacy side effect.

This distinction is important:

compare behavior

does not mean:

duplicate production effects

Measure Divergence Instead of Waiting for Perfection

When running thousands of comparisons, a binary:

pass / fail

may not tell the whole story.

You can measure divergence.

For example:

Requests compared:     100,000
Equivalent:             99,620
Different:                 380

Divergence rate:          0.38%

Then classify those 380:

250 timestamp differences
80 known intentional changes
30 comparator problems
15 migration defects fixed
5 still unexplained

After normalization:

meaningful unresolved divergence:
5 / 100,000
= 0.005%

Now the conversation becomes much more concrete.

Instead of:

I think the migration is ready.

you can say:

We compared 100,000 representative executions and have five unresolved behavioral differences.

Whether that's acceptable depends on what those five cases are.

One incorrect financial transaction can matter more than 100 harmless formatting differences.

So don't evaluate only the percentage. Evaluate the severity.

How to Know When You're Ready for Cutover

Differential testing doesn't give you a universal threshold. But it can give you evidence.

Before cutover, I would want to answer questions such as:

Have Important Input Classes Been Compared?

Not only happy paths.

Include:

boundaries
errors
historical bugs
large values
missing values
rare states

Are Meaningful Differences Classified?

Avoid:

we have 47 unexplained mismatches

Are Critical Differences Resolved?

Especially:

money
authorization
state transitions
data integrity
external contracts
idempotency

Are Intentional Differences Documented?

If the new behavior intentionally differs, that should be explicit.

Are Side Effects Equivalent?

Not only responses.

Have Production-like Cases Been Tested?

Synthetic fixtures alone may not be enough.

Can the Migration Be Rolled Back?

Differential confidence reduces risk. It doesn't eliminate the need for rollback.

If you can answer these questions, you're much closer to a controlled cutover.

A Practical Differential Testing Workflow

Here's the workflow I would use.

1. Pick One Capability

For example:

Process Order
Calculate Invoice
Approve Customer

Don't compare the whole platform at once.

2. Define the Observable Contract

List what matters:

return value
status
error
database state
events
external calls

3. Create Legacy and New Adapters

Expose both implementations through the same conceptual interface.

4. Define Normalization Rules

Decide how to handle:

timestamps
generated IDs
ordering
representation changes
optional values

Do this before looking at lots of failures. Otherwise you may weaken the comparator simply to make results pass.

5. Compare Known Cases

Begin with:

existing tests
characterization cases
edge cases
historical bugs

6. Capture Side Effects

Use recording or fake adapters where necessary.

7. Automate the Harness

Produce structured output for every mismatch.

For example:

{
  "caseId": "case-493",
  "equivalent": false,
  "legacy": {},
  "migrated": {},
  "difference": {}
}

8. Classify Differences

Use categories:

defect
intentional change
normalization issue
nondeterminism
unknown

9. Add Representative Real-World Cases

Use anonymized or safely reconstructed production patterns.

10. Shadow Real Traffic When Appropriate

Only after controlling side effects and privacy risk.

11. Measure Divergence

Track both:

frequency
severity

12. Resolve Unknowns Before Cutover

The most dangerous category is often not:

different

It is:

different and nobody knows why

What Differential Testing Can't Prove

Differential testing has an important limitation: it compares the new system against the old one.

That means the legacy system becomes a behavioral reference. But the legacy system may already be wrong.

Suppose:

legacy output = wrong
new output    = same wrong result

The differential test passes, but that doesn't make the behavior correct.

This is why differential testing should complement:

specification tests
characterization tests
business requirements
security testing
performance testing
contract testing
domain review

It answers:

Did behavior change?

It doesn't automatically answer:

Is this the right behavior?

That distinction matters. The legacy application is evidence, it's not absolute truth.

Differential Testing Turns Migration Risk into Evidence

There's another reason I like this technique. Without differential testing, migration discussions can become subjective.

One person says:

The new implementation looks ready.

Another says:

I do not trust it yet.

Both may have reasonable instincts, but neither statement is very measurable.

Differential testing changes the conversation.

Now you can say:

12,000 cases compared
47 differences found
31 representation differences
9 intentional behavior changes
6 migration defects fixed
1 unresolved

That is a much better engineering discussion. You're converting uncertainty into observable differences. Then you can decide what to do with them.

Conclusion

A legacy migration is not complete because the new implementation passes its own tests.

The harder question is whether it preserves the behavior that matters from the system it is replacing.

Differential testing gives you another way to answer that question.

Run both implementations with the same inputs.

Compare outputs.

Compare errors.

Compare side effects.

Normalize only the differences that truly do not matter.

Investigate everything else.

And when possible, use representative production behavior to discover cases your test suite did not anticipate.

The migration sequence now becomes:

Understand
↓
Characterize
↓
Refactor
↓
Migrate
↓
Compare
↓
Cut over

AI can accelerate this process too.

It can help build comparators, analyze failures, group similar divergences, inspect code paths, and suggest additional test cases.

But it should not decide which implementation is correct.

That still requires evidence, domain knowledge, and engineering judgment.

The purpose of differential testing is not to eliminate uncertainty completely.

It is to make uncertainty visible before you switch production traffic.

Because during a migration, discovering that the new system behaves differently is useful.

Discovering it after the old system has been turned off is much more expensive.