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
57.0 KB
Raw Blame
/**
 * Public surface for `src/core/search/*`: config resolution plus the
 * index/search/status/check entry points used by CLI and MCP layers.
 */

import { discoverConfig } from "../config.ts";
import {
  envOrConfig,
  parseBool as parseBoolShared,
  parseFloat01 as parseFloat01Shared,
  parseInteger as parseIntegerShared,
  normalizeReservedName,
} from "../validate.ts";
import { resolveVaultScope } from "../vault-scope/index.ts";
import { DEFAULT_HYBRID_DEADLINE_MS } from "./pipeline/request.ts";
import { resolveIndexPathForProbe, SEARCH_DB_CONFIG_KEY, SEARCH_DB_ENV } from "./paths.ts";
import { resolveIndexedStoreProbe } from "./brain-store/location.ts";
import { buildFtsTokenize } from "./schema.ts";
import { isFusionMode, DEFAULT_RRF_K } from "./fusion.ts";
import { DEFAULT_RECENCY } from "./recency.ts";
import {
  loadProviderRegistry,
  expandRegisteredProvider,
  type ExpandedProvider,
  type ProviderProfile,
} from "./embeddings/registry.ts";
import {
  EMBEDDING_KEY_CONFIG,
  EMBEDDING_KEY_ENV,
  type CredentialSourceContext,
} from "./embeddings/credential-report.ts";
import { loadRerankRegistry, expandRegisteredRerankProvider } from "./rerank/registry.ts";
import { decisionModelModeFor, resolveDecisionModelConfig } from "../decision-model/config.ts";
import {
  isSearchTrustGateMode,
  resolveSearchTrustGateLegacyEnabled,
  resolveSearchTrustGateMode,
  SEARCH_TRUST_GATE_MODE,
} from "../brain/trust/retrieval-gate.ts";
import { INPUT_WINDOW_TOKENS_KEY, resolveEmbeddingPrefixes } from "./embeddings/presets.ts";
import {
  EMBEDDING_PRICE_MODEL_ENV,
  EMBEDDING_PRICE_MODEL_KEY,
  EMBEDDING_PRICE_RATE_ENV,
  EMBEDDING_PRICE_RATE_KEY,
  type EmbeddingPriceOverride,
} from "./embeddings/pricing.ts";
import { SearchError } from "./types.ts";
import { isSecretReferenceValue, resolveNamedSecret } from "../secret-resolver.ts";
import { SecretReferenceError } from "../secret-ref.ts";
import {
  SecretStoreKeyfileMissingError,
  SecretStoreLockedError,
} from "../brain/secrets/envelope.ts";
import type {
  ResolvedEmbeddingConfig,
  ResolvedFreshenConfig,
  ResolvedRecallConfig,
  ResolvedRerankConfig,
  ResolvedSearchConfig,
  VaultScopeRules,
} from "./types.ts";
import { ITERATIVE_RECALL_MAX_ROUNDS_CAP, ITERATIVE_RECALL_MAX_ROUNDS_DEFAULT } from "./types.ts";

type SearchConfigOverrides = Partial<
  Omit<ResolvedSearchConfig, "scopeRules" | "semantic" | "rerank">
> & {
  readonly scopeRules?: VaultScopeRules;
  readonly semantic?: Partial<ResolvedEmbeddingConfig>;
  readonly rerank?: Partial<ResolvedRerankConfig>;
};

export type {
  BrainSearchResult,
  ChunkWindowCensus,
  DisclosureMode,
  EvidencePack,
  ExpandedNote,
  ExpandedRawChunk,
  ExpandHitInput,
  ExpandHitResult,
  IndexCheckReport,
  CredentialSourceReport,
  EmbedderRecordCensus,
  IndexStats,
  IndexStatusSnapshot,
  PendingVectorCensus,
  ResolvedEmbeddingConfig,
  ResolvedFreshenConfig,
  ResolvedRecallConfig,
  ResolvedRerankConfig,
  ResolvedSearchConfig,
  SearchCard,
  SearchErrorCode,
  SearchLaneTiming,
  SearchOptions,
  SearchOutcome,
  SearchSessionFocus,
  StructuredRecallQueryDocument,
  VaultPathRule,
  VaultScopeRules,
  VisibilityHonestyFinding,
} from "./types.ts";
export {
  chunkWindowDiagnosticCode,
  CHUNK_WINDOW_CODE,
  EMBEDDING_QUOTA_MESSAGE,
  SearchError,
  SEARCH_ERROR_CODES,
} from "./types.ts";
export {
  resolveTraversalBudgets,
  TRAVERSAL_MAX_SEEDS,
  TRAVERSAL_MAX_EXPANSION_PER_NODE,
  TRAVERSAL_MAX_TOTAL_NODES,
  TRAVERSAL_HUB_DEGREE_THRESHOLD,
  TRAVERSAL_MAX_SEEDS_ENV,
  TRAVERSAL_MAX_EXPANSION_PER_NODE_ENV,
  TRAVERSAL_MAX_TOTAL_NODES_ENV,
  TRAVERSAL_HUB_DEGREE_THRESHOLD_ENV,
  TRAVERSAL_MAX_SEEDS_CONFIG,
  TRAVERSAL_MAX_EXPANSION_PER_NODE_CONFIG,
  TRAVERSAL_MAX_TOTAL_NODES_CONFIG,
  TRAVERSAL_HUB_DEGREE_THRESHOLD_CONFIG,
  type TraversalBudgets,
} from "./relational-fanout.ts";
export {
  parseStructuredRecallQueryDocument,
  structuredRecallQueryText,
} from "./structured-query.ts";
export {
  clearSessionFocus,
  normalizeSessionFocus,
  readSessionFocus,
  sessionFocusIsActive,
  writeSessionFocus,
} from "./session-focus.ts";
export { evaluateSurfacingGate, type SurfacingGateDecision } from "./surfacing-gate.ts";
export { buildEvidencePack, serializeEvidencePack } from "./evidence-pack.ts";
export {
  serializeChunkWindowCensus,
  serializeEmbedderRecordCensus,
  serializePendingVectorCensus,
  serializeSearchCard,
  serializeIndexStatus,
  serializeStampMismatches,
  serializeVisibilityHonestyFinding,
} from "./serialize.ts";
export {
  callableVisibilitySurfaces,
  excludedCallableVisibilitySurfaces,
  excludedVisibilitySurfaces,
  VISIBILITY_SURFACE_CATEGORY,
  VISIBILITY_SURFACE_KIND,
  VISIBILITY_SURFACE_REGISTRY,
  type VisibilitySurfaceCategory,
  type VisibilitySurfaceEntry,
  type VisibilitySurfaceKind,
} from "./visibility-surface-registry.ts";
export {
  loadProviderRegistry,
  addProviderProfile,
  removeProviderProfile,
  getProviderProfile,
  providerRegistryPath,
  RESERVED_PROVIDER_NAMES,
  type ProviderProfile,
} from "./embeddings/registry.ts";
export {
  loadRerankRegistry,
  addRerankProviderProfile,
  removeRerankProviderProfile,
  getRerankProviderProfile,
  rerankRegistryPath,
  type RerankProviderProfile,
} from "./rerank/registry.ts";
export {
  applyCrossEncoderRerank,
  type ApplyCrossEncoderRerankOptions,
  type RerankTelemetryEvent,
} from "./rerank/index.ts";
export { LocalRerankProvider, scoreLocalRerank } from "./rerank/local.ts";
export {
  runRerankEvalGate,
  type RerankEvalGateOptions,
  type RerankEvalGateResult,
} from "./rerank-eval-gate.ts";

export { resolveConfiguredIndexPath, resolveIndexPath } from "./paths.ts";
export {
  indexVault,
  reindexVault,
  indexStatus,
  indexCheck,
  indexRootCoverage,
  indexBehindCount,
  type IndexBehind,
  type IndexRootCoverage,
  type IndexVaultOptions,
  type IndexProgressEvent,
} from "./indexer.ts";
export {
  EVENT_TIME_RECENT_WINDOW_DAYS,
  eventTimeStatus,
  renderEventTimeStatus,
  serializeEventTimeStatus,
  type EventTimeStatus,
} from "./event-time-status.ts";
export { search, SEARCH_LIMIT_MIN, SEARCH_LIMIT_MAX } from "./search.ts";
export { DEFAULT_HYBRID_DEADLINE_MS } from "./pipeline/request.ts";
export { expandHit } from "./cards.ts";
export { planReadShortlist, planRead } from "./graph-prepass.ts";
export type { GraphPrepassOptions, GraphPrepassResult, ShouldReadEntry } from "./graph-prepass.ts";
export {
  captureRecallFeedback,
  computeLearnedWeights,
  feedbackDir,
  learnedWeightsPath,
  loadFeedbackEvents,
  readLearnedWeights,
  resetLearnedWeights,
  LEARNED_WEIGHT_MIN,
  LEARNED_WEIGHT_MAX,
  type LearnedWeights,
  type RecallFeedbackEvent,
} from "./feedback.ts";

