@workglow/test-contract 0.6.1

package/dist/tabular-migrations/assertions/freshDbFastPath.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { TabularMigrationContractHandle, TabularMigrationContractOpts } from "../types";
+export declare function freshDbFastPathBlock(opts: TabularMigrationContractOpts, getHandle: () => TabularMigrationContractHandle): void;

package/dist/tabular-migrations/assertions/incrementalApplication.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { TabularMigrationContractHandle, TabularMigrationContractOpts } from "../types";
+export declare function incrementalApplicationBlock(_opts: TabularMigrationContractOpts, getHandle: () => TabularMigrationContractHandle): void;

package/dist/tabular-migrations/assertions/renameColumn.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { TabularMigrationContractHandle, TabularMigrationContractOpts } from "../types";
+export declare function renameColumnBlock(_opts: TabularMigrationContractOpts, getHandle: () => TabularMigrationContractHandle): void;

package/dist/tabular-migrations/runTabularMigrationContract.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { TabularMigrationContractOpts } from "./types";
+export declare function runTabularMigrationContract(opts: TabularMigrationContractOpts): void;
+export type { TabularMigrationContractHandle, TabularMigrationContractOpts } from "./types";

package/dist/tabular-migrations/types.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { AnyTabularStorage, ITabularMigration } from "@workglow/storage";
+export interface TabularMigrationContractHandle {
+    /**
+     * Build a fresh storage at the given target schema, with the supplied
+     * migrations and an optional pre-populated set of rows. Calls
+     * `setupDatabase` before returning.
+     *
+     * The schema's properties at minimum include `id: string` (PK) plus
+     * whatever extra columns the test's migration ops mention.
+     */
+    makeStorage(properties: Record<string, unknown>, migrations: ReadonlyArray<ITabularMigration>, preExistingRows?: ReadonlyArray<Record<string, unknown>>): Promise<AnyTabularStorage>;
+    dispose(): Promise<void>;
+}
+export interface TabularMigrationContractOpts {
+    readonly name: string;
+    readonly factory: () => Promise<TabularMigrationContractHandle>;
+    readonly skip?: boolean;
+    readonly timeout?: number;
+    /** True for SQL backends: DDL is enforced; addColumn produces a real column. */
+    readonly enforcesDdl: boolean;
+    /** True for FsFolder, IDB, SQLite-on-disk: bookkeeping survives restart. */
+    readonly persistentBookkeeping?: boolean;
+}

package/dist/tabular-migrations.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Conformance suite for tabular schema migrations — add, drop, rename and
+ * backfill against a live table.
+ */
+export * from "./tabular-migrations/runTabularMigrationContract";
+export * from "./tabular-migrations/types";
+export * from "./tabular-migrations/assertions/addAndDropIndex";
+export * from "./tabular-migrations/assertions/addColumn";
+export * from "./tabular-migrations/assertions/backfill";
+export * from "./tabular-migrations/assertions/dropColumn";
+export * from "./tabular-migrations/assertions/failedMigrationNotRecorded";
+export * from "./tabular-migrations/assertions/freshDbFastPath";
+export * from "./tabular-migrations/assertions/incrementalApplication";
+export * from "./tabular-migrations/assertions/renameColumn";

package/dist/tabular-migrations.js

