@oneuptime/common 14.0.6 → 14.0.8

package/Tests/Server/Utils/Topology/InventoryItemEntityKeyIndexMigrationPostgres.test.ts

@@ -0,0 +1,430 @@
+import {
+  AddInventoryItemProjectEntityKeyIndex1795200000000,
+  INVENTORY_ITEM_PROJECT_ENTITY_KEY_INDEX,
+  INVENTORY_ITEM_PROJECT_ENTITY_KEY_INDEX_RUNBOOK,
+} from "../../../../Server/Infrastructure/Postgres/SchemaMigrations/1795200000000-AddInventoryItemProjectEntityKeyIndex";
+import logger from "../../../../Server/Utils/Logger";
+import ObjectID from "../../../../Types/ObjectID";
+import { DataSource, QueryRunner } from "typeorm";
+
+/*
+ * Migration 1795200000000 EXECUTED on Postgres, against a clone of the
+ * migrated InventoryItem table: the branch that builds the index, the branch
+ * that leaves a large table to the operator's CONCURRENTLY runbook (and that
+ * runbook then working), the planner-statistics and bounded-count estimates,
+ * an INVALID leftover of a failed online build, and the statement_timeout the
+ * build runs under — the connection's own, even after something on the
+ * session raised it.
+ *
+ * The inline-build threshold is lowered through the migration's constructor so
+ * a few dozen rows stand in for a million.
+ *
+ * Opt in with RUN_POSTGRES_TOPOLOGY_TESTS=true (the Topology Postgres suites'
+ * flag) against a Postgres migrated to the current head. The table's
+ * STRUCTURE is cloned into a unique schema that is the connection's whole
+ * search_path, and dropped afterwards; no real row is read or written.
+ * Credentials from DATABASE_USERNAME / DATABASE_PASSWORD, database from
+ * TOPOLOGY_TEST_DATABASE_NAME or DATABASE_NAME, endpoint from
+ * TOPOLOGY_TEST_DATABASE_HOST / _PORT (default localhost:5400).
+ */
+const describePostgres: typeof describe =
+  process.env["RUN_POSTGRES_TOPOLOGY_TESTS"] === "true"
+    ? describe
+    : describe.skip;
+
+/* The connection's statement_timeout, distinct from any server default. */
+const CONNECTION_STATEMENT_TIMEOUT_MS: number = 43_210;
+
+/* DDL on an index, as the recorded statements spell it. */
+const INDEX_DDL: RegExp = /^(CREATE|DROP) INDEX/;
+
+/* Any index on exactly these columns, whatever the clone named it. */
+const ENTITY_KEY_INDEX_DEFINITION: RegExp = /\("projectId", "entityKey"\)$/;
+
+interface IndexState {
+  name: string;
+  isValid: boolean;
+  isUnique: boolean;
+  definition: string;
+}
+
+describePostgres(
+  "AddInventoryItemProjectEntityKeyIndex1795200000000 against Postgres",
+  () => {
+    const schema: string = `topology_migration_${ObjectID.generate()
+      .toString()
+      .replace(/-/g, "")}`;
+    const projectId: string = ObjectID.generate().toString();
+    let database: DataSource;
+
+    beforeAll(async () => {
+      database = new DataSource({
+        type: "postgres",
+        host: process.env["TOPOLOGY_TEST_DATABASE_HOST"] || "localhost",
+        port: Number(process.env["TOPOLOGY_TEST_DATABASE_PORT"] || "5400"),
+        username: process.env["DATABASE_USERNAME"] || "postgres",
+        password: process.env["DATABASE_PASSWORD"] || "password",
+        database:
+          process.env["TOPOLOGY_TEST_DATABASE_NAME"] ||
+          process.env["DATABASE_NAME"] ||
+          "oneuptimedb",
+        entities: [],
+        schema,
+        synchronize: false,
+        extra: {
+          options: `-c search_path=${schema}`,
+          statement_timeout: CONNECTION_STATEMENT_TIMEOUT_MS,
+        },
+      });
+      await database.initialize();
+      await database.query(`CREATE SCHEMA "${schema}"`);
+      expect(
+        (await database.query("SELECT current_schema()"))[0].current_schema,
+      ).toBe(schema);
+    });
+
+    afterAll(async () => {
+      if (database?.isInitialized) {
+        await database.query(`DROP SCHEMA IF EXISTS "${schema}" CASCADE`);
+        await database.destroy();
+      }
+    });
+
+    /*
+     * A fresh clone per test: new tables have never been analyzed, so each
+     * test starts from the statistics a just-created table has.
+     */
+    beforeEach(async () => {
+      await database.query(`DROP TABLE IF EXISTS "${schema}"."InventoryItem"`);
+      await database.query(
+        `CREATE TABLE "${schema}"."InventoryItem" (LIKE public."InventoryItem" INCLUDING ALL)`,
+      );
+      for (const index of await indexes()) {
+        await database.query(`DROP INDEX "${schema}"."${index.name}"`);
+      }
+    });
+
+    afterEach(() => {
+      jest.restoreAllMocks();
+    });
+
+    /* The indexes on ("projectId", "entityKey") in the test schema. */
+    async function indexes(): Promise<Array<IndexState>> {
+      const rows: Array<{
+        name: string;
+        isValid: boolean;
+        isUnique: boolean;
+        definition: string;
+      }> = await database.query(
+        `SELECT c.relname AS "name", x.indisvalid AS "isValid",
+                x.indisunique AS "isUnique",
+                pg_get_indexdef(x.indexrelid) AS "definition"
+         FROM pg_index x
+         JOIN pg_class c ON c.oid = x.indexrelid
+         JOIN pg_class t ON t.oid = x.indrelid
+         JOIN pg_namespace n ON n.oid = t.relnamespace
+         WHERE n.nspname = $1 AND t.relname = 'InventoryItem'`,
+        [schema],
+      );
+      return rows.filter((index: IndexState): boolean => {
+        return ENTITY_KEY_INDEX_DEFINITION.test(index.definition);
+      });
+    }
+
+    /* `count` items with distinct keys, or all sharing one key. */
+    async function seed(count: number, sharedKey?: string): Promise<void> {
+      await database.query(
+        `INSERT INTO "${schema}"."InventoryItem"
+          ("_id", "createdAt", "updatedAt", "version", "projectId", "entityType",
+           "entityKey", "displayName", "source", "lastSeenAt", "isArchived")
+         SELECT gen_random_uuid(), now(), now(), 1, $1, 'type-' || g,
+                COALESCE($2, 'key-' || g), 'item ' || g, 'discovered', now(), false
+         FROM generate_series(1, $3) AS g`,
+        [projectId, sharedKey ?? null, count],
+      );
+    }
+
+    interface Run {
+      statements: Array<string>;
+      /* current_setting('statement_timeout') right after up() returned. */
+      statementTimeout: string;
+    }
+
+    /*
+     * Runs up() the way TypeORM runs a migration: inside its own transaction
+     * on one connection. `before` runs on that connection first.
+     */
+    async function runUp(
+      maxRows: number,
+      before?: (queryRunner: QueryRunner) => Promise<void>,
+    ): Promise<Run> {
+      const queryRunner: QueryRunner = database.createQueryRunner();
+      await queryRunner.connect();
+      const statements: Array<string> = [];
+      const query: QueryRunner["query"] = queryRunner.query.bind(queryRunner);
+      queryRunner.query = (async (
+        sql: string,
+        params?: Array<unknown>,
+      ): Promise<unknown> => {
+        statements.push(sql.replace(/\s+/g, " ").trim());
+        return await query(sql, params);
+      }) as QueryRunner["query"];
+      try {
+        if (before) {
+          await before(queryRunner);
+        }
+        await queryRunner.startTransaction();
+        try {
+          await new AddInventoryItemProjectEntityKeyIndex1795200000000(
+            maxRows,
+          ).up(queryRunner);
+          const setting: Array<{ value: string }> = await query(
+            `SELECT current_setting('statement_timeout') AS "value"`,
+          );
+          await queryRunner.commitTransaction();
+          return { statements, statementTimeout: setting[0]!.value };
+        } catch (error) {
+          await queryRunner.rollbackTransaction();
+          throw error;
+        }
+      } finally {
+        // Nothing `before` set may follow the connection back into the pool.
+        await query(`RESET statement_timeout`);
+        await queryRunner.release();
+      }
+    }
+
+    function silenceWarnings(): { mock: { calls: Array<Array<unknown>> } } {
+      return jest.spyOn(logger, "warn").mockImplementation((): void => {
+        return undefined;
+      }) as unknown as { mock: { calls: Array<Array<unknown>> } };
+    }
+
+    function created(run: Run): boolean {
+      return run.statements.some((statement: string): boolean => {
+        return statement.startsWith("CREATE INDEX");
+      });
+    }
+
+    function counted(run: Run): boolean {
+      return run.statements.some((statement: string): boolean => {
+        return statement.includes("COUNT(*)");
+      });
+    }
+
+    test("a table under the threshold gets the plain, valid, non-unique index", async () => {
+      await seed(5);
+      const run: Run = await runUp(10);
+      expect(created(run)).toBe(true);
+      expect(await indexes()).toEqual([
+        {
+          name: INVENTORY_ITEM_PROJECT_ENTITY_KEY_INDEX,
+          isValid: true,
+          isUnique: false,
+          definition: expect.stringMatching(
+            /^CREATE INDEX "IDX_INVENTORY_ITEM_PROJECT_ENTITY_KEY" ON .*"InventoryItem" USING btree \("projectId", "entityKey"\)$/,
+          ),
+        },
+      ]);
+    });
+
+    test("the build runs under the connection's statement_timeout, even after the session raised it", async () => {
+      await seed(3);
+      const run: Run = await runUp(
+        10,
+        async (queryRunner: QueryRunner): Promise<void> => {
+          await queryRunner.query(`SET statement_timeout = '600s'`);
+        },
+      );
+      expect(created(run)).toBe(true);
+      expect(run.statementTimeout).toBe(`${CONNECTION_STATEMENT_TIMEOUT_MS}ms`);
+    });
+
+    test("a table past the threshold is left to the runbook, which then works, and a rerun is a no-op", async () => {
+      const warn: { mock: { calls: Array<Array<unknown>> } } =
+        silenceWarnings();
+      await seed(50);
+
+      const skipped: Run = await runUp(10);
+      expect(created(skipped)).toBe(false);
+      expect(await indexes()).toEqual([]);
+      expect(warn.mock.calls).toHaveLength(1);
+      expect(String(warn.mock.calls[0]![0])).toContain(
+        INVENTORY_ITEM_PROJECT_ENTITY_KEY_INDEX_RUNBOOK,
+      );
+
+      // The operator's online build, outside any transaction.
+      await database.query(INVENTORY_ITEM_PROJECT_ENTITY_KEY_INDEX_RUNBOOK);
+      expect(await indexes()).toEqual([
+        expect.objectContaining({
+          name: INVENTORY_ITEM_PROJECT_ENTITY_KEY_INDEX,
+          isValid: true,
+          isUnique: false,
+        }),
+      ]);
+
+      const rerun: Run = await runUp(10);
+      expect(
+        rerun.statements.filter((statement: string): boolean => {
+          return INDEX_DDL.test(statement);
+        }),
+      ).toEqual([]);
+      expect(counted(rerun)).toBe(false);
+      expect(warn.mock.calls).toHaveLength(1);
+    });
+
+    test("an analyzed table is judged by the planner's statistics, without a count", async () => {
+      silenceWarnings();
+      await seed(50);
+      await database.query(`ANALYZE "${schema}"."InventoryItem"`);
+
+      const skipped: Run = await runUp(10);
+      expect(counted(skipped)).toBe(false);
+      expect(created(skipped)).toBe(false);
+
+      const built: Run = await runUp(100);
+      expect(counted(built)).toBe(false);
+      expect(created(built)).toBe(true);
+      expect(await indexes()).toHaveLength(1);
+    });
+
+    test("a never-analyzed table is counted, only up to just past the threshold", async () => {
+      silenceWarnings();
+      await seed(50);
+      const run: Run = await runUp(10);
+      /*
+       * Autovacuum may analyze the fresh table first; either way the table
+       * is judged too large.
+       */
+      expect(created(run)).toBe(false);
+      expect(await indexes()).toEqual([]);
+    });
+
+    test("an INVALID leftover of a failed online build is dropped and rebuilt", async () => {
+      // Two rows sharing (projectId, entityKey) make a UNIQUE online build fail.
+      await seed(2, "shared-key");
+      await expect(
+        database.query(
+          `CREATE UNIQUE INDEX CONCURRENTLY "${INVENTORY_ITEM_PROJECT_ENTITY_KEY_INDEX}" ON "InventoryItem" ("projectId", "entityKey")`,
+        ),
+      ).rejects.toThrow();
+      expect(await indexes()).toEqual([
+        expect.objectContaining({
+          name: INVENTORY_ITEM_PROJECT_ENTITY_KEY_INDEX,
+          isValid: false,
+          isUnique: true,
+        }),
+      ]);
+
+      const run: Run = await runUp(10);
+      expect(run.statements).toContain(
+        `DROP INDEX IF EXISTS "${INVENTORY_ITEM_PROJECT_ENTITY_KEY_INDEX}"`,
+      );
+      expect(await indexes()).toEqual([
+        expect.objectContaining({
+          name: INVENTORY_ITEM_PROJECT_ENTITY_KEY_INDEX,
+          isValid: true,
+          isUnique: false,
+        }),
+      ]);
+    });
+
+    /*
+     * An operator's CONCURRENTLY build that is still running is INVALID
+     * until it finishes. Dropping it would queue for ACCESS EXCLUSIVE behind
+     * the build and stall every reader and writer of the table, so the
+     * migration must leave it alone and complete at once.
+     */
+    test("an online build still in progress is left to finish, never dropped", async () => {
+      await seed(3);
+      const writer: QueryRunner = database.createQueryRunner();
+      const builder: QueryRunner = database.createQueryRunner();
+      await writer.connect();
+      await builder.connect();
+      try {
+        // An open writer makes CONCURRENTLY wait with its index INVALID.
+        await writer.startTransaction();
+        await writer.query(
+          `INSERT INTO "InventoryItem"
+            ("_id", "createdAt", "updatedAt", "version", "projectId", "entityType",
+             "entityKey", "displayName", "source", "lastSeenAt", "isArchived")
+           VALUES (gen_random_uuid(), now(), now(), 1, $1, 'type-w', 'key-w',
+             'writer', 'discovered', now(), false)`,
+          [projectId],
+        );
+        const build: Promise<unknown> = builder.query(
+          `CREATE INDEX CONCURRENTLY "${INVENTORY_ITEM_PROJECT_ENTITY_KEY_INDEX}" ON "InventoryItem" ("projectId", "entityKey")`,
+        );
+
+        let inProgress: boolean = false;
+        for (let attempt: number = 0; attempt < 50 && !inProgress; attempt++) {
+          const rows: Array<unknown> = await database.query(
+            `SELECT 1 FROM pg_stat_progress_create_index p
+             JOIN pg_class c ON c.oid = p.index_relid
+             WHERE c.relname = $1`,
+            [INVENTORY_ITEM_PROJECT_ENTITY_KEY_INDEX],
+          );
+          inProgress = rows.length > 0;
+          if (!inProgress) {
+            await new Promise<void>((resolve: () => void): void => {
+              setTimeout(resolve, 100);
+            });
+          }
+        }
+        expect(inProgress).toBe(true);
+        expect(await indexes()).toEqual([
+          expect.objectContaining({ isValid: false }),
+        ]);
+
+        const warn: { mock: { calls: Array<Array<unknown>> } } =
+          silenceWarnings();
+        const startedAt: number = Date.now();
+        const run: Run = await runUp(10);
+        expect(Date.now() - startedAt).toBeLessThan(3_000);
+        expect(run.statements).not.toContain(
+          `DROP INDEX IF EXISTS "${INVENTORY_ITEM_PROJECT_ENTITY_KEY_INDEX}"`,
+        );
+        expect(created(run)).toBe(false);
+        expect(String(warn.mock.calls[0]![0])).toContain("in progress");
+
+        await writer.commitTransaction();
+        await build;
+        expect(await indexes()).toEqual([
+          expect.objectContaining({
+            name: INVENTORY_ITEM_PROJECT_ENTITY_KEY_INDEX,
+            isValid: true,
+            isUnique: false,
+          }),
+        ]);
+      } finally {
+        if (writer.isTransactionActive) {
+          await writer.rollbackTransaction();
+        }
+        await writer.release();
+        await builder.release();
+      }
+    });
+
+    test("down() drops it, inside its own transaction as TypeORM runs it", async () => {
+      await seed(1);
+      await runUp(10);
+      expect(await indexes()).toHaveLength(1);
+      const queryRunner: QueryRunner = database.createQueryRunner();
+      await queryRunner.connect();
+      try {
+        await queryRunner.startTransaction();
+        await new AddInventoryItemProjectEntityKeyIndex1795200000000().down(
+          queryRunner,
+        );
+        const lockTimeout: Array<{ value: string }> = await queryRunner.query(
+          `SELECT current_setting('lock_timeout') AS "value"`,
+        );
+        expect(lockTimeout[0]!.value).toBe("5s");
+        await queryRunner.commitTransaction();
+      } finally {
+        await queryRunner.release();
+      }
+      expect(await indexes()).toEqual([]);
+    });
+  },
+);