/**
 * Shipped keyword-lane weight.
 *
 * Named because it is quoted outside this module. `rankResults` min-max
 * normalises the keyword lane, so the top-ranked row of any recall whose
 * KEYWORD lane is non-empty carries exactly this much keyword term
 * whatever it matched - and every layer `rankResults` adds on top of that
 * term (freshness, link, tag, entity, activation, co-access, reuse,
 * temporal intent, session focus) is non-negative. So this number is a
 * FLOOR on that row's score, not the score: `>=`, never `=`.
 *
 * The distinction is not academic. Measured on a keyword-only vault whose
 * files were just written, the top row scores 0.6499997... - this weight
 * plus the freshness prior sitting at its amplitude, which is the one
 * other layer such a vault has live ({@link FRESH_KEYWORD_ONLY_TOP_SCORE}).
 * On the committed benchmark corpus a row that also draws a link or entity
 * boost reaches 0.67, and with the semantic lane on the pinned window runs
 * from 0.2675 to 0.9405. What is invariant is the floor, and only while
 * the keyword lane is non-empty.
 *
 * Prose that states the pin - `src/core/bench/failure-modes.ts`,
 * `src/core/config.ts`, `src/core/brain/recall-adequacy.ts`,
 * `src/core/brain/gaps/gap-loop.ts`, `src/core/search/types.ts` - cites
 * these two symbols rather than repeating the digits, and
 * `tests/core/search/keyword-lane-top-score.test.ts` drives the shipped
 * pipeline over such a vault and asserts both numbers against these
 * bindings, so the stated number cannot drift from the shipped one again.
 */
export const DEFAULT_KEYWORD_WEIGHT = 0.6;

/**
 * What the top row of a keyword-only recall over freshly written files
 * actually scores: {@link DEFAULT_KEYWORD_WEIGHT} plus the freshness
 * prior at its full amplitude.
 *
 * Derived rather than written out, because it is the sum of two shipped
 * defaults and a hand-copied 0.65 is exactly the digit that drifted.
 * An upper bound for that vault only - nothing else is live there - and
 * not a ceiling in general: the other eight boost layers are additive.
 * The real content of the number is the pair of unreachability facts the
 * threshold moves rest on: it clears every floor a score used to be
 * compared against (0.35, 0.5, 0.6), and it falls short of the 0.8 chain
 * stop.
 */
export const FRESH_KEYWORD_ONLY_TOP_SCORE = DEFAULT_KEYWORD_WEIGHT + DEFAULT_RECENCY.amplitude;

const DEFAULTS = {
  chunkSize: 800,
  chunkOverlap: 100,
  chunkMinSize: 100,
  keywordWeight: DEFAULT_KEYWORD_WEIGHT,
  semanticWeight: 0.4,
  provider: "openai-compat" as const,
  timeoutMs: 10_000,
  concurrency: 4,
  batchSize: 32,
  maxRetries: 6,
  costGateUsd: 0,
  mmrLambda: 0.7,
  maxHops: 1,
  hopDecay: 0.5,
  maxExpansionPerHit: 3,
  // Read off the curve module rather than copied: `FRESH_KEYWORD_ONLY_TOP_SCORE`
  // is derived from the amplitude, so a second copy of it here could make
  // the derived constant describe a curve the resolver does not ship.
  recencyShape: DEFAULT_RECENCY.shape,
  recencyScale: DEFAULT_RECENCY.scale,
  recencyAmplitude: DEFAULT_RECENCY.amplitude,
  synonymMaxTerms: 3,
  cacheTtlSeconds: 300,
  fusionMode: "linear" as const,
  rrfK: DEFAULT_RRF_K,
  shutdownGraceSeconds: 5,
  resumeReindex: false,
  chainStopScore: 0.8,
  trigramPrefilterEnabled: false,
  trigramPrefilterMinChunks: 5000,
  trigramPrefilterMaxSelectivity: 0.5,
  // Per-source-session pool cap (t_bb6ce095): off at 0, which never runs
  // the phase and adds no frontmatter reads.
  poolMaxPerSession: 0,
  rerankTopK: 20,
  rerankMinScore: 0,
};

function parseFusionMode(raw: string | null): "linear" | "rrf" {
  if (raw === null) return DEFAULTS.fusionMode;
  if (isFusionMode(raw)) return raw;
  throw new SearchError(
    "INVALID_INPUT",
    `search_fusion_mode must be 'linear' or 'rrf', got '${raw}'`,
  );
}

type IntegerRange = { readonly min?: number; readonly max?: number };

function parseInteger(
  raw: string | null,
  fallback: number,
  fieldName: string,
  range?: IntegerRange,
): number {
  try {
    return parseIntegerShared(raw, fallback, fieldName, range);
  } catch (e) {
    throw new SearchError("INVALID_INPUT", (e as Error).message);
  }
}

function parseFloat01(raw: string | null, fallback: number, fieldName: string): number {
  try {
    return parseFloat01Shared(raw, fallback, fieldName);
  } catch (e) {
    throw new SearchError("INVALID_INPUT", (e as Error).message);
  }
}

function parseBool(raw: string | null, fallback: boolean, fieldName: string): boolean {
  try {
    return parseBoolShared(raw, fallback, fieldName);
  } catch (e) {
    throw new SearchError("INVALID_INPUT", (e as Error).message);
  }
}

/** Parse a strictly-positive finite float (e.g. Weibull shape / scale). */
function parsePositiveFloat(raw: string | null, fallback: number, fieldName: string): number {
  if (raw === null) return fallback;
  const n = Number(raw);
  if (!Number.isFinite(n) || n <= 0) {
    throw new SearchError("INVALID_INPUT", `${fieldName} must be a number > 0, got '${raw}'`);
  }
  return n;
}

/** Parse a non-negative finite float (e.g. a cost gate; 0 disables). */
function parseNonNegativeFloat(raw: string | null, fallback: number, fieldName: string): number {
  if (raw === null) return fallback;
  // `Number("  ")` is 0: a blank gate would read as a gate switched off.
  if (raw.trim() === "") {
    throw new SearchError("INVALID_INPUT", `${fieldName} must be a number >= 0, got empty string`);
  }
  const n = Number(raw);
  if (!Number.isFinite(n) || n < 0) {
    throw new SearchError("INVALID_INPUT", `${fieldName} must be a number >= 0, got '${raw}'`);
  }
  return n;
}

/** The highest declarable embedding rate, in USD per million tokens. */
const EMBEDDING_PRICE_RATE_CEILING = 1_000_000;

/**
 * Parse a declared embedding rate. Only a plain decimal spelling is a
 * price: `Number()` would read `0x10`, `1e3` or `Infinity` as numbers an
 * operator never wrote as a rate. A rate above the ceiling is a typo, not
 * a price, and would overflow every estimate built on it.
 */
function parseEmbeddingPriceRate(raw: string, fieldName: string): number {
  if (!/^\d+(\.\d+)?$/.test(raw)) {
    throw new SearchError(
      "INVALID_INPUT",
      `${fieldName} must be a plain decimal number >= 0 (for example 0.02), got '${raw}'`,
    );
  }
  const n = Number(raw);
  if (n > EMBEDDING_PRICE_RATE_CEILING) {
    throw new SearchError(
      "INVALID_INPUT",
      `${fieldName} must be at most ${EMBEDDING_PRICE_RATE_CEILING} USD per million tokens, got '${raw}'`,
    );
  }
  return n;
}

/**
 * The operator's declared embedding price: `embedding_price_model` and
 * `embedding_price_usd_per_mtok`, both or neither, overridable as a unit
 * by their `OPEN_SECOND_BRAIN_EMBEDDING_PRICE_*` env twins. A pair, not a
 * model-keyed map, because the flat parser splits a key on its first
 * colon and model ids carry colons (`nomic-embed-text:latest`); the value
 * side keeps them. Binding the rate to one model name means a model
 * switch never silently re-targets the price. The pair resolves from ONE
 * source: when either env twin is set both halves come from env, so an
 * env model never borrows a config rate into a price nobody declared.
 * Null when neither source sets either half.
 */
