---
id: WF-PFM-ELG-004
title: Evaluate eligibility through Platform
trigger: >-
  A permitted portal, console or service caller asks for one to fifty
  eligibility evaluations; trials and role checks use the shared pipeline.
product_area: platform
module: eligibility
revision: 1
status: draft
design_intent: confirmed
origin: >-
  Eligibility Engine architecture D-08 (three states, consumer-declared fail
  policy), D-10 (sampling) and D-31 (hosted evaluation for tests, populations
  and the decisions API), approved 2026-10-17 (PLAT-M11 "Decisions"); PLAT-M11
  plan D1 "Always check" for unknown persons
implementation_evidence: observed
inference: []
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
implements:
  - CAP-PFM-ELG-008
  - CAP-PFM-ELG-009
  - CAP-PFM-ELG-010
  - CAP-PFM-ELG-012
  - CAP-PFM-ELG-003
moves: []
crosses:
  - SVC-PFM-ELG-eligibility
idempotency: >-
  Suitable display requests can reuse a two-minute answer without history. A
  fresh selected evaluation creates another history identity when retried.
concurrency: >-
  Provider calls share a five-second budget and run in parallel. Display
  sampling is process-local per workspace and uses a configurable rate.
hops:
  - 'n': 1
    actor_or_service: Evaluate operation
    action: >-
      Check batch size, explanation level, declared caller and evaluation
      authority; reject web transactional consistency and restrict member
      display to the linked contact and asserted facts.
    anchor: >-
      services-platform:modules/eligibility/services/evaluate/evaluate-for-caller.ts:evaluateForCaller
    seam: sync
    on_failure: Invalid or unauthorized requests fail as a whole.
    left_inconsistent: No evaluation history is inserted by caller validation.
    observer: The requester receives the refusal.
    provenance: observed
    source: >-
      services-platform:modules/eligibility/services/evaluate/evaluate-for-caller.ts:kindCallerRefusal
  - 'n': 2
    actor_or_service: Hosted evaluator
    action: >-
      Prepare uses, effective or pinned releases, references, vocabulary and
      plans through memory, shared cache and durable storage.
    anchor: >-
      services-platform:modules/eligibility/services/evaluate/hosted-evaluate.ts:prepareEvaluations
    seam: sync
    on_failure: A missing or suspended use rejects the entire preparation batch.
    left_inconsistent: No partial answer is returned.
    observer: The requester or Security retry logs show the failure.
    provenance: observed
    source: >-
      services-platform:modules/eligibility/services/compile/plan-cache.ts:cachedPlan
  - 'n': 3
    actor_or_service: Hosted evaluator
    action: Reuse eligible display cache entries and evaluate the remaining requests.
    anchor: >-
      services-platform:modules/eligibility/services/evaluate/decision-cache.ts:readCachedDecisions
    seam: sync
    on_failure: Cache access failure is treated as a miss.
    left_inconsistent: The pipeline supplies a fresh result instead.
    observer: Hit and miss counters track reuse.
    provenance: observed
    source: >-
      services-platform:modules/eligibility/services/evaluate/decision-cache.ts:isCacheable
  - 'n': 4
    actor_or_service: Evaluation pipeline
    action: >-
      Verify subjects, read dataset predicates once per dataset and day, fetch
      provider facts behind workspace circuit breakers, combine three-valued
      results and apply policy and explanations.
    anchor: >-
      services-platform:modules/eligibility/services/evaluate/pipeline.ts:runPipeline
    seam: sync
    on_failure: >-
      Read and provider failures make affected results indeterminate rather than
      fail unrelated evaluations.
    left_inconsistent: Uncertainty remains explicit in the returned answer.
    observer: 'Read, provider and circuit metrics expose degraded evaluation.'
    provenance: observed
    source: >-
      services-platform:modules/eligibility/services/evaluate/failed-reads.ts:reportReadFailure
  - 'n': 5
    actor_or_service: Decision recording
    action: >-
      Await selected authorization inserts, start selected display inserts
      asynchronously, including indeterminate display results, and cache
      suitable decided answers.
    anchor: >-
      services-platform:modules/eligibility/services/evaluate/decision-recording.ts:recordDecisions
    seam: sync
    on_failure: >-
      An authorization insert failure fails the request; a deferred display
      failure only logs.
    left_inconsistent: >-
      Display history can be missing even after the response reports recording,
      with no outbox repair.
    observer: The deferred-insert log is the direct failure signal.
    provenance: observed
    source: >-
      services-platform:modules/eligibility/services/evaluate/hosted-evaluate.ts:evaluateBatch;
      services-platform:modules/eligibility/services/evaluate/decision-recording.ts:recordDecisions
  - 'n': 6
    actor_or_service: Observability
    action: >-
      Emit evaluation and provider-call diagnostics without raw facts or
      personal data.
    anchor: 'services-platform:modules/eligibility/services/observability/names.ts'
    seam: sync
    on_failure: Diagnostics provide observation rather than business compensation.
    left_inconsistent: No additional business state is maintained here.
    observer: >-
      Eligibility alarms cover uncertainty, circuits, recheck delay and
      population failure.
    provenance: observed
    source: >-
      services-platform:modules/eligibility/aws/logic/eligibility-alarms.cloudwatch.ts
