---
id: WF-PFM-INT-009
title: Invalidate and restore bindings when eligibility changes
trigger: The initiating integrations service starts this flow.
product_area: platform
module: integrations
revision: 1
status: draft
design_intent: confirmed
implementation_evidence: observed
origin: docs/milestones/INTG-M2-calls-through-the-gateway.md#Decisions M2-D4 (Andrew)
inference: []
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
implements:
  - CAP-PFM-INT-007
moves:
  - STATE-PFM-INT-006
crosses: []
idempotency: >-
  Recomputing the same eligibility leaves it unchanged, and rolled-back causes generate no post-commit
  notices.
concurrency: Dependency changes and binding updates share their database transaction and row locks.
hops:
  - 'n': 1
    actor_or_service: Integrations service
    action: Call binding reassessment from the transaction changing an account or installation.
    anchor: 'services-platform:modules/integrations/services/hooks/integration-hooks.ts'
    seam: sync
    on_failure: A hook error aborts the initiating mutation.
    left_inconsistent: The cause and bindings preserve their former state.
    observer: The causing operation’s caller
    provenance: observed
    source: 'services-platform:modules/integrations/services/hooks/integration-hooks.ts'
  - 'n': 2
    actor_or_service: Binding hooks
    action: >-
      Compute current binding eligibility from account usability, installation status, supported major and
      required features.
    anchor: 'services-platform:modules/integrations/services/bindings/invalidation.ts'
    seam: sync
    on_failure: Rollback the causing transaction if reassessment fails.
    left_inconsistent: No invalidation commits independently of its cause.
    observer: Binding history
    provenance: observed
    source: 'services-platform:modules/integrations/services/bindings/invalidation.ts'
  - 'n': 3
    actor_or_service: Binding hooks
    action: Advance revisions for changed bindings and append their snapshots and audit records.
    anchor: 'services-platform:modules/integrations/services/bindings/invalidation.ts'
    seam: sync
    on_failure: Abort the transaction on a recording error.
    left_inconsistent: Neither the changed binding nor incomplete history commits.
    observer: Binding history and the security trail
    provenance: observed
    source: 'services-platform:modules/integrations/services/bindings/invalidation.ts'
  - 'n': 4
    actor_or_service: Binding notices
    action: >-
      After commit, request one administrator message per affected connection listing new invalid bindings;
      restorations remain silent.
    anchor: 'services-platform:modules/integrations/services/bindings/binding-notices.ts'
    seam: sync
    on_failure: Log failed mail requests.
    left_inconsistent: The new binding status remains visible even without mail.
    observer: Mail logs
    provenance: observed
    source: 'services-platform:modules/integrations/services/bindings/binding-notices.ts'
evidence:
  - >-
    services-platform at ad3f6a65: modules/integrations/services/bindings/invalidation.ts, binding-notices.ts;
    services/hooks/integration-hooks.ts; docs/integrations/README.md (Invalidation and restoration)
  - >-
    services-platform:modules/integrations/tests/integration/services/bindings/invalidation.integration.spec.js#invalidates
    its active bindings with connection_suspended, at the next revision
  - >-
    services-platform:modules/integrations/tests/integration/services/bindings/invalidation.integration.spec.js#invalidates
    its active bindings with connection_suspended, at the next revision
  - >-
    services-platform:modules/integrations/tests/integration/services/bindings/binding-operations.integration.spec.js#writes
    the creation, the replacement and the removal to the security trail
  - >-
    services-platform:modules/integrations/tests/integration/services/bindings/invalidation.integration.spec.js#tells
    the administrators once, after the commit, naming both bindings and why
controls: [TC-AVL-001, TC-AVL-004, 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-MON-002, TC-MON-003, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, 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]
---

# Invalidate and restore bindings when eligibility changes

## What It Does

Bindings follow the saved eligibility of the account and installation they select. Reassessment shares the transaction that changed that dependency, preserving a reason and new revision. Notifications follow commit and restoration requires no email.

## The Flow

```mermaid
sequenceDiagram
  participant P0 as Integrations service
  participant P1 as Binding hooks
  participant P2 as Binding notices
  P0->>P0: 1. Call binding reassessment from the transaction changing an account or installation.
  P1->>P1: 2. Compute current binding eligibility from account usability
  P1->>P1: 3. Advance revisions for changed bindings and append their snapshots and audit records.
  P2->>P2: 4. After commit
```

## When Something Fails

A hook error aborts the initiating mutation. The cause and bindings preserve their former state. Rollback the causing transaction if reassessment fails. No invalidation commits independently of its cause. Abort the transaction on a recording error. Neither the changed binding nor incomplete history commits. Log failed mail requests. The new binding status remains visible even without mail.

## Open Design Questions

Saved eligibility and mail receipt have separate consistency limits; a failed notice has no durable retry.