function resolveEmbeddingPriceOverride(
  env: NodeJS.ProcessEnv,
  config: Readonly<Record<string, string>>,
): EmbeddingPriceOverride | null {
  // A blank half is a missing half: `Number("  ")` is 0, so a whitespace
  // rate would otherwise declare an unpriced model free.
  const set = (layer: Readonly<Record<string, string | undefined>>, name: string) => {
    const value = layer[name]?.trim();
    return value === undefined || value === "" ? null : value;
  };
  const fromEnv =
    set(env, EMBEDDING_PRICE_MODEL_ENV) !== null || set(env, EMBEDDING_PRICE_RATE_ENV) !== null;
  const [layer, modelName, rateName] = fromEnv
    ? [env, EMBEDDING_PRICE_MODEL_ENV, EMBEDDING_PRICE_RATE_ENV]
    : [config, EMBEDDING_PRICE_MODEL_KEY, EMBEDDING_PRICE_RATE_KEY];
  const model = set(layer, modelName);
  const rateRaw = set(layer, rateName);
  if (model === null && rateRaw === null) return null;
  if (model === null || rateRaw === null) {
    const [present, missing] = model === null ? [rateName, modelName] : [modelName, rateName];
    throw new SearchError(
      "INVALID_INPUT",
      `${present} is set but ${missing} is not: declare both or neither`,
    );
  }
  const usdPerMtok = parseEmbeddingPriceRate(rateRaw, rateName);
  return Object.freeze({ model, usdPerMtok });
}

export const EXTRA_BODY_KEY = "embedding_extra_body";
export const EXTRA_BODY_ENV = "OPEN_SECOND_BRAIN_EMBEDDING_EXTRA_BODY";
const EMBEDDING_DIMENSION_KEY = "embedding_dimension";

/**
 * Request-body fields the OpenAI-compatible provider owns. An extra body
 * may not name them in any spelling: the provider spreads the extra
 * fields first so these win anyway, but a silently ignored field is a
 * configuration the operator believes is in force when it is not.
 */
export const RESERVED_EMBEDDING_BODY_KEYS: ReadonlyArray<string> = Object.freeze([
  "model",
  "input",
  "encoding_format",
]);

const RESERVED_BODY_KEYS_NORMALIZED: ReadonlySet<string> = new Set(
  RESERVED_EMBEDDING_BODY_KEYS.map(normalizeReservedName),
);

/**
 * The operator's extra request body: a JSON object in one flat key,
 * because the config file cannot hold a nested map. Read with raw
 * presence so a blank value is refused rather than folded into "unset".
 * Every refusal names the source the value came from - the env variable
 * when it is set, the config key otherwise. The cross-checks against the
 * rest of the resolved config (the `dimensions` field, the provider)
 * live in `validateExtraBody`, so a programmatic override meets them too.
 * Null when neither source sets the key.
 */
function resolveEmbeddingExtraBody(
  env: NodeJS.ProcessEnv,
  config: Readonly<Record<string, string>>,
): Readonly<Record<string, unknown>> | null {
  const raw = rawSetting(env, config, EXTRA_BODY_ENV, EXTRA_BODY_KEY);
  if (raw === null) return null;
  const source = env[EXTRA_BODY_ENV] !== undefined ? EXTRA_BODY_ENV : EXTRA_BODY_KEY;
  if (raw.trim() === "") {
    throw new SearchError("INVALID_INPUT", `${source} must be a JSON object, got a blank value`);
  }
  let parsed: unknown;
  try {
    parsed = JSON.parse(raw);
  } catch {
    throw new SearchError("INVALID_INPUT", `${source} must be a JSON object, got invalid JSON`);
  }
  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
    throw new SearchError(
      "INVALID_INPUT",
      `${source} must be a JSON object, got ${describeJsonKind(parsed)}`,
    );
  }
  const body = parsed as Record<string, unknown>;
  refuseReservedBodyKeys(body, source);
  return Object.freeze(body);
}

/** The kind of a parsed JSON value that is not an object, as a refusal names it. */
function describeJsonKind(value: unknown): string {
  if (value === null) return "null";
  if (Array.isArray(value)) return "an array";
  return typeof value;
}

/**
 * Refuse every key that names an owned request field in any spelling,
 * listing them all in one sentence that names `source`. Run at parse time
 * to name the env variable or the key, and again in `validateExtraBody`
 * so an override that never passed through the parser meets it too.
 */
function refuseReservedBodyKeys(body: Readonly<Record<string, unknown>>, source: string): void {
  const reserved = Object.keys(body).filter((k) =>
    RESERVED_BODY_KEYS_NORMALIZED.has(normalizeReservedName(k)),
  );
  if (reserved.length > 0) {
    throw new SearchError(
      "INVALID_INPUT",
      `${source} may not set the owned request fields (${RESERVED_EMBEDDING_BODY_KEYS.join(", ")}): ` +
        `refused ${reserved.map((k) => `'${k}'`).join(", ")}`,
    );
  }
}

/**
 * Cross-check a resolved extra body against the config it rides in.
 *
 * A `dimensions` field, in any spelling, changes the width the provider
 * answers with. With no configured `embedding_dimension` nothing pins the
 * index to that width, so a mismatch with the stored index would surface
 * as a raw vector-store error mid-search; with one configured, the two
 * must agree. Only the OpenAI-compatible provider sends an extra body at
 * all, so naming one for another backend is refused rather than left as a
 * configuration the operator believes is in force; `disabled` sends
 * nothing, so the body is inert there. All of it is refused here rather
 * than at parse time so an override that never passed through the parser
 * meets it too. Every refusal names `source`: the env variable when it
 * supplied the body, the config key otherwise.
 */
function validateExtraBody(semantic: ResolvedEmbeddingConfig, source: string): void {
  const body = semantic.extraBody;
  if (body === undefined) return;
  if (semantic.provider !== "openai-compat" && semantic.provider !== "disabled") {
    throw new SearchError(
      "INVALID_INPUT",
      `${source} is only sent by the 'openai-compat' provider, ` +
        `but embedding_provider is '${semantic.provider}': remove the key or switch providers`,
    );
  }
  refuseReservedBodyKeys(body, source);
  const target = normalizeReservedName("dimensions");
  for (const key of Object.keys(body)) {
    if (normalizeReservedName(key) !== target) continue;
    const value = JSON.stringify(body[key]);
    if (semantic.dimension === null) {
      throw new SearchError(
        "INVALID_INPUT",
        `${source} sets '${key}' ${value} but ${EMBEDDING_DIMENSION_KEY} is not set: ` +
          `declare ${EMBEDDING_DIMENSION_KEY} with the same width so the index is pinned to it`,
      );
    }
    if (body[key] !== semantic.dimension) {
      throw new SearchError(
        "INVALID_INPUT",
        `${source} sets '${key}' ${value} but ${EMBEDDING_DIMENSION_KEY} is ${semantic.dimension}`,
      );
    }
  }
}

/**
 * Raw setting lookup that preserves an explicit empty string
 * (memory-write-path-integrity B2). Unlike `envOrConfig`, which folds `""`
 * into "unset", this returns `""` when a key is present-but-empty so an
 * operator can explicitly DISABLE a preset-provided default; only a truly
 * absent key returns null.
 */
function rawSetting(
  env: NodeJS.ProcessEnv,
  config: Readonly<Record<string, string>>,
  envKey: string,
  configKey: string,
): string | null {
  const e = env[envKey];
  if (e !== undefined) return e;
  const c = config[configKey];
  if (c !== undefined) return c;
  return null;
}

/**
 * Parse a finite float over the whole real line (e.g. a rerank floor,
 * which can be negative for backends that emit logits rather than [0, 1]
 * relevance).
 */
function parseFiniteFloat(raw: string | null, fallback: number, fieldName: string): number {
  if (raw === null) return fallback;
  if (raw.trim() === "") {
    throw new SearchError(
      "INVALID_INPUT",
      `${fieldName} must be a finite number, got empty string`,
    );
  }
  const n = Number(raw);
  if (!Number.isFinite(n)) {
    throw new SearchError("INVALID_INPUT", `${fieldName} must be a finite number, got '${raw}'`);
  }
  return n;
}

