@effectstream/db 0.100.20 → 0.100.22

package/migrations/system-up-v-0.0.0.sql

@@ -1,7 +1,5 @@
 CREATE SCHEMA IF NOT EXISTS effectstream;
 
-CREATE EXTENSION IF NOT EXISTS pg_ivm;
-
 CREATE TABLE effectstream.effectstream_expected_version (
   app_version_major INTEGER NOT NULL,
   app_version_minor INTEGER NOT NULL,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effectstream/db",
-  "version": "0.100.20",
+  "version": "0.100.22",
   "license": "MIT",
   "homepage": "https://effectstream.github.io/docs/",
   "repository": {
@@ -21,15 +21,15 @@
     "./version": "./migrations/system-version.ts"
   },
   "dependencies": {
-    "@effectstream/coroutine": "0.100.20",
-    "@effectstream/log": "0.100.20",
-    "@effectstream/runtime": "0.100.20",
-    "@effectstream/sync": "0.100.20",
-    "@effectstream/utils": "0.100.20",
+    "@effectstream/coroutine": "0.100.22",
+    "@effectstream/log": "0.100.22",
+    "@effectstream/runtime": "0.100.22",
+    "@effectstream/sync": "0.100.22",
+    "@effectstream/utils": "0.100.22",
     "@electric-sql/pglite": "^0.3.14",
     "@pgtyped/runtime": "2.4.2",
     "@pgtyped/parser": "2.4.2",
-    "pg": "8.17.2",
+    "pg": "8.21.0",
     "pg-tx": "^1.0.1",
     "effection": "^3.5.0",
     "pg-gateway": "^0.3.0-beta.4"

package/scripts/start-pglite.ts

@@ -31,10 +31,6 @@ export async function startPglite(port = 5432): Promise<PgliteHandle> {
     },
   );
 
-  // Serialize every client's execProtocolRaw through one promise chain
-  // PGlite allows only one in-flight query, and per-process db_mutex can't coordinate across separate TCP clients.
-  let queue: Promise<unknown> = Promise.resolve();
-
   // TODO: consider switching to pglite-socket once it works
   //       https://discord.com/channels/933657521581858818/1371976702674075780/1371992712076595250
   const server = net.createServer(async (socket) => {
@@ -58,11 +54,8 @@ export async function startPglite(port = 5432): Promise<PgliteHandle> {
           return;
         }
 
-        // Forward raw message to PGlite and send response to client, serialized
-        // through the queue so the single WASM backend handles one at a time.
-        const run = queue.then(() => db.execProtocolRaw(data));
-        queue = run.catch(() => {}); // keep the chain alive even if a query errors
-        return await run;
+        // Forward raw message to PGlite and send response to client
+        return await db.execProtocolRaw(data);
       },
     });
   });

package/src/MaterializedViewStrategy.ts

@@ -0,0 +1,50 @@
+/**
+ * Strategy for publishing the read-side relation that primitives query
+ * (e.g. `primitives.erc20_balances_view_<name>`).
+ *
+ * The intermediate table and the maintenance trigger are identical in both
+ * modes — only how the view itself is created differs. The query API
+ * (`SELECT * FROM primitives.<viewName>`) is unchanged across strategies.
+ */
+export interface MaterializedViewStrategy {
+  /**
+   * Stable identifier used to namespace migration rows per strategy.
+   * Empty string for the legacy pg_ivm strategy, so its migration rows keep
+   * the same names that existing deployments already have in their
+   * `effectstream_migration_history`. Only the new fallback strategy uses a
+   * suffixed name. This avoids re-applying dynamic-table DDL (which would
+   * fail on already-existing triggers/IMMVs) when an existing app upgrades.
+   */
+  readonly migrationSuffix: "" | "-view";
+  /** Emit DDL that publishes `viewName` as a queryable relation backed by `selectSql`. */
+  createView(viewName: string, selectSql: string): string;
+}
+
+/**
+ * Uses the `pg_ivm` extension to create an incrementally maintained
+ * materialized view. Requires the extension to be installed in the database.
+ *
+ * Migration rows for this strategy use the historical unsuffixed name
+ * (`dynamic-tables-<type>-<name>`) so deployments that were already running
+ * the engine before the strategy pattern existed keep matching their
+ * previously-applied rows on upgrade — no re-application, no DDL conflicts.
+ */
+export const pgIvmStrategy: MaterializedViewStrategy = {
+  migrationSuffix: "",
+  createView: (viewName, selectSql) =>
+    `SELECT pgivm.create_immv('${viewName}', $IVM$${selectSql}$IVM$);`,
+};
+
+/**
+ * Fallback: a plain SQL view computed on read. The intermediate table is
+ * still trigger-maintained, so the only extra cost is re-applying the
+ * (typically cheap) WHERE filter at query time.
+ *
+ * Migration rows use a `-view` suffix to keep this strategy's history
+ * distinct from the pg_ivm strategy's.
+ */
+export const plainViewStrategy: MaterializedViewStrategy = {
+  migrationSuffix: "-view",
+  createView: (viewName, selectSql) =>
+    `CREATE OR REPLACE VIEW ${viewName} AS ${selectSql};`,
+};

