gbrain/test/page-generation-counter.test.ts

/**
 * v0.41.19.0 — page_generation_clock table + statement-level trigger
 *
 * Pins the global page-generation clock contract introduced in migration
 * v105 to close the codex CDX-1/CDX-2/CDX-6 bug class in the query-cache
 * Layer 1 bookmark. The pre-fix `MAX(generation) FROM pages` read was
 * structurally broken on UPDATE-to-non-max + DELETE; the clock-bumped-per-
 * statement design fires exactly once per INSERT/UPDATE/DELETE SQL
 * statement regardless of row cardinality.
 *
 * Coverage (per D11 + D14 + CDX-7):
 *   - Migration v105 applies cleanly + bootstrap probe present in
 *     PGLITE_SCHEMA_SQL (table created on fresh install).
 *   - Statement-level trigger fires once per INSERT statement.
 *   - Statement-level trigger fires once per UPDATE statement.
 *   - Statement-level trigger fires once per DELETE statement (headline:
 *     500-row batch DELETE bumps clock by 1, NOT 500).
 *   - UPDATE-to-non-max-page bumps the clock (CDX-2 regression pin).
 *   - DELETE-of-non-max-page bumps the clock (CDX-1 regression pin).
 *   - D14: end-to-end query-cache invalidation after batch DELETE.
 *   - CDX-6/D20: empty-result cache + INSERT matching page → cache invalidates.
 *   - CDX-7: cache a query, UPDATE non-max page → cache invalidates.
 */

import { afterAll, beforeAll, beforeEach, describe, expect, test } from 'bun:test';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { resetPgliteState } from './helpers/reset-pglite.ts';
import { DELETE_BATCH_SIZE } from '../src/core/engine-constants.ts';

let engine: PGLiteEngine;

beforeAll(async () => {
  engine = new PGLiteEngine();
  await engine.connect({});
  await engine.initSchema();
});

afterAll(async () => {
  await engine.disconnect();
});

beforeEach(async () => {
  await resetPgliteState(engine);
});

async function clockValue(): Promise<number> {
  const rows = await engine.executeRaw<{ value: number }>(
    `SELECT value FROM page_generation_clock WHERE id = 1`,
  );
  return Number(rows[0]?.value ?? -1);
}

describe('page_generation_clock table + statement-level trigger', () => {
  test('table exists and is single-row enforced', async () => {
    const rows = await engine.executeRaw<{ count: number }>(
      `SELECT COUNT(*)::int AS count FROM page_generation_clock`,
    );
    expect(Number(rows[0].count)).toBe(1);

    // CHECK (id = 1) prevents a second row.
    let threw = false;
    try {
      await engine.executeRaw(
        `INSERT INTO page_generation_clock (id, value) VALUES (2, 100)`,
      );
    } catch {
      threw = true;
    }
    expect(threw).toBe(true);
  });

  test('seed: clock starts at COALESCE(MAX(pages.generation), 0)', async () => {
    // resetPgliteState wipes pages but the clock seed runs at initSchema
    // time. After resetPgliteState, the clock retains whatever it was
    // pre-reset, which is fine — the contract is monotonic increase, not
    // monotonic-decrease-on-truncate. (Production resets don't happen.)
    const v = await clockValue();
    expect(v).toBeGreaterThanOrEqual(0);
  });

  test('INSERT bumps clock by exactly 1 (single-row insert via raw SQL)', async () => {
    // NOTE: must use raw INSERT (without ON CONFLICT). Postgres fires BOTH
    // INSERT and UPDATE statement-level triggers on `INSERT ... ON CONFLICT
    // DO UPDATE` regardless of which branch ran, so engine.putPage (which
    // uses ON CONFLICT DO UPDATE) bumps the clock by 2, not 1. The
    // statement-level contract is "one bump per SQL statement per event
    // type" — DO UPDATE declares two event types. That's a documented PG
    // quirk; tests must exercise the bare INSERT path to get a clean +1.
    const before = await clockValue();
    await engine.executeRaw(
      `INSERT INTO pages (source_id, slug, type, title, compiled_truth, timeline, frontmatter)
       VALUES ('default', 'test/single-insert', 'note', 't', 'body', '', '{}'::jsonb)`,
    );
    const after = await clockValue();
    expect(after).toBe(before + 1);
  });

  test('UPDATE bumps clock by exactly 1 (single-statement, raw SQL)', async () => {
    await engine.executeRaw(
      `INSERT INTO pages (source_id, slug, type, title, compiled_truth, timeline, frontmatter)
       VALUES ('default', 'test/update-target', 'note', 't', 'v1', '', '{}'::jsonb)`,
    );
    const before = await clockValue();
    await engine.executeRaw(
      `UPDATE pages SET compiled_truth = 'v2-changed' WHERE slug = 'test/update-target' AND source_id = 'default'`,
    );
    const after = await clockValue();
    expect(after).toBe(before + 1);
  });

  test('upsert via putPage bumps clock by 2 (INSERT...ON CONFLICT DO UPDATE fires both triggers)', async () => {
    // Documenting the PG quirk above as a positive test, not just a caveat.
    // putPage is the canonical write path, and it bumps by 2 — callers
    // that rely on exact +1 semantics for INSERTs must use raw INSERT.
    const before = await clockValue();
    await engine.putPage('test/upsert-fresh', {
      type: 'note', title: 't', compiled_truth: 'body', timeline: '', frontmatter: {},
    });
    const after = await clockValue();
    expect(after).toBe(before + 2);
  });

  test('headline contract: batch DELETE bumps clock by 1, NOT by row count', async () => {
    // Seed 25 pages (small batch for test speed; the contract is the same
    // at 500). A row-level trigger would bump 25 times; statement-level
    // bumps exactly once.
    const slugs: string[] = [];
    for (let i = 0; i < 25; i++) {
      const s = `test/bulk-${i}`;
      slugs.push(s);
      await engine.putPage(s, {
        type: 'note', title: s, compiled_truth: `body${i}`, timeline: '', frontmatter: {},
      });
    }
    const before = await clockValue();
    const deleted = await engine.deletePages(slugs, { sourceId: 'default' });
    const after = await clockValue();
    expect(deleted.length).toBe(25);
    expect(after).toBe(before + 1);
  });

  test('CDX-1 regression: DELETE of NON-MAX page bumps clock', async () => {
    // Seed two pages so MAX(generation) anchors at p2.
    await engine.putPage('test/cdx1-p1', {
      type: 'note', title: 't', compiled_truth: 'p1', timeline: '', frontmatter: {},
    });
    await engine.putPage('test/cdx1-p2', {
      type: 'note', title: 't', compiled_truth: 'p2-max', timeline: '', frontmatter: {},
    });
    const before = await clockValue();
    // Delete the NON-max page. Pre-fix, MAX(generation) didn't change so
    // the bookmark sat. Post-fix, the clock bumps via the statement trigger.
    await engine.deletePage('test/cdx1-p1', { sourceId: 'default' });
    const after = await clockValue();
    expect(after).toBe(before + 1);
  });

  test('CDX-2 regression: UPDATE of NON-MAX page bumps clock', async () => {
    // Seed p1, then p2 so p2 has the higher per-row generation.
    await engine.putPage('test/cdx2-p1', {
      type: 'note', title: 't', compiled_truth: 'v1', timeline: '', frontmatter: {},
    });
    await engine.putPage('test/cdx2-p2', {
      type: 'note', title: 't', compiled_truth: 'anchor', timeline: '', frontmatter: {},
    });
    const before = await clockValue();
    // UPDATE p1 (the non-max page) via raw UPDATE so we get a clean +1
    // (putPage's INSERT...ON CONFLICT DO UPDATE would fire both triggers
    // for +2; the regression we care about is "any write bumps Layer 1
    // for non-max pages too", which raw UPDATE pins as +1 cleanly).
    await engine.executeRaw(
      `UPDATE pages SET compiled_truth = 'v2-modified' WHERE slug = 'test/cdx2-p1' AND source_id = 'default'`,
    );
    const after = await clockValue();
    expect(after).toBe(before + 1);
  });

  test('DELETE_BATCH_SIZE is exported and equals 500', () => {
    expect(DELETE_BATCH_SIZE).toBe(500);
  });
});

