---
id: WF-PFM-ELG-008
title: Refresh answers and request role rechecks after a change
trigger: >-
  A registered record-event consumer, a system reconciliation request or a
  publication asks to refresh subjects and their derived roles.
product_area: platform
module: eligibility
revision: 1
status: draft
design_intent: confirmed
origin: >-
  Eligibility Engine architecture D-22 (derived roles with TTL, event-driven
  reconcile, sign-in reconcile and nightly backstop) and D-25 (24-hour TTL),
  approved 2026-10-17 (PLAT-M11 "Decisions")
implementation_evidence: partially-observed
inference: []
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
implements:
  - CAP-PFM-ELG-010
  - CAP-PFM-ELG-012
moves: []
crosses:
  - SVC-PFM-ELG-eligibility
idempotency: >-
  Repeated subjects share pending recheck requests; Security serializes and
  reconciles redeliveries rather than duplicate grants.
concurrency: >-
  Event batches process workspaces in turn with a function concurrency cap of
  five; Security owns the per-subject reconciliation lock.
hops:
  - 'n': 1
    actor_or_service: CRM change-event consumer
    action: >-
      Deliver up to one hundred events from a stream to Platform’s change
      handler.
    anchor: >-
      services-platform:modules/eligibility/aws/logic/eligibility-change-events.lambda.ts
    seam: event
    on_failure: The originating event consumer owns retry and dead-letter handling.
    left_inconsistent: No events arrive until the handler is registered.
    observer: The source event consumer observes delivery.
    provenance: documented
    source: 'services-platform:docs/eligibility.md#16. Invalidation (P4-05)'
  - 'n': 2
    actor_or_service: Eligibility change events
    action: >-
      Check whether an active event-refresh declaration reads the stream
      dataset; otherwise acknowledge without refresh.
    anchor: >-
      services-platform:modules/eligibility/services/invalidation/handle-change-events.ts:handleEligibilityChangeEvents
    seam: sync
    on_failure: An ignored stream needs no retry.
    left_inconsistent: >-
      Current time-only CRM declarations leave display cache until expiry and
      roles until other refresh paths.
    observer: Information logs identify ignored batches.
    provenance: observed
    source: >-
      services-platform:modules/eligibility/services/invalidation/handle-change-events.ts:handleEligibilityChangeEvents
  - 'n': 3
    actor_or_service: Eligibility change events
    action: >-
      Invalidate subject-indexed answers, queue role checks and nudge dispatch
      for affected subjects.
    anchor: >-
      services-platform:modules/eligibility/services/invalidation/decision-cache-keys.ts:forgetSubjectDecisions
    seam: sync
    on_failure: >-
      Return failed workspace events for retry while preserving other
      workspaces’ successes.
    left_inconsistent: Route caches without subject indexing survive up to two minutes.
    observer: Per-event results expose delivery outcomes.
    provenance: observed
    source: 'services-platform:docs/debt/eligibility-decision-cache-subject-keys.md'
  - 'n': 4
    actor_or_service: System reconcile operation
    action: >-
      Accept a bounded system reconciliation request and deduplicate its subject
      checks.
    anchor: >-
      services-platform:modules/eligibility/aws/api/reconcile.routes.ts:eligibilityReconcileRoutes
    seam: sync
    on_failure: Invalid requests enqueue nothing.
    left_inconsistent: Existing pending work remains unchanged.
    observer: The requesting application receives the refusal.
    provenance: observed
    source: >-
      services-platform:modules/security/services/persistence/derived-assignment-reconciles.ts:queueDerivedAssignmentReconciles
  - 'n': 5
    actor_or_service: Security reconcile dispatcher and consumer
    action: >-
      Dispatch waiting requests every minute or on nudge, then have Security
      evaluate and synchronize rule-derived grants.
    anchor: >-
      services-platform:modules/security/services/derived-assignments/reconcile.ts:reconcileSubject
    seam: queue
    on_failure: >-
      Retry can end in dead-lettering; a missing binding fails the subject’s
      batch.
    left_inconsistent: >-
      Prior grants remain until their twenty-four-hour expiry or a successful
      refresh.
    observer: The fifteen-minute queue-age threshold alarms.
    provenance: documented
    source: 'services-platform:docs/eligibility.md#13.4 The reconciler'
branches:
  - >-
    Publication atomically requests current holder rechecks and bounded
    simulation gains.
waits:
  - Queued subjects await Security’s dispatcher and consumer.
evidence:
  - >-
    services-platform at ad3f6a6: services/invalidation/;
    aws/api/reconcile.routes.ts; aws/logic/eligibility-change-events.lambda.ts;
    modules/security/services/persistence/derived-assignment-reconciles.ts;
    docs/eligibility.md §13, §16; docs/queued-work.md;
    docs/debt/eligibility-decision-cache-subject-keys.md.
controls: [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-DAT-001, TC-DAT-002, TC-DAT-003, TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-001, 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]
---
# Refresh answers and request role rechecks after a change

## What It Does

A registered record-event consumer, a system reconciliation request or a publication asks to refresh subjects and their derived roles.

## The Flow

```mermaid
flowchart TD
  H1["CRM change-event consumer" ]
  H2["Eligibility change events" ]
  H1 --> H2
  H3["Eligibility change events" ]
  H2 --> H3
  H4["System reconcile operation" ]
  H3 --> H4
  H5["Security reconcile dispatcher and consumer" ]
  H4 --> H5
```

Deliver up to one hundred events from a stream to Platform’s change handler. Check whether an active event-refresh declaration reads the stream dataset; otherwise acknowledge without refresh. Invalidate subject-indexed answers, queue role checks and nudge dispatch for affected subjects. Accept a bounded system reconciliation request and deduplicate its subject checks. Dispatch waiting requests every minute or on nudge, then have Security evaluate and synchronize rule-derived grants.

## When Something Fails

The originating event consumer owns retry and dead-letter handling. No events arrive until the handler is registered. An ignored stream needs no retry. Current time-only CRM declarations leave display cache until expiry and roles until other refresh paths. Return failed workspace events for retry while preserving other workspaces’ successes. Route caches without subject indexing survive up to two minutes. Invalid requests enqueue nothing. Existing pending work remains unchanged. Retry can end in dead-lettering; a missing binding fails the subject’s batch. Prior grants remain until their twenty-four-hour expiry or a successful refresh.

## Open Design Questions

Publication atomically requests current holder rechecks and bounded simulation gains.