function validateIntegerRange(n: number, fieldName: string, range?: IntegerRange): void {
  // NaN/Infinity fail every `<`/`>` comparison below, so without this guard
  // an override supplied as a raw (non-string) number silently passes range
  // checks that a string-sourced value would have caught via parseInteger.
  if (!Number.isFinite(n)) {
    throw new SearchError("INVALID_INPUT", `${fieldName} must be a finite number, got '${n}'`);
  }
  // Integrality, for the same reason: a string-sourced value has already
  // been through `parseInteger`, which refuses a fraction, so accepting one
  // from a programmatic override would leave two entry paths disagreeing
  // about what the field means - and hand a downstream consumer (the batch
  // packer, the chunker's stride) a value it cannot step by.
  if (!Number.isInteger(n)) {
    throw new SearchError("INVALID_INPUT", `${fieldName} must be an integer, got ${n}`);
  }
  if (range?.min !== undefined && n < range.min) {
    throw new SearchError("INVALID_INPUT", `${fieldName} must be >= ${range.min}, got ${n}`);
  }
  if (range?.max !== undefined && n > range.max) {
    throw new SearchError("INVALID_INPUT", `${fieldName} must be <= ${range.max}, got ${n}`);
  }
}

function validateWeight(n: number, fieldName: string): void {
  if (!Number.isFinite(n) || n < 0 || n > 1) {
    throw new SearchError("INVALID_INPUT", `${fieldName} must be a number in [0, 1], got '${n}'`);
  }
}

function validateResolvedConfig(config: ResolvedSearchConfig, extraBodySource: string): void {
  validateIntegerRange(config.chunkSize, "search_chunk_size", { min: 1 });
  validateIntegerRange(config.chunkOverlap, "search_chunk_overlap", { min: 0 });
  if (config.chunkOverlap >= config.chunkSize) {
    throw new SearchError(
      "INVALID_INPUT",
      `search_chunk_overlap must be smaller than search_chunk_size, got ${config.chunkOverlap} >= ${config.chunkSize}`,
    );
  }
  validateIntegerRange(config.chunkMinSize, "search_chunk_min_size", { min: 1 });
  if (config.chunkMinSize > config.chunkSize) {
    throw new SearchError(
      "INVALID_INPUT",
      `search_chunk_min_size must not exceed search_chunk_size, got ${config.chunkMinSize} > ${config.chunkSize}`,
    );
  }
  validateWeight(config.keywordWeight, "search_keyword_weight");
  validateWeight(config.semanticWeight, "search_semantic_weight");
  // A mode can arrive through an override (a bench pin) that skipped the
  // key resolution, so the merged value is checked here too.
  const gateMode: unknown = config.recall.searchTrustGateMode;
  if (
    gateMode !== undefined &&
    !(typeof gateMode === "string" && isSearchTrustGateMode(gateMode))
  ) {
    throw new SearchError(
      "INVALID_INPUT",
      `search_trust_gate_mode must be 'off', 'shadow' or 'enforce', got '${String(gateMode)}'`,
    );
  }
  if (config.keywordWeight + config.semanticWeight > 1.0 + 1e-9) {
    throw new SearchError(
      "INVALID_INPUT",
      `keyword_weight + semantic_weight must sum to <= 1, got ${config.keywordWeight} + ${config.semanticWeight}`,
    );
  }
  if (config.semantic.dimension !== null) {
    validateIntegerRange(config.semantic.dimension, EMBEDDING_DIMENSION_KEY, {
      min: 1,
    });
  }
  validateIntegerRange(config.semantic.timeoutMs, "embedding_timeout_ms", {
    min: 1,
  });
  // Optional (configs written before the knob construct this shape
  // literally); a present value validates exactly like the per-lane
  // timeouts, except `0` is legal because it is the documented off
  // switch, not a misconfiguration (t_bdc24171).
  if (config.hybridDeadlineMs !== undefined) {
    validateIntegerRange(config.hybridDeadlineMs, "search_hybrid_deadline_ms", {
      min: 0,
    });
  }
  // Per-source-session pool cap (t_bb6ce095): optional (absent reads as
  // the off value 0), and never negative - a negative cap would drop
  // every identified row, which is a misconfiguration, not an off switch.
  // No upper bound here by design (review L4): a value at or above the
  // pool width the query resolves cannot drop a row from that pool, and
  // the assembly treats it as off - the phase never runs - while the
  // resolved value still folds into the search fingerprint, so a change
  // around that boundary can never serve a stale cached row.
  if (config.recall.poolMaxPerSession !== undefined) {
    validateIntegerRange(config.recall.poolMaxPerSession, "search_pool_max_per_session", {
      min: 0,
    });
  }
  validateIntegerRange(config.semantic.concurrency, "embedding_concurrency", {
    min: 1,
  });
  validateIntegerRange(config.semantic.batchSize, "embedding_batch_size", {
    min: 1,
  });
  // Optional: absent means no token budget. Present-but-zero is a
  // misconfiguration (a batch that can hold nothing), rejected the same way
  // `embedding_batch_size` is - including when supplied as a programmatic
  // override that never passed through `parseInteger`.
  if (config.semantic.batchTokens !== undefined) {
    validateIntegerRange(config.semantic.batchTokens, "embedding_batch_tokens", {
      min: 1,
    });
  }
  // Optional and default-free, like the token budget: a window that holds
  // nothing is a misconfiguration whatever its source. The offline local
  // embedder hashes the whole text with no positional limit and never
  // reads this key, so a declared window there would not be in force.
  if (config.semantic.inputWindowTokens !== undefined) {
    validateIntegerRange(config.semantic.inputWindowTokens, INPUT_WINDOW_TOKENS_KEY, {
      min: 1,
    });
    if (config.semantic.provider === "local") {
      throw new SearchError(
        "INVALID_INPUT",
        `${INPUT_WINDOW_TOKENS_KEY} is not read by the 'local' provider, ` +
          `which has no input window: remove the key or switch providers`,
      );
    }
  }
  validateIntegerRange(config.semantic.maxRetries, "embedding_max_retries", {
    min: 1,
  });
  validateExtraBody(config.semantic, extraBodySource);
}

function parseProvider(raw: string | null): ResolvedEmbeddingConfig["provider"] {
  if (raw === null) return DEFAULTS.provider;
  if (raw === "openai-compat" || raw === "disabled" || raw === "local" || raw === "zeroentropy") {
    return raw;
  }
  throw new SearchError(
    "INVALID_INPUT",
    `embedding_provider must be 'openai-compat', 'zeroentropy', 'local', 'disabled', or a registered provider name, got '${raw}'`,
  );
}

const BUILTIN_PROVIDERS: ReadonlySet<string> = new Set([
  "openai-compat",
  "disabled",
  "local",
  "zeroentropy",
]);

/**
 * Resolve a non-built-in `embedding_provider` name against the registry.
 * Returns null when the name is null, a built-in, or not registered - the
 * caller then defers to `parseProvider` (which validates built-ins and
 * raises a clear error for an unknown name). Fail-soft: a bad registry
 * yields null, never an exception.
 */
function resolveRegistryProvider(
  rawProvider: string | null,
  vault: string | null,
  env: NodeJS.ProcessEnv,
): ExpandedProvider | null {
  if (rawProvider === null || BUILTIN_PROVIDERS.has(rawProvider)) return null;
  try {
    // The vault's custody store joins the probe (store first, reference-
    // shaped probe entries resolved) so a registered provider's key can
    // live in the store; without it the probe reads env exactly as before.
    return expandRegisteredProvider(
      rawProvider,
      loadProviderRegistry(vault),
      env,
      vault === null ? {} : { secretsVault: vault },
    );
  } catch (err) {
    // The resolver's named refusals are ANSWERS, not expansion misses: a
    // locked store, a missing keyfile, or a malformed reference in a probe
    // entry surfaces by name, because swallowing it here returned null and
    // made `parseProvider` claim "not a registered provider" for a name that
    // IS registered - with the implied remedy (fix the name) wrong. Only
    // a genuinely broken registry file stays fail-soft.
    if (
      err instanceof SecretStoreLockedError ||
      err instanceof SecretStoreKeyfileMissingError ||
      err instanceof SecretReferenceError
    ) {
      throw err;
    }
    return null;
  }
}

