Skip to content

Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.

13.4 KB
Raw Blame
import { describe, expect, test } from "bun:test";
import { createHash } from "node:crypto";
import { mkdtemp, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { MIGRATIONS_JOURNAL } from "../src/db/apply-migrations";
import {
  type AppliedMigration,
  type FolderMigration,
  type MigrationsJournal,
  migrationsOutOfReach,
  migratorHighWaterMark,
  outOfReachRefusal,
  readMigrationFolder,
} from "../src/db/migration-reach";

/**
 * The check that `migration-journal.test.ts` cannot make.
 *
 * That file reads one journal and asks whether it is internally consistent — stamps increasing, a
 * file for every entry, a snapshot for every file. Every one of those passed over the defect this
 * file exists for, because the defect is not inside the journal. It is between the journal in the
 * repository and the stamps that a PREVIOUS journal already wrote into a running database: the
 * merge that renumbered this branch's migrations gave main's `0053_identity_links` a `when` older
 * than the stamp a pre-merge database had already recorded for the branch's own work, and the
 * migrator skips what it finds below the newest stamp without a word. `migrate` printed
 * `{"type":"migrations-applied","status":"ok"}` while `identity_links` and
 * `identity_link_challenges` did not exist.
 *
 * No journal, read alone, can show that. So the check lives in the migrator's path instead, and
 * this is its test.
 */

const migration = (
  tag: string,
  when: number,
  hash: string,
): FolderMigration => ({ tag, when, hash });

const applied = (hash: string, createdAt: number | null): AppliedMigration => ({
  hash,
  createdAt,
});

describe("migrations out of reach", () => {
  test("finds none on a database the migrator has never touched", () => {
    const folder = [
      migration("0000_first", 1000, "a"),
      migration("0001_second", 2000, "b"),
    ];

    expect(migrationsOutOfReach(folder, [])).toEqual([]);
  });

  test("finds none when the database is simply behind the folder", () => {
    const folder = [
      migration("0000_first", 1000, "a"),
      migration("0001_second", 2000, "b"),
      migration("0002_third", 3000, "c"),
    ];

    // The normal case, and the one that must never be refused: two applied, one pending.
    expect(
      migrationsOutOfReach(folder, [applied("a", 1000), applied("b", 2000)]),
    ).toEqual([]);
  });

  test("finds none when the database is exactly up to date", () => {
    const folder = [
      migration("0000_first", 1000, "a"),
      migration("0001_second", 2000, "b"),
    ];

    expect(
      migrationsOutOfReach(folder, [applied("a", 1000), applied("b", 2000)]),
    ).toEqual([]);
  });

  test("names a migration stamped below the mark that has never been applied", () => {
    /*
     * The renumber, in miniature. The database ran a branch whose migration was stamped 3000; the
     * merge then brought in a migration from main stamped 2000 and restamped the branch's work
     * 4000. The migrator compares against 3000, so 2000 is walked past, 4000 runs, and the run is
     * reported as a success that applied everything.
     */
    const folder = [
      migration("0000_first", 1000, "a"),
      migration("0001_from_main", 2000, "main"),
      migration("0002_branch_renumbered", 4000, "renumbered"),
    ];
    const database = [applied("a", 1000), applied("branch-as-shipped", 3000)];

    expect(migrationsOutOfReach(folder, database)).toEqual([
      migration("0001_from_main", 2000, "main"),
    ]);
  });

  test("names a migration stamped exactly on the mark", () => {
    /*
     * The comparison the migrator makes is `recorded < when`, so a migration stamped exactly at the
     * mark is skipped as surely as one stamped below it. Off by one here would be a check that
     * passes a database it cannot bring up to date.
     */
    const folder = [
      migration("0000_first", 1000, "a"),
      migration("0001_tied", 2000, "tied"),
    ];

    expect(migrationsOutOfReach(folder, [applied("a", 2000)])).toEqual([
      migration("0001_tied", 2000, "tied"),
    ]);
  });

  test("names every unreachable migration, not just the first", () => {
    const folder = [
      migration("0001_one", 1000, "one"),
      migration("0002_two", 2000, "two"),
      migration("0003_three", 5000, "three"),
    ];

    expect(
      migrationsOutOfReach(folder, [applied("something-else", 3000)]),
    ).toEqual([
      migration("0001_one", 1000, "one"),
      migration("0002_two", 2000, "two"),
    ]);
  });

  test("is not fooled by a migration whose file has been rewritten", () => {
    // Applied under one hash, present in the folder under another: the database ran different SQL
    // from the file that now claims to be it, and the difference will never be applied.
    const folder = [migration("0000_first", 1000, "rewritten")];

    expect(migrationsOutOfReach(folder, [applied("original", 1000)])).toEqual([
      migration("0000_first", 1000, "rewritten"),
    ]);
  });
});

describe("the row the migrator reads", () => {
  /*
   * The guard is only as good as its agreement with the migrator about WHICH applied row is the
   * mark. drizzle reads `order by created_at desc limit 1`, and Postgres sorts NULLs first in a
   * descending order: one NULL `created_at` is the row it reads, `Number(null)` is 0, and every
   * migration in the folder looks unapplied. `Math.max` over the stamps picks the newest real one
   * instead, finds nothing out of reach, and waves through a run that dies re-creating the first
   * type the database already has (`type "agent_type" already exists`).
   */
  test("is a NULL created_at, however many real stamps sit below it", () => {
    const folder = [
      migration("0000_first", 1000, "a"),
      migration("0001_second", 2000, "b"),
    ];
    const database = [
      applied("a", 1000),
      applied("b", 2000),
      applied("hand-written", null),
    ];

    expect(migratorHighWaterMark(database)).toBe(0);
    expect(migrationsOutOfReach(folder, database)).toEqual(folder);
  });

  test("is the newest stamp when no created_at is NULL", () => {
    expect(
      migratorHighWaterMark([applied("a", 1000), applied("b", 2000)]),
    ).toBe(2000);
  });

  test("does not exist on a database the migrator has never touched", () => {
    expect(migratorHighWaterMark([])).toBeUndefined();
  });

  test("refuses every applied migration the shipped folder would run a second time", async () => {
    const folder = await readMigrationFolder(
      new URL("../drizzle/", import.meta.url).pathname,
    );
    const database = [
      ...folder.map((entry) => applied(entry.hash, entry.when)),
      applied("hand-written", null),
    ];

    expect(
      migrationsOutOfReach(folder, database).map((entry) => entry.tag),
    ).toEqual(folder.map((entry) => entry.tag));
  });

  test("says that a NULL created_at is the mark, and names what would run twice", () => {
    const folder = [
      migration("0000_first", 1000, "a"),
      migration("0001_second", 2000, "b"),
    ];
    const database = [
      applied("a", 1000),
      applied("b", 2000),
      applied("hand-written", null),
    ];
    const text = outOfReachRefusal(
      migrationsOutOfReach(folder, database),
      folder,
      database,
      MIGRATIONS_JOURNAL,
    );

    expect(text).toContain("1 applied row has a NULL created_at");
    expect(text).toContain("would run them a second time");
    expect(text).toContain("0000_first (stamped 1000)");
    expect(text).toContain("0001_second (stamped 2000)");
    expect(text).not.toContain("would skip");
  });
});

describe("the refusal", () => {
  const folder = [
    migration("0000_first", 1000, "a"),
    migration("0001_from_main", 2000, "main"),
    migration("0002_branch_renumbered", 4000, "renumbered"),
  ];
  const database = [applied("a", 1000), applied("branch-as-shipped", 3000)];
  const text = outOfReachRefusal(
    migrationsOutOfReach(folder, database),
    folder,
    database,
    MIGRATIONS_JOURNAL,
  );

  test("names the migration that cannot be reached", () => {
    expect(text).toContain("0001_from_main (stamped 2000)");
  });

  test("names the mark that puts it out of reach", () => {
    expect(text).toContain("stamped 3000");
  });

  test("says that the database ran a journal this folder no longer has", () => {
    expect(text).toContain("1 applied migration is not in this folder at all");
  });

  test("says that nothing was applied", () => {
    expect(text).toContain("Nothing has been applied.");
  });
});

describe("the refusal, for a journal kept somewhere other than the default", () => {
  /*
   * The repair instructions are SQL an operator pastes into psql. They must name the table the
   * check read — never a spelling of the default that the configuration no longer guarantees.
   */
  const elsewhere: MigrationsJournal = {
    migrationsSchema: "c4_journal",
    migrationsTable: "applied_migrations",
  };
  const folder = [
    migration("0000_first", 1000, "a"),
    migration("0001_from_main", 2000, "main"),
    migration("0002_branch_renumbered", 4000, "renumbered"),
  ];

  test("tells the operator to record a skipped migration in that table", () => {
    const database = [applied("a", 1000), applied("branch-as-shipped", 3000)];
    const text = outOfReachRefusal(
      migrationsOutOfReach(folder, database),
      folder,
      database,
      elsewhere,
    );

    expect(text).toContain(
      'insert into "c4_journal"."applied_migrations" (hash, created_at)',
    );
    expect(text).not.toContain("__drizzle_migrations");
  });

  test("tells the operator to repair a NULL created_at in that table", () => {
    const database = [
      applied("a", 1000),
      applied("main", 2000),
      applied("hand-written", null),
    ];
    const text = outOfReachRefusal(
      migrationsOutOfReach(folder, database),
      folder,
      database,
      elsewhere,
    );

    expect(text).toContain("1 applied row has a NULL created_at");
    expect(text).toContain('update "c4_journal"."applied_migrations" set');
    expect(text).not.toContain("__drizzle_migrations");
  });

  test("quotes a name that would otherwise need it", () => {
    const database = [applied("a", 1000), applied("branch-as-shipped", 3000)];
    const text = outOfReachRefusal(
      migrationsOutOfReach(folder, database),
      folder,
      database,
      { migrationsSchema: "Ops", migrationsTable: 'odd"name' },
    );

    expect(text).toContain('insert into "Ops"."odd""name" (hash, created_at)');
  });
});

describe("reading a migration folder", () => {
  test("hashes the whole file the way the migrator does", async () => {
    const directory = await mkdtemp(join(tmpdir(), "migration-reach-"));
    const sql = 'CREATE TABLE "one" ("id" text);\n';
    await writeFile(join(directory, "0000_one.sql"), sql);
    await Bun.write(
      join(directory, "meta", "_journal.json"),
      JSON.stringify({
        version: "7",
        dialect: "postgresql",
        entries: [
          {
            idx: 0,
            version: "7",
            when: 1000,
            tag: "0000_one",
            breakpoints: true,
          },
        ],
      }),
    );

    expect(await readMigrationFolder(directory)).toEqual([
      {
        tag: "0000_one",
        when: 1000,
        // Whole file, before any `--> statement-breakpoint` split, which is what
        // `drizzle-orm/migrator` records and therefore what the database holds.
        hash: createHash("sha256").update(sql).digest("hex"),
      },
    ]);
  });
});

describe("the migrations this repository ships", () => {
  test("reach a database that has never been migrated", async () => {
    const folder = await readMigrationFolder(
      new URL("../drizzle/", import.meta.url).pathname,
    );

    expect(migrationsOutOfReach(folder, [])).toEqual([]);
  });

  test("reach a database that is up to date with them", async () => {
    const folder = await readMigrationFolder(
      new URL("../drizzle/", import.meta.url).pathname,
    );

    expect(
      migrationsOutOfReach(
        folder,
        folder.map((entry) => applied(entry.hash, entry.when)),
      ),
    ).toEqual([]);
  });

  test("do not reach a database that ran the arcade branch before it was merged", async () => {
    /*
     * The incident, pinned, because it is the only shape of this failure anybody has actually met.
     *
     * Before the merge, the arcade work shipped as `0053_adorable_frank_castle` (1791773482676) and
     * `0054_spicy_wallflower` (1791774497487). The merge renumbered it to `0057_arcade_provider`
     * (1791908858814, since squashed and restamped) and put main's `0053_identity_links` (1791547580808) in its place — a stamp
     * OLDER than what such a database had already recorded. Everything up to `0052` is byte for
     * byte the same file on both sides of the merge, so those rows are built from this folder.
     *
     * The expected answer is one name, and it is the migration whose two tables were missing from
     * the reproduction: `identity_links` and `identity_link_challenges`.
     */
    const folder = await readMigrationFolder(
      new URL("../drizzle/", import.meta.url).pathname,
    );
    const asShipped = [
      ...folder
        .filter((entry) => entry.when <= 1791396757748)
        .map((entry) => applied(entry.hash, entry.when)),
      applied("0053_adorable_frank_castle", 1791773482676),
      applied("0054_spicy_wallflower", 1791774497487),
    ];

    expect(
      migrationsOutOfReach(folder, asShipped).map((entry) => entry.tag),
    ).toEqual(["0053_identity_links"]);
  });
});