Refactor from per-session sqlite files to one shared shard at
~/.arborist/sessions.db. Three things that didn't work before now do:
1. Queries are first-class members of the tree.
nodes_fts (FTS5 over question + answer_text + cited_titles) lets
/find <query> walk every prior turn across every session. Cached
answers and threads become findable, surface in the REPL as
`[<bates>] <audit> <question>` lines.
2. Forking from history works the same as forking from a sibling.
parent_bates can cross sids. After /find returns a hit from
last week's session, /cd <bates> + ask = your next question
lands as a child under that historical turn. The cross-session
parent's subtree_hash ripples up its session_root.
3. One global audit chain instead of per-file.
audit_events.event_hash = sha256(prev || canonical body), one
chain over every state change in the shard. `make
session-chain-check` is now a single pass; tampering anywhere
in the operator's history breaks the chain.
Wire:
- arborist/qa/session.py — drop file-per-session SessionStore class;
Session becomes a viewport on SessionStore. cited_titles_json +
n_cited_sources materialized at insert time so FTS5 doesn't need
a join into providence_cache.
- arborist/cli.py — `session` subcommand swaps --gc for --find;
REPL adds /find. Ancestor-keyword extraction now reads
nodes.cited_titles_json directly (no qa.db roundtrip).
- Makefile — `make session-find Q="..." [LIMIT=N JSON=1]`; `make
session-gc` retired (no per-session files to GC).
- docs/sessions.md — rewritten for the single-shard shape.
- tests/test_session.py — 17 tests: create, add, fork (incl.
cross-session), find (FTS5 + by_cache_key), path_to_root crossing
sessions, audit chain (intact + tampered), cited-title extraction,
subtree_hash ripple across sessions.
Migration: pre-existing per-session dbs at ~/.arborist/sessions/*.db
become orphaned. None lost data — test sessions only. Operator can
rm -rf ~/.arborist/sessions/ (or rename to sessions-old/) at leisure.
126 session+providence+verify+inspect tests pass.
`arborist session` is an interactive multi-turn Q&A REPL where every
turn (or fork) mints one node in a per-session SQLite-backed tree.
Each node carries a stable Bates id (`<sid>-<6-digit>`) and folds into
a Merkle subtree-hash chain; the root node's subtree_hash is the
session_root.
Tree shape lets:
- **Forks** happen implicitly: `/cd <bates>` to a prior node, ask
again → sibling under that parent. Branch points (≥2 children)
surfaced by `/branches`.
- **Page-refresh caching** stay cheap: a client tracking
(bates → subtree_hash, body) only refetches subtrees whose hash
changed. Sibling subtrees that didn't change are byte-identical
→ cache-equivalent. Same property git pack-protocol and IPFS MFS
use.
- **Audit-chain verification** be per-session and independent: each
session db has its own session_audit_events with event_hash =
sha256(prev_hash || canonical_body). `make session-chain-check`
walks all sessions; 0 breaks each = intact.
Wire:
- arborist/qa/session.py — Session class, Bates minting, Merkle
recompute on O(depth) insert, audit chain, helpers (list, render,
resolve <bates|seq|label>).
- arborist/cli.py — `session` subcommand: REPL + --list / --tree
/ --chain-check / --gc / --json flags. Ancestor-titles → retrieval
keywords (parsed from cited-pointer lines in answer_text) flow down
the branch via policy["retrieval_keywords"].
- arborist/qa/providence_query.py — honor policy["retrieval_keywords"]:
augment FTS5 retrieval query without touching cache_key (mirrors
legacy --retrieval-keywords discipline, #000001).
- Makefile — `make session [SID=...]`, `make session-list`,
`make session-tree SID=...`, `make session-chain-check`,
`make session-gc SESSION_KEEP=N`.
- docs/sessions.md — schema, Merkle conventions (portability for
non-Python consumers), REPL command reference.
- tests/test_session.py — 15 tests: create, resume, add_node, fork
via cd, branches, root determinism, audit chain (intact + tampered),
resolve, list, render, sibling-invariance of subtree_hash.
Storage: ~/.arborist/sessions/<sid>.db (self-contained — no FK into
main store). Answers live in providence_cache keyed by cache_key;
session only carries conversation shape. Cache hits stay live across
sessions. Bounded growth via --gc.
Phase 1 scope: tree + Merkle + Bates + retrieval-keyword flow.
NOT in Phase 1: LLM-side conversation_history (threading prior Q&A
into the LLM prompt + conversation_hash). A bare-pronoun follow-up
("who created him?") gets the right retrieval today but the LLM may
still UNGROUNDED because it sees only the new question as user
message. Folding conversation_history into the prompt + cache_key's
conversation_hash dimension is the natural Phase 2.
197 tests pass.