package/src/capabilities.ts

@@ -0,0 +1,118 @@
+import type { PoolClient } from "pg";
+import { ENV } from "@effectstream/utils/node-env";
+import { ComponentNames, log, SeverityNumber } from "@effectstream/log";
+import {
+  type MaterializedViewStrategy,
+  pgIvmStrategy,
+  plainViewStrategy,
+} from "./MaterializedViewStrategy.ts";
+
+/**
+ * Optional database features the engine probes for at startup.
+ *
+ * - `pgIvm`: the `pg_ivm` extension that provides incrementally maintained
+ *   materialized views. When unavailable, the engine can fall back to plain
+ *   SQL views over the same trigger-maintained intermediate tables — but
+ *   only if the operator has explicitly opted in via `ENV.ALLOW_NO_PG_IVM`.
+ */
+export interface DatabaseCapabilities {
+  pgIvm: boolean;
+}
+
+/**
+ * Probes the connected database for optional features. Pure detection —
+ * no policy decision is made here; the caller (typically via
+ * {@link selectViewStrategy}) decides whether the resulting capability set
+ * is acceptable.
+ *
+ * - Best-effort `CREATE EXTENSION IF NOT EXISTS pg_ivm` (no-op if already
+ *   installed, soft-fail if the binary is missing on the server).
+ * - Then queries `pg_extension` to confirm the real state.
+ */
+export async function detectCapabilities(
+  client: Pick<PoolClient, "query">,
+): Promise<DatabaseCapabilities> {
+  try {
+    await client.query("CREATE EXTENSION IF NOT EXISTS pg_ivm");
+  } catch {
+    // Extension binary not installed on this server — fall through and let
+    // the pg_extension lookup confirm the absence.
+  }
+
+  const { rows } = await client.query<{ exists: boolean }>(
+    `SELECT EXISTS (SELECT 1 FROM pg_extension WHERE extname = 'pg_ivm') AS exists`,
+  );
+  return { pgIvm: rows[0]?.exists === true };
+}
+
+/**
+ * Decide which materialized-view strategy to use based on detected
+ * capabilities and operator policy.
+ *
+ * Behavior matrix:
+ *
+ * | pg_ivm available | ALLOW_NO_PG_IVM | Result                                   |
+ * | :--------------- | :-------------- | :--------------------------------------- |
+ * | yes              | any             | pgIvmStrategy (production path)          |
+ * | no               | false / unset   | **throws** — startup aborts loudly       |
+ * | no               | true            | plainViewStrategy + prominent startup WARN |
+ *
+ * The throw is intentional: silently degrading to a slower read path in
+ * production is much worse than failing early with a clear remediation
+ * message. Operators who genuinely need the dev/test fallback must opt in.
+ */
+export function selectViewStrategy(
+  capabilities: DatabaseCapabilities,
+): MaterializedViewStrategy {
+  if (capabilities.pgIvm) return pgIvmStrategy;
+
+  if (!ENV.ALLOW_NO_PG_IVM) {
+    throw new Error(formatMissingPgIvmError());
+  }
+
+  log.local(
+    ComponentNames.EFFECTSTREAM_RUNTIME,
+    "pg_ivm-fallback",
+    SeverityNumber.WARN,
+    (l) =>
+      l(
+        [
+          "─────────────────────────────────────────────────────────────",
+          "  effectstream: running WITHOUT pg_ivm (fallback mode)",
+          "  ALLOW_NO_PG_IVM=true is set; using plain SQL views over the",
+          "  trigger-maintained intermediate tables.",
+          "",
+          "  This path is intended for dev/test and low-volume apps only.",
+          "  Read-path performance degrades sharply on long-lived contracts",
+          "  with high address cardinality (intermediate tables grow",
+          "  monotonically; the plain view does a seq scan + filter per",
+          "  read). DO NOT run production on this configuration.",
+          "─────────────────────────────────────────────────────────────",
+        ].join("\n"),
+      ),
+  );
+  return plainViewStrategy;
+}
+
+function formatMissingPgIvmError(): string {
+  return [
+    "",
+    "Effectstream startup aborted: the `pg_ivm` PostgreSQL extension is not",
+    "available on this database.",
+    "",
+    "The engine uses `pg_ivm` for incrementally maintained materialized views,",
+    "which give compact, fast reads on long-lived contracts. Without it the",
+    "engine can fall back to plain SQL views over the trigger-maintained",
+    "intermediate tables — but that path degrades sharply on high-cardinality",
+    "data and is only suitable for dev/test and low-volume apps.",
+    "",
+    "To proceed:",
+    "  • Install pg_ivm in your PostgreSQL instance:",
+    "      https://github.com/sraoss/pg_ivm",
+    "  • OR explicitly accept the dev-mode fallback by setting:",
+    "      ALLOW_NO_PG_IVM=true",
+    "    (NOT recommended for production — see the database docs for the",
+    "     performance ceiling.)",
+    "",
+  ].join("\n");
+}

