Modelling who can get what.

-- Rules and conditions, with provenance as a first-class citizen.
CREATE TABLE eligibility_rules (
  rule_id           BIGSERIAL PRIMARY KEY,
  institution_id    TEXT NOT NULL,
  kind              TEXT NOT NULL,   -- geography | employer | association | military | family | open
  description       TEXT NOT NULL,   -- human-readable, rendered to users
  -- Provenance. Not metadata: without it a verdict cannot be explained,
  -- corrected, or aged out, which are the three things you will need most.
  source_id         BIGINT NOT NULL REFERENCES eligibility_sources(source_id),
  evidence_quote    TEXT NOT NULL,   -- the sentence that justified the rule
  observed_at       TIMESTAMPTZ NOT NULL,
  confidence        REAL NOT NULL,
  -- Supersede, never overwrite: last year's verdict must stay explainable.
  superseded_at     TIMESTAMPTZ,
  superseded_by_rule_id BIGINT
);
 
CREATE TABLE eligibility_conditions (
  condition_id  BIGSERIAL PRIMARY KEY,
  rule_id       BIGINT NOT NULL REFERENCES eligibility_rules(rule_id),
  kind          TEXT NOT NULL,
  -- Canonical keys, never free text: 'county:NC:mecklenburg'. This is what
  -- turns a fuzzy geographic question into an exact index hit.
  geo_level     TEXT,
  geo_value     TEXT,
  org_id        TEXT,
  params_json   JSONB
);
 
-- The inverse index is the whole performance story: it turns "which of 4,000
-- institutions might apply to this person" into a handful of key lookups.
CREATE INDEX ON eligibility_conditions (geo_value) WHERE geo_value IS NOT NULL;
CREATE INDEX ON eligibility_conditions (org_id)    WHERE org_id    IS NOT NULL;

// Narrow, then evaluate. The order matters and the second half is the subtle part.
function findEligible(person: Facts): Verdict[] {
  // 1. NARROW — cheap index hits from the person's facts.
  const candidates = new Set([
    ...byGeo(person.geoKeys),
    ...byOrg(person.orgIds),
    ...openToAnyone(),
  ]);
 
  // 2. EVALUATE — against each institution's FULL rule set.
  //
  //    The trap: an institution surfaced by ONE matching condition is not
  //    thereby eligible. Its rule may require that condition AND another the
  //    person fails. Scoring on the condition that surfaced the candidate is
  //    the single most common way an eligibility engine becomes confidently
  //    wrong, because it only ever over-reports.
  return [...candidates].map((id) => evaluate(allRulesFor(id), person));
}