russell@unturf.com
326badf6d8
Three things in one commit because they're tightly coupled (README
points at the diagrams; diagrams index in modules/index.md points
back at README; module pages embed the diagrams).
(1) README — label refresh:
- Quickstart label changed from STRICT/HYBRID/UNGROUNDED to the
four-rung ladder POINTER-LINKED → ANCHOR-WARRANTED →
EVIDENCE-WARRANTED → UNGROUNDED with -PARTIAL suffix on HYBRID.
- Verifier section spells out both layers (schema trichotomy +
display ladder), the seven hard checks of claim_lattice, and
the five anchor classes of warrant.
- Architecture tree updated: concepts/ package added, qa/
sub-modules expanded (warrant, evidence, parse_claims, dag),
verify.py described as quote/span/entity/paraphrase + claim_lattice.
- Concept overlay description updated for corpus-derived layer
(concept_relations table, link_reciprocity extractor, 1.6%
tax cite).
- Test count: 326+ → 641+.
(2) docs/diagrams/ — Graphviz dot sources:
- aborist-modules.dot — top-level package graph (substrate /
storage / sources / retrieval / qa / mesh / cli)
- query-pipeline.dot — question → cache → retrieval → LLM →
verify → render → cache write, with phase budgets
- ingest-pipeline.dot — source doc → canonicalize → chunk →
Merkle → upsert (+ optional distill)
- verifier-ladder.dot — (audit_mode, violations) → display rung
decision tree
Existing mesh-*.dot kept as-is. Makefile `make docs` target
extended to also emit .svg alongside the existing .png so the
diagrams render in markdown viewers.
(3) docs/modules/ — per-module reference pages:
- index.md (links to every diagram + every module page)
- merkle.md, document.md, store.md, ingest.md, evict.md,
sources.md, search.md, concepts.md, qa.md, distill.md,
wikitext.md
Each page is a one-screenful concise reference: what the
module is for, public API, key invariants, embedded diagrams
where useful, link to source. Mesh stays at the existing
docs/mesh.md + docs/mesh-deploy.md (already comprehensive).
Tests: 641 passed (no code change).
49 lines
2.5 KiB
Text
49 lines
2.5 KiB
Text
// Verifier label ladder: how (audit_mode, violations) → display rung.
|
|
//
|
|
// Schema column `audit_mode` keeps the v9.8 trichotomy
|
|
// (STRICT / HYBRID / UNGROUNDED). The display ladder is a renderer-
|
|
// only transformation that names what's actually proved at each rung.
|
|
//
|
|
// Render: dot -Tsvg verifier-ladder.dot -o verifier-ladder.svg
|
|
|
|
digraph verifier_ladder {
|
|
rankdir=TB
|
|
node [shape=box, style="rounded,filled", fontname="Helvetica", fontsize=10]
|
|
edge [fontname="Helvetica", fontsize=9]
|
|
bgcolor="white"
|
|
|
|
// Inputs
|
|
inputs [label="VERIFIER OUTPUT\naudit_mode ∈ {STRICT, HYBRID, UNGROUNDED}\nviolations: list[dict]", fillcolor="#fff7e6", shape=note]
|
|
|
|
// Decision tree
|
|
is_ungrounded [label="audit_mode == UNGROUNDED?", fillcolor="#dddddd", shape=diamond]
|
|
has_warrant_miss [label="WARRANT_MISSING or\nTITLE_MISMATCH in violations?", fillcolor="#dddddd", shape=diamond]
|
|
has_soft_demote [label="any soft-demote violation?\n(LAZY_ANCHOR_DEMOTED,\nPOINTER_OVERFLOW_TRIMMED,\nTOO_MANY_CLAIMS, …)", fillcolor="#dddddd", shape=diamond]
|
|
is_hybrid [label="audit_mode == HYBRID?", fillcolor="#dddddd", shape=diamond]
|
|
|
|
// Rungs (top to bottom = strongest to weakest)
|
|
evidence_warranted [label="EVIDENCE-WARRANTED\npointer verified +\nwarrant ran & passed +\nNO soft demotes", fillcolor="#28a745", fontcolor="white"]
|
|
anchor_warranted [label="ANCHOR-WARRANTED\npointer-linked +\nwarrant passed where it ran;\nsoft demotes present", fillcolor="#7cc66e"]
|
|
pointer_linked [label="POINTER-LINKED\npointer/source/chunk verified;\nwarrant didn't apply OR failed\nfor at least one claim", fillcolor="#ffc107"]
|
|
ungrounded [label="UNGROUNDED\nno verified pairs\nat all", fillcolor="#dc3545", fontcolor="white"]
|
|
|
|
// Suffix annotation
|
|
partial [label="HYBRID → add `-PARTIAL` suffix\non whichever rung applies", fillcolor="#fff0e0", shape=note]
|
|
|
|
// Decision flow
|
|
inputs -> is_ungrounded
|
|
is_ungrounded -> ungrounded [label="yes"]
|
|
is_ungrounded -> has_warrant_miss [label="no"]
|
|
has_warrant_miss -> pointer_linked [label="yes"]
|
|
has_warrant_miss -> has_soft_demote [label="no"]
|
|
has_soft_demote -> anchor_warranted [label="yes"]
|
|
has_soft_demote -> evidence_warranted [label="no"]
|
|
|
|
// HYBRID adds suffix to all 3 non-UNGROUNDED rungs
|
|
evidence_warranted -> is_hybrid [style=dotted]
|
|
anchor_warranted -> is_hybrid [style=dotted]
|
|
pointer_linked -> is_hybrid [style=dotted]
|
|
is_hybrid -> partial [label="yes" style=dotted]
|
|
|
|
{rank=same; evidence_warranted; anchor_warranted; pointer_linked; ungrounded}
|
|
}
|