Joshua MoonandClaude Opus 5.5
0914c8e57d
Lane E concept ranking: evidence lanes (qualified definitions,
identifier occurrences, phrase, all-terms), identifier evidence tiers,
the 0.7 path prior, rerank tiers, snippet choice, and the
concept-audit evaluation manifest.
Conversions made while merging:
- search_prepared runs lane E's concept lanes with lane C's bound
path filter: concept_lanes, the occurrence lane (its raw
substr(f.path,...) check is now paths.sql_clause("f.path")),
lexical/file lanes and semantic_lane::append all take `paths`.
- PathPrior::for_query reads query.path.includes() for test/doc
component checks instead of a raw prefix string.
- Lane D's declarations::is_test_path is deleted; declarations and
reference_sites call path_class::is_test_path, so fixtures/, bare
`test` stems and generic *_test stems are production paths there
too (D's classifier test moves evaluation/fixtures/x.dm to the
negatives).
- The A::b concept lane calls D's declarations::qualified_hits
(QualifiedName::matches) instead of lane E's own container matcher.
- The file-ranking section moves from index-contract.md (then over
200 lines) to a new docs/ranking-contract.md; links follow.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
3.9 KiB
Trufflepig design
Trufflepig locates source spans for agents exploring complex repositories. Exact identifiers, lexical search, structural navigation, and verified follow-up reads are the core. Correct source identity takes priority over compact output.
The required scope is a Linux CLI operating locally on CPU, with Rust,
TypeScript/JavaScript, C#, PHP, Luau, and DreamMaker extraction. Tests, documentation,
configuration, and uncovered regions of source files remain searchable. Optional
semantic retrieval requires an explicit --sem request.
Contracts
CLI usage describes runnable commands and current operational limits.
- Search, handles, reads, and output
- Free-text lanes, evidence tiers, and path prior
- Definition, reference, and outline navigation
- Authoritative storage and publication
- Cache ownership, daemon lifecycle, and transport
- Historical navigation and local Git objects
- Diagnostic retention, sessions, and delivery evidence
- Language extraction and relationship evidence
- PHP extraction and XenForo metadata candidates
- Semantic inference gate and resource limits
- Evaluation and acceptance
- Retained licensing declarations for Josh
These documents specify required behavior. Executable tests and evaluation reports establish what the implementation actually verifies; a requirement alone is not evidence of support or measured performance.
Scope boundaries
Repository content is data, never executable instructions. Trufflepig does not edit source, answer questions in generated prose, upload source, or provide a complete compiler/type-checker model. Candidates remain visible and distinct from statically resolved relationships.
The live SQLite WAL database with FTS5 publishes source and graph facts together. A separate history database retains immutable Git facts and captured-tip traversal views; diagnostics retain bounded observations and explicit session baselines. A live result identifies its source revision and index generation. Historical changes identify commit, blob, path, and original-byte span on each side. These databases have independent transaction boundaries.
Tantivy, custom mmap stores, vector quantization, dimension truncation, ANN, HyDE, PageRank, LSP/SCIP, and MCP are outside the required scope. An opt-in cross-encoder rerank stage reorders the top 32 fused files; see the semantic contract for its bounds and fallback. All-ref traversal, historical ranking/embeddings, cochange/hotness, agent transcript adapters, and paired-agent trial orchestration remain outside this release. GPU support cannot block CPU use. No latency, memory, hit-count, or retrieval quality guarantee follows from the design. Agent harness integration lives in plugins/trufflepig-agent: a shared skill, a wrapper command that tags requests and writes per-call audit records, and a summarizer that flags struggling sessions.
Evidence and limits
Codebase-Memory reports approximately tenfold lower token use and 2.1-fold fewer calls, with exploration quality scores of 0.83 versus 0.92. Its author-graded, one-model exploration study motivates evaluation; it does not demonstrate equal patch success. Study and limitations
The FTS5 feasibility experiment establishes basic identifier expansion and transactional behavior only. Repository-scale performance and retrieval quality require the evaluation protocol.
Explicit multi-repository retrieval and owner routing follow the workspace contract. Each member retains its own index.