@@ -0,0 +1,257 @@
+// src/tabular-migrations/runTabularMigrationContract.ts
+import { afterAll, beforeAll, describe } from "vitest";
+
+// src/tabular-migrations/assertions/addAndDropIndex.ts
+import { expect, it } from "vitest";
+function addAndDropIndexBlock(_opts, getHandle) {
+  it("addIndex / dropIndex: query still returns correct rows", async () => {
+    const storage = await getHandle().makeStorage({ id: { type: "string" }, name: { type: "string" } }, [
+      {
+        version: 1,
+        ops: [
+          { kind: "addIndex", name: "idx_name", columns: ["name"] },
+          { kind: "dropIndex", name: "idx_name" }
+        ]
+      }
+    ], [
+      { id: "u1", name: "alice" },
+      { id: "u2", name: "bob" }
+    ]);
+    const rows = await storage.query({ name: "alice" }) ?? [];
+    expect(rows.map((r) => r.id)).toEqual(["u1"]);
+  });
+}
+
+// src/tabular-migrations/assertions/addColumn.ts
+import { expect as expect2, it as it2 } from "vitest";
+function addColumnBlock(_opts, getHandle) {
+  it2("addColumn: existing rows survive; new column readable", async () => {
+    const storage = await getHandle().makeStorage({
+      id: { type: "string" },
+      name: { type: "string" },
+      archived: { anyOf: [{ type: "boolean" }, { type: "null" }] }
+    }, [
+      {
+        version: 1,
+        ops: [
+          {
+            kind: "addColumn",
+            name: "archived",
+            schema: { anyOf: [{ type: "boolean" }, { type: "null" }] }
+          }
+        ]
+      }
+    ], [{ id: "u1", name: "alice" }]);
+    const row = await storage.get({ id: "u1" });
+    expect2(row).toBeDefined();
+    expect2(row.id).toBe("u1");
+    expect2(row.archived ?? null).toBeNull();
+  });
+}
+
+// src/tabular-migrations/assertions/backfill.ts
+import { expect as expect3, it as it3 } from "vitest";
+function backfillBlock(_opts, getHandle) {
+  it3("backfill: every existing row is rewritten", async () => {
+    const rows = Array.from({ length: 30 }, (_, i) => ({ id: `r${i}`, n: i }));
+    const storage = await getHandle().makeStorage({ id: { type: "string" }, n: { type: "integer" } }, [
+      {
+        version: 1,
+        ops: [
+          {
+            kind: "backfill",
+            batchSize: 7,
+            transform: (row) => ({ ...row, n: row.n * 2 })
+          }
+        ]
+      }
+    ], rows);
+    const all = await storage.getAll() ?? [];
+    const r3 = all.find((r) => r.id === "r3");
+    expect3(r3).toBeDefined();
+    expect3(r3.n).toBe(6);
+    expect3(all.length).toBe(30);
+  });
+}
+
+// src/tabular-migrations/assertions/dropColumn.ts
+import { expect as expect4, it as it4 } from "vitest";
+function dropColumnBlock(_opts, getHandle) {
+  it4("dropColumn: column removed; existing rows preserved (sans column)", async () => {
+    const storage = await getHandle().makeStorage({ id: { type: "string" }, name: { type: "string" } }, [
+      {
+        version: 1,
+        ops: [{ kind: "dropColumn", name: "removed_field" }]
+      }
+    ], [{ id: "u1", name: "alice", removed_field: "old" }]);
+    const row = await storage.get({ id: "u1" });
+    expect4(row).toBeDefined();
+    expect4(row.name).toBe("alice");
+    expect4(row.removed_field).toBeUndefined();
+  });
+}
+
+// src/tabular-migrations/assertions/failedMigrationNotRecorded.ts
+import { expect as expect5, it as it5 } from "vitest";
+function failedMigrationNotRecordedBlock(_opts, getHandle) {
+  it5("a failed migration is not recorded; subsequent run can succeed", async () => {
+    let failOnFirst = true;
+    const migrations = [
+      {
+        version: 1,
+        ops: [
+          {
+            kind: "backfill",
+            transform: (row) => {
+              if (failOnFirst) {
+                failOnFirst = false;
+                throw new Error("boom");
+              }
+              return row;
+            }
+          }
+        ]
+      }
+    ];
+    await expect5(getHandle().makeStorage({ id: { type: "string" } }, migrations, [{ id: "u1" }])).rejects.toThrow(/boom/);
+    const storage = await getHandle().makeStorage({ id: { type: "string" } }, migrations, [
+      { id: "u1" }
+    ]);
+    expect5(await storage.size()).toBe(1);
+  });
+}
+
+// src/tabular-migrations/assertions/freshDbFastPath.ts
+import { expect as expect6, it as it6 } from "vitest";
+function freshDbFastPathBlock(opts, getHandle) {
+  it6("fresh DB: backfill is NOT executed; bookkeeping marks all applied", async () => {
+    let transformCalls = 0;
+    const storage = await getHandle().makeStorage({ id: { type: "string" }, n: { type: "integer" } }, [
+      {
+        version: 1,
+        ops: [
+          {
+            kind: "backfill",
+            transform: (row) => {
+              transformCalls++;
+              return row;
+            }
+          }
+        ]
+      }
+    ], []);
+    expect6(transformCalls).toBe(0);
+    expect6(await storage.size()).toBe(0);
+  });
+  if (opts.enforcesDdl) {
+    it6("fresh DB: addColumn against target-schema does NOT execute (fast path)", async () => {
+      const storage = await getHandle().makeStorage({
+        id: { type: "string" },
+        name: { type: "string" },
+        archived: { anyOf: [{ type: "boolean" }, { type: "null" }] }
+      }, [
+        {
+          version: 1,
+          ops: [
+            {
+              kind: "addColumn",
+              name: "archived",
+              schema: { anyOf: [{ type: "boolean" }, { type: "null" }] }
+            }
+          ]
+        }
+      ], []);
+      expect6(await storage.size()).toBe(0);
+    });
+  }
+}
+
+// src/tabular-migrations/assertions/incrementalApplication.ts
+import { expect as expect7, it as it7 } from "vitest";
+function incrementalApplicationBlock(_opts, getHandle) {
+  it7("running migrations twice is idempotent (each version applied once)", async () => {
+    let backfillCalls = 0;
+    const migrations = [
+      {
+        version: 1,
+        ops: [
+          {
+            kind: "backfill",
+            transform: (row) => {
+              backfillCalls++;
+              return row;
+            }
+          }
+        ]
+      }
+    ];
+    await getHandle().makeStorage({ id: { type: "string" }, n: { type: "integer" } }, migrations, [
+      { id: "r1", n: 1 }
+    ]);
+    const firstCount = backfillCalls;
+    await getHandle().makeStorage({ id: { type: "string" }, n: { type: "integer" } }, migrations, [
+      { id: "r1", n: 1 }
+    ]);
+    expect7(backfillCalls).toBe(firstCount);
+  });
+}
+
+// src/tabular-migrations/assertions/renameColumn.ts
+import { expect as expect8, it as it8 } from "vitest";
+function renameColumnBlock(_opts, getHandle) {
+  it8("renameColumn: data preserved under new name", async () => {
+    const storage = await getHandle().makeStorage({ id: { type: "string" }, state: { type: "string" } }, [
+      {
+        version: 1,
+        ops: [{ kind: "renameColumn", from: "status", to: "state" }]
+      }
+    ], [{ id: "u1", status: "active" }]);
+    const row = await storage.get({ id: "u1" });
+    expect8(row).toBeDefined();
+    expect8(row.state).toBe("active");
+  });
+}
+
+// src/tabular-migrations/runTabularMigrationContract.ts
+function runTabularMigrationContract(opts) {
+  describe.skipIf(opts.skip)(`Tabular migration contract: ${opts.name}`, () => {
+    let handle;
+    const getHandle = () => {
+      if (!handle)
+        throw new Error("handle not initialized");
+      return handle;
+    };
+    beforeAll(async () => {
+      handle = await opts.factory();
+    }, opts.timeout);
+    afterAll(async () => {
+      if (handle)
+        await handle.dispose();
+    });
+    if (opts.enforcesDdl) {
+      addColumnBlock(opts, getHandle);
+      dropColumnBlock(opts, getHandle);
+      renameColumnBlock(opts, getHandle);
+      addAndDropIndexBlock(opts, getHandle);
+    }
+    backfillBlock(opts, getHandle);
+    freshDbFastPathBlock(opts, getHandle);
+    if (opts.persistentBookkeeping !== false) {
+      incrementalApplicationBlock(opts, getHandle);
+      failedMigrationNotRecordedBlock(opts, getHandle);
+    }
+  });
+}
+export {
+  addAndDropIndexBlock,
+  addColumnBlock,
+  backfillBlock,
+  dropColumnBlock,
+  failedMigrationNotRecordedBlock,
+  freshDbFastPathBlock,
+  incrementalApplicationBlock,
+  renameColumnBlock,
+  runTabularMigrationContract
+};
+
+//# debugId=FAE6293E721A4E2664756E2164756E21

