Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
7.0 KB
Raw Blame
/**
 * Refactor wave 1, W0 / EO9 (T-G5): pin PostgresEngine's checkoutGauge
 * (issue #6 pool diagnostics) on master. The W1 engine-sql adapter must bypass
 * the gauge exactly like today's tagged-template calls do, and keep the
 * raw / direct / reserved / tx labels where master counts them.
 *
 * Two goldens in `test/fixtures/goldens/postgres-engine-gauge.json`:
 *   - `sequence`: `getPoolDiagnostics()` after each step of a fixed op
 *     sequence on a fake connection (queries held in flight, then released,
 *     then a rejected query), covering every lane: raw, direct, tx (incl. a
 *     nested savepoint that must not double count), reserved, and tagged
 *     domain calls that must not count at all;
 *   - `acquiresByCase`: per EO8 SQL-text case (12 W1 domains), how many times
 *     each gauge kind was acquired, plus the invariant that every acquire was
 *     released when the method settled (a read transaction's tx count when
 *     its COMMIT, which the method does not wait for, settles: GBRA-156).
 */

import { describe, expect, test } from 'bun:test';
import { CheckoutGauge, type GaugeKind } from '../src/core/pool-gauge.ts';
import { PostgresEngine } from '../src/core/postgres-engine.ts';
import { defineNormalizer, expectGolden, expectNormalizerStable } from './helpers/golden.ts';
import { makeFakeSql, type RecordedStatement } from './helpers/fake-postgres-sql.ts';
import { SQL_CASES, makeEngineWithFake, withPinnedSqlEnvironment } from './helpers/postgres-engine-sql-cases.ts';

class RecordingGauge extends CheckoutGauge {
  acquired: Record<string, number> = {};
  override acquire(kind: GaugeKind): void {
    this.acquired[kind] = (this.acquired[kind] ?? 0) + 1;
    super.acquire(kind);
  }
}

async function settle(until: () => boolean): Promise<void> {
  for (let i = 0; i < 200 && !until(); i++) await new Promise((r) => setTimeout(r, 0));
  if (!until()) throw new Error('gauge sequence: held statement never reached the fake');
}

async function captureSequence(): Promise<Array<{ step: string; diagnostics: unknown }>> {
  const holds = new Map<string, (rows: unknown[] | Error) => void>();
  const fake = makeFakeSql((stmt: RecordedStatement) => {
    const name = /\/\*hold:([\w-]+)\*\//.exec(stmt.text)?.[1]
      ?? (stmt.text.includes('COUNT(DISTINCT l.from_page_id)') ? 'enrichment' : undefined)
      ?? (stmt.text.includes('SELECT DISTINCT tag FROM tags') ? 'domain-tagged' : undefined);
    if (!name) return undefined;
    return new Promise((resolve) => holds.set(name, resolve as (rows: unknown[] | Error) => void));
  }, { poolMax: 10 });
  const engine = new PostgresEngine() as any;
  engine._sql = fake.sql;
  engine._connectionStyle = 'instance';
  const held = (name: string) => () => holds.has(name);
  const release = (name: string, value: unknown[] | Error = []) => { holds.get(name)!(value); holds.delete(name); };
  const steps: Array<{ step: string; diagnostics: unknown }> = [];
  const snap = (step: string) => steps.push({ step, diagnostics: engine.getPoolDiagnostics() });

  snap('idle');
  const raw = engine.executeRaw('SELECT /*hold:raw*/ 1');
  await settle(held('raw')); snap('executeRaw in flight');
  const direct = engine.executeRawDirect('SELECT /*hold:direct*/ 1');
  await settle(held('direct')); snap('+ executeRawDirect in flight');
  const tx = engine.transaction(async (t: any) => {
    await t.executeRaw('SELECT /*hold:tx-raw*/ 1');
    await t.transaction(async (inner: any) => inner.executeRaw('SELECT /*hold:savepoint-raw*/ 1'));
  });
  await settle(held('tx-raw')); snap('+ transaction body executeRaw in flight');
  release('tx-raw');
  await settle(held('savepoint-raw')); snap('+ nested savepoint executeRaw in flight (tx counted once)');
  const reserved = engine.withReservedConnection(async (conn: any) => conn.executeRaw('SELECT /*hold:reserved*/ 1'));
  await settle(held('reserved')); snap('+ withReservedConnection in flight');
  const tagged = engine.sql`SELECT /*hold:tagged*/ 1`;
  const taggedDone = tagged.then(() => undefined);
  await settle(held('tagged')); snap('+ tagged-template query in flight (not tracked)');
  const domainTagged = engine.getTags('people/alice-example');
  await settle(held('domain-tagged')); snap('+ getTags in flight (tagged domain SQL, not tracked)');
  const enrichment = engine.getBacklinkCounts([1, 2]);
  await settle(held('enrichment')); snap('+ getBacklinkCounts in flight (executeRaw-backed, counted raw)');
  release('enrichment'); await enrichment; snap('getBacklinkCounts released');
  release('domain-tagged'); await domainTagged; snap('getTags released');

  release('raw'); await raw; snap('raw released');
  release('direct'); await direct; snap('direct released');
  release('savepoint-raw'); await tx; snap('transaction committed');
  release('reserved'); await reserved; snap('reserved released');
  release('tagged'); await taggedDone; snap('tagged released');
  const rejected = engine.executeRaw('SELECT /*hold:rejected*/ 1');
  await settle(held('rejected')); snap('executeRaw in flight before rejection');
  release('rejected', new Error('query was cancelled'));
  await expect(rejected).rejects.toThrow('query was cancelled');
  snap('after rejected executeRaw (released)');
  return steps;
}

