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
mechanical checker — not by another AI grading the first one. The
checker labels each answer **grounded** (every claim was found in the
source), **partly grounded** (some claims, not all), or **not
grounded**. The label travels with the answer and is stored in a
source), **partly grounded** (some claims, not all), or
**ungrounded**. The label travels with the answer and is stored in a
tamper-evident chain back to the source bytes.
**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,
paraphrase coverage) try in sequence to confirm each claim against
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
soft signals in disguise. The verifier names what it can prove and
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"]
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]

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)
-->
<!-- Title: arch_stack Pages: 1 -->
<svg width="434pt" 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">
<svg width="480pt" height="268pt"
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)">
<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 -->
<g id="node1" class="node">
<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"/>
<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="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="267" y="-7.2" font-family="Helvetica,sans-Serif" font-size="11.00">chunked → hashed → full&#45;text&#45;indexed</text>
<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="313.5" y="-31.2" font-family="Helvetica,sans-Serif" font-size="11.00">Ingested documents</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="313.5" y="-7.2" font-family="Helvetica,sans-Serif" font-size="11.00">chunked → hashed → full&#45;text&#45;indexed</text>
</g>
<!-- core -->
<g id="node2" class="node">
<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"/>
<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="204" 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>
<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="250.5" y="-103.2" font-family="Helvetica,sans-Serif" font-size="11.00">Derived layers</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="250.5" y="-79.2" font-family="Helvetica,sans-Serif" font-size="11.00">hash&#45;bound back to source chunks</text>
</g>
<!-- surface&#45;&gt;core -->
<g id="edge1" class="edge">
<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"/>
<polygon fill="black" stroke="black" points="227.41,-61.75 223.32,-71.53 232.62,-66.44 227.41,-61.75"/>
<text text-anchor="middle" x="252" y="-55.8" font-family="Helvetica,sans-Serif" font-size="9.00">distill</text>
<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="273.91,-61.75 269.82,-71.53 279.12,-66.44 273.91,-61.75"/>
<text text-anchor="middle" x="298.5" y="-55.8" font-family="Helvetica,sans-Serif" font-size="9.00">distill</text>
</g>
<!-- audit -->
<g id="node4" class="node">
<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"/>
<polyline fill="none" stroke="black" points="419.5,-260 419.5,-254 "/>
<polyline fill="none" stroke="black" points="425.5,-254 419.5,-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="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="300" y="-223.2" font-family="Helvetica,sans-Serif" font-size="11.00">a single tampered record breaks the chain</text>
<polygon fill="#fde7e9" stroke="black" points="466,-260 221,-260 221,-216 472,-216 472,-254 466,-260"/>
<polyline fill="none" stroke="black" points="466,-260 466,-254 "/>
<polyline fill="none" stroke="black" points="472,-254 466,-254 "/>
<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="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="346.5" y="-223.2" font-family="Helvetica,sans-Serif" font-size="11.00">a single tampered record breaks the chain</text>
</g>
<!-- surface&#45;&gt;audit -->
<g id="edge5" class="edge">
<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"/>
<polygon fill="#888888" stroke="#888888" points="307.98,-205.49 309.46,-215.98 314.84,-206.85 307.98,-205.49"/>
<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="354.48,-205.49 355.96,-215.98 361.34,-206.85 354.48,-205.49"/>
</g>
<!-- cache -->
<g id="node3" class="node">
<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"/>
<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="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="139" y="-151.2" font-family="Helvetica,sans-Serif" font-size="11.00">cryptographic chain back to source bytes</text>
<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="162.5" y="-175.2" font-family="Helvetica,sans-Serif" font-size="11.00">Answer cache</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="162.5" y="-151.2" font-family="Helvetica,sans-Serif" font-size="11.00">cryptographic chain back to source bytes</text>
</g>
<!-- core&#45;&gt;cache -->
<g id="edge2" class="edge">
<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"/>
<polygon fill="black" stroke="black" points="163.18,-133.82 158.94,-143.53 168.31,-138.58 163.18,-133.82"/>
<text text-anchor="middle" x="209" y="-127.8" font-family="Helvetica,sans-Serif" font-size="9.00">verify → cache</text>
<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="194.84,-134.81 189.19,-143.77 199.19,-140.28 194.84,-134.81"/>
<text text-anchor="middle" x="245.5" y="-127.8" font-family="Helvetica,sans-Serif" font-size="9.00">verify → cache</text>
</g>
<!-- core&#45;&gt;audit -->
<g id="edge4" class="edge">
<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"/>
<polygon fill="#888888" stroke="#888888" points="297.87,-205.99 301.44,-215.97 304.87,-205.94 297.87,-205.99"/>
<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="344.37,-205.99 347.94,-215.97 351.37,-205.94 344.37,-205.99"/>
</g>
<!-- cache&#45;&gt;audit -->
<g id="edge3" class="edge">
<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"/>
<polygon fill="#888888" stroke="#888888" points="240.88,-215.11 251.45,-215.89 243.68,-208.69 240.88,-215.11"/>
<text text-anchor="middle" x="255.5" y="-199.8" font-family="Helvetica,sans-Serif" font-size="9.00">every write</text>
<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="280.42,-215.61 291.02,-215.89 282.91,-209.06 280.42,-215.61"/>
<text text-anchor="middle" x="292" y="-199.8" font-family="Helvetica,sans-Serif" font-size="9.00">every write</text>
</g>
</g>
</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_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]

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 -->
<g id="node8" class="node">
<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"/>
<text text-anchor="middle" x="1103.5" y="-21.4" font-family="Helvetica,sans-Serif" font-size="12.00" fill="white">not grounded</text>
<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">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>
</g>
<!-- verifier&#45;&gt;label_ungrounded -->
<g id="edge7" class="edge">
<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"/>
<polygon fill="black" stroke="black" points="1046.08,-37.17 1054.79,-31.14 1044.22,-30.43 1046.08,-37.17"/>
<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="1050.11,-36.07 1058.82,-30.03 1048.25,-29.32 1050.11,-36.07"/>
</g>
<!-- audit -->
<g id="node9" class="node">
@ -141,8 +141,8 @@
<!-- label_ungrounded&#45;&gt;audit -->
<g id="edge10" class="edge">
<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"/>
<polygon fill="#888888" stroke="#888888" points="1201.15,-49.03 1211.73,-48.39 1203.06,-42.3 1201.15,-49.03"/>
<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.19,-49.05 1211.77,-48.41 1203.1,-42.31 1201.19,-49.05"/>
</g>
</g>
</svg>

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 9.6 KiB

After

Width:  |  Height:  |  Size: 9.6 KiB

Before After
Before After