---
id: WF-PFM-INT-010
title: Migrate bindings to another contract major
trigger: The initiating integration administrator starts this flow.
product_area: platform
module: integrations
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
inference: []
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
implements:
  - CAP-PFM-INT-007
moves:
  - STATE-PFM-INT-006
crosses: []
idempotency: 'Existing target bindings are reported on repeat migration, and each scope can complete independently.'
concurrency: >-
  Target-scope updates serialize within individual binding transactions, rather than one migration-wide
  transaction.
hops:
  - 'n': 1
    actor_or_service: Integration administrator
    action: >-
      Request a capability-major migration with optional scope or account filters, preview and
      source-supersession choices.
    anchor: 'services-platform:modules/integrations/services/bindings/binding-operations.ts:migrateBindings'
    seam: sync
    on_failure: Reject malformed migration options.
    left_inconsistent: No binding copy is attempted.
    observer: The administrator
    provenance: observed
    source: 'services-platform:modules/integrations/services/bindings/binding-operations.ts:migrateBindings'
  - 'n': 2
    actor_or_service: Integrations service
    action: >-
      Copy up to two hundred eligible source bindings to the target major using their scope, account, features
      and policy, each in its own transaction.
    anchor: 'services-platform:modules/integrations/services/bindings/binding-operations.ts:migrateBindings'
    seam: sync
    on_failure: Report the reason for each refused copy.
    left_inconsistent: Successful copies remain even when others fail.
    observer: The administrator
    provenance: observed
    source: 'services-platform:modules/integrations/services/bindings/binding-operations.ts:migrateBindings'
  - 'n': 3
    actor_or_service: Integrations service
    action: >-
      Append migration history and both audit entries and optionally supersede the source within that binding
      transaction; report remaining work.
    anchor: 'services-platform:modules/integrations/services/bindings/binding-operations.ts:migrateBindings'
    seam: sync
    on_failure: Rollback only the failed binding transaction.
    left_inconsistent: Other committed scope migrations remain intact.
    observer: Binding history
    provenance: observed
    source: 'services-platform:modules/integrations/services/bindings/binding-operations.ts:migrateBindings'
evidence:
  - >-
    services-platform at ad3f6a65: modules/integrations/services/bindings/binding-operations.ts;
    docs/integrations/README.md (Migrating bindings between majors);
    docs/milestones/INTG-M2-calls-through-the-gateway.md (M2-D10)
  - >-
    services-platform:modules/integrations/tests/integration/services/bindings/binding-migration.integration.spec.js#refuses
    each ineligible binding with its reason and leaves the already migrated one alone
  - >-
    services-platform:modules/integrations/tests/integration/services/bindings/binding-migration.integration.spec.js#refuses
    each ineligible binding with its reason and leaves the already migrated one alone
  - >-
    services-platform:modules/integrations/tests/integration/services/bindings/binding-migration.integration.spec.js#refuses
    each ineligible binding with its reason and leaves the already migrated one alone
controls: [TC-AVL-001, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CHG-005, TC-CHG-006, TC-CHG-007, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003]
---

# Migrate bindings to another contract major

## What It Does

A contract-major migration copies routing choices through the ordinary binding rules. Each scope commits independently, allowing partial progress and repeat requests. The old major remains available unless the caller explicitly supersedes its bindings.

## The Flow

```mermaid
sequenceDiagram
  participant P0 as Integration administrator
  participant P1 as Integrations service
  P0->>P0: 1. Request a capability-major migration with optional scope or account filters
  P1->>P1: 2. Copy up to two hundred eligible source bindings to the target major using their scope
  P1->>P1: 3. Append migration history and both audit entries and optionally supersede the source within that binding transa
```

## When Something Fails

Reject malformed migration options. No binding copy is attempted. Report the reason for each refused copy. Successful copies remain even when others fail. Rollback only the failed binding transaction. Other committed scope migrations remain intact.

## Open Design Questions

The approved gateway milestone deferred major migration, so its implemented availability remains a planning disagreement.