russell@unturf.com
de07ad9392
Three Explore agents fanned out in parallel for a docs/ + diagrams/
+ code-comment audit against the shipped state of the three
preflight tickets. This commit lands all the alignment fixes.
Core docs updates:
CLAUDE.md
- dag.py module description: stage counts now read
"7/8 quote · 9/10 CTI · 3 reject" reflecting #000009 preflight
stage + reject-broad early-return shape.
docs/cti-architecture.md §2.2 + §2.3
- §2.3 Merkle-AGI-DAG section rewritten: documents all five DAG
shapes (legacy 7/9, post-#000009 8/10, reject-broad 3),
describes the preflight stage's 5 nested CTI clauses
(classifier / answer_contract / prompt_contract /
evidence_contract / policy_refs), pins
PREFLIGHT_NODE_VERSION = "preflight-node-v1", states the
audit-replay payoff.
- §2.2 CTI section: adds the four new modules
(quantifier, model_profiles, quantifier_reminder,
metacognition) as code anchors. Notes that pre-answer
preflight contract extends CTI upstream of retrieval.
docs/seven-point-program.md
- D3 status ½ → ¾ — pre-answer preflight contract landed via
#000008 + #000010. Code anchors + pinning tests updated.
- D4 status ½ → ¾ — preflight stage adds upstream control
commitment to the run-DAG. Code anchors include
build_reject_run_dag + preflight_node_hash.
- Status snapshot table: tickets column now references
#000008/#000009/#000010 against D1/D3/D4 directives.
- "Post-landing addendum (2026-05-03 / 2026-05-04)" subsection
summarises all three tickets + their commit shas + final
test count (993 passing, up from 734).
docs/modules.md
- Q&A pipeline table: added 4 new modules (quantifier.py,
model_profiles.py, quantifier_reminder.py, metacognition.py).
dag.py row updated to "7/8 quote · 9/10 CTI · 3 reject".
- dag.py subsection rewritten: documents all 5 DAG shapes,
describes the preflight payload's 5 clauses + question_state.
- 4 new module subsections (quantifier / model_profiles /
quantifier_reminder / metacognition) explaining each
module's purpose, signature, and how it feeds the run-DAG
preflight clause.
Diagram updates:
docs/diagrams/query-pipeline.dot + .svg
- New "PREFLIGHT (#000008 + #000010)" node inserted between
cache_check and concepts_lookup.
- New "REJECT-BROAD" node showing the 3-stage minimal DAG
escape path.
- render node label extended with the audit-line tail token
catalog.
docs/diagrams/aborist-modules.dot + .svg
- 4 new qa_* nodes in the retrieval & verifier cluster.
- 8 new edges: qa_query/qa_runner each call into all 4
preflight modules; qa_dag has dotted edges to qa_quantifier
+ qa_metacognition (preflight clause sources).
- qa_dag label updated to mention preflight_node_hash + 5 clauses.
docs/diagrams/verifier-ladder.dot + .svg
- Soft-demote violations list extended: BROAD_QUANTIFIER_RUNAWAY
/ CAP_APPLIED / SCOPE_UNBOUND, FORMAT_COLLAPSED, BARE_NAME_CLAIM.
- New "AUDIT-LINE TAILS" annotation node listing all 11 tail
tokens (#000008 broad-* + #000010 metacog + classic verifier).
- Dashed edges from each rung to tails note showing tails
compose onto labels.
Code-side stale-comment fixes (caught by 3rd Explore agent):
aborist/qa/keys.py:218
- "The four fields" → "The seven fields"; mention #000010 adds
six more for metacognition.
aborist/qa/query.py:2644
- 7-stage / 9-stage comment expanded to enumerate all four
base+preflight shapes plus the 3-stage reject path.
aborist/qa/runner.py:835
- same expansion as query.py for runner.ask() callsite.
mesh-*.dot, ingest-pipeline.dot, qa-modes-bench.md, bench-maxing.md,
bench-emergent-design.md, verifier-semantic-gap-design.md,
self-reference-design.md, concept-relations-design.md confirmed
orthogonal — no edits needed.
993 tests still passing (no behavior change). 7 files modified
across docs/ + 3 dot diagrams + 3 SVGs + 4 code-comment fixes.
76 lines
4.5 KiB
Text
76 lines
4.5 KiB
Text
// Query pipeline: how a question becomes a verified answer.
|
||
//
|
||
// Per-stage timing budget at the top of each box (Hermes ~6-8s
|
||
// dominates; everything else target sub-second per phase).
|
||
//
|
||
// Render: dot -Tsvg query-pipeline.dot -o query-pipeline.svg
|
||
|
||
digraph query_pipeline {
|
||
rankdir=TB
|
||
node [shape=box, style="rounded,filled", fontname="Helvetica", fontsize=10]
|
||
edge [fontname="Helvetica", fontsize=9]
|
||
bgcolor="white"
|
||
|
||
question [label="QUESTION\n\"what tech can reconstruct\nanother person's thoughts?\"", fillcolor="#fff7e6", shape=note]
|
||
|
||
// Cache lookup first (free hit if previously asked)
|
||
cache_check [label="cache lookup\nproperence_cache by 8-dim cache_key\n• equivalence_class fallback\n• ~0.3ms warm", fillcolor="#e6f0ff"]
|
||
cache_hit [label="CACHE HIT\nreplay answer + Merkle proof\n~100ms total", fillcolor="#d4edda", shape=note]
|
||
|
||
// Preflight (Tickets #000008 + #000010 — Merkle-bound via #000009)
|
||
preflight [label="PREFLIGHT (#000008 + #000010)\nclassifier (10-rung quantifier)\n+ metacognition QuestionState\n• temporal · contradiction\n• false-premise · out-of-corpus\n• broad-quantifier scope hint\n→ 5-clause CTI contract\n→ run-DAG `preflight` stage", fillcolor="#fff0e0"]
|
||
preflight_reject [label="REJECT-BROAD\n3-stage minimal DAG\nquestion → preflight → final_label\nno LLM call (~0ms)", fillcolor="#ffd4d4", shape=note]
|
||
|
||
// Retrieval
|
||
fts5 [label="FTS5 BM25 search\n• AND-mode first (strict)\n• OR-mode fallback (top-5 longest +\n synonym pool)\n• ~0.25s/shard", fillcolor="#ffe6f0"]
|
||
title_like [label="title-LIKE backup\n(skipped if >5 tokens)\n• ~0.5s/shard for short queries", fillcolor="#ffe6f0"]
|
||
phrase_route [label="phrase-pattern route\n4-token sliding-window match\n(closes allusion gap)", fillcolor="#ffe6f0"]
|
||
concepts_lookup [label="concepts/ overlay\n• synonym_expand(qtokens)\n• rivalry_excluded()\n• per-process cache, ~1ms warm", fillcolor="#ffe6f0"]
|
||
|
||
// Filter
|
||
filter [label="title-relevance filter\n4 accept paths:\n1. title-token overlap\n2. TF-IDF core match\n3. body density\n4. phrase match", fillcolor="#ffe6f0"]
|
||
rerank [label="rerank stack\n• body coverage (sqrt)\n• title token boost\n• source role boost\n• title purity", fillcolor="#ffe6f0"]
|
||
|
||
// Evidence map (claim_lattice modes)
|
||
evidence_map [label="evidence map\n(claim_lattice modes)\nEvidenceObject per chunk\nrun-stable evidence_id (sha256)\nprompt-facing pointer_id (E1, E2…)", fillcolor="#fff0e0"]
|
||
|
||
// Context assembly
|
||
context [label="context assembly\n• per-source cap\n• 60KB total budget\n• wikitext.to_base() prose-strip", fillcolor="#fff0e0"]
|
||
|
||
// LLM
|
||
llm [label="LLM call (Hermes-3 / vLLM)\n6–8s — DOMINANT cost\nclaim_lattice_pointer or\nclaim_lattice (JSON)", fillcolor="#ffd4d4"]
|
||
|
||
// Verification
|
||
verify [label="verify_claim_lattice\n7 hard checks:\n1. parser succeeded\n2. evidence_id resolves\n3. source_role allowed\n4. claim text non-empty\n5. citation coverage\n6. pointer count cap\n7. anchor-class warrant", fillcolor="#e7ffe7"]
|
||
warrant [label="warrant_check (5 anchor classes)\n• proper-noun (relation-gated)\n• date (year + month)\n• count (digit↔word)\n• entity-list\n• cause (why-shape)", fillcolor="#e7ffe7"]
|
||
|
||
// Render
|
||
render [label="render\n• spotlight excerpt (density rank)\n• [E5 | Title | chunk_prefix: \"...\"]\n• four-rung label ladder\n• audit-line tails:\n · false premise · contradictory\n · stale risk · out of corpus\n · frame ambiguous\n · broad cap N · broad rejected", fillcolor="#fff7e6"]
|
||
|
||
// Persistence
|
||
cache_write [label="providence_cache write\n• 8-dim cache_key\n• run_dag_root + run_dag_blob\n• audit_event chained\n• context_root committed", fillcolor="#e6f0ff"]
|
||
|
||
answer [label="ANSWER\nlabel: POINTER-LINKED-PARTIAL ·\nvia claim_lattice · 2/2 · 11.6s", fillcolor="#d4edda", shape=note]
|
||
|
||
// Edges
|
||
question -> cache_check
|
||
cache_check -> cache_hit [label="match"]
|
||
cache_check -> preflight [label="miss"]
|
||
preflight -> preflight_reject [label="reject-broad\n(opt-in)", style=dashed, color="#cc4444"]
|
||
preflight -> concepts_lookup [label="continue"]
|
||
concepts_lookup -> fts5
|
||
concepts_lookup -> title_like
|
||
concepts_lookup -> phrase_route
|
||
fts5 -> filter
|
||
title_like -> filter
|
||
phrase_route -> filter
|
||
filter -> rerank
|
||
rerank -> evidence_map
|
||
evidence_map -> context
|
||
context -> llm
|
||
llm -> verify
|
||
verify -> warrant
|
||
warrant -> render
|
||
render -> cache_write
|
||
cache_write -> answer
|
||
}
|