--- id: SVC-PFM-ELG-eligibility title: Eligibility Service Module product_area: platform module: eligibility repository: services-platform source_module: modules/eligibility revision: 1 status: draft design_intent: confirmed origin: >- Eligibility Engine architecture approved by Andrew 2026-10-17 (decision groups D-01/D-31/D-11/D-12, D-22/D-23/D-25, D-18 to D-21 and D-13/D-10/D-14; PLAT-M11 "Decisions"); PLAT-M11 plan D1 to D8 (2026-10-21). Population and simulation operations stay proposed with PLAT-M12. implementation_evidence: observed inference: [] source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owns: - DOM-PFM-ELG-001 - DOM-PFM-ELG-002 - DOM-PFM-ELG-003 does_not_own: - >- Security maintains role grants, authorization policy, recheck execution and baseline staff access. - >- Queries owns dataset interpretation, predicate execution, enumeration and dataset read grants. - Metadata owns objects and the custom fields inspected by rules. - >- Applications own their vocabulary, fact providers, consumer records and the business consequences of qualification. - The shared job engine executes and reconciles durable work. - >- Operations and workspace lifecycle coordinate partition maintenance and deletion. - Retired conversion work is outside this module. operations: - operation_id: getEligibilityHealth intent: Expose the deployed eligibility build without querying business records. access: public permission: >- none: public health route (the operation name follows the getHealth pattern of the shared health route) realises: - CAP-PFM-ELG-012 published_to_submissions: 'not published: build diagnostics capture no domain request' provenance: documented source: >- services-platform:modules/eligibility/aws/api/eligibility.routes.ts:healthRoute - operation_id: getEligibilityTenantHealth intent: >- Exercise workspace authorization and return deployed build information without business data. access: console permission: platform.eligibility.read realises: - CAP-PFM-ELG-012 published_to_submissions: 'not published: this infrastructure operation has no domain intake contract' provenance: observed source: >- services-platform:modules/eligibility/aws/api/eligibility.routes.ts:getEligibilityTenantHealth - operation_id: listEligibilityConditionTypes intent: >- Return licensed condition declarations, including deprecated types only when requested. access: console permission: platform.eligibility.read realises: - CAP-PFM-ELG-006 published_to_submissions: 'not published: retrieving existing information creates no domain intake' provenance: observed source: >- services-platform:modules/eligibility/aws/api/eligibility.routes.ts:listEligibilityConditionTypes - operation_id: listEligibilityConsumerKinds intent: Return the purposes declared by licensed applications. access: console permission: platform.eligibility.read realises: - CAP-PFM-ELG-006 published_to_submissions: 'not published: retrieving existing information creates no domain intake' provenance: observed source: >- services-platform:modules/eligibility/aws/api/eligibility.routes.ts:listEligibilityConsumerKinds - operation_id: listEligibilityDefinitions intent: >- Search workspace definitions in key order using lifecycle, owner, reuse, subject, condition and text filters, with usage counts. access: console permission: platform.eligibility.read realises: - CAP-PFM-ELG-002 published_to_submissions: 'not published: retrieving existing information creates no domain intake' provenance: observed source: >- services-platform:modules/eligibility/aws/api/definitions.routes.ts:listEligibilityDefinitions - operation_id: createEligibilityDefinition intent: >- Allocate a permanent readable definition key and optionally save its first draft, returning validation details. access: console permission: platform.eligibility.write realises: - CAP-PFM-ELG-001 published_to_submissions: 'not published: this infrastructure operation has no domain intake contract' provenance: observed source: >- services-platform:modules/eligibility/aws/api/definitions.routes.ts:createEligibilityDefinition - operation_id: getEligibilityDefinition intent: 'Retrieve the definition, current draft, latest release and usage totals.' access: console permission: platform.eligibility.read realises: - CAP-PFM-ELG-002 published_to_submissions: 'not published: retrieving existing information creates no domain intake' provenance: observed source: >- services-platform:modules/eligibility/aws/api/definitions.routes.ts:getEligibilityDefinition - operation_id: updateEligibilityDefinition intent: >- Update descriptive values using the read version; expanding reuse additionally checks publishing authority. access: console permission: platform.eligibility.write (evaluates platform.eligibility.publish) realises: - CAP-PFM-ELG-001 published_to_submissions: 'not published: this infrastructure operation has no domain intake contract' provenance: observed source: >- services-platform:modules/eligibility/aws/api/definitions.routes.ts:updateEligibilityDefinition - operation_id: saveEligibilityDefinitionDraft intent: >- Replace the editable draft even when it has problems, checking a supplied draft version. access: console permission: platform.eligibility.write realises: - CAP-PFM-ELG-001 published_to_submissions: 'not published: this infrastructure operation has no domain intake contract' provenance: observed source: >- services-platform:modules/eligibility/aws/api/definitions.routes.ts:saveEligibilityDefinitionDraft - operation_id: validateEligibilityDefinition intent: >- Check publication readiness and return validation details and a readable summary without saving. access: console permission: platform.eligibility.read realises: - CAP-PFM-ELG-001 published_to_submissions: 'not published: retrieving existing information creates no domain intake' provenance: observed source: >- services-platform:modules/eligibility/aws/api/definitions.routes.ts:validateEligibilityDefinition - operation_id: listEligibilityDefinitionVersions intent: Retrieve draft and released versions in descending version order. access: console permission: platform.eligibility.read realises: - CAP-PFM-ELG-004 published_to_submissions: 'not published: retrieving existing information creates no domain intake' provenance: observed source: >- services-platform:modules/eligibility/aws/api/definitions.routes.ts:listEligibilityDefinitionVersions - operation_id: getEligibilityDefinitionVersion intent: Retrieve the expression and summary of a requested release. access: console permission: platform.eligibility.read realises: - CAP-PFM-ELG-004 published_to_submissions: 'not published: retrieving existing information creates no domain intake' provenance: observed source: >- services-platform:modules/eligibility/aws/api/definitions.routes.ts:getEligibilityDefinitionVersion - operation_id: diffEligibilityDefinitionVersions intent: >- Explain expression additions, deletions and modifications between two versions. access: console permission: platform.eligibility.read realises: - CAP-PFM-ELG-004 published_to_submissions: 'not published: retrieving existing information creates no domain intake' provenance: observed source: >- services-platform:modules/eligibility/aws/api/definitions.routes.ts:diffEligibilityDefinitionVersions - operation_id: publishEligibilityDefinition intent: >- Freeze the checked draft into the next release with publication choices, rejecting incompatible followers unless force suspends them. access: console permission: platform.eligibility.publish realises: - CAP-PFM-ELG-004 - CAP-PFM-ELG-010 - CAP-PFM-ELG-011 published_to_submissions: 'not published: this infrastructure operation has no domain intake contract' provenance: observed source: >- services-platform:modules/eligibility/aws/api/definitions.routes.ts:publishEligibilityDefinition - operation_id: republishEligibilityDefinitionVersion intent: >- Publish selected earlier logic under a new release number while retaining the draft. access: console permission: platform.eligibility.publish realises: - CAP-PFM-ELG-004 - CAP-PFM-ELG-010 published_to_submissions: 'not published: this infrastructure operation has no domain intake contract' provenance: observed source: >- services-platform:modules/eligibility/aws/api/definitions.routes.ts:republishEligibilityDefinitionVersion - operation_id: testEligibilityDefinition intent: >- Evaluate draft or release logic on an accessible subject without history recording and with full explanation. access: console permission: platform.eligibility.read (evaluates the record types' read keys) realises: - CAP-PFM-ELG-003 published_to_submissions: 'not published: retrieving existing information creates no domain intake' provenance: observed source: >- services-platform:modules/eligibility/aws/api/definitions.routes.ts:testEligibilityDefinition - operation_id: getEligibilityDefinitionUsage intent: Retrieve consumer uses by purpose and live rule references. access: console permission: platform.eligibility.read realises: - CAP-PFM-ELG-002 published_to_submissions: 'not published: retrieving existing information creates no domain intake' provenance: observed source: >- services-platform:modules/eligibility/aws/api/definitions.routes.ts:getEligibilityDefinitionUsage - operation_id: duplicateEligibilityDefinition intent: >- Create another definition whose draft copies the latest release or available draft. access: console permission: platform.eligibility.write realises: - CAP-PFM-ELG-001 published_to_submissions: 'not published: this infrastructure operation has no domain intake contract' provenance: observed source: >- services-platform:modules/eligibility/aws/api/definitions.routes.ts:duplicateEligibilityDefinition - operation_id: deprecateEligibilityDefinition intent: Stop accepting new uses and optionally designate a replacement. access: console permission: platform.eligibility.retire realises: - CAP-PFM-ELG-005 published_to_submissions: 'not published: this infrastructure operation has no domain intake contract' provenance: observed source: >- services-platform:modules/eligibility/aws/api/definitions.routes.ts:deprecateEligibilityDefinition - operation_id: archiveEligibilityDefinition intent: >- Retain an inactive definition after checking active dependencies are absent. access: console permission: platform.eligibility.retire realises: - CAP-PFM-ELG-005 published_to_submissions: 'not published: this infrastructure operation has no domain intake contract' provenance: observed source: >- services-platform:modules/eligibility/aws/api/definitions.routes.ts:archiveEligibilityDefinition - operation_id: deleteEligibilityDefinition intent: >- Remove an unreleased definition only when no use or reference depends on it. access: console permission: platform.eligibility.retire realises: - CAP-PFM-ELG-005 published_to_submissions: 'not published: this infrastructure operation has no domain intake contract' provenance: observed source: >- services-platform:modules/eligibility/aws/api/definitions.routes.ts:deleteEligibilityDefinition - operation_id: restoreEligibilityDefinition intent: Reactivate an archived or deprecated definition. access: console permission: platform.eligibility.retire realises: - CAP-PFM-ELG-005 published_to_submissions: 'not published: this infrastructure operation has no domain intake contract' provenance: observed source: >- services-platform:modules/eligibility/aws/api/definitions.routes.ts:restoreEligibilityDefinition - operation_id: migrateEligibilityDefinitionReferences intent: >- Move compatible following consumers and republish following references, reporting pins left for review. access: console permission: platform.eligibility.retire realises: - CAP-PFM-ELG-005 published_to_submissions: 'not published: this infrastructure operation has no domain intake contract' provenance: observed source: >- services-platform:modules/eligibility/aws/api/definitions.routes.ts:migrateEligibilityDefinitionReferences - operation_id: createEligibilityBinding intent: >- Create a consumer connection after purpose and expression compatibility checks. access: console permission: platform.eligibility-bindings.manage realises: - CAP-PFM-ELG-007 published_to_submissions: 'not published: this infrastructure operation has no domain intake contract' provenance: observed source: >- services-platform:modules/eligibility/aws/api/bindings.routes.ts:createEligibilityBinding - operation_id: listEligibilityBindings intent: >- Page connections by rule or consumer application, supporting up to one hundred consumer-reference filters. access: console permission: platform.eligibility-bindings.manage realises: - CAP-PFM-ELG-007 published_to_submissions: 'not published: retrieving existing information creates no domain intake' provenance: observed source: >- services-platform:modules/eligibility/aws/api/bindings.routes.ts:listEligibilityBindings - operation_id: getEligibilityBinding intent: Retrieve a workspace-scoped consumer connection. access: console permission: platform.eligibility-bindings.manage realises: - CAP-PFM-ELG-007 published_to_submissions: 'not published: retrieving existing information creates no domain intake' provenance: observed source: >- services-platform:modules/eligibility/aws/api/bindings.routes.ts:getEligibilityBinding - operation_id: updateEligibilityBinding intent: >- Refit and update consumer label, release selection, parameters, policy or status under an expected version. access: console permission: platform.eligibility-bindings.manage realises: - CAP-PFM-ELG-007 published_to_submissions: 'not published: this infrastructure operation has no domain intake contract' provenance: observed source: >- services-platform:modules/eligibility/aws/api/bindings.routes.ts:updateEligibilityBinding - operation_id: deleteEligibilityBinding intent: Delete the connection and plans while preserving recorded evaluations. access: console permission: platform.eligibility-bindings.manage realises: - CAP-PFM-ELG-007 published_to_submissions: 'not published: this infrastructure operation has no domain intake contract' provenance: observed source: >- services-platform:modules/eligibility/aws/api/bindings.routes.ts:deleteEligibilityBinding - operation_id: getEligibilityBindingPlan intent: Return a redacted console plan with conditional version-tag support. access: console permission: platform.eligibility.read realises: - CAP-PFM-ELG-007 published_to_submissions: 'not published: retrieving existing information creates no domain intake' provenance: observed source: >- services-platform:modules/eligibility/aws/api/bindings.routes.ts:getEligibilityBindingPlan - operation_id: createEligibilityBindingForService intent: Create a consumer connection using the calling service principal. access: internal permission: platform.eligibility-bindings.manage realises: - CAP-PFM-ELG-007 published_to_submissions: 'not published: this infrastructure operation has no domain intake contract' provenance: observed source: >- services-platform:modules/eligibility/aws/api/eligibility-service.routes.ts:createEligibilityBindingForService - operation_id: listEligibilityBindingsForService intent: Retrieve connections available to the calling consumer service. access: internal permission: platform.eligibility-bindings.manage realises: - CAP-PFM-ELG-007 published_to_submissions: 'not published: this infrastructure operation has no domain intake contract' provenance: observed source: >- services-platform:modules/eligibility/aws/api/eligibility-service.routes.ts:listEligibilityBindingsForService - operation_id: getEligibilityBindingForService intent: Retrieve one connection as its consumer service. access: internal permission: platform.eligibility-bindings.manage realises: - CAP-PFM-ELG-007 published_to_submissions: 'not published: this infrastructure operation has no domain intake contract' provenance: observed source: >- services-platform:modules/eligibility/aws/api/eligibility-service.routes.ts:getEligibilityBindingForService - operation_id: updateEligibilityBindingForService intent: >- Change a service connection with its expected version and compatibility checks. access: internal permission: platform.eligibility-bindings.manage realises: - CAP-PFM-ELG-007 published_to_submissions: 'not published: this infrastructure operation has no domain intake contract' provenance: observed source: >- services-platform:modules/eligibility/aws/api/eligibility-service.routes.ts:updateEligibilityBindingForService - operation_id: deleteEligibilityBindingForService intent: Remove a connection as the consumer service. access: internal permission: platform.eligibility-bindings.manage realises: - CAP-PFM-ELG-007 published_to_submissions: 'not published: this infrastructure operation has no domain intake contract' provenance: observed source: >- services-platform:modules/eligibility/aws/api/eligibility-service.routes.ts:deleteEligibilityBindingForService - operation_id: getEligibilityBindingPlanForService intent: >- Return the complete service plan and conditional version tag for local evaluation. access: internal permission: platform.eligibility.read realises: - CAP-PFM-ELG-007 published_to_submissions: 'not published: this infrastructure operation has no domain intake contract' provenance: observed source: >- services-platform:modules/eligibility/aws/api/eligibility-service.routes.ts:getEligibilityBindingPlanForService - operation_id: evaluateEligibilityForService intent: >- Evaluate a bounded service batch using consistency permitted by its declared purpose. access: internal permission: platform.eligibility.read realises: - CAP-PFM-ELG-008 published_to_submissions: 'not published: this infrastructure operation has no domain intake contract' provenance: observed source: >- services-platform:modules/eligibility/aws/api/eligibility-service.routes.ts:evaluateEligibilityForService - operation_id: evaluateEligibility intent: >- Evaluate a bounded staff or member batch with authorized explanations; member access is self-only display. access: portal permission: >- platform.security-self.read (evaluates platform.eligibility.read; the purpose's declared callers decide admission) realises: - CAP-PFM-ELG-008 - CAP-PFM-ELG-009 - CAP-PFM-ELG-010 published_to_submissions: 'not published: this infrastructure operation has no domain intake contract' provenance: observed source: >- services-platform:modules/eligibility/aws/api/evaluate.routes.ts:evaluateEligibility - operation_id: listEligibilityDecisions intent: Page stored subject or rule history newest first without traces. access: console permission: platform.eligibility.read realises: - CAP-PFM-ELG-009 published_to_submissions: 'not published: retrieving existing information creates no domain intake' provenance: observed source: >- services-platform:modules/eligibility/aws/api/evaluate.routes.ts:listEligibilityDecisions - operation_id: getEligibilityDecision intent: Retrieve a recorded answer including its retained summary trace. access: console permission: platform.eligibility.read realises: - CAP-PFM-ELG-009 published_to_submissions: 'not published: retrieving existing information creates no domain intake' provenance: observed source: >- services-platform:modules/eligibility/aws/api/evaluate.routes.ts:getEligibilityDecision - operation_id: startEligibilityPopulationRun intent: >- Submit durable enumeration for a release and dataset, optionally comparing results or producing an export. access: console permission: platform.eligibility.population (evaluates the dataset query keys) realises: - CAP-PFM-ELG-011 published_to_submissions: 'not published: this infrastructure operation has no domain intake contract' provenance: observed source: >- services-platform:modules/eligibility/aws/api/population.routes.ts:startEligibilityPopulationRun - operation_id: getEligibilityPopulationRun intent: >- Retrieve run progress, totals, deltas and a page of retained subject results. access: console permission: platform.eligibility.population realises: - CAP-PFM-ELG-011 published_to_submissions: 'not published: retrieving existing information creates no domain intake' provenance: observed source: >- services-platform:modules/eligibility/aws/api/population.routes.ts:getEligibilityPopulationRun - operation_id: startEligibilitySimulation intent: Submit comparison of the draft with its latest release. access: console permission: platform.eligibility.publish (evaluates the dataset query keys) realises: - CAP-PFM-ELG-011 published_to_submissions: 'not published: this infrastructure operation has no domain intake contract' provenance: observed source: >- services-platform:modules/eligibility/aws/api/population.routes.ts:startEligibilitySimulation - operation_id: getEligibilitySimulation intent: Retrieve completed or running simulation impact and summary. access: console permission: platform.eligibility.publish realises: - CAP-PFM-ELG-011 published_to_submissions: 'not published: retrieving existing information creates no domain intake' provenance: observed source: >- services-platform:modules/eligibility/aws/api/population.routes.ts:getEligibilitySimulation - operation_id: requestEligibilityReconcile intent: >- Request role checks for at most one hundred subjects, reusing pending requests. access: internal permission: 'platform.eligibility.reconcile (system access, staff-only key)' realises: - CAP-PFM-ELG-010 published_to_submissions: 'not published: this infrastructure operation has no domain intake contract' provenance: observed source: >- services-platform:modules/eligibility/aws/api/reconcile.routes.ts:requestEligibilityReconcile events: - name: platform.eligibility.definition.published direction: produced when: >- Publication and rollback invoke the in-process subscriber inside their transaction; this is not an external event bus. payload_summary: 'Carries workspace, definition, release and bounded role-check subjects.' - name: eligibility.change (audit event) direction: produced when: >- Accepted definition and binding mutations append audit in the business transaction. payload_summary: >- Includes actor, record, action, release and change details with simulation choice. - name: CRM contact and organization change events direction: consumed when: >- The record-event handler can consume registered CRM streams for event-refresh declarations; CRM registration remains absent. payload_summary: Carries up to one hundred stream events with workspace and record changes. jobs: - >- Population and simulation use platform_eligibility_population and the platform-eligibility-population state machine. - >- Deployment invokes platform_eligibility_registration with complete manifests. - Registered CRM delivery would invoke platform_eligibility_change_events. - >- Consumer principals call platform_eligibility_service for service operations. - >- Uncertainty, provider circuit, role-check delay and population execution have alarms. - >- Operations maintains decision partitions and workspace deletion calls the eligibility participant. integrations: - system: Application provider functions direction: outbound contract: >- Declared provider functions receive batched synchronous requests within a shared five-second budget, with one eligible transport retry and workspace circuit protection. - system: Shared cache cluster (queries module) direction: outbound contract: >- Optional shared plan copies live twenty-four hours and display results two minutes; generation and circuit state use the same shared cache boundary. - system: Reporting layer direction: outbound contract: >- The read-only eligibility reader executes reporting predicates, projections and subject enumeration. - system: Security direction: outbound contract: >- Eligibility records queued role-check requests; Security owns grants and decision reads used by authorization. - system: Consumer transactions direction: inbound contract: >- The recorded evaluator uses the consumer transaction through its system reader; the SQL-only function uses the caller’s row policy and returns without history insertion. consistency: - rule: >- Release, supersession, forced suspensions, plan deletion, audit and queued role checks commit in one transaction. kind: transactional compensation: A refused publication rolls back all these mutations. - rule: >- Input fingerprints select fresh plans after a rule change; old display results expire within two minutes. kind: eventual compensation: Optional cache cleanup has no compensating business write. - rule: >- The recorded transaction evaluator inserts history with the business change; the SQL-only check does not. kind: transactional compensation: The caller’s rollback discards its transactional insertion. - rule: >- Authorization insertion is awaited, while selected display insertion is deferred even for uncertain answers. kind: eventual compensation: Deferred failures are logged without durable history recovery. - rule: A vocabulary manifest commits atomically. kind: transactional compensation: Invalid registration leaves the previous catalogue. - rule: 'Role refresh follows successful queued checks, sign-in and overnight work.' kind: eventual compensation: Failed refresh leaves grants until their time-to-live expires. - rule: >- Each population page commits counts, subjects and cursor under a matching cursor guard. kind: transactional compensation: >- Run failure marks the dependent simulation failed without undoing earlier pages. evidence: - >- services-platform at ad3f6a6: modules/eligibility/aws/api/*.routes.ts, eligibility.schemas.ts; aws/lambda/*; aws/logic/*; services/**; aws/platform.service.ts (ELIGIBILITY and ELIGIBILITY_BINDINGS permission groups); docs/eligibility.md; docs/proposals/eligibility/17-decision-register.md; docs/standards/submission-compatible-operations.md. - 'react-console at baf6dae: lib/eligibility/api.ts; components/eligibility/**.' controls: [TC-AVL-001, TC-AVL-004, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, 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-CRY-001, TC-CRY-002, TC-CRY-003, TC-CRY-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-DAT-005, TC-IAM-001, TC-IAM-002, TC-IAM-003, 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-TEN-004, TC-VEN-001, TC-VEN-002, TC-VEN-003] --- # Eligibility Service Module ## What This Service Is For Eligibility lets applications express qualification once and obtain a reasoned result under the policy appropriate to each use. ## Boundary It owns definitions, versions, vocabulary, bindings, plans, recorded decisions and evaluation runs. Applications retain their business records and Security retains grant ownership. ## Operations in Words Authoring and governance manage definitions and releases; binding operations connect consumer decisions; evaluation explains answers; history, population and simulation support review. Public and workspace health exercise separate access paths. ## Events and Jobs Publication notification is in process, change trails are audited and CRM event consumption awaits registration. Population and simulation use the shared durable-job machinery. No model inference occurs. ## Consistency Guarantees The contract distinguishes atomic publication from eventual cache and role refresh, and recorded transaction checks from SQL-only checks. Display history may be lost after a successful response.