arborist/docs/cti-architecture.md

CTI architecture — layer cake mapped onto today's codebase

Date: 2026-05-01 Audience: fox + future blackops shifts. Purpose: name the architectural layers fox's de novo synthesis identifies (PROMETHEUS-Σ / CTI / Merkle-AGI-DAG / Reverse-RAG / v9.8 / Hermes) against the modules that already exist, so future work has a stable vocabulary for which layer it touches.

This is a mapping doc, not a rename. The codebase keeps its internal terms (claim_lattice, claim_lattice_pointer, verify_claim_lattice); the architectural labels (CTI, PROMETHEUS-Σ, Merkle-AGI) live in docs and commit messages where the cross-cutting story matters.

---

1. The layer cake

┌────────────────────────────────────────────────────────────┐
│   PROMETHEUS-Σ                                             │
│   policy / admissibility / one-shot mode / cache reuse     │
└────────────────────────────────────────────────────────────┘
            │
            ▼
┌────────────────────────────────────────────────────────────┐
│   CTI — Clause Tree Intelligence                           │
│   claim nodes · evidence edges · statuses · falsifiers     │
│   (the runtime IR for reasoning, NOT a model output format)│
└────────────────────────────────────────────────────────────┘
            │
            ▼
┌────────────────────────────────────────────────────────────┐
│   Merkle-AGI-DAG                                           │
│   roots · run-DAG · path proofs · audit lineage            │
└────────────────────────────────────────────────────────────┘
            │
            ▼
┌────────────────────────────────────────────────────────────┐
│   Reverse-RAG (Merkle Providence)                          │
│   answer claim → evidence pointer → source span → root     │
└────────────────────────────────────────────────────────────┘
            │
            ▼
┌────────────────────────────────────────────────────────────┐
│   v9.8 Merkle Providence Runtime                           │
│   8-dim cache_key · falsification states · audit chain     │
└────────────────────────────────────────────────────────────┘
            │
            ▼
┌────────────────────────────────────────────────────────────┐
│   Hermes (and any other base model)                        │
│   weak proposer of natural-language pointer-line clauses   │
└────────────────────────────────────────────────────────────┘

The animating principle: the model proposes, the runtime structures, the verifier falsifies, the renderer quotes, the Merkle-DAG commits, PROMETHEUS-Σ admits. Authority moves DOWN the stack — from training-time priors into runtime artifacts.

2. Per-layer responsibility + module map

2.1 PROMETHEUS-Σ (controller)

Owns:

• which answer_mode is active
• whether cache read / write is allowed
• whether a record is admissible for reuse (the 8-dim match + state filter)
• whether a verifier policy changed (governance hash bump)
• whether a run is scoreable under one-shot rules
• which falsification triggers stale a record

Today's codebase:

• arborist/qa/runner.py:ask — orchestrates the full lookup → infer → verify → admissibility flow for the per-document path
• arborist/qa/query.py:query — same orchestration for the multi-source RAG path
• DEFAULT_POLICY (runner) and DEFAULT_QUERY_POLICY (query) — the policy dict
• arborist.qa.keys.governance_policy_hash — folds policy into the cache_key

Status: Implicit. The layer exists as code but is not named. The de-novo doc proposes naming it; the codebase doesn't need a prometheus.py module today — the dispatch logic in runner.py and query.py IS PROMETHEUS-Σ.

2.2 CTI — Clause Tree Intelligence (reasoning IR)

Owns:

• claim nodes with text + evidence edges
• per-claim statuses (PARSED, NO_EVIDENCE_POINTER, EVIDENCE_LINKED, EVIDENCE_LINKED_PARTIAL, UNKNOWN_EVIDENCE_ID, SOURCE_ROLE_BLOCKED, CITATION_MISMATCH, SCHEMA_INVALID, etc.)
• soft-signal sidecars: lazy-anchor smell, deflection, partial-grounding split, semantic-entailment (designed in docs/verifier-semantic-gap-design.md)
• the boundary between hard checks (lexical, deterministic) and soft checks (heuristic, demote-only)

Today's codebase:

