--- id: DOM-PFM-ELG-003 title: Eligibility Decision realises: CON-PFM-ELG-003 product_area: platform module: eligibility revision: 1 status: draft design_intent: confirmed origin: >- Eligibility Engine architecture approved by Andrew 2026-10-17 (D-08 three states, D-10 thirteen months and display sampling, D-17 transactional SQL function, recorded in PLAT-M11 "Decisions"); partition standard (services-platform docs/partitions.md). Population and simulation remain proposed with their milestone (PLAT-M12). implementation_evidence: observed source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owned_by: SVC-PFM-ELG-eligibility readable_by: [] lifecycle: STATE-PFM-ELG-004 custom_fields: none identity: >- A persisted decision receives a time-ordered identity at evaluation. Cache hits and unrecorded trials have none; population runs and simulations receive separate identities at submission. attributes: - name: qualification state kind: enum required: true computed: true notes: >- Reports eligible, ineligible or indeterminate and the corresponding three-valued result. - name: outcome kind: enum required: false computed: true notes: >- Applies the use policy to produce allow, deny, review or defer; the wire response can omit the outcome for defer. - name: reasons and explanation kind: collection required: true computed: true notes: >- Returns up to fifty reason codes and member or administrator explanations. Full responses include condition traces; persisted history keeps a summary trace. - name: subjects and evaluation day kind: collection required: true computed: false notes: >- Names subject slots and evaluation day. Caller facts and their trust levels are inputs rather than persisted raw fact values. - name: consistency kind: enum required: true computed: false notes: >- Selects display, authorization or transactional behavior for cache and recording policy. - name: 'use, rule, version and plan' kind: reference required: true computed: false notes: >- Retains rule, release and plan references for recorded evaluation; the use reference can be absent and historical values survive use deletion. - name: bulk run kind: collection required: false computed: false notes: >- Tracks dataset enumeration for a release and day, state counts, cursor, retained pages, bounded comparison deltas and optional export, with intended ninety-day expiry and durable job history. - name: simulation kind: collection required: false computed: false notes: >- Tracks a draft comparison over recent decision subjects, role holders and optional scope, with counts, bounded gain and loss samples, warnings, fingerprint and affected consumers, with intended thirty-day expiry. relationships: - to: DOM-PFM-ELG-002 cardinality: >- Multiple decisions can name one use; a recorded decision can also have no use reference. ownership: History retains the reference without a lifetime foreign key to the use. cross_service: false - to: DOM-PFM-ELG-001 cardinality: >- A release can be referenced by many decisions, population runs and simulations. ownership: These evaluation records retain their release context. cross_service: false invariants: - id: INV-DOM-PFM-ELG-003-01 statement: >- Ordinary application access can insert and read decisions but cannot update or delete them; retention and restricted deletion remove history. enforced_at: - database provenance: observed source: 'services-platform:docs/eligibility.md#3. Row-level security' - id: INV-DOM-PFM-ELG-003-02 statement: >- Each decision belongs to the UTC month of its evaluation and must fit that partition. enforced_at: - database provenance: observed source: >- services-platform:modules/eligibility/db/eligibility-decisions.table.ts:eligibility_decisions_month_check - id: INV-DOM-PFM-ELG-003-03 statement: >- Decision reads explicitly constrain the workspace because the history table has no ordinary row policy. enforced_at: - service provenance: observed source: 'services-platform:modules/eligibility/services/persistence/decisions.ts' - id: INV-DOM-PFM-ELG-003-04 statement: >- Authorization recording and the in-transaction evaluator await insertion; the SQL-only transaction check returns without inserting history. enforced_at: - service provenance: observed source: >- services-platform:modules/eligibility/services/evaluate/decision-recording.ts:recordDecisions - id: INV-DOM-PFM-ELG-003-05 statement: >- A missing workspace subject produces indeterminate with a not-found reason before uncertainty policy is applied. enforced_at: - service - database provenance: observed source: >- services-platform:modules/eligibility/services/evaluate/subject-existence.ts - id: INV-DOM-PFM-ELG-003-06 statement: >- Authorization, transactional, indeterminate, test and dry-run answers bypass the display cache. enforced_at: - service provenance: observed source: >- services-platform:modules/eligibility/services/evaluate/decision-cache.ts:isCacheable - id: INV-DOM-PFM-ELG-003-07 statement: >- Population pages atomically advance counts, subjects and cursor only when the stored cursor matches their starting position. enforced_at: - service - database provenance: observed source: >- services-platform:modules/eligibility/services/population/population-run.ts:evaluatePopulationPage - id: INV-DOM-PFM-ELG-003-08 statement: >- Workspace-scoped reads reject other workspaces’ decisions, runs and simulations, and workspace deletion purges them. enforced_at: - service - database provenance: observed source: >- services-platform:modules/eligibility/services/maintenance/tenant-participant.ts physical: - platform.eligibility_decisions - platform.eligibility_population_runs - platform.eligibility_population_jobs - platform.eligibility_population_job_steps - platform.eligibility_population_job_events - platform.eligibility_simulations evidence: - >- services-platform at ad3f6a6: db/eligibility-decisions.table.ts, eligibility-population-*.table.ts, eligibility-simulations.table.ts; services/evaluate/ (hosted-evaluate, pipeline, policy, decision-recording, decision-cache, subject-existence, in-transaction); services/population/; services/simulation/; services/persistence/decisions.ts; services/maintenance/tenant-participant.ts; docs/eligibility.md §3, §4, §9 to §11, §14, §15. --- # Eligibility Decision ## What It Models A decision explains qualification at a particular moment. Population and simulation records collect related evaluations for comparison and enumeration. ## Identity and Attributes Recorded history identifies the evaluated release and subject slots without storing raw caller facts. ## Relationships Rule and use references preserve evaluation context, while the job engine owns durable execution machinery. ## Invariants Recording guarantees differ by entry point and consistency; selection for history does not guarantee a deferred display insert succeeds. ## How It Is Stored and Shared Eligibility owns the append-only decision store and run records. Decisions use monthly partitions; none of these records declares custom fields. ## Open Design Questions The SQL-only path has no history insert, display persistence has no durable repair, and run expiry lacks a deployed schedule.