Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript

refactor: DRY and decomposition (Phases 0-2) (#121)

Sol Aitken67bcb71cff75
diff --git a/.gitignore b/.gitignore
index 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.ts
index 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.ts
index 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;
}
// add
if (!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.ts
index 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.ts
index 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.ts
index 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): DigestData
retiredEntries.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): DigestData
merge_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.ts
index 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): v
else 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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 recognised
diff --git a/src/core/search/evidence-pack.ts b/src/core/search/evidence-pack.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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<Record
if (!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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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", () => {