--- id: WF-PFM-ELG-006 title: List the subjects a rule covers trigger: >- A caller with population and dataset query authority requests subjects qualifying under a release and day, with optional scope, comparison or export. 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-011 moves: - STATE-PFM-ELG-004 crosses: - SVC-PFM-ELG-eligibility idempotency: >- The workspace-and-run identity deduplicates a delivered job start. Cursor guards deduplicate page commits; repeated manual requests create different runs. concurrency: >- A task function permits two invocations; each run evaluates pages sequentially, independently of other runs. hops: - 'n': 1 actor_or_service: Population operation action: >- Prepare the release and plan, check supported providers and subject dataset, bound named subjects at 250,000, create run and job atomically, then start after commit. anchor: >- services-platform:modules/eligibility/services/population/population-run.ts:submitPopulationRun seam: sync on_failure: >- Preparation is refused before insertion; a failed post-commit start leaves the job for reconciliation. left_inconsistent: A submitted run can remain queued after a start failure. observer: The requester and job reconciler can inspect it. provenance: observed source: >- services-platform:modules/eligibility/services/population/population-run.ts:submitPopulationRun - 'n': 2 actor_or_service: Population state machine action: 'Execute the durable job’s evaluation, completion and failure steps.' anchor: >- services-platform:modules/eligibility/aws/logic/eligibility-population.step-function.ts seam: state_machine on_failure: Failed or timed-out executions settle the job and trigger alarms. left_inconsistent: Run and dependent simulation failure remain visible. observer: Execution alarms and the shared job monitor show the state. provenance: observed source: >- services-platform:modules/eligibility/services/population/population-workflow.ts:populationWorkflow - 'n': 3 actor_or_service: Population task action: >- Read ordered dataset pages, prune permitted database-only exclusions, evaluate remaining subjects in batches of one hundred and atomically store counts, subjects and cursor. anchor: >- services-platform:modules/eligibility/services/population/population-run.ts:evaluatePopulationPage seam: state_machine on_failure: >- Retries recompute a page but cannot commit it twice; an unallowed million-subject limit fails the run. left_inconsistent: Previously committed page results remain on a failed run. observer: Page diagnostics and population alarms expose failure. provenance: observed source: >- services-platform:modules/eligibility/services/population/sql-prefix.ts:sqlPrefixOf - 'n': 4 actor_or_service: Population task action: >- Calculate comparison deltas, produce any requested export, set the intended ninety-day expiry and finish a dependent simulation. anchor: >- services-platform:modules/eligibility/services/population/population-run.ts:finishPopulationRun seam: state_machine on_failure: Completion failure marks the run and simulation failed. left_inconsistent: An export written before failure can remain without cleanup. observer: Duration and outcome metrics describe completion. provenance: observed source: >- services-platform:modules/eligibility/services/population/population-failure.ts:failPopulationRunOfJob - 'n': 5 actor_or_service: Requester action: >- Read the submitted run and cursor pages of retained subjects using its returned identity. anchor: >- services-platform:modules/eligibility/aws/api/population.routes.ts:populationRoutes seam: sync on_failure: Unknown or other-workspace identities return not found. left_inconsistent: Lookup makes no business changes. observer: The original requester sees the result. provenance: observed source: >- services-platform:modules/eligibility/aws/api/population.routes.ts:populationRoutes branches: - >- Without pruning, subjects excluded by the database-only prefix still contribute ineligible counts. waits: - >- The caller polls its returned run identity; this module has no run list or cancellation operation. evidence: - >- services-platform at ad3f6a6: services/population/; aws/api/population.routes.ts; aws/logic/eligibility-population.lambda.ts, eligibility-population.step-function.ts; docs/eligibility.md §14; docs/jobs.md; docs/milestones/PLAT-M12-eligibility-who-qualifies.md (Proposed). controls: [TC-AVL-001, TC-AVL-004, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-DAT-005, 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-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] --- # List the subjects a rule covers ## What It Does A caller with population and dataset query authority requests subjects qualifying under a release and day, with optional scope, comparison or export. ## The Flow ```mermaid flowchart TD H1["Population operation" ] H2["Population state machine" ] H1 --> H2 H3["Population task" ] H2 --> H3 H4["Population task" ] H3 --> H4 H5["Requester" ] H4 --> H5 ``` Prepare the release and plan, check supported providers and subject dataset, bound named subjects at 250,000, create run and job atomically, then start after commit. Execute the durable job’s evaluation, completion and failure steps. Read ordered dataset pages, prune permitted database-only exclusions, evaluate remaining subjects in batches of one hundred and atomically store counts, subjects and cursor. Calculate comparison deltas, produce any requested export, set the intended ninety-day expiry and finish a dependent simulation. Read the submitted run and cursor pages of retained subjects using its returned identity. ## When Something Fails Preparation is refused before insertion; a failed post-commit start leaves the job for reconciliation. A submitted run can remain queued after a start failure. Failed or timed-out executions settle the job and trigger alarms. Run and dependent simulation failure remain visible. Retries recompute a page but cannot commit it twice; an unallowed million-subject limit fails the run. Previously committed page results remain on a failed run. Completion failure marks the run and simulation failed. An export written before failure can remain without cleanup. Unknown or other-workspace identities return not found. Lookup makes no business changes. ## Open Design Questions Without pruning, subjects excluded by the database-only prefix still contribute ineligible counts.