• arborist/qa/parse_claims.py:parse_pointer_claims — the model's pointer-line output → ParsedClaim records (the CTI compile step)
• arborist/qa/evidence.py:EvidenceObject — typed evidence nodes with evidence_id (content-addressed) + pointer_id (prompt-facing)
• arborist/qa/evidence.py:render_claim_lattice — the renderer that interpolates source spans by offset
• arborist/qa/verify.py:verify_claim_lattice — the deterministic verifier (six hard checks + sidecar signals)
• arborist/qa/verify.py:verify_claim_lattice_json — same for the JSON variant
• arborist/qa/quantifier.py:classify_question_quantifier — pure 10-rung intensity classifier (#000008); feeds the preflight stage's classifier clause
• arborist/qa/model_profiles.py:cap_for_intensity — per-model claim-cap profiles (#000008); feeds the answer_contract clause's claim_cap_resolved
• arborist/qa/quantifier_reminder.py:broad_quantifier_reminder — broad-question reminder text generator (#000008); feeds the prompt_contract clause
• arborist/qa/metacognition.py:preflight_question — meta-cognition QuestionState detector suite (#000010): temporal, contradiction, false-premise-lite, out-of-corpus. Feeds the preflight stage's question_state clause.

Status: Real. CTI is what claim_lattice already is. The architectural insight from fox's synthesis — that this is an INTERNAL bytecode for reasoning, not a model output format — is the right reading: the model emits weak pointer lines; the runtime parses them into the CTI lattice; the lattice is what the verifier and renderer operate on. The pre-answer preflight contract (#000008 quantifier classifier + #000010 metacognition QuestionState) extends CTI upstream of retrieval — the runtime now classifies the question before generating an answer, so policy can refuse, cap, or reject without burning an LLM call.

2.3 Merkle-AGI-DAG (commitment)

Owns:

• per-run Merkle DAG; four shapes depending on path:
  • Quote mode (legacy) — 7 stages: question / retrieval / context / prompt / answer / verify / final_label.
  • Quote mode + preflight (post-#000009) — 8 stages: question / preflight / retrieval / context / prompt / answer / verify / final_label.
  • Pointer-mode CTI (legacy) — 9 stages: question / retrieval / evidence_map / prompt / raw_answer / parsed_claim_lattice / verify / render / final_label.
  • Pointer-mode CTI + preflight (post-#000009) — 10 stages: question / preflight / retrieval / evidence_map / prompt / raw_answer / parsed_claim_lattice / verify / render / final_label.
  • Reject-broad (post-#000009 §8) — 3 stages: question / preflight / final_label. Emitted by build_reject_run_dag() when the broad-quantifier guard early-returns before the LLM call. Audit replay can identify reject-path rows by stage count alone.
• run_dag_root (sha256 of the canonical DAG)
• run_dag_blob (the structured data for inspection)
• the audit-chain integrity (each audit_event_hash chains to the previous)
• inclusion proofs from chunk → document_root → source corpus

The preflight stage payload (#000009 + #000010). Single Merkle leaf, nested-clause structure for diff legibility:

• classifier — quantifier classifier output (#000008): intensity, matched_token, explicit_count, scope_bound_hint, is_broad, classifier_version, operational_shape.
• answer_contract — guard / cap / reject / metacog state taken on this run: guard_enabled, mode_gated, apply_caps_active, claim_cap_resolved, claim_cap_applied, reject_broad_active, metacognition_enabled, etc.
• prompt_contract — reminder_enabled, reminder_injected, reminder_template_id (broad-quantifier-bounded-v1 / broad-quantifier-unbounded-v1).
• evidence_contract — max_evidence_ids_exposed, one_claim_per_line.
• policy_refs — governance_policy_hash, model_profile_hash, answer_mode (reference-by-hash; raw policy state isn't double-committed).
• question_state — meta-cognition QuestionState (#000010): logical_statuses, question_shape, false_premise_hints, contradiction_pairs, temporal_sensitivity, scope_bound_hint, preflight_result.

PREFLIGHT_NODE_VERSION = "preflight-node-v1" is folded into the payload so legacy runs without the stage can be unambiguously labeled unavailable_legacy_run by audit tools.

Audit-replay payoff: two cache rows that share the same question + same model output + same verifier verdict but different preflight policy state (cap on/off, reminder on/off, reject path taken/not, metacog gates) now produce different run_dag_root values.

Today's codebase:

• arborist/qa/dag.py:build_run_dag — emits the 7/8/9/10-stage DAG; returns {root, nodes, blob}. preflight_hash parameter optional for backward-compat with legacy roots.
• arborist/qa/dag.py:build_reject_run_dag — emits the 3-stage reject-path DAG.
• arborist/qa/dag.py:preflight_node_hash + build_preflight_node_payload — canonical hash of the preflight clause set.
• arborist/merkle.py — the non-commutative HashCombine + odd-self-duplicate Merkle conventions (Python port of proxy.unturf.com/pkg/verified/merkle.go)
• arborist.store.append_audit — the only legal entry point for audit_events; computes event_hash = sha256(prev_event_hash || canonical(body))
• arborist/qa/keys.py:cache_key — the 8-dim composite hash that gates record reuse

Status: Real. The base 7/9-stage DAG was the F-track work earlier in the session; preflight binding landed 2026-05-03 (#000009 base, c36e85c) and was restructured to nested-clause shape 2026-05-04 (111dda6).

2.4 Reverse-RAG / Merkle Providence (evidence direction)

Owns:

• the claim → evidence_id → source_span → source_root → corpus reverse path
• per-claim provenance: every claim links forward to an evidence edge that maps to a chunk_root that proves into a document_root that proves into a source_root
• the renderer pulls source text by (chunk_root, offset_start, offset_end) — the model NEVER owns the quote text; the runtime interpolates it

Today's codebase:

• arborist/qa/evidence.py — EvidenceObject(source_root, document_uri, chunk_root, offset_start, offset_end, source_role, text_hash, span, evidence_id, pointer_id). The pointer_id (E1, E2, …) is what the model sees in the prompt; the evidence_id (content-addressed) is the cache/run-DAG handle. The runtime maps pointer_id → object → content-addressed evidence_id internally.
• arborist/qa/verify.py:verify_claim_lattice step 6 (citation-overlap check) — the claim → cited_span lexical-coverage gate
• arborist/qa/evidence.py:render_claim_lattice — interpolates source spans by offset, not Hermes text. Synthetic-elision is impossible by construction in pointer mode because the model never produces the quote string.

Status: Real. Pointer mode makes the reverse-RAG direction explicit; the model produces the LEFT side of the chain (claim) and points to the RIGHT side (evidence_id) — the runtime walks the rest.

2.5 v9.8 Merkle Providence Runtime (admissibility ledger)

Owns:

• the 8-dim cache_key: source_root | question_hash | model_profile_hash | conversation_hash | governance_policy_hash | schema_version | canonicalization_version | chunking_version
• falsification_state ∈ {live, failed, stale, quarantined} and the rules for transitions
• the providence_cache table + the audit_events chain
• the deliberate honesty boundary: NOT semantic truth, NOT hallucination elimination, NOT formal proof — just admissible provenance

Today's codebase:

• arborist/qa/keys.py — all eight dimensions hashed into cache_key
• arborist/store.py — schema, audit chain, transaction helpers
• arborist/qa/runner.py + arborist/qa/query.py — the cache-lookup-then-infer-then-write flow

Status: Real and honest. CLAUDE.md "Schema invariants (do not break)" enforces this boundary.

2.6 Hermes (proposer)

Owns:

• emitting weak pointer-line claims like Steve Jobs co-founded Apple. [E1]
• emitting JSON with evidence_ids referencing the same pointer ids
• nothing else — every other artifact (the lattice, the verdict, the rendered prose, the run DAG) comes from the runtime

Today's codebase:

• arborist/qa/client.py:OpenAICompatibleClient — HTTP client with retry on 502/503/504
• arborist/qa/client.py:StubClient — offline test stub
• claim_lattice_system_prompt + claim_lattice_grounding_reminder — the prompt fields that frame Hermes' role
• claim_lattice_json_system_prompt + claim_lattice_json_grounding_reminder — JSON variant

Status: Real. The negation-removal + atomic-claim work earlier in the session was about tightening the proposer's output shape so the runtime has cleaner input to compile.

3. The two information-flow directions

Two flows traverse the layers in opposite directions:

Inference flow (top-to-bottom-then-up):

  question → PROMETHEUS-Σ (admissibility check) → cache miss → 
  retrieval (Reverse-RAG path: titles → chunks → evidence map) →
  Hermes prompt (with pointer ids) → 
  Hermes response (pointer-line clauses) →
  CTI compile (parse_pointer_claims) →
  CTI verify (verify_claim_lattice) →
  CTI render (render_claim_lattice + spotlight excerpts) →
  Merkle-AGI commit (build_run_dag + audit_event) →
  v9.8 cache write (providence_cache row) →
  PROMETHEUS-Σ admit (audit_mode + falsification_state)

Audit flow (bottom-to-top, on demand):

  cache_key lookup → record + run_dag_blob →
  rebuild CTI lattice from run_dag stages →
  re-verify hard checks against current evidence map →
  if mismatch: PROMETHEUS-Σ falsifies → state flips

The audit flow is what makes Merkle-AGI O(log N + k) per challenged claim — you don't re-run Hermes; you replay the deterministic CTI verify path against the committed run-DAG.

4. Where each design doc lives

concern	doc
this layer-cake	docs/cti-architecture.md (you are here)
QA mode bench journey	docs/qa-modes-bench-2026-04-30.md
NLI semantic-gap sidecar	docs/verifier-semantic-gap-design.md
Self-reference (flat MVP)	docs/self-reference-design.md
Self-reference (deep, distillation-based)	docs/self-reference-design.md
Bench-maxing discipline	CLAUDE.md "Bench-maxing" section
Schema invariants	CLAUDE.md "Schema invariants (do not break)"
Convention list	CLAUDE.md "Conventions (do not silently change)"

5. What this layering DOESN'T claim

Per fox's de-novo synthesis (and CLAUDE.md's existing honesty boundary):

• Merkle-AGI does NOT make full-model verification free. It moves construction to O(N) once; targeted audit becomes O(log N + k). Full-model proof remains expensive.
• CTI is NOT semantic truth. The hard checks are lexical (substring, source-role, evidence-id resolution). Semantic checks (NLI, entailment, predicate compatibility) live in the soft-signal sidecar layer and never enter the proof path.
• v9.8 admissibility is NOT correctness. A STRICT record means "every claim grounded under the current verifier policy" — the policy is fallible (lazy-anchor false-positives, the Great Wall case in the bench journey doc). PROMETHEUS-Σ falsification is the corrective mechanism.
• Reverse-RAG does NOT prove sources are authoritative. It proves the answer pointed at the source the runtime committed to. Source quality is a separate problem (handled at retrieval time via _classify_source_role, noisy markers, title-purity rerank).

The substrate's honesty boundary stays where v9.8 placed it. The layer cake names the machinery; it does not extend the claims.

6. What's still open

These are the layer-cake-shaped work items still on the roadmap:

1. Verifier-policy-hash separation — landing in this commit pass. Fold answer_mode + parser_version + evidence_schema_version + manual_quote_policy + hard_checks_list into a 9th dimension that's separate from governance_policy_hash. Prevents cross-mode cache aliasing more cleanly.
2. Soft-signal taxonomy expansion — the NLI sidecar (docs/verifier-semantic-gap-design.md) is one. Predicate-compatibility, completeness, counterevidence, source-authority, scope-ambiguity are others. All demote-only, all out of the proof path. Implementations come one at a time as the bench surfaces motivating cases.
3. Self-reference distillation — STRICT claims become Cores via a new ProvidenceDistiller (see docs/self-reference-design.md). Lets new claims compose from existing facts, not just retrieve them.
4. PROMETHEUS-Σ explicit naming — deferred. The control logic exists; an extracted prometheus.py module is a refactor with no behavior change.

The architecture is real. The labels above name what's already there.