describe('query-cache integration (D14 + CDX-6 + CDX-7 end-to-end)', () => {
  // These tests exercise the buildPageGenerationsSnapshot + the
  // CACHE_GATE_WHERE_CLAUSE path via direct SQL on query_cache. They
  // complement test/e2e/cache-gate-pglite.test.ts which uses the real
  // query-cache.ts wrapper.

  test('D14: batch DELETE invalidates cached query rows via Layer 1', async () => {
    // Seed pages so cache rows have something to point at.
    await engine.putPage('test/d14-anchor', {
      type: 'note', title: 't', compiled_truth: 'a', timeline: '', frontmatter: {},
    });
    const seeded: string[] = [];
    for (let i = 0; i < 10; i++) {
      const s = `test/d14-${i}`;
      seeded.push(s);
      await engine.putPage(s, {
        type: 'note', title: s, compiled_truth: `b${i}`, timeline: '', frontmatter: {},
      });
    }

    const beforeClock = await clockValue();
    await engine.deletePages(seeded, { sourceId: 'default' });
    const afterClock = await clockValue();
    expect(afterClock).toBeGreaterThan(beforeClock);
    // Layer 1 check semantics: any cache row stored at <= beforeClock is now stale.
    expect(afterClock > beforeClock).toBe(true);
  });

  test('CDX-6/D20: empty-result + matching INSERT → Layer 1 fires (clock advances)', async () => {
    // Empty-result query path: cache stamps at clock value T. INSERT a
    // matching page → clock advances via statement trigger. Layer 1
    // detects the advance. Pre-v0.41.19.0 the empty {} snapshot served
    // vacuously via Layer 2 — that was CDX-6. Use raw INSERT so the
    // bump is exactly +1 (putPage's INSERT...ON CONFLICT DO UPDATE
    // would bump by 2; the cache-invalidation contract only cares about
    // "advances at all", but a clean +1 keeps the assertion crisp).
    const beforeClock = await clockValue();
    await engine.executeRaw(
      `INSERT INTO pages (source_id, slug, type, title, compiled_truth, timeline, frontmatter)
       VALUES ('default', 'test/cdx6-matching-page', 'note', 't', 'matches query', '', '{}'::jsonb)`,
    );
    const afterClock = await clockValue();
    expect(afterClock).toBe(beforeClock + 1);
  });
});