One-page map: rule/2 → schema → example → card
Use this table before changing rules code: find the head pattern, read the obligation schema (what must hold), open one specimen, then the policy card. Procedural “how” lives in the Owns column of each card.
rule/2 head (pattern) |
Obligation schema (what) | Specimen | Card |
|---|---|---|---|
target(Q,Arg):run|fetchonly|uninstall |
Resolve query → ebuild action (+ world side effects) | test01, test71 | Target |
Repo://E:install |
Eligible ∧ (keep | update-for-USE | resolve build deps) | test01, test67 | Install |
Repo://E:run |
Eligible ∧ (keep | update-for-USE | install + RDEPEND) | test01, test66 | Run |
Repo://E:download|fetchonly |
Fetch / fetch-only obligations | test71 | Target |
Repo://E:update|upgrade|downgrade |
Replace installed with selected under constraints | test73, test74 | Install |
Repo://E:depclean|uninstall|reinstall |
VDB-oriented maintenance actions | test75, test77 | Install |
grouped_package_dependency(no,…) |
Select one CN under version/slot/USE domain | test13, test55 | Dependency |
grouped_package_dependency(weak|strong,…) |
Soft / hard blocker semantics | test27, test26 | Blocker |
any_of_group(…) |
Admit arms → rank → commit one | test20, test60 | Choice |
exactly_one_of_group(…) |
Cardinality 1 among arms | test17 | Choice |
at_most_one_of_group(…) |
Cardinality ≤ 1 among arms | test23 | Choice |
all_of_group(…) |
Conjunction of members | test16 | Dependency |
use_conditional_group(±,…) |
Include body iff USE condition holds | test14 | USE |
required(…) / blocking(…) |
REQUIRED_USE literals | test40, test49 | REQUIRED_USE |
| Eligibility inside resolve | Not masked / keyword / license OK | test12 | Visibility |
| Slot ops on atoms | :N, :*, :=, sub-slot |
test41–test44 | Slots |
rule(assumed(X)) |
Domain assumption (pos/neg polarity) | test09, test12 | Assumptions |
assumed(rule(Lit)) |
Prover cycle-break (benign axis) | test03, test05 | Cycle |
Where “how” still lives
| Concern | Search / tactic modules (OK to be procedural) |
|---|---|
| Candidate enum + reprove | Rules/Resolving/candidate.pl, Rules/Resolving/heuristic.pl |
|| preference fold/sort |
Rules/Resolving/ranking.pl |
| USE eval + REQUIRED_USE | Rules/Resolving/use.pl |
| Dep model / ctx threading | Rules/Resolving/dependency.pl, query.pl |
| Learned domains | prover:learn/3, Rules/Resolving/cnselect.pl |
| Progressive relaxation | pipeline:prove_*_with_fallback |
Sync checklist
When you change policy:
- Update the relevant card invariants (one sentence if needed).
- Point at an overlay specimen (add a row here if it is curriculum-worthy).
- Keep polarity language aligned with
Source/Pipeline/Printer/Plan/assumption.pl. - Do not move procedural detail into cards — link to the module instead.