fix(import): normalize mixed-case slugs before chunk upsert (#430)

putPage lowercases slugs via validateSlug, but upsertChunks queried
pages by the caller's raw slug — so a mixed-case slug through
importFromContent created the page row, then failed the chunk upsert
with 'Page not found' and rolled back the whole import.

Normalize via validateSlug at importFromContent entry and inside
_upsertChunksOnce on BOTH engines (postgres + pglite parity).

Takeover of #855, rebased onto current master shapes (batchRetry
wrapper / _upsertChunksOnce, rewritten importFromContent opts block).

Co-authored-by: Kage18 <Kage18@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 per-file import/sync failures (Bug 9)
+  failedFiles?: number; // count of parse 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 import (open ledger
+  // issue #1939 adversarial finding #1: a file that failed to parse (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 import:\n` +
+        `\nSync blocked: ${fileFailCount} file(s) failed to parse:\n` +
         `${codeBreakdown}\n\n` +
-        `Fix the listed file errors and re-run, or use 'gbrain sync --skip-failed' to ` +
+        `Fix the frontmatter 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 import.`);
+      write(`Sync BLOCKED at ${result.toCommit.slice(0, 8)}: ${result.failedFiles ?? 0} file(s) failed to parse.`);
       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/import-file.ts

@@ -36,7 +36,7 @@ import {
 } from './embedding-context.ts';
 import { loadSearchModeConfig, resolveSearchMode } from './search/mode.ts';
 import { normalizeAliasList } from './search/alias-normalize.ts';
-import { isUndefinedTableError, warnOncePerProcess } from './utils.ts';
+import { isUndefinedTableError, warnOncePerProcess, validateSlug } from './utils.ts';
 import { computeCorpusGeneration } from './contextual-retrieval-service.ts';
 import { runGuardrails } from './guardrails.ts';
 
@@ -295,6 +295,12 @@ export async function importFromContent(
     remote?: boolean;
   } = {},
 ): Promise<ImportResult> {
+  // Normalize BEFORE any tx write: putPage lowercases via validateSlug but
+  // upsertChunks used to query by the caller's raw slug, so a mixed-case slug
+  // created the page row then failed the chunk upsert with "Page not found",
+  // rolling back the whole import (#430).
+  slug = validateSlug(slug);
+
   // v0.18.0+ multi-source: when caller is syncing under a non-default source,
   // every per-page tx call must carry `sourceId` so writes target the right
   // (source_id, slug) row. Pre-fix, putPage relied on the schema DEFAULT and

src/core/pglite-engine.ts

@@ -1058,16 +1058,6 @@ 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>);
   }
 
@@ -2245,6 +2235,9 @@ export class PGLiteEngine implements BrainEngine {
   }
 
   private async _upsertChunksOnce(slug: string, chunks: ChunkInput[], opts?: { sourceId?: string }): Promise<void> {
+    // Normalize the same way putPage does — pages.slug is stored lowercased,
+    // so a raw mixed-case slug here would miss the row it just wrote (#430).
+    slug = validateSlug(slug);
     const sourceId = opts?.sourceId ?? 'default';
 
     // Source-scope the page-id lookup so duplicate slugs in different sources

src/core/postgres-engine.ts

@@ -1119,16 +1119,6 @@ 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]);
   }
 
@@ -2395,6 +2385,9 @@ export class PostgresEngine implements BrainEngine {
   }
 
   private async _upsertChunksOnce(slug: string, chunks: ChunkInput[], opts?: { sourceId?: string }): Promise<void> {
+    // Normalize the same way putPage does — pages.slug is stored lowercased,
+    // so a raw mixed-case slug here would miss the row it just wrote (#430).
+    slug = validateSlug(slug);
     const sql = this.sql;
     const sourceId = opts?.sourceId ?? 'default';
 

test/pglite-engine.test.ts

@@ -6,6 +6,7 @@
 
 import { describe, test, expect, beforeAll, afterAll, beforeEach } from 'bun:test';
 import { PGLiteEngine } from '../src/core/pglite-engine.ts';
+import { importFromContent } from '../src/core/import-file.ts';
 import type { BrainEngine } from '../src/core/engine.ts';
 import type { PageInput, ChunkInput } from '../src/core/types.ts';
 
@@ -181,6 +182,24 @@ describe('PGLiteEngine: Pages', () => {
     const page = await engine.putPage('Test/UPPER', testPage);
     expect(page.slug).toBe('test/upper');
   });
+
+  test('importFromContent normalizes mixed-case slugs before all tx writes (#430)', async () => {
+    const result = await importFromContent(
+      engine,
+      'TestNamespace/Page-Name',
+      '---\ntype: note\ntitle: Mixed Case\n---\n\nbody text',
+      { noEmbed: true },
+    );
+    expect(result.status).toBe('imported');
+    expect(result.slug).toBe('testnamespace/page-name');
+
+    const page = await engine.getPage('testnamespace/page-name');
+    expect(page).not.toBeNull();
+    expect(page!.title).toBe('Mixed Case');
+
+    const chunks = await engine.getChunks('testnamespace/page-name');
+    expect(chunks.length).toBeGreaterThan(0);
+  });
 });
 
 // ─────────────────────────────────────────────────────────────────
@@ -364,6 +383,17 @@ describe('PGLiteEngine: Chunks', () => {
     expect(chunks[1].chunk_text).toBe('Chunk one');
   });
 
+  test('upsertChunks normalizes mixed-case slugs like putPage (#430)', async () => {
+    await engine.putPage('Test/ChunkCase', testPage);
+    await engine.upsertChunks('Test/ChunkCase', [
+      { chunk_index: 0, chunk_text: 'Mixed-case chunk', chunk_source: 'compiled_truth' },
+    ]);
+
+    const chunks = await engine.getChunks('test/chunkcase');
+    expect(chunks.length).toBe(1);
+    expect(chunks[0].chunk_text).toBe('Mixed-case chunk');
+  });
+
   test('upsertChunks removes orphan chunks', async () => {
     await engine.putPage('test/orphan', testPage);
     await engine.upsertChunks('test/orphan', [

test/putpage-returning-guard.test.ts

@@ -1,74 +0,0 @@
-// #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,31 +375,6 @@ 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.