engineering/arborist
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: pagers — rename 'not grounded' → 'ungrounded' (agreed label set: grounded / partly grounded / ungrounded)

Browse source 
'not grounded' was a drift from the agreed three-label vocabulary. Single-word labels are cleaner in tables, diagrams, and prose.
This commit is contained in:
russell@unturf.com 2026-05-14 12:56:13 -04:00
parent 42ed5c61a7
commit b711215f11
No known key found for this signature in database
8 changed files with 45 additions and 45 deletions
Download patch file Download diff file Expand all files Collapse all files

4
docs/_source/arborist-one-pager.rst
View file

@ -14,8 +14,8 @@ model embroidered it. **arborist closes that gap.** Every answer is
verified against its source *after* the language model finishes, by a verified against its source *after* the language model finishes, by a
mechanical checker — not by another AI grading the first one. The mechanical checker — not by another AI grading the first one. The
checker labels each answer **grounded** (every claim was found in the checker labels each answer **grounded** (every claim was found in the
source), **partly grounded** (some claims, not all), or **not source), **partly grounded** (some claims, not all), or
grounded**. The label travels with the answer and is stored in a **ungrounded**. The label travels with the answer and is stored in a
tamper-evident chain back to the source bytes. tamper-evident chain back to the source bytes.
**Fabricated citations become impossible.** When the model answers, it **Fabricated citations become impossible.** When the model answers, it

2
docs/_source/arborist-two-pager.rst
View file

@ -69,7 +69,7 @@ After generation, the verifier runs. Four mechanical strategies
(exact-quote match, line-span match, named-entity proximity, (exact-quote match, line-span match, named-entity proximity,
paraphrase coverage) try in sequence to confirm each claim against paraphrase coverage) try in sequence to confirm each claim against
the cited chunks. The output is a single label per answer: **grounded** the cited chunks. The output is a single label per answer: **grounded**
(every claim verifies), **partly grounded**, or **not grounded**. (every claim verifies), **partly grounded**, or **ungrounded**.
There is no "high confidence" middle ground — confidence labels are There is no "high confidence" middle ground — confidence labels are
soft signals in disguise. The verifier names what it can prove and soft signals in disguise. The verifier names what it can prove and
what it cannot. what it cannot.

2
docs/diagrams/pager-arch-stack.dot
View file

