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
refactor: DRY and decomposition (Phases 0-2) (#121)
Sol Aitken67bcb71cff75
diff --git a/.gitignore b/.gitignoreindex dc3ffd1b..c1cf3069 100644--- a/.gitignore+++ b/.gitignore@@ -29,3 +29,4 @@ sandbox-vault/# Local Kanban/git worktrees (never committed; exclude from lint/fmt).worktrees/+.code-ranker/diff --git a/src/cli/brain/verbs/morning-brief.ts b/src/cli/brain/verbs/morning-brief.tsindex 59534d70..d1181854 100644--- a/src/cli/brain/verbs/morning-brief.ts+++ b/src/cli/brain/verbs/morning-brief.ts@@ -25,7 +25,7 @@ export async function cmdBrainMorningBrief(argv: string[]): Promise<number> {const { config, vault } = brainVerbContext(flags);// Positive-integer validation mirroring the MCP tool's- // optionalPositiveInt, so the CLI and MCP surfaces share semantics.+ // coercePositiveInteger, so the CLI and MCP surfaces share semantics.const positiveInt = (name: string): { value: number | null; error: string | null } => {const parsed = parseOptionalNumberFlag(flags, name);if (parsed.error) return parsed;diff --git a/src/cli/search.ts b/src/cli/search.tsindex 0b1ec926..0cf219dd 100644--- a/src/cli/search.ts+++ b/src/cli/search.ts@@ -49,6 +49,11 @@ import {addRerankProviderProfile,removeRerankProviderProfile,getRerankProviderProfile,+ serializeEvidencePack,+ serializeSearchCard,+ serializeIndexStatus,+ SEARCH_LIMIT_MIN,+ SEARCH_LIMIT_MAX,} from "../core/search/index.ts";import type {IndexCheckReport,@@ -341,11 +346,43 @@ function formatLearnedWeights(w: LearnedWeights): string {// βββ provider registry (Embedding Provider Suite) ββββββββββββββββββββββββββββ-async function cmdSearchProvider(argv: ReadonlyArray<string>): Promise<number> {+/** Structural shape shared by `ProviderProfile` and `RerankProviderProfile`. */+interface CliRegistryProfile {+ readonly name: string;+ readonly baseUrl: string;+ readonly defaultModel: string;+ readonly envKey: string;+}++/**+ * CRUD operations a provider-style registry exposes to the CLI, plus the+ * naming used in usage/output strings. `verb` is the CLI subcommand name+ * (`provider` / `rerank-provider`); `kind` is the human noun used in prose+ * (`provider` / `rerank provider`).+ */+interface ProviderRegistryOps<T extends CliRegistryProfile> {+ readonly verb: string;+ readonly kind: string;+ readonly load: (vault: string) => ReadonlyArray<T>;+ readonly get: (vault: string, name: string) => T | null;+ readonly add: (vault: string, profile: CliRegistryProfile) => ReadonlyArray<T>;+ readonly remove: (vault: string, name: string) => { removed: boolean };+}++/**+ * Shared `add|list|show|remove` dispatch for the provider and rerank-provider+ * registries (retrieval-precision-quality-loop, card A) - identical CRUD+ * shape over two structurally identical profile registries.+ */+async function runProviderRegistryCommand<T extends CliRegistryProfile>(+ argv: ReadonlyArray<string>,+ ops: ProviderRegistryOps<T>,+): Promise<number> {+ const { verb, kind } = ops;const action = argv[0];if (!action || !["add", "list", "show", "remove"].includes(action)) {throw new CliError(- "usage: o2b search provider <add NAME --base-url U --model M --env-key K | list | show NAME | remove NAME> [--json]",+ `usage: o2b search ${verb} <add NAME --base-url U --model M --env-key K | list | show NAME | remove NAME> [--json]`,);}const { flags, positional } = parseFlags(argv.slice(1), {@@ -362,13 +399,13 @@ async function cmdSearchProvider(argv: ReadonlyArray<string>): Promise<number> {const name = typeof positional[0] === "string" ? positional[0] : undefined;if (action === "list") {- const registry = loadProviderRegistry(cfg.vault);+ const registry = ops.load(cfg.vault);if (json) {process.stdout.write(JSON.stringify(registry) + "\n");return 0;}if (registry.length === 0) {- process.stdout.write("no registered providers\n");+ process.stdout.write(`no registered ${kind}s\n`);return 0;}for (const p of registry) {@@ -378,10 +415,10 @@ async function cmdSearchProvider(argv: ReadonlyArray<string>): Promise<number> {}if (action === "show") {- if (!name) throw new CliError("usage: o2b search provider show NAME");- const profile = getProviderProfile(cfg.vault, name);+ if (!name) throw new CliError(`usage: o2b search ${verb} show NAME`);+ const profile = ops.get(cfg.vault, name);if (!profile) {- process.stderr.write(`error: no registered provider named '${name}'\n`);+ process.stderr.write(`error: no registered ${kind} named '${name}'\n`);return 1;}process.stdout.write(@@ -393,135 +430,61 @@ async function cmdSearchProvider(argv: ReadonlyArray<string>): Promise<number> {}if (action === "remove") {- if (!name) throw new CliError("usage: o2b search provider remove NAME");- const { removed } = removeProviderProfile(cfg.vault, name);+ if (!name) throw new CliError(`usage: o2b search ${verb} remove NAME`);+ const { removed } = ops.remove(cfg.vault, name);if (json) {process.stdout.write(JSON.stringify({ removed, name }) + "\n");} else {- process.stdout.write(- removed ? `removed provider '${name}'\n` : `no such provider '${name}'\n`,- );+ process.stdout.write(removed ? `removed ${kind} '${name}'\n` : `no such ${kind} '${name}'\n`);}return removed ? 0 : 1;}// addif (!name)- throw new CliError("usage: o2b search provider add NAME --base-url U --model M --env-key K");+ throw new CliError(`usage: o2b search ${verb} add NAME --base-url U --model M --env-key K`);const baseUrl = typeof flags["base-url"] === "string" ? (flags["base-url"] as string) : undefined;const model = typeof flags["model"] === "string" ? (flags["model"] as string) : undefined;const envKey = typeof flags["env-key"] === "string" ? (flags["env-key"] as string) : undefined;if (!baseUrl || !model || !envKey) {throw new CliError(- "provider add requires --base-url, --model, and --env-key (the env var NAME holding the API key)",+ `${verb} add requires --base-url, --model, and --env-key (the env var NAME holding the API key)`,);}- const registry = addProviderProfile(cfg.vault, { name, baseUrl, defaultModel: model, envKey });+ const registry = ops.add(cfg.vault, { name, baseUrl, defaultModel: model, envKey });const added = registry.find((p) => p.name === name)!;if (json) {process.stdout.write(JSON.stringify(added) + "\n");} else {process.stdout.write(- `added provider '${name}' (set ${envKey} in the environment to supply its key)\n`,+ `added ${kind} '${name}' (set ${envKey} in the environment to supply its key)\n`,);}return 0;}-// βββ rerank provider registry (retrieval-precision-quality-loop, card A) βββββ--async function cmdSearchRerankProvider(argv: ReadonlyArray<string>): Promise<number> {- const action = argv[0];- if (!action || !["add", "list", "show", "remove"].includes(action)) {- throw new CliError(- "usage: o2b search rerank-provider <add NAME --base-url U --model M --env-key K | list | show NAME | remove NAME> [--json]",- );- }- const { flags, positional } = parseFlags(argv.slice(1), {- vault: { type: "string" },- config: { type: "string" },- db: { type: "string" },- "base-url": { type: "string" },- model: { type: "string" },- "env-key": { type: "string" },- json: { type: "boolean" },+async function cmdSearchProvider(argv: ReadonlyArray<string>): Promise<number> {+ return runProviderRegistryCommand(argv, {+ verb: "provider",+ kind: "provider",+ load: loadProviderRegistry,+ get: getProviderProfile,+ add: addProviderProfile,+ remove: removeProviderProfile,});- const cfg = resolveConfig(flags);- const json = flags["json"] === true;- const name = typeof positional[0] === "string" ? positional[0] : undefined;-- if (action === "list") {- const registry = loadRerankRegistry(cfg.vault);- if (json) {- process.stdout.write(JSON.stringify(registry) + "\n");- return 0;- }- if (registry.length === 0) {- process.stdout.write("no registered rerank providers\n");- return 0;- }- for (const p of registry) {- process.stdout.write(`${p.name} ${p.baseUrl} model=${p.defaultModel} env=${p.envKey}\n`);- }- return 0;- }-- if (action === "show") {- if (!name) throw new CliError("usage: o2b search rerank-provider show NAME");- const profile = getRerankProviderProfile(cfg.vault, name);- if (!profile) {- process.stderr.write(`error: no registered rerank provider named '${name}'\n`);- return 1;- }- process.stdout.write(- json- ? JSON.stringify(profile) + "\n"- : `${profile.name}\n base-url: ${profile.baseUrl}\n model: ${profile.defaultModel}\n env-key: ${profile.envKey}\n`,- );- return 0;- }+}- if (action === "remove") {- if (!name) throw new CliError("usage: o2b search rerank-provider remove NAME");- const { removed } = removeRerankProviderProfile(cfg.vault, name);- if (json) {- process.stdout.write(JSON.stringify({ removed, name }) + "\n");- } else {- process.stdout.write(- removed ? `removed rerank provider '${name}'\n` : `no such rerank provider '${name}'\n`,- );- }- return removed ? 0 : 1;- }+// βββ rerank provider registry (retrieval-precision-quality-loop, card A) βββββ- // add- if (!name)- throw new CliError(- "usage: o2b search rerank-provider add NAME --base-url U --model M --env-key K",- );- const baseUrl = typeof flags["base-url"] === "string" ? (flags["base-url"] as string) : undefined;- const model = typeof flags["model"] === "string" ? (flags["model"] as string) : undefined;- const envKey = typeof flags["env-key"] === "string" ? (flags["env-key"] as string) : undefined;- if (!baseUrl || !model || !envKey) {- throw new CliError(- "rerank-provider add requires --base-url, --model, and --env-key (the env var NAME holding the API key)",- );- }- const registry = addRerankProviderProfile(cfg.vault, {- name,- baseUrl,- defaultModel: model,- envKey,+async function cmdSearchRerankProvider(argv: ReadonlyArray<string>): Promise<number> {+ return runProviderRegistryCommand(argv, {+ verb: "rerank-provider",+ kind: "rerank provider",+ load: loadRerankRegistry,+ get: getRerankProviderProfile,+ add: addRerankProviderProfile,+ remove: removeRerankProviderProfile,});- const added = registry.find((p) => p.name === name)!;- if (json) {- process.stdout.write(JSON.stringify(added) + "\n");- } else {- process.stdout.write(- `added rerank provider '${name}' (set ${envKey} in the environment to supply its key)\n`,- );- }- return 0;}// βββ query ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ@@ -573,8 +536,8 @@ async function cmdSearchQuery(argv: ReadonlyArray<string>): Promise<number> {throw new CliError("query string is required when --query-doc has no searchable lanes");}const limitNum = Number(flags["limit"] ?? "10");- if (!Number.isInteger(limitNum) || limitNum < 1 || limitNum > 100) {- throw new CliError("--limit must be an integer in 1..100");+ if (!Number.isInteger(limitNum) || limitNum < SEARCH_LIMIT_MIN || limitNum > SEARCH_LIMIT_MAX) {+ throw new CliError(`--limit must be an integer in ${SEARCH_LIMIT_MIN}..${SEARCH_LIMIT_MAX}`);}const disclosureRaw = typeof flags["disclosure"] === "string" ? flags["disclosure"] : undefined;if (disclosureRaw !== undefined && disclosureRaw !== "full" && disclosureRaw !== "cards") {@@ -697,73 +660,8 @@ function jsonForOutcome(o: SearchOutcome): unknown {})),warnings: o.warnings,total: o.total,- ...(o.cards- ? {- cards: o.cards.map((c) => ({- path: c.path,- title: c.title,- score: c.score,- snippet: c.snippet,- pointer: c.pointer,- reasons: c.reasons,- document_id: c.documentId,- chunk_id: c.chunkId,- ...(c.origin !== undefined ? { origin: c.origin } : {}),- })),- }- : {}),- ...(o.evidencePack ? { evidence_pack: jsonForEvidencePack(o.evidencePack) } : {}),- };-}--function jsonForEvidencePack(pack: NonNullable<SearchOutcome["evidencePack"]>): unknown {- return {- significant_terms: pack.significantTerms,- matched_terms: pack.matchedTerms,- missing_terms: pack.missingTerms,- support_coverage: pack.supportCoverage,- records: pack.records.map((record) => ({- path: record.path,- document_id: record.documentId,- chunk_id: record.chunkId,- line_pointer: record.linePointer,- matched_terms: record.matchedTerms,- missing_terms: record.missingTerms,- support_coverage: record.supportCoverage,- terminal_state: record.terminalState,- why_retrieved: record.whyRetrieved,- dropped_candidate_reasons: record.droppedCandidateReasons,- })),- dropped_candidates: pack.droppedCandidates,- abstention: pack.abstention,- ...(pack.idfWeightedCoverage !== undefined- ? { idf_weighted_coverage: pack.idfWeightedCoverage }- : {}),- ...(pack.rareTerms !== undefined ? { rare_terms: pack.rareTerms } : {}),- ...(pack.uncoveredRareTerms !== undefined- ? { uncovered_rare_terms: pack.uncoveredRareTerms }- : {}),- ...(pack.unionRecords !== undefined- ? {- union_records: pack.unionRecords.map((r) => ({- term: r.term,- path: r.path,- document_id: r.documentId,- chunk_id: r.chunkId,- })),- }- : {}),- ...(pack.completeness !== undefined- ? {- completeness: {- verdict: pack.completeness.verdict,- idf_weighted_coverage: pack.completeness.idfWeightedCoverage,- covered_terms: pack.completeness.coveredTerms,- uncovered_terms: pack.completeness.uncoveredTerms,- uncovered_but_present_in_corpus: pack.completeness.uncoveredButPresentInCorpus,- },- }- : {}),+ ...(o.cards ? { cards: o.cards.map(serializeSearchCard) } : {}),+ ...(o.evidencePack ? { evidence_pack: serializeEvidencePack(o.evidencePack) } : {}),};}@@ -1141,35 +1039,13 @@ async function cmdSearchStatus(argv: ReadonlyArray<string>): Promise<number> {const cfg = resolveConfig(flags);const status = await indexStatus(cfg);if (flags["json"]) {- process.stdout.write(JSON.stringify(jsonForStatus(status)) + "\n");+ process.stdout.write(JSON.stringify(serializeIndexStatus(status)) + "\n");return 0;}process.stdout.write(renderStatusHuman(status));return 0;}-function jsonForStatus(s: IndexStatusSnapshot): unknown {- return {- index_path: s.indexPath,- exists: s.exists,- schema_version: s.schemaVersion,- documents: s.documents,- chunks: s.chunks,- embeddings: s.embeddings,- stale_embeddings: s.staleEmbeddings,- embedding_model: s.embeddingModel,- embedding_dimension: s.embeddingDimension,- embedding_signature: s.embeddingSignature,- estimated_refresh_cost_usd: s.estimatedRefreshCostUsd,- vec_extension: s.vecExtension,- semantic_enabled: s.semanticEnabled,- embedding_key_present: s.embeddingKeyPresent,- last_indexed_at: s.lastIndexedAt,- last_full_index_at: s.lastFullIndexAt,- warnings: s.warnings,- };-}-function renderStatusHuman(s: IndexStatusSnapshot): string {if (!s.exists) {return `index: not initialised. Run: o2b search index\n path: ${s.indexPath}\n`;diff --git a/src/core/brain/backlinks.ts b/src/core/brain/backlinks.tsindex 47926fa6..e9b0db31 100644--- a/src/core/brain/backlinks.ts+++ b/src/core/brain/backlinks.ts@@ -33,7 +33,7 @@ import { relationFromFrontmatterField } from "../graph/relation-vocab.ts";import { normalizeRelationTarget } from "../graph/frontmatter-relations.ts";import { buildAliasIndex } from "./link-graph/alias-index.ts";import { extractWikilinkRichBodies, parseWikilinkRich } from "./link-graph/parse-wikilink.ts";-import { listLogDates, readLogDay } from "./log-jsonl.ts";+import { listLogShardFiles, readLogDay } from "./log-jsonl.ts";import { brainDirs } from "./paths.ts";import { normalizeDerivedKeys } from "./preference.ts";import { normaliseWikilinkTarget } from "./wikilink.ts";@@ -264,12 +264,17 @@ function collectLog(push: (target: string, ref: BacklinkRef) => void,): void {if (!existsSync(dir)) return;- // Shard-aware (Memory Integrity Suite): merged per-day reads.- for (const date of listLogDates(vault)) {+ // Shard-aware (Memory Integrity Suite): merged per-day reads. List the+ // log directory once and share it across every date's readLogDay call+ // instead of one readdirSync+sort per date (this loop can span a+ // vault's entire log history).+ const shards = listLogShardFiles(vault);+ const dates = [...new Set(shards.map((f) => f.date))].toSorted();+ for (const date of dates) {const source = `log-${date}`;let entries;try {- entries = readLogDay(vault, date).entries;+ entries = readLogDay(vault, date, shards).entries;} catch {continue;}diff --git a/src/core/brain/continuity/usage-signal.ts b/src/core/brain/continuity/usage-signal.tsindex 7ac24a41..abac2493 100644--- a/src/core/brain/continuity/usage-signal.ts+++ b/src/core/brain/continuity/usage-signal.ts@@ -20,6 +20,7 @@* Read-only by construction; this module never writes to the store.*/+import { clamp01 } from "../../math.ts";import { listRecallTelemetry } from "../recall-telemetry.ts";import type { NormalizedContinuityRecord } from "./read-model.ts";@@ -220,8 +221,3 @@ function readArtifacts(value: unknown): ReadonlyArray<ArtifactRef> {function readString(value: unknown): string | null {return typeof value === "string" && value.length > 0 ? value : null;}--function clamp01(value: number): number {- if (!Number.isFinite(value)) return 0;- return Math.min(1, Math.max(0, value));-}diff --git a/src/core/brain/digest.ts b/src/core/brain/digest.tsindex 1f60ed13..f4f5a97c 100644--- a/src/core/brain/digest.ts+++ b/src/core/brain/digest.ts@@ -40,7 +40,7 @@ import { join } from "node:path";import type { LinkOutputFormat } from "../config.ts";-import { backlinkCount, buildBacklinkIndex } from "./backlinks.ts";+import { backlinkCount, buildBacklinkIndex, type BacklinkIndex } from "./backlinks.ts";import { computeAgentSummary, type AgentSummaryEntry } from "./digest-agent-summary.ts";import { findMergeCandidates } from "./merge-candidates.ts";import { computeMostApplied } from "./most-applied.ts";@@ -500,7 +500,11 @@ function collectDigestData(vault: string, since: Date, until: Date): DigestDataretiredEntries.sort((a, b) => a.id.localeCompare(b.id));const top_applied = pickTopApplied(preferences);- const top_referenced = pickTopReferenced(vault, preferences);+ // Built once and shared with `computeConnectionHealth` below: both+ // read the same vault state within this digest run, so one+ // full-history backlink scan replaces two.+ const backlinkIndex = buildBacklinkIndex(vault);+ const top_referenced = pickTopReferenced(backlinkIndex, preferences);// `merge_suggestions` reflects current vault state, not windowed// change. It is independent of `since`/`until` on purpose β// operators should see pending duplicates regardless of the digest@@ -572,7 +576,7 @@ function collectDigestData(vault: string, since: Date, until: Date): DigestDatamerge_suggestions,agent_summary,most_applied,- connection_health: computeConnectionHealth(vault, preferences),+ connection_health: computeConnectionHealth(vault, backlinkIndex, preferences),actions: collectMaintenanceActions(vault),};}@@ -606,10 +610,9 @@ function pickTopApplied(}function pickTopReferenced(- vault: string,+ index: BacklinkIndex,preferences: ReadonlyArray<PreferenceWithPath>,): ReadonlyArray<DigestJsonTopReferenced> {- const index = buildBacklinkIndex(vault);const scored = preferences.map(({ pref }) => ({pref,@@ -636,9 +639,9 @@ function pickTopReferenced(*/function computeConnectionHealth(vault: string,+ index: BacklinkIndex,preferences: ReadonlyArray<PreferenceWithPath>,): DigestJsonConnectionHealth {- const index = buildBacklinkIndex(vault);const allIds = preferences.map(({ pref }) => pref.id);// Also include retired entries.const dirs = brainDirs(vault);diff --git a/src/core/brain/doctor.ts b/src/core/brain/doctor.tsindex 6469af6d..a47b7431 100644--- a/src/core/brain/doctor.ts+++ b/src/core/brain/doctor.ts@@ -666,17 +666,12 @@ function checkVaultIgnore(vault: string, issues: DoctorIssue[]): void {function checkSignals(vault: string, issues: DoctorIssue[], idIndex: Map<string, string[]>): void {const dirs = brainDirs(vault);for (const dir of [dirs.inbox, dirs.processed]) {- if (!existsSync(dir)) continue;- for (const entry of readdirSync(dir, { withFileTypes: true })) {- if (!entry.isFile()) continue;- if (!entry.name.endsWith(".md")) continue;- if (!entry.name.startsWith("sig-")) continue;- const path = join(dir, entry.name);+ forEachBrainFile(dir, "sig-", (path, filename) => {try {const sig = parseSignal(path);registerId(idIndex, sig.id, path);checkIso(path, "created_at", sig.created_at, issues);- const expectedId = entry.name.slice(0, -".md".length);+ const expectedId = filename.slice(0, -".md".length);if (sig.id !== expectedId) {issues.push({severity: "warning",@@ -693,7 +688,7 @@ function checkSignals(vault: string, issues: DoctorIssue[], idIndex: Map<string,message: (err as Error).message ?? String(err),});}- }+ });}}@@ -706,11 +701,7 @@ function checkPreferences(knownBasenames: ReadonlySet<string>,): void {const dirs = brainDirs(vault);- if (!existsSync(dirs.preferences)) return;- for (const entry of readdirSync(dirs.preferences, { withFileTypes: true })) {- if (!entry.isFile() || !entry.name.endsWith(".md")) continue;- if (!entry.name.startsWith("pref-")) continue;- const path = join(dirs.preferences, entry.name);+ forEachBrainFile(dirs.preferences, "pref-", (path) => {try {const pref = parsePreference(path);registerId(idIndex, pref.id, path);@@ -744,32 +735,9 @@ function checkPreferences(});}} catch (err) {- if (err instanceof BrainStatusFolderMismatchError) {- issues.push({- severity: "warning",- code: "status-folder-mismatch",- path,- message: err.message,- });- } else {- // Distinguish field-missing errors (write-time contract) from- // unexpected throws so the CLI report stays useful.- const msg = (err as Error).message ?? String(err);- const isMissingField = /missing field/.test(msg);- const isInvalidIso = /ISO-8601/i.test(msg);- issues.push({- severity: "error",- code: isMissingField- ? "preference-missing-field"- : isInvalidIso- ? "iso-invalid"- : "preference-invalid",- path,- message: msg,- });- }+ classifyParseError(err, path, "preference", issues);}- }+ });}// ----- Retired check --------------------------------------------------------@@ -781,11 +749,7 @@ function checkRetired(knownBasenames: ReadonlySet<string>,): void {const dirs = brainDirs(vault);- if (!existsSync(dirs.retired)) return;- for (const entry of readdirSync(dirs.retired, { withFileTypes: true })) {- if (!entry.isFile() || !entry.name.endsWith(".md")) continue;- if (!entry.name.startsWith("ret-")) continue;- const path = join(dirs.retired, entry.name);+ forEachBrainFile(dirs.retired, "ret-", (path) => {try {const ret = parseRetired(path);registerId(idIndex, ret.id, path);@@ -800,30 +764,9 @@ function checkRetired(checkWikilinks(path, "superseded_by", [ret.superseded_by], knownBasenames, issues);}} catch (err) {- if (err instanceof BrainStatusFolderMismatchError) {- issues.push({- severity: "warning",- code: "status-folder-mismatch",- path,- message: err.message,- });- } else {- const msg = (err as Error).message ?? String(err);- const isMissingField = /missing field/.test(msg);- const isInvalidIso = /ISO-8601/i.test(msg);- issues.push({- severity: "error",- code: isMissingField- ? "retired-missing-field"- : isInvalidIso- ? "iso-invalid"- : "retired-invalid",- path,- message: msg,- });- }+ classifyParseError(err, path, "retired", issues);}- }+ });}// ----- Log check ------------------------------------------------------------@@ -853,6 +796,62 @@ function registerId(idIndex: Map<string, string[]>, id: string, path: string): velse idIndex.set(id, [path]);}+/**+ * Iterate the `<prefix>*.md` files directly inside `dir` (non-recursive),+ * invoking `cb(path, filename)` for each. Absent `dir` is a no-op - the+ * per-kind checks (`checkPreferences`, `checkRetired`, `checkSignals`) all+ * treat a missing Brain subdirectory as "nothing to check", not an error.+ */+function forEachBrainFile(+ dir: string,+ prefix: string,+ cb: (path: string, filename: string) => void,+): void {+ if (!existsSync(dir)) return;+ for (const entry of readdirSync(dir, { withFileTypes: true })) {+ if (!entry.isFile() || !entry.name.endsWith(".md")) continue;+ if (!entry.name.startsWith(prefix)) continue;+ cb(join(dir, entry.name), entry.name);+ }+}++/**+ * Classify a parse-time error into a `DoctorIssue` and push it. Shared by+ * `checkPreferences` and `checkRetired`, which previously carried+ * byte-identical copies of this regex-based classification - a change to+ * a parser's error wording would otherwise reclassify issues in one path+ * without the other noticing.+ */+function classifyParseError(+ err: unknown,+ path: string,+ kindPrefix: string,+ issues: DoctorIssue[],+): void {+ if (err instanceof BrainStatusFolderMismatchError) {+ issues.push({+ severity: "warning",+ code: "status-folder-mismatch",+ path,+ message: err.message,+ });+ return;+ }+ const msg = (err as Error).message ?? String(err);+ const isMissingField = /missing field/.test(msg);+ const isInvalidIso = /ISO-8601/i.test(msg);+ issues.push({+ severity: "error",+ code: isMissingField+ ? `${kindPrefix}-missing-field`+ : isInvalidIso+ ? "iso-invalid"+ : `${kindPrefix}-invalid`,+ path,+ message: msg,+ });+}+// ISO-8601 UTC: YYYY-MM-DDTHH:MM:SS(.fff)?Z. Lenient β we accept the// shorter date-only form too (created_at is sometimes a date-only string// in hand-authored signals).diff --git a/src/core/brain/heal-enrich.ts b/src/core/brain/heal-enrich.tsindex 735c2590..9261d11e 100644--- a/src/core/brain/heal-enrich.ts+++ b/src/core/brain/heal-enrich.ts@@ -16,6 +16,8 @@* functions are pure and side-effect free regardless.*/+import { escapeRegex } from "../strings.ts";+const H1_RE = /^#[ \t]+(.+?)[ \t]*$/m;// Existing wikilinks, fenced code blocks, and inline code spans are// protected from linking. The fenced-block alternation comes first so a@@ -31,10 +33,6 @@ export function deriveTitleFromContent(markdown: string): string | null {return title.length > 0 ? title : null;}-function escapeRegExp(s: string): string {- return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");-}-/*** Wrap exact whole-token occurrences of any `known` title/alias in a* wikilink. Text inside existing wikilinks or inline code is left@@ -50,7 +48,7 @@ export function linkExactMentions(body: string, known: ReadonlyArray<string>): s.toSorted((a, b) => b.length - a.length || (a < b ? -1 : a > b ? 1 : 0));if (phrases.length === 0) return body;- const alternation = phrases.map(escapeRegExp).join("|");+ const alternation = phrases.map(escapeRegex).join("|");// Whole-token boundaries via Unicode letter/number lookarounds so the// match is language-agnostic (works for any script).const linkRe = new RegExp(`(?<![\\p{L}\\p{N}])(?:${alternation})(?![\\p{L}\\p{N}])`, "gu");diff --git a/src/core/brain/log-jsonl.ts b/src/core/brain/log-jsonl.tsindex 94280e78..52726a69 100644--- a/src/core/brain/log-jsonl.ts+++ b/src/core/brain/log-jsonl.ts@@ -53,7 +53,7 @@ const ISO_UTC_TS_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/;// that does not match are NOT log shards.const LOG_FILE_RE = /^(\d{4}-\d{2}-\d{2})(?:\.([a-z0-9-]{1,32}))?\.(jsonl|md)$/;-interface LogShardFile {+export interface LogShardFile {readonly date: string;/** Empty string for the legacy un-sharded pair. */readonly shardId: string;@@ -62,8 +62,13 @@ interface LogShardFile {readonly name: string;}-/** Every recognised log file under `Brain/log/`, sorted by name. */-function listLogShardFiles(vault: string): LogShardFile[] {+/**+ * Every recognised log file under `Brain/log/`, sorted by name. Exported+ * so a caller that reads MANY dates in one operation (e.g. the backlink+ * index) can list once and pass the result to {@link readLogDay} instead+ * of paying one `readdirSync` + sort per date.+ */+export function listLogShardFiles(vault: string): LogShardFile[] {const dir = brainDirs(vault).log;if (!existsSync(dir)) return [];const out: LogShardFile[] = [];@@ -126,10 +131,19 @@ export function listLogMarkdownFiles(vault: string): Array<{ date: string; path:* markdown is the fallback. When no file exists, returns an empty* result with `source: "jsonl"` (a convenient default β the caller* treats it as "no events for that date" regardless of source).+ *+ * `preloadedShards` lets a caller iterating many dates in one operation+ * (e.g. `collectLog`) list the directory once and pass the result in,+ * instead of every call re-running `readdirSync` + sort - output is+ * identical either way, this only skips redundant directory scans.*/-export function readLogDay(vault: string, date: string): ReadLogDayResult {+export function readLogDay(+ vault: string,+ date: string,+ preloadedShards?: ReadonlyArray<LogShardFile>,+): ReadLogDayResult {const validDate = validateIsoDate(date);- const shards = listLogShardFiles(vault).filter((f) => f.date === validDate);+ const shards = (preloadedShards ?? listLogShardFiles(vault)).filter((f) => f.date === validDate);if (shards.length === 0) return { entries: [], source: "jsonl", warnings: [] };// Group by shard id; per shard prefer .jsonl over .md.diff --git a/src/core/brain/policy.ts b/src/core/brain/policy.tsindex ceea5337..92e72100 100644--- a/src/core/brain/policy.ts+++ b/src/core/brain/policy.ts@@ -341,6 +341,26 @@ export function resolveSessions(cfg: BrainConfig): ResolvedBrainSessionsConfig {}) as ResolvedBrainSessionsConfig;}+/**+ * Factory for the "load + resolve a block, fall back to its defaults on+ * ANY failure" pattern repeated at every `load*ConfigSafe` below (missing+ * `_brain.yaml`, malformed YAML, or a validation error all collapse to+ * the same fallback - these are read surfaces for vaults that may not+ * have run `brain init` yet, not strict config consumers).+ */+function makeSafeLoader<T>(+ resolveFn: (config: BrainConfig) => T,+ fallback: T,+): (vault: string) => T {+ return (vault: string): T => {+ try {+ return resolveFn(loadBrainConfig(vault));+ } catch {+ return fallback;+ }+ };+}+/*** Load + resolve the `notes:` block, falling back to* `BRAIN_NOTES_DEFAULTS` when the config file is missing, malformed,@@ -349,13 +369,7 @@ export function resolveSessions(cfg: BrainConfig): ResolvedBrainSessionsConfig {* vault that has not been `brain init`-ed still produces a clean* "no user folders to read" result.*/-export function loadNotesConfigSafe(vault: string): ResolvedBrainNotesConfig {- try {- return resolveNotes(loadBrainConfig(vault));- } catch {- return BRAIN_NOTES_DEFAULTS;- }-}+export const loadNotesConfigSafe = makeSafeLoader(resolveNotes, BRAIN_NOTES_DEFAULTS);/*** Load + resolve the `temporal:` block, falling back to@@ -364,13 +378,7 @@ export function loadNotesConfigSafe(vault: string): ResolvedBrainNotesConfig {* consumer (MCP wrappers, CLI verbs) so a freshly-initialised vault* still produces a useful report.*/-export function loadTemporalConfigSafe(vault: string): ResolvedBrainTemporalConfig {- try {- return resolveTemporal(loadBrainConfig(vault));- } catch {- return BRAIN_TEMPORAL_DEFAULTS;- }-}+export const loadTemporalConfigSafe = makeSafeLoader(resolveTemporal, BRAIN_TEMPORAL_DEFAULTS);/*** Load + resolve the `guardrails:` block, falling back to@@ -379,13 +387,7 @@ export function loadTemporalConfigSafe(vault: string): ResolvedBrainTemporalConf* context pack) that must work on a vault without a full `brain init`;* the opt-in toggles therefore default off rather than throwing.*/-export function loadGuardrailsConfigSafe(vault: string): ResolvedBrainGuardrailConfig {- try {- return resolveGuardrails(loadBrainConfig(vault));- } catch {- return BRAIN_GUARDRAIL_DEFAULTS;- }-}+export const loadGuardrailsConfigSafe = makeSafeLoader(resolveGuardrails, BRAIN_GUARDRAIL_DEFAULTS);/*** Load the configured `feedback.default_scope`, or `undefined` when the@@ -394,13 +396,10 @@ export function loadGuardrailsConfigSafe(vault: string): ResolvedBrainGuardrailC* stays scope-less (byte-identical to pre-feature behaviour) instead of* throwing when the signal is recorded.*/-export function loadFeedbackDefaultScopeSafe(vault: string): string | undefined {- try {- return loadBrainConfig(vault).feedback?.default_scope;- } catch {- return undefined;- }-}+export const loadFeedbackDefaultScopeSafe = makeSafeLoader(+ (config: BrainConfig) => config.feedback?.default_scope,+ undefined as string | undefined,+);/*** Default `_brain.yaml` content. Mirrors Β§10 of the design doc. Used by@@ -636,6 +635,12 @@ export function validateBrainConfigDetailed(}const obj = parsed as Record<string, unknown>;const warnings: BrainConfigLoadWarning[] = [];+ // Populated by every `hasBlock`/`mergeBlock` call below; drives the+ // forward-compat "unknown top-level field" check at the end of this+ // function. `schema_version` is seeded directly since its presence is+ // checked by an inverted `if (!(... in obj))` immediately below, not+ // through either helper.+ const knownBlockKeys = new Set<string>(["schema_version"]);// schema_version is mandatory and must be in the supported set.if (!("schema_version" in obj)) {@@ -667,7 +672,7 @@ export function validateBrainConfigDetailed(// writer would later refuse to emit fails fast at load time// instead of round-tripping into a state we cannot persist.let primaryAgent: string | null = DEFAULT_BRAIN_CONFIG.primary_agent;- if ("primary_agent" in obj) {+ if (hasBlock(obj, "primary_agent", knownBlockKeys)) {const v = obj["primary_agent"];if (v === null || v === undefined) {primaryAgent = null;@@ -708,6 +713,7 @@ export function validateBrainConfigDetailed(obj["dream"],DEFAULT_BRAIN_CONFIG.dream as unknown as Readonly<Record<string, number>>,source,+ knownBlockKeys,);requirePositiveInteger("dream.candidate_threshold", dream.candidate_threshold, source);requirePositiveInteger("dream.unconfirmed_window_days", dream.unconfirmed_window_days, source);@@ -722,6 +728,7 @@ export function validateBrainConfigDetailed(obj["retire"],DEFAULT_BRAIN_CONFIG.retire as unknown as Readonly<Record<string, number>>,source,+ knownBlockKeys,);requirePositiveInteger("retire.stale_evidence_days", retire.stale_evidence_days, source);@@ -730,6 +737,7 @@ export function validateBrainConfigDetailed(obj["confidence"],DEFAULT_BRAIN_CONFIG.confidence as unknown as Readonly<Record<string, number>>,source,+ knownBlockKeys,);requireNonNegativeInteger("confidence.low_max_applied", confidence.low_max_applied, source);requireUnitInterval("confidence.medium_min", confidence.medium_min, source);@@ -748,6 +756,7 @@ export function validateBrainConfigDetailed(obj["snapshots"],DEFAULT_BRAIN_CONFIG.snapshots as unknown as Readonly<Record<string, number>>,source,+ knownBlockKeys,);requirePositiveInteger("snapshots.retention_count", snapshots.retention_count, source);@@ -757,16 +766,9 @@ export function validateBrainConfigDetailed(// operators who explicitly removed it; the resolver falls back to// `DEFAULT_VAULT_IGNORE_PATHS` in both cases.let vault: BrainVaultConfig | undefined;- if ("vault" in obj) {+ if (hasBlock(obj, "vault", knownBlockKeys)) {const raw = obj["vault"];- if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {- throw new BrainConfigError(- `block must be a map of keys; got ${describe(raw)}`,- "vault",- source,- );- }- const rawMap = raw as Record<string, unknown>;+ const rawMap = requireMapBlock(raw, "vault", source);if ("ignore_paths" in rawMap) {const list = rawMap["ignore_paths"];if (!Array.isArray(list)) {@@ -831,14 +833,7 @@ export function validateBrainConfigDetailed(vault = { ignore_paths: Object.freeze(validated) };}// Forward-compat: unknown sub-keys under `vault:` β warning.- for (const key of Object.keys(rawMap)) {- if (key !== "ignore_paths") {- warnings.push({- path: source ?? "<config>",- message: `vault.${key}: unknown field ignored (forward-compat)`,- });- }- }+ warnUnknownKeys(rawMap, ["ignore_paths"], "vault", source, warnings);}// Optional `active.{most_applied_window_days, most_applied_limit}`@@ -850,16 +845,9 @@ export function validateBrainConfigDetailed(// groups them so downstream consumers (`active.md`, `brain_digest`)// can pass one struct around.let active: BrainActiveConfig | undefined;- if ("active" in obj) {+ if (hasBlock(obj, "active", knownBlockKeys)) {const rawActive = obj["active"];- if (typeof rawActive !== "object" || rawActive === null || Array.isArray(rawActive)) {- throw new BrainConfigError(- `block must be a map of keys; got ${describe(rawActive)}`,- "active",- source,- );- }- const activeMap = rawActive as Record<string, unknown>;+ const activeMap = requireMapBlock(rawActive, "active", source);const hasWindow = "most_applied_window_days" in activeMap;const hasLimit = "most_applied_limit" in activeMap;let mostApplied: BrainMostAppliedConfig | undefined;@@ -915,18 +903,13 @@ export function validateBrainConfigDetailed(injectBudgetChars = raw;}// Forward-compat: unknown sub-keys under `active:` β warning.- for (const k of Object.keys(activeMap)) {- if (- k !== "most_applied_window_days" &&- k !== "most_applied_limit" &&- k !== "inject_budget_chars"- ) {- warnings.push({- path: source ?? "<config>",- message: `active.${k}: unknown field ignored (forward-compat)`,- });- }- }+ warnUnknownKeys(+ activeMap,+ ["most_applied_window_days", "most_applied_limit", "inject_budget_chars"],+ "active",+ source,+ warnings,+ );active = {...(mostApplied !== undefined ? { most_applied: mostApplied } : {}),...(injectBudgetChars !== undefined ? { inject_budget_chars: injectBudgetChars } : {}),@@ -937,16 +920,9 @@ export function validateBrainConfigDetailed(// recency-scored lessons digest. Hard-error on out-of-range values β// operator-tunable knobs must never silently fall back to defaults.let lessons: BrainLessonsConfig | undefined;- if ("lessons" in obj) {+ if (hasBlock(obj, "lessons", knownBlockKeys)) {const rawLessons = obj["lessons"];- if (typeof rawLessons !== "object" || rawLessons === null || Array.isArray(rawLessons)) {- throw new BrainConfigError(- `block must be a map of keys; got ${describe(rawLessons)}`,- "lessons",- source,- );- }- const lessonsMap = rawLessons as Record<string, unknown>;+ const lessonsMap = requireMapBlock(rawLessons, "lessons", source);const halfLife = readBoundedInt(lessonsMap,"half_life_days",@@ -968,14 +944,13 @@ export function validateBrainConfigDetailed(LESSONS_LIMIT_MAX,source,);- for (const k of Object.keys(lessonsMap)) {- if (k !== "half_life_days" && k !== "corroboration_min" && k !== "limit") {- warnings.push({- path: source ?? "<config>",- message: `lessons.${k}: unknown field ignored (forward-compat)`,- });- }- }+ warnUnknownKeys(+ lessonsMap,+ ["half_life_days", "corroboration_min", "limit"],+ "lessons",+ source,+ warnings,+ );lessons = {...(halfLife !== undefined ? { half_life_days: halfLife } : {}),...(corroborationMin !== undefined ? { corroboration_min: corroborationMin } : {}),@@ -987,7 +962,7 @@ export function validateBrainConfigDetailed(// warning and drop the section (return undefined) rather than throwing β// the rest of the CLI surface must keep working.let disciplineReport: DisciplineReportConfig | undefined;- if ("discipline_report" in obj) {+ if (hasBlock(obj, "discipline_report", knownBlockKeys)) {const dr = obj["discipline_report"];if (typeof dr !== "object" || dr === null || Array.isArray(dr)) {warnings.push({@@ -1071,16 +1046,9 @@ export function validateBrainConfigDetailed(// `cfg.guardrails` undefined; `resolveGuardrails` injects defaults// on the read side so consumers receive a fully-populated struct.let guardrails: BrainGuardrailConfig | undefined;- if ("guardrails" in obj) {+ if (hasBlock(obj, "guardrails", knownBlockKeys)) {const raw = obj["guardrails"];- if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {- throw new BrainConfigError(- `block must be a map of keys; got ${describe(raw)}`,- "guardrails",- source,- );- }- const rawMap = raw as Record<string, unknown>;+ const rawMap = requireMapBlock(raw, "guardrails", source);const partial: {promotion_min_signals?: number;promotion_min_distinct_agents?: number;@@ -1164,24 +1132,22 @@ export function validateBrainConfigDetailed(}// Forward-compat: unknown sub-keys under `guardrails:` β warning.- const knownGuardrailKeys = new Set([- "promotion_min_signals",- "promotion_min_distinct_agents",- "promotion_min_age_days",- "instruction_file_max_lines",- "untrusted_source_delimiting",- "derived_fact_synthesis",- "provenance_trust_ordering",- "owner_scoped_facts",- ]);- for (const key of Object.keys(rawMap)) {- if (!knownGuardrailKeys.has(key)) {- warnings.push({- path: source ?? "<config>",- message: `guardrails.${key}: unknown field ignored (forward-compat)`,- });- }- }+ warnUnknownKeys(+ rawMap,+ [+ "promotion_min_signals",+ "promotion_min_distinct_agents",+ "promotion_min_age_days",+ "instruction_file_max_lines",+ "untrusted_source_delimiting",+ "derived_fact_synthesis",+ "provenance_trust_ordering",+ "owner_scoped_facts",+ ],+ "guardrails",+ source,+ warnings,+ );if (Object.keys(partial).length > 0) {guardrails = partial;@@ -1201,12 +1167,9 @@ export function validateBrainConfigDetailed(// Absent block β `cfg.link_graph` undefined; resolveLinkGraph// returns the bit-identical defaults.let linkGraph: BrainLinkGraphConfig | undefined;- if ("link_graph" in obj) {+ if (hasBlock(obj, "link_graph", knownBlockKeys)) {const rawLg = obj["link_graph"];- if (typeof rawLg !== "object" || rawLg === null || Array.isArray(rawLg)) {- throw new BrainConfigError("link_graph must be a mapping", "link_graph", source);- }- const lgObj = rawLg as Record<string, unknown>;+ const lgObj = requireMapBlock(rawLg, "link_graph", source);const partialLg: Record<string, unknown> = {};if ("moc_min_outbound_links" in lgObj) {const v = lgObj["moc_min_outbound_links"];@@ -1256,18 +1219,13 @@ export function validateBrainConfigDetailed(partialLg["vault_instruction_file"] = trimmed;}// Forward-compat: unknown sub-keys under `link_graph:` β warning.- for (const key of Object.keys(lgObj)) {- if (- key !== "moc_min_outbound_links" &&- key !== "moc_min_link_ratio" &&- key !== "vault_instruction_file"- ) {- warnings.push({- path: source ?? "<config>",- message: `link_graph.${key}: unknown field ignored (forward-compat)`,- });- }- }+ warnUnknownKeys(+ lgObj,+ ["moc_min_outbound_links", "moc_min_link_ratio", "vault_instruction_file"],+ "link_graph",+ source,+ warnings,+ );linkGraph = Object.keys(partialLg).length > 0 ? (partialLg as BrainLinkGraphConfig) : {};}@@ -1281,12 +1239,9 @@ export function validateBrainConfigDetailed(// Absent block β `cfg.temporal` undefined; resolveTemporal returns// the bit-identical defaults.let temporal: BrainTemporalConfig | undefined;- if ("temporal" in obj) {+ if (hasBlock(obj, "temporal", knownBlockKeys)) {const rawTp = obj["temporal"];- if (typeof rawTp !== "object" || rawTp === null || Array.isArray(rawTp)) {- throw new BrainConfigError("temporal must be a mapping", "temporal", source);- }- const tpObj = rawTp as Record<string, unknown>;+ const tpObj = requireMapBlock(rawTp, "temporal", source);const partialTp: Record<string, unknown> = {};const positiveIntKeys: ReadonlyArray<"stale_pref_days" | "stale_signal_days" | "stale_log_days"@@ -1323,21 +1278,19 @@ export function validateBrainConfigDetailed(partialTp["daily_window_offset_hours"] = v;}// Forward-compat: unknown sub-keys under `temporal:` β warning.- const knownTp = new Set([- "stale_pref_days",- "stale_signal_days",- "stale_log_days",- "weekly_start_dow",- "daily_window_offset_hours",- ]);- for (const key of Object.keys(tpObj)) {- if (!knownTp.has(key)) {- warnings.push({- path: source ?? "<config>",- message: `temporal.${key}: unknown field ignored (forward-compat)`,- });- }- }+ warnUnknownKeys(+ tpObj,+ [+ "stale_pref_days",+ "stale_signal_days",+ "stale_log_days",+ "weekly_start_dow",+ "daily_window_offset_hours",+ ],+ "temporal",+ source,+ warnings,+ );temporal = Object.keys(partialTp).length > 0 ? (partialTp as BrainTemporalConfig) : {};}@@ -1350,12 +1303,9 @@ export function validateBrainConfigDetailed(// Absent block β `cfg.health` undefined; resolveHealth returns the// bit-identical defaults.let health: BrainHealthConfig | undefined;- if ("health" in obj) {+ if (hasBlock(obj, "health", knownBlockKeys)) {const rawH = obj["health"];- if (typeof rawH !== "object" || rawH === null || Array.isArray(rawH)) {- throw new BrainConfigError("health must be a mapping", "health", source);- }- const hObj = rawH as Record<string, unknown>;+ const hObj = requireMapBlock(rawH, "health", source);const partialH: Record<string, unknown> = {};if ("contradiction_jaccard" in hObj) {const v = hObj["contradiction_jaccard"];@@ -1380,20 +1330,18 @@ export function validateBrainConfigDetailed(partialH[key] = v;}}- const knownH = new Set([- "contradiction_jaccard",- "concept_gap_min_frequency",- "stale_claim_max_age_days",- "remediation_step_cap",- ]);- for (const key of Object.keys(hObj)) {- if (!knownH.has(key)) {- warnings.push({- path: source ?? "<config>",- message: `health.${key}: unknown field ignored (forward-compat)`,- });- }- }+ warnUnknownKeys(+ hObj,+ [+ "contradiction_jaccard",+ "concept_gap_min_frequency",+ "stale_claim_max_age_days",+ "remediation_step_cap",+ ],+ "health",+ source,+ warnings,+ );health = Object.keys(partialH).length > 0 ? (partialH as BrainHealthConfig) : {};}@@ -1406,12 +1354,9 @@ export function validateBrainConfigDetailed(// bit-identical defaults (empty `read_paths`). The list is purely// a READ surface; agents never write to these paths.let notes: BrainNotesConfig | undefined;- if ("notes" in obj) {+ if (hasBlock(obj, "notes", knownBlockKeys)) {const rawNotes = obj["notes"];- if (typeof rawNotes !== "object" || rawNotes === null || Array.isArray(rawNotes)) {- throw new BrainConfigError("notes must be a mapping", "notes", source);- }- const notesObj = rawNotes as Record<string, unknown>;+ const notesObj = requireMapBlock(rawNotes, "notes", source);const partialNotes: Record<string, unknown> = {};if ("read_paths" in notesObj) {const v = notesObj["read_paths"];@@ -1459,14 +1404,7 @@ export function validateBrainConfigDetailed(partialNotes["read_paths"] = cleaned;}// Forward-compat: unknown sub-keys under `notes:` β warning.- for (const key of Object.keys(notesObj)) {- if (key !== "read_paths") {- warnings.push({- path: source ?? "<config>",- message: `notes.${key}: unknown field ignored (forward-compat)`,- });- }- }+ warnUnknownKeys(notesObj, ["read_paths"], "notes", source, warnings);notes = Object.keys(partialNotes).length > 0 ? (partialNotes as BrainNotesConfig) : {};}@@ -1480,12 +1418,9 @@ export function validateBrainConfigDetailed(// capture-boundary warning, never a config error, so a typo cannot// take the whole Brain config down).let sessions: BrainSessionsConfig | undefined;- if ("sessions" in obj) {+ if (hasBlock(obj, "sessions", knownBlockKeys)) {const rawSessions = obj["sessions"];- if (typeof rawSessions !== "object" || rawSessions === null || Array.isArray(rawSessions)) {- throw new BrainConfigError("sessions must be a mapping", "sessions", source);- }- const sessionsObj = rawSessions as Record<string, unknown>;+ const sessionsObj = requireMapBlock(rawSessions, "sessions", source);const partial: Record<string, unknown> = {};const LIST_KEYS = ["ignore_patterns", "stateless_patterns", "ignore_message_patterns"];for (const key of LIST_KEYS) {@@ -1511,14 +1446,7 @@ export function validateBrainConfigDetailed(});partial[key] = cleaned;}- for (const key of Object.keys(sessionsObj)) {- if (!LIST_KEYS.includes(key)) {- warnings.push({- path: source ?? "<config>",- message: `sessions.${key}: unknown field ignored (forward-compat)`,- });- }- }+ warnUnknownKeys(sessionsObj, LIST_KEYS, "sessions", source, warnings);sessions = partial as BrainSessionsConfig;}@@ -1536,12 +1464,9 @@ export function validateBrainConfigDetailed(// Absent block leaves cfg.schema undefined; consumers merge built-ins// through resolveSchemaVocabulary.let schema: BrainSchemaConfig | undefined;- if ("schema" in obj) {+ if (hasBlock(obj, "schema", knownBlockKeys)) {const rawSchema = obj["schema"];- if (typeof rawSchema !== "object" || rawSchema === null || Array.isArray(rawSchema)) {- throw new BrainConfigError("schema must be a mapping", "schema", source);- }- const schemaObj = rawSchema as Record<string, unknown>;+ const schemaObj = requireMapBlock(rawSchema, "schema", source);const partialSchema: Partial<Record<keyof BrainSchemaConfig, ReadonlyArray<string>>> = {};for (const category of SCHEMA_VOCAB_CATEGORIES) {if (!(category in schemaObj)) continue;@@ -1591,17 +1516,13 @@ export function validateBrainConfigDetailed(return trimmed;});}- for (const key of Object.keys(schemaObj)) {- if (- !(SCHEMA_VOCAB_CATEGORIES as ReadonlyArray<string>).includes(key) &&- !(schemaMetaKeys as ReadonlyArray<string>).includes(key)- ) {- warnings.push({- path: source ?? "<config>",- message: `schema.${key}: unknown field ignored (forward-compat)`,- });- }- }+ warnUnknownKeys(+ schemaObj,+ [...(SCHEMA_VOCAB_CATEGORIES as ReadonlyArray<string>), ...schemaMetaKeys],+ "schema",+ source,+ warnings,+ );try {const declarations = validateSchemaDeclarations(partialSchema);schema = {@@ -1623,47 +1544,11 @@ export function validateBrainConfigDetailed(}}- // Forward-compat: unknown top-level keys β warning, not error.- const known = new Set([- "schema_version",- "primary_agent",- "dream",- "retire",- "confidence",- "snapshots",- "vault",- "active",- "lessons",- "discipline_report",- "guardrails",- "link_graph",- "temporal",- "notes",- "sessions",- "schema",- "feedback",- ]);- for (const key of Object.keys(obj)) {- if (!known.has(key)) {- warnings.push({- path: source ?? "<config>",- message: `unknown top-level field '${key}' ignored (forward-compat)`,- });- }- }-// Optional `hygiene:` block (continuity-hygiene-freshness suite).let hygiene: BrainHygieneConfig | undefined;- if ("hygiene" in obj) {+ if (hasBlock(obj, "hygiene", knownBlockKeys)) {const raw = obj["hygiene"];- if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {- throw new BrainConfigError(- `block must be a map of keys; got ${describe(raw)}`,- "hygiene",- source,- );- }- const rawMap = raw as Record<string, unknown>;+ const rawMap = requireMapBlock(raw, "hygiene", source);const partial: { resolver_cmd?: string; dedup_threshold?: number } = {};if ("resolver_cmd" in rawMap) {const cmd = rawMap["resolver_cmd"];@@ -1692,16 +1577,9 @@ export function validateBrainConfigDetailed(// Optional `anticipatory:` block (continuity-hygiene-freshness suite).let anticipatory: BrainAnticipatoryConfig | undefined;- if ("anticipatory" in obj) {+ if (hasBlock(obj, "anticipatory", knownBlockKeys)) {const raw = obj["anticipatory"];- if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {- throw new BrainConfigError(- `block must be a map of keys; got ${describe(raw)}`,- "anticipatory",- source,- );- }- const rawMap = raw as Record<string, unknown>;+ const rawMap = requireMapBlock(raw, "anticipatory", source);const partial: { ttl_seconds?: number; max_tokens?: number } = {};if ("ttl_seconds" in rawMap) {requirePositiveInteger("anticipatory.ttl_seconds", rawMap["ttl_seconds"], source);@@ -1716,16 +1594,9 @@ export function validateBrainConfigDetailed(// Optional `recall:` block (continuity-hygiene-freshness suite).let recall: BrainRecallConfig | undefined;- if ("recall" in obj) {+ if (hasBlock(obj, "recall", knownBlockKeys)) {const raw = obj["recall"];- if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {- throw new BrainConfigError(- `block must be a map of keys; got ${describe(raw)}`,- "recall",- source,- );- }- const rawMap = raw as Record<string, unknown>;+ const rawMap = requireMapBlock(raw, "recall", source);const partial: { degradation?: "hard-cut" | "staged" } = {};if ("degradation" in rawMap) {const mode = rawMap["degradation"];@@ -1747,16 +1618,9 @@ export function validateBrainConfigDetailed(// exactly (non-empty after trim, single-line, <= SCOPE_MAX_LEN) so a// configured default can never pass validation yet fail at write time.let feedback: BrainFeedbackConfig | undefined;- if ("feedback" in obj) {+ if (hasBlock(obj, "feedback", knownBlockKeys)) {const raw = obj["feedback"];- if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {- throw new BrainConfigError(- `block must be a map of keys; got ${describe(raw)}`,- "feedback",- source,- );- }- const rawMap = raw as Record<string, unknown>;+ const rawMap = requireMapBlock(raw, "feedback", source);const partial: { default_scope?: string } = {};if ("default_scope" in rawMap) {const value = rawMap["default_scope"];@@ -1792,17 +1656,25 @@ export function validateBrainConfigDetailed(partial.default_scope = trimmed;}// Forward-compat: unknown sub-keys under `feedback:` β warning.- for (const key of Object.keys(rawMap)) {- if (key !== "default_scope") {- warnings.push({- path: source ?? "<config>",- message: `feedback.${key}: unknown field ignored (forward-compat)`,- });- }- }+ warnUnknownKeys(rawMap, ["default_scope"], "feedback", source, warnings);feedback = Object.freeze(partial);}+ // Forward-compat: unknown top-level keys β warning, not error. Runs+ // last (every block above has had a chance to register itself into+ // `knownBlockKeys` via `hasBlock`/`mergeBlock`) so a block can never be+ // parsed-but-not-yet-known at the point this check reads the set. Uses+ // its own message format (distinct from `warnUnknownKeys`'s+ // `block.key: ...` shape), pinned by an existing test.+ for (const key of Object.keys(obj)) {+ if (!knownBlockKeys.has(key)) {+ warnings.push({+ path: source ?? "<config>",+ message: `unknown top-level field '${key}' ignored (forward-compat)`,+ });+ }+ }+const config: BrainConfig = {schema_version: schemaVersion,primary_agent: primaryAgent,@@ -1854,29 +1726,87 @@ export function validateBrainConfigDetailed(* block (string, number, array) is a hard error β the user probably* miswrote the YAML.*/+/**+ * Narrow a raw config value to a plain object, or throw a field-named+ * `BrainConfigError`. Centralizes the "block must be a map of keys" guard+ * that used to be copy-pasted at every optional-block site with two+ * slightly different wordings ("must be a mapping" vs "must be a map of+ * keys") - callers get one consistent message (`BrainConfigError` already+ * prepends the block's `field` name, so the message itself does not repeat+ * it).+ */+function requireMapBlock(+ raw: unknown,+ blockKey: string,+ source: string | null,+): Record<string, unknown> {+ if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {+ throw new BrainConfigError(`must be a map of keys; got ${describe(raw)}`, blockKey, source);+ }+ return raw as Record<string, unknown>;+}++/**+ * Push one forward-compat warning per key in `map` that isn't in `known`.+ * Replaces the per-block loop that used to mix `Set`, chained `!==`, and+ * (elsewhere) `.includes` for the same "unknown sub-key" check, each with+ * its own copy of the `${blockName}.${key}: unknown field ignored+ * (forward-compat)` message.+ */+function warnUnknownKeys(+ map: Readonly<Record<string, unknown>>,+ known: ReadonlySet<string> | ReadonlyArray<string>,+ blockName: string,+ source: string | null,+ warnings: BrainConfigLoadWarning[],+): void {+ const knownSet = known instanceof Set ? known : new Set(known);+ for (const key of Object.keys(map)) {+ if (!knownSet.has(key)) {+ warnings.push({+ path: source ?? "<config>",+ message: `${blockName}.${key}: unknown field ignored (forward-compat)`,+ });+ }+ }+}+function mergeBlock(blockKey: string,raw: unknown,fallback: Readonly<Record<string, number>>,source: string | null,+ knownBlockKeys: Set<string>,): Record<string, unknown> {+ knownBlockKeys.add(blockKey);if (raw === undefined) {return { ...fallback };}- if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {- throw new BrainConfigError(- `block must be a map of keys; got ${describe(raw)}`,- blockKey,- source,- );- }+ const rawMap = requireMapBlock(raw, blockKey, source);const merged: Record<string, unknown> = { ...fallback };- for (const [k, v] of Object.entries(raw as Record<string, unknown>)) {+ for (const [k, v] of Object.entries(rawMap)) {merged[k] = v;}return merged;}+/**+ * Record that this call site checked for `key` at the top level, then+ * report whether it's present. Every top-level block/field presence+ * check (`"vault" in obj`, etc.) MUST go through this - or `mergeBlock`,+ * for the four blocks that merge onto numeric defaults instead of being+ * fully optional - so `knownBlockKeys` can never drift from the set of+ * keys this function actually understands (the bug class fixed in+ * phase 0: four blocks were parsed but missing from a hand-maintained+ * `known` list, so valid config produced a false "unknown field"+ * warning). A key that is never checked can never be "known", by+ * construction - there is no separate list to forget to update.+ */+function hasBlock(obj: Record<string, unknown>, key: string, knownBlockKeys: Set<string>): boolean {+ knownBlockKeys.add(key);+ return key in obj;+}+function requirePositiveInteger(field: string, value: unknown, source: string | null): void {if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {throw new BrainConfigError(`must be a positive integer; got ${describe(value)}`, field, source);diff --git a/src/core/brain/portability/origins.ts b/src/core/brain/portability/origins.tsindex 868f9b76..02f40c18 100644--- a/src/core/brain/portability/origins.ts+++ b/src/core/brain/portability/origins.ts@@ -14,9 +14,9 @@* they never reach the search fan-out.*/-import { statSync } from "node:fs";import { resolve } from "node:path";+import { isDir as isDirectory } from "../../fs-utils.ts";import { listProfiles } from "./profiles.ts";import { listRecallSources } from "./recall-sources.ts";@@ -31,14 +31,6 @@ export interface SearchOrigin {readonly kind: SearchOriginKind;}-function isDirectory(path: string): boolean {- try {- return statSync(path).isDirectory();- } catch {- return false;- }-}-export function listSearchOrigins(configPath: string,activeVault: string,diff --git a/src/core/brain/portability/pointer.ts b/src/core/brain/portability/pointer.tsindex 6bdce59a..83a8f13a 100644--- a/src/core/brain/portability/pointer.ts+++ b/src/core/brain/portability/pointer.ts@@ -18,10 +18,11 @@* it without a cycle - same constraint as `profiles.ts`.*/-import { existsSync, mkdirSync, readFileSync, rmSync, statSync } from "node:fs";+import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";import { dirname, join, resolve, sep } from "node:path";import { atomicWriteFileSync } from "../../fs-atomic.ts";+import { isDir as isDirectory } from "../../fs-utils.ts";export const VAULT_POINTER_FILE = ".o2b-vault.json";@@ -41,14 +42,6 @@ export interface PointerProbe {readonly error: string | null;}-function isDirectory(path: string): boolean {- try {- return statSync(path).isDirectory();- } catch {- return false;- }-}-function assertNotInsideVault(projectDir: string, vault: string): void {const project = resolve(projectDir);const vaultAbs = resolve(vault);diff --git a/src/core/brain/portability/recall-sources.ts b/src/core/brain/portability/recall-sources.tsindex 6c156ba8..a498d189 100644--- a/src/core/brain/portability/recall-sources.ts+++ b/src/core/brain/portability/recall-sources.ts@@ -13,10 +13,11 @@* Standalone module (no import of config.ts), same as `profiles.ts`.*/-import { existsSync, mkdirSync, readFileSync, statSync } from "node:fs";+import { existsSync, mkdirSync, readFileSync } from "node:fs";import { dirname, join, resolve } from "node:path";import { atomicWriteFileSync } from "../../fs-atomic.ts";+import { isDir as isDirectory } from "../../fs-utils.ts";export interface RecallSource {readonly alias: string;@@ -37,14 +38,6 @@ export function recallSourcesPath(configPath: string): string {return join(dirname(configPath), "recall-sources.json");}-function isDirectory(path: string): boolean {- try {- return statSync(path).isDirectory();- } catch {- return false;- }-}-function loadRegistry(configPath: string,opts: { tolerateParseError?: boolean } = {},diff --git a/src/core/brain/query-demand.ts b/src/core/brain/query-demand.tsindex 2234afd7..4e749293 100644--- a/src/core/brain/query-demand.ts+++ b/src/core/brain/query-demand.ts@@ -24,16 +24,11 @@* rolling and byte-budget-capped (see {@link DEMAND_LOG_MAX_BYTES}).*/-import {- appendFileSync,- existsSync,- mkdirSync,- readFileSync,- statSync,- writeFileSync,-} from "node:fs";+import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";import { dirname } from "node:path";+import { atomicWriteFileSync } from "../fs-atomic.ts";+import { clamp01 } from "../math.ts";import { ensureInsideVault } from "../path-safety.ts";import { redactRawOutput } from "../redactor.ts";import { queryDemandLogPath } from "./paths.ts";@@ -430,13 +425,7 @@ function compactIfNeeded(path: string): void {bytes += lineBytes;}kept.reverse();- writeFileSync(path, kept.length > 0 ? `${kept.join("\n")}\n` : "", { encoding: "utf8" });-}--function clamp01(value: number): number {- if (value < 0) return 0;- if (value > 1) return 1;- return value;+ atomicWriteFileSync(path, kept.length > 0 ? `${kept.join("\n")}\n` : "");}/**diff --git a/src/core/brain/schema-pack.ts b/src/core/brain/schema-pack.tsindex 88b016db..a96bbf54 100644--- a/src/core/brain/schema-pack.ts+++ b/src/core/brain/schema-pack.ts@@ -1,5 +1,6 @@import { existsSync, readFileSync } from "node:fs";+import { escapeRegex } from "../strings.ts";import { brainConfigPath } from "./paths.ts";import {SCHEMA_VOCAB_CATEGORIES,@@ -432,7 +433,3 @@ function unique(values: ReadonlyArray<string>): string[] {}return out;}--function escapeRegex(value: string): string {- return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");-}diff --git a/src/core/brain/secrets/exec.ts b/src/core/brain/secrets/exec.tsindex 56bc1d99..3d5714fd 100644--- a/src/core/brain/secrets/exec.ts+++ b/src/core/brain/secrets/exec.ts@@ -11,6 +11,7 @@import { redactRawOutput } from "../../redactor.ts";import { appendAuditRecord } from "../../reliability/audit.ts";+import { escapeRegex } from "../../strings.ts";import { brainDirs } from "../paths.ts";import { join } from "node:path";import { resolveSecretForExec, type SecretAuditContext } from "./store.ts";@@ -44,14 +45,7 @@ export interface RunWithSecretResult {/** Glob match: `*` is the only metacharacter, everything else literal. */export function matchesAllowlist(allow: ReadonlyArray<string>, command: string): boolean {return allow.some((pattern) => {- const re = new RegExp(- "^" +- pattern- .split("*")- .map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))- .join(".*") +- "$",- );+ const re = new RegExp("^" + pattern.split("*").map(escapeRegex).join(".*") + "$");return re.test(command);});}diff --git a/src/core/brain/signal.ts b/src/core/brain/signal.tsindex 906b5f4b..966efc5c 100644--- a/src/core/brain/signal.ts+++ b/src/core/brain/signal.ts@@ -357,14 +357,7 @@ export function parseSignal(path: string, options: ParseSignalOptions = {}): Bra// Optional fields. `scope` is a plain scalar; `source` is an inline// array of wikilink strings. `raw` is extracted from the body if the// canonical heading is present.- let scope: string | undefined;- if (meta["scope"] !== undefined) {- const s = meta["scope"];- if (typeof s !== "string") {- throw new Error(`signal field 'scope' must be a string (${path})`);- }- if (s.trim()) scope = s.trim();- }+ const scope = readOptionalTrimmedString(meta, "scope", path);let source: ReadonlyArray<string> | undefined;if (meta["source"] !== undefined) {@@ -424,25 +417,8 @@ export function parseSignal(path: string, options: ParseSignalOptions = {}): Bra}}- let dedup_hash: string | undefined;- if (meta["dedup_hash"] !== undefined) {- const v = meta["dedup_hash"];- if (typeof v !== "string") {- throw new Error(`signal field 'dedup_hash' must be a string (${path})`);- }- const trimmed = v.trim();- if (trimmed) dedup_hash = trimmed;- }-- let session_ref: string | undefined;- if (meta["session_ref"] !== undefined) {- const v = meta["session_ref"];- if (typeof v !== "string") {- throw new Error(`signal field 'session_ref' must be a string (${path})`);- }- const trimmed = v.trim();- if (trimmed) session_ref = trimmed;- }+ const dedup_hash = readOptionalTrimmedString(meta, "dedup_hash", path);+ const session_ref = readOptionalTrimmedString(meta, "session_ref", path);const result: BrainSignal = {kind: "brain-signal",@@ -482,26 +458,35 @@ function readBiTemporal(readonly valid_until?: string;readonly recorded_at?: string;} {+ const valid_from = readOptionalTrimmedString(meta, "valid_from", path);+ const valid_until = readOptionalTrimmedString(meta, "valid_until", path);+ const recorded_at = readOptionalTrimmedString(meta, "recorded_at", path);return {- ...readBiTemporalSlot(meta, "valid_from", path),- ...readBiTemporalSlot(meta, "valid_until", path),- ...readBiTemporalSlot(meta, "recorded_at", path),+ ...(valid_from !== undefined ? { valid_from } : {}),+ ...(valid_until !== undefined ? { valid_until } : {}),+ ...(recorded_at !== undefined ? { recorded_at } : {}),};}-function readBiTemporalSlot(+/**+ * Read an optional string frontmatter field, trimmed. Returns `undefined`+ * when the key is absent or trims to empty; throws if present but not a+ * string (a wrong-typed value is a corruption worth surfacing, not+ * something to silently drop). Shared by every optional-string signal+ * field (`scope`, `dedup_hash`, `session_ref`) and the bi-temporal slots.+ */+function readOptionalTrimmedString(meta: ReturnType<typeof parseFrontmatter>[0],- key: "valid_from" | "valid_until" | "recorded_at",+ key: string,path: string,-): Partial<Record<"valid_from" | "valid_until" | "recorded_at", string>> {+): string | undefined {const v = meta[key];- if (v === undefined) return {};+ if (v === undefined) return undefined;if (typeof v !== "string") {throw new Error(`signal field '${key}' must be a string (${path})`);}const trimmed = v.trim();- if (trimmed.length === 0) return {};- return { [key]: trimmed };+ return trimmed.length > 0 ? trimmed : undefined;}// ----- Helpers --------------------------------------------------------------diff --git a/src/core/config.ts b/src/core/config.tsindex a7dfd11d..996a4a9d 100644--- a/src/core/config.ts+++ b/src/core/config.ts@@ -300,6 +300,19 @@ export function resolveSkillsDir(configPath?: string): string | null {return isAbsolute(expanded) ? expanded : resolve(dirname(discovery.path), expanded);}+/**+ * Shared body for a default-OFF boolean config gate: env var (trimmed)+ * wins, falling back to the matching `_brain.yaml`/config key (trimmed);+ * only the literal strings `"true"`/`"1"` are truthy, anything else+ * (including absence) resolves to `false`. Replaces seven copy-pasted+ * resolver bodies that differed only in their env/config key names.+ */+function resolveConfigFlag(envKey: string, configKey: string, configPath?: string): boolean {+ const env = process.env[envKey]?.trim();+ const raw = env || discoverConfig(configPath).data[configKey]?.trim();+ return raw === "true" || raw === "1";+}+/*** Skill-attach triggers gate (Agent Surface Suite). When enabled (default* OFF), the `triggers` field from each skill's SKILL.md frontmatter is@@ -308,9 +321,11 @@ export function resolveSkillsDir(configPath?: string): string | null {* (1x) only.*/export function resolveSkillsAttachTriggers(configPath?: string): boolean {- const env = process.env["OPEN_SECOND_BRAIN_SKILLS_ATTACH_TRIGGERS"]?.trim();- const raw = env || discoverConfig(configPath).data["skills_attach_triggers"]?.trim();- return raw === "true" || raw === "1";+ return resolveConfigFlag(+ "OPEN_SECOND_BRAIN_SKILLS_ATTACH_TRIGGERS",+ "skills_attach_triggers",+ configPath,+ );}/**@@ -320,9 +335,7 @@ export function resolveSkillsAttachTriggers(configPath?: string): boolean {* default per-turn injection stays bit-identical.*/export function resolveSkillAutoAttach(configPath?: string): boolean {- const env = process.env["OPEN_SECOND_BRAIN_SKILL_AUTO_ATTACH"]?.trim();- const raw = env || discoverConfig(configPath).data["skill_auto_attach"]?.trim();- return raw === "true" || raw === "1";+ return resolveConfigFlag("OPEN_SECOND_BRAIN_SKILL_AUTO_ATTACH", "skill_auto_attach", configPath);}/**@@ -332,9 +345,11 @@ export function resolveSkillAutoAttach(configPath?: string): boolean {* pack byte-identical.*/export function resolveSearchFocusContextPack(configPath?: string): boolean {- const env = process.env["OPEN_SECOND_BRAIN_SEARCH_FOCUS_CONTEXT_PACK"]?.trim();- const raw = env || discoverConfig(configPath).data["search_focus_context_pack"]?.trim();- return raw === "true" || raw === "1";+ return resolveConfigFlag(+ "OPEN_SECOND_BRAIN_SEARCH_FOCUS_CONTEXT_PACK",+ "search_focus_context_pack",+ configPath,+ );}/**@@ -345,9 +360,11 @@ export function resolveSearchFocusContextPack(configPath?: string): boolean {* post-compaction re-assertion and stay byte-identical.*/export function resolvePostCompactSurvivalAudit(configPath?: string): boolean {- const env = process.env["OPEN_SECOND_BRAIN_POST_COMPACT_SURVIVAL_AUDIT"]?.trim();- const raw = env || discoverConfig(configPath).data["post_compact_survival_audit"]?.trim();- return raw === "true" || raw === "1";+ return resolveConfigFlag(+ "OPEN_SECOND_BRAIN_POST_COMPACT_SURVIVAL_AUDIT",+ "post_compact_survival_audit",+ configPath,+ );}/**@@ -356,9 +373,7 @@ export function resolvePostCompactSurvivalAudit(configPath?: string): boolean {* `session_handoff: "true"`.*/export function resolveSessionHandoff(configPath?: string): boolean {- const env = process.env["OPEN_SECOND_BRAIN_SESSION_HANDOFF"]?.trim();- const raw = env || discoverConfig(configPath).data["session_handoff"]?.trim();- return raw === "true" || raw === "1";+ return resolveConfigFlag("OPEN_SECOND_BRAIN_SESSION_HANDOFF", "session_handoff", configPath);}/**@@ -406,9 +421,11 @@ export function resolveTriggerCooldownDays(configPath?: string): number {* prompt).*/export function resolveRecallGateTelemetry(configPath?: string): boolean {- const env = process.env["OPEN_SECOND_BRAIN_RECALL_GATE_TELEMETRY"]?.trim();- const raw = env || discoverConfig(configPath).data["recall_gate_telemetry"]?.trim();- return raw === "true" || raw === "1";+ return resolveConfigFlag(+ "OPEN_SECOND_BRAIN_RECALL_GATE_TELEMETRY",+ "recall_gate_telemetry",+ configPath,+ );}/**@@ -482,9 +499,11 @@ function resolveAdequacyMinResults(env: string | undefined, fileValue: string |* a single report when the config gate is off.*/export function resolveGenerationTraceEnabled(configPath?: string): boolean {- const env = process.env["OPEN_SECOND_BRAIN_GENERATION_TRACE_ENABLED"]?.trim();- const raw = env || discoverConfig(configPath).data["generation_trace_enabled"]?.trim();- return raw === "true" || raw === "1";+ return resolveConfigFlag(+ "OPEN_SECOND_BRAIN_GENERATION_TRACE_ENABLED",+ "generation_trace_enabled",+ configPath,+ );}/**diff --git a/src/core/graph/mcp-config.ts b/src/core/graph/mcp-config.tsindex de3930b7..5fe59eb6 100644--- a/src/core/graph/mcp-config.ts+++ b/src/core/graph/mcp-config.ts@@ -18,6 +18,8 @@import { readFileSync, readdirSync, statSync, type Dirent } from "node:fs";import { join } from "node:path";+import { EXCLUDED_DIRS } from "../vault.ts";+/** The config filenames recognised across common MCP hosts. */export const MCP_CONFIG_FILENAMES: ReadonlyArray<string> = Object.freeze([".mcp.json",@@ -28,15 +30,12 @@ export const MCP_CONFIG_FILENAMES: ReadonlyArray<string> = Object.freeze([const FILENAME_SET = new Set<string>(MCP_CONFIG_FILENAMES);-/** Directories never descended into during discovery. */-const SKIP_DIRS = new Set<string>([- ".git",- ".obsidian",- ".trash",- ".stversions",- "node_modules",- ".open-second-brain",-]);+/**+ * Directories never descended into during discovery: the vault-wide+ * exclusions plus two extra dirs specific to config discovery+ * (`node_modules`, `.open-second-brain`).+ */+const SKIP_DIRS = new Set<string>([...EXCLUDED_DIRS, "node_modules", ".open-second-brain"]);/** Commands that take a package reference as their first non-flag argument. */const PACKAGE_RUNNERS = new Set<string>(["npx", "bunx", "pnpx", "uvx", "pipx"]);diff --git a/src/core/math.ts b/src/core/math.tsnew file mode 100644index 00000000..d7be1ff8--- /dev/null+++ b/src/core/math.ts@@ -0,0 +1,12 @@+/**+ * Numeric primitives shared across scoring/ranking code (search relevance,+ * recency decay, brain query-demand). No I/O, no side effects.+ */++/** Clamp `x` to `[0, 1]`. Non-finite input (`NaN`, `Infinity`) clamps to `0`. */+export function clamp01(x: number): number {+ if (!Number.isFinite(x)) return 0;+ if (x < 0) return 0;+ if (x > 1) return 1;+ return x;+}diff --git a/src/core/partner/codegraph.ts b/src/core/partner/codegraph.tsindex 02619581..ef00b6a0 100644--- a/src/core/partner/codegraph.ts+++ b/src/core/partner/codegraph.ts@@ -12,10 +12,11 @@* from config. No deep filesystem walk.*/-import { existsSync, readdirSync, realpathSync, statSync } from "node:fs";+import { existsSync, readdirSync, realpathSync } from "node:fs";import { dirname, join, resolve } from "node:path";import type { CheckResult } from "../types.ts";+import { isDir } from "../fs-utils.ts";import { assessGraphHealth, summarizeGraphHealth } from "./codegraph-health.ts";const CODE_MANIFESTS: ReadonlyArray<string> = [@@ -32,14 +33,6 @@ const CODE_MANIFESTS: ReadonlyArray<string> = [const DEFAULT_LIMIT = 50;-function isDir(path: string): boolean {- try {- return statSync(path).isDirectory();- } catch {- return false;- }-}-/*** Heuristic check: does `dir` look like a code project root?* Requires BOTH a `.git/` directory AND at least one recogniseddiff --git a/src/core/search/evidence-pack.ts b/src/core/search/evidence-pack.tsindex 7b4a2e15..e88ed1c5 100644--- a/src/core/search/evidence-pack.ts+++ b/src/core/search/evidence-pack.ts@@ -226,4 +226,60 @@ export function buildEvidencePack(});}+/**+ * Snake_case wire representation of an {@link EvidencePack}, shared by the+ * CLI (`o2b search`) and MCP (`brain_search`) surfaces so the two never+ * drift on this safety-relevant contract (abstention, coverage).+ */+export function serializeEvidencePack(pack: EvidencePack): Record<string, unknown> {+ return {+ significant_terms: pack.significantTerms,+ matched_terms: pack.matchedTerms,+ missing_terms: pack.missingTerms,+ support_coverage: pack.supportCoverage,+ records: pack.records.map((record) => ({+ path: record.path,+ document_id: record.documentId,+ chunk_id: record.chunkId,+ line_pointer: record.linePointer,+ matched_terms: record.matchedTerms,+ missing_terms: record.missingTerms,+ support_coverage: record.supportCoverage,+ terminal_state: record.terminalState,+ why_retrieved: record.whyRetrieved,+ dropped_candidate_reasons: record.droppedCandidateReasons,+ })),+ dropped_candidates: pack.droppedCandidates,+ abstention: pack.abstention,+ ...(pack.idfWeightedCoverage !== undefined+ ? { idf_weighted_coverage: pack.idfWeightedCoverage }+ : {}),+ ...(pack.rareTerms !== undefined ? { rare_terms: pack.rareTerms } : {}),+ ...(pack.uncoveredRareTerms !== undefined+ ? { uncovered_rare_terms: pack.uncoveredRareTerms }+ : {}),+ ...(pack.unionRecords !== undefined+ ? {+ union_records: pack.unionRecords.map((r) => ({+ term: r.term,+ path: r.path,+ document_id: r.documentId,+ chunk_id: r.chunkId,+ })),+ }+ : {}),+ ...(pack.completeness !== undefined+ ? {+ completeness: {+ verdict: pack.completeness.verdict,+ idf_weighted_coverage: pack.completeness.idfWeightedCoverage,+ covered_terms: pack.completeness.coveredTerms,+ uncovered_terms: pack.completeness.uncoveredTerms,+ uncovered_but_present_in_corpus: pack.completeness.uncoveredButPresentInCorpus,+ },+ }+ : {}),+ };+}+export { buildCoverageReport, significantTerms };diff --git a/src/core/search/index.ts b/src/core/search/index.tsindex 28605c1c..912ec4d6 100644--- a/src/core/search/index.ts+++ b/src/core/search/index.ts@@ -71,7 +71,8 @@ export {type SearchSessionFocus,} from "./session-focus.ts";export { evaluateSurfacingGate, type SurfacingGateDecision } from "./surfacing-gate.ts";-export { buildEvidencePack, type EvidencePack } from "./evidence-pack.ts";+export { buildEvidencePack, serializeEvidencePack, type EvidencePack } from "./evidence-pack.ts";+export { serializeSearchCard, serializeIndexStatus } from "./serialize.ts";export {loadProviderRegistry,addProviderProfile,@@ -104,7 +105,7 @@ export {type IndexVaultOptions,type IndexProgressEvent,} from "./indexer.ts";-export { search, expandHit } from "./search.ts";+export { search, expandHit, SEARCH_LIMIT_MIN, SEARCH_LIMIT_MAX } from "./search.ts";export {captureRecallFeedback,computeLearnedWeights,@@ -223,6 +224,12 @@ function parseFiniteFloat(raw: string | null, fallback: number, fieldName: strin}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}'`);+ }if (range?.min !== undefined && n < range.min) {throw new SearchError("INVALID_INPUT", `${fieldName} must be >= ${range.min}, got ${n}`);}diff --git a/src/core/search/ranker.ts b/src/core/search/ranker.tsindex 2f3a69df..a20ed07f 100644--- a/src/core/search/ranker.ts+++ b/src/core/search/ranker.ts@@ -9,6 +9,7 @@* testable and substitutable.*/+import { clamp01 } from "../math.ts";import { PAGE_TIER_DEFAULT, tierWeight, type PageTier } from "../brain/page-meta/tier.ts";import { weibullDecay, DEFAULT_RECENCY, type WeibullRecencyOptions } from "./recency.ts";import { scoreSessionFocusTarget, type SearchSessionFocus } from "./session-focus.ts";@@ -106,13 +107,6 @@ export interface RankerOptions {const DAY_MS = 24 * 60 * 60 * 1000;-function clamp01(x: number): number {- if (!Number.isFinite(x)) return 0;- if (x < 0) return 0;- if (x > 1) return 1;- return x;-}-/** Min-max normalise BM25 within the candidate set. Lower BM25 is better. */function normalizeBm25(hits: ReadonlyArray<KeywordHit>): Map<number, number> {const out = new Map<number, number>();diff --git a/src/core/search/recency.ts b/src/core/search/recency.tsindex 72225b30..2ce53192 100644--- a/src/core/search/recency.ts+++ b/src/core/search/recency.ts@@ -20,6 +20,8 @@* injectable at the ranker boundary.*/+import { clamp01 } from "../math.ts";+export interface WeibullRecencyOptions {/** Weibull shape parameter k (> 0). Lower values decay faster early. */readonly shape: number;@@ -48,13 +50,6 @@ export const DEFAULT_RECENCY: WeibullRecencyOptions = Object.freeze({*/const EPSILON = 0.0005;-function clamp01(x: number): number {- if (!Number.isFinite(x)) return 0;- if (x < 0) return 0;- if (x > 1) return 1;- return x;-}-/*** Recency boost for a content age in days under a Weibull curve. Ages at* or below 0 (including future timestamps) yield the full amplitude.diff --git a/src/core/search/relation-polarity.ts b/src/core/search/relation-polarity.tsindex 238e01a8..63254669 100644--- a/src/core/search/relation-polarity.ts+++ b/src/core/search/relation-polarity.ts@@ -20,6 +20,7 @@* without typed relations are unaffected.*/+import { clamp01 } from "../math.ts";import type { BrainSearchResult } from "./types.ts";/** Multiplier applied to a matched predecessor's score. */@@ -88,13 +89,6 @@ interface Mutable {positiveBoost: number;}-function clamp01(x: number): number {- if (!Number.isFinite(x)) return 0;- if (x < 0) return 0;- if (x > 1) return 1;- return x;-}-function fmt(x: number): string {return x.toFixed(3);}diff --git a/src/core/search/search.ts b/src/core/search/search.tsindex 10b812df..94b9e8b1 100644--- a/src/core/search/search.ts+++ b/src/core/search/search.ts@@ -13,6 +13,7 @@ import { statSync } from "node:fs";import { join } from "node:path";import { parseFrontmatter } from "../vault.ts";+import type { FrontmatterMap } from "../types.ts";import { isVisible, normalizeVisibilityScope, pageVisibility } from "../graph/visibility.ts";import { isOwnerVisible, normalizeAgentScope, pageOwner } from "../graph/agent-scope.ts";import { makeProvider } from "./embeddings/provider.ts";@@ -225,6 +226,48 @@ async function openReadOrSelfHeal(config: ResolvedSearchConfig): Promise<Store>}}+/**+ * Bounds for the public `limit` option. CLI validates against the same+ * ceiling before calling in; MCP applies its own, lower `MCP_LIMIT_MAX`+ * (token-budget conscious) - the two ceilings are deliberately different,+ * this just gives the shared one a name instead of a bare `100` literal.+ */+export const SEARCH_LIMIT_MIN = 1;+export const SEARCH_LIMIT_MAX = 100;++/**+ * Semantic candidate-pool over-fetch policy: rank more than `limit` rows+ * so downstream filtering (property/visibility scope, MMR diversify) has+ * enough headroom to still fill the final window. `floor` is the minimum+ * pool size regardless of `limit`; `overfetch` is the multiplier applied+ * to `limit` itself.+ */+const POOL_OVERFETCH = 5;+const POOL_FLOOR = 50;++function semanticPoolSize(limit: number): number {+ return Math.max(limit * POOL_OVERFETCH, POOL_FLOOR);+}++/**+ * One frontmatter read per (vault, path) pair, shared across every filter+ * stage of a single `search()` call. `parseFrontmatter` never throws (a+ * read failure resolves to empty metadata internally), so caching the raw+ * result changes no call site's fallback behaviour - it only stops the+ * same file being read and parsed once per stage instead of once total.+ */+function readCachedFrontmatter(+ cache: Map<string, FrontmatterMap>,+ vault: string,+ path: string,+): FrontmatterMap {+ const cached = cache.get(path);+ if (cached !== undefined) return cached;+ const [meta] = parseFrontmatter(join(vault, path));+ cache.set(path, meta);+ return meta;+}+export async function search(config: ResolvedSearchConfig,opts: SearchOptions,@@ -245,7 +288,7 @@ export async function search(profileParams ?? (config.recall.selfTuningEnabled ? loadTunedParameters(config.vault) : null);if (tuned !== null) config = applyTunedParameters(config, tuned);const expandActive = opts.expand ?? (tuned !== null && tuned.expansion);- const limit = Math.max(1, Math.min(100, opts.limit ?? 10));+ const limit = Math.max(SEARCH_LIMIT_MIN, Math.min(SEARCH_LIMIT_MAX, opts.limit ?? 10));if (opts.threshold !== undefined && (!Number.isFinite(opts.threshold) || opts.threshold < 0)) {throw new SearchError("INVALID_INPUT", "threshold must be a finite number >= 0");}@@ -271,6 +314,11 @@ export async function search(? await Store.open(config, { mode: "read" }): await openReadOrSelfHeal(config);try {+ // Shared across every frontmatter-reading filter stage below (Plan 1,+ // 1.3) so a candidate path already read by one stage is not re-read+ // and re-parsed by the next.+ const frontmatterCache = new Map<string, FrontmatterMap>();+// Opt-in local expansion (t_2fa95db1): an explicit structured// document always wins; expansion only fills the gap. The lex lane's// corpus-common tokens are derived from document frequency here@@ -410,7 +458,7 @@ export async function search(}if (policy.wantSemantic) {const semOutcome = await runSemanticPhase(store, config, semanticLaneQuery ?? query, {- limit: Math.max(limit * 5, 50),+ limit: semanticPoolSize(limit),pathPrefix,explicit: policy.explicit,});@@ -448,7 +496,7 @@ export async function search(if (validityWindowCache.has(path)) return validityWindowCache.get(path) ?? null;let window: ValidityWindow | null = null;try {- const [meta] = parseFrontmatter(join(config.vault, path));+ const meta = readCachedFrontmatter(frontmatterCache, config.vault, path);window = parseValidityWindow(meta as Record<string, unknown>);} catch {window = null;@@ -474,7 +522,7 @@ export async function search(if (terms.length >= 2) {const broadened = runFtsQueryDetailed(store, terms[0]!, {expandedTerms: terms.slice(1),- limit: Math.max(limit * 5, 50),+ limit: semanticPoolSize(limit),pathPrefix: pathPrefix ?? null,});for (const w of broadened.warnings) warnings.push(w);@@ -530,7 +578,7 @@ export async function search(if (plan.fire) {const targeted = runFtsQueryDetailed(store, plan.terms[0]!, {expandedTerms: plan.terms.slice(1),- limit: Math.max(limit * 5, 50),+ limit: semanticPoolSize(limit),pathPrefix: pathPrefix ?? null,});for (const w of targeted.warnings) warnings.push(w);@@ -638,7 +686,7 @@ export async function search(if (cached !== undefined) return cached;let fmKind: string | null = null;try {- const [meta] = parseFrontmatter(join(config.vault, path));+ const meta = readCachedFrontmatter(frontmatterCache, config.vault, path);const raw = (meta as Record<string, unknown>)["kind"];fmKind = typeof raw === "string" ? raw : null;} catch {@@ -714,7 +762,7 @@ export async function search(seenDocs.add(h.documentId);if (!h.path.startsWith("Brain/preferences/")) continue;try {- const [meta] = parseFrontmatter(join(config.vault, h.path));+ const meta = readCachedFrontmatter(frontmatterCache, config.vault, h.path);const trend = parseFreshnessTrend((meta as Record<string, unknown>)["freshness_trend"]);if (trend !== null) byDoc.set(h.documentId, trend);} catch {@@ -769,7 +817,7 @@ export async function search(const maxHops = opts.maxHops ?? config.recall.maxHops;const traversalActive = maxHops > 0;const baseRankLimit =- hasFrontmatterFilter || hasStructuredExclusions ? Math.max(limit * 5, 50) : limit;+ hasFrontmatterFilter || hasStructuredExclusions ? semanticPoolSize(limit) : limit;const rankLimit =mmrActive || traversalActive || crossEncoderActive? Math.max(baseRankLimit, limit * 3, 30, crossEncoderActive ? config.rerank.topK : 0)@@ -869,13 +917,20 @@ export async function search(// drops pages outside the requested visibility scope. Caching by// document path bounds the read cost to the result set.const propFiltered = hasPropertyFilter- ? applyPropertyFilter(ranked, opts.properties!, config.vault)+ ? applyPropertyFilter(ranked, opts.properties!, config.vault, frontmatterCache): ranked;- const visible = applyVisibilityScope(propFiltered, visibilityScope, config.vault);+ const visible = applyVisibilityScope(+ propFiltered,+ visibilityScope,+ config.vault,+ frontmatterCache,+ );// Agent-ownership isolation (Unit 5): only when a scope is requested;// a null scope skips the filter entirely (byte-identical default).const scoped =- agentScope !== null ? applyAgentScope(visible, agentScope, config.vault) : visible;+ agentScope !== null+ ? applyAgentScope(visible, agentScope, config.vault, frontmatterCache)+ : visible;return { preVisibility: propFiltered.length, visible: scoped, capHit };};@@ -893,7 +948,7 @@ export async function search(assembled.visible.length < assembled.preVisibility &&assembled.capHit) {- const wideCap = Math.max(limit * 5, 50, limit * 3, 30);+ const wideCap = Math.max(semanticPoolSize(limit), limit * 3, 30);if (wideCap > rankLimit) assembled = assemble(wideCap);}const excluded = applyStructuredExclusions(assembled.visible, structured);@@ -991,7 +1046,7 @@ export async function search(// in evidence-pack mode.const terminalPaths =opts.evidencePack === true- ? buildTerminalPaths(config.vault, withSecondPassReasons)+ ? buildTerminalPaths(config.vault, withSecondPassReasons, frontmatterCache): new Set<string>();const finalResults =opts.evidencePack === true@@ -1275,6 +1330,7 @@ function highFrequencyTokens(store: Store, query: string): ReadonlySet<string> {function buildTerminalPaths(vault: string,results: ReadonlyArray<BrainSearchResult>,+ frontmatterCache: Map<string, FrontmatterMap>,): ReadonlySet<string> {const terminal = new Set<string>();const seen = new Set<string>();@@ -1282,7 +1338,7 @@ function buildTerminalPaths(if (seen.has(r.path)) continue;seen.add(r.path);try {- const [meta] = parseFrontmatter(join(vault, r.path));+ const meta = readCachedFrontmatter(frontmatterCache, vault, r.path);if (isTerminalStatus((meta as Record<string, unknown>)["status"])) terminal.add(r.path);} catch {// Unreadable frontmatter is non-terminal.@@ -1440,16 +1496,12 @@ function applyPropertyFilter(ranked: ReadonlyArray<BrainSearchResult>,filters: ReadonlyMap<string, ReadonlyArray<string>>,vault: string,+ frontmatterCache: Map<string, FrontmatterMap>,): ReadonlyArray<BrainSearchResult> {- const cache = new Map<string, Record<string, unknown> | null>();const reader = (path: string): Record<string, unknown> | null => {- if (cache.has(path)) return cache.get(path) ?? null;try {- const [meta] = parseFrontmatter(join(vault, path));- cache.set(path, meta as Record<string, unknown>);- return meta as Record<string, unknown>;+ return readCachedFrontmatter(frontmatterCache, vault, path) as Record<string, unknown>;} catch {- cache.set(path, null);return null;}};@@ -1487,20 +1539,14 @@ function applyVisibilityScope(ranked: ReadonlyArray<BrainSearchResult>,scope: ReadonlySet<string>,vault: string,+ frontmatterCache: Map<string, FrontmatterMap>,): ReadonlyArray<BrainSearchResult> {- const cache = new Map<string, string[]>();const tagsFor = (path: string): string[] => {- const cached = cache.get(path);- if (cached) return cached;- let tags: string[] = [];try {- const [meta] = parseFrontmatter(join(vault, path));- tags = pageVisibility(meta);+ return pageVisibility(readCachedFrontmatter(frontmatterCache, vault, path));} catch {- tags = [];+ return [];}- cache.set(path, tags);- return tags;};return ranked.filter((r) => isVisible(tagsFor(r.path), scope));}@@ -1509,25 +1555,19 @@ function applyAgentScope(ranked: ReadonlyArray<BrainSearchResult>,scope: string,vault: string,+ frontmatterCache: Map<string, FrontmatterMap>,): ReadonlyArray<BrainSearchResult> {// Fail-closed sentinel: a page whose frontmatter cannot be parsed has// an unknowable owner, so under an active scope it is dropped rather// than leaked. This is stricter than visibility scoping's fail-open// default - deliberate, because agent-scope is an isolation boundary.const UNPARSEABLE = " unparseable-owner";- const cache = new Map<string, string>();const ownerFor = (path: string): string => {- const cached = cache.get(path);- if (cached !== undefined) return cached;- let owner: string;try {- const [meta] = parseFrontmatter(join(vault, path));- owner = pageOwner(meta) ?? "";+ return pageOwner(readCachedFrontmatter(frontmatterCache, vault, path)) ?? "";} catch {- owner = UNPARSEABLE;+ return UNPARSEABLE;}- cache.set(path, owner);- return owner;};return ranked.filter((r) => {const owner = ownerFor(r.path);diff --git a/src/core/search/serialize.ts b/src/core/search/serialize.tsnew file mode 100644index 00000000..34d25d38--- /dev/null+++ b/src/core/search/serialize.ts@@ -0,0 +1,49 @@+/**+ * Snake_case wire serializers shared by the CLI (`o2b search`) and MCP+ * (`brain_search`) surfaces, so the two output contracts cannot drift+ * field-by-field the way independently hand-written copies do.+ */++import type { IndexStatusSnapshot, SearchCard } from "./types.ts";++/** Layer-1 card projection - identical shape on both the CLI and MCP surfaces. */+export function serializeSearchCard(c: SearchCard): Record<string, unknown> {+ return {+ path: c.path,+ title: c.title,+ score: c.score,+ snippet: c.snippet,+ pointer: c.pointer,+ reasons: c.reasons,+ document_id: c.documentId,+ chunk_id: c.chunkId,+ ...(c.origin !== undefined ? { origin: c.origin } : {}),+ };+}++/**+ * Full snake_case index-status mapping. The CLI surfaces every field; the+ * MCP block (token-budget conscious) picks a subset of the returned object+ * rather than re-declaring the mapping.+ */+export function serializeIndexStatus(s: IndexStatusSnapshot): Record<string, unknown> {+ return {+ index_path: s.indexPath,+ exists: s.exists,+ schema_version: s.schemaVersion,+ documents: s.documents,+ chunks: s.chunks,+ embeddings: s.embeddings,+ stale_embeddings: s.staleEmbeddings,+ embedding_model: s.embeddingModel,+ embedding_dimension: s.embeddingDimension,+ embedding_signature: s.embeddingSignature,+ estimated_refresh_cost_usd: s.estimatedRefreshCostUsd,+ vec_extension: s.vecExtension,+ semantic_enabled: s.semanticEnabled,+ embedding_key_present: s.embeddingKeyPresent,+ last_indexed_at: s.lastIndexedAt,+ last_full_index_at: s.lastFullIndexAt,+ warnings: s.warnings,+ };+}diff --git a/src/core/search/store.ts b/src/core/search/store.tsindex 0f06ca58..acddc569 100644--- a/src/core/search/store.ts+++ b/src/core/search/store.ts@@ -206,6 +206,11 @@ function nowIso(): string {return new Date().toISOString();}+/** `?,?,...` placeholder list for a SQL `IN (...)` clause of `items.length` params. */+function sqlPlaceholders(items: ReadonlyArray<unknown>): string {+ return items.map(() => "?").join(",");+}+/*** Stale window for the writer lock (ms). A lock whose mtime is older* than this is treated as abandoned (crashed holder) and taken over by@@ -703,7 +708,7 @@ export class Store {this.db.exec("BEGIN");try {this.purgeVecRowsByChunkIds(chunkIds);- const placeholders = chunkIds.map(() => "?").join(",");+ const placeholders = sqlPlaceholders(chunkIds);this.db.run(`DELETE FROM chunks WHERE id IN (${placeholders})`, chunkIds as number[]);this.db.exec("COMMIT");} catch (e) {@@ -725,7 +730,7 @@ export class Store {private purgeVecRowsByChunkIds(chunkIds: ReadonlyArray<number>): void {if (!this._vecLoaded || chunkIds.length === 0) return;- const placeholders = chunkIds.map(() => "?").join(",");+ const placeholders = sqlPlaceholders(chunkIds);const vecRows = this.db.query<{ vec_rowid: number }, number[]>(`SELECT vec_rowid FROM chunk_vec_map WHERE chunk_id IN (${placeholders})`,@@ -737,7 +742,7 @@ export class Store {private purgeVecRowidsRaw(vecRowids: number[]): void {if (!this._vecLoaded || vecRowids.length === 0) return;- const placeholders = vecRowids.map(() => "?").join(",");+ const placeholders = sqlPlaceholders(vecRowids);this.db.run(`DELETE FROM chunk_vec WHERE rowid IN (${placeholders})`, vecRowids);}@@ -1094,7 +1099,7 @@ export class Store {): Map<number, Array<{ relation: string; target: string }>> {const out = new Map<number, Array<{ relation: string; target: string }>>();if (documentIds.length === 0) return out;- const placeholders = documentIds.map(() => "?").join(",");+ const placeholders = sqlPlaceholders(documentIds);const rows = this.db.query<{@@ -1138,7 +1143,7 @@ export class Store {readonly targetDocumentId: number | null;}> {if (documentIds.length === 0) return [];- const placeholders = documentIds.map(() => "?").join(",");+ const placeholders = sqlPlaceholders(documentIds);const rows = this.db.query<{@@ -1566,7 +1571,7 @@ export class Store {hydrateChunks(chunkIds: ReadonlyArray<number>): Map<number, HydratedChunk> {const out = new Map<number, HydratedChunk>();if (chunkIds.length === 0) return out;- const placeholders = chunkIds.map(() => "?").join(",");+ const placeholders = sqlPlaceholders(chunkIds);const rows = this.db.query<{@@ -1610,7 +1615,7 @@ export class Store {inboundLinkSources(candidateChunkIds: ReadonlyArray<number>): Map<number, Set<number>> {const out = new Map<number, Set<number>>();if (candidateChunkIds.length === 0) return out;- const placeholders = candidateChunkIds.map(() => "?").join(",");+ const placeholders = sqlPlaceholders(candidateChunkIds);const rows = this.db.query<{ chunk_id: number; source_document_id: number }, number[]>("SELECT c.id AS chunk_id, l.source_document_id " +@@ -1639,7 +1644,7 @@ export class Store {outboundLinkTargets(sourceDocumentIds: ReadonlyArray<number>): Map<number, number[]> {const out = new Map<number, number[]>();if (sourceDocumentIds.length === 0) return out;- const placeholders = sourceDocumentIds.map(() => "?").join(",");+ const placeholders = sqlPlaceholders(sourceDocumentIds);const rows = this.db.query<{ source_document_id: number; target_document_id: number }, number[]>("SELECT DISTINCT l.source_document_id, l.target_document_id " +@@ -1671,7 +1676,7 @@ export class Store {representativeChunks(documentIds: ReadonlyArray<number>): Map<number, HydratedChunk> {const out = new Map<number, HydratedChunk>();if (documentIds.length === 0) return out;- const placeholders = documentIds.map(() => "?").join(",");+ const placeholders = sqlPlaceholders(documentIds);const rows = this.db.query<{@@ -1762,8 +1767,8 @@ export class Store {): Map<number, number> {const out = new Map<number, number>();if (candidateChunkIds.length === 0 || queryEntities.length === 0) return out;- const chunkPlaceholders = candidateChunkIds.map(() => "?").join(",");- const entityPlaceholders = queryEntities.map(() => "?").join(",");+ const chunkPlaceholders = sqlPlaceholders(candidateChunkIds);+ const entityPlaceholders = sqlPlaceholders(queryEntities);const rows = this.db.query<{ chunk_id: number; c: number }, (number | string)[]>("SELECT chunk_id, COUNT(DISTINCT entity) AS c FROM chunk_entities " +@@ -1782,7 +1787,7 @@ export class Store {tagsByChunkDocument(candidateChunkIds: ReadonlyArray<number>): Map<number, Set<string>> {const out = new Map<number, Set<string>>();if (candidateChunkIds.length === 0) return out;- const placeholders = candidateChunkIds.map(() => "?").join(",");+ const placeholders = sqlPlaceholders(candidateChunkIds);const rows = this.db.query<{ chunk_id: number; tag: string }, number[]>("SELECT c.id AS chunk_id, l.link_text AS tag " +diff --git a/src/mcp/brain/brief-tools.ts b/src/mcp/brain/brief-tools.tsindex 3cda958d..efb45f89 100644--- a/src/mcp/brain/brief-tools.ts+++ b/src/mcp/brain/brief-tools.ts@@ -31,23 +31,28 @@ import { MCP_PREVIEW_BUDGET } from "../preview-budget.ts";import { coerceIsoDate, coerceFormat } from "../coerce.ts";import {coerceIsoTimestampOrDate,+ coercePositiveInteger,dispatchByView,localizeEnvelope,- optionalPositiveInt,} from "./shared.ts";async function toolBrainMorningBrief(ctx: ServerContext,args: Record<string, unknown>,): Promise<Record<string, unknown>> {- const topK = optionalPositiveInt(args, "top_k", "brain_brief view=morning") ?? 10;- const lookbackDays = optionalPositiveInt(args, "lookback_days", "brain_brief view=morning") ?? 7;- const maxCharsPerMemory = optionalPositiveInt(- args,+ const topK = coercePositiveInteger("brain_brief view=morning", "top_k", args["top_k"]) ?? 10;+ const lookbackDays =+ coercePositiveInteger("brain_brief view=morning", "lookback_days", args["lookback_days"]) ?? 7;+ const maxCharsPerMemory = coercePositiveInteger(+ "brain_brief view=morning","max_chars_per_memory",+ args["max_chars_per_memory"],+ );+ const maxTotalChars = coercePositiveInteger("brain_brief view=morning",+ "max_total_chars",+ args["max_total_chars"],);- const maxTotalChars = optionalPositiveInt(args, "max_total_chars", "brain_brief view=morning");const now = new Date();const brief = buildMorningBrief(ctx.vault, {now,diff --git a/src/mcp/brain/derive-tools.ts b/src/mcp/brain/derive-tools.tsindex 8b2d8e0a..b67a655e 100644--- a/src/mcp/brain/derive-tools.ts+++ b/src/mcp/brain/derive-tools.ts@@ -14,9 +14,10 @@import { deriveFact, DeriveFactError } from "../../core/brain/derived-fact.ts";import { loadGuardrailsConfigSafe } from "../../core/brain/policy.ts";import { asProvenanceLevel } from "../../core/brain/provenance/provenance.ts";-import { INTERNAL_ERROR, INVALID_PARAMS, MCPError } from "../protocol.ts";+import { INVALID_PARAMS, MCPError } from "../protocol.ts";import type { ServerContext, ToolDefinition } from "../tools.ts";import { coerceStr, coerceStrList } from "../coerce.ts";+import { wrapToolErrors } from "./shared.ts";const TOOL = "brain_derive_fact";@@ -24,41 +25,34 @@ async function toolBrainDeriveFact(ctx: ServerContext,args: Record<string, unknown>,): Promise<Record<string, unknown>> {- if (!loadGuardrailsConfigSafe(ctx.vault).derived_fact_synthesis) {- throw new MCPError(- INVALID_PARAMS,- `${TOOL}: derived-fact synthesis is off; enable guardrails.derived_fact_synthesis in _brain.yaml`,- );- }+ return wrapToolErrors(TOOL, [DeriveFactError], async () => {+ if (!loadGuardrailsConfigSafe(ctx.vault).derived_fact_synthesis) {+ throw new MCPError(+ INVALID_PARAMS,+ `${TOOL}: derived-fact synthesis is off; enable guardrails.derived_fact_synthesis in _brain.yaml`,+ );+ }- const slug = coerceStr(args, "slug", true)!;- const topic = coerceStr(args, "topic", true)!;- const principle = coerceStr(args, "principle", true)!;- const levelRaw = coerceStr(args, "level", true)!;- const level = asProvenanceLevel(levelRaw);- if (level === null || level === "stated") {- throw new MCPError(INVALID_PARAMS, `${TOOL}: 'level' must be 'deduced' or 'inferred'`);- }- const premises = coerceStrList(args, "premises");- if (premises.length === 0) {- throw new MCPError(INVALID_PARAMS, `${TOOL}: 'premises' must list at least one premise id`);- }+ const slug = coerceStr(args, "slug", true)!;+ const topic = coerceStr(args, "topic", true)!;+ const principle = coerceStr(args, "principle", true)!;+ const levelRaw = coerceStr(args, "level", true)!;+ const level = asProvenanceLevel(levelRaw);+ if (level === null || level === "stated") {+ throw new MCPError(INVALID_PARAMS, `${TOOL}: 'level' must be 'deduced' or 'inferred'`);+ }+ const premises = coerceStrList(args, "premises");+ if (premises.length === 0) {+ throw new MCPError(INVALID_PARAMS, `${TOOL}: 'premises' must list at least one premise id`);+ }- try {const res = deriveFact(ctx.vault,{ slug, topic, principle, premises, level },{ now: new Date() },);return { id: res.id, level, premises };- } catch (err) {- if (err instanceof DeriveFactError) {- throw new MCPError(INVALID_PARAMS, `${TOOL}: ${err.message}`);- }- if (err instanceof MCPError) throw err;- const reason = err instanceof Error ? err.message : String(err);- throw new MCPError(INTERNAL_ERROR, `${TOOL}: ${reason}`);- }+ });}export const DERIVE_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([diff --git a/src/mcp/brain/ingest-tools.ts b/src/mcp/brain/ingest-tools.tsindex b1b89a00..fdbf6c34 100644--- a/src/mcp/brain/ingest-tools.ts+++ b/src/mcp/brain/ingest-tools.ts@@ -12,10 +12,10 @@import { ingestSource } from "../../core/brain/ingest/ingest.ts";import { IntakeValidationError } from "../../core/brain/intake/extract-intake.ts";import { resolveAgentName } from "../../core/config.ts";-import { INTERNAL_ERROR, INVALID_PARAMS, MCPError } from "../protocol.ts";import type { ServerContext, ToolDefinition } from "../tools.ts";import { coerceStr } from "../coerce.ts";import { parseExtractionIntakeArgs } from "./intake-args.ts";+import { wrapToolErrors } from "./shared.ts";const TOOL = "brain_ingest_source";@@ -31,7 +31,7 @@ async function toolBrainIngestSource(? parsed.agent: resolveAgentName(ctx.configPath ?? undefined);- try {+ return wrapToolErrors(TOOL, [IntakeValidationError], async () => {const res = ingestSource(ctx.vault,{ sourcePath, summary, extraction: parsed.intake },@@ -44,14 +44,7 @@ async function toolBrainIngestSource(entities_updated: [...res.entitiesUpdated],connections: [...res.connections],};- } catch (err) {- if (err instanceof IntakeValidationError) {- throw new MCPError(INVALID_PARAMS, `${TOOL}: ${err.message}`);- }- if (err instanceof MCPError) throw err;- const reason = err instanceof Error ? err.message : String(err);- throw new MCPError(INTERNAL_ERROR, `${TOOL}: ${reason}`);- }+ });}export const INGEST_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([diff --git a/src/mcp/brain/intake-args.ts b/src/mcp/brain/intake-args.tsindex dbecbc67..f1379a07 100644--- a/src/mcp/brain/intake-args.ts+++ b/src/mcp/brain/intake-args.ts@@ -28,11 +28,11 @@ export interface ParsedIntakeArgs {readonly agent?: string;}-function isRecord(value: unknown): value is Record<string, unknown> {+export function isRecord(value: unknown): value is Record<string, unknown> {return typeof value === "object" && value !== null && !Array.isArray(value);}-function requiredString(value: unknown, tool: string, field: string): string {+export function requiredString(value: unknown, tool: string, field: string): string {if (typeof value !== "string" || value.trim().length === 0) {throw new MCPError(INVALID_PARAMS, `${tool}: '${field}' must be a non-empty string`);}diff --git a/src/mcp/brain/knowledge-tools.ts b/src/mcp/brain/knowledge-tools.tsindex e1c6c94e..01eebff1 100644--- a/src/mcp/brain/knowledge-tools.ts+++ b/src/mcp/brain/knowledge-tools.ts@@ -45,7 +45,7 @@ import { INVALID_PARAMS, MCPError } from "../protocol.ts";import type { ServerContext, ToolDefinition } from "../tools.ts";import { MCP_PREVIEW_BUDGET } from "../preview-budget.ts";import { coerceStr, coerceBool } from "../coerce.ts";-import { optionalPositiveInt } from "./shared.ts";+import { coercePositiveInteger } from "./shared.ts";/** Forward-looking projection envelope; read-only fold. */function toolBrainForesight(@@ -320,7 +320,7 @@ async function toolBrainDeepSynthesis(args: Record<string, unknown>,): Promise<Record<string, unknown>> {const topic = coerceStr(args, "topic", true)!;- const limit = optionalPositiveInt(args, "limit", "brain_deep_synthesis") ?? 30;+ const limit = coercePositiveInteger("brain_deep_synthesis", "limit", args["limit"]) ?? 30;if (limit > 100) {throw new MCPError(INVALID_PARAMS, "brain_deep_synthesis: limit must be at most 100");}@@ -370,7 +370,7 @@ function toolBrainIdeaDiscovery(ctx: ServerContext,args: Record<string, unknown>,): Record<string, unknown> {- const cap = optionalPositiveInt(args, "cap", "brain_idea_discovery") ?? 5;+ const cap = coercePositiveInteger("brain_idea_discovery", "cap", args["cap"]) ?? 5;if (cap > 50) {throw new MCPError(INVALID_PARAMS, "brain_idea_discovery: cap must be at most 50");}diff --git a/src/mcp/brain/ner-tools.ts b/src/mcp/brain/ner-tools.tsindex e21a4a57..5edc2ef5 100644--- a/src/mcp/brain/ner-tools.ts+++ b/src/mcp/brain/ner-tools.ts@@ -16,9 +16,9 @@import { intakeExtraction, IntakeValidationError } from "../../core/brain/intake/extract-intake.ts";import { resolveAgentName } from "../../core/config.ts";-import { INTERNAL_ERROR, INVALID_PARAMS, MCPError } from "../protocol.ts";import type { ServerContext, ToolDefinition } from "../tools.ts";import { parseExtractionIntakeArgs } from "./intake-args.ts";+import { wrapToolErrors } from "./shared.ts";const TOOL = "brain_intake_entities";@@ -31,7 +31,9 @@ async function toolBrainIntakeEntities(parsed.agent && parsed.agent.trim().length > 0? parsed.agent: resolveAgentName(ctx.configPath ?? undefined);- try {+ // A malformed extraction is a client-resolvable input problem, not a+ // server fault - surface it as INVALID_PARAMS, never a fabricated result.+ return wrapToolErrors(TOOL, [IntakeValidationError], async () => {const result = intakeExtraction(ctx.vault, parsed.intake, {agent,now: new Date(),@@ -42,16 +44,7 @@ async function toolBrainIntakeEntities(entities_updated: [...result.entitiesUpdated],relations_applied: result.relationsApplied,};- } catch (err) {- // A malformed extraction is a client-resolvable input problem, not a- // server fault - surface it as INVALID_PARAMS, never a fabricated result.- if (err instanceof IntakeValidationError) {- throw new MCPError(INVALID_PARAMS, `${TOOL}: ${err.message}`);- }- if (err instanceof MCPError) throw err;- const reason = err instanceof Error ? err.message : String(err);- throw new MCPError(INTERNAL_ERROR, `${TOOL}: ${reason}`);- }+ });}export const NER_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([diff --git a/src/mcp/brain/pack-tools.ts b/src/mcp/brain/pack-tools.tsindex 8cc2ab45..f4106214 100644--- a/src/mcp/brain/pack-tools.ts+++ b/src/mcp/brain/pack-tools.ts@@ -45,7 +45,6 @@ import { MCP_PREVIEW_BUDGET } from "../preview-budget.ts";import { coerceStr, coerceStrList, coerceBool } from "../coerce.ts";import {coercePositiveInteger,- optionalPositiveInt,optionalStringArg,requiredStringArg,telemetryOptionsFromArgs,@@ -59,14 +58,8 @@ async function toolBrainContextPack(ctx: ServerContext,args: Record<string, unknown>,): Promise<Record<string, unknown>> {- const maxRaw = args["max_tokens"];- const maxTokens =- typeof maxRaw === "number"- ? maxRaw- : typeof maxRaw === "string" && /^[0-9]+$/.test(maxRaw.trim())- ? Number.parseInt(maxRaw.trim(), 10)- : Number.NaN;- if (!Number.isInteger(maxTokens) || maxTokens <= 0) {+ const maxTokens = coercePositiveInteger("brain_context_pack", "max_tokens", args["max_tokens"]);+ if (maxTokens === undefined) {throw new MCPError(INVALID_PARAMS, "brain_context_pack: max_tokens must be a positive integer");}const query = typeof args["query"] === "string" ? (args["query"] as string) : undefined;@@ -74,8 +67,16 @@ async function toolBrainContextPack(const cacheStable = coerceBool(args, "cache_stable");const dedupRepeated = coerceBool(args, "dedup_repeated");const attentionFlowIds = coerceStrList(args, "attention_flow_ids");- const maxCharsPerMemory = optionalPositiveInt(args, "max_chars_per_memory", "brain_context_pack");- const maxTotalChars = optionalPositiveInt(args, "max_total_chars", "brain_context_pack");+ const maxCharsPerMemory = coercePositiveInteger(+ "brain_context_pack",+ "max_chars_per_memory",+ args["max_chars_per_memory"],+ );+ const maxTotalChars = coercePositiveInteger(+ "brain_context_pack",+ "max_total_chars",+ args["max_total_chars"],+ );const receipt = receiptOptionsFromArgs("brain_context_pack", args, "context_pack", "mcp");const telemetry = telemetryOptionsFromArgs("brain_context_pack", args, "mcp");// Adequacy verdict (t_b8f66fec): when the caller passes the recall@@ -386,13 +387,17 @@ async function toolBrainPreCompressPack(ctx: ServerContext,args: Record<string, unknown>,): Promise<Record<string, unknown>> {- const topK = optionalPositiveInt(args, "top_k", "brain_pre_compress_pack") ?? 10;- const maxCharsPerMemory = optionalPositiveInt(- args,+ const topK = coercePositiveInteger("brain_pre_compress_pack", "top_k", args["top_k"]) ?? 10;+ const maxCharsPerMemory = coercePositiveInteger(+ "brain_pre_compress_pack","max_chars_per_memory",+ args["max_chars_per_memory"],+ );+ const maxTotalChars = coercePositiveInteger("brain_pre_compress_pack",+ "max_total_chars",+ args["max_total_chars"],);- const maxTotalChars = optionalPositiveInt(args, "max_total_chars", "brain_pre_compress_pack");const receipt = receiptOptionsFromArgs("brain_pre_compress_pack", args, "pre_compress", "mcp");const telemetry = telemetryOptionsFromArgs("brain_pre_compress_pack", args, "mcp");const pack = buildPreCompressPack(ctx.vault, {diff --git a/src/mcp/brain/procedure-tools.ts b/src/mcp/brain/procedure-tools.tsindex b32d6535..c5817a39 100644--- a/src/mcp/brain/procedure-tools.ts+++ b/src/mcp/brain/procedure-tools.ts@@ -29,7 +29,7 @@ import {import { INVALID_PARAMS, MCPError } from "../protocol.ts";import type { ServerContext, ToolDefinition } from "../tools.ts";import { coerceStrList } from "../coerce.ts";-import { optionalPositiveInt, optionalStringArg, requiredStringArg } from "./shared.ts";+import { coercePositiveInteger, optionalStringArg, requiredStringArg } from "./shared.ts";async function toolBrainSkillProposals(ctx: ServerContext,@@ -37,7 +37,11 @@ async function toolBrainSkillProposals(): Promise<Record<string, unknown>> {const operation = requiredStringArg("brain_skill_proposals", args, "operation");if (operation === "learn") {- const minSupport = optionalPositiveInt(args, "min_support", "brain_skill_proposals");+ const minSupport = coercePositiveInteger(+ "brain_skill_proposals",+ "min_support",+ args["min_support"],+ );const result =minSupport !== undefined? learnSkillProposals(ctx.vault, { minSupport })diff --git a/src/mcp/brain/research-tools.ts b/src/mcp/brain/research-tools.tsindex 8f43f97f..17b0dc17 100644--- a/src/mcp/brain/research-tools.ts+++ b/src/mcp/brain/research-tools.ts@@ -14,26 +14,19 @@ import {type ResearchFinding,} from "../../core/brain/research/research.ts";import { resolveAgentName } from "../../core/config.ts";-import { INTERNAL_ERROR, INVALID_PARAMS, MCPError } from "../protocol.ts";+import { INVALID_PARAMS, MCPError } from "../protocol.ts";import type { ServerContext, ToolDefinition } from "../tools.ts";import { coerceStr } from "../coerce.ts";+import { isRecord, requiredString } from "./intake-args.ts";+import { wrapToolErrors } from "./shared.ts";const TOOL = "brain_research_report";-function isRecord(value: unknown): value is Record<string, unknown> {- return typeof value === "object" && value !== null && !Array.isArray(value);-}-function reqStringList(value: unknown, field: string): string[] {if (!Array.isArray(value) || value.length === 0) {throw new MCPError(INVALID_PARAMS, `${TOOL}: '${field}' must be a non-empty array of strings`);}- return value.map((item, i) => {- if (typeof item !== "string" || item.trim().length === 0) {- throw new MCPError(INVALID_PARAMS, `${TOOL}: '${field}[${i}]' must be a non-empty string`);- }- return item;- });+ return value.map((item, i) => requiredString(item, TOOL, `${field}[${i}]`));}function parseFinding(value: unknown, i: number): ResearchFinding {@@ -68,7 +61,7 @@ async function toolBrainResearchReport(? agentArg: resolveAgentName(ctx.configPath ?? undefined);- try {+ return wrapToolErrors(TOOL, [ResearchValidationError], async () => {const res = writeResearchReport(ctx.vault,{ title, sources, findings },@@ -79,14 +72,7 @@ async function toolBrainResearchReport(created: res.created,finding_count: res.findingCount,};- } catch (err) {- if (err instanceof ResearchValidationError) {- throw new MCPError(INVALID_PARAMS, `${TOOL}: ${err.message}`);- }- if (err instanceof MCPError) throw err;- const reason = err instanceof Error ? err.message : String(err);- throw new MCPError(INTERNAL_ERROR, `${TOOL}: ${reason}`);- }+ });}export const RESEARCH_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([diff --git a/src/mcp/brain/shared.ts b/src/mcp/brain/shared.tsindex f6fac703..18ff08b6 100644--- a/src/mcp/brain/shared.ts+++ b/src/mcp/brain/shared.ts@@ -9,12 +9,39 @@ import { resolveTimezone } from "../../core/config.ts";import { type RecallTelemetryOptions } from "../../core/brain/recall-telemetry.ts";import { isoSecond } from "../../core/brain/time.ts";import { formatLocalTimestamp } from "../../core/brain/present-time.ts";-import { INVALID_PARAMS, MCPError } from "../protocol.ts";+import { INTERNAL_ERROR, INVALID_PARAMS, MCPError } from "../protocol.ts";import type { ServerContext } from "../tools.ts";import { coerceBool } from "../coerce.ts";export const ISO_DATE_ONLY_RE = /^\d{4}-\d{2}-\d{2}$/;+/**+ * Run a tool handler body, classifying a thrown error into the right MCP+ * error code: a client-resolvable input problem (any class in+ * `validationClasses`, or an already-typed `MCPError`) surfaces as+ * `INVALID_PARAMS`; anything else is a server fault (`INTERNAL_ERROR`).+ * This mapping is safety-relevant - it decides whether the CALLER or the+ * SERVER is blamed for a failure - and was previously copy-pasted+ * identically across derive-tools, ingest-tools, ner-tools, and+ * research-tools, one drift away from silently reclassifying an error.+ */+export async function wrapToolErrors<T>(+ tool: string,+ validationClasses: ReadonlyArray<new (...args: never[]) => Error>,+ fn: () => Promise<T>,+): Promise<T> {+ try {+ return await fn();+ } catch (err) {+ if (validationClasses.some((cls) => err instanceof cls)) {+ throw new MCPError(INVALID_PARAMS, `${tool}: ${(err as Error).message}`);+ }+ if (err instanceof MCPError) throw err;+ const reason = err instanceof Error ? err.message : String(err);+ throw new MCPError(INTERNAL_ERROR, `${tool}: ${reason}`);+ }+}+export function coerceIsoTimestampOrDate(tool: string,field: string,@@ -111,26 +138,6 @@ export function localizeEnvelope(ctx: ServerContext, result: unknown): unknown {};}-/** Parse an optional positive-integer arg, throwing INVALID_PARAMS otherwise. */-export function optionalPositiveInt(- args: Record<string, unknown>,- key: string,- tool: string,-): number | undefined {- const raw = args[key];- if (raw === undefined) return undefined;- const n =- typeof raw === "number"- ? raw- : typeof raw === "string" && /^[0-9]+$/.test(raw.trim())- ? Number.parseInt(raw.trim(), 10)- : Number.NaN;- if (!Number.isInteger(n) || n <= 0) {- throw new MCPError(INVALID_PARAMS, `${tool}: ${key} must be a positive integer`);- }- return n;-}-export function optionalStringArg(tool: string,args: Record<string, unknown>,diff --git a/src/mcp/coerce.ts b/src/mcp/coerce.tsindex 36f6bd00..c2f376b6 100644--- a/src/mcp/coerce.ts+++ b/src/mcp/coerce.ts@@ -7,7 +7,6 @@*/import { INVALID_PARAMS, MCPError } from "./protocol.ts";-import { parseOptionalFiniteNumberInput } from "../core/validate.ts";export function coerceStr(args: Record<string, unknown>,@@ -51,17 +50,6 @@ export function coerceInt(return value;}-export function coerceOptionalNumber(args: Record<string, unknown>, key: string): number | null {- const parsed = parseOptionalFiniteNumberInput(args[key]);- if (parsed.error === "finite-number") {- throw new MCPError(INVALID_PARAMS, `argument '${key}' must be a finite number`);- }- if (parsed.error === "number-or-numeric-string") {- throw new MCPError(INVALID_PARAMS, `argument '${key}' must be a number or numeric string`);- }- return parsed.value;-}-export function coerceBool(args: Record<string, unknown>, key: string): boolean {const value = args[key];if (value === undefined || value === null) return false;diff --git a/src/mcp/search-tools.ts b/src/mcp/search-tools.tsindex 48588e27..6b5ca0a0 100644--- a/src/mcp/search-tools.ts+++ b/src/mcp/search-tools.ts@@ -18,6 +18,9 @@ import {resolveSearchConfig,search,SearchError,+ serializeEvidencePack,+ serializeSearchCard,+ serializeIndexStatus,} from "../core/search/index.ts";import { normalizeSessionFocus, parseStructuredRecallQueryDocument } from "../core/search/index.ts";import type { BrainSearchResult, SearchOutcome } from "../core/search/index.ts";@@ -634,24 +637,10 @@ async function toolBrainSearch(...(outcome.evidencePack ? { why_retrieved: r.reasons } : {}),...(r.relations && r.relations.length > 0 ? { relations: r.relations } : {}),})),- ...(outcome.cards- ? {- cards: outcome.cards.map((c) => ({- path: c.path,- title: c.title,- score: c.score,- snippet: c.snippet,- pointer: c.pointer,- reasons: c.reasons,- document_id: c.documentId,- chunk_id: c.chunkId,- ...(c.origin !== undefined ? { origin: c.origin } : {}),- })),- }- : {}),+ ...(outcome.cards ? { cards: outcome.cards.map(serializeSearchCard) } : {}),warnings: outcome.warnings,total: outcome.total,- ...(outcome.evidencePack ? { evidence_pack: mcpEvidencePack(outcome.evidencePack) } : {}),+ ...(outcome.evidencePack ? { evidence_pack: serializeEvidencePack(outcome.evidencePack) } : {}),...(recallHint !== null ? { recall_hint: recallHint } : {}),...(telemetryRecord ? { telemetry_id: telemetryRecord.id } : {}),};@@ -666,59 +655,6 @@ function searchTelemetryGaps(outcome: SearchOutcome): ReadonlyArray<string> {return [...gaps];}-function mcpEvidencePack(- pack: NonNullable<SearchOutcome["evidencePack"]>,-): Record<string, unknown> {- return {- significant_terms: pack.significantTerms,- matched_terms: pack.matchedTerms,- missing_terms: pack.missingTerms,- support_coverage: pack.supportCoverage,- records: pack.records.map((record) => ({- path: record.path,- document_id: record.documentId,- chunk_id: record.chunkId,- line_pointer: record.linePointer,- matched_terms: record.matchedTerms,- missing_terms: record.missingTerms,- support_coverage: record.supportCoverage,- terminal_state: record.terminalState,- why_retrieved: record.whyRetrieved,- dropped_candidate_reasons: record.droppedCandidateReasons,- })),- dropped_candidates: pack.droppedCandidates,- abstention: pack.abstention,- ...(pack.idfWeightedCoverage !== undefined- ? { idf_weighted_coverage: pack.idfWeightedCoverage }- : {}),- ...(pack.rareTerms !== undefined ? { rare_terms: pack.rareTerms } : {}),- ...(pack.uncoveredRareTerms !== undefined- ? { uncovered_rare_terms: pack.uncoveredRareTerms }- : {}),- ...(pack.unionRecords !== undefined- ? {- union_records: pack.unionRecords.map((r) => ({- term: r.term,- path: r.path,- document_id: r.documentId,- chunk_id: r.chunkId,- })),- }- : {}),- ...(pack.completeness !== undefined- ? {- completeness: {- verdict: pack.completeness.verdict,- idf_weighted_coverage: pack.completeness.idfWeightedCoverage,- covered_terms: pack.completeness.coveredTerms,- uncovered_terms: pack.completeness.uncoveredTerms,- uncovered_but_present_in_corpus: pack.completeness.uncoveredButPresentInCorpus,- },- }- : {}),- };-}-async function toolBrainRecallGate(ctx: ServerContext,args: Record<string, unknown>,@@ -1284,22 +1220,15 @@ export async function buildSearchStatusBlock(ctx: ServerContext): Promise<Recordif (!snap.exists) {return { exists: false, hint: "run: o2b search index" };}- return {- index_path: snap.indexPath,- exists: true,- schema_version: snap.schemaVersion,- documents: snap.documents,- chunks: snap.chunks,- embeddings: snap.embeddings,- stale_embeddings: snap.staleEmbeddings,- embedding_model: snap.embeddingModel,- embedding_dimension: snap.embeddingDimension,- vec_extension: snap.vecExtension,- semantic_enabled: snap.semanticEnabled,- embedding_key_present: snap.embeddingKeyPresent,- last_indexed_at: snap.lastIndexedAt,- last_full_index_at: snap.lastFullIndexAt,- };+ // Token-budget conscious: pick the MCP subset out of the shared+ // serializer's full field set rather than re-declaring the mapping.+ const {+ embedding_signature: _embeddingSignature,+ estimated_refresh_cost_usd: _estimatedRefreshCostUsd,+ warnings: _warnings,+ ...rest+ } = serializeIndexStatus(snap);+ return rest;} catch (e) {return { exists: false, error: e instanceof Error ? e.message : String(e) };}diff --git a/tests/cli/search-rerank-provider-cli.test.ts b/tests/cli/search-rerank-provider-cli.test.tsnew file mode 100644index 00000000..b9cff5d3--- /dev/null+++ b/tests/cli/search-rerank-provider-cli.test.ts@@ -0,0 +1,100 @@+/**+ * CLI tests for `o2b search rerank-provider <add|list|show|remove>`.+ *+ * Mirrors search-provider-cli.test.ts: the two commands share+ * `runProviderRegistryCommand` (src/cli/search.ts) over structurally+ * identical registries, so this pins the rerank-provider verb's own+ * usage/output strings and persisted-file path.+ */++import { afterEach, beforeEach, expect, test } from "bun:test";+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import { runCli } from "../helpers/run-cli.ts";++let tmp: string;+let vault: string;+let config: string;++beforeEach(() => {+ tmp = mkdtempSync(join(tmpdir(), "o2b-rerank-provider-cli-"));+ vault = join(tmp, "vault");+ mkdirSync(vault, { recursive: true });+ config = join(tmp, "config.yaml");+ writeFileSync(config, `vault: "${vault}"\n`);+});++afterEach(() => {+ rmSync(tmp, { recursive: true, force: true });+});++const env = () => ({ OPEN_SECOND_BRAIN_CONFIG: config });+const addArgs = [+ "search",+ "rerank-provider",+ "add",+ "cohere-rerank",+ "--base-url",+ "https://api.cohere.ai/v1",+ "--model",+ "rerank-english-v3.0",+ "--env-key",+ "COHERE_API_KEY",+];++test("rerank-provider add then list shows the registered profile", async () => {+ const add = await runCli(addArgs, { env: env() });+ expect(add.returncode).toBe(0);+ expect(existsSync(join(vault, "Brain", "search", "rerank-providers.json"))).toBe(true);++ const list = await runCli(["search", "rerank-provider", "list"], { env: env() });+ expect(list.returncode).toBe(0);+ expect(list.stdout).toContain("cohere-rerank");+});++test("rerank-provider list --json returns the profile array", async () => {+ await runCli(addArgs, { env: env() });+ const list = await runCli(["search", "rerank-provider", "list", "--json"], { env: env() });+ expect(list.returncode).toBe(0);+ const arr = JSON.parse(list.stdout);+ expect(Array.isArray(arr)).toBe(true);+ expect(arr[0]).toMatchObject({+ name: "cohere-rerank",+ baseUrl: "https://api.cohere.ai/v1",+ defaultModel: "rerank-english-v3.0",+ envKey: "COHERE_API_KEY",+ });+});++test("rerank-provider show prints a single profile", async () => {+ await runCli(addArgs, { env: env() });+ const show = await runCli(["search", "rerank-provider", "show", "cohere-rerank", "--json"], {+ env: env(),+ });+ expect(show.returncode).toBe(0);+ expect(JSON.parse(show.stdout)).toMatchObject({ name: "cohere-rerank" });+});++test("rerank-provider remove deletes the profile", async () => {+ await runCli(addArgs, { env: env() });+ const rm = await runCli(["search", "rerank-provider", "remove", "cohere-rerank"], {+ env: env(),+ });+ expect(rm.returncode).toBe(0);+ const list = await runCli(["search", "rerank-provider", "list", "--json"], { env: env() });+ expect(JSON.parse(list.stdout)).toEqual([]);+});++test("rerank-provider add with missing required flags fails with exit 2", async () => {+ const add = await runCli(["search", "rerank-provider", "add", "incomplete"], { env: env() });+ expect(add.returncode).toBe(2);+ expect(add.stderr).toContain("rerank-provider add requires");+});++test("rerank-provider show of an unknown name exits non-zero", async () => {+ const show = await runCli(["search", "rerank-provider", "show", "ghost"], { env: env() });+ expect(show.returncode).not.toBe(0);+ expect(show.stderr).toContain("no registered rerank provider named");+});diff --git a/tests/core/brain.policy.test.ts b/tests/core/brain.policy.test.tsindex ad099439..9b61fa0c 100644--- a/tests/core/brain.policy.test.ts+++ b/tests/core/brain.policy.test.ts@@ -420,6 +420,20 @@ describe("validateBrainConfig β warnings (forward-compat)", () => {);expect(result.warnings.length).toBe(0);});++ test("health/hygiene/anticipatory/recall blocks are known top-level keys", () => {+ const result = validateBrainConfigDetailed(+ {+ schema_version: 1,+ health: {},+ hygiene: {},+ anticipatory: {},+ recall: {},+ },+ "<test>",+ );+ expect(result.warnings.length).toBe(0);+ });});describe("validateBrainConfig β vault block (v0.10.9)", () => {diff --git a/tests/core/math.test.ts b/tests/core/math.test.tsnew file mode 100644index 00000000..2144eb8a--- /dev/null+++ b/tests/core/math.test.ts@@ -0,0 +1,22 @@+import { describe, expect, test } from "bun:test";++import { clamp01 } from "../../src/core/math.ts";++describe("clamp01", () => {+ test("passes values already in [0, 1] through unchanged", () => {+ expect(clamp01(0)).toBe(0);+ expect(clamp01(1)).toBe(1);+ expect(clamp01(0.42)).toBe(0.42);+ });++ test("clamps below 0 and above 1", () => {+ expect(clamp01(-0.5)).toBe(0);+ expect(clamp01(1.5)).toBe(1);+ });++ test("clamps non-finite input to 0", () => {+ expect(clamp01(NaN)).toBe(0);+ expect(clamp01(Infinity)).toBe(0);+ expect(clamp01(-Infinity)).toBe(0);+ });+});diff --git a/tests/core/search/config.test.ts b/tests/core/search/config.test.tsindex 89cc5a40..ead61568 100644--- a/tests/core/search/config.test.ts+++ b/tests/core/search/config.test.ts@@ -323,6 +323,19 @@ test("overrides are validated after merging", () => {).toThrow(/embedding_batch_size/);});+test("a NaN integer override is rejected instead of silently passing range checks", () => {+ // `NaN < min` and `NaN > max` are both false, so an integer-range check+ // that only compares bounds would let a NaN override through unnoticed.+ writeFileSync(configPath, `vault: "${tmp}"\n`);+ expect(() =>+ resolveSearchConfig({+ vault: tmp,+ configPath,+ overrides: { semantic: { concurrency: Number.NaN } },+ }),+ ).toThrow(/embedding_concurrency/);+});+// ββ Indexer Durability suite: shutdown grace + resume flag ββββββββββββββββββtest("durability keys default to a 5s grace and no resume", () => {