package/dist/tabular-migrations.js.map

@@ -0,0 +1,18 @@
+{
+  "version": 3,
+  "sources": ["../src/tabular-migrations/runTabularMigrationContract.ts", "../src/tabular-migrations/assertions/addAndDropIndex.ts", "../src/tabular-migrations/assertions/addColumn.ts", "../src/tabular-migrations/assertions/backfill.ts", "../src/tabular-migrations/assertions/dropColumn.ts", "../src/tabular-migrations/assertions/failedMigrationNotRecorded.ts", "../src/tabular-migrations/assertions/freshDbFastPath.ts", "../src/tabular-migrations/assertions/incrementalApplication.ts", "../src/tabular-migrations/assertions/renameColumn.ts"],
+  "sourcesContent": [
+    "/**\n * @license\n * Copyright 2026 Steven Roussey <sroussey@gmail.com>\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport { afterAll, beforeAll, describe } from \"vitest\";\n\nimport { addAndDropIndexBlock } from \"./assertions/addAndDropIndex\";\nimport { addColumnBlock } from \"./assertions/addColumn\";\nimport { backfillBlock } from \"./assertions/backfill\";\nimport { dropColumnBlock } from \"./assertions/dropColumn\";\nimport { failedMigrationNotRecordedBlock } from \"./assertions/failedMigrationNotRecorded\";\nimport { freshDbFastPathBlock } from \"./assertions/freshDbFastPath\";\nimport { incrementalApplicationBlock } from \"./assertions/incrementalApplication\";\nimport { renameColumnBlock } from \"./assertions/renameColumn\";\nimport type { TabularMigrationContractHandle, TabularMigrationContractOpts } from \"./types\";\n\nexport function runTabularMigrationContract(opts: TabularMigrationContractOpts): void {\n  describe.skipIf(opts.skip)(`Tabular migration contract: ${opts.name}`, () => {\n    let handle: TabularMigrationContractHandle | undefined;\n    const getHandle = (): TabularMigrationContractHandle => {\n      if (!handle) throw new Error(\"handle not initialized\");\n      return handle;\n    };\n\n    beforeAll(async () => {\n      handle = await opts.factory();\n    }, opts.timeout);\n    afterAll(async () => {\n      if (handle) await handle.dispose();\n    });\n\n    if (opts.enforcesDdl) {\n      addColumnBlock(opts, getHandle);\n      dropColumnBlock(opts, getHandle);\n      renameColumnBlock(opts, getHandle);\n      addAndDropIndexBlock(opts, getHandle);\n    }\n    backfillBlock(opts, getHandle);\n    freshDbFastPathBlock(opts, getHandle);\n    if (opts.persistentBookkeeping !== false) {\n      incrementalApplicationBlock(opts, getHandle);\n      failedMigrationNotRecordedBlock(opts, getHandle);\n    }\n  });\n}\n\nexport type { TabularMigrationContractHandle, TabularMigrationContractOpts } from \"./types\";\n",
+    "/**\n * @license\n * Copyright 2026 Steven Roussey <sroussey@gmail.com>\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport { expect, it } from \"vitest\";\nimport type { TabularMigrationContractHandle, TabularMigrationContractOpts } from \"../types\";\n\nexport function addAndDropIndexBlock(\n  _opts: TabularMigrationContractOpts,\n  getHandle: () => TabularMigrationContractHandle\n): void {\n  it(\"addIndex / dropIndex: query still returns correct rows\", async () => {\n    const storage = await getHandle().makeStorage(\n      { id: { type: \"string\" }, name: { type: \"string\" } },\n      [\n        {\n          version: 1,\n          ops: [\n            { kind: \"addIndex\", name: \"idx_name\", columns: [\"name\"] },\n            { kind: \"dropIndex\", name: \"idx_name\" },\n          ],\n        },\n      ],\n      [\n        { id: \"u1\", name: \"alice\" },\n        { id: \"u2\", name: \"bob\" },\n      ]\n    );\n    const rows = (await storage.query({ name: \"alice\" })) ?? [];\n    expect(rows.map((r) => (r as { id: string }).id)).toEqual([\"u1\"]);\n  });\n}\n",
+    "/**\n * @license\n * Copyright 2026 Steven Roussey <sroussey@gmail.com>\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport { expect, it } from \"vitest\";\nimport type { TabularMigrationContractHandle, TabularMigrationContractOpts } from \"../types\";\n\nexport function addColumnBlock(\n  _opts: TabularMigrationContractOpts,\n  getHandle: () => TabularMigrationContractHandle\n): void {\n  it(\"addColumn: existing rows survive; new column readable\", async () => {\n    const storage = await getHandle().makeStorage(\n      {\n        id: { type: \"string\" },\n        name: { type: \"string\" },\n        archived: { anyOf: [{ type: \"boolean\" }, { type: \"null\" }] },\n      },\n      [\n        {\n          version: 1,\n          ops: [\n            {\n              kind: \"addColumn\",\n              name: \"archived\",\n              schema: { anyOf: [{ type: \"boolean\" }, { type: \"null\" }] },\n            },\n          ],\n        },\n      ],\n      [{ id: \"u1\", name: \"alice\" }]\n    );\n    const row = (await storage.get({ id: \"u1\" })) as\n      | { id: string; name: string; archived?: boolean | null }\n      | undefined;\n    expect(row).toBeDefined();\n    expect(row!.id).toBe(\"u1\");\n    expect(row!.archived ?? null).toBeNull();\n  });\n}\n",
+    "/**\n * @license\n * Copyright 2026 Steven Roussey <sroussey@gmail.com>\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport { expect, it } from \"vitest\";\nimport type { TabularMigrationContractHandle, TabularMigrationContractOpts } from \"../types\";\n\nexport function backfillBlock(\n  _opts: TabularMigrationContractOpts,\n  getHandle: () => TabularMigrationContractHandle\n): void {\n  it(\"backfill: every existing row is rewritten\", async () => {\n    const rows = Array.from({ length: 30 }, (_, i) => ({ id: `r${i}`, n: i }));\n    const storage = await getHandle().makeStorage(\n      { id: { type: \"string\" }, n: { type: \"integer\" } },\n      [\n        {\n          version: 1,\n          ops: [\n            {\n              kind: \"backfill\",\n              batchSize: 7,\n              transform: (row) => ({ ...row, n: (row.n as number) * 2 }),\n            },\n          ],\n        },\n      ],\n      rows\n    );\n    const all = (await storage.getAll()) ?? [];\n    const r3 = all.find((r) => (r as { id: string }).id === \"r3\") as { n: number } | undefined;\n    expect(r3).toBeDefined();\n    expect(r3!.n).toBe(6);\n    expect(all.length).toBe(30);\n  });\n}\n",
+    "/**\n * @license\n * Copyright 2026 Steven Roussey <sroussey@gmail.com>\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport { expect, it } from \"vitest\";\nimport type { TabularMigrationContractHandle, TabularMigrationContractOpts } from \"../types\";\n\nexport function dropColumnBlock(\n  _opts: TabularMigrationContractOpts,\n  getHandle: () => TabularMigrationContractHandle\n): void {\n  it(\"dropColumn: column removed; existing rows preserved (sans column)\", async () => {\n    const storage = await getHandle().makeStorage(\n      { id: { type: \"string\" }, name: { type: \"string\" } },\n      [\n        {\n          version: 1,\n          ops: [{ kind: \"dropColumn\", name: \"removed_field\" }],\n        },\n      ],\n      [{ id: \"u1\", name: \"alice\", removed_field: \"old\" }]\n    );\n    const row = (await storage.get({ id: \"u1\" })) as\n      | { id: string; name: string; removed_field?: string }\n      | undefined;\n    expect(row).toBeDefined();\n    expect(row!.name).toBe(\"alice\");\n    expect((row as Record<string, unknown>).removed_field).toBeUndefined();\n  });\n}\n",
+    "/**\n * @license\n * Copyright 2026 Steven Roussey <sroussey@gmail.com>\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport { expect, it } from \"vitest\";\nimport type { TabularMigrationContractHandle, TabularMigrationContractOpts } from \"../types\";\n\nexport function failedMigrationNotRecordedBlock(\n  _opts: TabularMigrationContractOpts,\n  getHandle: () => TabularMigrationContractHandle\n): void {\n  it(\"a failed migration is not recorded; subsequent run can succeed\", async () => {\n    let failOnFirst = true;\n    const migrations = [\n      {\n        version: 1,\n        ops: [\n          {\n            kind: \"backfill\" as const,\n            transform: (row: Record<string, unknown>) => {\n              if (failOnFirst) {\n                failOnFirst = false;\n                throw new Error(\"boom\");\n              }\n              return row;\n            },\n          },\n        ],\n      },\n    ];\n    await expect(\n      getHandle().makeStorage({ id: { type: \"string\" } }, migrations, [{ id: \"u1\" }])\n    ).rejects.toThrow(/boom/);\n\n    const storage = await getHandle().makeStorage({ id: { type: \"string\" } }, migrations, [\n      { id: \"u1\" },\n    ]);\n    expect(await storage.size()).toBe(1);\n  });\n}\n",
+    "/**\n * @license\n * Copyright 2026 Steven Roussey <sroussey@gmail.com>\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport { expect, it } from \"vitest\";\nimport type { TabularMigrationContractHandle, TabularMigrationContractOpts } from \"../types\";\n\nexport function freshDbFastPathBlock(\n  opts: TabularMigrationContractOpts,\n  getHandle: () => TabularMigrationContractHandle\n): void {\n  it(\"fresh DB: backfill is NOT executed; bookkeeping marks all applied\", async () => {\n    let transformCalls = 0;\n    const storage = await getHandle().makeStorage(\n      { id: { type: \"string\" }, n: { type: \"integer\" } },\n      [\n        {\n          version: 1,\n          ops: [\n            {\n              kind: \"backfill\",\n              transform: (row) => {\n                transformCalls++;\n                return row;\n              },\n            },\n          ],\n        },\n      ],\n      [] // no pre-existing rows -> fresh DB\n    );\n    expect(transformCalls).toBe(0);\n    expect(await storage.size()).toBe(0);\n  });\n\n  // Regression test for the fresh-DB fast path on SQL backends. If the\n  // orchestrator's freshTable signal is wired up correctly, addColumn for\n  // a column that already exists in the target schema must NOT run as a\n  // real ALTER TABLE — which would throw \"duplicate column\" — because\n  // the migration is recorded as already-applied without executing ops.\n  // Only meaningful on backends that enforce DDL (i.e. SQL ones).\n  if (opts.enforcesDdl) {\n    it(\"fresh DB: addColumn against target-schema does NOT execute (fast path)\", async () => {\n      // The target schema already includes `archived`. A v1 migration that\n      // would `ALTER TABLE … ADD COLUMN archived` should be marked applied\n      // without running on a brand-new DB.\n      const storage = await getHandle().makeStorage(\n        {\n          id: { type: \"string\" },\n          name: { type: \"string\" },\n          archived: { anyOf: [{ type: \"boolean\" }, { type: \"null\" }] },\n        },\n        [\n          {\n            version: 1,\n            ops: [\n              {\n                kind: \"addColumn\",\n                name: \"archived\",\n                schema: { anyOf: [{ type: \"boolean\" }, { type: \"null\" }] },\n              },\n            ],\n          },\n        ],\n        [] // no pre-existing rows -> fresh DB\n      );\n      // If the fast path is broken, makeStorage above throws on the\n      // duplicate-column error and we never reach here. Reaching this\n      // assertion is itself the proof.\n      expect(await storage.size()).toBe(0);\n    });\n  }\n}\n",
+    "/**\n * @license\n * Copyright 2026 Steven Roussey <sroussey@gmail.com>\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport { expect, it } from \"vitest\";\nimport type { TabularMigrationContractHandle, TabularMigrationContractOpts } from \"../types\";\n\nexport function incrementalApplicationBlock(\n  _opts: TabularMigrationContractOpts,\n  getHandle: () => TabularMigrationContractHandle\n): void {\n  it(\"running migrations twice is idempotent (each version applied once)\", async () => {\n    let backfillCalls = 0;\n    const migrations = [\n      {\n        version: 1,\n        ops: [\n          {\n            kind: \"backfill\" as const,\n            transform: (row: Record<string, unknown>) => {\n              backfillCalls++;\n              return row;\n            },\n          },\n        ],\n      },\n    ];\n    await getHandle().makeStorage({ id: { type: \"string\" }, n: { type: \"integer\" } }, migrations, [\n      { id: \"r1\", n: 1 },\n    ]);\n    const firstCount = backfillCalls;\n    await getHandle().makeStorage({ id: { type: \"string\" }, n: { type: \"integer\" } }, migrations, [\n      { id: \"r1\", n: 1 },\n    ]);\n    expect(backfillCalls).toBe(firstCount);\n  });\n}\n",
+    "/**\n * @license\n * Copyright 2026 Steven Roussey <sroussey@gmail.com>\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport { expect, it } from \"vitest\";\nimport type { TabularMigrationContractHandle, TabularMigrationContractOpts } from \"../types\";\n\nexport function renameColumnBlock(\n  _opts: TabularMigrationContractOpts,\n  getHandle: () => TabularMigrationContractHandle\n): void {\n  it(\"renameColumn: data preserved under new name\", async () => {\n    const storage = await getHandle().makeStorage(\n      { id: { type: \"string\" }, state: { type: \"string\" } },\n      [\n        {\n          version: 1,\n          ops: [{ kind: \"renameColumn\", from: \"status\", to: \"state\" }],\n        },\n      ],\n      [{ id: \"u1\", status: \"active\" }]\n    );\n    const row = (await storage.get({ id: \"u1\" })) as { id: string; state: string } | undefined;\n    expect(row).toBeDefined();\n    expect(row!.state).toBe(\"active\");\n  });\n}\n"
+  ],
+  "mappings": "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",
+  "debugId": "FAE6293E721A4E2664756E2164756E21",
+  "names": []
+}

