Primitives catalog
Primitives are the typed, zero-completion building blocks of the query machine. Assured operations freeze chains over them. This page catalogs engine ops and labels what an agent can call vs what is internal composition.
Parent: Retrieval. Shipped HTTP: API reference.
Rules that apply to every primitive
- No LLM completion on the hot path (semantic channels may embed the query).
- No write side effects — reads never enqueue work.
- Grain is declared where an envelope is returned.
- Temporal params
valid_at/believed_atcompose where validity exists. - Query-engine results hydrate through Postgres except pure mount reads.
Prefer these public surfaces first
| Surface | Call |
|---|---|
| Assured ops | POST /operations/resolve_entity, testimony_context, fact_context, answer_context |
| Open SQL | POST /query/sql (+ explain, space discovery, saved queries) |
| Direct primitives (subset) | See API reference: resolve / lookup / search claims & chunks / hydrate / transcript endpoints as composed |
Do not invent /fuse, /rerank, /scan, etc. unless the API reference lists them.
Catalog (engine ops)
Legend: Public = stable agent call path today · Internal = used inside operations / engine · Design = specified, not a public agent surface yet
resolve
| Surface | Public via resolve_entity / resolve endpoint |
| In | name / text, optional type |
| Out | ranked entity candidates |
| Shipped behavior | T0 exact alias match; ambiguity returns candidates, never a silent single guess. Write-time cascade is richer (T0–T4). |
lookup
| Surface | Public subset (/lookup/relations, /lookup/observations, … — see API) |
| In | relations / observations / claims / entity / document keys |
| Out | scalar records |
| Job | Direct spine reads |
search
| Surface | Public as search/claims and search/chunks (and inside assured ops) |
| Shipped channels | semantic | bm25 (independent; hybrid = one of each) |
| Shipped targets | claims, chunks |
| Design / not public agent targets yet | relations, observations, k_pages, media_segments as general search targets; extra fts channel name |
Shipped P1 notes:
- Chunk hits are evidence grain with typed chunk payload; body vs location header stay separate.
- Generation-safe across re-embed cutovers where implemented.
- Cross-modal media segment search is design-complete / not the default public target — do not document it as a callable search target until API lists it.
graph
| Surface | Public via typed graph methods + live SQL helpers |
| Job | SQL/PGQ for fixed shallow patterns and bounded recursive SQL for deeper/shortest traversal; authority hydration drops incomplete paths as units. |
fuse / rerank / combine_evidence
| Surface | Internal composition (also frozen inside operations like testimony_context) |
| Job | RRF merge, inspectable re-sort, typed evidence combination without UUID soup |
hydrate
| Surface | Public hydrate endpoints + implicit in assured ops |
| In | ids, depth (record | evidence | sources | bytes where exposed) |
| Job | Confirmation hop + progressive deepening |
transcript
| Surface | Public transcript endpoints for supported subjects (see API) |
| Out | decision history (recent-first, bounded; truncation signaled) |
delta / pages_about / aggregate / scan
| Surface | Internal / design / open-query equivalents — prefer saved examples + SQL for analytics; do not assume every name is an HTTP route |
| Job | Change feed, K routing index reverse lookup, enumerated aggregates, batch export |
How assured ops use them
testimony_context (evidence)
Conceptual chain:
- Semantic + lexical claim nomination → fuse → hydrate once
- Semantic + lexical chunk nomination → fuse → hydrate once
combine_evidenceunder one evidence envelope
fact_context (fact)
Conceptual chain:
- Resolve names separately and pass the unambiguous
entity_ids - For
current/at, walk one hop by default with empty predicates (allRELATES, includingother:*) - Nominate relation labels and observation statements inside the capped anchor + neighbor IDs
- Hydrate live relations/observations and attach testimony under a hard evidence budget
- Package graph nodes separately from facts, plus
fact_evidence, exact totals, contradictions, support markers
hops is 1–2. predicate is optional and may be any stored predicate; it is
passed unchanged to the live graph and re-confirmed on relation rows in Postgres. It is an
exact relation-only filter, so observations are excluded when it is present;
unfiltered observations remain facts and never become graph nodes. Unavailable
live-graph authority or a current anchor absent from it is a typed boundary;
a neighbor that becomes stale across the bounded reads is omitted and counted
in dropped_by_hydration. The combined entity cap is explicit in truncation.
overlap and history retain the explicit anchor scope because graph traversal
requires a single world-time instant.
Without entity_ids, profile prose is a second bounded nomination path for
fact text. “List banks” can therefore reach a bank observation; no type
argument or query-path completion model exists.
answer_context (ContextBundle/v1)
Purely composes the complete testimony_context and fact_context responses
under separate named fields. It adds no retrieval, ranking, hydration, or
flattening.
resolve_entity
Typed veneer over resolve with envelope packaging.
Temporal composition pattern
1) search/lookup event → read its world timestamp from the envelope
2) lookup/graph/search with valid_at = that timestamp
Belief horizons and boundaries
| Channel | Typical horizon behavior |
|---|---|
| Postgres | Full belief history |
| Live graph | Same PostgreSQL belief history and transaction snapshot |
| P1 | May have finite horizon |
Querying past a finite horizon → boundary negative with workaround.