Skip to content

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
27.5 KB
Raw Blame
/**
 * 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],
            })),
          }
        : {}),
    },
  };
}