package/dist/tabular-storage/assertions/countMatchesQuery.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { TabularStorageContractOpts } from "../types";
+export declare function countMatchesQueryBlock(opts: TabularStorageContractOpts): void;

package/dist/tabular-storage/assertions/guardParity.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { TabularStorageContractOpts } from "../types";
+/**
+ * A guard on a public method is a guard on the transaction path.
+ *
+ * It was not always. `withTransaction` used to hand its callback a Proxy that
+ * resolved `tx.foo(...)` to `_fooInternal(...)` by name, skipping the public
+ * method, so a check written on `foo` was silently absent from `tx.foo`. That
+ * cost three fixes — `tx.deleteSearch({})` turning from a no-op into a `DELETE
+ * FROM t WHERE` syntax error and criteria excluding nothing into a truncated
+ * table; `tx.updateWhere` rewriting a row's identity where the same call
+ * outside a transaction threw; `tx.getBulk([])` reaching DuckDB as `IN ()` —
+ * and each could only restate the guard in the private method.
+ *
+ * `createTxView` now leaves the public methods in place and neutralizes only
+ * the mutex, so `tx.foo(args)` runs `foo`. Parity is a property of the routing
+ * rather than of anyone's diligence, and this block is what says so out loud:
+ * every guard below is written once, on the public method, and asserted on both
+ * paths, over a set of methods derived from the object rather than written down.
+ */
+export declare function guardParityBlock(opts: TabularStorageContractOpts): void;

