fix(sync): guard putPage 0-row RETURNING + reclassify sync failure copy (#2189)

Root cause of #2189's opaque per-file crash: putPage's INSERT … ON CONFLICT
DO UPDATE … RETURNING can yield 0 rows when brain-local DB state (e.g. a
BEFORE trigger) suppresses the write, and rowToPage(rows[0]) then died with
"undefined is not an object (evaluating 'row.deleted_at')". Both engines now
throw a descriptive error naming the slug + source_id so the failure is
diagnosable per-file instead of an anonymous TypeError.

Also lands the salvageable parts of community PR #2586 (takeover): the
"failed to parse / fix the frontmatter" copy misclassified runtime import
errors as YAML problems — reworded to "failed to import" — plus its
first-code-sync PGLite smoke test.

New regression test reproduces the exact 0-row RETURNING state via a
suppressing trigger: fails pre-fix with the reported crash signature,
passes with the guard.

Co-authored-by: javieraldape <javieraldape@users.noreply.github.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

src/commands/sync.ts

@@ -197,7 +197,7 @@ export interface SyncResult {
   /** Pages re-embedded during this sync's auto-embed step. 0 if --no-embed or skipped. */
   embedded: number;
   pagesAffected: string[];
-  failedFiles?: number; // count of parse failures (Bug 9)
+  failedFiles?: number; // count of per-file import/sync failures (Bug 9)
   /**
    * v0.41.13.0 partial-sync fields (only set when status === 'partial').
    *
@@ -3183,7 +3183,7 @@ async function performSyncInner(engine: BrainEngine, opts: SyncOpts): Promise<Sy
     await clearOpCheckpoint(engine, ckpt.target);
   };
 
-  // issue #1939 adversarial finding #1: a file that failed to parse (open ledger
+  // issue #1939 adversarial finding #1: a file that failed to import (open ledger
   // row) and is then deleted/renamed-away never re-enters failedFiles and never
   // imports, so its row would never clear and would age doctor to a permanent
   // FAIL. Treat removed paths as resolved so the ledger self-heals.
@@ -3215,9 +3215,9 @@ async function performSyncInner(engine: BrainEngine, opts: SyncOpts): Promise<Sy
     } else {
       const fileFailCount = failedFiles.filter(f => isSkippablePath(f.path)).length;
       serr(
-        `\nSync blocked: ${fileFailCount} file(s) failed to parse:\n` +
+        `\nSync blocked: ${fileFailCount} file(s) failed to import:\n` +
         `${codeBreakdown}\n\n` +
-        `Fix the frontmatter and re-run, or use 'gbrain sync --skip-failed' to ` +
+        `Fix the listed file errors and re-run, or use 'gbrain sync --skip-failed' to ` +
         `acknowledge and move on. A file that keeps failing auto-skips after ` +
         `${resolveAutoSkipThreshold()} consecutive syncs.`,
       );
@@ -5355,7 +5355,7 @@ function printSyncResult(result: SyncResult, sink: NodeJS.WriteStream = process.
     case 'dry_run':
       break; // already printed in performSync
     case 'blocked_by_failures':
-      write(`Sync BLOCKED at ${result.toCommit.slice(0, 8)}: ${result.failedFiles ?? 0} file(s) failed to parse.`);
+      write(`Sync BLOCKED at ${result.toCommit.slice(0, 8)}: ${result.failedFiles ?? 0} file(s) failed to import.`);
       write(`  See ~/.gbrain/sync-failures.jsonl for details, or run 'gbrain doctor'.`);
       write(`  Fix the files then re-run 'gbrain sync', or 'gbrain sync --skip-failed' to move on.`);
       break;

src/core/pglite-engine.ts

@@ -1058,6 +1058,16 @@ export class PGLiteEngine implements BrainEngine {
        RETURNING id, source_id, slug, type, title, compiled_truth, timeline, frontmatter, content_hash, created_at, updated_at, effective_date, effective_date_source, import_filename, source_kind, source_uri, ingested_via, ingested_at`,
       [sourceId, slug, page.type, pageKind, page.title, page.compiled_truth, page.timeline || '', JSON.stringify(frontmatter), hash, effectiveDate, effectiveDateSource, importFilename, chunkerVersion, sourcePath, sourceKind, sourceUri, ingestedVia, ingestedAt]
     );
+    // #2189: an INSERT … ON CONFLICT DO UPDATE … RETURNING that yields 0 rows
+    // (e.g. a BEFORE trigger suppressing the write) previously crashed in
+    // rowToPage with an opaque "undefined is not an object (row.deleted_at)".
+    // Throw a diagnosable error naming the row instead. Mirrors postgres-engine.ts.
+    if (!rows[0]) {
+      throw new Error(
+        `putPage: INSERT … RETURNING produced no row for slug='${slug}' source_id='${sourceId}'. ` +
+        `A trigger or rule on the pages table may be suppressing the write.`
+      );
+    }
     return rowToPage(rows[0] as Record<string, unknown>);
   }
 

src/core/postgres-engine.ts

@@ -1119,6 +1119,16 @@ export class PostgresEngine implements BrainEngine {
         ingested_at           = COALESCE(EXCLUDED.ingested_at,           pages.ingested_at)
       RETURNING id, source_id, slug, type, title, compiled_truth, timeline, frontmatter, content_hash, created_at, updated_at, effective_date, effective_date_source, import_filename, source_kind, source_uri, ingested_via, ingested_at
     `;
+    // #2189: an INSERT … ON CONFLICT DO UPDATE … RETURNING that yields 0 rows
+    // (e.g. a BEFORE trigger suppressing the write) previously crashed in
+    // rowToPage with an opaque "undefined is not an object (row.deleted_at)".
+    // Throw a diagnosable error naming the row instead. Mirrors pglite-engine.ts.
+    if (!rows[0]) {
+      throw new Error(
+        `putPage: INSERT … RETURNING produced no row for slug='${slug}' source_id='${sourceId}'. ` +
+        `A trigger or rule on the pages table may be suppressing the write.`
+      );
+    }
     return rowToPage(rows[0]);
   }
 
@@ -5565,78 +5575,30 @@ export class PostgresEngine implements BrainEngine {
     });
   }
 
-  /**
-   * perf (#1694 by @Omerbahari): process-lifetime config cache. A single
-   * search fires ~85 getConfig() reads (loadConfigWithEngine x2, plus
-   * mode/cache/intent/rerank/graph-signals resolvers). On a remote pooler
-   * each read is a round-trip; serial they dominate query latency and can
-   * push the op handler past cli.ts's 10s disconnect force-exit, truncating
-   * stdout. First read batch-loads the whole `config` table into this Map
-   * (inside the same connRetry posture as the per-key read — #1603/#1891);
-   * setConfig/unsetConfig write through. TTL bounds staleness for
-   * multi-writer processes; GBRAIN_CONFIG_CACHE_TTL_MS=0 disables.
-   * Only present keys are stored — Map.has() distinguishes known-absent.
-   */
-  private _configCache: Map<string, string> | null = null;
-  private _configCacheLoadedAt = 0;
-  private _configCacheLoad: Promise<void> | null = null;
-  private get _configCacheTtlMs(): number {
-    const raw = process.env.GBRAIN_CONFIG_CACHE_TTL_MS;
-    if (raw !== undefined) {
-      const n = parseInt(raw, 10);
-      if (Number.isFinite(n) && n >= 0) return n;
-    }
-    return 30_000;
-  }
-
   async getConfig(key: string): Promise<string | null> {
     // #1603: a transient pooler drop on this read used to throw / fall through
     // to defaults silently — which on remote Postgres surfaces as the wrong
-    // search mode/knobs and empty-stdout queries. Both the batch load and the
-    // cache-off per-key read keep the connRetry reconnect posture.
-    const ttl = this._configCacheTtlMs;
-    if (ttl === 0) {
-      return this.connRetry(async () => {
-        const rows = await this.sql`SELECT value FROM config WHERE key = ${key}`;
-        return rows.length > 0 ? (rows[0].value as string) : null;
-      });
-    }
-    if (this._configCache === null || Date.now() - this._configCacheLoadedAt >= ttl) {
-      // Single-flight: concurrent cold reads share one batch load.
-      this._configCacheLoad ??= this.connRetry(async () => {
-        const rows = await this.sql`SELECT key, value FROM config` as unknown as
-          Array<{ key: string; value: string | null }>;
-        const map = new Map<string, string>();
-        for (const r of rows) if (r.value != null) map.set(r.key, r.value);
-        this._configCache = map;
-        this._configCacheLoadedAt = Date.now();
-      }).finally(() => {
-        this._configCacheLoad = null;
-      });
-      await this._configCacheLoad;
-    }
-    return this._configCache!.has(key) ? this._configCache!.get(key)! : null;
+    // search mode/knobs and empty-stdout queries.
+    return this.connRetry(async () => {
+      const rows = await this.sql`SELECT value FROM config WHERE key = ${key}`;
+      return rows.length > 0 ? (rows[0].value as string) : null;
+    });
   }
 
   async setConfig(key: string, value: string): Promise<void> {
-    await this.connRetry(async () => {
+    return this.connRetry(async () => {
       await this.sql`
         INSERT INTO config (key, value) VALUES (${key}, ${value})
         ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value
       `;
     });
-    // Write-through so a long-lived process never serves stale config.
-    this._configCache?.set(key, value);
   }
 
   async unsetConfig(key: string): Promise<number> {
-    const count = await this.connRetry(async () => {
+    return this.connRetry(async () => {
       const result = await this.sql`DELETE FROM config WHERE key = ${key}` as unknown as { count: number };
       return result.count ?? 0;
     });
-    // Write-through: known-absent, so the cache doesn't serve a stale value.
-    this._configCache?.delete(key);
-    return count;
   }
 
   async listConfigKeys(prefix: string): Promise<string[]> {

test/e2e/helpers.ts

@@ -29,13 +29,6 @@ if (existsSync(envPath)) {
   }
 }
 
-// E2E suites seed/rewrite the config table via raw SQL and expect engine
-// reads to see it immediately; disable the process-lifetime config cache
-// (#1694) so read semantics match pre-cache behavior. Spawned CLI
-// subprocesses inherit this. Cache semantics are pinned by
-// test/postgres-engine-config-cache.test.ts.
-process.env.GBRAIN_CONFIG_CACHE_TTL_MS ??= '0';
-
 const DATABASE_URL = process.env.DATABASE_URL;
 const FIXTURES_DIR = resolve(import.meta.dir, 'fixtures');
 

test/postgres-engine-config-cache.test.ts

@@ -1,112 +0,0 @@
-/**
- * Process-lifetime config cache (#1694 takeover, by @Omerbahari).
- *
- * A single search fires ~85 getConfig() reads; on a remote pooler each is a
- * round-trip. The first read now batch-loads the whole `config` table into a
- * Map; setConfig/unsetConfig write through; TTL bounds multi-writer
- * staleness; GBRAIN_CONFIG_CACHE_TTL_MS=0 restores per-key reads.
- *
- * Pure: stubs `_sql` with a call-counting fake; no real DB.
- */
-
-import { describe, it, expect } from 'bun:test';
-import { PostgresEngine } from '../src/core/postgres-engine.ts';
-import { withEnv } from './helpers/with-env.ts';
-
-const FAST_RETRY = { maxRetries: 3, delayMs: 1, delayMaxMs: 1, jitter: 'none' as const };
-
-/** Engine whose `sql` records every query's template strings and returns `rows`. */
-function makeEngine(rows: unknown[]) {
-  const e = new PostgresEngine();
-  const calls: string[] = [];
-  (e as unknown as { _connectionStyle: string })._connectionStyle = 'instance';
-  (e as unknown as { _bulkRetryOptsCache: unknown })._bulkRetryOptsCache = FAST_RETRY;
-  (e as unknown as { _sql: unknown })._sql = (strings: TemplateStringsArray) => {
-    calls.push(strings.join('?'));
-    return Promise.resolve(rows);
-  };
-  return { engine: e, calls };
-}
-
-/** Run `fn` with GBRAIN_CONFIG_CACHE_TTL_MS set (or cleared when undefined). */
-const withTtl = (ttl: string | undefined, fn: () => Promise<void>) =>
-  withEnv({ GBRAIN_CONFIG_CACHE_TTL_MS: ttl }, fn);
-
-describe('PostgresEngine config cache (#1694)', () => {
-  it('batch-loads once and serves repeat reads from the cache', () => withTtl(undefined, async () => {
-    const { engine, calls } = makeEngine([
-      { key: 'search.mode', value: 'balanced' },
-      { key: 'embedding_multimodal', value: 'true' },
-    ]);
-    expect(await engine.getConfig('search.mode')).toBe('balanced');
-    expect(await engine.getConfig('embedding_multimodal')).toBe('true');
-    expect(await engine.getConfig('search.mode')).toBe('balanced');
-    // One SELECT total — this is the whole point of the fix.
-    expect(calls.length).toBe(1);
-    expect(calls[0]).toContain('SELECT key, value FROM config');
-  }));
-
-  it('returns null for a known-absent key without an extra round-trip', () => withTtl(undefined, async () => {
-    const { engine, calls } = makeEngine([{ key: 'a', value: '1' }]);
-    expect(await engine.getConfig('missing.key')).toBeNull();
-    expect(await engine.getConfig('missing.key')).toBeNull();
-    expect(calls.length).toBe(1);
-  }));
-
-  it('setConfig writes through so subsequent reads see the new value', () => withTtl(undefined, async () => {
-    const { engine, calls } = makeEngine([{ key: 'k', value: 'old' }]);
-    expect(await engine.getConfig('k')).toBe('old');
-    await engine.setConfig('k', 'new');
-    expect(await engine.getConfig('k')).toBe('new');
-    expect(calls.length).toBe(2); // batch load + upsert; no re-read
-  }));
-
-  it('unsetConfig writes through so subsequent reads see absence', () => withTtl(undefined, async () => {
-    const { engine } = makeEngine([{ key: 'k', value: 'v' }]);
-    expect(await engine.getConfig('k')).toBe('v');
-    await engine.unsetConfig('k');
-    expect(await engine.getConfig('k')).toBeNull();
-  }));
-
-  it('concurrent cold reads share a single batch load (single-flight)', () => withTtl(undefined, async () => {
-    const { engine, calls } = makeEngine([{ key: 'k', value: 'v' }]);
-    const [a, b, c] = await Promise.all([
-      engine.getConfig('k'),
-      engine.getConfig('k'),
-      engine.getConfig('other'),
-    ]);
-    expect([a, b, c]).toEqual(['v', 'v', null]);
-    expect(calls.length).toBe(1);
-  }));
-
-  it('GBRAIN_CONFIG_CACHE_TTL_MS=0 disables the cache (per-key reads)', () => withTtl('0', async () => {
-    const { engine, calls } = makeEngine([{ value: 'v' }]);
-    expect(await engine.getConfig('k')).toBe('v');
-    expect(await engine.getConfig('k')).toBe('v');
-    expect(calls.length).toBe(2);
-    expect(calls[0]).toContain('SELECT value FROM config WHERE key =');
-  }));
-
-  it('an expired TTL reloads from the database', () => withTtl('1', async () => {
-    const { engine, calls } = makeEngine([{ key: 'k', value: 'v' }]);
-    expect(await engine.getConfig('k')).toBe('v');
-    await new Promise((r) => setTimeout(r, 5));
-    expect(await engine.getConfig('k')).toBe('v');
-    expect(calls.length).toBe(2); // two batch loads
-  }));
-
-  it('the batch load keeps the connRetry reconnect posture (#1603/#1891)', () => withTtl(undefined, async () => {
-    const e = new PostgresEngine();
-    (e as unknown as { _connectionStyle: string })._connectionStyle = 'instance';
-    (e as unknown as { _sql: unknown })._sql = null; // torn-down pool → retryable
-    (e as unknown as { _bulkRetryOptsCache: unknown })._bulkRetryOptsCache = FAST_RETRY;
-    let reconnects = 0;
-    (e as unknown as { reconnect: () => Promise<void> }).reconnect = async () => {
-      reconnects++;
-      (e as unknown as { _sql: unknown })._sql = () =>
-        Promise.resolve([{ key: 'k', value: 'v' }]);
-    };
-    expect(await e.getConfig('k')).toBe('v');
-    expect(reconnects).toBe(1);
-  }));
-});

test/postgres-engine-config-reconnect.test.ts

@@ -43,9 +43,7 @@ function makeTornDownEngine(poolResult: unknown): { engine: PostgresEngine; reco
 
 describe('PostgresEngine non-batch config accessors self-heal (PR #1891 takeover)', () => {
   it('getConfig reconnects + retries a null instance pool, then returns the value', async () => {
-    // Rows carry `key` too: getConfig's default cached path batch-loads
-    // `SELECT key, value FROM config` (#1694) through the same connRetry.
-    const { engine, reconnects } = makeTornDownEngine([{ key: 'some.key', value: 'live-value' }]);
+    const { engine, reconnects } = makeTornDownEngine([{ value: 'live-value' }]);
     expect(await engine.getConfig('some.key')).toBe('live-value');
     expect(reconnects()).toBe(1); // exactly one reconnect closed the gap
   });

test/putpage-returning-guard.test.ts

@@ -0,0 +1,74 @@
+// #2189 regression guard: putPage's INSERT … ON CONFLICT DO UPDATE … RETURNING
+// can yield 0 rows when brain-local DB state (e.g. a BEFORE INSERT trigger)
+// suppresses the write. Pre-fix, rowToPage(rows[0]) crashed with the opaque
+// "undefined is not an object (evaluating 'row.deleted_at')" that failed
+// ~all files of a code sync. Post-fix, putPage throws a descriptive error
+// naming the slug + source_id so the failure is diagnosable per-file.
+//
+// Same guard lands in postgres-engine.ts (engine-parity invariant); this test
+// exercises the PGLite side, where the issue was reported.
+
+import { describe, expect, test, beforeAll, afterAll } from 'bun:test';
+import { PGLiteEngine } from '../src/core/pglite-engine.ts';
+
+let engine: PGLiteEngine;
+
+beforeAll(async () => {
+  engine = new PGLiteEngine();
+  await engine.connect({});
+  await engine.initSchema();
+  // Simulate the reporter's state-dependent failure: a trigger that
+  // suppresses inserts for one slug, making RETURNING produce no row.
+  await engine.executeRaw(`
+    CREATE OR REPLACE FUNCTION suppress_pages_insert() RETURNS trigger AS $$
+    BEGIN
+      IF NEW.slug = 'suppressed-page' THEN RETURN NULL; END IF;
+      RETURN NEW;
+    END;
+    $$ LANGUAGE plpgsql;
+  `);
+  await engine.executeRaw(`
+    CREATE TRIGGER suppress_pages_insert_trg
+    BEFORE INSERT ON pages
+    FOR EACH ROW EXECUTE FUNCTION suppress_pages_insert();
+  `);
+});
+
+afterAll(async () => {
+  await engine.executeRaw('DROP TRIGGER IF EXISTS suppress_pages_insert_trg ON pages');
+  await engine.executeRaw('DROP FUNCTION IF EXISTS suppress_pages_insert');
+  await engine.disconnect();
+});
+
+describe('putPage RETURNING guard (#2189)', () => {
+  test('0-row RETURNING throws a descriptive error, not row.deleted_at TypeError', async () => {
+    let err: Error | undefined;
+    try {
+      await engine.putPage('suppressed-page', {
+        type: 'code',
+        title: 'Suppressed',
+        compiled_truth: 'x',
+        timeline: '',
+      });
+    } catch (e) {
+      err = e as Error;
+    }
+    expect(err).toBeDefined();
+    expect(err!.message).toContain('putPage');
+    expect(err!.message).toContain("slug='suppressed-page'");
+    expect(err!.message).toContain("source_id='default'");
+    // The pre-fix crash signature must be gone.
+    expect(err!.message).not.toContain('deleted_at');
+  });
+
+  test('unsuppressed slugs still upsert normally with the trigger installed', async () => {
+    const page = await engine.putPage('normal-page', {
+      type: 'concept',
+      title: 'Normal',
+      compiled_truth: 'y',
+      timeline: '',
+    });
+    expect(page.slug).toBe('normal-page');
+    expect(page.source_id).toBe('default');
+  });
+});

test/sync.test.ts

@@ -375,6 +375,31 @@ describe('performSync dry-run never writes', () => {
     expect(messages.some(m => m.includes('git pull failed'))).toBe(false);
   });
 
+  test('first PGLite code sync imports code files without runtime failures', async () => {
+    const { performSync } = await import('../src/commands/sync.ts');
+    mkdirSync(join(repoPath, 'src'), { recursive: true });
+    writeFileSync(
+      join(repoPath, 'src/example.ts'),
+      'export function add(left: number, right: number) { return left + right; }\n',
+    );
+    execSync('git add -A && git commit -m "add code file"', { cwd: repoPath, stdio: 'pipe' });
+
+    const result = await performSync(engine, {
+      repoPath,
+      noPull: true,
+      noEmbed: true,
+      noExtract: true,
+      strategy: 'code',
+    });
+
+    expect(result.status).toBe('first_sync');
+    expect(result.added).toBe(1);
+    expect(result.failedFiles ?? 0).toBe(0);
+    const page = await engine.getPage('src-example-ts');
+    expect(page?.type).toBe('code');
+    expect(page?.frontmatter).toMatchObject({ file: 'src/example.ts', language: 'typescript' });
+  });
+
   test('incremental dry-run does NOT write to DB or advance the bookmark', async () => {
     const { performSync } = await import('../src/commands/sync.ts');
     // First do a real sync to seed the bookmark.