@ -12,7 +12,7 @@ digraph arch_stack {
surface [label="Ingested documents\n(Wikipedia · HTML · TeX · git · claim-packs)\nchunked → hashed → full-text-indexed", fillcolor="#e9f3ff"] surface [label="Ingested documents\n(Wikipedia · HTML · TeX · git · claim-packs)\nchunked → hashed → full-text-indexed", fillcolor="#e9f3ff"]
core [label="Derived layers\n(summaries, indices, distillations)\nhash-bound back to source chunks", fillcolor="#dff5e7"] core [label="Derived layers\n(summaries, indices, distillations)\nhash-bound back to source chunks", fillcolor="#dff5e7"]
cache [label="Answer cache\nverified Q&A · grounded / partly / not grounded\ncryptographic chain back to source bytes", fillcolor="#fff3d6"] cache [label="Answer cache\nverified Q&A · grounded / partly grounded / ungrounded\ncryptographic chain back to source bytes", fillcolor="#fff3d6"]
audit [label="Audit chain\nevery write appends a hash-linked row;\na single tampered record breaks the chain", fillcolor="#fde7e9", shape=note] audit [label="Audit chain\nevery write appends a hash-linked row;\na single tampered record breaks the chain", fillcolor="#fde7e9", shape=note]

BIN
docs/diagrams/pager-arch-stack.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 38 KiB

After

Width:  |  Height:  |  Size: 40 KiB

Before After
Before After

68
docs/diagrams/pager-arch-stack.svg
View file

@ -4,77 +4,77 @@
<!-- Generated by graphviz version 2.43.0 (0) <!-- Generated by graphviz version 2.43.0 (0)
--> -->
<!-- Title: arch_stack Pages: 1 --> <!-- Title: arch_stack Pages: 1 -->
<svg width="434pt" height="268pt" <svg width="480pt" height="268pt"
viewBox="0.00 0.00 433.50 268.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> viewBox="0.00 0.00 480.00 268.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 264)"> <g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 264)">
<title>arch_stack</title> <title>arch_stack</title>
<polygon fill="white" stroke="transparent" points="-4,4 -4,-264 429.5,-264 429.5,4 -4,4"/> <polygon fill="white" stroke="transparent" points="-4,4 -4,-264 476,-264 476,4 -4,4"/>
<!-- surface --> <!-- surface -->
<g id="node1" class="node"> <g id="node1" class="node">
<title>surface</title> <title>surface</title>
<path fill="#e9f3ff" stroke="black" d="M380.5,-44C380.5,-44 153.5,-44 153.5,-44 147.5,-44 141.5,-38 141.5,-32 141.5,-32 141.5,-12 141.5,-12 141.5,-6 147.5,0 153.5,0 153.5,0 380.5,0 380.5,0 386.5,0 392.5,-6 392.5,-12 392.5,-12 392.5,-32 392.5,-32 392.5,-38 386.5,-44 380.5,-44"/> <path fill="#e9f3ff" stroke="black" d="M427,-44C427,-44 200,-44 200,-44 194,-44 188,-38 188,-32 188,-32 188,-12 188,-12 188,-6 194,0 200,0 200,0 427,0 427,0 433,0 439,-6 439,-12 439,-12 439,-32 439,-32 439,-38 433,-44 427,-44"/>
<text text-anchor="middle" x="267" y="-31.2" font-family="Helvetica,sans-Serif" font-size="11.00">Ingested documents</text> <text text-anchor="middle" x="313.5" y="-31.2" font-family="Helvetica,sans-Serif" font-size="11.00">Ingested documents</text>
<text text-anchor="middle" x="267" y="-19.2" font-family="Helvetica,sans-Serif" font-size="11.00">(Wikipedia · HTML · TeX · git · claim&#45;packs)</text> <text text-anchor="middle" x="313.5" y="-19.2" font-family="Helvetica,sans-Serif" font-size="11.00">(Wikipedia · HTML · TeX · git · claim&#45;packs)</text>
<text text-anchor="middle" x="267" y="-7.2" font-family="Helvetica,sans-Serif" font-size="11.00">chunked → hashed → full&#45;text&#45;indexed</text> <text text-anchor="middle" x="313.5" y="-7.2" font-family="Helvetica,sans-Serif" font-size="11.00">chunked → hashed → full&#45;text&#45;indexed</text>
</g> </g>
<!-- core --> <!-- core -->
<g id="node2" class="node"> <g id="node2" class="node">
<title>core</title> <title>core</title>
<path fill="#dff5e7" stroke="black" d="M295.5,-116C295.5,-116 112.5,-116 112.5,-116 106.5,-116 100.5,-110 100.5,-104 100.5,-104 100.5,-84 100.5,-84 100.5,-78 106.5,-72 112.5,-72 112.5,-72 295.5,-72 295.5,-72 301.5,-72 307.5,-78 307.5,-84 307.5,-84 307.5,-104 307.5,-104 307.5,-110 301.5,-116 295.5,-116"/> <path fill="#dff5e7" stroke="black" d="M342,-116C342,-116 159,-116 159,-116 153,-116 147,-110 147,-104 147,-104 147,-84 147,-84 147,-78 153,-72 159,-72 159,-72 342,-72 342,-72 348,-72 354,-78 354,-84 354,-84 354,-104 354,-104 354,-110 348,-116 342,-116"/>
<text text-anchor="middle" x="204" y="-103.2" font-family="Helvetica,sans-Serif" font-size="11.00">Derived layers</text> <text text-anchor="middle" x="250.5" y="-103.2" font-family="Helvetica,sans-Serif" font-size="11.00">Derived layers</text>
<text text-anchor="middle" x="204" y="-91.2" font-family="Helvetica,sans-Serif" font-size="11.00">(summaries, indices, distillations)</text> <text text-anchor="middle" x="250.5" y="-91.2" font-family="Helvetica,sans-Serif" font-size="11.00">(summaries, indices, distillations)</text>
<text text-anchor="middle" x="204" y="-79.2" font-family="Helvetica,sans-Serif" font-size="11.00">hash&#45;bound back to source chunks</text> <text text-anchor="middle" x="250.5" y="-79.2" font-family="Helvetica,sans-Serif" font-size="11.00">hash&#45;bound back to source chunks</text>
</g> </g>
<!-- surface&#45;&gt;core --> <!-- surface&#45;&gt;core -->
<g id="edge1" class="edge"> <g id="edge1" class="edge">
<title>surface&#45;&gt;core</title> <title>surface&#45;&gt;core</title>
<path fill="none" stroke="black" d="M248.1,-44C242.47,-50.25 236.2,-57.22 230.2,-63.89"/> <path fill="none" stroke="black" d="M294.6,-44C288.97,-50.25 282.7,-57.22 276.7,-63.89"/>
<polygon fill="black" stroke="black" points="227.41,-61.75 223.32,-71.53 232.62,-66.44 227.41,-61.75"/> <polygon fill="black" stroke="black" points="273.91,-61.75 269.82,-71.53 279.12,-66.44 273.91,-61.75"/>
<text text-anchor="middle" x="252" y="-55.8" font-family="Helvetica,sans-Serif" font-size="9.00">distill</text> <text text-anchor="middle" x="298.5" y="-55.8" font-family="Helvetica,sans-Serif" font-size="9.00">distill</text>
</g> </g>
<!-- audit --> <!-- audit -->
<g id="node4" class="node"> <g id="node4" class="node">
<title>audit</title> <title>audit</title>
<polygon fill="#fde7e9" stroke="black" points="419.5,-260 174.5,-260 174.5,-216 425.5,-216 425.5,-254 419.5,-260"/> <polygon fill="#fde7e9" stroke="black" points="466,-260 221,-260 221,-216 472,-216 472,-254 466,-260"/>
<polyline fill="none" stroke="black" points="419.5,-260 419.5,-254 "/> <polyline fill="none" stroke="black" points="466,-260 466,-254 "/>
<polyline fill="none" stroke="black" points="425.5,-254 419.5,-254 "/> <polyline fill="none" stroke="black" points="472,-254 466,-254 "/>
<text text-anchor="middle" x="300" y="-247.2" font-family="Helvetica,sans-Serif" font-size="11.00">Audit chain</text> <text text-anchor="middle" x="346.5" y="-247.2" font-family="Helvetica,sans-Serif" font-size="11.00">Audit chain</text>
<text text-anchor="middle" x="300" y="-235.2" font-family="Helvetica,sans-Serif" font-size="11.00">every write appends a hash&#45;linked row;</text> <text text-anchor="middle" x="346.5" y="-235.2" font-family="Helvetica,sans-Serif" font-size="11.00">every write appends a hash&#45;linked row;</text>
<text text-anchor="middle" x="300" y="-223.2" font-family="Helvetica,sans-Serif" font-size="11.00">a single tampered record breaks the chain</text> <text text-anchor="middle" x="346.5" y="-223.2" font-family="Helvetica,sans-Serif" font-size="11.00">a single tampered record breaks the chain</text>
</g> </g>
<!-- surface&#45;&gt;audit --> <!-- surface&#45;&gt;audit -->
<g id="edge5" class="edge"> <g id="edge5" class="edge">
<title>surface&#45;&gt;audit</title> <title>surface&#45;&gt;audit</title>
<path fill="none" stroke="#888888" stroke-dasharray="5,2" d="M294.75,-44.09C302.85,-51.88 310.68,-61.42 315,-72 320.38,-85.18 319.5,-160.34 311.42,-206.13"/> <path fill="none" stroke="#888888" stroke-dasharray="5,2" d="M341.25,-44.09C349.35,-51.88 357.18,-61.42 361.5,-72 366.88,-85.18 366,-160.34 357.92,-206.13"/>
<polygon fill="#888888" stroke="#888888" points="307.98,-205.49 309.46,-215.98 314.84,-206.85 307.98,-205.49"/> <polygon fill="#888888" stroke="#888888" points="354.48,-205.49 355.96,-215.98 361.34,-206.85 354.48,-205.49"/>
</g> </g>
<!-- cache --> <!-- cache -->
<g id="node3" class="node"> <g id="node3" class="node">
<title>cache</title> <title>cache</title>
<path fill="#fff3d6" stroke="black" d="M266,-188C266,-188 12,-188 12,-188 6,-188 0,-182 0,-176 0,-176 0,-156 0,-156 0,-150 6,-144 12,-144 12,-144 266,-144 266,-144 272,-144 278,-150 278,-156 278,-156 278,-176 278,-176 278,-182 272,-188 266,-188"/> <path fill="#fff3d6" stroke="black" d="M313,-188C313,-188 12,-188 12,-188 6,-188 0,-182 0,-176 0,-176 0,-156 0,-156 0,-150 6,-144 12,-144 12,-144 313,-144 313,-144 319,-144 325,-150 325,-156 325,-156 325,-176 325,-176 325,-182 319,-188 313,-188"/>
<text text-anchor="middle" x="139" y="-175.2" font-family="Helvetica,sans-Serif" font-size="11.00">Answer cache</text> <text text-anchor="middle" x="162.5" y="-175.2" font-family="Helvetica,sans-Serif" font-size="11.00">Answer cache</text>
<text text-anchor="middle" x="139" y="-163.2" font-family="Helvetica,sans-Serif" font-size="11.00">verified Q&amp;A · grounded / partly / not grounded</text> <text text-anchor="middle" x="162.5" y="-163.2" font-family="Helvetica,sans-Serif" font-size="11.00">verified Q&amp;A · grounded / partly grounded / ungrounded</text>
<text text-anchor="middle" x="139" y="-151.2" font-family="Helvetica,sans-Serif" font-size="11.00">cryptographic chain back to source bytes</text> <text text-anchor="middle" x="162.5" y="-151.2" font-family="Helvetica,sans-Serif" font-size="11.00">cryptographic chain back to source bytes</text>
</g> </g>
<!-- core&#45;&gt;cache --> <!-- core&#45;&gt;cache -->
<g id="edge2" class="edge"> <g id="edge2" class="edge">
<title>core&#45;&gt;cache</title> <title>core&#45;&gt;cache</title>
<path fill="none" stroke="black" d="M184.5,-116C178.69,-122.25 172.22,-129.22 166.03,-135.89"/> <path fill="none" stroke="black" d="M224.1,-116C215.65,-122.72 206.16,-130.27 197.21,-137.39"/>
<polygon fill="black" stroke="black" points="163.18,-133.82 158.94,-143.53 168.31,-138.58 163.18,-133.82"/> <polygon fill="black" stroke="black" points="194.84,-134.81 189.19,-143.77 199.19,-140.28 194.84,-134.81"/>
<text text-anchor="middle" x="209" y="-127.8" font-family="Helvetica,sans-Serif" font-size="9.00">verify → cache</text> <text text-anchor="middle" x="245.5" y="-127.8" font-family="Helvetica,sans-Serif" font-size="9.00">verify → cache</text>
</g> </g>
<!-- core&#45;&gt;audit --> <!-- core&#45;&gt;audit -->
<g id="edge4" class="edge"> <g id="edge4" class="edge">
<title>core&#45;&gt;audit</title> <title>core&#45;&gt;audit</title>
<path fill="none" stroke="#888888" stroke-dasharray="5,2" d="M254.11,-116.13C265.91,-123.34 277.28,-132.55 285,-144 297.19,-162.08 300.75,-186.55 301.37,-205.85"/> <path fill="none" stroke="#888888" stroke-dasharray="5,2" d="M300.61,-116.13C312.41,-123.34 323.78,-132.55 331.5,-144 343.69,-162.08 347.25,-186.55 347.87,-205.85"/>
<polygon fill="#888888" stroke="#888888" points="297.87,-205.99 301.44,-215.97 304.87,-205.94 297.87,-205.99"/> <polygon fill="#888888" stroke="#888888" points="344.37,-205.99 347.94,-215.97 351.37,-205.94 344.37,-205.99"/>
</g> </g>
<!-- cache&#45;&gt;audit --> <!-- cache&#45;&gt;audit -->
<g id="edge3" class="edge"> <g id="edge3" class="edge">
<title>cache&#45;&gt;audit</title> <title>cache&#45;&gt;audit</title>
<path fill="none" stroke="#888888" stroke-dasharray="5,2" d="M187.31,-188C204.58,-195.51 224.22,-204.05 242.21,-211.88"/> <path fill="none" stroke="#888888" stroke-dasharray="5,2" d="M217.71,-188C237.81,-195.65 260.72,-204.37 281.59,-212.31"/>
<polygon fill="#888888" stroke="#888888" points="240.88,-215.11 251.45,-215.89 243.68,-208.69 240.88,-215.11"/> <polygon fill="#888888" stroke="#888888" points="280.42,-215.61 291.02,-215.89 282.91,-209.06 280.42,-215.61"/>
<text text-anchor="middle" x="255.5" y="-199.8" font-family="Helvetica,sans-Serif" font-size="9.00">every write</text> <text text-anchor="middle" x="292" y="-199.8" font-family="Helvetica,sans-Serif" font-size="9.00">every write</text>
</g> </g>
</g> </g>
</svg> </svg>

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 5.5 KiB

After

Width:  |  Height:  |  Size: 5.4 KiB

Before After
Before After

2
docs/diagrams/pager-verifier-flow.dot
View file

@ -18,7 +18,7 @@ digraph verifier_flow {
label_grounded [label="grounded\nevery claim verifies", fillcolor="#28a745", fontcolor="white"] label_grounded [label="grounded\nevery claim verifies", fillcolor="#28a745", fontcolor="white"]
label_partial [label="partly grounded\nsome verify, some don't", fillcolor="#ffc107"] label_partial [label="partly grounded\nsome verify, some don't", fillcolor="#ffc107"]
label_ungrounded [label="not grounded\nnone verify", fillcolor="#dc3545", fontcolor="white"] label_ungrounded [label="ungrounded\nnone verify", fillcolor="#dc3545", fontcolor="white"]
audit [label="Audit chain\n+ answer cache\n(reproducible, replayable)", fillcolor="#fde7e9", shape=note] audit [label="Audit chain\n+ answer cache\n(reproducible, replayable)", fillcolor="#fde7e9", shape=note]

BIN
docs/diagrams/pager-verifier-flow.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 62 KiB

After

Width:  |  Height:  |  Size: 62 KiB

Before After
Before After

12
docs/diagrams/pager-verifier-flow.svg
View file

@ -106,15 +106,15 @@
<!-- label_ungrounded --> <!-- label_ungrounded -->
<g id="node8" class="node"> <g id="node8" class="node">
<title>label_ungrounded</title> <title>label_ungrounded</title>
<path fill="#dc3545" stroke="black" d="M1140,-36C1140,-36 1067,-36 1067,-36 1061,-36 1055,-30 1055,-24 1055,-24 1055,-12 1055,-12 1055,-6 1061,0 1067,0 1067,0 1140,0 1140,0 1146,0 1152,-6 1152,-12 1152,-12 1152,-24 1152,-24 1152,-30 1146,-36 1140,-36"/> <path fill="#dc3545" stroke="black" d="M1136,-36C1136,-36 1071,-36 1071,-36 1065,-36 1059,-30 1059,-24 1059,-24 1059,-12 1059,-12 1059,-6 1065,0 1071,0 1071,0 1136,0 1136,0 1142,0 1148,-6 1148,-12 1148,-12 1148,-24 1148,-24 1148,-30 1142,-36 1136,-36"/>
<text text-anchor="middle" x="1103.5" y="-21.4" font-family="Helvetica,sans-Serif" font-size="12.00" fill="white">not grounded</text> <text text-anchor="middle" x="1103.5" y="-21.4" font-family="Helvetica,sans-Serif" font-size="12.00" fill="white">ungrounded</text>
<text text-anchor="middle" x="1103.5" y="-8.4" font-family="Helvetica,sans-Serif" font-size="12.00" fill="white">none verify</text> <text text-anchor="middle" x="1103.5" y="-8.4" font-family="Helvetica,sans-Serif" font-size="12.00" fill="white">none verify</text>
</g> </g>
<!-- verifier&#45;&gt;label_ungrounded --> <!-- verifier&#45;&gt;label_ungrounded -->
<g id="edge7" class="edge"> <g id="edge7" class="edge">
<title>verifier&#45;&gt;label_ungrounded</title> <title>verifier&#45;&gt;label_ungrounded</title>
<path fill="none" stroke="black" d="M991.9,-48.47C1009.75,-43.55 1028.18,-38.48 1044.74,-33.91"/> <path fill="none" stroke="black" d="M991.9,-48.47C1011.22,-43.15 1031.2,-37.64 1048.77,-32.8"/>
<polygon fill="black" stroke="black" points="1046.08,-37.17 1054.79,-31.14 1044.22,-30.43 1046.08,-37.17"/> <polygon fill="black" stroke="black" points="1050.11,-36.07 1058.82,-30.03 1048.25,-29.32 1050.11,-36.07"/>
</g> </g>
<!-- audit --> <!-- audit -->
<g id="node9" class="node"> <g id="node9" class="node">
@ -141,8 +141,8 @@
<!-- label_ungrounded&#45;&gt;audit --> <!-- label_ungrounded&#45;&gt;audit -->
<g id="edge10" class="edge"> <g id="edge10" class="edge">
<title>label_ungrounded&#45;&gt;audit</title> <title>label_ungrounded&#45;&gt;audit</title>
<path fill="none" stroke="#888888" stroke-dasharray="5,2" d="M1152.08,-31.49C1167.19,-35.77 1184.45,-40.66 1201.63,-45.53"/> <path fill="none" stroke="#888888" stroke-dasharray="5,2" d="M1148.2,-30.39C1164.29,-34.95 1183.19,-40.31 1201.97,-45.63"/>
<polygon fill="#888888" stroke="#888888" points="1201.15,-49.03 1211.73,-48.39 1203.06,-42.3 1201.15,-49.03"/> <polygon fill="#888888" stroke="#888888" points="1201.19,-49.05 1211.77,-48.41 1203.1,-42.31 1201.19,-49.05"/>
</g> </g>
</g> </g>
</svg> </svg>

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 9.6 KiB

After

Width:  |  Height:  |  Size: 9.6 KiB

Before After
Before After