package/dist/tabular-storage/assertions/inListCriterion.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { TabularStorageContractOpts } from "../types";
+/**
+ * The `{ operator: "in" }` criterion, which every backend renders differently —
+ * expanded placeholders on SQLite/DuckDB, a single `= ANY($n)` array parameter
+ * on Postgres, a PostgREST `in.()` filter on Supabase, and an in-memory
+ * membership test elsewhere. That divergence is exactly why the semantics are
+ * pinned here rather than per backend.
+ */
+export declare function inListCriterionBlock(opts: TabularStorageContractOpts): void;

package/dist/tabular-storage/assertions/joinBoundedLeftRead.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { AuthorStorage, PostStorage } from "../joinFixtures";
+/**
+ * What the hash join reads off the left side, and when it is allowed to stop.
+ *
+ * `join`'s own docstring makes a promise with a condition attached: `limit` and
+ * `offset` apply to the joined rows, and the fallback "bounds the left read —
+ * and stops early — only when the joined order does not need a sort", meaning
+ * `orderBy` is absent or names left columns the left query can serve. An
+ * `orderBy` touching the right side is sorted in memory, and that sort needs
+ * every joined row, so such a join reads the whole left table however small its
+ * `limit`.
+ *
+ * Both halves matter and they fail in opposite directions. Losing the bound is
+ * a performance cliff a caller cannot see: over a remote backend a `limit: 2`
+ * join quietly puts the whole table on the wire. Applying it when the order is
+ * NOT already final is a wrong answer: the first N left rows in arbitrary order
+ * are sorted afterwards and returned as though they were the top N. Nothing
+ * else in this contract asserts either one — the pushdown is bounded by the
+ * database, so only the fallback can be caught getting this wrong.
+ */
+export declare function joinBoundedLeftReadBlock(createPosts: () => Promise<PostStorage>, createAuthors: () => Promise<AuthorStorage>, seed: (posts: PostStorage, authors: AuthorStorage) => Promise<void>, opts: {
+    readonly expectSqlPushdown?: boolean;
+    readonly timeout?: number;
+}): void;

