API Reference

Core Functions

`retrieve(options)`

Run the full retrieval pipeline. Returns a RetrievalBundle.

const bundle = await retrieve({
  store: CorpusStore,       // required
  roleId: string,           // required
  taskText: string,         // required
  overlay: RoleOverlay | null, // null = shared corpus only
  packetContextSummary?: string,
  lexicalOnly?: boolean,    // skip semantic search
  embeddingModel?: string,  // Ollama model (default: nomic-embed-text)
  ollamaUrl?: string,       // default: http://localhost:11434
});

`CorpusStore`

SQLite-backed document and chunk storage.

const store = new CorpusStore(":memory:"); // or file path
store.insertDocument(doc);
store.insertChunk(chunk);
store.searchFTS(query, limit);
store.insertEmbedding(chunkId, vector, model);
store.close();

`ingestFixtureCorpus(store, path)`

Load a JSON corpus file into a store. Returns { documents_ingested, chunks_ingested, errors }.

`ingestCorpusData(store, corpusData)`

Same as above but accepts parsed JSON directly.

`validateOverlay(data)`

Validate a role overlay JSON against the schema. Returns { valid, errors }.

`validateBundle(data)`

Validate a retrieval bundle JSON against the schema. Returns { valid, errors }.

Pipeline Functions

These are used internally by retrieve() but are exported for testing and custom pipelines.

Function	Purpose
`buildQuery(taskText, overlay, context?)`	Overlay-aware query expansion
`lexicalSearch(store, ftsQuery, limit?)`	BM25 via FTS5
`semanticSearch(store, queryText, limit?, model?, url?)`	Embedding similarity
`mergeCandidates(lexical, semantic)`	Union + deduplicate
`metadataFilter(candidates, overlay)`	Apply governance rules
`rerank(candidates, overlay)`	Weighted scoring + diversity
`assembleBundle(input)`	Produce final `RetrievalBundle`

Key Types

`RetrievalBundle`

The governed output of every retrieval operation.

Field	Type	Description
`version`	`"1.0"`	Schema version
`role_id`	`string`	Which role this was retrieved for
`query`	`QueryTrace`	Full audit trail of query construction
`summary`	`RetrievalSummary`	Aggregate stats
`selected`	`RetrievedChunk[]`	Top evidence with scores
`rejected`	`RejectedCandidate[]`	Why candidates were excluded
`provenance`	`ProvenanceSummary`	Trust and freshness posture
`warnings`	`RetrievalWarning[]`	Degradation signals
`diagnostics`	`RetrievalDiagnostics`	Performance stats

`RoleOverlay`

Declarative per-role retrieval configuration.

Field	Type	Description
`role_id`	`string`	Role identifier
`mission`	`string`	What this role retrieves for
`anti_goals`	`string[]`	What it must NOT drift into
`vocabulary`	`RoleVocabulary`	Boost/suppress terms
`source_policy`	`SourcePolicy`	Preferred/forbidden sources
`retrieval_policy`	`RetrievalPolicy`	Weights and limits
`synthesis_policy`	`SynthesisPolicy`	Output guidance
`eval_profile`	`EvalProfile`	Golden set for testing

`FallbackDecision`

State	Action	When
`healthy`	continue	Normal operation
`no_overlay`	continue	Shared corpus only
`no_strong_match`	warn	Bundle is empty or weak
`stale_dominant`	warn	Majority of evidence is outdated
`forbidden_hit`	continue	Forbidden sources removed
`conflicting`	warn	High-trust sources disagree