package/src/dynamic-tables.ts

@@ -6,26 +6,42 @@ import type { PoolClient } from "pg";
 import type { VersionInfo } from "../migrations/system-version.ts";
 import { applyMigrations } from "../scripts/apply-migrations.ts";
 import { findMigrationByName } from "./sql/system.queries.ts";
+import {
+  type MaterializedViewStrategy,
+  plainViewStrategy,
+} from "./MaterializedViewStrategy.ts";
 
 /**
  * Creates dynamic tables for the given sync protocols.
- * This is used to create the IVMs for the given sync protocols.
+ * This is used to create the read-side relations (incrementally maintained
+ * via pg_ivm when available, otherwise plain SQL views) for each primitive's
+ * intermediate state.
  *
  * For example for ERC20 it creates a table that holds the balance for each address.
  * For ERC721 it creates a table that holds the token id for each address.
  *
  * @param dbConn - The database connection.
  * @param syncProtocols - The sync protocols.
+ * @param strategy - How to publish the read-side view. Defaults to the plain
+ *   view fallback so callers that haven't probed capabilities yet stay safe
+ *   on managed Postgres without pg_ivm. The runtime detects the extension
+ *   and passes `pgIvmStrategy` explicitly when available.
  */
 export function* createDynamicTables(
   versionInfo: VersionInfo,
   lastBlockHeight: number,
   dbConn: PoolClient,
   syncProtocols: any[], // AllSyncProtocols[],
+  strategy: MaterializedViewStrategy = plainViewStrategy,
 ) {
   for (const syncProtocol of syncProtocols) {
     for (const primitive of syncProtocol.config.primitives) {
-      yield* createDynamicTableForPrimitive(primitive, lastBlockHeight, dbConn);
+      yield* createDynamicTableForPrimitive(
+        primitive,
+        lastBlockHeight,
+        dbConn,
+        strategy,
+      );
     }
   }
 }
@@ -39,6 +55,7 @@ function* createDynamicTableForPrimitive(
   },
   lastBlockHeight: number,
   dbConn: PoolClient,
