---
id: CAP-PFM-ELG-011
title: List qualifying subjects and assess a draft’s impact
feature: FEAT-PFM-ELG-03
product_area: platform
module: eligibility
revision: 1
status: draft
product_intent: proposed
implementation_evidence: partially-observed
supersedes:
  - CAP-ELIG-POP-001
  - CAP-ELIG-POP-002
  - CAP-ELIG-POP-003
  - CAP-ELIG-POP-004
  - CAP-ELIG-POP-005
  - CAP-ELIG-POP-006
  - CAP-ELIG-POP-007
  - CAP-ELIG-POP-008
  - CAP-ELIG-POP-009
  - CAP-ELIG-POP-010
  - CAP-ELIG-POP-011
  - CAP-ELIG-POP-012
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
intent_sources:
  - >-
    services-platform:docs/milestones/PLAT-M12-eligibility-who-qualifies.md#Scope
    in one paragraph
purpose: >-
  A population run explains the reach of one version. A simulation helps staff
  assess how a proposed expression changes that reach.
outcomes:
  - 'Completed bulk work separates qualifying, refusing and uncertain subjects.'
  - A release can cite its measured impact on subjects.
concepts:
  - CON-PFM-ELG-003
  - CON-PFM-ELG-001
actors:
  - ACT-PFM-023
surfaces:
  - console
  - api
  - job
preconditions: []
postconditions: []
permissions:
  - key: platform.eligibility.population
    where_checked: api
    scope: tenant
  - key: platform.eligibility.publish
    where_checked: api
    scope: tenant
  - key: crm.contacts.query
    where_checked: service
    scope: tenant
rules:
  - id: BR-CAP-PFM-ELG-011-01
    proved_by: [ATS-PFM-ELG-011-01, TST-PFM-ELG-267, TST-PFM-ELG-268, TST-PFM-ELG-414]
    statement: >-
      Population start and read require population authority plus the dataset
      query permission; simulation start and read require publish authority plus
      that dataset permission.
    kind: permission
    enforced_at:
      - api
      - service
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/eligibility/tests/e2e/eligibility-population.e2e.spec.js#refuses
      a population run to a caller without the dataset query key, 403 naming it
    origin: none
  - id: BR-CAP-PFM-ELG-011-02
    proved_by: [ATS-PFM-ELG-011-02, TST-PFM-ELG-264, TST-PFM-ELG-265, TST-PFM-ELG-266, TST-PFM-ELG-464]
    statement: >-
      Population runs evaluate an effective or numbered version on its subject
      dataset, optionally filtered, rejecting compile failures, nonbatch
      providers, a foreign dataset, more than 250,000 explicit subjects or
      saved-query output before creating a run.
    kind: validation
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/eligibility/tests/integration/services/population/population-run.integration.spec.js#refuses
      a rule whose provider type cannot be called in batches, and creates no run
    origin: none
  - id: BR-CAP-PFM-ELG-011-03
    proved_by: [ATS-PFM-ELG-011-03, TST-PFM-ELG-274, TST-PFM-ELG-464, TST-PFM-ELG-489]
    statement: >-
      Eligible-only runs prune subjects excluded by database conditions, but
      provider-dependent branches cannot eliminate candidates in advance.
    kind: calculation
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/eligibility/tests/integration/services/population/population-run.integration.spec.js#enumerates
      only the subjects the sql prefix keeps when the run asks for the eligible
      alone
    origin: none
  - id: BR-CAP-PFM-ELG-011-04
    proved_by: [ATS-PFM-ELG-011-04, ATS-PFM-ELG-011-11, ATS-PFM-ELG-012-09, TST-PFM-ELG-464]
    statement: >-
      Population jobs persist each cursor page once and resume after
      interruptions, with runs exceeding one million subjects stopped unless
      explicitly allowed.
    kind: invariant
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/eligibility/tests/integration/services/population/population-run.integration.spec.js#records
      a retried page once: the second attempt from the old cursor changes
      nothing
    origin: none
  - id: BR-CAP-PFM-ELG-011-05
    proved_by: [ATS-PFM-ELG-011-05, TST-PFM-ELG-275, TST-PFM-ELG-464]
    statement: >-
      Completed runs expose state counts and ordered pages of at most 1,000
      subject references, comparison gains and losses limited to 10,000 each,
      unchanged counts and optional reference-and-state exports.
    kind: calculation
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/eligibility/tests/integration/services/population/population-run.integration.spec.js#answers
      the subjects newly eligible against the earlier run, and none no longer
      eligible
    origin: none
  - id: BR-CAP-PFM-ELG-011-06
    proved_by: [ATS-PFM-ELG-011-06, TST-PFM-ELG-464]
    statement: >-
      Simulations compare a draft and publication over recent decision subjects,
      derived-role holders and any requested scope, returning state changes and
      affected bindings and references, with nonbatch providers making results
      partial.
    kind: calculation
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/eligibility/tests/integration/services/population/population-run.integration.spec.js#counts
      each state before and after the change over the same subjects
    origin: none
  - id: BR-CAP-PFM-ELG-011-07
    proved_by: [ATS-PFM-ELG-004-17, ATS-PFM-ELG-010-09, ATS-PFM-ELG-011-07, ATS-PFM-ELG-011-09, ATS-PFM-ELG-011-10, TST-PFM-ELG-167, TST-PFM-ELG-271, TST-PFM-ELG-464]
    statement: >-
      Publication may cite a completed simulation of its current draft or record
      a skip, rejecting both choices together, foreign simulations, unfinished
      simulations and results for earlier drafts.
    kind: validation
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/eligibility/tests/integration/services/population/population-run.integration.spec.js#refuses
      a publish naming a simulation of another version of the draft
    origin: none
  - id: BR-CAP-PFM-ELG-011-08
    proved_by: [ATS-PFM-ELG-011-08, TST-PFM-ELG-458, TST-PFM-ELG-460]
    statement: >-
      Population runs have a 90-day retention target and simulations 30 days;
      the product should enforce expiry, but scheduled cleanup is absent.
    kind: lifecycle
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/eligibility/tests/integration/services/persistence/population-runs.integration.spec.js#expires
      the settled run once its time has come, and only in its own tenant
    origin: none
  - id: BR-CAP-PFM-ELG-011-09
    proved_by: [ATS-PFM-ELG-011-12, TST-PFM-ELG-437]
    statement: >-
      Population and simulation reads conceal other workspaces’ records, and
      workspace deletion removes their runs and simulations.
    kind: invariant
    enforced_at:
      - service
      - database
    must_prove: true
    provenance: observed
    source: >-
      services-platform:modules/eligibility/services/maintenance/tenant-participant.ts
    origin: none
  - id: BR-CAP-PFM-ELG-011-10
    proved_by: []
    statement: >-
      The product exposes run lookup by its returned identity but offers neither
      a run list nor cancellation.
    kind: policy
    enforced_at:
      - api
    must_prove: false
    provenance: test
    source: >-
      react-console:acceptance/eligibility/playwright/journeys/population/ELIG-ACC-0450.spec.ts#ELIG-ACC-0450
    origin: none