/**
 * Resolve one credential VALUE read from env or config for `vault`: a
 * `$secret:NAME` reference resolves through the custody store (store
 * first, env fallback), surfacing the same named locked/reference
 * refusals the registry probe beside it raises; any other value passes
 * through untouched, byte-identical to the pre-routing read. This is the
 * routing the explicit `embedding_api_key` read and the cross-encoder
 * rerank env-key read go through, so every key inside one resolved
 * config resolves by one rule.
 */
function resolveCredentialValue(vault: string | null, value: string | null): string | null {
  if (value === null || !isSecretReferenceValue(value)) return value;
  return resolveNamedSecret(vault, value.trim());
}

/**
 * The names `search check` hands the credential-source report: the
 * registered profile `embedding_provider` selects (by the same env-over-
 * config rule and registry lookup {@link resolveSearchConfig} expands),
 * the vault's registry and the env. Fail-soft like the expansion itself:
 * `loadProviderRegistry` reads a missing or malformed registry as an empty
 * one, so the report names exactly the profiles the resolver can see, and a
 * name the registry does not hold is no profile.
 */
export function resolveCredentialContext(opts: {
  vault: string | null;
  configPath?: string;
  env?: NodeJS.ProcessEnv;
}): CredentialSourceContext {
  const env = opts.env ?? process.env;
  const config: Readonly<Record<string, string>> = opts.configPath
    ? discoverConfig(opts.configPath).data
    : {};
  const rawProvider = envOrConfig(
    env,
    config,
    "OPEN_SECOND_BRAIN_EMBEDDING_PROVIDER",
    "embedding_provider",
  );
  const registry: ReadonlyArray<ProviderProfile> = loadProviderRegistry(opts.vault);
  const activeProfile =
    rawProvider !== null &&
    !BUILTIN_PROVIDERS.has(rawProvider) &&
    registry.some((p) => p.name === rawProvider)
      ? rawProvider
      : null;
  return Object.freeze({ activeProfile, registry, env });
}

