Eligibility

Recipient eligibility traits decide who is qualified to receive a routable — before a routing strategy runs. They are a governed qualification contract, not another general-purpose annotation: a licensed agent for a regulated product, a certified installer, a language match for support. Encoding those gates as durable traits keeps eligibility logic out of ad-hoc rules and makes "why wasn't this recipient eligible?" answerable.

Traits are administered through the management surface and evaluated during routing before selection.

Where it runs

Routing evaluates the eligibility profile bound to a pool or route before strategy selection, in this order:

The fallback mode is one of reject, queue, fallback pool, best-effort, or manual review.

Because preferred requirements emit strategy feature facts, they flow straight into the feature snapshot under the eligibility.* keys — so the strategy that runs next can prefer better-qualified recipients without eligibility having to pick the winner itself.

Trait kinds

{ "key": "skill.mortgage", "kind": "skill", "value_type": "bool" }

{ "key": "ca-bay-area", "shape_type": "postal", "postal_codes": ["94105", "94107", "94607"] }

Territory sets support postal, administrative, radius, polygon, account-list, and connector-derived coverage, and feed the eligibility.territory_match / eligibility.territory_distance_km features so a profile can require in-territory coverage or prefer closer recipients.

Connector-derived assignments

A trait assignment can be populated from a connector record through mapping/import flows:

{
  "source": "connector",
  "source_ref": {
    "provider_key": "hubspot",
    "connection_id": "conn-1",
    "sync_run_id": "sync-run-1",
    "model": "owner",
    "external_id": "owner-123",
    "record_version": "sha256:record"
  }
}

The result is still a Ductor trait assignment with its own status, evidence, expiry, and redaction behavior. If the source record is deleted or revoked, or the mapping profile drifts, the assignment is marked stale or revoked — never silently deleted.

Gotchas

Readiness and promotion

Eligibility evaluation emits a routing reliability fact with dimension eligibility and target kind eligibility_profile, carrying profile, pool, candidate, eligible, eliminated, warning, and issue counts plus redacted issue codes. A promotion candidate can include an eligibility_profile artifact whose metadata names bounded sample recipients:

{ "sample_recipient_ids": ["recipient-1", "recipient-2"], "environment_id": "prod", "pool_id": "pool-mortgage" }

Preflight runs the profile against those samples and blocks promotion on any of the failure conditions above.

Migrating from tags

Don't reinterpret tags as traits at runtime. Use tags as an input to an explicit migration preview, then create trait definitions and assignments. Typical mappings: region:west → a territory set, language:es → language.es, license:ca → a license trait with evidence and expiry. tier:premium is usually metadata or a strategy feature, not eligibility — unless it represents a governed qualification.

Related