cap: Documentation
Browse Sign In

Specificity

Scoring rules, tie behavior by subsystem, and ranking policy

Purpose

Specificity measures how constrained a URN is. It is used for ranking among valid dispatch candidates — NOT for validity. Dispatch validity is determined by the dispatch predicate (see Dispatch); specificity determines which valid candidate to prefer.

Tagged URN Score

TaggedUrn::specificity uses graded scores per tag:

Value Score Meaning
K=v (exact value) 3 Most specific — constrains to one value
K=* (must-have-any) 2 Requires presence, any value
K=! (must-not-have) 1 Requires absence
K=? (unspecified) 0 No constraint (least specific)

$\text{Total score} = \sum \text{per-tag scores}$.

specificity_tuple() also exists but is not universally used by CAP selection paths.

CAP URN Score

CapUrn::specificity counts three components:

  1. Input media tags: in_media.inner().tags.len() — number of tags in the input media URN (0 if in=media: which is the wildcard identity)
  2. Output media tags: out_media.inner().tags.len() — same for output
  3. Non-direction tags: +1 for each non-wildcard ($\neq$ *) non-direction tag
$$ \text{specificity} = \text{in_tag_count} + \text{out_tag_count} + \text{non_wildcard_cap_tag_count} $$

This is a tag-count scoring system, not the graded scoring used by generic TaggedUrn. The distinction matters: Cap URN specificity counts tags (0 or 1 per tag), while TaggedUrn specificity grades values (0-3 per tag).

Examples

Cap URN in tags out tags cap tags Score
cap:in=media:;out=media: 0 0 0 0
cap:in="media:pdf";out=media:;op=extract 1 0 1 2
cap:in="media:pdf;bytes";out="media:text";op=extract 2 1 1 4

Properties

  • Non-negative: $\text{specificity} \geq 0$
  • Zero for identity: cap:in=media:;out=media: has specificity 0
  • Monotonic: adding a tag can only increase specificity
  • Deterministic: same input always produces the same score

Ranking Among Valid Providers

Given a request and multiple providers that pass the dispatch predicate, ranking uses specificity distance:

$$ \text{dist}(p, r) = \text{specificity}(p) - \text{specificity}(r) $$

Preference order:

  1. Exact match (dist = 0) — provider is exactly as specific as request
  2. Refinement (dist > 0) — provider is more specific than request
  3. Fallback (dist < 0) — provider is less specific than request

Within each category, higher absolute specificity is preferred.

Tie Behavior Matrix

Different subsystems handle ties differently:

Subsystem Method Tie Behavior
UrnMatcher::find_all_matches Returns all matches Sorts by score descending only
CapMatrix::find_best_cap_set Within one registry Strict > replacement. On tie, keeps first encountered match
CapBlock::find_best_cap_set Across registries Strict > across registries. On tie, keeps first registry in registration order

In practice this means: when two providers have equal specificity, the one registered first wins. This is deterministic but order-dependent.

Preferred Cap Hints

A preferred_cap hint overrides specificity-based ranking. When the caller specifies a preferred cap URN, the ranker selects it if it passes dispatch — regardless of whether another provider has higher specificity.

This is a user-level override, not a system-level mechanism. The dispatch predicate still must pass; preferred hints only affect selection among valid candidates.

References