Compare commits

..
Author SHA1 Message Date
Garry TanandClaude Fable 5 52fffc7ecc fix(facts): seed phase B backfill row_nums past the DB max (#2044 class)
phaseBFenceFacts appended at fence-max+1 with no DB seeding, so on a
diverged page (stamped DB rows + missing fence at the resolved path —
the same divergence class the writeFactsToFence fix handles) the
post-rename UPDATE hit idx_facts_fence_key, the page failed, and the
already-renamed fence disagreed with the DB while the row_num-NULL
backlog persisted. Seed appended row_nums from MAX(fence max, DB max)
per (source_id, slug), mirroring the fence-write fix. Repro test added.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-22 11:46:22 -07:00
Garry TanandClaude Fable 5 039b97df36 fix(facts): route exit codes through setCliExitVerdict
The cli-exit-verdict-pin guard requires every exit-code write in src/
to go through setCliExitVerdict (raw process.exitCode assignments get
zeroed by the owned-verdict read on PGLite). Replace the two raw
assignments in the new facts command.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-22 10:50:45 -07:00
Garry TanandClaude Fable 5 2bb3424863 fix(facts): idempotent fence deposits + re-runnable fence-backfill command
Two fixes for the remote extract_facts deposit path:

#2044 — a second deposit to an already-fenced page could throw
idx_facts_fence_key and roll back the whole batch when fence and DB
row_nums diverged (e.g. legacy wrong-path fence writes). writeFactsToFence
now seeds the next row_num from MAX(fence max, DB max(row_num)) for the
(source_id, slug) pair, and insertFacts in BOTH engines adds
ON CONFLICT (source_id, source_markdown_slug, row_num) WHERE row_num IS
NOT NULL DO NOTHING so a residual collision skips one row instead of
failing the batch.

#1867 — row_num-NULL backlogs (remote deposits that predate the fence
backstop) had no remedy: the fence backfill lived only inside the one-shot
v0_32_2 migration, and the cycle guard pointed at `gbrain apply-migrations
--yes`, which never re-runs a completed migration. phaseBFenceFacts (already
idempotent on row_num IS NULL) is now exported and exposed as
`gbrain facts fence-backfill [--dry-run]`; the guard message points at it.
The backfill also routes page paths through resolvePageFilePath so
non-default sources fence into the same path the fence-write backstop uses.