branches:
  - >-
    Trials check subject-record access, request full explanations and retain no
    decision history.
  - >-
    Service callers use the same declared-purpose boundary through the service
    function.
waits: []
evidence:
  - >-
    services-platform at ad3f6a6: services/evaluate/ (evaluate-for-caller,
    hosted-evaluate, pipeline, subjects, subject-existence, providers,
    circuit-breaker, failed-reads, policy, decision-cache, decision-recording,
    test-definition); aws/api/evaluate.routes.ts, eligibility-service.routes.ts;
    aws/logic/eligibility-alarms.cloudwatch.ts; docs/eligibility.md §9 to §11,
    §18; docs/debt/eligibility-display-decision-outbox.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-CRY-001, TC-CRY-002, TC-CRY-003, TC-CRY-004, 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-001, 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]
---
# Evaluate eligibility through Platform

## What It Does

A permitted portal, console or service caller asks for one to fifty eligibility evaluations; trials and role checks use the shared pipeline.

## The Flow

```mermaid
flowchart TD
  H1["Evaluate operation" ]
  H2["Hosted evaluator" ]
  H1 --> H2
  H3["Hosted evaluator" ]
  H2 --> H3
  H4["Evaluation pipeline" ]
  H3 --> H4
  H5["Decision recording" ]
  H4 --> H5
  H6["Observability" ]
  H5 --> H6
```

Check batch size, explanation level, declared caller and evaluation authority; reject web transactional consistency and restrict member display to the linked contact and asserted facts. Prepare uses, effective or pinned releases, references, vocabulary and plans through memory, shared cache and durable storage. Reuse eligible display cache entries and evaluate the remaining requests. Verify subjects, read dataset predicates once per dataset and day, fetch provider facts behind workspace circuit breakers, combine three-valued results and apply policy and explanations. Await selected authorization inserts, start selected display inserts asynchronously, including indeterminate display results, and cache suitable decided answers. Emit evaluation and provider-call diagnostics without raw facts or personal data.

## When Something Fails

Invalid or unauthorized requests fail as a whole. No evaluation history is inserted by caller validation. A missing or suspended use rejects the entire preparation batch. No partial answer is returned. Cache access failure is treated as a miss. The pipeline supplies a fresh result instead. Read and provider failures make affected results indeterminate rather than fail unrelated evaluations. Uncertainty remains explicit in the returned answer. An authorization insert failure fails the request; a deferred display failure only logs. Display history can be missing even after the response reports recording, with no outbox repair. Diagnostics provide observation rather than business compensation. No additional business state is maintained here.

## Open Design Questions

Trials check subject-record access, request full explanations and retain no decision history. Service callers use the same declared-purpose boundary through the service function.