Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Wipe per-test data on a connected PGLite engine without dropping the schema.
* Used by tests that share one engine across the file (beforeAll) and need a
* clean slate per test (beforeEach).
*
* Why this exists: PGLite WASM cold-start + initSchema() is ~20s on CI runners.
* Spinning up a fresh engine per test (the prior beforeEach pattern) multiplies
* that across every test in every file. Sharing one engine and wiping data
* is two orders of magnitude faster.
*
* Canonical block (copy verbatim into PGLite-using test files; enforced by
* scripts/check-test-isolation.sh rules R3 + R4):
*
* import { PGLiteEngine } from '../src/core/pglite-engine.ts';
* import { resetPgliteState } from './helpers/reset-pglite.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);
* });
*
* Why this exact shape:
* - `beforeAll` creates one engine per file (~20s schema init paid once).
* - `beforeEach` resets user data without re-creating the engine.
* - `afterAll(disconnect)` is REQUIRED. The v0.26.4 parallel runner loads
* multiple test files into one bun process per shard; without disconnect,
* engines leak across file boundaries within a shard process.
*
* Implementation:
* 1. Empty every public table, including `sources` (so tests
* that register their own sources don't leak rows into the next test).
* 2. Re-seed the default source row that pages.source_id's DEFAULT FKs
* against. Without this, the next page insert would fail FK validation.
* 3. Preserve `schema_version` — it carries the migration ledger that
* initSchema() populates; wiping it would make migration helpers think
* the brain is on v0.
*
* Cleanup bypasses row triggers, like TRUNCATE, and resets owned sequences.
* DELETE avoids recreating every empty table/index's storage on each test.
* Schemas with truncate/replica triggers or rules, inheritance, or external foreign
* keys retain TRUNCATE CASCADE semantics. Cleanup is one atomic statement;
* normal trigger behavior is restored before re-seeding or running tests.
* Aggregate table/index/TOAST storage over 8 MiB also uses TRUNCATE so deleted
* rows cannot accumulate unbounded storage across repeated fixture resets.
* Identifiers are quoted defensively against pathological table names.
*/
import type { PGLiteEngine } from '../../src/core/pglite-engine.ts';
import { disposePersistenceConsumer } from '../../src/core/persistence/service.ts';
// v0.41.21.0: `page_generation_clock` is single-row infrastructure (like
// schema_version) and must survive resetPgliteState. The row is seeded at
// initSchema time by PGLITE_SCHEMA_SQL; TRUNCATEing the table breaks
// page_generation_counter.test.ts AND any test that reads the clock value
// after a reset. Production never truncates the clock table.
const PRESERVE_TABLES = new Set(['schema_version', 'page_generation_clock', 'persistence_brain']);
// Conditions (over plpgsql variables `tables regclass[]` and `storage_bytes`)
// under which a replica-role DELETE of `tables` would not match TRUNCATE:
// TRUNCATE or always/replica triggers, always/replica rules, inheritance,
// no superuser to set session_replication_role, or enough storage that dead
// rows should be reclaimed by TRUNCATE instead.
const DELETE_DIVERGES_FROM_TRUNCATE = `storage_bytes > 8 * 1024 * 1024 OR EXISTS (
SELECT 1 FROM pg_trigger WHERE tgrelid = ANY(tables)
AND ((tgtype::int & 32) <> 0 OR tgenabled IN ('A', 'R'))
) OR EXISTS (
SELECT 1 FROM pg_rewrite WHERE ev_class = ANY(tables) AND ev_enabled IN ('A', 'R')
) OR EXISTS (
SELECT 1 FROM pg_inherits WHERE inhrelid = ANY(tables) OR inhparent = ANY(tables)
) OR NOT EXISTS (
SELECT 1 FROM pg_roles WHERE rolname = current_user AND rolsuper
)`;
export async function resetPgliteState(engine: PGLiteEngine): Promise<void> {
await disposePersistenceConsumer(engine);
await engine.executeRaw(`DO $reset$
DECLARE
tables regclass[];
targets text;
storage_bytes bigint;
target regclass;
sequence record;
original_role text := current_setting('session_replication_role');
BEGIN
SELECT array_agg(c.oid::regclass), string_agg(format('%I.%I', n.nspname, c.relname), ', '),
sum(pg_total_relation_size(c.oid))
INTO tables, targets, storage_bytes
FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
WHERE n.nspname = 'public' AND c.relkind IN ('r', 'p')
AND c.relname NOT IN (${[...PRESERVE_TABLES].map(t => `'${t}'`).join(', ')});
IF targets IS NULL THEN RETURN; END IF;
IF ${DELETE_DIVERGES_FROM_TRUNCATE} OR EXISTS (
SELECT 1 FROM pg_constraint WHERE contype = 'f'
AND confrelid = ANY(tables) AND NOT conrelid = ANY(tables)
) OR EXISTS (
SELECT 1 FROM pg_event_trigger WHERE evtenabled <> 'D'
) THEN
EXECUTE 'TRUNCATE ' || targets || ' RESTART IDENTITY CASCADE';
ELSE
PERFORM set_config('session_replication_role', 'replica', true);
FOREACH target IN ARRAY tables LOOP
EXECUTE format('DELETE FROM %s', target);
END LOOP;
FOR sequence IN
SELECT n.nspname, c.relname FROM pg_class c
JOIN pg_namespace n ON n.oid = c.relnamespace
JOIN pg_depend d ON d.objid = c.oid
WHERE c.relkind = 'S' AND d.refobjid = ANY(tables)
AND d.classid = 'pg_class'::regclass AND d.refclassid = 'pg_class'::regclass
AND d.deptype IN ('a', 'i')
LOOP
EXECUTE format('ALTER SEQUENCE %I.%I RESTART', sequence.nspname, sequence.relname);
END LOOP;
PERFORM set_config('session_replication_role', original_role, true);
END IF;
UPDATE persistence_brain SET brain_id = gen_random_uuid(), enabled = false, activated_at = NULL WHERE singleton = 1;
INSERT INTO sources (id, name, config)
VALUES ('default', 'default', '{"federated": true}'::jsonb)
ON CONFLICT (id) DO NOTHING;
END $reset$`);
}
/** Structural engine slice so the narrow reset works on either engine. */
export interface NarrowResetEngine {
executeRaw(sql: string): Promise<unknown>;
}
const TABLE_NAME_RE = /^[a-z_][a-z0-9_]*$/;
/**
* Truncate ONLY the named tables (one TRUNCATE ... RESTART IDENTITY CASCADE
* statement) — for hot loops where the full-catalog reset is overkill.
*
* The table list is EXPLICIT and REQUIRED — there is deliberately no default.
* A default silently under-truncates the moment a migration adds a table the
* test writes to; writer.test.ts's 7-table set (pages, links, content_chunks,
* timeline_entries, tags, raw_data, page_versions) is a reference example,
* not a default.
*
* Constraints:
* - Every name must match /^[a-z_][a-z0-9_]*$/ (throws otherwise — names
* reach the SQL text; validated names are additionally identifier-quoted).
* - Refuses PRESERVE_TABLES (schema_version, page_generation_clock): the
* narrow variant preserves everything resetPgliteState preserves.
* - CASCADE follows FKs — truncating `sources` also empties pages etc.
* - Re-seeds the default source row ONLY when 'sources' is in the list
* (mirrors resetPgliteState).
*/
export async function resetPgliteStateNarrow(
engine: NarrowResetEngine,
tables: string[],
): Promise<void> {
if (tables.length === 0) {
throw new Error(
'resetPgliteStateNarrow: table list is required and must be non-empty (no default; see doc comment)',
);
}
for (const t of tables) {
if (!TABLE_NAME_RE.test(t)) {
throw new Error(
`resetPgliteStateNarrow: invalid table name ${JSON.stringify(t)} (must match ${TABLE_NAME_RE})`,
);
}
if (PRESERVE_TABLES.has(t)) {
throw new Error(
`resetPgliteStateNarrow: refusing to truncate preserved infrastructure table "${t}"`,
);
}
}
const quoted = tables.map(t => `"${t}"`).join(', ');
await engine.executeRaw(`TRUNCATE ${quoted} RESTART IDENTITY CASCADE`);
if (tables.includes('sources')) {
await engine.executeRaw(
`INSERT INTO sources (id, name, config)
VALUES ('default', 'default', '{"federated": true}'::jsonb)
ON CONFLICT (id) DO NOTHING`,
);
}
}
/**
* Same end state as `TRUNCATE <tables> CASCADE` (sequences continue): empties
* the named tables and every table that references them, transitively, by
* foreign key. Works on either engine.
*
* On Postgres, TRUNCATE gives every table and index in that closure new
* storage files, even when all of them are already empty. `pages` alone
* reaches 23 tables and over 100 indexes, so one call costs ~0.8 s on a
* container; a per-test reset built on it dominated embedding-recovery-parity's
* wall clock. There this deletes the closure's rows under replica role instead
* (~4 ms), and keeps TRUNCATE whenever DELETE could behave differently
* (DELETE_DIVERGES_FROM_TRUNCATE).
*
* Without an autovacuum launcher (PGLite) TRUNCATE is kept: nothing reclaims
* the deleted rows, and the stale page counts misled the planner enough to
* slow two later embedding-recovery tests from ~2 s to ~11 s, while TRUNCATE
* there is an in-memory operation. No ALTER SEQUENCE is issued, so event
* triggers see nothing on either path.
*/
export async function truncateCascade(engine: NarrowResetEngine, tables: string[]): Promise<void> {
if (tables.length === 0) throw new Error('truncateCascade: table list must be non-empty');
for (const t of tables) {
if (!TABLE_NAME_RE.test(t)) {
throw new Error(`truncateCascade: invalid table name ${JSON.stringify(t)} (must match ${TABLE_NAME_RE})`);
}
}
const quoted = tables.map(t => `"${t}"`).join(', ');
await engine.executeRaw(`DO $truncate$
DECLARE
tables regclass[];
storage_bytes bigint;
target regclass;
original_role text := current_setting('session_replication_role');
BEGIN
WITH RECURSIVE closure(oid) AS (
SELECT unnest(ARRAY[${tables.map(t => `'"${t}"'`).join(', ')}]::regclass[])::oid
UNION
SELECT c.conrelid FROM pg_constraint c JOIN closure ON c.confrelid = closure.oid WHERE c.contype = 'f'
)
SELECT array_agg(oid::regclass), sum(pg_total_relation_size(oid)) INTO tables, storage_bytes FROM closure;
IF ${DELETE_DIVERGES_FROM_TRUNCATE} OR NOT EXISTS (
SELECT 1 FROM pg_stat_activity WHERE backend_type = 'autovacuum launcher'
) THEN
EXECUTE 'TRUNCATE ${quoted} CASCADE';
ELSE
PERFORM set_config('session_replication_role', 'replica', true);
FOREACH target IN ARRAY tables LOOP
EXECUTE format('DELETE FROM %s', target);
END LOOP;
PERFORM set_config('session_replication_role', original_role, true);
END IF;
END $truncate$`);
}