Fixes #2044
Fixes #1867

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-21 14:45:53 -07:00
20 changed files with 362 additions and 213 deletions
+12 -1
View File
@@ -54,7 +54,7 @@ export function bigintToStringReplacer(_key: string, value: unknown): unknown {
}
// CLI-only commands that bypass the operation layer
export const CLI_ONLY = new Set(['init', 'reinit-pglite', 'upgrade', 'post-upgrade', 'check-update', 'integrations', 'publish', 'check-backlinks', 'lint', 'report', 'import', 'export', 'files', 'embed', 'serve', 'call', 'config', 'doctor', 'migrate', 'eval', 'sync', 'extract', 'extract-conversation-facts', 'enrich', 'features', 'autopilot', 'graph-query', 'jobs', 'agent', 'apply-migrations', 'skillpack-check', 'skillpack', 'resolvers', 'integrity', 'repair-jsonb', 'orphans', 'sources', 'mounts', 'dream', 'check-resolvable', 'routing-eval', 'skillify', 'smoke-test', 'providers', 'storage', 'repos', 'code-def', 'code-refs', 'reindex', 'reindex-code', 'reindex-frontmatter', 'code-callers', 'code-callees', 'reconcile-links', 'frontmatter', 'auth', 'friction', 'claw-test', 'book-mirror', 'takes', 'think', 'salience', 'anomalies', 'calibration', 'transcripts', 'models', 'remote', 'recall', 'forget', 'edges-backfill', 'cache', 'ze-switch', 'founder', 'brainstorm', 'lsd', 'schema', 'capture', 'onboard', 'conversation-parser', 'status', 'connect', 'skillopt', 'quarantine', 'self-upgrade', 'advisor', 'watch', 'reindex-search-vector']);
export const CLI_ONLY = new Set(['init', 'reinit-pglite', 'upgrade', 'post-upgrade', 'check-update', 'integrations', 'publish', 'check-backlinks', 'lint', 'report', 'import', 'export', 'files', 'embed', 'serve', 'call', 'config', 'doctor', 'migrate', 'eval', 'sync', 'extract', 'extract-conversation-facts', 'enrich', 'features', 'autopilot', 'graph-query', 'jobs', 'agent', 'apply-migrations', 'skillpack-check', 'skillpack', 'resolvers', 'integrity', 'repair-jsonb', 'orphans', 'sources', 'mounts', 'dream', 'check-resolvable', 'routing-eval', 'skillify', 'smoke-test', 'providers', 'storage', 'repos', 'code-def', 'code-refs', 'reindex', 'reindex-code', 'reindex-frontmatter', 'code-callers', 'code-callees', 'reconcile-links', 'frontmatter', 'auth', 'friction', 'claw-test', 'book-mirror', 'takes', 'think', 'salience', 'anomalies', 'calibration', 'transcripts', 'models', 'remote', 'recall', 'forget', 'edges-backfill', 'facts', 'cache', 'ze-switch', 'founder', 'brainstorm', 'lsd', 'schema', 'capture', 'onboard', 'conversation-parser', 'status', 'connect', 'skillopt', 'quarantine', 'self-upgrade', 'advisor', 'watch', 'reindex-search-vector']);
// CLI-only commands whose handlers print their own --help text. These are
// excluded from the generic short-circuit so detailed per-command and
// per-subcommand usage stays reachable.
@@ -991,6 +991,8 @@ const THIN_CLIENT_REFUSED_COMMANDS = new Set([
// hint pointing at the routable MCP tools; per-subcommand splits are
// a v0.31.x follow-up TODO.
'takes', 'sources',
// #1867: fence-backfill edits local .md fences + stamps the local DB.
'facts',
// v0.32 thin-client routing audit (Codex round 2 findings #2, #4):
// - `pages` purge-deleted is admin+localOnly (operations.ts:856-864)
// - `files` list / file_url MCP ops are localOnly (operations.ts:1769-1879)
@@ -1026,6 +1028,7 @@ const THIN_CLIENT_REFUSE_HINTS: Record<string, string> = {
migrate: "migrate runs on the host's local engine. Run on the host machine.",
'apply-migrations': 'schema migrations run on the host. SSH and run there.',
'repair-jsonb': 'repair-jsonb operates on the local DB only.',
facts: 'facts fence-backfill edits local entity-page fences. Run on the host machine.',
integrity: 'integrity scans local files. Run on the host machine.',
serve: 'serve starts a server. Run on the host, not the thin client.',
dream: 'dream runs the autopilot cycle on the host. `gbrain remote ping` queues one. (Native `gbrain dream` thin-client routing planned for v0.31.2.)',
@@ -1855,6 +1858,13 @@ async function handleCliOnly(command: string, args: string[]) {
await runEdgesBackfill(engine, args);
break;
}
case 'facts': {
// #1867 — re-runnable fence-backfill for row_num-NULL legacy fact
// rows (idempotent v0_32_2 phase B, exposed as an operator command).
const { runFactsCommand } = await import('./commands/facts.ts');
await runFactsCommand(engine, args);
break;
}
case 'whoknows': {
// v0.33 (Issue #?): expertise + relationship-proximity routing.
// MCP op `find_experts` (read-scoped) backs the same code path; CLI
@@ -2335,6 +2345,7 @@ TOOLS
check-backlinks <check|fix> [dir] Find/fix missing back-links across brain
lint <dir|file> [--fix] Catch LLM artifacts, placeholder dates, bad frontmatter
orphans [--json] [--count] Find pages with no inbound wikilinks
facts fence-backfill [--dry-run] Fence legacy fact rows (row_num NULL) onto entity pages
salience [--days N] [--kind P] v0.29: pages ranked by emotional + activity salience
anomalies [--since D] [--sigma N] v0.29: cohort-based statistical anomalies (tag, type)
transcripts recent [--days N] v0.29: recent raw .txt transcripts (local-only)
+48
View File
@@ -0,0 +1,48 @@
/**
* gbrain facts — fact-store maintenance surface (#1867).
*
* `fence-backfill` re-runs the v0_32_2 fence-backfill phase on demand.
* Remote `extract_facts` deposits that predate the fence-write backstop
* (and any legacy DB-only insert) leave `row_num IS NULL` rows that the
* cycle extract_facts guard refuses to reconcile past — previously the
* only remedy was the one-shot v0_32_2 migration, which the ledger marks
* complete and never re-runs. The phase is idempotent (only touches
* `row_num IS NULL` rows), so exposing it as a command is safe to re-run
* any time the backlog reappears.
*/
import type { BrainEngine } from '../core/engine.ts';
import { setCliExitVerdict } from '../core/cli-force-exit.ts';
import { phaseBFenceFacts } from './migrations/v0_32_2.ts';
function printHelp(): void {
process.stderr.write(
`Usage: gbrain facts fence-backfill [--dry-run]\n\n` +
`Fence-backfill: appends every legacy fact row (row_num IS NULL) to its\n` +
`entity page's \`## Facts\` fence and stamps row_num + source_markdown_slug\n` +
`back onto the DB row. Idempotent — re-runs only pick up rows still\n` +
`missing a fence assignment. Clears the backlog that makes the cycle's\n` +
`extract_facts phase skip fence→DB reconciliation.\n\n` +
` --dry-run report what would be fenced; no FS or DB writes\n`,
);
}
export async function runFactsCommand(engine: BrainEngine, args: string[]): Promise<void> {
const sub = args[0];
if (!sub || sub === '--help' || sub === '-h') {
printHelp();
return;
}
if (sub !== 'fence-backfill') {
process.stderr.write(`Unknown facts subcommand: ${sub}\n`);
printHelp();
setCliExitVerdict(1);
return;
}
const dryRun = args.includes('--dry-run');
const result = await phaseBFenceFacts(engine, { dryRun });
process.stderr.write(
`fence-backfill: ${result.status}${result.detail ? `${result.detail}` : ''}\n`,
);
if (result.status === 'failed') setCliExitVerdict(1);
}
+32 -4
View File
@@ -39,6 +39,7 @@ import type { BrainEngine } from '../../core/engine.ts';
import { loadConfig, toEngineConfig } from '../../core/config.ts';
import { createEngine } from '../../core/engine-factory.ts';
import { upsertFactRow, parseFactsFence } from '../../core/facts-fence.ts';
import { resolvePageFilePath } from '../../core/markdown.ts';
let testEngineOverride: BrainEngine | null = null;
export function __setTestEngineOverride(engine: BrainEngine | null): void {
@@ -148,9 +149,16 @@ function isLocalPathDirty(localPath: string): boolean {
}
}
async function phaseBFenceFacts(
/**
* Exported (not just via `__testing`) because `gbrain facts fence-backfill`
* (#1867) re-runs this phase on demand: remote `extract_facts` deposits that
* predate the fence-write backstop leave row_num-NULL rows the cycle guard
* refuses to reconcile past. The phase is idempotent (only touches
* `row_num IS NULL` rows), so re-running is always safe.
*/
export async function phaseBFenceFacts(
engine: BrainEngine | null,
opts: OrchestratorOpts,
opts: Pick<OrchestratorOpts, 'dryRun'>,
): Promise<OrchestratorPhaseResult> {
if (opts.dryRun) {
// Dry-run: report what WOULD happen without touching FS or DB.
@@ -238,7 +246,11 @@ async function phaseBFenceFacts(
for (const [key, group] of groups) {
const [sourceId, entitySlug] = key.split('\0');
const localPath = localPathById.get(sourceId)!;
const filePath = join(localPath, `${entitySlug}.md`);
// resolvePageFilePath, NOT a bare join — non-default sources fence
// into `<local_path>/.sources/<id>/<slug>.md`, the same path the
// fence-write backstop and put_page write-through compute. A bare
// join here diverges fence and DB for non-default sources (#2044).
const filePath = resolvePageFilePath(localPath, entitySlug, sourceId);
const tmpPath = `${filePath}.tmp`;
try {
@@ -269,6 +281,21 @@ async function phaseBFenceFacts(
const existingFence = parseFactsFence(body);
const existingKeySet = new Set(existingFence.facts.map(f => `${f.claim}\0${f.source ?? ''}`));
// Seed appended row_nums from MAX(fence max, DB max) — same #2044
// divergence guard as writeFactsToFence. When the fence at the
// resolved path is missing/behind but the DB already holds stamped
// rows for this slug (legacy wrong-path fence writes), fence-max+1
// collides with idx_facts_fence_key on the post-rename UPDATE,
// failing the page and leaving fence and DB disagreeing.
const dbMaxRows = await engine.executeRaw<{ max: number | string | null }>(
`SELECT MAX(row_num) AS max FROM facts
WHERE source_id = $1 AND source_markdown_slug = $2`,
[sourceId, entitySlug],
);
const dbMaxRowNum = Number(dbMaxRows[0]?.max ?? 0) || 0;
const fenceMaxRowNum = existingFence.facts.reduce((m, f) => Math.max(m, f.rowNum), 0);
let nextRowNum = Math.max(fenceMaxRowNum, dbMaxRowNum) + 1;
const assignments: Array<{ id: string; row_num: number }> = [];
for (const row of group) {
const key = `${row.fact}\0${row.source ?? ''}`;
@@ -291,6 +318,7 @@ async function phaseBFenceFacts(
.toISOString().slice(0, 10)
: undefined;
const { body: updated, rowNum } = upsertFactRow(body, {
rowNum: nextRowNum++,
claim: row.fact,
kind: row.kind,
confidence: row.confidence,
@@ -381,7 +409,7 @@ async function phaseCVerify(
for (const g of groups) {
const localPath = localPathById.get(g.source_id);
if (!localPath) continue;
const filePath = join(localPath, `${g.source_markdown_slug}.md`);
const filePath = resolvePageFilePath(localPath, g.source_markdown_slug, g.source_id);
if (!existsSync(filePath)) {
mismatches.push(`${g.source_markdown_slug} (file missing)`);
continue;
-4
View File
@@ -908,10 +908,6 @@ export const KNOWN_CONFIG_KEYS: readonly string[] = [
'facts.extraction_model',
// #2113: output-token cap for the per-turn facts extractor (default 4000).
'facts.extraction_max_tokens',
// Owner opt-in: let the local stdio MCP pipe read this owner's private facts
// (find_trajectory / recall). Default off; HTTP transport ignores it. See
// src/core/facts/reader-trust.ts.
'facts.trust_local_reads',
// Dream cycle config
'dream.synthesize.session_corpus_dir',
'dream.synthesize.meeting_transcripts_dir',
+5 -3
View File
@@ -176,9 +176,11 @@ export async function runExtractFacts(
if (legacyCount > 0) {
result.guardTriggered = true;
result.warnings.push(
`extract_facts: ${legacyCount} legacy v0.31 fact rows pending fence backfill. ` +
`Run \`gbrain apply-migrations --yes\` to complete v0_32_2 before this phase ` +
`can safely reconcile fence → DB.`,
`extract_facts: ${legacyCount} legacy fact rows pending fence backfill ` +
`(row_num IS NULL — v0.31 rows or remote extract_facts deposits that ` +
`predate the fence backstop). Run \`gbrain facts fence-backfill\` ` +
`(idempotent, re-runnable) before this phase can safely reconcile ` +
`fence → DB.`,
);
return result;
}
+7 -8
View File
@@ -591,8 +591,6 @@ export interface TrajectoryOpts {
sourceIds?: string[];
/** When true, filters to visibility='world' only. Set by MCP layer from ctx.remote. */
remote?: boolean;
/** Owner opt-in: read private facts despite `remote`. See facts/reader-trust.ts. */
trustedFactReads?: boolean;
/** Metric filter. When set, only facts with this canonical metric label participate. */
metric?: string;
/**
@@ -1741,13 +1739,14 @@ export interface BrainEngine {
* single-row supersede flow because fence reconciliation is the canonical
* source-of-truth direction, not the consolidator path.
*
* Insertion is atomic per call: all rows commit in a single transaction
* or none commit (the transaction rolls back on any constraint
* violation, e.g. the v51 partial UNIQUE index on
* `(source_id, source_markdown_slug, row_num)`).
* Insertion runs in a single transaction. A collision on the v51
* partial UNIQUE index `(source_id, source_markdown_slug, row_num)`
* skips ONLY that row (ON CONFLICT DO NOTHING, #2044) — the rest of
* the batch still commits, so a redundant deposit against an
* already-indexed fence row is idempotent instead of a hard failure.
*
* Returns the inserted ids in input-order so callers can correlate
* fence-row → DB-id without a separate lookup.
* Returns the inserted ids in input-order (colliding rows omitted) so
* callers can correlate fence-row → DB-id without a separate lookup.
*/
insertFacts(
rows: Array<NewFact & { row_num: number; source_markdown_slug: string }>,
+17 -1
View File
@@ -218,11 +218,27 @@ export async function writeFactsToFence(
}
// 2. Upsert each fact onto the fence in input order. row_num
// monotonically increases (max-existing + 1 per call, append-only).
// monotonically increases, append-only, seeded from the MAX of
// the fence and the DB index (#2044): when fence and DB have
// diverged (e.g. legacy writes that stamped DB rows against a
// fence at a path this code no longer reads), fence-max+1 can
// collide with an existing DB row_num, tripping
// idx_facts_fence_key and rolling back the whole batch.
const dbMaxRows = await engine.executeRaw<{ max: number | string | null }>(
`SELECT MAX(row_num) AS max FROM facts
WHERE source_id = $1 AND source_markdown_slug = $2`,
[target.sourceId, target.slug],
);
const dbMaxRowNum = Number(dbMaxRows[0]?.max ?? 0) || 0;
const fenceMaxRowNum = parseFactsFence(body).facts
.reduce((m, f) => Math.max(m, f.rowNum), 0);
let nextRowNum = Math.max(fenceMaxRowNum, dbMaxRowNum) + 1;
const assignedRowNums: number[] = [];
for (const f of facts) {
const validFromStr = (f.validFrom ?? new Date()).toISOString().slice(0, 10);
const { body: updated, rowNum } = upsertFactRow(body, {
rowNum: nextRowNum++,
claim: f.fact,
kind: (f.kind ?? 'fact') as 'fact' | 'event' | 'preference' | 'commitment' | 'belief',
confidence: f.confidence ?? 1.0,
+5 -8
View File
@@ -17,7 +17,6 @@
import type { OperationContext } from './../operations.ts';
import type { FactRow } from './../engine.ts';
import { effectiveConfidence } from './decay.ts';
import { readableFactVisibilities } from './reader-trust.ts';
const DEFAULT_TTL_MS = 30_000;
const DEFAULT_TOP_K = 10;
@@ -51,13 +50,7 @@ export async function getBrainHotMemoryMeta(
const sessionId = (ctx as { source_session?: string }).source_session
?? null;
const allowListHash = hashAllowList(ctx.takesHoldersAllowList);
// Visibility tier: untrusted remote → world-only; trusted local +
// owner-trusted reads → all rows. Folded into the cache key (the header's
// "cache entries don't bleed across tiers" invariant): trustedFactReads is
// re-read from config per call, so a mid-session opt-out must not keep
// serving a private-inclusive cached payload for the TTL window.
const visibility = readableFactVisibilities(ctx);
const cacheKey = `${sourceId}::${sessionId ?? '_'}::${allowListHash}::${visibility ? 'world' : 'all'}`;
const cacheKey = `${sourceId}::${sessionId ?? '_'}::${allowListHash}`;
const ttl = Math.max(1000, opts.ttlMs ?? DEFAULT_TTL_MS);
const topK = Math.max(1, Math.min(opts.topK ?? DEFAULT_TOP_K, 25));
@@ -68,6 +61,10 @@ export async function getBrainHotMemoryMeta(
return cached.payload;
}
// Build a fresh payload. Visibility tier: remote → world-only;
// local → all rows.
const visibility = ctx.remote === false ? undefined : ['world'] as ('world' | 'private')[];
let rows: FactRow[] = [];
if (sessionId) {
rows = await ctx.engine.listFactsBySession(sourceId, sessionId, {
-48
View File
@@ -1,48 +0,0 @@
/**
* Fact-read visibility trust.
*
* Fact rows are tagged `private` | `world`. Remote/untrusted callers
* (`remote === true`) see only `world` rows — the posture that keeps a
* published or HTTP-served brain from leaking private claims to strangers.
*
* But the stdio MCP server is an unauthenticated LOCAL pipe: on a single-owner
* machine the caller IS the owner, yet it still defaults `remote: true` for
* safety, so the owner's own agent is denied the owner's own private facts
* (e.g. `find_trajectory` returns empty over MCP even though the facts exist).
*
* `trustedFactReads` is a narrow, READ-ONLY trust elevation, deliberately
* DECOUPLED from `remote` so every other remote protection — file_upload
* confinement, source isolation, fence stripping, takes-holder scoping — stays
* fully in force. The stdio MCP server sets it ONLY when the brain owner opts
* in via the `facts.trust_local_reads` config (default off). The HTTP/published
* transport never sets it, so a served brain stays world-only regardless.
*/
export interface FactReaderTrust {
/**
* Mirrors OperationContext.remote. FAIL-CLOSED: anything not strictly
* `false` is treated as remote/untrusted (CLAUDE.md trust invariant).
*/
remote?: boolean;
/** Owner opt-in: this remote caller may read private facts. */
trustedFactReads?: boolean;
}
/**
* True when the reader is restricted to `visibility = 'world'` rows.
* Fail-closed: an unset/undefined `remote` is untrusted — only an explicit
* `remote: false` (trusted local CLI) or an explicit owner opt-in
* (`trustedFactReads: true`) reads private rows.
*/
export function factsWorldOnly(t: FactReaderTrust): boolean {
return t.remote !== false && t.trustedFactReads !== true;
}
/**
* Visibility filter for list-style fact reads: `['world']` when the reader is
* world-only, `undefined` (no filter — all rows) when it is trusted.
*/
export function readableFactVisibilities(
t: FactReaderTrust,
): ('private' | 'world')[] | undefined {
return factsWorldOnly(t) ? ['world'] : undefined;
}
+7 -14
View File
@@ -18,7 +18,6 @@ import { captureEvalCandidate, isEvalCaptureEnabled, isEvalScrubEnabled } from '
import type { HybridSearchMeta } from './types.ts';
import { extractPageLinks, isAutoLinkEnabled, isAutoTimelineEnabled, isGlobalBasenameEnabled, parseTimelineEntries, makeResolver, type UnresolvedFrontmatterRef } from './link-extraction.ts';
import { isFactsBackstopEligible } from './facts/eligibility.ts';
import { readableFactVisibilities } from './facts/reader-trust.ts';
import { stripTakesFence } from './takes-fence.ts';
import { stripFactsFence } from './facts-fence.ts';
import { getContentFlag } from './quarantine.ts';
@@ -333,15 +332,6 @@ export interface OperationContext {
* remote/untrusted (defense in depth in case the type is bypassed via cast).
*/
remote: boolean;
/**
* Owner opt-in (`facts.trust_local_reads`): allow this remote caller to read
* `private` facts. A NARROW, read-only trust elevation decoupled from
* `remote` — every other remote protection (file confinement, source
* isolation, fence stripping, takes scoping) stays in force. Set ONLY by the
* stdio MCP server when the config is on; the HTTP transport never sets it.
* Consulted via `src/core/facts/reader-trust.ts`.
*/
trustedFactReads?: boolean;
/**
* Subagent runtime context (v0.16+). Set by the subagent tool dispatcher when
* dispatching an op as a tool call from an LLM loop. Used to enforce per-op
@@ -3639,7 +3629,6 @@ const find_trajectory: Operation = {
entitySlug: p.entity_slug,
...scope,
remote: ctx.remote === true,
trustedFactReads: ctx.trustedFactReads === true,
metric,
kind,
since,
@@ -4000,9 +3989,13 @@ const recall: Operation = {
const includeExpired = p.include_expired === true;
const grep = typeof p.grep === 'string' ? p.grep.toLowerCase() : null;
// Visibility filter: world-only for untrusted remote callers; all rows for
// trusted local CLI and owner-trusted reads (facts.trust_local_reads).
const visibility = readableFactVisibilities(ctx);
// Visibility filter: remote callers see world-only unless their token
// grants elevated visibility (future-proofing; v0.31 ships world-only
// for remote, all for local CLI).
const visibility =
ctx.remote === false
? undefined
: ['world'] as ('private' | 'world')[];
let rows: Awaited<ReturnType<typeof ctx.engine.listFactsByEntity>> = [];
+19 -13
View File
@@ -18,7 +18,6 @@ import type {
} from './engine.ts';
import { MAX_SEARCH_LIMIT, clampSearchLimit } from './engine.ts';
import { withRetry, BULK_RETRY_OPTS, resolveBulkRetryOpts, computeNextDelay, type BatchAuditSite } from './retry.ts';
import { factsWorldOnly } from './facts/reader-trust.ts';
import { logBatchRetry as auditLogBatchRetry, logBatchExhausted as auditLogBatchExhausted } from './audit/batch-retry-audit.ts';
import { runMigrations } from './migrate.ts';
import { PGLITE_SCHEMA_SQL, getPGLiteSchema } from './pglite-schema.ts';
@@ -4103,11 +4102,13 @@ export class PGLiteEngine implements BrainEngine {
): Promise<{ inserted: number; ids: number[] }> {
if (rows.length === 0) return { inserted: 0, ids: [] };
// Single transaction so the v51 partial UNIQUE index can roll back the
// whole batch on constraint violation. Per-row INSERTs (not multi-row
// VALUES) keep the embedding-vs-no-embedding branching readable; batch
// sizes are small (5-30 rows per page in practice) so the loop overhead
// is negligible vs the embedding compute cost.
// Single transaction; per-row INSERTs (not multi-row VALUES) keep the
// embedding-vs-no-embedding branching readable; batch sizes are small
// (5-30 rows per page in practice) so the loop overhead is negligible
// vs the embedding compute cost. #2044: ON CONFLICT DO NOTHING on the
// v51 partial UNIQUE index makes a residual fence/DB row_num collision
// skip that row instead of rolling back the whole batch (parity with
// postgres-engine.ts).
const ids = await this.db.transaction(async (tx) => {
const out: number[] = [];
for (const input of rows) {
@@ -4150,7 +4151,11 @@ export class PGLiteEngine implements BrainEngine {
$14, $15,
$16, $17, $18, $19,
$20
) RETURNING id`
)
ON CONFLICT (source_id, source_markdown_slug, row_num)
WHERE row_num IS NOT NULL
DO NOTHING
RETURNING id`
: `INSERT INTO facts (
source_id, entity_slug, fact, kind, visibility, notability, context,
valid_from, valid_until, source, source_session, confidence,
@@ -4164,12 +4169,16 @@ export class PGLiteEngine implements BrainEngine {
$15, $16,
$17, $18, $19, $20,
$21
) RETURNING id`,
)
ON CONFLICT (source_id, source_markdown_slug, row_num)
WHERE row_num IS NOT NULL
DO NOTHING
RETURNING id`,
embedStr === null
? [ctx.source_id, entitySlug, input.fact, kind, visibility, notability, context, validFrom, validUntil, input.source, sourceSession, confidence, embeddedAt, input.row_num, input.source_markdown_slug, claimMetric, claimValue, claimUnit, claimPeriod, eventType]
: [ctx.source_id, entitySlug, input.fact, kind, visibility, notability, context, validFrom, validUntil, input.source, sourceSession, confidence, embedStr, embeddedAt, input.row_num, input.source_markdown_slug, claimMetric, claimValue, claimUnit, claimPeriod, eventType],
);
out.push(ins.rows[0].id);
if (ins.rows[0]) out.push(ins.rows[0].id);
}
return out;
});
@@ -4319,10 +4328,7 @@ export class PGLiteEngine implements BrainEngine {
const useArray = Array.isArray(opts.sourceIds) && opts.sourceIds.length > 0;
const sourceIds = useArray ? opts.sourceIds! : null;
const sourceId = opts.sourceId ?? 'default';
// Direct-engine contract: unset `remote` here means a trusted in-process
// caller (CLI/tests) — the fail-closed default lives in the op layer, which
// always passes explicit booleans. Normalize before the fail-closed helper.
const remoteFilter = factsWorldOnly({ remote: opts.remote === true, trustedFactReads: opts.trustedFactReads === true });
const remoteFilter = opts.remote === true;
// Build SQL dynamically. PGLite uses $N positional params; we
// assemble the WHERE clauses + params array in tandem to keep them
+13 -11
View File
@@ -14,7 +14,6 @@ import type {
SourceRow,
} from './engine.ts';
import { withRetry, BULK_RETRY_OPTS, resolveBulkRetryOpts, computeNextDelay, type BatchAuditSite } from './retry.ts';
import { factsWorldOnly } from './facts/reader-trust.ts';
import { logBatchRetry as auditLogBatchRetry, logBatchExhausted as auditLogBatchExhausted } from './audit/batch-retry-audit.ts';
import type {
DomainBankSampleOpts, CorpusSampleOpts, DomainBankRow,
@@ -4303,10 +4302,12 @@ export class PostgresEngine implements BrainEngine {
// ONCE per process so the cast matches the actual column type
// (halfvec vs vector). The probe is cached after first call.
const castSuffix = await this.resolveFactsEmbeddingCast();
// Single transaction so the v51 partial UNIQUE index can roll back
// the whole batch on constraint violation. Per-row INSERTs (not
// multi-row VALUES) keep the embedding-vs-no-embedding branching
// readable; batch sizes are small (5-30 rows per page in practice).
// Single transaction; per-row INSERTs (not multi-row VALUES) keep the
// embedding-vs-no-embedding branching readable; batch sizes are small
// (5-30 rows per page in practice). #2044: ON CONFLICT DO NOTHING on
// the v51 partial UNIQUE index makes a residual fence/DB row_num
// collision skip that row instead of rolling back the whole batch —
// the fence stays system-of-record and reconciliation catches up.
// No supersede flow in this path — fence reconciliation is the
// canonical source-of-truth direction, not the consolidator path.
const ids = await sql.begin(async (tx) => {
@@ -4347,9 +4348,13 @@ export class PostgresEngine implements BrainEngine {
${input.row_num}, ${input.source_markdown_slug},
${claimMetric}, ${claimValue}, ${claimUnit}, ${claimPeriod},
${eventType}
) RETURNING id
)
ON CONFLICT (source_id, source_markdown_slug, row_num)
WHERE row_num IS NOT NULL
DO NOTHING
RETURNING id
`;
out.push(Number(ins[0].id));
if (ins[0]) out.push(Number(ins[0].id));
}
return out;
});
@@ -4533,10 +4538,7 @@ export class PostgresEngine implements BrainEngine {
const useArray = Array.isArray(opts.sourceIds) && opts.sourceIds.length > 0;
const sourceIds = useArray ? opts.sourceIds! : null;
const sourceId = opts.sourceId ?? 'default';
// Direct-engine contract: unset `remote` here means a trusted in-process
// caller (CLI/tests) — the fail-closed default lives in the op layer, which
// always passes explicit booleans. Normalize before the fail-closed helper.
const remoteFilter = factsWorldOnly({ remote: opts.remote === true, trustedFactReads: opts.trustedFactReads === true });
const remoteFilter = opts.remote === true;
// Source-scope predicate: array path (federated) wins over scalar.
// Engine.ts contract: returns chronological points; regressions +
-8
View File
@@ -30,13 +30,6 @@ export interface ToolResult {
export interface DispatchOpts {
/** Defaults to true (remote/untrusted). Local CLI callers (`gbrain call`) pass false. */
remote?: boolean;
/**
* Owner opt-in (`facts.trust_local_reads`): let this remote caller read
* `private` facts. Set ONLY by the stdio MCP server; the HTTP transport
* leaves it unset so a served brain stays world-only. See
* `src/core/facts/reader-trust.ts`.
*/
trustedFactReads?: boolean;
/** Override the default stderr logger (e.g. CLI uses console.* directly). */
logger?: OperationContext['logger'];
/**
@@ -210,7 +203,6 @@ export function buildOperationContext(
logger: opts.logger || stderrLogger,
dryRun: !!params.dry_run,
remote: opts.remote ?? true,
trustedFactReads: opts.trustedFactReads === true,
takesHoldersAllowList: opts.takesHoldersAllowList,
// v0.34 D4: sourceId is REQUIRED at the type level. Auto-fill 'default'
// for single-source brains and any caller who didn't resolve a sourceId.
-11
View File
@@ -35,16 +35,6 @@ export async function startMcpServer(engine: BrainEngine) {
// shape and cast through `any` (the SDK accepts it via the ServerResult union).
server.setRequestHandler(CallToolRequestSchema, async (request: any): Promise<any> => {
const { name, arguments: params } = request.params;
// Owner opt-in: the stdio pipe is local + unauthenticated, so on a
// single-owner machine its caller is the owner. When facts.trust_local_reads
// is on, let fact reads (find_trajectory / recall) see this owner's own
// private facts. Narrow + read-only — every other remote protection stays
// on (remote stays true). HTTP transport never sets this. Best-effort: a
// config read blip falls back to the safe world-only default.
let trustedFactReads = false;
try {
trustedFactReads = (await engine.getConfig('facts.trust_local_reads')) === 'true';
} catch { /* keep world-only default */ }
// v0.28: stdio MCP has no per-token auth (local pipe). Default the
// takes-holder allow-list to ['world'] so agent-facing callers don't
// see private hunches via takes_list / takes_search / query. Operators
@@ -52,7 +42,6 @@ export async function startMcpServer(engine: BrainEngine) {
// `gbrain call <op>` (sets remote=false in src/cli.ts).
return dispatchToolCall(engine, name, params, {
remote: true,
trustedFactReads,
takesHoldersAllowList: ['world'],
// v0.31: source defaults to 'default' for stdio (no per-token scope).
// Operators who want a different source on stdio MCP should set
-16
View File
@@ -165,22 +165,6 @@ describe('findTrajectory — visibility filter (D-CDX-1 / R6)', () => {
const all = await engine.findTrajectory({ entitySlug: 'traj-vis-default' });
expect(all.length).toBe(2);
});
test('remote=true + trustedFactReads bypasses world-only (owner-trusted reads)', async () => {
await insertTyped({ entity_slug: 'traj-vis-trusted', metric: 'mrr', value: 50000, visibility: 'private', valid_from: new Date('2026-01-15') });
await insertTyped({ entity_slug: 'traj-vis-trusted', metric: 'mrr', value: 99999, visibility: 'world', valid_from: new Date('2026-04-12') });
// Untrusted remote: world only.
const untrusted = await engine.findTrajectory({ entitySlug: 'traj-vis-trusted', remote: true });
expect(untrusted.length).toBe(1);
expect(untrusted[0].value).toBe(99999);
// Owner-trusted remote: sees the private point too. remote stays true — only
// fact-read visibility is elevated.
const trusted = await engine.findTrajectory({ entitySlug: 'traj-vis-trusted', remote: true, trustedFactReads: true });
expect(trusted.length).toBe(2);
expect(trusted.map(p => p.value).sort((a, b) => (a! - b!))).toEqual([50000, 99999]);
});
});
describe('findTrajectory — metric + since + until filters', () => {
+3 -1
View File
@@ -304,7 +304,9 @@ describe('runExtractFacts — empty-fence guard (Codex R2-#7)', () => {
expect(r.legacyRowsPending).toBe(1);
expect(r.factsInserted).toBe(0);
expect(r.factsDeleted).toBe(0);
expect(r.warnings.some(w => w.includes('apply-migrations'))).toBe(true);
// #1867: the remedy hint points at the re-runnable backfill command,
// not the one-shot v0_32_2 migration (which the ledger never re-runs).
expect(r.warnings.some(w => w.includes('gbrain facts fence-backfill'))).toBe(true);
// Legacy row was NOT touched.
// eslint-disable-next-line @typescript-eslint/no-explicit-any
+133
View File
@@ -0,0 +1,133 @@
/**
* #1867 — `gbrain facts fence-backfill` command tests.
*
* The command re-runs the (idempotent) v0_32_2 phase B on demand so
* row_num-NULL backlogs — remote extract_facts deposits that predate
* the fence-write backstop — can be cleared without re-running the
* one-shot migration. Real PGLite + real tempdir filesystem.
*/
import { describe, test, expect, beforeAll, afterAll, beforeEach } from 'bun:test';
import { mkdtempSync, rmSync, existsSync, readFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { runFactsCommand } from '../src/commands/facts.ts';
import { phaseBFenceFacts } from '../src/commands/migrations/v0_32_2.ts';
let engine: PGLiteEngine;
let brainDir: string;
beforeAll(async () => {
engine = new PGLiteEngine();
await engine.connect({});
await engine.initSchema();
});
afterAll(async () => {
await engine.disconnect();
try {
if (brainDir) rmSync(brainDir, { recursive: true, force: true });
} catch { /* best-effort */ }
});
beforeEach(async () => {
brainDir = mkdtempSync(join(tmpdir(), 'facts-backfill-cmd-test-'));
// eslint-disable-next-line @typescript-eslint/no-explicit-any
await (engine as any).db.query('DELETE FROM facts');
// eslint-disable-next-line @typescript-eslint/no-explicit-any
await (engine as any).db.query(
`UPDATE sources SET local_path = $1 WHERE id = 'default'`,
[brainDir],
);
});
async function seedLegacyFact(fact: string): Promise<void> {
// The row_num-NULL shape a remote extract_facts deposit leaves behind
// when it lands via the legacy DB-only path.
// eslint-disable-next-line @typescript-eslint/no-explicit-any
await (engine as any).db.query(
`INSERT INTO facts (source_id, entity_slug, fact, kind, visibility, notability,
valid_from, source, confidence)
VALUES ('default', 'people/alice', $1, 'fact', 'private', 'medium',
now(), 'mcp:extract_facts', 1.0)`,
[fact],
);
}
describe('gbrain facts fence-backfill', () => {
test('fences row_num-NULL rows and stamps the DB', async () => {
await seedLegacyFact('Deposited remotely');
await runFactsCommand(engine, ['fence-backfill']);
// The fence exists on disk with the claim.
const filePath = join(brainDir, 'people/alice.md');
expect(existsSync(filePath)).toBe(true);
expect(readFileSync(filePath, 'utf-8')).toContain('Deposited remotely');
// The backlog is cleared: no row_num-NULL rows remain.
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const rows = await (engine as any).db.query(
'SELECT row_num, source_markdown_slug FROM facts',
);
expect(rows.rows).toHaveLength(1);
expect(rows.rows[0].row_num).toBe(1);
expect(rows.rows[0].source_markdown_slug).toBe('people/alice');
});
test('re-run is a no-op (idempotent)', async () => {
await seedLegacyFact('Deposited remotely');
await runFactsCommand(engine, ['fence-backfill']);
await runFactsCommand(engine, ['fence-backfill']);
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const rows = await (engine as any).db.query('SELECT id FROM facts');
expect(rows.rows).toHaveLength(1);
const body = readFileSync(join(brainDir, 'people/alice.md'), 'utf-8');
expect(body.match(/Deposited remotely/g)).toHaveLength(1);
});
test('--dry-run reports without writing', async () => {
await seedLegacyFact('Deposited remotely');
await runFactsCommand(engine, ['fence-backfill', '--dry-run']);
expect(existsSync(join(brainDir, 'people/alice.md'))).toBe(false);
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const rows = await (engine as any).db.query(
'SELECT row_num FROM facts',
);
expect(rows.rows[0].row_num).toBeNull();
});
test('diverged page: appends past the DB row_num max instead of colliding (#2044 class)', async () => {
// The #2044 divergence shape the backfill must survive: the DB already
// holds stamped rows 1..3 for the slug (legacy wrong-path fence write),
// but the fence at the resolved path is missing. Fence-max+1 (= 1) would
// collide with the stamped rows on the post-rename UPDATE, failing the
// page and leaving the renamed fence disagreeing with the DB.
for (let n = 1; n <= 3; n++) {
// eslint-disable-next-line @typescript-eslint/no-explicit-any
await (engine as any).db.query(
`INSERT INTO facts (source_id, entity_slug, fact, kind, visibility, notability,
valid_from, source, confidence, row_num, source_markdown_slug)
VALUES ('default', 'people/alice', $1, 'fact', 'private', 'medium',
now(), 'mcp:extract_facts', 1.0, $2, 'people/alice')`,
[`stamped ${n}`, n],
);
}
await seedLegacyFact('Deposited remotely');
const result = await phaseBFenceFacts(engine, { dryRun: false });
expect(result.status).toBe('complete');
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const rows = await (engine as any).db.query(
`SELECT row_num FROM facts WHERE fact = 'Deposited remotely'`,
);
expect(rows.rows[0].row_num).toBe(4);
const body = readFileSync(join(brainDir, 'people/alice.md'), 'utf-8');
expect(body).toContain('| 4 | Deposited remotely |');
});
});
-43
View File
@@ -1,43 +0,0 @@
import { describe, test, expect } from 'bun:test';
import {
factsWorldOnly,
readableFactVisibilities,
} from '../src/core/facts/reader-trust.ts';
describe('factsWorldOnly', () => {
test('FAIL-CLOSED: unset remote is untrusted (world-only)', () => {
expect(factsWorldOnly({})).toBe(true);
expect(factsWorldOnly({ remote: undefined })).toBe(true);
expect(factsWorldOnly({ trustedFactReads: false })).toBe(true);
});
test('explicit remote=false (trusted local CLI) sees all', () => {
expect(factsWorldOnly({ remote: false })).toBe(false);
expect(factsWorldOnly({ remote: false, trustedFactReads: false })).toBe(false);
});
test('untrusted remote callers are world-only', () => {
expect(factsWorldOnly({ remote: true })).toBe(true);
expect(factsWorldOnly({ remote: true, trustedFactReads: false })).toBe(true);
});
test('owner-trusted remote reads bypass the world-only filter', () => {
expect(factsWorldOnly({ remote: true, trustedFactReads: true })).toBe(false);
});
test('trustedFactReads is a no-op for an already-trusted local caller', () => {
expect(factsWorldOnly({ remote: false, trustedFactReads: true })).toBe(false);
});
});
describe('readableFactVisibilities', () => {
test("world-only readers get the ['world'] filter (incl. unset remote)", () => {
expect(readableFactVisibilities({ remote: true })).toEqual(['world']);
expect(readableFactVisibilities({})).toEqual(['world']);
});
test('trusted readers get undefined (no filter — all rows)', () => {
expect(readableFactVisibilities({ remote: false })).toBeUndefined();
expect(readableFactVisibilities({ remote: true, trustedFactReads: true })).toBeUndefined();
});
});
+43
View File
@@ -292,6 +292,49 @@ describe('lookupSourceLocalPath', () => {
});
});
describe('writeFactsToFence — fence/DB divergence (#2044)', () => {
test('seeds row_num past the DB max when the fence lags the DB', async () => {
// Simulate the divergence class from #2044: DB rows were stamped with
// row_nums against a fence written at a path this code no longer reads
// (e.g. the pre-"Local patch 2026-06-11" wrong-path writes). The page
// on disk has NO fence, but the DB already holds row_num 1..3 for the
// slug. Pre-fix, the next deposit re-assigned row_num=1 from fence
// text alone and the whole insertFacts batch failed on
// idx_facts_fence_key.
for (let n = 1; n <= 3; n++) {
// eslint-disable-next-line @typescript-eslint/no-explicit-any
await (engine as any).db.query(
`INSERT INTO facts (source_id, entity_slug, fact, kind, visibility, notability,
valid_from, source, confidence, row_num, source_markdown_slug)
VALUES ('default', 'people/dana', $1, 'fact', 'private', 'medium',
now(), 'mcp:extract_facts', 1.0, $2, 'people/dana')`,
[`old claim ${n}`, n],
);
}
const result = await writeFactsToFence(
engine,
{ sourceId: 'default', localPath: brainDir, slug: 'people/dana' },
[baseInput({ fact: 'second deposit' })],
);
expect(result.fenceWriteFailed).toBeUndefined();
expect(result.inserted).toBe(1);
// The new row landed PAST the DB max, not at fence-max+1 (= 1).
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const rows = await (engine as any).db.query(
'SELECT row_num FROM facts WHERE id = $1',
[result.ids[0]],
);
expect(rows.rows[0].row_num).toBe(4);
// And the on-disk fence carries the same row_num — fence and DB agree.
const body = readFileSync(join(brainDir, 'people/dana.md'), 'utf-8');
expect(body).toContain('| 4 | second deposit |');
});
});
// Cleanup any leftover tempdirs after the whole suite.
afterAll(() => {
// No-op: each test cleaned up via the beforeEach; this is a safety net.
+18 -19
View File
@@ -5,7 +5,7 @@
* - Batch insert N rows persists row_num + source_markdown_slug
* - Empty batch is a no-op
* - Returns ids in input-order
* - v51 partial UNIQUE index rolls back the whole batch on a collision
* - v51 partial UNIQUE collision skips only the colliding row (#2044)
* - deleteFactsForPage scopes by (source_id, source_markdown_slug);
* never touches other pages or pre-v51 NULL-source_markdown_slug rows
* - deleteFactsForPage on an empty page returns deleted:0 (idempotent)
@@ -135,30 +135,29 @@ describe('engine.insertFacts — batch insert', () => {
});
});
test('v51 partial UNIQUE index rolls back the whole batch on collision', async () => {
test('v51 partial UNIQUE collision skips ONLY the colliding row (#2044)', async () => {
// Seed row #1 first.
await engine.insertFacts([fixtureFact(1, { fact: 'seeded' })], { source_id: 'default' });
// Now try to batch-insert rows that include a colliding row_num=1.
let threw = false;
try {
await engine.insertFacts(
[
fixtureFact(2, { fact: 'second' }),
fixtureFact(1, { fact: 'collides' }), // row_num=1 on same (source_id, source_markdown_slug)
fixtureFact(3, { fact: 'third' }),
],
{ source_id: 'default' },
);
} catch {
threw = true;
}
expect(threw).toBe(true);
// Batch-insert rows that include a colliding row_num=1. Pre-#2044 this
// threw and rolled back the whole batch, making a second remote
// extract_facts deposit to an already-fenced page a hard failure. Now
// ON CONFLICT DO NOTHING skips the colliding row and keeps the rest.
const result = await engine.insertFacts(
[
fixtureFact(2, { fact: 'second' }),
fixtureFact(1, { fact: 'collides' }), // row_num=1 on same (source_id, source_markdown_slug)
fixtureFact(3, { fact: 'third' }),
],
{ source_id: 'default' },
);
expect(result.inserted).toBe(2);
expect(result.ids).toHaveLength(2);
// Verify the transaction rolled back — only the seeded row should remain.
// The seeded row survives untouched; the colliding claim is skipped.
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const rows = await (engine as any).db.query('SELECT fact FROM facts ORDER BY id');
expect(rows.rows.map((r: { fact: string }) => r.fact)).toEqual(['seeded']);
expect(rows.rows.map((r: { fact: string }) => r.fact)).toEqual(['seeded', 'second', 'third']);
});
test('different source_markdown_slug values DO NOT collide on the same row_num', async () => {