arborist/docs/naming-deferral.md

Why we don't rename claim_lattice to CTI / PROMETHEUS-Σ

Date: 2026-05-01 Decision: keep the codebase's internal terms (claim_lattice, claim_lattice_pointer, verify_claim_lattice, governance_policy_hash, etc.). The architectural labels (CTI, PROMETHEUS-Σ, Merkle-AGI-DAG, Reverse-RAG) live in docs/cti-architecture.md and commit messages where the cross-cutting story matters. Status: active. Re-evaluate when the rename triggers below fire.

---

1. The concrete proposal we considered

Fox's de-novo synthesis (2026-05-01) names the architectural layers cleanly:

PROMETHEUS-Σ      controller / policy / admissibility / one-shot
CTI               Clause Tree Intelligence — the runtime IR
Merkle-AGI-DAG    cryptographic commitment layer
Reverse-RAG       evidence direction (claim → span → root)
v9.8 Providence   admissibility ledger
Hermes            weak proposer

The internal codebase uses different names for the same layers:

architectural label	internal name(s)	location
PROMETHEUS-Σ	runner.ask, query.query, the policy-dict + dispatch logic	aborist/qa/runner.py, aborist/qa/query.py
CTI	claim_lattice (mode), claim_lattice_pointer (mode), verify_claim_lattice, parse_pointer_claims, EvidenceObject	aborist/qa/{verify,parse_claims,evidence}.py
Merkle-AGI-DAG	build_run_dag, run_dag_root, audit_events, MerkleTree, HashCombine	aborist/qa/dag.py, aborist/merkle.py, aborist/store.py
Reverse-RAG	the claim → evidence_id → chunk_root → source_root chain in verify_claim_lattice + render_claim_lattice	aborist/qa/verify.py, aborist/qa/evidence.py
v9.8 Providence	providence_cache table, the 8-dim cache_key, falsification_state	aborist/store.py, aborist/qa/keys.py
Hermes proposer	OpenAICompatibleClient, claim_lattice_system_prompt	aborist/qa/client.py, aborist/qa/runner.py

Both vocabularies refer to exactly the same code. The question is whether to rename internal symbols to match the external architectural labels.

The decision is no, defer. The reasoning is below.

2. What the rename would actually cost

Renaming the internal symbols isn't a search-and-replace. The cost lives in five places.

2.1 Cache invalidation

The string "claim_lattice" and "claim_lattice_pointer" are values of policy["answer_mode"] — and answer_mode is folded into governance_policy_hash which is one of the 8 dimensions of cache_key. Renaming the mode strings changes the hash, which stales every cached record under those modes on next lookup.

That's not catastrophic — caches are designed to handle invalidation — but it converts a stylistic rename into a substrate-wide cache flush. Every cached run since the modes existed becomes inaccessible-by-default. Mesh-broadcast records would diverge between renamed and pre-rename peers until they all migrated.

The rename has to be worth a mass cache invalidation. Aesthetic alignment with architectural docs isn't.

2.2 Test fixture footprint

The strings claim_lattice, claim_lattice_pointer, verify_claim_lattice, policy["answer_mode"] = "claim_lattice", etc. appear in:

• tests/test_claim_lattice.py (~75 references)
• tests/test_verify_json.py (~40 references)
• tests/test_qa_quality_live.py (~20 references — mode="claim_lattice_pointer" parameter)
• tests/test_query.py and tests/test_qa.py (additional refs)
• Many docstrings in aborist/qa/*.py

A consistent rename touches ~150+ references across the test suite + docstrings. None of it is hard; all of it is churn. Reviewing the diff to confirm "every rename is correct" is the actual cost.

2.3 Schema CHECK constraints

The providence_cache.verifier_method column has a SQL CHECK constraint:

verifier_method IN ('quote','span','entity','paraphrase','claim_lattice','none')

If we rename claim_lattice to cti, every existing cached record violates the new CHECK. Migration script + downtime + audit-chain integrity check. Real engineering work, not a refactor.

2.4 External commit history + doc archeology

Today's git log --oneline includes commit messages that read clean:

qa: drop manual-quote rule from pointer verifier; port G0 policy to runner
qa: bare-name guard, lazy-anchor demote, game tie-in noisy markers
qa: JSON mode uses pointer IDs (E1, E2, …) — close hallucination loop
qa: self-reference thought chains — STRICT-as-fact substrate

A rename produces a different parallel set of commit messages mid-history:

qa: rename claim_lattice → cti everywhere
qa: rename claim_lattice_pointer → cti_pointer everywhere
... [N follow-up commits fixing references the first pass missed]

The blame view becomes messier; git log -S claim_lattice_pointer returns nothing useful past the rename point; future agents reading commit messages see a disconnect between yesterday's commits and today's symbol names.

2.5 Mesh / broadcast compatibility

Records exchanged across the mesh carry their full 8-dim cache_key + answer_mode. A peer running a renamed build sees answer_mode="cti_pointer" from itself but answer_mode="claim_lattice_pointer" from peers running pre-rename. Either:

• the rename is rolled out atomically across all mesh peers (real coordination cost), or
• both names are accepted in parallel for a transition window (which means we maintain BOTH vocabularies for as long as the transition takes — the explicit cost we're trying to avoid).

3. What we get from the rename

Honest accounting:

• Symbol-level alignment with architectural docs. Reading verify_cti instead of verify_claim_lattice matches docs/cti-architecture.md directly.
• Onboarding clarity for new contributors. "What is claim_lattice?" requires a doc lookup; "what is cti?" matches the prose docs more obviously.
• Marketing / external-doc consistency. If the project ever publishes externally, "CTI" reads as a coherent architecture name; "claim lattice" reads as one implementation detail.

These are real wins. They're also small relative to the cost in §2.

4. The core argument: an internal vocabulary IS a feature

Every codebase that survives long enough develops its own internal terminology that doesn't match the architectural prose. Linux kernel "vmas" for "virtual memory areas." Postgres "tuples" for "rows." Git "blobs" for "file contents." That terminology survives because:

1. It's what the maintainers mutter about while debugging at 3am. Naming continuity matters when you're scanning for the symbol that changed three commits ago.
2. It carries history. Code symbols are historical artifacts as much as design decisions. Renaming them is an act of erasure that disconnects future-you from past-you's reasoning.
3. The architectural label is the right shape for prose; the internal label is the right shape for grep. They're different ergonomics with different audiences.

The codebase has its own vocabulary. The architectural doc has its own vocabulary. Both are correct in their domain. The mapping doc (docs/cti-architecture.md) is the bridge — read it once, then read code in code's vocabulary and prose in prose's vocabulary.

5. Triggers that would change this decision

We rename when:

1. The cost ratio inverts. If the codebase grows substantially and onboarding cost (people stuck on "what is claim_lattice?") exceeds the rename's cache-flush + test-churn cost, do the rename.
2. A SCHEMA / cache invalidation is happening anyway. A schema_version or chunking_version bump already stales all cached records — adding the rename to that migration is free incremental cost.
3. An external publication forces the architectural names. If a paper / blog / disclosure is published using "CTI" terminology and the codebase needs to match for credibility, do the rename.
4. A PROMETHEUS-Σ refactor extracts an explicit controller module. If someone needs to write a prometheus.py that holds the policy/admissibility/one-shot dispatch logic, the rest of the renames could ride along in one consolidated commit.

None of those are the case today. So we hold.

6. What we DO commit to

Independent of the rename decision:

• docs/cti-architecture.md — the mapping doc, kept current as the architecture evolves.
• Commit messages use both vocabularies when relevant. "qa: pointer mode hardening (CTI runtime IR)" is fine; "qa: claim_lattice tweak" is fine; mixing them when the cross-cutting story matters is fine.
• Docstrings reference the architectural labels where the layer-cake context matters. verify_claim_lattice's docstring should mention "the deterministic verifier in the CTI layer" so a reader following the architectural label can find the symbol.
• CLAUDE.md authority. When the architectural labels and the internal labels disagree, CLAUDE.md and the docs in docs/ are authoritative for the layer story; the symbol names are authoritative for the implementation. Neither is wrong.

7. Why this matters for fox's framing

Fox's de-novo synthesis is correct: CTI / PROMETHEUS-Σ / Merkle-AGI-DAG / Reverse-RAG / v9.8 / Hermes is the right architectural decomposition. Calling that out clearly in docs/cti-architecture.md is the right move.

But the architectural decomposition is a layered reading of code that already exists. The code already does CTI; the code already does PROMETHEUS-Σ; the code already does Reverse-RAG. Renaming the symbols doesn't make the architecture more real — it just changes which words name the same machinery.

The decision to defer is the decision to spend our limited rename-budget when it actually buys something. Today the buy is small and the cost is real. So we name the architecture in docs, and let the code keep its history-rich internal vocabulary.

If the cost ratio inverts, we revisit. The mapping table in §1 of this doc is the deferred rename plan, ready to execute when one of the §5 triggers fires.