Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Source resolution for CLI commands (v0.18.0).
*
* Resolution priority (highest first):
* 1. Explicit --source <id> flag (caller passes this as `explicit`)
* 2. GBRAIN_SOURCE env var
* 3. .gbrain-source dotfile in CWD or any ancestor directory
* 4. Registered source whose local_path contains CWD
* 5. Brain-level default via `gbrain sources default <id>`
* 6. Literal 'default' (backward compat for pre-v0.17 brains)
*
* This helper is shared by the sources CLI, future sync/extract/query
* commands (Steps 4/5), and the operation layer (Step 2+).
*/
import { readFileSync, lstatSync, type Stats } from 'fs';
import { syncDispatchRow } from './sync-dispatch-read.ts';
import { join, dirname, isAbsolute, resolve } from 'path';
import type { BrainEngine } from './engine.ts';
import { requestSnapshotRead } from './config-snapshot.ts';
import type { ExplicitReadBinding } from './ops/contract.ts';
import { isSourceFederated, parseSourceConfig } from './sources-load.ts';
import { SOURCE_ID_RE, isValidSourceId, ALL_SOURCES } from './source-id.ts';
import { isTrustedDotfile, realpathOrResolve, realpathOrResolveAsync } from './path-confine.ts';
import { noteResolvedSource } from './fix-routing.ts';
import { hookSessionCwd } from './session-cwd.ts';
// Re-export so scope-resolution call sites can import the sentinel from
// either module (#1712).
export { ALL_SOURCES };
/** A caller-selected source id is invalid, missing, or archived. */
export class SourceTargetError extends Error {
constructor(message: string) {
super(message);
this.name = 'SourceTargetError';
}
}
const DOTFILE = '.gbrain-source';
// Canonical SOURCE_ID_RE imported from `source-id.ts` (single source of truth).
// Re-exported below as `__testing.SOURCE_ID_RE` for legacy test imports.
// Two validator shapes per codex r2 P1-F:
// - `isValidSourceId(s)`: boolean — used by tiers that silently fall through
// on invalid input (dotfile tier 3, brain_default tier 5)
// - explicit throw — used by tiers that must reject loudly with a tailored
// message (explicit `--source` flag tier 1, GBRAIN_SOURCE env tier 2).
// Tier-specific messages are clearer than the generic assertValidSourceId
// error, so the throws stay inline.
/** GBRAIN_SOURCE for this resolution: a caller-supplied value (even unset) wins over this process's env. */
function ambientSourceEnv(opts: { env?: string }): string | undefined {
return Object.hasOwn(opts, 'env') ? opts.env : process.env.GBRAIN_SOURCE;
}
function readDotfileWalk(startDir: string): string | null {
let dir = resolve(startDir);
// Guard against infinite loops on malformed paths.
for (let i = 0; i < 50; i++) {
const candidate = join(dir, DOTFILE);
// lstatSync (NOT statSync) so a planted symlink is seen here, not silently
// followed-then-trusted. Any stat error (ENOENT / permission) → skip this
// candidate and keep walking (fail-closed). On a multi-user host an
// attacker who can write a shared ancestor dir could otherwise plant a
// forged `.gbrain-source`; `isTrustedDotfile` refuses symlinks,
// foreign-owned, and world-writable files (#418).
let st: Stats | null = null;
try { st = lstatSync(candidate); } catch { st = null; }
if (st && isTrustedDotfile(st)) {
try {
const content = readFileSync(candidate, 'utf8').trim().split('\n')[0].trim();
// Silent-fallback tier per codex P1-F: invalid dotfile content
// (legacy ids with underscores, hand-edits with whitespace, etc.)
// falls through to the next tier instead of throwing. The CLI's
// explicit/env tiers throw; dotfiles are operator-edited and the
// forgiving behavior preserves the resolver's existing semantics.
if (isValidSourceId(content)) return content;
} catch {
// Unreadable dotfile — skip and keep walking.
}
}
const parent = dirname(dir);
if (parent === dir) break; // reached filesystem root
dir = parent;
}
return null;
}
/**
* Resolve the source id for a CLI command.
*
* @param engine Connected brain engine (for sources table lookups).
* @param explicit The --source <id> flag value, if the caller parsed one.
* @param cwd The working directory to walk for .gbrain-source. Defaults
* to process.cwd(). Exposed for testability.
* @returns The resolved source id. Falls back to 'default' if no other
* signal is present. Never returns null — every command must
* target exactly one default source.
* @throws If the resolved id doesn't correspond to a registered source
* (prevents silently writing to a nonexistent source and bloating
* pages with a dead FK).
*/
/**
* Tier-4 shared core: "registered source whose local_path contains CWD",
* longest-prefix-wins. Realpaths BOTH sides (not bare resolve) so a
* symlinked CWD can't forge a prefix match against a registered local_path
* it doesn't really live under (codex #9); `realpathOrResolveAsync` falls
* back to lexical resolve() for a stale registration whose path no longer
* exists.
*
* All N `local_path` realpaths (plus cwd's) resolve via `Promise.all`
* (#4091-class fix): a synchronous `realpathSync` loop blocks the event
* loop for the FULL duration of every call in sequence, so wrapping the
* sync calls in `Promise.all` doesn't parallelize anything — a single slow
* or interrupted filesystem path (network mount, macOS on-access security
* scan, degraded disk) still serializes the whole tier behind itself times
* the registered-source count. The async realpath here truly overlaps I/O
* across sources, so the tier's cost is bounded by the SLOWEST single
* source, not their sum.
*
* Shared by `resolveSourceId` and `resolveSourceWithTier` so the two
* resolution-chain entry points can't drift on this tier (mirrors how
* `pickSoleNonDefaultSource` is already shared for tier 5.5).
*/
async function resolveRegisteredPathMatch(
registered: RegisteredSource[],
cwd: string,
): Promise<{ id: string; path: string; pathLen: number } | null> {
registered = registered.filter(r => isAbsolute(r.local_path));
if (registered.length === 0) return null;
const [cwdResolved, resolvedPaths] = await Promise.all([
realpathOrResolveAsync(cwd),
Promise.all(registered.map(r => realpathOrResolveAsync(r.local_path))),
]);
// #3880: ACTIVE sources win the prefix match — an archived (deeper)
// registration must not shadow an active parent source. When cwd lands
// ONLY in archived trees, the caller's assertSourceExists still throws
// (explicit unavailable target — never silent continuation). The paths
// are already resolved above, so the tiering is a pure in-memory pass.
for (const archivedTier of [false, true]) {
let best: { id: string; path: string; pathLen: number } | null = null;
for (let i = 0; i < registered.length; i++) {
if ((registered[i].archived === true) !== archivedTier) continue;
const p = resolvedPaths[i];
if (cwdResolved === p || cwdResolved.startsWith(p + '/')) {
if (!best || p.length > best.pathLen) {
best = { id: registered[i].id, path: p, pathLen: p.length };
}
}
}
if (best) return best;
}
return null;
}
/**
* Tier 4 alone: the active registered source whose local_path contains `cwd` (deepest wins, an archived registration
* never shadows an active parent), or null. The deferred corpus-session resolution accepts only this evidence (#7868).
*/
export async function resolveRegisteredLocalPathSource(engine: BrainEngine, cwd: string): Promise<string | null> {
const registered = await listRegisteredLocalPathSources(engine);
const best = await resolveRegisteredPathMatch(registered, cwd);
return best && registered.find(r => r.id === best.id)?.archived !== true ? best.id : null;
}
export async function resolveSourceId(
engine: BrainEngine,
explicit: string | null | undefined,
cwd: string = hookSessionCwd(),
// Local IPC already evaluated the client's flag/env/dotfile tiers. The
// owner's environment must never redirect that client's unscoped request.
// `env` stands in for GBRAIN_SOURCE when a resident serve resolves for a
// CLI caller (the warm CLI socket): the caller's value, never the serve's.
opts: { skipLocalSignals?: boolean; env?: string } = {},
): Promise<string> {
const id = await resolveSourceIdChain(engine, explicit, cwd, opts);
if (!opts.skipLocalSignals) noteResolvedSource(id);
return id;
}
/** GBRA-133: `seen.registered` receives the tier-4 listing when the chain reached it, so a caller needs no second read of it. */
async function resolveSourceIdChain(
engine: BrainEngine,
explicit: string | null | undefined,
cwd: string,
opts: { skipLocalSignals?: boolean; env?: string },
seen: { registered?: RegisteredSource[] } = {},
): Promise<string> {
// 1. Explicit flag wins. The __all__ sentinel passes through verbatim
// (#1712) — it is not a source id, so it skips both the regex and
// assertSourceExists; sourceScopeOpts gives it span-everything semantics.
if (explicit) {
if (explicit === ALL_SOURCES) return ALL_SOURCES;
if (!SOURCE_ID_RE.test(explicit)) {
throw new SourceTargetError(`Invalid --source value "${explicit}". Must match [a-z0-9-]{1,32}.`);
}
await assertSourceExists(engine, explicit);
return explicit;
}
// 2. Env var. Same __all__ pass-through (#2140).
const env = opts.skipLocalSignals ? undefined : ambientSourceEnv(opts);
if (env && env.length > 0) {
if (env === ALL_SOURCES) return ALL_SOURCES;
if (!SOURCE_ID_RE.test(env)) {
throw new SourceTargetError(`Invalid GBRAIN_SOURCE value "${env}". Must match [a-z0-9-]{1,32}.`);
}
await assertSourceExists(engine, env);
return env;
}
// 3. .gbrain-source dotfile walk-up.
const dotfile = opts.skipLocalSignals ? null : readDotfileWalk(cwd);
if (dotfile) {
await assertSourceExists(engine, dotfile);
return dotfile;
}
// 4. Registered source whose local_path contains CWD.
// Uses longest-prefix match so nested-path configurations (e.g.
// gstack at ~/gstack + plans at ~/gstack/plans) pick the deepest.
// #3880 active-over-archived tiering + parallel realpath both live in
// the shared resolveRegisteredPathMatch helper.
// GBRA-133: tier 5's config read is independent of the listing, so it is sent with it (unused when tier 4 wins).
const defaultRead = engine.getConfig('sources.default');
defaultRead.catch(() => {});
const registered = seen.registered = await listRegisteredLocalPathSources(engine);
const best = await resolveRegisteredPathMatch(registered, cwd);
if (best) {
// A local_path registration can outlive source archival. Treat landing in
// that tree as an explicit unavailable target, never as permission to
// continue writing through an archived source id.
await assertSourceExists(engine, best.id);
return best.id;
}
// 5. Brain-level default.
// Silent-fallback tier per codex P1-F: an invalid `sources.default` config
// value (operator hand-edit gone wrong, legacy underscore id) falls through
// to tier 6 rather than throwing. Resolver stays robust to bad config.
const globalDefault = await defaultRead;
if (globalDefault && isValidSourceId(globalDefault)) {
await assertSourceExists(engine, globalDefault);
return globalDefault;
}
// 5.5. Single-non-default-source convenience (v0.41.13, #1434).
// When NO brain_default is set AND exactly one registered source has
// local_path set AND it isn't 'default', route there. This closes
// the "532 silent edit failures" bug class where users with a single
// Vault-mounted source ran `gbrain sync` without --source and routed
// to source_id='default' (which held 0 pages). Conservative: fires
// only when there's literally one option AND 'default' is empty
// (#3070) — multi-source brains and established default corpora
// still require explicit --source or sources.default.
//
// Placed AFTER brain_default per codex review: a user who explicitly
// set sources.default has stated intent, that wins over auto-routing.
const soleNonDefault = await pickSoleNonDefaultSource(engine);
if (soleNonDefault) return soleNonDefault;
// 6. Fallback: the seeded 'default' source. Always exists post-migration
// v16 so this is a safe terminal.
return 'default';
}
/**
* Engine-free tiers (1-3) of the resolution chain: explicit flag →
* GBRAIN_SOURCE env → .gbrain-source dotfile walk. Used by the thin-client
* CLI path (#2098), which has no local engine to run tiers 4-6 or
* assertSourceExists against — the remote server enforces existence + grant.
* Returns null when no engine-free tier fires.
*/
export function resolveSourceIdEngineFree(
explicit: string | null | undefined,
cwd: string = hookSessionCwd(),
opts: { env?: string } = {},
): string | null {
if (explicit) {
if (explicit === ALL_SOURCES) return ALL_SOURCES; // #1712 sentinel pass-through
if (!SOURCE_ID_RE.test(explicit)) {
throw new Error(`Invalid --source value "${explicit}". Must match [a-z0-9-]{1,32}.`);
}
return explicit;
}
const env = ambientSourceEnv(opts);
if (env && env.length > 0) {
if (env === ALL_SOURCES) return ALL_SOURCES; // #2140 sentinel pass-through
if (!SOURCE_ID_RE.test(env)) {
throw new Error(`Invalid GBRAIN_SOURCE value "${env}". Must match [a-z0-9-]{1,32}.`);
}
return env;
}
return readDotfileWalk(cwd);
}
/**
* Returns the id of the SINGLE registered non-default source with a
* local_path, when exactly one such row exists. Returns null when:
* - zero non-default sources are registered (fresh install)
* - 2+ non-default sources are registered (ambiguous — user must pick)
* - the only non-default source has a NULL local_path (no on-disk shape)
* - the only registered source IS 'default'
* - 'default' holds an established corpus (#3070 — any active page): the
* tier's charter is rescuing brains whose 'default' is EMPTY (#1434's
* "532 silent edit failures"); when 'default' is actively used,
* auto-routing would hijack every bare `put`/`capture`/`sync` into the
* sole side-source, so the resolver falls through to seed_default and
* the user must pick via --source / sources.default. The flip prints a
* one-line stderr warning naming both sides (suppressed by
* GBRAIN_NO_SOLE_NON_DEFAULT_NUDGE=1) so the reroute is diagnosable.
*
* Excludes archived sources (`archived = false`) so a soft-deleted source
* doesn't auto-resolve, and the storage manifest (GST-1943), which only the storage verbs write. Shared by `resolveSourceId` and `resolveSourceWithTier`
* so the heuristic can't drift between the two entry points.
*
* NOTE (#2928): this tier deliberately does NOT consult config.federated —
* `--no-federated` governs READ mixing, not write routing, and unqualified
* `sync`/`import` on a single-vault brain must keep landing in the vault
* (#1434, pinned by test/sync-sole-non-default-routing.test.ts). The
* unfederate read fix lives in `localFederatedSourceIds` below.
*/
/**
* #3880: list registered local_path sources WITH their archived flag so the
* tier-4 cwd prefix match can prefer active sources. The archived column is
* v34+ — fall back to the column-less query on older brains (rows then carry
* no `archived` key and are treated as active, the pre-v34 behavior).
*/
type RegisteredSource = { id: string; local_path: string; archived?: boolean };
async function listRegisteredLocalPathSources(
engine: BrainEngine,
): Promise<RegisteredSource[]> {
const pending = requestSourceRows(engine);
const request = pending && await pending;
if (request) return request.filter(row => row.local_path !== null).map(({ id, local_path, archived }) => ({ id, local_path: local_path!, archived }));
try {
return await engine.executeRaw<{ id: string; local_path: string; archived?: boolean }>(
`SELECT id, local_path, archived FROM sources WHERE local_path IS NOT NULL`,
);
} catch {
return engine.executeRaw<{ id: string; local_path: string }>(
`SELECT id, local_path FROM sources WHERE local_path IS NOT NULL`,
);
}
}
/**
* Every source row in one statement, once per request config snapshot (#7147): a CLI read or an MCP request resolves
* its source through tier 4, tier 5.5 and the federated set, three reads of a table that does not change under one
* read. Each row also carries tier 5.5's emptiness guard (`default_has_pages`), so the request pays one round trip.
* Undefined without an open snapshot (no await, so a live read keeps its timing) and null on a brain older than
* the `archived` column; the callers then read live.
*/
function requestSourceRows(
engine: BrainEngine,
): Promise<Array<{ id: string; local_path: string | null; archived: boolean; config: unknown; default_has_pages: boolean }> | null> | undefined {
return requestSnapshotRead(engine, 'sources', () => engine.executeRaw<{ id: string; local_path: string | null; archived: boolean; config: unknown; default_has_pages: boolean }>(
`SELECT id, local_path, archived, config, EXISTS (SELECT 1 FROM pages WHERE source_id = 'default' AND deleted_at IS NULL) AS default_has_pages FROM sources ORDER BY id`,
).catch(() => null));
}
async function pickSoleNonDefaultSource(
engine: BrainEngine,
opts: { quiet?: boolean } = {},
): Promise<string | null> {
// archived column was added in v34 (v0.26.5). Older brains may not have
// it — fall back to the un-archived query in that case via try/catch.
const pending = requestSourceRows(engine);
const request = pending && await pending;
// GBRA-133: the emptiness guard's read is sent with the listing (one round trip); it is used only for a sole candidate.
// The request's rows carry its answer already.
const defaultHasPages = request
? Promise.resolve(request.some(row => row.default_has_pages))
: engine.executeRaw<{ one: number }>(
`SELECT 1 AS one FROM pages WHERE source_id = 'default' AND deleted_at IS NULL LIMIT 1`,
).then(found => found.length > 0);
defaultHasPages.catch(() => {});
let rows: Array<{ id: string; config?: unknown }> = request ? request.filter(row => row.local_path !== null && row.id !== 'default' && row.archived === false && parseSourceConfig(row.config).role !== 'storage_manifest') : [];
if (!request) {
try {
rows = await engine.executeRaw<{ id: string; config: unknown }>(
`SELECT id, config FROM sources WHERE local_path IS NOT NULL AND id != 'default' AND archived = false AND config->>'role' IS DISTINCT FROM 'storage_manifest'`,
);
} catch {
rows = await engine.executeRaw<{ id: string }>(
`SELECT id FROM sources WHERE local_path IS NOT NULL AND id != 'default'`,
);
}
}
if (rows.length !== 1) return null;
// #3070 emptiness guard: fire only when 'default' holds no active pages.
try {
if (await defaultHasPages) {
// The flip must not be silent: one stray page in 'default' reroutes
// every bare command away from the sole side-source, and the user
// hunts for "lost" writes. One stderr line names both sides so the
// misroute is diagnosable; same suppression knob as the routing nudge.
// GST-2732: a federated side source is in default search already, so the routing loses nothing and stays quiet.
const federated = (parseSourceConfig(rows[0].config) as { federated?: unknown }).federated === true;
if (!opts.quiet && !federated && process.env.GBRAIN_NO_SOLE_NON_DEFAULT_NUDGE !== '1') {
console.error(
`[gbrain] sole non-default source '${rows[0].id}' exists, but 'default' is non-empty — routing to 'default' (#3070 emptiness guard). Pass --source ${rows[0].id} or set sources.default to target it.`,
);
}
return null;
}
} catch {
// pages.deleted_at exists on every supported schema; a failure here means
// an exotic/legacy brain — keep the pre-guard routing rather than breaking
// resolution outright.
}
return rows[0].id;
}
/**
* Once-per-process (per stale id) latch for the stale `sources.default`
* warning below, so bulk callers don't spam stderr. Reset seam exported via
* `__testing.resetStaleImplicitDefaultWarnings`.
*/
const warnedStaleImplicitDefaults = new Set<string>();
/**
* Source id that represents the brain's implicit default target for a bare
* local command (#4700). Unlike resolveSourceWithTier(), this deliberately
* ignores env, dotfile, cwd, and local_path tiers so callers can distinguish
* the canonical default-like source from an explicit/path-scoped source cycle.
*
* Fail-open on a STALE `sources.default` (the configured source was deleted
* or archived after the config row was set): tier-5 posture, same as
* resolveSourceId's brain_default tier being silent-fallback and
* resolveLinkFallbackDefault never throwing. The stale value is treated as
* absent — one stderr warning names it — and resolution falls through to the
* legacy sole-non-default routing. Genuine engine failures still propagate.
*/
export async function resolveImplicitDefaultSourceId(engine: BrainEngine): Promise<string | null> {
const globalDefault = await engine.getConfig('sources.default');
if (globalDefault && isValidSourceId(globalDefault)) {
try {
await assertSourceExists(engine, globalDefault);
return globalDefault;
} catch (e) {
if (!(e instanceof SourceTargetError)) throw e;
if (!warnedStaleImplicitDefaults.has(globalDefault)) {
warnedStaleImplicitDefaults.add(globalDefault);
console.error(
`[gbrain] config sources.default points at '${globalDefault}', which is not an active source — ` +
`ignoring it for this run. Fix with \`gbrain config set sources.default <id>\` ` +
`(see \`gbrain sources list\`) or restore it: \`gbrain sources restore ${globalDefault}\`.`,
);
}
}
}
return pickSoleNonDefaultSource(engine, { quiet: true });
}
/**
* Format the one-line stderr nudge that fires when source resolution falls
* through to the `sole_non_default` tier. Returns null when suppressed via
* `GBRAIN_NO_SOLE_NON_DEFAULT_NUDGE=1` (CI / scripted-pipeline ergonomics).
*
* Single source of truth so the wording stays consistent across every CLI
* dispatch site that fires the nudge (sync, import, extract, etc.). Callers
* print to stderr; this helper just builds the line.
*/
export function formatSoleNonDefaultNudge(sourceId: string): string | null {
if (process.env.GBRAIN_NO_SOLE_NON_DEFAULT_NUDGE === '1') return null;
return `[gbrain] routing to source '${sourceId}' (sole non-default source registered; pass --source to override).`;
}
// ---------------------------------------------------------------------------
// #4583 (fixes #4564's misrouted-write symptom) — write-time guard for the
// seed_default tier.
//
// `sole_non_default` (tier 5.5) only auto-routes when EXACTLY one non-default
// source with a local_path is registered. On a brain with 2+ non-default
// sources (or a sole one whose local_path is NULL), an unscoped mutating op
// still falls through to `seed_default` and silently lands in source_id
// 'default' — re-opening the cross-source duplicate-slug class (#1434 /
// PR #707), which can silently produce thousands of duplicates.
//
// The guard fires only when the brain's real content lives OUTSIDE 'default'
// (non-default sources hold the bulk of pages). A fresh brain, or a legacy
// brain whose content legitimately still sits in 'default', is left untouched.
// This is the ADVISORY sibling of the opt-in fail-closed serve-time guard
// (`sourceGuardBlocksWrite` / WRITE_SAFE_SOURCE_TIERS below).
// ---------------------------------------------------------------------------
/** Env escape hatch: scripted pipelines that intend to write to 'default'. */
export const GBRAIN_ALLOW_DEFAULT_WRITE_ENV = 'GBRAIN_ALLOW_DEFAULT_WRITE';
export interface DefaultWriteAssessment {
/** True when an unscoped write to 'default' should be guarded (refused/warned). */
shouldGuard: boolean;
/** Pages currently held by source_id = 'default'. */
defaultPages: number;
/** Pages held across all non-default sources. */
nonDefaultPages: number;
/** Count of distinct non-default source_ids with at least one page. */
nonDefaultSources: number;
/**
* True when the page-distribution aggregate FAILED and the verdict above is
* the fail-open default rather than a measurement. A caller that caches or
* latches on an assessment must not treat a failed one as settled.
*/
failed?: true;
}
/**
* Assess whether an unscoped write that resolved to source 'default' should be
* guarded. Call ONLY after resolution returned tier `seed_default` (explicit /
* env / dotfile / local_path / brain_default / sole_non_default writers have
* stated intent and must never be guarded).
*
* Fires when non-default sources hold the bulk of the brain's pages, i.e.
* `nonDefaultPages > defaultPages` with at least one non-default source.
*
* Fail-open: any query error (e.g. a half-migrated brain with no `pages`
* table) returns `shouldGuard=false`. A guard must never be the reason a
* legitimate write fails.
*/
export async function assessDefaultWriteGuard(
engine: BrainEngine,
): Promise<DefaultWriteAssessment> {
const empty: DefaultWriteAssessment = {
shouldGuard: false,
defaultPages: 0,
nonDefaultPages: 0,
nonDefaultSources: 0,
};
try {
const rows = await engine.executeRaw<{
default_pages: number | string | bigint | null;
non_default_pages: number | string | bigint | null;
non_default_sources: number | string | bigint | null;
}>(
// deleted_at IS NULL (review fix): soft-deleted pages skewed the
// distribution both directions — a graveyard outside 'default' could
// fire the guard on a live default-dominant brain, and a graveyard in
// 'default' could mask a live non-default-dominant one. Every sibling
// predicate in this module filters live rows; so does this.
`SELECT
COALESCE(SUM(CASE WHEN source_id = 'default' THEN 1 ELSE 0 END), 0) AS default_pages,
COALESCE(SUM(CASE WHEN source_id <> 'default' THEN 1 ELSE 0 END), 0) AS non_default_pages,
COUNT(DISTINCT source_id) FILTER (WHERE source_id <> 'default') AS non_default_sources
FROM pages
WHERE deleted_at IS NULL`,
);
const r = rows[0];
if (!r) return empty;
const defaultPages = Number(r.default_pages) || 0;
const nonDefaultPages = Number(r.non_default_pages) || 0;
const nonDefaultSources = Number(r.non_default_sources) || 0;
// Strict `>` keeps a default-dominant (fresh / legacy) brain un-guarded:
// with nonDefaultPages 0, the condition is false and 'default' stays valid.
const shouldGuard = nonDefaultSources >= 1 && nonDefaultPages > defaultPages;
return { shouldGuard, defaultPages, nonDefaultPages, nonDefaultSources };
} catch {
return { ...empty, failed: true };
}
}
/**
* Once-per-process memo of assessDefaultWriteGuard, keyed on the engine.
* The assessment is an unindexed full-`pages` aggregate whose inputs are
* process-stable (the brain's page distribution, the env escape hatch), so
* in-process callers that run many unscoped writes — runImport under the
* sync_brain MCP op, the autopilot daemon, minion sync — pay for it ONCE per
* engine rather than on every call. Mirrors the stdio advisory latch
* (createDefaultWriteAdvisory in mcp/server.ts): the memo arms on the first
* SUCCESSFUL assessment, whatever its verdict. A FAILED assessment (the
* fail-open `failed: true` shape) is returned to its caller but forgotten,
* so one transient query error cannot pin "no guard" for the rest of the
* process — the next caller retries. Concurrent callers share the in-flight
* attempt. A WeakMap so a disconnected engine never pins its entry.
*/
let defaultWriteAssessments = new WeakMap<BrainEngine, Promise<DefaultWriteAssessment>>();
export function assessDefaultWriteGuardOnce(engine: BrainEngine): Promise<DefaultWriteAssessment> {
const memo = defaultWriteAssessments;
let pending = memo.get(engine);
if (!pending) {
const attempt: Promise<DefaultWriteAssessment> = assessDefaultWriteGuard(engine).then(a => {
if (a.failed && memo.get(engine) === attempt) memo.delete(engine);
return a;
});
pending = attempt;
memo.set(engine, attempt);
}
return pending;
}
/** Test seam: forget every memoized assessment (e.g. after reseeding a shared engine). */
export function __resetDefaultWriteGuardMemo(): void {
defaultWriteAssessments = new WeakMap();
}
/** True when the operator opted into unscoped 'default' writes for this process. */
export function defaultWriteAllowedByEnv(): boolean {
return process.env[GBRAIN_ALLOW_DEFAULT_WRITE_ENV] === '1';
}
/**
* Multi-line refusal shown when a CLI mutating op (sync / import) would write
* to 'default' on a bulk-non-default brain. `command` is the bare subcommand
* (e.g. `sync`, `import <dir>`). `sourceFlag` is the flag that scopes THIS
* command (source for sync, source-id for import). Escape hatches are spelled
* out inline.
*
* NOTE: never spell a NEW CLI flag with its leading double dash anywhere in
* this file. scripts/generate-flag-registry.ts scans this module one level
* deep from nearly every command and harvests such literals, which would
* grant that flag to all ~90 commands in the generated registry — they would
* then accept and silently ignore it. The `sourceFlag` default below is the
* UNIVERSAL source flag (already legal everywhere); callers with a different
* flag pass it in from their own module.
*/
export function formatDefaultWriteRefusal(
command: string,
a: DefaultWriteAssessment,
sourceFlag: string = '--source',
): string {
return [
`[gbrain] Refusing unscoped ${command}: it would write to source 'default'.`,
` This brain keeps its content in ${a.nonDefaultSources} non-default source(s) ` +
`(${a.nonDefaultPages} pages); 'default' holds ${a.defaultPages}.`,
` An unscoped write to 'default' re-creates cross-source duplicate slugs.`,
` Choose a target:`,
` gbrain ${command} ${sourceFlag} <id> route to a real source (see: gbrain sources list)`,
` gbrain ${command} ${sourceFlag} default write to 'default' on purpose (escape hatch)`,
` ${GBRAIN_ALLOW_DEFAULT_WRITE_ENV}=1 gbrain ${command} allow, for scripted pipelines`,
].join('\n');
}
/**
* One-line warning for surfaces where refusing would be worse than writing
* (the tokenless MCP stdio pipe; in-process import callers). Non-fatal: the
* write proceeds, but the operator is told how to scope future writes.
*/
export function formatDefaultWriteWarning(a: DefaultWriteAssessment, sourceFlag?: string): string {
const escape = sourceFlag
? `Pass ${sourceFlag} <id>`
: `Set ${'GBRAIN_SOURCE'}=<id>`;
return (
`[gbrain] WARNING: writing to source 'default' on a multi-source brain ` +
`(${a.nonDefaultSources} non-default source(s), ${a.nonDefaultPages} pages). ` +
`${escape} to scope writes and avoid cross-source duplicate slugs.` +
(sourceFlag ? ` GBRAIN_SOURCE=<id> works too; GBRAIN_ALLOW_DEFAULT_WRITE=1 keeps 'default' on purpose.` : '')
);
}
/**
* #4583 rework for the stdio MCP lane: decide the once-per-process advisory
* warning from the ALREADY-RESOLVED source tier, not from raw env presence.
* Master's stdio dispatch runs the full ambient chain
* (resolveMcpStdioSourceScope), so a dotfile / local_path / brain_default pin
* resolves a REAL source — warning there would be a false positive. Only the
* `seed_default` tier actually lands the write in 'default'. Returns the
* warning line (null when nothing should be printed) plus `assessed`: true
* when the decision is settled for the process (a successful assessment, a
* non-writing tier, or the process-stable env escape hatch), false when the
* aggregate FAILED — the null is fail-open for this write only and the caller
* must not latch on it. Never throws.
*/
export async function assessUnscopedDefaultWrite(
engine: BrainEngine,
tier: SourceTier,
mutating: boolean,
): Promise<{ warning: string | null; assessed: boolean }> {
if (!mutating || tier !== 'seed_default') return { warning: null, assessed: true };
if (defaultWriteAllowedByEnv()) return { warning: null, assessed: true };
const assessment = await assessDefaultWriteGuard(engine);
if (assessment.failed) return { warning: null, assessed: false };
return { warning: assessment.shouldGuard ? formatDefaultWriteWarning(assessment) : null, assessed: true };
}
async function assertSourceExists(engine: BrainEngine, id: string): Promise<void> {
// GBRA-133: inside a CLI sync's routing scope the source's routing row answers this (sync-dispatch-read.ts).
const routing = await syncDispatchRow(engine, id);
// GBRA-156: inside a request snapshot the request's source rows answer it.
const pending = routing ? undefined : requestSourceRows(engine);
const request = pending && await pending;
const rows = routing ? (routing.id !== null && routing.archived === false ? [routing] : [])
: request ? request.filter(row => row.id === id && row.archived === false)
: await engine.executeRaw<{ id: string }>(
`SELECT id FROM sources WHERE id = $1 AND archived = false`,
[id],
);
if (rows.length === 0) {
const nearest = await nearestSourceId(engine, id);
throw new SourceTargetError(
`Source "${id}" not found or is archived. Available active sources: ` +
`run \`gbrain sources list\` to see registered sources, ` +
`or create/restore "${id}" before retrying.${nearest ? ` Did you mean "${nearest}"?` : ''}`,
);
}
}
/**
* #7193: the active source an unknown id most likely meant: the one whose id or name it names exactly or is the only
* prefix of (`notes` for `notes-brain`), else the nearest id by edit distance (levenshtein.ts). Never throws.
*/
async function nearestSourceId(engine: BrainEngine, id: string): Promise<string | null> {
try {
const sources = await engine.executeRaw<{ id: string; name: string | null }>('SELECT id, name FROM sources WHERE archived = false ORDER BY id');
const named = sources.filter(s => s.name === id);
if (named.length === 1) return named[0]!.id;
const prefixed = sources.filter(s => s.id.startsWith(id) || (s.name ?? '').startsWith(id));
if (prefixed.length === 1) return prefixed[0]!.id;
const { suggestNearest } = await import('./levenshtein.ts');
return suggestNearest(id, sources.map(s => s.id));
} catch {
return null;
}
}
/**
* Predicate: is this error one of THIS module's user-facing throws (an
* unknown / archived source from `assertSourceExists`, or an invalid
* `--source` / `GBRAIN_SOURCE` value from the resolve chain) that a CLI
* command should surface as a clean stderr line + exit 1?
*
* Lives next to the messages it matches so the wordings cannot drift apart
* again — three commands (dream, agent, the code-* scope resolver) once
* carried their own copies, and one of them missed the fail-closed
* ` not found or is archived.` wording, so an archived source escaped as a
* stack trace. Anything else (TypeError / connection failures / genuine
* bugs) is deliberately NOT matched and keeps propagating.
*/
export function isResolverUserError(e: unknown): boolean {
if (!(e instanceof Error)) return false;
const m = e.message;
return (m.startsWith('Source "')
&& (m.includes(' not found.') || m.includes(' not found or is archived.')))
|| m.startsWith('Invalid --source value')
|| m.startsWith('Invalid GBRAIN_SOURCE value');
}
/**
* #3765 — resolve the source id for an EXPLICIT repo path (`sync --repo <dir>`
* / the sync_brain op's `repo` param), anchored at the REPO DIR instead of
* process.cwd(). Without this, `gbrain sync --repo ~/other-vault` parsed the
* path but resolved the SOURCE from the caller's cwd — anchors, page writes,
* and the per-source sync lock all routed to whatever source the cwd implied.
*
* Two tiers, mirroring resolveSourceId's dotfile + local_path tiers but
* rooted at `dir`:
* 1. `.gbrain-source` dotfile walk up from the repo dir (same trust rules)
* 2. registered source whose local_path contains the repo dir
* (longest-prefix match; realpath both sides — codex #9 rationale)
*
* Returns null when neither tier fires — the caller falls back to its ambient
* resolution (cwd chain / ctx.sourceId). Never consults env/cwd: an explicit
* repo path is a statement of intent about THAT tree.
*/
export async function resolveSourceForRepoPath(
engine: BrainEngine,
dir: string,
): Promise<{ source_id: string; tier: 'dotfile' | 'local_path'; detail: string } | null> {
// 1. Dotfile pinned in (or above) the repo tree.
const dotfile = readDotfileWalk(dir);
if (dotfile) {
await assertSourceExists(engine, dotfile);
return { source_id: dotfile, tier: 'dotfile', detail: `.gbrain-source under ${dir}` };
}
// 2. Registered local_path containing the repo dir (longest prefix wins).
const registered = await engine.executeRaw<{ id: string; local_path: string }>(
`SELECT id, local_path FROM sources WHERE local_path IS NOT NULL`,
);
const dirResolved = realpathOrResolve(dir);
let best: { id: string; path: string; pathLen: number } | null = null;
for (const r of registered) {
if (!isAbsolute(r.local_path)) continue;
const p = realpathOrResolve(r.local_path);
if (dirResolved === p || dirResolved.startsWith(p + '/')) {
if (!best || p.length > best.pathLen) {
best = { id: r.id, path: p, pathLen: p.length };
}
}
}
if (best) {
await assertSourceExists(engine, best.id);
return { source_id: best.id, tier: 'local_path', detail: best.path };
}
return null;
}
/**
* Get the local_path of the resolved source (per the resolveSourceId chain).
*
* Returns the on-disk brain repo path for the source the user is currently
* operating against. Used by `gbrain storage status` and `gbrain export
* --restore-only` to find the brain repo without raw SQL or bare try/catch.
*
* Resolution order:
* 1. `sources.local_path` for the resolved source id (multi-source v0.18+ path)
* 2. Legacy global `sync.repo_path` config key (pre-v0.18 default-source brains)
* 3. null
*
* @returns local_path string, or null if no path is configured anywhere.
* @throws If DB error occurs (does NOT silently swallow). Callers handle
* the null case to provide their own fallback (typically a hard error
* telling the user to pass --repo).
*/
export async function getDefaultSourcePath(
engine: BrainEngine,
cwd: string = hookSessionCwd(),
): Promise<string | null> {
const seen: { registered?: RegisteredSource[] } = {};
const sourceId = await resolveSourceIdChain(engine, null, cwd, {}, seen);
noteResolvedSource(sourceId);
// GBRA-133: when the chain listed every source with a local_path, the resolved source's path is in that listing
// (absent means NULL), so it is not read again.
const localPath = seen.registered
? seen.registered.find(r => r.id === sourceId)?.local_path ?? null
: (await engine.executeRaw<{ local_path: string | null }>(`SELECT local_path FROM sources WHERE id = $1`, [sourceId]))[0]?.local_path ?? null;
if (localPath) return localPath;
// Legacy fallback: pre-v0.18 brains stored the repo path in the global
// config table under sync.repo_path. The sources table exists but its
// local_path is NULL for the seeded 'default' row. Fall back so storage
// tiering works without forcing a `gbrain sources add . --path .` migration.
const legacyPath = await engine.getConfig('sync.repo_path');
return legacyPath ?? null;
}
/**
* v0.37.7.0 — tier labels for `resolveSourceWithTier()`. Exported so
* `gbrain sources current --json` and downstream consumers share a
* canonical vocabulary instead of redefining strings inline.
*
* Order matches the 1-6 priority of `resolveSourceId()`.
*/
export const SOURCE_TIER_NAMES = [
'flag',
'env',
'dotfile',
'local_path',
'brain_default',
'sole_non_default',
'seed_default',
] as const;
export type SourceTier = typeof SOURCE_TIER_NAMES[number];
/**
* Same resolution chain as `resolveSourceId()`, but also returns
* WHICH tier won. Additive — does not duplicate the logic; runs the
* same six steps in the same order. Used by `gbrain sources current`
* so users can verify the resolved source AND the reason it resolved
* before destructive ops.
*
* @returns `{ source_id, tier, detail? }` where `detail` is an
* optional human-readable extra (e.g. the env-var name or
* the matched dotfile / local_path).
*/
export async function resolveSourceWithTier(
engine: BrainEngine,
explicit: string | null | undefined,
cwd: string = hookSessionCwd(),
opts: { env?: string } = {},
): Promise<{ source_id: string; tier: SourceTier; detail?: string }> {
const resolved = await resolveSourceWithTierChain(engine, explicit, cwd, opts);
noteResolvedSource(resolved.source_id);
return resolved;
}
async function resolveSourceWithTierChain(
engine: BrainEngine,
explicit: string | null | undefined,
cwd: string,
opts: { env?: string },
): Promise<{ source_id: string; tier: SourceTier; detail?: string }> {
// 1. Explicit flag wins. __all__ sentinel passes through verbatim (#1712).
if (explicit) {
if (explicit === ALL_SOURCES) {
return { source_id: ALL_SOURCES, tier: 'flag', detail: `--source ${ALL_SOURCES} (spans all sources)` };
}
if (!SOURCE_ID_RE.test(explicit)) {
throw new SourceTargetError(`Invalid --source value "${explicit}". Must match [a-z0-9-]{1,32}.`);
}
await assertSourceExists(engine, explicit);
return { source_id: explicit, tier: 'flag', detail: `--source ${explicit}` };
}
// 2. Env var. Same __all__ pass-through (#2140).
const env = ambientSourceEnv(opts);
if (env && env.length > 0) {
if (env === ALL_SOURCES) {
return { source_id: ALL_SOURCES, tier: 'env', detail: `GBRAIN_SOURCE=${ALL_SOURCES} (spans all sources)` };
}
if (!SOURCE_ID_RE.test(env)) {
throw new SourceTargetError(`Invalid GBRAIN_SOURCE value "${env}". Must match [a-z0-9-]{1,32}.`);
}
await assertSourceExists(engine, env);
return { source_id: env, tier: 'env', detail: `GBRAIN_SOURCE=${env}` };
}
// 3. .gbrain-source dotfile walk-up.
const dotfile = readDotfileWalk(cwd);
if (dotfile) {
await assertSourceExists(engine, dotfile);
return { source_id: dotfile, tier: 'dotfile', detail: `.gbrain-source` };
}
// 4. Registered source whose local_path contains CWD.
// #3880 active-over-archived tiering + parallel realpath both live in
// the shared resolveRegisteredPathMatch helper.
// GBRA-156: tier 5's config read is sent with the listing, as in resolveSourceIdChain.
const defaultRead = engine.getConfig('sources.default');
defaultRead.catch(() => {});
const best = await resolveRegisteredPathMatch(await listRegisteredLocalPathSources(engine), cwd);
if (best) {
await assertSourceExists(engine, best.id);
return { source_id: best.id, tier: 'local_path', detail: best.path };
}
// 5. Brain-level default. Silent-fallback (P1-F) like tier 5 in resolveSourceId.
const globalDefault = await defaultRead;
if (globalDefault && isValidSourceId(globalDefault)) {
await assertSourceExists(engine, globalDefault);
return { source_id: globalDefault, tier: 'brain_default', detail: 'sources.default config' };
}
// 5.5. Single-non-default-source convenience (v0.41.13, #1434).
// See resolveSourceId for the design rationale. Same helper, same
// precedence (AFTER brain_default).
const soleNonDefault = await pickSoleNonDefaultSource(engine);
if (soleNonDefault) {
return {
source_id: soleNonDefault,
tier: 'sole_non_default',
detail: `only non-default registered source with local_path`,
};
}
// 6. Fallback: seeded 'default' source.
return { source_id: 'default', tier: 'seed_default' };
}
/**
* #3242 parity: the widening set a TRANSPORT should attach for a caller that
* carries no operator source grant, or `undefined` when the caller must keep
* its scalar scope.
*
* The gate is deliberately `hasSourceGrant === false` rather than falsy.
* `false` is set only for a legacy bearer token whose
* `access_tokens.permissions.source_id` is absent — the historical no-grant
* floor. `true` is an operator-set scope and `undefined` is an OAuth client,
* and neither may widen, so a falsy check would hand OAuth clients the
* federated set.
*
* Resolution is best-effort by design: a source table that cannot be read
* leaves the scalar scope standing rather than failing the request, matching
* the surrounding transport behaviour.
*/
export async function noGrantFederatedScope(
engine: BrainEngine,
hasSourceGrant: boolean | undefined,
sourceId: string | undefined,
): Promise<string[] | undefined> {
if (hasSourceGrant !== false || !sourceId) return undefined;
try {
return await localFederatedSourceIds(engine, sourceId, 'seed_default');
} catch {
return undefined;
}
}
/**
* #8982: whether a caller with no source grant reads `sourceId` unqualified: `default`, or a source in the federated
* set noGrantFederatedScope threads for that floor. Throws when the sources cannot be read, so a write policy keyed on
* it fails closed instead of treating an unreadable table as "not shared".
*/
export async function noGrantFloorReads(engine: BrainEngine, sourceId: string): Promise<boolean> {
return sourceId === 'default' || ((await localFederatedSourceIds(engine, 'default', 'seed_default'))?.includes(sourceId) ?? false);
}
/**
* #2561 — compute the federated read scope for an UNQUALIFIED local CLI call.
*
* `sources add --federated` promises that a `config.federated = true` source
* "participates in unqualified `gbrain search` results"
* (docs/guides/multi-source-brains.md). This helper turns that promise into a
* scope: given the resolved source and WHICH tier resolved it, return
* `[resolvedSource, ...other federated source ids]` — or `undefined` when the
* expansion must not apply:
*
* - explicit tiers (`flag` / `env` / `dotfile`): the user named a source;
* scalar scope stands (that IS the qualified case);
* - no other federated source exists: keep the scalar fast path unchanged;
* - #2928: the resolved source is explicitly isolated (config.federated =
* false): it must not be mixed into a cross-source read in EITHER
* direction, so the scalar scope stands.
*
* Archived sources are excluded (same rationale as pickSoleNonDefaultSource);
* the archived column is v34+, so fall back to the un-archived query on older
* brains. Callers put the result on `OperationContext.localFederatedSourceIds`,
* consumed by `federatedSearchScope`. Two caller classes exist: local CLI/MCP
* stdio (`remote === false`, the original #2561 path) and — via
* `noGrantFederatedScope` below — remote transports for a legacy no-grant
* bearer token (#3242 parity), where the transport itself decides the caller
* may see the federated floor.
*/
export async function localFederatedSourceIds(
engine: BrainEngine,
sourceId: string,
tier: SourceTier,
): Promise<string[] | undefined> {
if (tier === 'flag' || tier === 'env' || tier === 'dotfile') return undefined;
return federatedSetFor(await liveSourceRows(engine), sourceId);
}
/**
* #5081 — explicit-read admission for a stdio connection bound by
* `GBRAIN_SOURCE` (tier `env`) or a `.gbrain-source` pin (tier `dotfile`).
* The admitted set is exactly what `localFederatedSourceIds` would compute for
* the same source on a non-explicit tier (one shared `federatedSetFor`), so a
* bound connection may NAME the sources an unbound one reads unqualified. The
* #2928 isolated anchor (`config.federated === false`) admits only itself.
* Unqualified reads of a bound connection stay scalar: the result goes on
* `OperationContext.explicitReadBinding`, never `localFederatedSourceIds`.
* Returns undefined for every other tier (no extra query).
*/
export async function explicitReadBinding(
engine: BrainEngine,
sourceId: string,
tier: SourceTier,
): Promise<ExplicitReadBinding | undefined> {
if (tier !== 'env' && tier !== 'dotfile') return undefined;
const rows = await liveSourceRows(engine);
return {
sourceId,
via: tier === 'env' ? 'GBRAIN_SOURCE' : '.gbrain-source',
sourceIds: federatedSetFor(rows, sourceId) ?? [sourceId],
optedOut: rows.filter((row) => parseSourceConfig(row.config).federated === false).map((row) => row.id),
};
}
async function liveSourceRows(engine: BrainEngine): Promise<Array<{ id: string; config: unknown; archived?: boolean }>> {
const pending = requestSourceRows(engine);
const request = pending && await pending;
if (request) return request.filter(row => row.archived === false).map(({ id, config, archived }) => ({ id, config, archived }));
try {
return await engine.executeRaw<{ id: string; config: unknown; archived?: boolean }>(
`SELECT id, config, archived FROM sources WHERE archived = false ORDER BY id`,
);
} catch {
return await engine.executeRaw<{ id: string; config: unknown }>(
`SELECT id, config FROM sources ORDER BY id`,
);
}
}
function federatedSetFor(
rows: Array<{ id: string; config: unknown; archived?: boolean }>,
sourceId: string,
): string[] | undefined {
// #2928: an EXPLICITLY isolated anchor (`sources unfederate` /
// `--no-federated` → config.federated = false) opted out of cross-source
// read mixing — never widen it into the federated set (which would drag
// other sources' pages into its unqualified reads and vice versa). Scalar
// scope stands. UNSET federated keeps the pre-#2928 widening behavior;
// write routing (tier 5.5 above) is deliberately untouched.
const resolvedRow = rows.find((row) => row.id === sourceId);
if (resolvedRow && parseSourceConfig(resolvedRow.config).federated === false) {
return undefined;
}
const ids = [
sourceId,
...rows
.filter((row) => row.archived !== true && isSourceFederated(row.config))
.map((row) => row.id)
.filter((id) => id !== sourceId),
];
return ids.length > 1 ? ids : undefined;
}
/**
* Source-guard write policy (`gbrain serve --source-guard`) — the plugin
* lanes' fail-closed routing rule.
*
* A plugin-managed MCP server is user-global and runs with the plugin
* snapshot as its cwd, so two ambient resolution tiers lose their meaning:
* `dotfile` never finds the user's project pin, and `local_path` can match a
* registered source whose local_path happens to CONTAIN the snapshot dir
* (e.g. a source registered at $HOME) — the exact silent-wrong-source write
* the guard exists to prevent. Under the guard, write/admin ops are allowed
* only when the binding is deliberate or unambiguous:
*
* flag / env / dotfile deliberate binding (dotfile still counts: if it
* resolved, someone placed a pin on the cwd path —
* a hand-run from a real project, not the snapshot)
* brain_default the operator configured sources.default
* sole_non_default exactly one candidate — unambiguous
* seed_default unambiguous ONLY while 'default' is the sole
* source; ambiguous the moment others exist
* local_path blocked — cwd-derived intent is invalid under a
* plugin-managed serve
*
* Reads stay unrestricted on every tier (within-brain, and the federated
* read scope is transport-computed) — the guard is a WRITE guard.
*/
export const WRITE_SAFE_SOURCE_TIERS: ReadonlySet<SourceTier> = new Set([
'flag',
'env',
'dotfile',
'brain_default',
'sole_non_default',
]);
/**
* Decide whether a write/admin op must be blocked under `--source-guard`
* for the given resolution tier. Engine is consulted only on the
* `seed_default` tier (source count decides ambiguity); errors fail CLOSED
* — if the guard cannot prove the write is unambiguous, it blocks.
*/
/**
* Which sources-query shape this engine's schema supports. Cached at module
* level after the first successful probe so a pre-`archived`-column schema
* pays the fallback exception ONCE, not on every guarded write (the guard
* runs on the seed_default tier of every write/admin MCP call).
*/
let sourcesQueryShape: 'archived' | 'legacy' | null = null;
/** True iff a source other than the seeded 'default' exists. Bounded single-
* row probe (the verdict needs existence, not the list) with the
* pre-`archived`-column fallback. The `legacy` shape is memoized ONLY when
* the archived query fails with a missing-column error — a transient error
* (pool blip, connection reset) must NOT poison the shape for the process
* lifetime (which would make archived-capable brains block forever). Errors
* propagate to the caller, which decides the fail-closed verdict. */
async function otherSourceExists(engine: BrainEngine): Promise<boolean> {
if (sourcesQueryShape !== 'legacy') {
try {
const rows = await engine.executeRaw<{ id: string }>(
`SELECT id FROM sources WHERE id <> 'default' AND archived = false LIMIT 1`,
);
sourcesQueryShape = 'archived';
return rows.length > 0;
} catch (err) {
// Cache 'legacy' ONLY for a genuine missing-column error; re-throw
// anything else so a transient failure doesn't permanently degrade.
const msg = err instanceof Error ? err.message.toLowerCase() : String(err).toLowerCase();
const missingColumn = msg.includes('archived') && (msg.includes('column') || msg.includes('does not exist') || msg.includes('no such column'));
if (!missingColumn) throw err;
sourcesQueryShape = 'legacy';
}
}
const rows = await engine.executeRaw<{ id: string }>(
`SELECT id FROM sources WHERE id <> 'default' LIMIT 1`,
);
return rows.length > 0;
}
export async function sourceGuardBlocksWrite(
engine: BrainEngine,
tier: SourceTier,
): Promise<boolean> {
if (WRITE_SAFE_SOURCE_TIERS.has(tier)) return false;
// local_path AND seed_default are cwd-derived / seed-fallback tiers under a
// plugin serve — block ONLY when the binding is genuinely ambiguous (some
// OTHER source exists). A sole-source brain is unambiguous even when its
// local_path contains the serve cwd, so it must not be blocked. Engine
// failure fails CLOSED.
try {
return await otherSourceExists(engine);
} catch {
return true;
}
}
/** Test seam: reset the cached sources-query shape (module-level memo). */
export function __resetSourceGuardQueryShape(): void {
sourcesQueryShape = null;
}
/** Exposed for tests. */
export const __testing = {
readDotfileWalk,
SOURCE_ID_RE,
resetStaleImplicitDefaultWarnings(): void {
warnedStaleImplicitDefaults.clear();
},
};