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
/**
* 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;
}