+  strategy: MaterializedViewStrategy,
 ) {
   const type = p.primitive.type;
   const name = p.primitive.name;
@@ -54,10 +71,15 @@ function* createDynamicTableForPrimitive(
 
   // This primitive does not have dynamic tables.
   if (!sqlFunction) return;
-  const code = sqlFunction(name);
+  const code = sqlFunction(name, strategy);
   if (!code) return;
 
-  const migrationName = `dynamic-tables-${type}-${name}`;
+  // pgIvmStrategy uses the legacy unsuffixed name so existing deployments
+  // upgrading from a pre-strategy build keep matching their previously-
+  // applied migration rows. plainViewStrategy uses a `-view` suffix to keep
+  // its history distinct, so a deployment that later gains or loses pg_ivm
+  // re-applies the correct view-creation DDL.
+  const migrationName = `dynamic-tables-${type}-${name}${strategy.migrationSuffix}`;
   const [migration] = yield* until(findMigrationByName.run({
     name: migrationName,
     isSystemMigration: true,

package/src/mod.ts

@@ -54,7 +54,6 @@ export * from "./sql/tables.queries.ts";
 
 export * from "./event-indexing.ts";
 export * from "./register-events.ts";
-export * from "./transient-pg-errors.ts";
 export * from "./pg-connection.ts";
 export * from "./scheduled-constructors.ts";
 export * from "./system.ts";
@@ -64,6 +63,13 @@ export {
   getPrimitiveIntermediatePrefix,
   getPrimitivePrefix,
 } from "./dynamic-tables.ts";
+export { detectCapabilities, selectViewStrategy } from "./capabilities.ts";
+export type { DatabaseCapabilities } from "./capabilities.ts";
+export {
+  pgIvmStrategy,
+  plainViewStrategy,
+} from "./MaterializedViewStrategy.ts";
+export type { MaterializedViewStrategy } from "./MaterializedViewStrategy.ts";
 // export { startPGlite } from "./start-pglite.ts";
 
 export { getMigrationsForBlockHeight } from "./migrations.ts";

package/src/pg-connection.ts

@@ -1,16 +1,10 @@
 import type { Client, PoolClient, PoolConfig } from "pg";
 import pg from "pg";
-import { ComponentNames, installUnhandledRejectionLogger } from "@effectstream/log";
+import { ComponentNames, log, SeverityNumber } from "@effectstream/log";
 import { type Operation, run, sleep } from "effection";
 import { ENV } from "@effectstream/utils/node-env";
-import { isTransientPgError } from "./transient-pg-errors.ts";
-import { poolErrors } from "./pool-error-tracker.ts";
-
-export { isTransientPgError } from "./transient-pg-errors.ts";
-export { poolErrors, PoolErrorTracker } from "./pool-error-tracker.ts";
 
 let readonlyDBConn: pg.Pool | null;
-let unhandledRejectionLoggerInstalled = false;
 
 // PGLite does not support multiple connections, so we need to use a mutex to ensure that only one query is executed at a time.
 // * For transactions use yield* acquireDBMutex(); ...Your Operations... releaseDBMutex();
@@ -144,8 +138,6 @@ export async function runPreparedQuery<T>(
     });
     result = await Promise.race([p, timeout]);
     clearTimeout(t);
-    // A successful query proves the DB is reachable end-to-end
-    poolErrors.markHealthy();
   } finally {
     releaseDBMutex(`pq:${name}`);
   }
@@ -156,14 +148,6 @@ export const getConnection = (
   creds?: PoolConfig,
   readonly = false,
 ): pg.Pool => {
-  if (!unhandledRejectionLoggerInstalled) {
-    unhandledRejectionLoggerInstalled = true;
-    installUnhandledRejectionLogger(
-      ComponentNames.EFFECTSTREAM_PGLITE,
-      isTransientPgError,
-    );
-  }
-
   if (!creds) {
     creds = {
       host: ENV.DB_HOST,
@@ -179,21 +163,30 @@ export const getConnection = (
   const MAX_CONNECTIONS = ENV.PGLITE ? 1 : 10;
 
   const pool = new pg.Pool({ ...creds, max: MAX_CONNECTIONS });
-  pool.on("error", (err: unknown) => poolErrors.log(err, ["query"]));
+  pool.on("error", (err: unknown) =>
+    log.remote(
+      ComponentNames.EFFECTSTREAM_PGLITE,
+      ["query"],
+      SeverityNumber.ERROR,
+      (log) => log(err),
+    ));
   pool.on("connect", (_client: PoolClient) => {
-    // Successful connect proves the DB is reachable — reset the failure clock.
-    poolErrors.markHealthy();
-    // Register a per-client error handler; pg can emit errors on idle clients.
+    // On each new client initiated, need to register for error(this is a serious bug on pg, the client throw errors although it should not)
     // https://github.com/brianc/node-postgres/issues/2499#issuecomment-805477725
-    _client.on("error", (err: Error) => poolErrors.log(err, ["connect"]));
+    _client.on("error", (err: Error) => {
+      log.remote(
+        ComponentNames.EFFECTSTREAM_PGLITE,
+        ["connect"],
+        SeverityNumber.ERROR,
+        (log) => log(err),
+      );
+    });
   });
 
   if (readonly) {
     const ensureReadOnly =
       `SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY;`;
-    void pool.query(ensureReadOnly).catch((err: unknown) =>
-      poolErrors.log(err, ["readonly-setup"]),
-    );
+    void pool.query(ensureReadOnly); // note: this query modifies the DB state
     readonlyDBConn = pool;
   }
 
@@ -205,6 +198,14 @@ export const getPersistentConnection = (creds: PoolConfig): Client => {
   const client = new pg.Client(creds);
   client.connect(() => {});
   // https://github.com/brianc/node-postgres/issues/2499#issuecomment-805477725
-  client.on("error", (err: Error) => poolErrors.log(err, ["persistent"]));
+  // On each new client initiated, need to register for error(this is a serious bug on pg, the client throw errors although it should not)
+  client.on("error", (err: Error) => {
+    log.remote(
+      ComponentNames.EFFECTSTREAM_PGLITE,
+      ["query"],
+      SeverityNumber.ERROR,
+      (log) => log(err),
+    );
+  });
   return client;
 };

package/src/sql/rollup_inputs.queries.ts

@@ -383,61 +383,6 @@ const getFutureGameInputByMaxTimestampIR: any = {"usedParamSet":{"max_timestamp"
 export const getFutureGameInputByMaxTimestamp = new PreparedQuery<IGetFutureGameInputByMaxTimestampParams,IGetFutureGameInputByMaxTimestampResult>(getFutureGameInputByMaxTimestampIR);
 
 
-/** 'GetEarliestScheduledBlockHeight' parameters type */
-export type IGetEarliestScheduledBlockHeightParams = void;
-
-/** 'GetEarliestScheduledBlockHeight' return type */
-export interface IGetEarliestScheduledBlockHeightResult {
-  min_block_height: number | null;
-}
-
-/** 'GetEarliestScheduledBlockHeight' query type */
-export interface IGetEarliestScheduledBlockHeightQuery {
-  params: IGetEarliestScheduledBlockHeightParams;
-  result: IGetEarliestScheduledBlockHeightResult;
-}
-
-const getEarliestScheduledBlockHeightIR: any = {"usedParamSet":{},"params":[],"statement":"SELECT MIN(future_block_height) AS min_block_height\nFROM effectstream.rollup_input_future_block"};
-
-/**
- * Query generated from SQL:
- * ```
- * SELECT MIN(future_block_height) AS min_block_height
- * FROM effectstream.rollup_input_future_block
- * ```
- */
-export const getEarliestScheduledBlockHeight = new PreparedQuery<IGetEarliestScheduledBlockHeightParams,IGetEarliestScheduledBlockHeightResult>(getEarliestScheduledBlockHeightIR);
-
-
-/** 'GetEarliestScheduledTimestamp' parameters type */
-export type IGetEarliestScheduledTimestampParams = void;
-
-/** 'GetEarliestScheduledTimestamp' return type */
-export interface IGetEarliestScheduledTimestampResult {
-  min_timestamp: Date | null;
-}
-
-/** 'GetEarliestScheduledTimestamp' query type */
-export interface IGetEarliestScheduledTimestampQuery {
-  params: IGetEarliestScheduledTimestampParams;
-  result: IGetEarliestScheduledTimestampResult;
-}
-
-const getEarliestScheduledTimestampIR: any = {"usedParamSet":{},"params":[],"statement":"SELECT MIN(rollup_input_future_timestamp.future_ms_timestamp) AS min_timestamp\nFROM effectstream.rollup_input_future_timestamp\nLEFT OUTER JOIN effectstream.rollup_input_result\n  ON (effectstream.rollup_input_result.id = effectstream.rollup_input_future_timestamp.id)\nWHERE effectstream.rollup_input_result.id IS NULL"};
-
-/**
- * Query generated from SQL:
- * ```
- * SELECT MIN(rollup_input_future_timestamp.future_ms_timestamp) AS min_timestamp
- * FROM effectstream.rollup_input_future_timestamp
- * LEFT OUTER JOIN effectstream.rollup_input_result
- *   ON (effectstream.rollup_input_result.id = effectstream.rollup_input_future_timestamp.id)
- * WHERE effectstream.rollup_input_result.id IS NULL
- * ```
- */
-export const getEarliestScheduledTimestamp = new PreparedQuery<IGetEarliestScheduledTimestampParams,IGetEarliestScheduledTimestampResult>(getEarliestScheduledTimestampIR);
-
-
 /** 'GetGameInputResultByBlockHeight' parameters type */
 export interface IGetGameInputResultByBlockHeightParams {
   block_height: number;

package/src/sql/rollup_inputs.sql

@@ -144,17 +144,6 @@ WHERE rollup_input_future_timestamp.future_ms_timestamp <= :max_timestamp! AND
      effectstream.rollup_input_result.id IS NULL
 ORDER BY rollup_input_future_timestamp.future_ms_timestamp ASC;
 
-/* @name getEarliestScheduledBlockHeight */
-SELECT MIN(future_block_height) AS min_block_height
-FROM effectstream.rollup_input_future_block;
-
-/* @name getEarliestScheduledTimestamp */
-SELECT MIN(rollup_input_future_timestamp.future_ms_timestamp) AS min_timestamp
-FROM effectstream.rollup_input_future_timestamp
-LEFT OUTER JOIN effectstream.rollup_input_result
-  ON (effectstream.rollup_input_result.id = effectstream.rollup_input_future_timestamp.id)
-WHERE effectstream.rollup_input_result.id IS NULL;
-
 /* @name getGameInputResultByBlockHeight */
 SELECT
   rollup_inputs.id,

package/src/pool-error-tracker.test.ts

@@ -1,65 +0,0 @@
-import { afterEach, expect, test } from "bun:test";
-
-// Thresholds are read from env at module load (and `envMs` rejects 0, so use
-// small positive values). SUSTAINED=5ms → a failure older than 5ms is
-// "sustained"; FATAL=30ms → older than 30ms triggers the process.exit
-// escalation. Dynamic import so these are picked up before the module
-// computes its constants.
-process.env.POOL_SUSTAINED_THRESHOLD_MS = "5";
-process.env.POOL_FATAL_THRESHOLD_MS = "30";
-const { PoolErrorTracker } = await import("./pool-error-tracker.ts");
-
-const transient = () => ({
-  code: "ECONNRESET",
-  message: "Client network socket disconnected before secure TLS connection",
-  stack: "    at node_modules/pg-pool/index.js:45:11",
-});
-
-const realExit = process.exit;
-afterEach(() => {
-  process.exit = realExit;
-});
-
-test("ignores non-transient errors (auth/schema bugs)", () => {
-  const t = new PoolErrorTracker();
-  t.log(new Error("column foo does not exist"), ["sync-write"]);
-  expect(t.state().consecutive).toBe(0);
-  expect(t.state().sustained).toBe(false);
-});
-
-test("counts consecutive transient failures and reports sustained", async () => {
-  const t = new PoolErrorTracker();
-  t.log(transient(), ["sync-write"]);
-  expect(t.state().sustained).toBe(false); // fresh failure, < 5ms old
-  await Bun.sleep(15); // exceed SUSTAINED_THRESHOLD_MS=5, stay under FATAL=30
-  t.log(transient(), ["sync-write"]);
-  const s = t.state();
-  expect(s.consecutive).toBe(2);
-  expect(s.sustained).toBe(true);
-});
-
-test("markHealthy resets the failure clock", () => {
-  const t = new PoolErrorTracker();
-  t.log(transient(), ["sync-write"]);
-  t.markHealthy();
-  const s = t.state();
-  expect(s.consecutive).toBe(0);
-  expect(s.firstFailureAt).toBe(0);
-  expect(s.sustained).toBe(false);
-});
-
-test("exits the process once failures persist past the fatal threshold", async () => {
-  let exitCode: number | undefined;
-  process.exit = ((code?: number) => {
-    exitCode = code;
-  }) as typeof process.exit;
-
-  const t = new PoolErrorTracker();
-  t.log(transient(), ["sync-write"]); // starts the clock; not yet fatal
-  await Bun.sleep(40); // exceed FATAL_THRESHOLD_MS=20
-  t.log(transient(), ["sync-write"]); // now duration >= fatal → schedules exit
-
-  // exit is deferred via setImmediate so the fatal log line can flush first.
-  await new Promise((resolve) => setImmediate(resolve));
-  expect(exitCode).toBe(1);
-});

package/src/pool-error-tracker.ts

@@ -1,87 +0,0 @@
-import { ComponentNames, log, SeverityNumber } from "@effectstream/log";
-import { isTransientPgError } from "./transient-pg-errors.ts";
-
-function envMs(name: string, fallback: number): number {
-  const raw = process.env[name];
-  const parsed = raw != null ? Number(raw) : NaN;
-  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
-}
-
-/** After this long, treat continuous transient failures as a real outage. */
-const SUSTAINED_THRESHOLD_MS = envMs("POOL_SUSTAINED_THRESHOLD_MS", 60_000);
-/** After this long, exit so the orchestrator restarts the process. */
-const FATAL_THRESHOLD_MS = envMs("POOL_FATAL_THRESHOLD_MS", 5 * 60_000);
-
-/**
- * Tracks consecutive transient pool errors. Severity escalates WARN → ERROR
- * once failures persist past `SUSTAINED_THRESHOLD_MS`, and the process exits
- * past `FATAL_THRESHOLD_MS` (relying on the orchestrator's restart policy).
- * Call `markHealthy()` on any positive signal to reset.
- */
-export class PoolErrorTracker {
-  private consecutive = 0;
-  private firstFailureAt = 0;
-
-  log(err: unknown, tags: string[]): void {
-    // Non-transient errors are a different failure mode (auth, schema, etc.).
-    if (!isTransientPgError(err)) {
-      log.remote(
-        ComponentNames.EFFECTSTREAM_PGLITE,
-        tags,
-        SeverityNumber.ERROR,
-        (l) => l(err),
-      );
-      return;
-    }
-
-    if (this.consecutive === 0) this.firstFailureAt = Date.now();
-    this.consecutive++;
-
-    const durationMs = Date.now() - this.firstFailureAt;
-    const sustained = durationMs >= SUSTAINED_THRESHOLD_MS;
-    const fatal = durationMs >= FATAL_THRESHOLD_MS;
-
-    log.remote(
-      ComponentNames.EFFECTSTREAM_PGLITE,
-      fatal
-        ? [...tags, "sustained-failure", "fatal"]
-        : sustained
-        ? [...tags, "sustained-failure"]
-        : tags,
-      sustained ? SeverityNumber.ERROR : SeverityNumber.WARN,
-      (l) => l({ err, consecutive: this.consecutive, durationMs }),
-    );
-
-    if (fatal) {
-      // Defer to the next tick so the log line above has a chance to flush.
-      setImmediate(() => process.exit(1));
-    }
-  }
-
-  /** Call when the DB has proven reachable (e.g. successful pool connect). */
-  markHealthy(): void {
-    this.consecutive = 0;
-    this.firstFailureAt = 0;
-  }
-
-  /** Read-only snapshot for health checks, heartbeats, or external probes. */
-  state(): {
-    consecutive: number;
-    firstFailureAt: number;
-    sustainedDurationMs: number;
-    sustained: boolean;
-  } {
-    const durationMs = this.firstFailureAt === 0
-      ? 0
-      : Date.now() - this.firstFailureAt;
-    return {
-      consecutive: this.consecutive,
-      firstFailureAt: this.firstFailureAt,
-      sustainedDurationMs: durationMs,
-      sustained: durationMs >= SUSTAINED_THRESHOLD_MS,
-    };
-  }
-}
-
-/** Process-wide singleton — failures aggregate at DB-health granularity. */
-export const poolErrors = new PoolErrorTracker();

package/src/transient-pg-errors.test.ts

@@ -1,47 +0,0 @@
-import { test, expect } from "bun:test";
-import { isTransientPgError } from "./transient-pg-errors.ts";
-
-test("isTransientPgError - Neon pg-pool TLS reset", () => {
-  expect(
-    isTransientPgError({
-      code: "ECONNRESET",
-      message:
-        "Client network socket disconnected before secure TLS connection was established",
-      stack: "    at /app/node_modules/.bun/pg-pool@3.14.0/node_modules/pg-pool/index.js:45:11",
-    }),
-  ).toBe(true);
-});
-
-test("isTransientPgError - rejects non-pg ETIMEDOUT", () => {
-  expect(
-    isTransientPgError({
-      code: "ETIMEDOUT",
-      message: "fetch failed",
-      stack: "    at node:internal/deps/undici/undici.js:1234:5",
-    }),
-  ).toBe(false);
-});
-
-test("isTransientPgError - walks cause chain", () => {
-  const inner = {
-    code: "ECONNRESET",
-    message:
-      "Client network socket disconnected before secure TLS connection was established",
-    stack: "    at node_modules/pg-pool/index.js:45:11",
-  };
-  expect(isTransientPgError({ message: "wrapper", cause: inner })).toBe(true);
-});
-
-test("isTransientPgError - rejects logic errors", () => {
-  expect(isTransientPgError(new Error("column foo does not exist"))).toBe(
-    false,
-  );
-});
-
-test("isTransientPgError - idle pool message without stack", () => {
-  expect(
-    isTransientPgError({
-      message: "Connection terminated unexpectedly",
-    }),
-  ).toBe(true);
-});

package/src/transient-pg-errors.ts

@@ -1,56 +0,0 @@
-const PG_STACK_RE = /node_modules\/(pg-pool|pg)\//;
-
-const TRANSIENT_PG_MESSAGES = [
-  "Connection terminated unexpectedly",
-  "Client has encountered a connection error",
-  "Client network socket disconnected before secure TLS connection",
-  "Query read timeout",
-] as const;
-
-function* walkErrors(reason: unknown): Generator<unknown> {
-  let current: unknown = reason;
-  const seen = new Set<unknown>();
-  while (current != null && typeof current === "object" && !seen.has(current)) {
-    seen.add(current);
-    yield current;
-    current = (current as { cause?: unknown }).cause;
-  }
-}
-
-function isFromPgStack(err: unknown): boolean {
-  if (err == null || typeof err !== "object" || !("stack" in err)) {
-    return false;
-  }
-  return PG_STACK_RE.test(String((err as Error).stack));
-}
-
-function hasTransientPgMessage(err: unknown): boolean {
-  if (err == null || typeof err !== "object") return false;
-  const msg = (err as { message?: string }).message;
-  if (typeof msg !== "string") return false;
-  return TRANSIENT_PG_MESSAGES.some((fragment) => msg.includes(fragment));
-}
-
-function isTransientPgErrorSingle(err: unknown): boolean {
-  if (err == null || typeof err !== "object") return false;
-  if (hasTransientPgMessage(err)) return true;
-  if (!isFromPgStack(err)) return false;
-  const code = (err as { code?: string }).code;
-  return code === "ECONNRESET" || code === "EPIPE" ||
-    code === "ECONNREFUSED";
-}
-
-/**
- * Returns true for pg / network errors that are normal on serverless Postgres
- * (Neon, etc.): cold-start RSTs, idle-socket evictions, transient TLS blips.
- * The pool recovers on the next query — use with `installUnhandledRejectionLogger`
- * from `@effectstream/log` so these do not crash the process.
- *
- * Intentionally narrow: known-recoverable conditions only; logic/SQL bugs still crash.
- */
-export function isTransientPgError(reason: unknown): boolean {
-  for (const err of walkErrors(reason)) {
-    if (isTransientPgErrorSingle(err)) return true;
-  }
-  return false;
-}