async function captureAcquiresByCase(): Promise<Record<string, Record<string, number>>> {
  return withPinnedSqlEnvironment(undefined, async () => {
    const out: Record<string, Record<string, number>> = {};
    for (const c of SQL_CASES) {
      const { engine } = makeEngineWithFake(c.rows);
      const gauge = new RecordingGauge();
      engine.checkoutGauge = gauge;
      await c.run(engine);
      // GBRA-156: a top-level read transaction returns before its COMMIT; its tx count is released when COMMIT settles.
      await new Promise((r) => setTimeout(r, 0));
      const leaked = Object.entries(gauge.snapshot()).filter(([, n]) => n !== 0);
      if (leaked.length) throw new Error(`${c.method}#${c.variant} leaked gauge counts: ${JSON.stringify(leaked)}`);
      out[`${c.method}#${c.variant}`] = gauge.acquired;
    }
    return out;
  });
}

/** No volatile content: counts and fixed step labels only. */
const SEQUENCE_NORMALIZER = defineNormalizer<Array<{ step: string; diagnostics: unknown }>>('gauge-sequence-v1', (steps) => steps);
const ACQUIRES_NORMALIZER = defineNormalizer<Record<string, Record<string, number>>>('gauge-acquires-by-case-v1', (m) => m);

describe('EO9 checkoutGauge golden (fake connection)', () => {
  test('gauge snapshot after each step of the fixed op sequence matches master', async () => {
    const steps = await expectNormalizerStable(captureSequence, SEQUENCE_NORMALIZER);
    expect((steps.at(-1)!.diagnostics as { tracked: unknown }).tracked).toEqual({ raw: 0, direct: 0, reserved: 0, tx: 0 });
    expectGolden('postgres-engine-gauge/sequence', steps, SEQUENCE_NORMALIZER);
  });

  test('per-method gauge acquires for the W1 domain cases match master, and every acquire is released', async () => {
    const acquires = await expectNormalizerStable(captureAcquiresByCase, ACQUIRES_NORMALIZER);
    expectGolden('postgres-engine-gauge/acquires-by-case', acquires, ACQUIRES_NORMALIZER);
  });
});