package/Tests/Server/Utils/Topology/TopologyActivityParityPostgres.test.ts

@@ -0,0 +1,279 @@
+import {
+  activeSql,
+  epochMsSql,
+} from "../../../../Server/Utils/Topology/TopologySql";
+import EntitySource from "../../../../Types/Telemetry/EntitySource";
+import {
+  ActivityFields,
+  isEntityActive,
+} from "../../../../../App/FeatureSet/Dashboard/src/Components/Topology/TopologyActivity";
+import { DataSource, QueryRunner } from "typeorm";
+
+/*
+ * "Did this resource report in the range?" is answered twice: by Postgres
+ * (activeSql, which picks each resource's active container, counts active
+ * collection items and runs-on targets) and by the browser
+ * (TopologyActivity.isEntityActive, which decides what the maps draw). The
+ * browser judges the rows the server shipped — `source` and `lastSeenAt`
+ * floored to epoch milliseconds (epochMsSql) — against the range start the
+ * server echoed. If the two ever disagree, a resource is drawn inactive
+ * inside the container the server chose as its ACTIVE one, or counted as
+ * active in a total the map then leaves out.
+ *
+ * This runs the real predicate text through a real Postgres over a truth
+ * table, feeds the same rows through the browser predicate exactly as the
+ * decoder would hand them over, and requires the answers to match — at
+ * microsecond precision around the range start, and whatever the session
+ * time zone is. No table is read or written: the rows are an unnest() of
+ * bound arrays.
+ *
+ * Opt in with RUN_POSTGRES_TOPOLOGY_TESTS=true (the flag the other Topology
+ * Postgres suite uses). Credentials from DATABASE_USERNAME /
+ * DATABASE_PASSWORD, database from TOPOLOGY_TEST_DATABASE_NAME or
+ * DATABASE_NAME, endpoint from TOPOLOGY_TEST_DATABASE_HOST / _PORT (default
+ * localhost:5400).
+ */
+const describePostgres: typeof describe =
+  process.env["RUN_POSTGRES_TOPOLOGY_TESTS"] === "true"
+    ? describe
+    : describe.skip;
+
+/* The server floors the range start to the minute; this one already is. */
+const RANGE_START_ISO: string = "2026-09-20T10:00:00.000Z";
+
+interface ParityCase {
+  label: string;
+  source: string | null;
+  /* timestamptz input text (microseconds and offsets allowed), or null. */
+  lastSeenAt: string | null;
+  active: boolean;
+}
+
+const CASES: Array<ParityCase> = [
+  {
+    label: "discovered, exactly at the range start",
+    source: EntitySource.Discovered,
+    lastSeenAt: "2026-09-20T10:00:00.000000Z",
+    active: true,
+  },
+  {
+    label: "discovered, 1 microsecond before the range start",
+    source: EntitySource.Discovered,
+    lastSeenAt: "2026-09-20T09:59:59.999999Z",
+    active: false,
+  },
+  {
+    label: "discovered, 1 microsecond after the range start",
+    source: EntitySource.Discovered,
+    lastSeenAt: "2026-09-20T10:00:00.000001Z",
+    active: true,
+  },
+  {
+    label: "discovered, half a millisecond before (floors below the start)",
+    source: EntitySource.Discovered,
+    lastSeenAt: "2026-09-20T09:59:59.999500Z",
+    active: false,
+  },
+  {
+    label: "discovered, 999 microseconds after (floors onto the start)",
+    source: EntitySource.Discovered,
+    lastSeenAt: "2026-09-20T10:00:00.000999Z",
+    active: true,
+  },
+  {
+    label: "discovered, the start written in another offset",
+    source: EntitySource.Discovered,
+    lastSeenAt: "2026-09-20T12:00:00+02:00",
+    active: true,
+  },
+  {
+    label: "discovered, 1 ms before the start in another offset",
+    source: EntitySource.Discovered,
+    lastSeenAt: "2026-09-20T05:59:59.999-04:00",
+    active: false,
+  },
+  {
+    label: "discovered, a day stale",
+    source: EntitySource.Discovered,
+    lastSeenAt: "2026-09-19T10:00:00Z",
+    active: false,
+  },
+  {
+    label: "discovered, never reported",
+    source: EntitySource.Discovered,
+    lastSeenAt: null,
+    active: true,
+  },
+  {
+    label: "no source, stale",
+    source: null,
+    lastSeenAt: "2026-09-19T10:00:00Z",
+    active: false,
+  },
+  {
+    label: "no source, never reported",
+    source: null,
+    lastSeenAt: null,
+    active: true,
+  },
+  {
+    label: "blank source, stale",
+    source: "",
+    lastSeenAt: "2026-09-19T10:00:00Z",
+    active: false,
+  },
+  {
+    label: "blank source, in range",
+    source: "",
+    lastSeenAt: "2026-09-20T10:05:00Z",
+    active: true,
+  },
+  {
+    label: "manual, a year stale",
+    source: EntitySource.Manual,
+    lastSeenAt: "2025-09-20T10:00:00Z",
+    active: true,
+  },
+  {
+    label: "inventory-mirrored, stale",
+    source: EntitySource.Inventory,
+    lastSeenAt: "2026-09-19T10:00:00Z",
+    active: true,
+  },
+  {
+    label: "manual, never reported",
+    source: EntitySource.Manual,
+    lastSeenAt: null,
+    active: true,
+  },
+  {
+    label: "'Discovered' in another case is not discovered",
+    source: "Discovered",
+    lastSeenAt: "2026-09-19T10:00:00Z",
+    active: true,
+  },
+  {
+    label: "a whitespace source is not blank",
+    source: " ",
+    lastSeenAt: "2026-09-19T10:00:00Z",
+    active: true,
+  },
+];
+
+interface ParityRow {
+  ord: number;
+  active: boolean;
+  lastSeenAt: number | null;
+}
+
+/* The row as the Dashboard decoder hands it to isEntityActive. */
+function decodedFields(
+  source: string | null,
+  lastSeenAt: number | null,
+): ActivityFields {
+  const fields: ActivityFields = {};
+  if (typeof source === "string") {
+    fields.source = source;
+  }
+  if (typeof lastSeenAt === "number") {
+    fields.lastSeenAt = new Date(lastSeenAt);
+  }
+  return fields;
+}
+
+async function evaluate(runner: QueryRunner): Promise<Array<ParityRow>> {
+  const sql: string =
+    `SELECT t."ord" AS "ord", ${activeSql("t", "$1")} AS "active", ` +
+    `${epochMsSql('t."lastSeenAt"')} AS "lastSeenAt" ` +
+    `FROM unnest($2::int[], $3::text[], $4::timestamptz[]) ` +
+    `AS t("ord", "source", "lastSeenAt") ORDER BY t."ord"`;
+  return (await runner.query(sql, [
+    RANGE_START_ISO,
+    CASES.map((_testCase: ParityCase, index: number): number => {
+      return index;
+    }),
+    CASES.map((testCase: ParityCase): string | null => {
+      return testCase.source;
+    }),
+    CASES.map((testCase: ParityCase): string | null => {
+      return testCase.lastSeenAt;
+    }),
+  ])) as Array<ParityRow>;
+}
+
+describePostgres("Topology activity: SQL and browser agree on Postgres", () => {
+  let database: DataSource;
+  let runner: QueryRunner;
+
+  beforeAll(async () => {
+    database = new DataSource({
+      type: "postgres",
+      host: process.env["TOPOLOGY_TEST_DATABASE_HOST"] || "localhost",
+      port: Number(process.env["TOPOLOGY_TEST_DATABASE_PORT"] || "5400"),
+      username: process.env["DATABASE_USERNAME"] || "postgres",
+      password: process.env["DATABASE_PASSWORD"] || "password",
+      database:
+        process.env["TOPOLOGY_TEST_DATABASE_NAME"] ||
+        process.env["DATABASE_NAME"] ||
+        "oneuptimedb",
+      entities: [],
+      synchronize: false,
+    });
+    await database.initialize();
+    /* One connection, so the session time zone below sticks. */
+    runner = database.createQueryRunner();
+    await runner.connect();
+  });
+
+  afterAll(async () => {
+    await runner?.release();
+    if (database?.isInitialized) {
+      await database.destroy();
+    }
+  });
+
+  test.each(["UTC", "America/Los_Angeles", "Asia/Kolkata"])(
+    "every row agrees, with the session time zone at %s",
+    async (timeZone: string) => {
+      await runner.query(`SELECT set_config('TimeZone', $1, false)`, [
+        timeZone,
+      ]);
+      const rows: Array<ParityRow> = await evaluate(runner);
+      const rangeStart: Date = new Date(RANGE_START_ISO);
+
+      expect(rows).toHaveLength(CASES.length);
+      for (const row of rows) {
+        const testCase: ParityCase = CASES[row.ord]!;
+        const browser: boolean = isEntityActive(
+          decodedFields(testCase.source, row.lastSeenAt),
+          rangeStart,
+        );
+        expect({ label: testCase.label, sql: row.active, browser }).toEqual({
+          label: testCase.label,
+          sql: testCase.active,
+          browser: testCase.active,
+        });
+      }
+    },
+  );
+
+  test("the epoch the browser receives is the floor of the stored instant", async () => {
+    await runner.query(`SELECT set_config('TimeZone', 'UTC', false)`);
+    const rows: Array<ParityRow> = await evaluate(runner);
+    const byLabel: Map<string, number | null> = new Map<string, number | null>(
+      rows.map((row: ParityRow): [string, number | null] => {
+        return [CASES[row.ord]!.label, row.lastSeenAt];
+      }),
+    );
+
+    expect(
+      byLabel.get(
+        "discovered, half a millisecond before (floors below the start)",
+      ),
+    ).toBe(Date.parse("2026-09-20T09:59:59.999Z"));
+    expect(
+      byLabel.get("discovered, 999 microseconds after (floors onto the start)"),
+    ).toBe(Date.parse(RANGE_START_ISO));
+    expect(byLabel.get("discovered, never reported")).toBeNull();
+  });
+});