package/dist/tabular-storage/assertions/joinPushdown.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { TabularStorageContractOpts } from "../types";
+/**
+ * Which path a join takes. A backend that can share a connection handle must
+ * run a same-handle join as one statement — proven by the right side's `query`
+ * never being called — and must fall back to the hash join, which does call
+ * it, when the right side lives elsewhere.
+ */
+export declare function joinPushdownBlock(opts: TabularStorageContractOpts): void;

package/dist/tabular-storage/assertions/notInListCriterion.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { TabularStorageContractOpts } from "../types";
+/**
+ * The `{ operator: "not-in" }` criterion. Pinned here for the same reason its
+ * complement is — `NOT IN (…)` on SQLite/DuckDB, `<> ALL($n)` on Postgres, a
+ * PostgREST `not.in.()` filter on Supabase, a JS predicate elsewhere — plus one
+ * of its own: an exclusion filter that silently matches nothing looks like an
+ * empty result set rather than a bug, so the empty-list and null cases need a
+ * test that says which way they are supposed to fall.
+ */
+export declare function notInListCriterionBlock(opts: TabularStorageContractOpts): void;

package/dist/tabular-storage/assertions/strategyParity.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { AuthorStorage, PostStorage } from "../joinFixtures";
+/**
+ * The two join strategies answer the same question the same way.
+ *
+ * `ITabularStorage.join` has one documented semantics and two implementations —
+ * a single `JOIN` statement when both tables share a connection, and an
+ * application-side hash join otherwise — and which one runs is decided by the
+ * planner, not by the caller. So a caller cannot tell them apart, and any
+ * disagreement between them is a wrong answer that no error reports and that
+ * changes with where the right-hand storage happens to live.
+ *
+ * That has already happened once: a pushdown chosen against a right side
+ * enlisted in a transaction it could not see returned zero rows from an inner
+ * join where the same call through the fallback returned the row. The block
+ * that covered `join` at the time stayed green throughout, because it asserted
+ * which path ran and never compared what the two paths returned.
+ *
+ * This asserts the second thing. It runs only where both strategies are
+ * reachable — a pair the planner pushes down — and compares them over specs
+ * derived from the option space rather than a list, so an option added to
+ * `JoinSpec` is covered by construction.
+ */
+export declare function joinStrategyParityBlock(createPosts: () => Promise<PostStorage>, createAuthors: () => Promise<AuthorStorage>, seed: (posts: PostStorage, authors: AuthorStorage) => Promise<void>, opts: {
+    readonly expectSqlPushdown?: boolean;
+    readonly timeout?: number;
+}): void;