scenarios:
  - id: SC-CAP-PFM-ELG-011-01
    given: A director needs a renewal population.
    when: They run the active-member expression on chapter contacts.
    then: >-
      Completed output gives state counts and pages without omissions or
      repeats.
    provenance: test
    source: >-
      services-platform:modules/eligibility/tests/integration/services/population/population-run.integration.spec.js#succeeds
      and counts every state of the planted contacts
  - id: SC-CAP-PFM-ELG-011-02
    given: A draft broadens the rate to inactive members.
    when: The director simulates and publishes with that result.
    then: >-
      Publication records the gains and losses and queues newly eligible
      subjects.
    provenance: test
    source: >-
      react-console:acceptance/eligibility/playwright/journeys/population/ELIG-ACC-0446.spec.ts#ELIG-ACC-0446
edge_cases: []
constraints: []
depends_on:
  - CAP-PFM-ELG-008
related:
  - CAP-PFM-ELG-004
  - CAP-PFM-ELG-010
journeys:
  - JNY-PFM-ELG-003
open_questions:
  - OQ-PFM-ELG-001
  - OQ-PFM-ELG-002
evidence:
  - >-
    services-platform: docs/eligibility.md;
    docs/milestones/PLAT-M11-eligibility-rules.md,
    PLAT-M12-eligibility-who-qualifies.md,
    PLAT-M13-eligibility-roles-and-permissions.md, plans/PLAT-M11-plan.md;
    docs/proposals/eligibility/17-decision-register.md;
    modules/eligibility/aws/api/population.routes.ts, services/population/**
    (population-run.ts, population-workflow.ts, sql-prefix.ts,
    population-failure.ts), services/simulation/**,
    services/persistence/population-runs.ts, simulations.ts,
    aws/logic/eligibility-population.step-function.ts,
    db/eligibility-population-runs.table.ts, eligibility-simulations.table.ts,
    eligibility-population-jobs.table.ts, _job_steps, _job_events;
    docs/debt/eligibility-population-deployment.md; rule-level source and test
    references
  - >-
    react-console: components/eligibility/governance/publish-dialog.tsx,
    simulation-summary.tsx; acceptance/eligibility/journeys/population/*.json.
controls: [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-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]
exercised_by: [FAS-PFM-ELG-03-01, FAS-PFM-ELG-03-02, FAS-PFM-ELG-03-03, FAS-PFM-ELG-03-04, FAS-PFM-ELG-03-05]
suites: [TST-PFM-ELG-167, TST-PFM-ELG-264, TST-PFM-ELG-265, TST-PFM-ELG-266, TST-PFM-ELG-267, TST-PFM-ELG-268, TST-PFM-ELG-271, TST-PFM-ELG-274, TST-PFM-ELG-275, TST-PFM-ELG-414, TST-PFM-ELG-437, TST-PFM-ELG-458, TST-PFM-ELG-460, TST-PFM-ELG-464, TST-PFM-ELG-489]
---
# List qualifying subjects and assess a draft’s impact

## Purpose

A population run explains the reach of one version. A simulation helps staff assess how a proposed expression changes that reach.

## How It Works

The caller chooses a version, date and subject scope. Dataset query authority is required in addition to the run or simulation permission. Platform submits background work and returns its identity. Pages persist progress so interrupted work can resume. Eligible-only work can avoid records already excluded by database predicates. Completed results offer counts, subject pages and optional exports. Comparisons identify changes between runs or versions. A draft simulation adds the consumers and references affected by publication. A publisher can attach that result or record a skip. Staff currently have no run list or cancel action, and scheduled retention cleanup is missing.

## Relationships

- Determine eligibility with an explanation supplies the evaluation pipeline for each subject page.