Handbook

Knowledge index (caller vs adapter)

Recipe routers, lmeta flows, and harnesses should call abstract knowledge ops — not deck, slide, or file-format APIs. Format-specific logic lives in consumer adapters.

Updated 2026-07-26

Caller plane (LCDL)

Type	Role
`KnowledgeRecord`	Normalized item: `record_id`, `source_id`, `title`, `text`, `facets`, `asset_kind`
`KnowledgeHit`	Record + `score` + `excerpt`
`KnowledgeQuery`	`text`, `facets`, `asset_kinds`, trusted `scope`, `top_k`, optional `expanded_terms`
`KnowledgeIndex`	Protocol: `search`, `get`, `facet_counts`, `rank`
`QueryExpansion`	`raw_query`, `terms`, `expanded_terms`, `phrases` — synonym/word-form expansion
`RelevanceNode`	Hierarchical relevance tree node (`library` → `deck` → `topic` → `slide` → `chunk`)

Bridge to existing RAG: hits_to_evidence_pack(hits) → EvidencePack for answer_from_evidence.

Query expansion (caller plane)

Function	Role
`expand_query_terms(text, providers)`	Tokenize + word forms + `SynonymProvider` expansion
`fts_match_terms(expansion)`	OR-join terms for FTS MATCH expressions

Hierarchical relevance (caller plane)

Function	Role
`rollup_tree(children, label, level)`	Aggregate child scores into parent node
`prune_tree(root, min_score, max_children)`	Trim low-score branches
`flatten_leaves(root)`	Ordered chunk hits from tree leaves
`rank_hierarchical(tree, criteria)`	Deterministic tree prune/rank
`navigate(root, path)`	Drill-down by label segments
`node_to_dict(node)`	Serialize tree for traces/JSON

rank_hits criteria keys: boost_facets, min_score, max_children_per_level.

Adapter plane (consumer)

Adapters implement KnowledgeIndex for a concrete store:

KA decks — KaDeckFtsAdapter maps SQLite FTS chunk rows + deck metadata to KnowledgeRecord.
In-memory — InMemoryKnowledgeIndex for tests and fixtures.

Adapters may attach private fields in metadata; callers must not branch on them.

Ops (lmeta / hooks)

Hook	Purpose	LLM budget
`knowledge.search`	Text + facet filter	0
`knowledge.facet`	Facet landscape	0
`knowledge.get`	Single record	0
`knowledge.rank`	Deterministic re-rank	0
`knowledge.compare_pack`	Two-sided evidence pack	0
`knowledge.synthesize`	`answer_from_evidence` wrapper	1

Legacy ka.search_slides hooks remain aliases during migration.

Presentation formatters

Retrieval returns abstract hits; presentation is composed at the consumer edge.

Layer	Location	Role
LCDL `forge_lcdl.output`	forge-lcdl	Generic compose engine, built-in blocks, `register_layout` / `register_block_type`
Consumer output pack	e.g. KA `output/install.py`	Domain shapes (`presentation.comparison@1`), custom blocks, validators

See Structured output composition. Legacy per-handler markdown assembly is deprecated in favor of compose(shape_id, data).

Forge LCDL