package/dist/tabular-storage/assertions/subscribeToChanges.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { TabularStorageContractOpts } from "../types";
+/**
+ * Subscription contract. Selection between the two blocks below is driven by
+ * `opts.usesPolling`:
+ *
+ *   - `usesPolling: false` → `subscribeToChanges.eventDriven` — strict commit
+ *     order (event-driven subscriptions like Postgres LISTEN/NOTIFY or the
+ *     in-memory broadcast bus emit one event per write, in write order).
+ *   - `usesPolling: true`  → `subscribeToChanges.polling` — set equality plus
+ *     event count (polling-based subscriptions diff a snapshot and have no
+ *     way to preserve commit order).
+ *
+ * When `capabilities.supportsSubscriptions` is true, `usesPolling` is
+ * required on the contract opts; the type guarantees this at compile time.
+ */
+export declare function subscribeToChangesBlock(opts: TabularStorageContractOpts): void;

package/dist/tabular-storage/assertions/vectorColumnFormat.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { TabularStorageContractOpts } from "../types";
+export declare function vectorColumnFormatBlock(opts: TabularStorageContractOpts): void;

package/dist/tabular-storage/assertions/withConnectionTransaction.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { TabularStorageContractOpts } from "../types";
+export declare function withConnectionTransactionBlock(opts: TabularStorageContractOpts): void;

package/dist/tabular-storage/assertions/withTransactionRollback.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { TabularStorageContractOpts } from "../types";
+export declare function withTransactionRollbackBlock(opts: TabularStorageContractOpts): void;

package/dist/tabular-storage/fixtures.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * The row shape every tabular assertion in this contract reads and writes.
+ *
+ * A compound primary key (`name` + `type`) rather than a single column, because
+ * a backend that gets one key right and the pair wrong is the common failure —
+ * cursor encoding, `getBulk` chunking and the join's tuple fingerprint all
+ * behave differently once the key has two parts.
+ */
+export declare const CompoundPrimaryKeyNames: readonly ["name", "type"];
+export declare const CompoundSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly name: {
+            readonly type: "string";
+        };
+        readonly type: {
+            readonly type: "string";
+        };
+        readonly option: {
+            readonly type: "string";
+        };
+        readonly success: {
+            readonly type: "boolean";
+        };
+    };
+    readonly required: readonly ["name", "type", "option", "success"];
+    readonly additionalProperties: false;
+};