---
id: WF-PFM-ELG-003
title: Replace an obsolete rule and move its uses
trigger: >-
  An administrator names a replacement for a deprecated rule and requests
  migration of following consumers and live references.
product_area: platform
module: eligibility
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
inference: []
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
implements:
  - CAP-PFM-ELG-005
moves:
  - STATE-PFM-ELG-001
  - STATE-PFM-ELG-002
crosses:
  - SVC-PFM-ELG-eligibility
idempotency: >-
  Already-moved followers are not moved again; consumers already using the
  replacement and pinned references are reported for review.
concurrency: >-
  Migration runs synchronously in one workspace transaction. A supplied
  definition version is checked, while an omitted version allows work against
  the current row.
hops:
  - 'n': 1
    actor_or_service: Rule administrator
    action: Deprecate the definition and designate an active published replacement.
    anchor: >-
      services-platform:modules/eligibility/services/governance/lifecycle.ts:deprecateDefinitionByKey
    seam: sync
    on_failure: An invalid replacement or stale supplied version is refused.
    left_inconsistent: Definition standing remains unchanged on refusal.
    observer: The administrator sees the service explanation.
    provenance: observed
    source: >-
      services-platform:modules/eligibility/services/governance/lifecycle.ts:deprecateDefinitionByKey
  - 'n': 2
    actor_or_service: Eligibility lifecycle (one transaction)
    action: >-
      Repoint compatible followers without duplicate replacement uses, republish
      live following references and retain their drafts; report pins and
      validation refusals.
    anchor: >-
      services-platform:modules/eligibility/services/governance/lifecycle.ts:migrateReferences
    seam: sync
    on_failure: >-
      A referencing-rule validation refusal is reported locally; other errors
      roll back migration.
    left_inconsistent: Pins and refused references deliberately remain on the old definition.
    observer: The migration result lists moved and remaining uses.
    provenance: observed
    source: >-
      services-platform:modules/eligibility/services/governance/lifecycle.ts:withReferencesRenamed
  - 'n': 3
    actor_or_service: Eligibility lifecycle (after commit)
    action: Discard plans and advance display generations for changed rules.
    anchor: >-
      services-platform:modules/eligibility/services/compile/plan-cache.ts:forgetPlans
    seam: sync
    on_failure: Optional cache errors receive no durable retry.
    left_inconsistent: Earlier display answers may survive for two minutes.
    observer: Cache counters reveal the outcome.
    provenance: observed
    source: 'services-platform:docs/eligibility.md#11. Decision cache'
  - 'n': 4
    actor_or_service: Rule administrator
    action: Review remaining pins and archive only when active dependencies are gone.
    anchor: >-
      services-platform:modules/eligibility/services/governance/lifecycle.ts:archiveDefinitionByKey
    seam: sync
    on_failure: Archive rejects surviving dependencies and reports their counts.
    left_inconsistent: The old definition remains deprecated.
    observer: Usage and the archive refusal guide the administrator.
    provenance: observed
    source: >-
      services-platform:modules/eligibility/services/governance/lifecycle.ts:archiveDefinitionByKey
branches:
  - The replacement must be active and published before migration begins.
waits:
  - Manual pin review separates migration from eventual archive.
evidence:
  - >-
    services-platform at ad3f6a6: services/governance/lifecycle.ts, publish.ts
    (publishRevision); docs/eligibility.md §7.6;
    docs/debt/eligibility-migrate-references-in-request.md.
controls: [TC-AVL-001, TC-AVL-004, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-006, 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-IAM-006, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003]
---
# Replace an obsolete rule and move its uses

## What It Does

An administrator names a replacement for a deprecated rule and requests migration of following consumers and live references.

## The Flow

```mermaid
flowchart TD
  H1["Rule administrator" ]
  H2["Eligibility lifecycle (one transaction)" ]
  H1 --> H2
  H3["Eligibility lifecycle (after commit)" ]
  H2 --> H3
  H4["Rule administrator" ]
  H3 --> H4
```

Deprecate the definition and designate an active published replacement. Repoint compatible followers without duplicate replacement uses, republish live following references and retain their drafts; report pins and validation refusals. Discard plans and advance display generations for changed rules. Review remaining pins and archive only when active dependencies are gone.

## When Something Fails

An invalid replacement or stale supplied version is refused. Definition standing remains unchanged on refusal. A referencing-rule validation refusal is reported locally; other errors roll back migration. Pins and refused references deliberately remain on the old definition. Optional cache errors receive no durable retry. Earlier display answers may survive for two minutes. Archive rejects surviving dependencies and reports their counts. The old definition remains deprecated.

## Open Design Questions

The replacement must be active and published before migration begins.