export function resolveSearchConfig(opts: {
  /** The vault, or `null` with no vault: the index then holds the brain store only (D14). */
  vault: string | null;
  configPath?: string;
  overrides?: SearchConfigOverrides;
}): ResolvedSearchConfig {
  const env = process.env;
  const config: Readonly<Record<string, string>> = opts.configPath
    ? discoverConfig(opts.configPath).data
    : {};

  // The brain store the index catches up from, when one is in use; the
  // index then lives in the store's device-local state (design D5).
  const storeProbe = resolveIndexedStoreProbe({
    vault: opts.vault,
    config,
    configPath: opts.configPath ?? null,
  });
  const brainStore = storeProbe.kind === "store" ? storeProbe.store : null;
  // An `unknown` probe keeps the store index this machine last wrote.
  const dbPath = resolveIndexPathForProbe(
    opts.vault,
    envOrConfig(env, config, SEARCH_DB_ENV, SEARCH_DB_CONFIG_KEY),
    storeProbe,
  );

  const chunkSize = parseInteger(
    envOrConfig(env, config, "OPEN_SECOND_BRAIN_SEARCH_CHUNK_SIZE", "search_chunk_size"),
    DEFAULTS.chunkSize,
    "search_chunk_size",
    { min: 1 },
  );
  const chunkOverlap = parseInteger(
    envOrConfig(env, config, "OPEN_SECOND_BRAIN_SEARCH_CHUNK_OVERLAP", "search_chunk_overlap"),
    DEFAULTS.chunkOverlap,
    "search_chunk_overlap",
    { min: 0 },
  );
  const chunkMinSize = parseInteger(
    envOrConfig(env, config, "OPEN_SECOND_BRAIN_SEARCH_CHUNK_MIN_SIZE", "search_chunk_min_size"),
    DEFAULTS.chunkMinSize,
    "search_chunk_min_size",
    { min: 1 },
  );
  const keywordWeight = parseFloat01(
    envOrConfig(env, config, "OPEN_SECOND_BRAIN_SEARCH_KW_WEIGHT", "search_keyword_weight"),
    DEFAULTS.keywordWeight,
    "search_keyword_weight",
  );
  const semanticWeight = parseFloat01(
    envOrConfig(env, config, "OPEN_SECOND_BRAIN_SEARCH_SEM_WEIGHT", "search_semantic_weight"),
    DEFAULTS.semanticWeight,
    "search_semantic_weight",
  );
  const fusionMode = parseFusionMode(
    envOrConfig(env, config, "OPEN_SECOND_BRAIN_SEARCH_FUSION_MODE", "search_fusion_mode"),
  );
  const rrfK = parseInteger(
    envOrConfig(env, config, "OPEN_SECOND_BRAIN_SEARCH_RRF_K", "search_rrf_k"),
    DEFAULTS.rrfK,
    "search_rrf_k",
    { min: 1 },
  );

  // v0.10.9: single source of truth lives in Brain/_brain.yaml under
  // `vault.ignore_paths`. The legacy `search_ignore_paths` config key
  // and `OPEN_SECOND_BRAIN_SEARCH_IGNORE` env variable were removed.
  const scope = resolveVaultScope(opts.vault);
  const scopeRules = scope.rules;

  const semanticEnabled = parseBool(
    envOrConfig(env, config, "OPEN_SECOND_BRAIN_SEARCH_SEMANTIC", "search_semantic_enabled"),
    false,
    "search_semantic_enabled",
  );
  const rawProvider = envOrConfig(
    env,
    config,
    "OPEN_SECOND_BRAIN_EMBEDDING_PROVIDER",
    "embedding_provider",
  );
  // A provider name that is not a built-in is looked up in the registry
  // AFTER the built-ins, so it never shadows an explicitly configured
  // built-in. A registered name resolves to openai-compat fields; an
  // unknown name falls through to parseProvider's clear validation error.
  const registryExpansion = resolveRegistryProvider(rawProvider, opts.vault, env);
  const provider = registryExpansion ? "openai-compat" : parseProvider(rawProvider);
  const explicitBaseUrl = envOrConfig(
    env,
    config,
    "OPEN_SECOND_BRAIN_EMBEDDING_BASE_URL",
    "embedding_base_url",
  );
  const explicitModel = envOrConfig(
    env,
    config,
    "OPEN_SECOND_BRAIN_EMBEDDING_MODEL",
    "embedding_model",
  );
  const explicitApiKey = resolveCredentialValue(
    opts.vault,
    envOrConfig(env, config, EMBEDDING_KEY_ENV, EMBEDDING_KEY_CONFIG),
  );
  // Explicit config/env always wins over the registry profile's fields.
  const baseUrl = explicitBaseUrl ?? registryExpansion?.baseUrl ?? null;
  // The plain-http opt-out binds to the URL the operator wrote down: the
  // registry file lives inside the vault, so a URL it supplies never
  // inherits an opt-out granted in config.
  const embeddingAllowInsecureHttp =
    parseBool(
      envOrConfig(
        env,
        config,
        "OPEN_SECOND_BRAIN_EMBEDDING_ALLOW_INSECURE_HTTP",
        "embedding_allow_insecure_http",
      ),
      false,
      "embedding_allow_insecure_http",
    ) && explicitBaseUrl !== null;
  const model = explicitModel ?? registryExpansion?.model ?? null;
  const apiKey = explicitApiKey ?? registryExpansion?.apiKey ?? null;
  // Multi-key failover list: an explicit key is single-valued; otherwise
  // use the registry profile's ordered probe list. Empty when no key.
  const apiKeys: ReadonlyArray<string> = explicitApiKey
    ? [explicitApiKey]
    : (registryExpansion?.apiKeys ?? (apiKey ? [apiKey] : []));
  const dimRaw = envOrConfig(
    env,
    config,
    "OPEN_SECOND_BRAIN_EMBEDDING_DIM",
    EMBEDDING_DIMENSION_KEY,
  );
  const dimension =
    dimRaw === null ? null : parseInteger(dimRaw, 0, EMBEDDING_DIMENSION_KEY, { min: 1 });
  const timeoutMs = parseInteger(
    envOrConfig(env, config, "OPEN_SECOND_BRAIN_EMBEDDING_TIMEOUT", "embedding_timeout_ms"),
    DEFAULTS.timeoutMs,
    "embedding_timeout_ms",
    { min: 1 },
  );
  // Composite hybrid deadline (t_bdc24171): one wall-clock budget over
  // embed -> semanticTopK -> rerank -> second pass, defaulting to the sum
  // of the two lane budgets above/below. The range starts at 0, unlike the
  // per-lane timeouts, because 0 is the documented off switch - a budget
  // of zero is not "expire immediately", it is "no composite deadline".
  const hybridDeadlineMs = parseInteger(
    envOrConfig(
      env,
      config,
      "OPEN_SECOND_BRAIN_SEARCH_HYBRID_DEADLINE",
      "search_hybrid_deadline_ms",
    ),
    DEFAULT_HYBRID_DEADLINE_MS,
    "search_hybrid_deadline_ms",
    { min: 0 },
  );
  const concurrency = parseInteger(
    envOrConfig(env, config, "OPEN_SECOND_BRAIN_EMBEDDING_CONCURRENCY", "embedding_concurrency"),
    DEFAULTS.concurrency,
    "embedding_concurrency",
    { min: 1 },
  );
  const batchSize = parseInteger(
    envOrConfig(env, config, "OPEN_SECOND_BRAIN_EMBEDDING_BATCH", "embedding_batch_size"),
    DEFAULTS.batchSize,
    "embedding_batch_size",
    { min: 1 },
  );
  // Per-request token budget. No DEFAULTS entry, because there is no
  // provider-independent ceiling to default to and an absent key must stay
  // absent: the providers read `undefined` as "count cap only", which is
  // byte-identical to the pre-feature fixed stride.
  const batchTokensRaw = envOrConfig(
    env,
    config,
    "OPEN_SECOND_BRAIN_EMBEDDING_BATCH_TOKENS",
    "embedding_batch_tokens",
  );
  const batchTokens =
    batchTokensRaw === null
      ? null
      : parseInteger(batchTokensRaw, 0, "embedding_batch_tokens", { min: 1 });
  // The declared input window of an uncurated model. Read with raw
  // presence, not `envOrConfig`, so a blank value is refused rather than
  // folded into "unset": an operator who wrote the key meant a window.
  const inputWindowTokensRaw = rawSetting(
    env,
    config,
    "OPEN_SECOND_BRAIN_EMBEDDING_INPUT_WINDOW_TOKENS",
    INPUT_WINDOW_TOKENS_KEY,
  );
  const inputWindowTokens =
    inputWindowTokensRaw === null
      ? null
      : parseInteger(inputWindowTokensRaw, 0, INPUT_WINDOW_TOKENS_KEY, { min: 1 });
  const maxRetries = parseInteger(
    envOrConfig(env, config, "OPEN_SECOND_BRAIN_EMBEDDING_MAX_RETRIES", "embedding_max_retries"),
    DEFAULTS.maxRetries,
    "embedding_max_retries",
    { min: 1 },
  );
  const costGateUsd = parseNonNegativeFloat(
    envOrConfig(env, config, "OPEN_SECOND_BRAIN_EMBEDDING_COST_GATE", "embedding_cost_gate_usd"),
    DEFAULTS.costGateUsd,
    "embedding_cost_gate_usd",
  );
  const priceOverride = resolveEmbeddingPriceOverride(env, config);
  const extraBody = resolveEmbeddingExtraBody(env, config);

  // Instruction prefixes (memory-write-path-integrity B2). Resolved with raw
  // presence, not `envOrConfig`, because an explicit empty string must DISABLE
  // a preset prefix rather than fall through to the default. An absent key
  // (null) falls through to the preset / structural e5 default.
  const { queryPrefix, passagePrefix } = resolveEmbeddingPrefixes(
    model,
    rawSetting(env, config, "OPEN_SECOND_BRAIN_EMBEDDING_PREFIX_QUERY", "embedding_prefix_query"),
    rawSetting(
      env,
      config,
      "OPEN_SECOND_BRAIN_EMBEDDING_PREFIX_PASSAGE",
      "embedding_prefix_passage",
    ),
  );

  const semantic: ResolvedEmbeddingConfig = Object.freeze({
    enabled: semanticEnabled,
    provider,
    baseUrl,
    model,
    apiKey,
    apiKeys: Object.freeze(apiKeys),
    ...(embeddingAllowInsecureHttp ? { allowInsecureHttp: true } : {}),
    dimension,
    timeoutMs,
    concurrency,
    batchSize,
    ...(batchTokens === null ? {} : { batchTokens }),
    ...(inputWindowTokens === null ? {} : { inputWindowTokens }),
    maxRetries,
    costGateUsd,
    ...(priceOverride === null ? {} : { priceOverride }),
    queryPrefix,
    passagePrefix,
    ...(extraBody === null ? {} : { extraBody }),
  });

  // Cross-encoder rerank (retrieval-precision-quality-loop, card A). Off
  // by default; when off the reader tail is byte-identical. A registered
  // provider name (`search_rerank_provider`) supplies base_url / model /
  // env-key defaults; explicit `search_rerank_*` config/env always wins.
  const rerankEnabled = parseBool(
    envOrConfig(env, config, "OPEN_SECOND_BRAIN_SEARCH_RERANK_ENABLED", "search_rerank_enabled"),
    false,
    "search_rerank_enabled",
  );
  const rerankProviderName = envOrConfig(
    env,
    config,
    "OPEN_SECOND_BRAIN_SEARCH_RERANK_PROVIDER",
    "search_rerank_provider",
  );
  const rerankProfile =
    rerankProviderName !== null
      ? expandRegisteredRerankProvider(rerankProviderName, loadRerankRegistry(opts.vault))
      : null;
  const explicitRerankBaseUrl = envOrConfig(
    env,
    config,
    "OPEN_SECOND_BRAIN_SEARCH_RERANK_BASE_URL",
    "search_rerank_base_url",
  );
  const rerankBaseUrl = explicitRerankBaseUrl ?? rerankProfile?.baseUrl ?? null;
  // Same binding as the embedding opt-out: a registry-supplied URL never
  // inherits it.
  const rerankAllowInsecureHttp =
    parseBool(
      envOrConfig(
        env,
        config,
        "OPEN_SECOND_BRAIN_SEARCH_RERANK_ALLOW_INSECURE_HTTP",
        "search_rerank_allow_insecure_http",
      ),
      false,
      "search_rerank_allow_insecure_http",
    ) && explicitRerankBaseUrl !== null;
  const rerankModel =
    envOrConfig(env, config, "OPEN_SECOND_BRAIN_SEARCH_RERANK_MODEL", "search_rerank_model") ??
    rerankProfile?.model ??
    null;
  const rerankEnvKey =
    envOrConfig(env, config, "OPEN_SECOND_BRAIN_SEARCH_RERANK_ENV_KEY", "search_rerank_env_key") ??
    rerankProfile?.envKey ??
    null;
  // Routed through the same value resolver as the explicit embedding key:
  // a reference-shaped env value resolves through the custody store, a
  // plain value passes byte-identically.
  const rerankApiKey = resolveCredentialValue(
    opts.vault,
    rerankEnvKey !== null ? (env[rerankEnvKey] ?? null) : null,
  );
  const rerankTopK = parseInteger(
    envOrConfig(env, config, "OPEN_SECOND_BRAIN_SEARCH_RERANK_TOP_K", "search_rerank_top_k"),
    DEFAULTS.rerankTopK,
    "search_rerank_top_k",
    { min: 1 },
  );
  const rerankMinScore = parseFiniteFloat(
    envOrConfig(
      env,
      config,
      "OPEN_SECOND_BRAIN_SEARCH_RERANK_MIN_SCORE",
      "search_rerank_min_score",
    ),
    DEFAULTS.rerankMinScore,
    "search_rerank_min_score",
  );
  // Relational rerank pin (t_d9f863e9). Off by default: the cross-encoder
  // is the last word on ordering as shipped. When true, the rerank may
  // promote relational-origin candidates but never sink them below their
  // pre-rerank heuristic order - enforced at the hand-off in the pipeline,
  // with `search_rerank_min_score` still applying unchanged.
  const relationalRerankPin = parseBool(
    envOrConfig(
      env,
      config,
      "OPEN_SECOND_BRAIN_SEARCH_RELATIONAL_RERANK_PIN",
      "search_relational_rerank_pin",
    ),
    false,
    "search_relational_rerank_pin",
  );
  const rerankKindRaw = envOrConfig(
    env,
    config,
    "OPEN_SECOND_BRAIN_SEARCH_RERANK_KIND",
    "search_rerank_kind",
  );
  if (
    rerankKindRaw !== null &&
    rerankKindRaw !== "openai-compat" &&
    rerankKindRaw !== "local" &&
    rerankKindRaw !== "decision-model"
  ) {
    throw new SearchError(
      "INVALID_INPUT",
      `search_rerank_kind must be 'openai-compat', 'local' or 'decision-model', got '${rerankKindRaw}'`,
    );
  }
  const rerankKind =
    rerankKindRaw === "local" || rerankKindRaw === "decision-model"
      ? rerankKindRaw
      : "openai-compat";
  // The decision-model kind reuses the core decision config. It is resolved
  // only for this kind, and it never throws: anything short of an active
  // config with a non-`off` rerank use leaves the stage disabled, which is
  // byte-identical to rerank off (no request, no record, no warning).
  const rerankDecisionModel =
    rerankKind === "decision-model"
      ? resolveDecisionModelConfig({ env, config, vault: opts.vault })
      : null;
  const rerankEffectiveEnabled =
    rerankDecisionModel === null
      ? rerankEnabled
      : rerankEnabled && decisionModelModeFor(rerankDecisionModel, "rerank") !== "off";
  const rerank: ResolvedRerankConfig = Object.freeze({
    enabled: rerankEffectiveEnabled,
    kind: rerankKind,
    baseUrl: rerankBaseUrl,
    model: rerankModel,
    envKey: rerankEnvKey,
    apiKey: rerankApiKey !== null && rerankApiKey !== "" ? rerankApiKey : null,
    ...(rerankAllowInsecureHttp ? { allowInsecureHttp: true } : {}),
    topK: rerankTopK,
    minScore: rerankMinScore,
    // Absent reads as off, matching this block's other opt-outs: the field
    // is optional so configs written before the knob stay valid, and the
    // exact-shape assertions on the resolved config keep holding.
    ...(relationalRerankPin ? { relationalRerankPin: true } : {}),
    ...(rerankDecisionModel !== null ? { decisionModel: rerankDecisionModel } : {}),
  });

  const mmrLambda = parseFloat01(
    envOrConfig(env, config, "OPEN_SECOND_BRAIN_SEARCH_MMR_LAMBDA", "search_mmr_lambda"),
    DEFAULTS.mmrLambda,
    "search_mmr_lambda",
  );
  const maxHops = parseInteger(
    envOrConfig(env, config, "OPEN_SECOND_BRAIN_SEARCH_MAX_HOPS", "search_max_hops"),
    DEFAULTS.maxHops,
    "search_max_hops",
    { min: 0 },
  );
  const hopDecay = parseFloat01(
    envOrConfig(env, config, "OPEN_SECOND_BRAIN_SEARCH_HOP_DECAY", "search_hop_decay"),
    DEFAULTS.hopDecay,
    "search_hop_decay",
  );
  const maxExpansionPerHit = parseInteger(
    envOrConfig(
      env,
      config,
      "OPEN_SECOND_BRAIN_SEARCH_MAX_EXPANSION_PER_HIT",
      "search_max_expansion_per_hit",
    ),
    DEFAULTS.maxExpansionPerHit,
    "search_max_expansion_per_hit",
    { min: 0 },
  );
  const recencyShape = parsePositiveFloat(
    envOrConfig(env, config, "OPEN_SECOND_BRAIN_SEARCH_RECENCY_SHAPE", "search_recency_shape"),
    DEFAULTS.recencyShape,
    "search_recency_shape",
  );
  const recencyScale = parsePositiveFloat(
    envOrConfig(env, config, "OPEN_SECOND_BRAIN_SEARCH_RECENCY_SCALE", "search_recency_scale"),
    DEFAULTS.recencyScale,
    "search_recency_scale",
  );
  const recencyAmplitude = parseFloat01(
    envOrConfig(
      env,
      config,
      "OPEN_SECOND_BRAIN_SEARCH_RECENCY_AMPLITUDE",
      "search_recency_amplitude",
    ),
    DEFAULTS.recencyAmplitude,
    "search_recency_amplitude",
  );
  const intentEnabled = parseBool(
    envOrConfig(env, config, "OPEN_SECOND_BRAIN_SEARCH_INTENT_ENABLED", "search_intent_enabled"),
    true,
    "search_intent_enabled",
  );
  const synonymEnabled = parseBool(
    envOrConfig(env, config, "OPEN_SECOND_BRAIN_SEARCH_SYNONYM_ENABLED", "search_synonym_enabled"),
    false,
    "search_synonym_enabled",
  );
  const synonymMaxTerms = parseInteger(
    envOrConfig(
      env,
      config,
      "OPEN_SECOND_BRAIN_SEARCH_SYNONYM_MAX_TERMS",
      "search_synonym_max_terms",
    ),
    DEFAULTS.synonymMaxTerms,
    "search_synonym_max_terms",
    { min: 0 },
  );
  const cacheEnabled = parseBool(
    envOrConfig(env, config, "OPEN_SECOND_BRAIN_SEARCH_CACHE_ENABLED", "search_cache_enabled"),
    false,
    "search_cache_enabled",
  );
  const cacheTtlSeconds = parseInteger(
    envOrConfig(env, config, "OPEN_SECOND_BRAIN_SEARCH_CACHE_TTL", "search_cache_ttl_seconds"),
    DEFAULTS.cacheTtlSeconds,
    "search_cache_ttl_seconds",
    { min: 1 },
  );
  const relationPolarityEnabled = parseBool(
    envOrConfig(
      env,
      config,
      "OPEN_SECOND_BRAIN_SEARCH_RELATION_POLARITY",
      "search_relation_polarity_enabled",
    ),
    true,
    "search_relation_polarity_enabled",
  );
  const relationalArmEnabled = parseBool(
    envOrConfig(
      env,
      config,
      "OPEN_SECOND_BRAIN_SEARCH_RELATIONAL_ARM",
      "search_relational_arm_enabled",
    ),
    false,
    "search_relational_arm_enabled",
  );
  // Metadata-boost lexical-vote gate (t_d9f863e9). Off by default: additive
  // metadata/structural boosts apply to every query as shipped. When true,
  // a query whose keyword lane returned no hits contributes exactly zero
  // from those layers, with the suppression named in the rank receipts.
  const metadataBoostGateEnabled = parseBool(
    envOrConfig(
      env,
      config,
      "OPEN_SECOND_BRAIN_SEARCH_METADATA_BOOST_GATE",
      "search_metadata_boost_gate",
    ),
    false,
    "search_metadata_boost_gate",
  );
  const retrievalTrustGateEnabled = resolveSearchTrustGateLegacyEnabled({ env, config });
  // The gate's mode (session-mining-economy, t_05a0eaa4): an explicit
  // `search_trust_gate_mode` wins (invalid values refused naming the key
  // in force, `parseFusionMode` discipline), else the legacy boolean
  // above maps true to enforce - the excluding behavior it always had -
  // and false to off. A bad legacy boolean is refused above, naming the
  // key in force.
  const searchTrustGateMode = resolveSearchTrustGateMode({ env, config });
  const supersedeFadeEnabled = parseBool(
    envOrConfig(
      env,
      config,
      "OPEN_SECOND_BRAIN_SEARCH_SUPERSEDE_FADE",
      "search_supersede_fade_enabled",
    ),
    false,
    "search_supersede_fade_enabled",
  );
  const learnedWeightsEnabled = parseBool(
    envOrConfig(
      env,
      config,
      "OPEN_SECOND_BRAIN_SEARCH_LEARNED_WEIGHTS",
      "search_learned_weights_enabled",
    ),
    false,
    "search_learned_weights_enabled",
  );
  const activationEnabled = parseBool(
    envOrConfig(env, config, "OPEN_SECOND_BRAIN_SEARCH_ACTIVATION", "search_activation_enabled"),
    true,
    "search_activation_enabled",
  );
  const twoPassEnabled = parseBool(
    envOrConfig(env, config, "OPEN_SECOND_BRAIN_SEARCH_TWO_PASS", "search_two_pass_enabled"),
    true,
    "search_two_pass_enabled",
  );
  const iterativeRecallEnabled = parseBool(
    envOrConfig(
      env,
      config,
      "OPEN_SECOND_BRAIN_SEARCH_ITERATIVE",
      "search_iterative_recall_enabled",
    ),
    false,
    "search_iterative_recall_enabled",
  );
  const iterativeRecallMaxRounds = parseInteger(
    envOrConfig(
      env,
      config,
      "OPEN_SECOND_BRAIN_SEARCH_ITERATIVE_MAX_ROUNDS",
      "search_iterative_recall_max_rounds",
    ),
    ITERATIVE_RECALL_MAX_ROUNDS_DEFAULT,
    "search_iterative_recall_max_rounds",
    { min: 1, max: ITERATIVE_RECALL_MAX_ROUNDS_CAP },
  );
  const poolMultiplier = parseInteger(
    envOrConfig(env, config, "OPEN_SECOND_BRAIN_SEARCH_POOL_MULTIPLIER", "search_pool_multiplier"),
    3,
    "search_pool_multiplier",
    { min: 1, max: 10 },
  );
  // Per-source-session pool cap (t_bb6ce095). No parse-time range: the
  // integer-range line in `validateResolvedConfig` owns the refusal of
  // config values, and a per-query override is judged by the same rules
  // (finite, integer, >= 0) at the assembly's read site
  // (`resolveSessionPoolCap`).
  const poolMaxPerSession = parseInteger(
    envOrConfig(
      env,
      config,
      "OPEN_SECOND_BRAIN_SEARCH_POOL_MAX_PER_SESSION",
      "search_pool_max_per_session",
    ),
    DEFAULTS.poolMaxPerSession,
    "search_pool_max_per_session",
  );
  const selfTuningEnabled = parseBool(
    envOrConfig(env, config, "OPEN_SECOND_BRAIN_SEARCH_SELF_TUNING", "search_self_tuning_enabled"),
    false,
    "search_self_tuning_enabled",
  );
  const chainStopEnabled = parseBool(
    envOrConfig(env, config, "OPEN_SECOND_BRAIN_SEARCH_CHAIN_STOP", "search_chain_stop_enabled"),
    false,
    "search_chain_stop_enabled",
  );
  const chainStopScore = parseFloat01(
    envOrConfig(
      env,
      config,
      "OPEN_SECOND_BRAIN_SEARCH_CHAIN_STOP_SCORE",
      "search_chain_stop_score",
    ),
    DEFAULTS.chainStopScore,
    "search_chain_stop_score",
  );
  const trigramPrefilterEnabled = parseBool(
    envOrConfig(
      env,
      config,
      "OPEN_SECOND_BRAIN_SEARCH_TRIGRAM_PREFILTER",
      "search_trigram_prefilter_enabled",
    ),
    DEFAULTS.trigramPrefilterEnabled,
    "search_trigram_prefilter_enabled",
  );
  const trigramPrefilterMinChunks = parseInteger(
    envOrConfig(
      env,
      config,
      "OPEN_SECOND_BRAIN_SEARCH_TRIGRAM_MIN_CHUNKS",
      "search_trigram_prefilter_min_chunks",
    ),
    DEFAULTS.trigramPrefilterMinChunks,
    "search_trigram_prefilter_min_chunks",
    { min: 0 },
  );
  const trigramPrefilterMaxSelectivity = parseFloat01(
    envOrConfig(
      env,
      config,
      "OPEN_SECOND_BRAIN_SEARCH_TRIGRAM_MAX_SELECTIVITY",
      "search_trigram_prefilter_max_selectivity",
    ),
    DEFAULTS.trigramPrefilterMaxSelectivity,
    "search_trigram_prefilter_max_selectivity",
  );
  const shutdownGraceSeconds = parseInteger(
    envOrConfig(
      env,
      config,
      "OPEN_SECOND_BRAIN_SEARCH_SHUTDOWN_GRACE",
      "search_shutdown_grace_seconds",
    ),
    DEFAULTS.shutdownGraceSeconds,
    "search_shutdown_grace_seconds",
    { min: 0 },
  );
  const resumeReindex = parseBool(
    envOrConfig(env, config, "OPEN_SECOND_BRAIN_SEARCH_RESUME_REINDEX", "search_resume_reindex"),
    DEFAULTS.resumeReindex,
    "search_resume_reindex",
  );
  // Configurable FTS tokenizer (t_618f7211). Both keys default to null,
  // which yields the byte-identical `unicode61 remove_diacritics 2`
  // clause; an out-of-range value throws SearchError("INVALID_INPUT")
  // here rather than reaching the DDL. Changing either key takes effect
  // only after `o2b search reindex`; there is no implicit reindex.
  const ftsTokenize = buildFtsTokenize({
    diacritics: rawSetting(
      env,
      config,
      "OPEN_SECOND_BRAIN_SEARCH_FTS_DIACRITICS",
      "search_fts_diacritics",
    ),
    stemmer: rawSetting(env, config, "OPEN_SECOND_BRAIN_SEARCH_FTS_STEMMER", "search_fts_stemmer"),
  });
  const recall: ResolvedRecallConfig = Object.freeze({
    mmrLambda,
    maxHops,
    hopDecay,
    maxExpansionPerHit,
    recencyShape,
    recencyScale,
    recencyAmplitude,
    intentEnabled,
    synonymEnabled,
    synonymMaxTerms,
    cacheEnabled,
    cacheTtlSeconds,
    relationPolarityEnabled,
    relationalArmEnabled,
    metadataBoostGateEnabled,
    retrievalTrustGateEnabled,
    // Only the off value stays absent (the relationalRerankPin pattern),
    // so exact-shape assertions on the resolved config keep holding.
    ...(searchTrustGateMode !== SEARCH_TRUST_GATE_MODE.off ? { searchTrustGateMode } : {}),
    supersedeFadeEnabled,
    learnedWeightsEnabled,
    activationEnabled,
    twoPassEnabled,
    iterativeRecallEnabled,
    iterativeRecallMaxRounds,
    poolMultiplier,
    selfTuningEnabled,
    chainStopEnabled,
    chainStopScore,
    trigramPrefilterEnabled,
    trigramPrefilterMinChunks,
    trigramPrefilterMaxSelectivity,
    // Only the off value stays absent, so exact-shape assertions on the
    // resolved config keep holding - the relationalRerankPin pattern. A
    // negative value is spread through so `validateResolvedConfig` owns
    // its refusal, exactly as it judges a programmatic override.
    ...(poolMaxPerSession !== DEFAULTS.poolMaxPerSession ? { poolMaxPerSession } : {}),
  });

  const freshen: ResolvedFreshenConfig = Object.freeze({
    intervalSeconds: parseInteger(
      envOrConfig(
        env,
        config,
        "OPEN_SECOND_BRAIN_SEARCH_FRESHEN_INTERVAL_S",
        "search_freshen_interval_s",
      ),
      60,
      "search_freshen_interval_s",
      { min: 0 },
    ),
    embeddings: parseBool(
      envOrConfig(
        env,
        config,
        "OPEN_SECOND_BRAIN_SEARCH_FRESHEN_EMBEDDINGS",
        "search_freshen_embeddings",
      ),
      false,
      "search_freshen_embeddings",
    ),
    configPath: opts.configPath ?? null,
  });

  const base: ResolvedSearchConfig = Object.freeze({
    vault: opts.vault,
    dbPath,
    brainStore,
    ...(storeProbe.kind === "unknown" ? { brainStoreUnknown: true } : {}),
    configPath: opts.configPath ?? null,
    scopeRules,
    chunkSize,
    chunkOverlap,
    chunkMinSize,
    keywordWeight,
    semanticWeight,
    fusionMode,
    rrfK,
    semantic,
    recall,
    rerank,
    shutdownGraceMs: shutdownGraceSeconds * 1000,
    resumeReindex,
    hybridDeadlineMs,
    ftsTokenize,
    freshen,
  });

  // The env variable names an extra-body refusal only when its value is
  // the one in force, by the same raw-presence rule the parser used.
  const extraBodySource =
    opts.overrides?.semantic?.extraBody === undefined && env[EXTRA_BODY_ENV] !== undefined
      ? EXTRA_BODY_ENV
      : EXTRA_BODY_KEY;
  if (!opts.overrides) {
    validateResolvedConfig(base, extraBodySource);
    return base;
  }
  const merged = Object.freeze({
    ...base,
    ...opts.overrides,
    semantic: Object.freeze({ ...base.semantic, ...opts.overrides.semantic }),
    rerank: Object.freeze({ ...base.rerank, ...opts.overrides.rerank }),
    scopeRules: opts.overrides.scopeRules
      ? Object.freeze({ ...opts.overrides.scopeRules })
      : base.scopeRules,
  });
  validateResolvedConfig(merged, extraBodySource);
  return merged;
}