AI Migration Assistants: Strangler Fig Cuts With Contract Tests

Client → Facade / Routing layer
            ├─ Legacy monolith handler (default)
            └─ New service handler (canary %)
                 └─ Dual-run comparator (shadow)

# migration rule excerpt
- One endpoint per PR unless a shared DTO must move first.
- Never remove legacy routes in the introducing PR.
- Always add dual-run tests under packages/migration-contracts.
- ❌ No “while we’re here” refactors outside the endpoint boundary.

// characterization from recorded fixtures — illustrative
import { legacyHandle } from "../legacy/invoices";
import fixtures from "./fixtures/invoices.get.json";

test.each(fixtures)("legacy characterization %s", async (fx) => {
  const res = await legacyHandle(fx.req);
  expect(res.status).toBe(fx.res.status);
  expect(normalize(res.body)).toEqual(normalize(fx.res.body));
});

function normalize(body: any) {
  const { requestId, serverTime, ...rest } = body;
  return rest; // strip volatile fields
}

type Tolerance = {
  ignorePaths: string[]; // json-pointer
  numericEpsilon?: Record<string, number>;
  arrayOrderInsensitive?: string[];
};

export function semanticEqual(a: unknown, b: unknown, tol: Tolerance): string[] {
  const drifts: string[] = [];
  // walk both trees; skip ignorePaths; compare numbers with epsilon
  // return human-readable drift list for the PR bot
  return drifts;
}

test("dual-run GET /invoices/:id", async () => {
  const req = sampleRequest();
  const [legacy, next] = await Promise.all([
    legacyHandle(req),
    newHandle(req),
  ]);
  const drifts = semanticEqual(legacy.body, next.body, {
    ignorePaths: ["/requestId", "/serverTime"],
    numericEpsilon: { "/taxCents": 1 },
  });
  expect(drifts).toEqual([]);
});

# cutover checklist enforced in CI labels
# 1. dual-run green for 48h on staging shadow
# 2. canary 5% → 25% → 100% with error-budget gates
# 3. only then open PR to remove legacy handler
gh pr edit "$PR" --add-label "migration/cutover-ready"

// routing facade — illustrative
export async function getInvoice(ctx, id: string) {
  const mode = await flags.get("invoices.get.impl", ctx.tenantId);
  if (mode === "new") return newHandle(ctx, id);
  if (mode === "shadow") {
    const legacy = await legacyHandle(ctx, id);
    void shadowCompare(legacy, () => newHandle(ctx, id));
    return legacy; // always return legacy until cut
  }
  return legacyHandle(ctx, id);
}