Local-first 🧠memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.
TypeScript
/**
* The retrieval trail (evidence-at-the-boundary, C2): why a search
* narrowed, and why it came back empty.
*
* ## The problem this module removes
*
* A dozen degradation signals were computed by the pipeline and then
* either dropped on the floor or flattened into free-form English inside
* an untyped `warnings: string[]`. Several more said nothing at all - a
* query that tokenises to an empty FTS match, an owner-scope filter that
* removes every hit. A caller that got nothing back could not tell an
* exhausted corpus from a broken embedder, because both answer with the
* same empty array and the same silence.
*
* The sentences are not the fix. A sentence is a UI decision that a
* machine has to pattern-match, and this tree already carried one lane
* (`store/trigram.ts`) that classified its own fault onto a closed union
* and then destroyed the type by interpolating it into prose at the last
* step. So the vocabulary below is the wire format, one English mapping
* lives behind an exhaustive switch with no default arm, and only the
* human transcript ever calls it.
*
* ## Why there is no `lane` field
*
* Every code belongs to exactly one lane and says so in its own name
* (`keyword-*`, `semantic-*`, `cross-vault-*`). A separate `lane` field
* would be a second copy of a fact the code already carries, and two
* copies of one fact are what drift. A consumer that wants to group by
* lane groups by the code, which is stable by contract.
*
* ## The `detail` rule
*
* `detail` carries identifiers and integers only - never a provider
* message, never a filesystem path, never query text. It is the rule
* `brain/negative-recall.ts` states for its reasons and the one
* `store/trigram.ts` states for its warnings, and it exists because this
* channel travels into logs and MCP payloads: an FTS5 error echoes the
* caller's own query back, and a SQLite error can name the index file.
*
* An identifier may carry ONE namespace segment, because the cross-vault
* codes key on origin LABELS and a label is namespaced by construction
* (`profile/<name>`, `source/<alias>`). {@link RETRIEVAL_DETAIL_IDENTIFIER}
* is that grammar written once, so a reader, a writer and a test cannot
* each hold a different idea of what an identifier is.
*
* ## Absent, not empty
*
* A healthy answer with rows in it carries no trail, so the envelope is
* `{}` and every existing caller's bytes are unchanged - the same rule
* `explain-envelope.ts` follows for its receipts. The trail appears when
* something narrowed the answer, or when the answer is empty and owes an
* explanation.
*/
import type {
NegativeRecallState,
NegativeRecallUnknownReason,
NegativeRecallVerdict,
} from "../brain/negative-recall.ts";
/**
* Why a retrieval narrowed, as a closed vocabulary.
*
* Every member names a site that exists in this pipeline today. Members
* are NOT invented for conditions nothing reports: a code with no
* producer would be a promise the search path does not keep.
*/
/** How old the index may be before a search names it on the trail. */
export const INDEX_STALE_SECONDS = 600;
export const RETRIEVAL_DEGRADATION = Object.freeze({
/**
* The index was last updated more than {@link INDEX_STALE_SECONDS} ago, so
* notes changed since then may be missing from the answer. Detail:
* `ageSeconds`. The code reports the age only, not that a refresh is
* running: freshen on read starts a background run when it can and
* starts none when it is off, backing off, blocked by another run or
* writer, read-only for this reader, or unable to spawn. Added at read time (`withIndexStale`), never
* stored in the query cache.
*/
indexStale: "index-stale",
/**
* The brain store catch-up before this read failed, so store records
* appended since the last good catch-up may be missing from the answer.
* The failure's own message rides the warning sentence, not the code.
*/
storeCatchUpFailed: "store-catch-up-failed",
/**
* The query tokenised to an empty FTS match, so the keyword lane never
* ran. The purest silent empty in the tree: `fts.ts` returned no hits
* and no warning, which reads exactly like a vault with nothing in it.
*/
keywordFtsMatchEmpty: "keyword-fts-match-empty",
/**
* The trigram candidate lane could not be read. `detail.fault` carries
* the lane's own closed classification (`locked`, `corrupt`, ...),
* which existed already and was being interpolated into a sentence.
*/
keywordTrigramLaneFault: "keyword-trigram-lane-fault",
/** The index holds no compatible embedding, so the vector lane was skipped. */
semanticEmbeddingsAbsent: "semantic-embeddings-absent",
/** sqlite-vec is not loaded on this machine, so the vector lane was skipped. */
semanticVecExtensionUnavailable: "semantic-vec-extension-unavailable",
/**
* The configured semantic capability blocks the lane. `detail.tier`
* carries the rung of `SEMANTIC_CAPABILITY_TIER` that blocked it.
*/
semanticCapabilityBlocked: "semantic-capability-blocked",
/**
* The embedding provider could not answer. `detail.category` carries
* `classifyEmbeddingError`'s category - already computed at the call
* site and, until now, stringified into a sentence and thrown away.
*/
semanticProviderUnavailable: "semantic-provider-unavailable",
/**
* The query-embed gateway refused the embed: a caller that is not local,
* under a positive `embedding_cost_gate_usd`, on a model nobody priced.
* No `detail`: the model name is configuration, and the warning names
* it with the price pair that clears the refusal.
*/
semanticCostUnpriced: "semantic-cost-unpriced",
/**
* The query was cut to the effective embedding input window, so the
* semantic lane searched a prefix of what the caller sent.
* `detail.windowTokens` is the window it was fitted to. The lane ran.
*/
semanticQueryTruncated: "semantic-query-truncated",
/**
* The instruction prefix alone fills the effective embedding input
* window, so no part of the query was left to embed and the semantic
* lane did not run. `detail.windowTokens` is that window. A code of its
* own, apart from the cut, because this one always means a stopped lane.
*/
semanticQueryEmptyFit: "semantic-query-empty-fit",
/** The provider answered with an empty vector, so there was nothing to search. */
semanticEmptyQueryVector: "semantic-empty-query-vector",
/** A structured semantic lane was requested while semantic search is off. */
semanticStructuredLanesSkipped: "semantic-structured-lanes-skipped",
/**
* The index carries embeddings written by another build.
* `detail.fields` counts the contradicted ABI fields; their names stay
* in the operator-facing warning, which is where they are actionable.
*/
semanticEmbeddingAbiDrift: "semantic-embedding-abi-drift",
/**
* The caller wanted hybrid recall and the semantic lane did not run, so
* the answer is keyword-only. The umbrella over the semantic codes above
* that stop the lane - they say why, this says what the caller received.
*/
hybridDegraded: "hybrid-degraded",
/**
* The composite hybrid path (embed -> semanticTopK -> rerank -> second
* pass) outlived its single wall-clock budget (t_bdc24171), so the
* phases past the budget were cut and the answer is keyword-only. The
* per-lane timeouts keep firing first on their own lanes; this code
* names the one clock they cannot account for, their sum.
* `detail.budgetMs` is the deadline, `detail.elapsedMs` the moment it
* fired.
*/
hybridDeadlineExceeded: "hybrid-deadline-exceeded",
/**
* A person form in the query reached more than one person ONLY through
* derivation - an initial, a word order or an operator nickname - so the
* registry expansion added nothing for it: the design reports derived
* ambiguity rather than guessing one person (write-honesty-egress-consent,
* F3). Produced by the pipeline's candidate-signal collection, emitted in
* assembly. One entry per ambiguous form; `detail` maps that form to the
* competing person ids, dot-joined - entity ids never carry a dot, so the
* join is exact. The form is the detail KEY, not a value, because a name
* form is not an identifier and the value lane carries identifiers and
* integers only.
*/
personDerivedAmbiguity: "person-derived-ambiguity",
/**
* The rank cap truncated the candidate pool: matches existed below the
* cut and were never ranked. `detail.cap` is the cap that bit.
*/
rankCapTruncatedPool: "rank-cap-truncated-pool",
/**
* The configured cross-encoder rerank (remote endpoint or local model)
* could not answer, so the heuristic order was served. `detail.category`
* carries the closed `RERANK_FAILURE_CATEGORY` the failure was typed
* with (`auth`, `gone`, `transient`, ...; a local model's failure is
* `unclassified`); the provider's own message stays in the
* `rerank_degraded:` warning. Never cached: the next identical query
* asks the reranker again.
*/
rerankProviderUnavailable: "rerank-provider-unavailable",
/**
* The configured rerank model is past the shutdown date the rerank
* sunset survey records for it, so no request was made and the
* heuristic order was served. No `detail`: the model name is
* configuration, not an identifier the results carry, and the doctor
* check names it. Deterministic for the build and the date, so cached.
*/
rerankModelSunset: "rerank-model-sunset",
/**
* The caller's relevance floor dropped ranked rows. `detail.dropped`
* counts them - which is how a floor that removed every hit stops
* looking like a vault with no match.
*/
relevanceFloorDroppedRows: "relevance-floor-dropped-rows",
/**
* The per-source-session pool cap (t_bb6ce095) dropped ranked rows
* whose source import session was already represented at the cap. The
* cap runs after the caller's own filters, so only filter-passing rows
* consume a session's quota, and it is removal-only: it can never
* surface a row those filters would withhold. `detail.dropped` counts
* them against `detail.cap`, the per-session cap in force - the FINAL
* pass's numbers, because an under-filled window earns one re-widen.
* The name says SOURCE session - the import a note came from - so the
* code never reads as the caller's session focus.
*/
sourceSessionCappedRows: "source-session-capped-rows",
/**
* Visibility, ownership or session/project scope dropped ranked rows.
* `detail.dropped` counts them against `detail.before`, so a scope that
* removed every hit is distinguishable from an exhausted corpus.
*/
scopeFiltersDroppedRows: "scope-filters-dropped-rows",
/**
* A cross-vault origin could not be searched. `detail.origin` is the
* origin LABEL, which is an identifier the results already carry - the
* failure's own message is deliberately not here.
*/
crossVaultOriginFailed: "cross-vault-origin-failed",
/**
* An origin answered confidently and the remaining origins were
* deliberately not searched. `detail.skipped` counts them.
*/
crossVaultChainStopped: "cross-vault-chain-stopped",
} as const);
/** Closed union over {@link RETRIEVAL_DEGRADATION}. */
export type RetrievalDegradationCode =
(typeof RETRIEVAL_DEGRADATION)[keyof typeof RETRIEVAL_DEGRADATION];
/** Membership list, ordered lane by lane along the pipeline. */
export const RETRIEVAL_DEGRADATION_CODES: ReadonlyArray<RetrievalDegradationCode> = Object.freeze([
RETRIEVAL_DEGRADATION.indexStale,
RETRIEVAL_DEGRADATION.storeCatchUpFailed,
RETRIEVAL_DEGRADATION.keywordFtsMatchEmpty,
RETRIEVAL_DEGRADATION.keywordTrigramLaneFault,
RETRIEVAL_DEGRADATION.semanticEmbeddingsAbsent,
RETRIEVAL_DEGRADATION.semanticVecExtensionUnavailable,
RETRIEVAL_DEGRADATION.semanticCapabilityBlocked,
RETRIEVAL_DEGRADATION.semanticCostUnpriced,
RETRIEVAL_DEGRADATION.semanticQueryTruncated,
RETRIEVAL_DEGRADATION.semanticQueryEmptyFit,
RETRIEVAL_DEGRADATION.semanticProviderUnavailable,
RETRIEVAL_DEGRADATION.semanticEmptyQueryVector,
RETRIEVAL_DEGRADATION.semanticStructuredLanesSkipped,
RETRIEVAL_DEGRADATION.semanticEmbeddingAbiDrift,
RETRIEVAL_DEGRADATION.hybridDegraded,
RETRIEVAL_DEGRADATION.hybridDeadlineExceeded,
RETRIEVAL_DEGRADATION.personDerivedAmbiguity,
RETRIEVAL_DEGRADATION.rankCapTruncatedPool,
RETRIEVAL_DEGRADATION.rerankProviderUnavailable,
RETRIEVAL_DEGRADATION.rerankModelSunset,
RETRIEVAL_DEGRADATION.relevanceFloorDroppedRows,
RETRIEVAL_DEGRADATION.sourceSessionCappedRows,
RETRIEVAL_DEGRADATION.scopeFiltersDroppedRows,
RETRIEVAL_DEGRADATION.crossVaultOriginFailed,
RETRIEVAL_DEGRADATION.crossVaultChainStopped,
]);
/** Narrow a string read back across a tool boundary. */
export function isRetrievalDegradationCode(value: unknown): value is RetrievalDegradationCode {
return (
typeof value === "string" &&
(RETRIEVAL_DEGRADATION_CODES as ReadonlyArray<string>).includes(value)
);
}
/**
* Identifiers and integers only. The type is the enforcement: there is no
* shape here a provider message or an absolute path can be assigned to
* without a reader noticing it is prose.
*/
export type RetrievalDegradationDetail = Readonly<Record<string, string | number>>;
/**
* What "an identifier" means for a {@link RetrievalDegradationDetail}
* string: an optional namespace segment, then the identifier body.
*
* The namespace is not a concession - it is the shape of the one detail
* value the pipeline computes rather than names, the cross-vault origin
* LABEL (`profile/<name>`, `source/<alias>`). The rejected alternative was
* to split the label into a kind and a name so the separator never
* appeared: that would break the join a caller makes between a trail entry
* and the rows beside it, which carry the whole label on `origin` and in
* their `origin:<label>` reason.
*
* Exactly one separator, never leading, is what keeps the widening from
* re-admitting what the rule exists to exclude: `/var/lib/index.sqlite`
* and `Brain/notes/a.md` both fail it, as does anything carrying
* whitespace or prose punctuation. It is stated as a pattern rather than
* as prose so the tests assert the rule itself instead of restating it.
*/
export const RETRIEVAL_DETAIL_IDENTIFIER = /^(?:[A-Za-z0-9_-]+\/)?[A-Za-z0-9_.:-]+$/u;
/** One narrowing, as the pipeline recorded it. */
export interface RetrievalDegradation {
readonly code: RetrievalDegradationCode;
readonly detail?: RetrievalDegradationDetail;
}
/**
* The stable typed code identifying a relational ordered-path trail entry
* (truth-correctable-time-aware). Its own vocabulary member, NOT a
* {@link RETRIEVAL_DEGRADATION} code: a walked provenance path is not a
* narrowing, and a degradation row would make every consumer treat a
* healthy answer as a degraded one. It rides the trail because the trail
* is the one typed, machine-readable channel beside the rows - the
* additive `relational:` reason strings stay human provenance.
*/
export const RETRIEVAL_RELATIONAL_PATH_CODE = "relational-path";
/**
* One relational row's ordered path, machine-readable: the document ids
* that stayed readable at the caller's reach and owner scope, in walk
* order. Path nodes the gates withhold are omitted from `path` - never
* named, and never counted, so the entry reads the same whether the walk
* crossed unreadable documents or not (the views' identical-to-absent
* convention: a count would tell the caller that a node it may not see
* exists). Present on the trail only when the relational arm contributed
* a gated path - absent otherwise, keeping a healthy arm-off answer
* byte-identical.
*/
export interface RelationalPathTrailEntry {
readonly code: typeof RETRIEVAL_RELATIONAL_PATH_CODE;
/** Readable document ids along the walked path, in walk order. */
readonly path: ReadonlyArray<number>;
}
/**
* What the corpus supports when nothing degraded and nothing matched -
* the three surfaced fields of a {@link NegativeRecallVerdict}. The
* digest-bound coverage receipt is deliberately left off: it is a
* multi-field attestation the recall gate exists to serve, and repeating
* it on every empty search would pay for a receipt nobody asked for.
*/
export interface RetrievalCorpusStatement {
readonly state: NegativeRecallState;
readonly reason: string;
readonly unknownReason?: NegativeRecallUnknownReason;
}
/**
* What one retrieval did, beyond the rows it returned.
*
* `retrieved` and `pool` are both stated, because `SearchOutcome.total`
* is the size of the RANKED POOL and not the number of rows handed back:
* a caller had to infer the retrieved count from the array it happened to
* receive, and under `disclosure: "cards"` that array is empty by design.
*/
export interface RetrievalTrail {
/** Rows handed back, whether they rode `results` or `cards`. */
readonly retrieved: number;
/** Size of the ranked pool the window was cut from - `SearchOutcome.total`. */
readonly pool: number;
readonly degraded: ReadonlyArray<RetrievalDegradation>;
/**
* Present only on a zero-result answer that no degradation accounts
* for. When a lane degraded, the degradation IS the explanation and
* claiming the corpus holds nothing would be a stronger statement than
* the search can support.
*/
readonly empty?: RetrievalCorpusStatement;
/**
* The relational arm's reach-gated ordered paths, one entry per surfaced
* relational row in ranked order. Absent (never empty) when the arm
* contributed nothing.
*/
readonly relationalPaths?: ReadonlyArray<RelationalPathTrailEntry>;
}
/**
* The sink the pipeline threads, exactly parallel to the `warnings`
* array it rides beside: mutable, created once per query, pushed to by
* each lane at the point where it already pushes its sentence.
*/
export type RetrievalDegradationSink = RetrievalDegradation[];
/** Record one narrowing. The only writer, so the shape cannot drift. */
export function noteDegradation(
sink: RetrievalDegradationSink,
code: RetrievalDegradationCode,
detail?: RetrievalDegradationDetail,
): void {
sink.push(Object.freeze(detail !== undefined ? { code, detail } : { code }));
}
/** The codes that each mean the semantic lane a hybrid caller wanted did not run. */
const SEMANTIC_LANE_STOPS: ReadonlySet<RetrievalDegradationCode> = new Set([
RETRIEVAL_DEGRADATION.hybridDegraded,
RETRIEVAL_DEGRADATION.semanticCapabilityBlocked,
RETRIEVAL_DEGRADATION.semanticCostUnpriced,
RETRIEVAL_DEGRADATION.semanticQueryEmptyFit,
RETRIEVAL_DEGRADATION.semanticProviderUnavailable,
RETRIEVAL_DEGRADATION.semanticEmptyQueryVector,
]);
/**
* Whether a hybrid caller was served keyword-only for a reason that is not
* the index or the machine: the one definition every consumer that must
* not learn from, or save, a keyword-only measurement reads.
*
* `hybrid-degraded` is the umbrella - the caller wanted the semantic lane
* and it did not run - so the deadline counts without a code of its own.
* The umbrella is only noted when the keyword lane found something, so the
* codes that always mean the lane stopped count on their own too: a hit
* that arrived through another lane was still scored without the
* semantic one. A cut query is not one of them - the lane ran on the cut
* text - while an empty fit, where the instruction prefix alone fills the
* window, is.
* An index with no embeddings or a machine without sqlite-vec is
* keyword-only by construction: the system it measured is the one that
* will serve.
*/
export function semanticLaneMissing(degraded: ReadonlyArray<RetrievalDegradationCode>): boolean {
if (
degraded.includes(RETRIEVAL_DEGRADATION.semanticEmbeddingsAbsent) ||
degraded.includes(RETRIEVAL_DEGRADATION.semanticVecExtensionUnavailable)
) {
return false;
}
return degraded.some((code) => SEMANTIC_LANE_STOPS.has(code));
}
/**
* The one English mapping, exhaustive over the vocabulary with no default
* arm - so adding a code fails to compile here rather than silently
* inheriting another code's sentence. Called by the human transcript and
* by nothing else: the machine surfaces carry codes.
*/
export function describeRetrievalDegradation(code: RetrievalDegradationCode): string {
switch (code) {
case RETRIEVAL_DEGRADATION.indexStale:
return "the index was last updated more than ten minutes ago, so notes changed since then may be missing";
case RETRIEVAL_DEGRADATION.storeCatchUpFailed:
return "the brain store catch-up before this read failed, so store records added since the last good catch-up may be missing";
case RETRIEVAL_DEGRADATION.keywordFtsMatchEmpty:
return "the query carried no term the keyword index can match, so the keyword lane never ran";
case RETRIEVAL_DEGRADATION.keywordTrigramLaneFault:
return "the trigram candidate lane could not be read, so substring matches were not merged into the keyword pool";
case RETRIEVAL_DEGRADATION.semanticEmbeddingsAbsent:
return "the index holds no compatible embedding, so the semantic lane could not run";
case RETRIEVAL_DEGRADATION.semanticVecExtensionUnavailable:
return "the sqlite-vec extension is not loaded, so the semantic lane could not run";
case RETRIEVAL_DEGRADATION.semanticCapabilityBlocked:
return "the configured semantic capability blocks the vector lane, so it did not run";
case RETRIEVAL_DEGRADATION.semanticCostUnpriced:
return "the embedding model has no known price and the cost gate is on, so a query embed for a caller that is not local was refused and the semantic lane did not run";
case RETRIEVAL_DEGRADATION.semanticQueryTruncated:
return "the query was longer than the embedding input window, so the semantic lane searched a cut prefix of it";
case RETRIEVAL_DEGRADATION.semanticQueryEmptyFit:
return "the instruction prefix alone fills the embedding input window, so no part of the query was left to embed and the semantic lane did not run";
case RETRIEVAL_DEGRADATION.semanticProviderUnavailable:
return "the embedding provider could not answer, so the semantic lane did not run";
case RETRIEVAL_DEGRADATION.semanticEmptyQueryVector:
return "the embedding provider returned an empty query vector, so the semantic lane was skipped";
case RETRIEVAL_DEGRADATION.semanticStructuredLanesSkipped:
return "the query declared a structured semantic lane while semantic search is disabled, so that lane was skipped";
case RETRIEVAL_DEGRADATION.semanticEmbeddingAbiDrift:
return "the index carries embeddings written by another build, so its neighbours may not be comparable";
case RETRIEVAL_DEGRADATION.hybridDegraded:
return "the semantic lane did not run, so this answer is keyword-only";
case RETRIEVAL_DEGRADATION.hybridDeadlineExceeded:
return "the composite search outlived its wall-clock deadline, so the phases past the budget were cut and this answer is keyword-only";
case RETRIEVAL_DEGRADATION.personDerivedAmbiguity:
return "a person name in the query matched several people only through a derived form - an initial, a word order or a nickname - so nothing was expanded for it rather than guess one person";
case RETRIEVAL_DEGRADATION.rankCapTruncatedPool:
return "the rank cap truncated the candidate pool, so lower-ranked matches were never considered";
case RETRIEVAL_DEGRADATION.rerankProviderUnavailable:
return "the configured reranker could not answer, so this answer keeps the heuristic order";
case RETRIEVAL_DEGRADATION.rerankModelSunset:
return "the configured rerank model is past its announced shutdown date, so no rerank request was made and this answer keeps the heuristic order";
case RETRIEVAL_DEGRADATION.relevanceFloorDroppedRows:
return "the requested relevance floor dropped every ranked row it judged, so matches below it are not in this answer";
case RETRIEVAL_DEGRADATION.sourceSessionCappedRows:
return "the per-source-session pool cap dropped ranked rows whose source import session already held its share of the pool; when that left the window under-filled, the pool was re-widened once before this answer was cut";
case RETRIEVAL_DEGRADATION.scopeFiltersDroppedRows:
return "visibility, ownership or session scope dropped ranked rows, so this answer is narrower than the match set";
case RETRIEVAL_DEGRADATION.crossVaultOriginFailed:
return "a search origin could not be read, so its documents were not searched";
case RETRIEVAL_DEGRADATION.crossVaultChainStopped:
return "an origin answered confidently, so the remaining origins were deliberately not searched";
}
}
/**
* Project a {@link NegativeRecallVerdict} onto the trail's statement.
* One projection, so the CLI and the MCP payload cannot disagree about
* which of the verdict's fields an empty search reports.
*/
export function corpusStatementFor(verdict: NegativeRecallVerdict): RetrievalCorpusStatement {
return Object.freeze({
state: verdict.state,
reason: verdict.reason,
...(verdict.unknown_reason !== undefined ? { unknownReason: verdict.unknown_reason } : {}),
});
}
/**
* The trail for one answer, or `undefined` when there is nothing to
* report: rows came back and no lane narrowed them. That absence is what
* keeps a healthy response byte-identical to the pre-change one.
*/
export function buildRetrievalTrail(input: {
readonly retrieved: number;
readonly pool: number;
readonly degraded: ReadonlyArray<RetrievalDegradation>;
readonly empty?: RetrievalCorpusStatement | undefined;
readonly relationalPaths?: ReadonlyArray<RelationalPathTrailEntry> | undefined;
}): RetrievalTrail | undefined {
if (input.retrieved > 0 && input.degraded.length === 0 && !input.relationalPaths?.length) {
return undefined;
}
return Object.freeze({
retrieved: input.retrieved,
pool: input.pool,
degraded: Object.freeze([...input.degraded]),
// A degradation already accounts for the empty; the corpus statement
// is the answer only when nothing else is.
...(input.empty !== undefined && input.degraded.length === 0 ? { empty: input.empty } : {}),
// Absent, never empty: an arm-off run keeps the pre-change shape.
...(input.relationalPaths?.length ? { relationalPaths: input.relationalPaths } : {}),
});
}
/** Response key carrying the retrieval trail. */
export const RETRIEVAL_TRAIL_KEY = "retrieval_trail";
/**
* The trail keys for one outcome, ready to spread into a response object -
* the seam `explain-envelope.ts` proved, so the CLI `--json` payload and
* the MCP response name the same key with the same body.
*
* The parameter is structural rather than `SearchOutcome`, because
* `search/types.ts` names {@link RetrievalTrail} on the outcome and a type
* import back from here would close that loop.
*/
export function retrievalTrailEnvelope(outcome: {
readonly retrievalTrail?: RetrievalTrail;
}): Record<string, unknown> {
const trail = outcome.retrievalTrail;
if (trail === undefined) return {};
return {
[RETRIEVAL_TRAIL_KEY]: {
retrieved: trail.retrieved,
pool: trail.pool,
degraded: trail.degraded.map((d) => (d.detail !== undefined ? { ...d } : { code: d.code })),
...(trail.empty !== undefined
? {
empty: {
state: trail.empty.state,
reason: trail.empty.reason,
...(trail.empty.unknownReason !== undefined
? { unknown_reason: trail.empty.unknownReason }
: {}),
},
}
: {}),
...(trail.relationalPaths?.length
? {
relational_paths: trail.relationalPaths.map((entry) => ({
code: entry.code,
path: [...entry.path],
})),
}
: {}),
},
};
}