@workglow/test-contract 0.6.1

package/dist/tabular-storage.js

@@ -0,0 +1,1477 @@
+// src/tabular-storage/assertions/countMatchesQuery.ts
+import { afterEach, beforeEach, describe, expect, it as it2 } from "vitest";
+
+// src/creditExhaustedSkip.ts
+import { it as vitestIt } from "vitest";
+var BILLING_CODES = new Set([
+  "insufficient_quota",
+  "billing_hard_limit_reached",
+  "insufficient_credits",
+  "insufficient_balance"
+]);
+var CREDIT_MESSAGE = /insufficient credits|not enough credits|no credits remaining|out of credits|insufficient[\s_-]balance|balance is (?:too low|insufficient)|exceeded[\s\S]{0,80}credits|monthly included credits|payment required|exceeded your current quota|check your plan and billing|billing_hard_limit/i;
+var HTTP_402_MESSAGE = /\bHTTP\/?\d?(?:\.\d)?\s*402\b|\bstatus(?:\s*code)?\s*[:=]\s*402\b|\berror code:?\s*402\b|(?:^|:\s+)402\s+[a-z]/im;
+function isCreditExhaustedError(err) {
+  const seen = new Set;
+  let current = err;
+  while (current !== undefined && current !== null && !seen.has(current)) {
+    seen.add(current);
+    if (matchesCreditExhaustion(current))
+      return true;
+    current = causeOf(current);
+  }
+  return false;
+}
+function matchesCreditExhaustion(err) {
+  if (typeof err === "string")
+    return messageLooksLikeCreditExhaustion(err);
+  if (!err || typeof err !== "object")
+    return false;
+  const rec = err;
+  const status = numericStatus(rec);
+  if (status === 402)
+    return true;
+  const code = stringish(rec.code) ?? stringish(nested(rec.error, "code"));
+  const type = stringish(rec.type) ?? stringish(nested(rec.error, "type"));
+  if (code && BILLING_CODES.has(code))
+    return true;
+  if (type && BILLING_CODES.has(type))
+    return true;
+  const message = [
+    stringish(rec.message),
+    stringish(nested(rec.error, "message")),
+    stringifyUnknown(err)
+  ].filter((part) => typeof part === "string").join(`
+`);
+  return messageLooksLikeCreditExhaustion(message);
+}
+function messageLooksLikeCreditExhaustion(message) {
+  return CREDIT_MESSAGE.test(message) || HTTP_402_MESSAGE.test(message);
+}
+function numericStatus(rec) {
+  for (const key of ["status", "statusCode"]) {
+    const value = rec[key];
+    if (typeof value === "number" && Number.isFinite(value))
+      return value;
+  }
+  const nestedStatus = nested(rec.error, "status");
+  if (typeof nestedStatus === "number" && Number.isFinite(nestedStatus))
+    return nestedStatus;
+  return;
+}
+function nested(value, key) {
+  if (!value || typeof value !== "object")
+    return;
+  return value[key];
+}
+function stringish(value) {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function stringifyUnknown(err) {
+  if (err instanceof Error)
+    return err.message;
+  return String(err);
+}
+function causeOf(err) {
+  if (!err || typeof err !== "object")
+    return;
+  return err.cause;
+}
+function creditSkipNote(err) {
+  const message = err instanceof Error ? err.message : String(err);
+  return `skipped: provider out of credits (${message})`;
+}
+var SKIP_OVERRIDE_ENV = "WORKGLOW_CREDIT_EXHAUSTED_SKIP";
+function isTruthyFlag(value) {
+  return !/^(?:0|false|off|no)$/i.test(value.trim());
+}
+function creditExhaustionSkipsTest(env = process.env) {
+  const override = env[SKIP_OVERRIDE_ENV];
+  if (override !== undefined && override.trim() !== "")
+    return isTruthyFlag(override);
+  for (const key of ["CI", "GITHUB_ACTIONS"]) {
+    const value = env[key];
+    if (value !== undefined && value.trim() !== "" && isTruthyFlag(value))
+      return true;
+  }
+  return false;
+}
+function reportLocalCreditFailure(err) {
+  const message = err instanceof Error ? err.message : String(err);
+  console.error(`provider out of credits (${message})
+` + `  Failing because this is not CI. Top the account up, or set ${SKIP_OVERRIDE_ENV}=1 to skip instead.`);
+}
+async function runWithCreditSkip(ctx, fn) {
+  try {
+    return await fn();
+  } catch (err) {
+    if (isCreditExhaustedError(err)) {
+      if (!creditExhaustionSkipsTest()) {
+        reportLocalCreditFailure(err);
+        throw err;
+      }
+      ctx.skip(creditSkipNote(err));
+      return;
+    }
+    throw err;
+  }
+}
+function wrapTestBodyForCreditSkip(fn) {
+  return async function wrapped(...args) {
+    try {
+      return await fn.apply(this, args);
+    } catch (err) {
+      if (!isCreditExhaustedError(err))
+        throw err;
+      if (!creditExhaustionSkipsTest()) {
+        reportLocalCreditFailure(err);
+        throw err;
+      }
+      const ctx = args[0];
+      if (ctx && typeof ctx.skip === "function") {
+        ctx.skip(creditSkipNote(err));
+        return;
+      }
+      console.warn(creditSkipNote(err));
+      return;
+    }
+  };
+}
+function wrapCallable(fn) {
+  return new Proxy(fn, {
+    apply(target, thisArg, argArray) {
+      const wrapped = argArray.map((arg) => typeof arg === "function" ? wrapTestBodyForCreditSkip(arg) : arg);
+      const result = Reflect.apply(target, thisArg, wrapped);
+      return typeof result === "function" ? wrapCallable(result) : result;
+    },
+    get(target, prop, receiver) {
+      const value = Reflect.get(target, prop, receiver);
+      if (typeof value === "function") {
+        return wrapCallable(value.bind(target));
+      }
+      return value;
+    }
+  });
+}
+var it = wrapCallable(vitestIt);
+
+// src/itExpectFail.ts
+var itExpectFail = (name, fn, timeout) => {
+  const native = it.fails;
+  if (typeof native === "function") {
+    native(name, fn, timeout);
+    return;
+  }
+  it(`${name} [expected-fail]`, async () => {
+    let passed = false;
+    try {
+      await fn();
+      passed = true;
+    } catch (err) {
+      if (isCreditExhaustedError(err))
+        throw err;
+    }
+    if (passed) {
+      throw new Error(`Test "${name}" was marked as expected-fail but passed. Remove its name from opts.expectedFailures.`);
+    }
+  }, timeout);
+};
+
+// src/tabular-storage/assertions/countMatchesQuery.ts
+function countMatchesQueryBlock(opts) {
+  const expectFails = new Set(opts.expectedFailures ?? []);
+  const itImpl = expectFails.has("countMatchesQuery") ? itExpectFail : it2;
+  describe.skipIf(!opts.capabilities.supportsQuery)("countMatchesQuery", () => {
+    let storage;
+    beforeEach(async () => {
+      storage = await opts.createStorage();
+      await storage.setupDatabase?.();
+    });
+    afterEach(async () => {
+      await storage.deleteAll();
+      storage.destroy?.();
+      await opts.releaseStorage?.(storage);
+    });
+    itImpl("count(predicate) equals query(predicate).length for every predicate", async () => {
+      const rows = [
+        { name: "a", type: "t", option: "x", success: true },
+        { name: "b", type: "t", option: "x", success: true },
+        { name: "c", type: "t", option: "x", success: true },
+        { name: "d", type: "t", option: "y", success: true },
+        { name: "e", type: "t", option: "y", success: true },
+        { name: "f", type: "t", option: "z", success: true }
+      ];
+      for (const row of rows) {
+        await storage.put(row);
+      }
+      const expected = { x: 3, y: 2, z: 1, missing: 0 };
+      for (const [option, expectedCount] of Object.entries(expected)) {
+        const counted = await storage.count({ option });
+        const queried = await storage.query({ option }) ?? [];
+        expect(counted, `count({option:"${option}"}) disagrees with query({option:"${option}"}).length`).toBe(queried.length);
+        expect(counted).toBe(expectedCount);
+      }
+      const totalCount = await storage.count();
+      const allRows = await storage.getAll() ?? [];
+      expect(totalCount).toBe(allRows.length);
+      expect(totalCount).toBe(rows.length);
+    }, opts.timeout);
+  });
+}
+// src/tabular-storage/assertions/guardParity.ts
+import { afterEach as afterEach2, beforeEach as beforeEach2, describe as describe2, expect as expect2, it as it3 } from "vitest";
+async function outcomeOf(call) {
+  try {
+    await call();
+    return { kind: "returned" };
+  } catch (error) {
+    return {
+      kind: "threw",
+      name: error instanceof Error ? error.constructor.name : typeof error,
+      message: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+var CASES = [
+  {
+    method: "getAll",
+    label: "a limit of zero",
+    run: (t) => t.getAll({ limit: 0 })
+  },
+  {
+    method: "getAll",
+    label: "a negative offset",
+    run: (t) => t.getAll({ offset: -1 })
+  },
+  {
+    method: "getPage",
+    label: "a limit of zero",
+    run: (t) => t.getPage({ limit: 0 })
+  },
+  {
+    method: "count",
+    label: "empty criteria",
+    run: (t) => t.count({})
+  },
+  {
+    method: "query",
+    label: "an operator outside the allow-list",
+    run: (t) => t.query({ name: { operator: "regex", value: "a" } })
+  },
+  {
+    method: "query",
+    label: "a column that is not in the schema",
+    run: (t) => t.query({ nope: "a" })
+  },
+  {
+    method: "query",
+    label: "a list operator whose value is not an array",
+    run: (t) => t.query({ name: { operator: "in", value: "a" } })
+  },
+  {
+    method: "queryPage",
+    label: "empty criteria",
+    run: (t) => t.queryPage({}, { limit: 5 })
+  },
+  {
+    method: "queryIndex",
+    label: "an empty select",
+    run: (t) => t.queryIndex({ name: "a" }, { select: [] })
+  },
+  {
+    method: "queryIndex",
+    label: "a select column that is not in the schema",
+    run: (t) => t.queryIndex({ name: "a" }, { select: ["nope"] })
+  },
+  {
+    method: "deleteSearch",
+    label: "empty criteria",
+    run: (t) => t.deleteSearch({})
+  },
+  {
+    method: "deleteSearch",
+    label: "criteria that exclude nothing",
+    run: (t) => t.deleteSearch({ option: { operator: "not-in", value: [] } })
+  },
+  {
+    method: "updateWhere",
+    label: "a patch that rewrites a primary-key column",
+    run: (t) => t.updateWhere({ name: "guard", type: "parity" }, { name: "moved" })
+  },
+  {
+    method: "join",
+    label: "a join column that is not in the schema",
+    run: (t) => t.join({ type: "inner", on: [{ left: "nope", right: "name" }] }, t)
+  }
+];
+var UNGUARDED = {
+  put: "an entity is coerced against the schema, not rejected by a guard",
+  putBulk: "as `put`",
+  get: "a primary key, and a malformed one reads as a miss on every backend",
+  getBulk: "as `get`",
+  delete: "as `get`",
+  deleteAll: "takes no arguments",
+  size: "takes no arguments",
+  getOffsetPage: "takes two numbers and the SQL backends validate neither"
+};
+function publicNameOf(internal) {
+  const match = /^_(.+)Internal$/.exec(internal);
+  return match?.[1];
+}
+function routedMethods(storage) {
+  const found = new Set;
+  for (let proto = Object.getPrototypeOf(storage);proto !== null && proto !== Object.prototype; proto = Object.getPrototypeOf(proto)) {
+    for (const key of Object.getOwnPropertyNames(proto)) {
+      const name = publicNameOf(key);
+      if (name !== undefined && typeof storage[key] === "function")
+        found.add(name);
+    }
+  }
+  return [...found].sort();
+}
+function guardParityBlock(opts) {
+  const expectFails = new Set(opts.expectedFailures ?? []);
+  const itImpl = expectFails.has("guardParity") ? itExpectFail : it3;
+  describe2.skipIf(!opts.capabilities.supportsTransactions || !opts.capabilities.supportsQuery)("guardParity", () => {
+    let storage;
+    beforeEach2(async () => {
+      storage = await opts.createStorage();
+      await storage.setupDatabase?.();
+      await storage.put({ name: "guard", type: "parity", option: "base", success: true });
+    });
+    afterEach2(async () => {
+      await storage.deleteAll();
+      storage.destroy?.();
+      await opts.releaseStorage?.(storage);
+    });
+    for (const testCase of CASES) {
+      itImpl(`${testCase.method} rejects ${testCase.label} the same way inside a transaction`, async () => {
+        const direct = await outcomeOf(() => testCase.run(storage));
+        let inside;
+        await storage.withTransaction(async (tx) => {
+          inside = await outcomeOf(() => testCase.run(tx));
+        });
+        expect2(inside).toEqual(direct);
+      }, opts.timeout);
+    }
+    itImpl("deleteSearch with empty criteria deletes nothing on either path", async () => {
+      await storage.deleteSearch({});
+      await storage.withTransaction(async (tx) => {
+        await tx.deleteSearch({});
+      });
+      expect2(await storage.get({ name: "guard", type: "parity" })).toBeDefined();
+    }, opts.timeout);
+    itImpl("runs the public method on the transaction path, not only its implementation", async () => {
+      const emitted = [];
+      const listener = (keys) => {
+        emitted.push(keys);
+      };
+      storage.on("getBulk", listener);
+      try {
+        await storage.withTransaction(async (tx) => {
+          await tx.getBulk([{ name: "guard", type: "parity" }]);
+        });
+      } finally {
+        storage.off("getBulk", listener);
+      }
+      expect2(emitted).toEqual([[{ name: "guard", type: "parity" }]]);
+    }, opts.timeout);
+    itImpl("states, for every method with a private implementation, what its guard is", async () => {
+      const covered = new Set(CASES.map((testCase) => testCase.method));
+      const unstated = routedMethods(storage).filter((method) => !covered.has(method) && UNGUARDED[method] === undefined);
+      expect2(unstated).toEqual([]);
+    }, opts.timeout);
+  });
+}
+// src/tabular-storage/assertions/inListCriterion.ts
+import { afterEach as afterEach3, beforeEach as beforeEach3, describe as describe3, expect as expect3, it as it4 } from "vitest";
+function inListCriterionBlock(opts) {
+  const expectFails = new Set(opts.expectedFailures ?? []);
+  const itImpl = expectFails.has("inListCriterion") ? itExpectFail : it4;
+  describe3.skipIf(!opts.capabilities.supportsQuery)("inListCriterion", () => {
+    let storage;
+    const rows = [
+      { name: "a", type: "t", option: "x", success: true },
+      { name: "b", type: "t", option: "y", success: true },
+      { name: "c", type: "t", option: "z", success: false },
+      { name: "d", type: "u", option: "x", success: false }
+    ];
+    beforeEach3(async () => {
+      storage = await opts.createStorage();
+      await storage.setupDatabase?.();
+      for (const row of rows)
+        await storage.put(row);
+    });
+    afterEach3(async () => {
+      await storage.deleteAll();
+      storage.destroy?.();
+      await opts.releaseStorage?.(storage);
+    });
+    const names = (found) => found.map((r) => r.name).sort();
+    itImpl("matches every listed value and nothing else", async () => {
+      const found = await storage.query({ option: { value: ["x", "z"], operator: "in" } }) ?? [];
+      expect3(names(found)).toEqual(["a", "c", "d"]);
+    }, opts.timeout);
+    itImpl("ANDs with the other criteria columns", async () => {
+      const found = await storage.query({ option: { value: ["x", "z"], operator: "in" }, type: "t" }) ?? [];
+      expect3(names(found)).toEqual(["a", "c"]);
+    }, opts.timeout);
+    itImpl("ignores values that match no row, and never duplicates a row for a repeated value", async () => {
+      const found = await storage.query({ option: { value: ["x", "nope", "x"], operator: "in" } }) ?? [];
+      expect3(names(found)).toEqual(["a", "d"]);
+    }, opts.timeout);
+    itImpl("matches nothing for an empty list", async () => {
+      const found = await storage.query({ option: { value: [], operator: "in" } }) ?? [];
+      expect3(found).toEqual([]);
+      expect3(await storage.count({ option: { value: [], operator: "in" } })).toBe(0);
+    }, opts.timeout);
+    itImpl("count agrees with query for an in-list", async () => {
+      const criteria = { option: { value: ["x", "z"], operator: "in" } };
+      const queried = await storage.query(criteria) ?? [];
+      expect3(await storage.count(criteria)).toBe(queried.length);
+    }, opts.timeout);
+    itImpl("deleteSearch removes exactly the listed rows", async () => {
+      await storage.deleteSearch({ option: { value: ["x", "z"], operator: "in" } });
+      const left = await storage.getAll() ?? [];
+      expect3(names(left)).toEqual(["b"]);
+    }, opts.timeout);
+    itImpl("deleteSearch with an empty list deletes nothing", async () => {
+      await storage.deleteSearch({ option: { value: [], operator: "in" } });
+      const left = await storage.getAll() ?? [];
+      expect3(left.length).toBe(rows.length);
+    }, opts.timeout);
+    itImpl("matches on a boolean column", async () => {
+      const found = await storage.query({ success: { value: [false], operator: "in" } }) ?? [];
+      expect3(names(found)).toEqual(["c", "d"]);
+    }, opts.timeout);
+  });
+}
+// src/tabular-storage/assertions/joinBoundedLeftRead.ts
+import { afterEach as afterEach4, beforeEach as beforeEach4, describe as describe4, expect as expect4, it as it5, vi } from "vitest";
+function limitsOf(spy) {
+  return spy.mock.calls.map((call) => call[call.length - 1]?.limit);
+}
+function joinBoundedLeftReadBlock(createPosts, createAuthors, seed, opts) {
+  const on = [{ left: "author_id", right: "id" }];
+  describe4.skipIf(opts.expectSqlPushdown !== false)("join bounded left read", () => {
+    let posts;
+    let authors;
+    beforeEach4(async () => {
+      posts = await createPosts();
+      authors = await createAuthors();
+      await posts.setupDatabase?.();
+      await authors.setupDatabase?.();
+      await seed(posts, authors);
+    });
+    afterEach4(async () => {
+      await posts.deleteAll();
+      await authors.deleteAll();
+      posts.destroy?.();
+      authors.destroy?.();
+      vi.restoreAllMocks();
+    });
+    it5("bounds the left read when no order is asked for", async () => {
+      const leftRead = vi.spyOn(posts, "getAll");
+      const rows = await posts.join({ type: "left", on, limit: 2 }, authors);
+      expect4(rows).toHaveLength(2);
+      expect4(limitsOf(leftRead)).toEqual([2]);
+    }, opts.timeout);
+    it5("bounds the left read when the left query can serve the order", async () => {
+      const leftRead = vi.spyOn(posts, "getAll");
+      const rows = await posts.join({
+        type: "left",
+        on,
+        orderBy: [{ side: "left", column: "views", direction: "DESC" }],
+        limit: 2
+      }, authors);
+      expect4(rows.map((r) => r.left.views)).toEqual([10, 9]);
+      expect4(limitsOf(leftRead)).toEqual([2]);
+    }, opts.timeout);
+    it5("counts offset toward the bound rather than ignoring it", async () => {
+      const leftRead = vi.spyOn(posts, "getAll");
+      const rows = await posts.join({
+        type: "left",
+        on,
+        orderBy: [{ side: "left", column: "views", direction: "DESC" }],
+        offset: 2,
+        limit: 2
+      }, authors);
+      expect4(rows.map((r) => r.left.views)).toEqual([7, 5]);
+      expect4(limitsOf(leftRead)).toEqual([4]);
+    }, opts.timeout);
+    it5("widens the left read when an inner join drops too many rows", async () => {
+      const leftRead = vi.spyOn(posts, "getAll");
+      const rows = await posts.join({ type: "inner", on, limit: 4 }, authors);
+      expect4(rows).toHaveLength(4);
+      const limits = limitsOf(leftRead);
+      expect4(limits.length).toBeGreaterThan(1);
+      expect4(limits[0]).toBe(4);
+      expect4(limits[1]).toBeGreaterThan(4);
+    }, opts.timeout);
+    it5("reads the whole left side when the joined order needs a sort", async () => {
+      const leftRead = vi.spyOn(posts, "getAll");
+      const rows = await posts.join({
+        type: "left",
+        on,
+        orderBy: [
+          { side: "right", column: "name", direction: "ASC" },
+          { side: "left", column: "id", direction: "ASC" }
+        ],
+        limit: 2
+      }, authors);
+      expect4(rows.map((r) => r.left.id)).toEqual(["p4", "p5"]);
+      expect4(limitsOf(leftRead)).toEqual([undefined]);
+    }, opts.timeout);
+    it5("reads the whole left side when the order names a nullable left column", async () => {
+      const leftRead = vi.spyOn(posts, "getAll");
+      const rows = await posts.join({
+        type: "left",
+        on,
+        orderBy: [
+          { side: "left", column: "author_id", direction: "ASC" },
+          { side: "left", column: "id", direction: "ASC" }
+        ],
+        limit: 2
+      }, authors);
+      expect4(rows.map((r) => r.left.id)).toEqual(["p5", "p1"]);
+      expect4(limitsOf(leftRead)).toEqual([undefined]);
+    }, opts.timeout);
+    it5("bounds the filtered left read the same way", async () => {
+      const leftQuery = vi.spyOn(posts, "query");
+      const rows = await posts.join({ type: "left", on, where: { left: { tenant: "t1" } }, limit: 2 }, authors);
+      expect4(rows).toHaveLength(2);
+      expect4(limitsOf(leftQuery)).toEqual([2]);
+    }, opts.timeout);
+  });
+}
+// src/tabular-storage/assertions/joinPushdown.ts
+import { InMemoryTabularStorage } from "@workglow/storage";
+import { afterEach as afterEach5, beforeEach as beforeEach5, describe as describe5, expect as expect5, it as it6, vi as vi2 } from "vitest";
+
+// src/tabular-storage/fixtures.ts
+var CompoundPrimaryKeyNames = ["name", "type"];
+var CompoundSchema = {
+  type: "object",
+  properties: {
+    name: { type: "string" },
+    type: { type: "string" },
+    option: { type: "string" },
+    success: { type: "boolean" }
+  },
+  required: ["name", "type", "option", "success"],
+  additionalProperties: false
+};
+
+// src/tabular-storage/assertions/joinPushdown.ts
+function joinPushdownBlock(opts) {
+  const expectFails = new Set(opts.expectedFailures ?? []);
+  const itImpl = expectFails.has("joinPushdown") ? itExpectFail : it6;
+  describe5.skipIf(!opts.capabilities.supportsQuery || !opts.createSiblingStorage)("joinPushdown", () => {
+    let primary;
+    let sibling;
+    beforeEach5(async () => {
+      primary = await opts.createStorage();
+      await primary.setupDatabase?.();
+      sibling = await opts.createSiblingStorage(primary);
+      await sibling.setupDatabase?.();
+      await primary.putBulk([
+        { name: "a", type: "t", option: "x", success: true },
+        { name: "b", type: "t", option: "y", success: false }
+      ]);
+      await sibling.putBulk([
+        { name: "a", type: "u", option: "p", success: true },
+        { name: "c", type: "u", option: "q", success: true }
+      ]);
+    });
+    afterEach5(async () => {
+      await primary.deleteAll();
+      await sibling.deleteAll();
+      primary.destroy?.();
+      sibling.destroy?.();
+      await opts.releaseStorage?.(primary);
+      await opts.releaseStorage?.(sibling);
+      vi2.restoreAllMocks();
+    });
+    itImpl("runs a same-connection join without querying the right side", async () => {
+      const rightQuery = vi2.spyOn(sibling, "query");
+      const rows = await primary.join({
+        type: "left",
+        on: [{ left: "name", right: "name" }],
+        orderBy: [{ side: "left", column: "name", direction: "ASC" }]
+      }, sibling);
+      expect5(rightQuery).not.toHaveBeenCalled();
+      expect5(rows.map((r) => `${r.left.name}:${r.right?.type ?? "-"}`)).toEqual(["a:u", "b:-"]);
+    }, opts.timeout);
+    itImpl("falls back to the hash join for a right side on another connection", async () => {
+      const elsewhere = new InMemoryTabularStorage(CompoundSchema, CompoundPrimaryKeyNames);
+      await elsewhere.putBulk([{ name: "b", type: "v", option: "z", success: true }]);
+      const rightQuery = vi2.spyOn(elsewhere, "query");
+      const rows = await primary.join({
+        type: "left",
+        on: [{ left: "name", right: "name" }],
+        orderBy: [{ side: "left", column: "name", direction: "ASC" }]
+      }, elsewhere);
+      expect5(rightQuery).toHaveBeenCalled();
+      expect5(rows.map((r) => `${r.left.name}:${r.right?.type ?? "-"}`)).toEqual(["a:-", "b:v"]);
+    }, opts.timeout);
+  });
+}
+// src/tabular-storage/assertions/notInListCriterion.ts
+import { afterEach as afterEach6, beforeEach as beforeEach6, describe as describe6, expect as expect6, it as it7 } from "vitest";
+function notInListCriterionBlock(opts) {
+  const expectFails = new Set(opts.expectedFailures ?? []);
+  const itImpl = expectFails.has("notInListCriterion") ? itExpectFail : it7;
+  describe6.skipIf(!opts.capabilities.supportsQuery)("notInListCriterion", () => {
+    let storage;
+    const rows = [
+      { name: "a", type: "t", option: "x", success: true },
+      { name: "b", type: "t", option: "y", success: true },
+      { name: "c", type: "t", option: "z", success: false },
+      { name: "d", type: "u", option: "x", success: false }
+    ];
+    beforeEach6(async () => {
+      storage = await opts.createStorage();
+      await storage.setupDatabase?.();
+      for (const row of rows)
+        await storage.put(row);
+    });
+    afterEach6(async () => {
+      await storage.deleteAll();
+      storage.destroy?.();
+      await opts.releaseStorage?.(storage);
+    });
+    const names = (found) => found.map((r) => r.name).sort();
+    itImpl("excludes every listed value and keeps the rest", async () => {
+      const found = await storage.query({ option: { value: ["x", "z"], operator: "not-in" } }) ?? [];
+      expect6(names(found)).toEqual(["b"]);
+    }, opts.timeout);
+    itImpl("is the exact complement of the same in-list", async () => {
+      const included = await storage.query({ option: { value: ["x"], operator: "in" } }) ?? [];
+      const excluded = await storage.query({ option: { value: ["x"], operator: "not-in" } }) ?? [];
+      expect6([...names(included), ...names(excluded)].sort()).toEqual(["a", "b", "c", "d"]);
+    }, opts.timeout);
+    itImpl("ANDs with the other criteria columns", async () => {
+      const found = await storage.query({ option: { value: ["x"], operator: "not-in" }, type: "t" }) ?? [];
+      expect6(names(found)).toEqual(["b", "c"]);
+    }, opts.timeout);
+    itImpl("ignores values that match no row, and tolerates a repeated value", async () => {
+      const found = await storage.query({ option: { value: ["x", "nope", "x"], operator: "not-in" } }) ?? [];
+      expect6(names(found)).toEqual(["b", "c"]);
+    }, opts.timeout);
+    itImpl("matches everything for an empty list", async () => {
+      const found = await storage.query({ option: { value: [], operator: "not-in" } }) ?? [];
+      expect6(names(found)).toEqual(["a", "b", "c", "d"]);
+      expect6(await storage.count({ option: { value: [], operator: "not-in" } })).toBe(rows.length);
+    }, opts.timeout);
+    itImpl("count agrees with query for a not-in list", async () => {
+      const criteria = { option: { value: ["x", "z"], operator: "not-in" } };
+      const queried = await storage.query(criteria) ?? [];
+      expect6(await storage.count(criteria)).toBe(queried.length);
+    }, opts.timeout);
+    itImpl("deleteSearch removes exactly the unlisted rows", async () => {
+      await storage.deleteSearch({ option: { value: ["x", "z"], operator: "not-in" } });
+      const left = await storage.getAll() ?? [];
+      expect6(names(left)).toEqual(["a", "c", "d"]);
+    }, opts.timeout);
+    itImpl("deleteSearch refuses criteria that reduce to an empty exclusion", async () => {
+      await expect6(storage.deleteSearch({ option: { value: [], operator: "not-in" } })).rejects.toThrow(/delete the whole table/);
+      const left = await storage.getAll() ?? [];
+      expect6(names(left)).toEqual(["a", "b", "c", "d"]);
+    }, opts.timeout);
+    itImpl("deleteSearch still runs when another column narrows the empty exclusion", async () => {
+      await storage.deleteSearch({
+        type: "u",
+        option: { value: [], operator: "not-in" }
+      });
+      const left = await storage.getAll() ?? [];
+      expect6(names(left)).toEqual(["a", "b", "c"]);
+    }, opts.timeout);
+    itImpl("matches on a boolean column", async () => {
+      const found = await storage.query({ success: { value: [false], operator: "not-in" } }) ?? [];
+      expect6(names(found)).toEqual(["a", "b"]);
+    }, opts.timeout);
+    itImpl("matches nothing when the list contains null", async () => {
+      const found = await storage.query({
+        option: { value: ["x", null], operator: "not-in" }
+      }) ?? [];
+      expect6(found).toEqual([]);
+    }, opts.timeout);
+    describe6.skipIf(!opts.capabilities.supportsTransactions)("through a transaction handle", () => {
+      itImpl("refuses an empty exclusion there too", async () => {
+        await expect6(storage.withTransaction(async (tx) => {
+          await tx.deleteSearch({ option: { value: [], operator: "not-in" } });
+        })).rejects.toThrow(/delete the whole table/);
+        const left = await storage.getAll() ?? [];
+        expect6(names(left)).toEqual(["a", "b", "c", "d"]);
+      }, opts.timeout);
+      itImpl("keeps empty criteria a no-op there too", async () => {
+        await storage.withTransaction(async (tx) => {
+          await tx.deleteSearch({});
+        });
+        const left = await storage.getAll() ?? [];
+        expect6(names(left)).toEqual(["a", "b", "c", "d"]);
+      }, opts.timeout);
+    });
+  });
+}
+// src/tabular-storage/assertions/strategyParity.ts
+import { BaseTabularStorage } from "@workglow/storage";
+import { describe as describe7, expect as expect7, it as it8 } from "vitest";
+var AXES = {
+  type: [
+    { label: "inner", value: "inner" },
+    { label: "left", value: "left" }
+  ],
+  on: [
+    { label: "one key", value: [{ left: "author_id", right: "id" }] },
+    {
+      label: "a compound key",
+      value: [
+        { left: "tenant", right: "tenant" },
+        { left: "author_id", right: "id" }
+      ]
+    }
+  ],
+  where: [
+    { label: "no filter", value: undefined },
+    { label: "a left filter", value: { left: { views: { value: 5, operator: ">" } } } },
+    { label: "a right filter", value: { right: { name: "Ann" } } },
+    { label: "a null right filter", value: { right: { country: null } } },
+    {
+      label: "both filters",
+      value: { left: { tenant: "t1" }, right: { name: "Ann" } }
+    }
+  ],
+  orderBy: [
+    { label: "no order", value: undefined },
+    {
+      label: "a left order",
+      value: [{ side: "left", column: "views", direction: "DESC" }]
+    },
+    {
+      label: "a nullable left order",
+      value: [
+        { side: "left", column: "author_id", direction: "ASC" },
+        { side: "left", column: "id", direction: "ASC" }
+      ]
+    },
+    {
+      label: "a right order",
+      value: [
+        { side: "right", column: "name", direction: "ASC" },
+        { side: "left", column: "id", direction: "ASC" }
+      ]
+    },
+    {
+      label: "a descending right order",
+      value: [
+        { side: "right", column: "name", direction: "DESC" },
+        { side: "left", column: "id", direction: "DESC" }
+      ]
+    }
+  ],
+  limit: [
+    { label: "no limit", value: undefined },
+    { label: "a limit of 2", value: 2 },
+    { label: "a limit of 50", value: 50 }
+  ],
+  offset: [
+    { label: "no offset", value: undefined },
+    { label: "an offset of 1", value: 1 },
+    { label: "an offset past the end", value: 99 }
+  ]
+};
+var BASE = {
+  type: AXES.type[0].value,
+  on: AXES.on[0].value
+};
+function buildSpecs() {
+  const specs = [];
+  const seen = new Set;
+  const add = (label, spec) => {
+    const key = JSON.stringify(spec);
+    if (seen.has(key))
+      return;
+    seen.add(key);
+    specs.push({ label, spec });
+  };
+  for (const key of Object.keys(AXES)) {
+    for (const variant of AXES[key]) {
+      add(variant.label, { ...BASE, [key]: variant.value });
+    }
+  }
+  for (const type of AXES.type) {
+    for (const order of AXES.orderBy) {
+      for (const limit of AXES.limit) {
+        for (const offset of AXES.offset) {
+          add(`${type.label} join, ${order.label}, ${limit.label}, ${offset.label}`, {
+            ...BASE,
+            type: type.value,
+            orderBy: order.value,
+            limit: limit.value,
+            offset: offset.value
+          });
+        }
+      }
+    }
+  }
+  return specs;
+}
+var SPECS = buildSpecs();
+function multisetRemainder(part, whole) {
+  const available = new Map;
+  for (const row of whole)
+    available.set(row, (available.get(row) ?? 0) + 1);
+  const unaccounted = [];
+  for (const row of part) {
+    const left = available.get(row) ?? 0;
+    if (left === 0)
+      unaccounted.push(row);
+    else
+      available.set(row, left - 1);
+  }
+  return unaccounted;
+}
+function windowLength(total, spec) {
+  const remaining = Math.max(0, total - (spec.offset ?? 0));
+  return spec.limit === undefined ? remaining : Math.min(spec.limit, remaining);
+}
+function shape(rows) {
+  return rows.map((row) => `${row.left.id}:${row.right?.id ?? "-"}`);
+}
+function sortRows(rows) {
+  return [...rows].sort((a, b) => `${a.left.id}:${a.right?.id ?? "-"}`.localeCompare(`${b.left.id}:${b.right?.id ?? "-"}`));
+}
+function comparisonFor(spec) {
+  if ((spec.orderBy?.length ?? 0) > 0)
+    return "ordered";
+  return spec.limit === undefined && spec.offset === undefined ? "set" : "window";
+}
+var viaHashJoin = BaseTabularStorage.prototype.join;
+function joinStrategyParityBlock(createPosts, createAuthors, seed, opts) {
+  describe7.skipIf(opts.expectSqlPushdown !== true)("join strategy parity", () => {
+    it8("states, for every field of a join spec, what the two strategies agree about", () => {
+      const empty = Object.keys(AXES).filter((key) => AXES[key].length === 0);
+      expect7(empty).toEqual([]);
+      expect7(SPECS.length).toBeGreaterThan(AXES.orderBy.length * AXES.limit.length);
+    }, opts.timeout);
+    for (const { label, spec } of SPECS) {
+      it8(`the pushdown and the hash join agree on ${label}`, async () => {
+        const posts = await createPosts();
+        const authors = await createAuthors();
+        try {
+          await posts.setupDatabase?.();
+          await authors.setupDatabase?.();
+          await seed(posts, authors);
+          const pushedDown = await posts.join(spec, authors);
+          const hashed = await viaHashJoin.call(posts, spec, authors);
+          switch (comparisonFor(spec)) {
+            case "ordered": {
+              expect7(shape(pushedDown)).toEqual(shape(hashed));
+              expect7(pushedDown).toEqual(hashed);
+              break;
+            }
+            case "set": {
+              expect7(shape(pushedDown).sort()).toEqual(shape(hashed).sort());
+              expect7(sortRows(pushedDown)).toEqual(sortRows(hashed));
+              break;
+            }
+            case "window": {
+              const whole = shape(await posts.join({ ...spec, limit: undefined, offset: undefined }, authors));
+              const expectedLength = windowLength(whole.length, spec);
+              expect7(shape(pushedDown)).toHaveLength(expectedLength);
+              expect7(shape(hashed)).toHaveLength(expectedLength);
+              expect7(multisetRemainder(shape(pushedDown), whole)).toEqual([]);
+              expect7(multisetRemainder(shape(hashed), whole)).toEqual([]);
+              break;
+            }
+          }
+        } finally {
+          await posts.deleteAll();
+          await authors.deleteAll();
+          posts.destroy?.();
+          authors.destroy?.();
+        }
+      }, opts.timeout);
+    }
+  });
+}
+// src/tabular-storage/assertions/subscribeToChanges.ts
+import { sleep } from "@workglow/util";
+import { afterEach as afterEach7, beforeEach as beforeEach7, describe as describe8, expect as expect8, it as it9 } from "vitest";
+function subscribeToChangesBlock(opts) {
+  if (!opts.capabilities.supportsSubscriptions) {
+    describe8.skip("subscribeToChanges", () => {
+      it9("skipped: capabilities.supportsSubscriptions === false", () => {});
+    });
+    return;
+  }
+  const expectFails = new Set(opts.expectedFailures ?? []);
+  const itImpl = expectFails.has("subscribeToChanges") ? itExpectFail : it9;
+  const usesPolling = opts.usesPolling;
+  const pollingIntervalMs = opts.pollingIntervalMs ?? 1;
+  const waitTime = usesPolling ? Math.max(pollingIntervalMs * 8, 200) : 50;
+  const initWaitTime = usesPolling ? Math.max(pollingIntervalMs * 10, 300) : 10;
+  if (usesPolling) {
+    describe8("subscribeToChanges.polling", () => {
+      let storage;
+      beforeEach7(async () => {
+        storage = await opts.createStorage();
+        await storage.setupDatabase?.();
+      });
+      afterEach7(async () => {
+        await storage.deleteAll();
+        storage.destroy?.();
+        await opts.releaseStorage?.(storage);
+      });
+      itImpl("observes every write (set equality + count, order unspecified)", async () => {
+        const changes = [];
+        const unsubscribe = storage.subscribeToChanges((change) => changes.push(change), {
+          pollingIntervalMs
+        });
+        await sleep(initWaitTime);
+        await storage.put({ name: "t1", type: "s1", option: "v1", success: true });
+        await storage.put({ name: "t2", type: "s2", option: "v2", success: false });
+        await storage.put({ name: "t3", type: "s3", option: "v3", success: true });
+        await sleep(waitTime);
+        const writeEvents = changes.filter((c) => c.type === "INSERT" || c.type === "UPDATE");
+        expect8(writeEvents.length).toBe(3);
+        const options = writeEvents.map((e) => e.new?.option).sort((a, b) => String(a).localeCompare(String(b)));
+        expect8(options).toEqual(["v1", "v2", "v3"]);
+        unsubscribe();
+      }, opts.timeout);
+    });
+    return;
+  }
+  describe8("subscribeToChanges.eventDriven", () => {
+    let storage;
+    beforeEach7(async () => {
+      storage = await opts.createStorage();
+      await storage.setupDatabase?.();
+    });
+    afterEach7(async () => {
+      await storage.deleteAll();
+      storage.destroy?.();
+      await opts.releaseStorage?.(storage);
+    });
+    itImpl("fires exactly once per write in commit order", async () => {
+      const changes = [];
+      const unsubscribe = storage.subscribeToChanges((change) => changes.push(change), {
+        pollingIntervalMs
+      });
+      await sleep(initWaitTime);
+      await storage.put({ name: "t1", type: "s1", option: "v1", success: true });
+      await storage.put({ name: "t2", type: "s2", option: "v2", success: false });
+      await storage.put({ name: "t3", type: "s3", option: "v3", success: true });
+      await sleep(waitTime);
+      const writeEvents = changes.filter((c) => c.type === "INSERT" || c.type === "UPDATE");
+      expect8(writeEvents.length).toBe(3);
+      expect8(writeEvents[0].new?.option).toBe("v1");
+      expect8(writeEvents[1].new?.option).toBe("v2");
+      expect8(writeEvents[2].new?.option).toBe("v3");
+      unsubscribe();
+    }, opts.timeout);
+  });
+}
+// src/tabular-storage/assertions/vectorColumnFormat.ts
+import { afterEach as afterEach8, beforeEach as beforeEach8, describe as describe9, expect as expect9, it as it10 } from "vitest";
+function vectorColumnFormatBlock(opts) {
+  const expectFails = new Set(opts.expectedFailures ?? []);
+  const itImpl = expectFails.has("vectorColumnFormat") ? itExpectFail : it10;
+  describe9.skipIf(!opts.capabilities.supportsVectorColumns)("vectorColumnFormat", () => {
+    let storage;
+    beforeEach8(async () => {
+      if (!opts.createVectorStorage) {
+        throw new Error("createVectorStorage is required when capabilities.supportsVectorColumns is true");
+      }
+      storage = await opts.createVectorStorage();
+      await storage.setupDatabase?.();
+    });
+    afterEach8(async () => {
+      await storage.deleteAll();
+      storage.destroy?.();
+      await opts.releaseStorage?.(storage);
+    });
+    itImpl("round-trip preserves Float32Array type and values", async () => {
+      const original = new Float32Array([0.1, 0.2, 0.3]);
+      await storage.put({ id: "v1", embedding: original });
+      const retrieved = await storage.get({ id: "v1" });
+      expect9(retrieved).toBeDefined();
+      const embedding = retrieved?.embedding;
+      expect9(embedding).toBeInstanceOf(Float32Array);
+      expect9(embedding[0]).toBeCloseTo(0.1, 5);
+      expect9(embedding[1]).toBeCloseTo(0.2, 5);
+      expect9(embedding[2]).toBeCloseTo(0.3, 5);
+    }, opts.timeout);
+  });
+}
+// src/tabular-storage/assertions/withConnectionTransaction.ts
+import {
+  ConnectionReentryError,
+  withConnectionTransaction
+} from "@workglow/storage";
+import { afterEach as afterEach9, beforeEach as beforeEach9, describe as describe10, expect as expect10, it as it11 } from "vitest";
+function withConnectionTransactionBlock(opts) {
+  const expectFails = new Set(opts.expectedFailures ?? []);
+  const itImpl = expectFails.has("withConnectionTransaction") ? itExpectFail : it11;
+  describe10.skipIf(!opts.capabilities.supportsTransactions || opts.createSiblingStorage === undefined)("withConnectionTransaction", () => {
+    let primary;
+    let sibling;
+    let outsider;
+    beforeEach9(async () => {
+      primary = await opts.createStorage();
+      await primary.setupDatabase?.();
+      sibling = await opts.createSiblingStorage(primary);
+      await sibling.setupDatabase?.();
+      outsider = await opts.createSiblingStorage(primary);
+      await outsider.setupDatabase?.();
+    });
+    afterEach9(async () => {
+      await outsider?.deleteAll();
+      outsider?.destroy?.();
+      await sibling?.deleteAll();
+      sibling?.destroy?.();
+      await primary?.deleteAll();
+      primary?.destroy?.();
+      await opts.releaseStorage?.(primary);
+    });
+    itImpl("commits writes across two tables", async () => {
+      await withConnectionTransaction([primary, sibling], async () => {
+        await primary.put({ name: "from-a", type: "x", option: "va", success: true });
+        await sibling.put({ name: "from-b", type: "x", option: "vb", success: true });
+      });
+      expect10(await primary.get({ name: "from-a", type: "x" })).toMatchObject({ option: "va" });
+      expect10(await sibling.get({ name: "from-b", type: "x" })).toMatchObject({ option: "vb" });
+    }, opts.timeout);
+    itImpl("rolls back both tables when the callback throws", async () => {
+      await primary.put({ name: "kept", type: "x", option: "base", success: true });
+      await expect10(withConnectionTransaction([primary, sibling], async () => {
+        await primary.put({ name: "from-a", type: "x", option: "va", success: true });
+        await sibling.put({ name: "from-b", type: "x", option: "vb", success: true });
+        throw new Error("forced rollback");
+      })).rejects.toThrow("forced rollback");
+      expect10(await primary.get({ name: "kept", type: "x" })).toBeDefined();
+      expect10(await primary.get({ name: "from-a", type: "x" })).toBeUndefined();
+      expect10(await sibling.get({ name: "from-b", type: "x" })).toBeUndefined();
+    }, opts.timeout);
+    itImpl("does not refuse an unrelated concurrent caller", async () => {
+      let releaseBody = () => {};
+      const bodyCanFinish = new Promise((resolve) => {
+        releaseBody = resolve;
+      });
+      let signalStarted = () => {};
+      const bodyStarted = new Promise((resolve) => {
+        signalStarted = resolve;
+      });
+      const txPromise = withConnectionTransaction([primary, sibling], async () => {
+        await primary.put({ name: "enlisted", type: "x", option: "ok", success: true });
+        signalStarted();
+        await bodyCanFinish;
+      });
+      await bodyStarted;
+      let outsiderError;
+      const concurrent = outsider.put({ name: "concurrent", type: "x", option: "yes", success: true }).catch((err) => {
+        outsiderError = err;
+      });
+      releaseBody();
+      await txPromise;
+      await concurrent;
+      expect10(outsiderError).toBeUndefined();
+      expect10(await outsider.get({ name: "concurrent", type: "x" })).toBeDefined();
+      expect10(await primary.get({ name: "enlisted", type: "x" })).toBeDefined();
+    }, opts.timeout);
+    itImpl("does not refuse a concurrent transaction whose participant set merely differs", async () => {
+      let releaseFirst = () => {};
+      const firstCanFinish = new Promise((resolve) => {
+        releaseFirst = resolve;
+      });
+      let signalStarted = () => {};
+      const firstStarted = new Promise((resolve) => {
+        signalStarted = resolve;
+      });
+      const first = withConnectionTransaction([primary, sibling], async () => {
+        await primary.put({ name: "first", type: "x", option: "one", success: true });
+        signalStarted();
+        await firstCanFinish;
+      });
+      await firstStarted;
+      let secondError;
+      const second = withConnectionTransaction([sibling, outsider], async () => {
+        await outsider.put({ name: "second", type: "x", option: "two", success: true });
+      }).catch((err) => {
+        secondError = err;
+      });
+      releaseFirst();
+      await first;
+      await second;
+      expect10(secondError).toBeUndefined();
+      expect10(await primary.get({ name: "first", type: "x" })).toBeDefined();
+      expect10(await outsider.get({ name: "second", type: "x" })).toBeDefined();
+    }, opts.timeout);
+    itImpl("does not show uncommitted rows to a concurrent reader", async () => {
+      await primary.put({ name: "iso", type: "x", option: "before", success: true });
+      let releaseBody = () => {};
+      const bodyCanFinish = new Promise((resolve) => {
+        releaseBody = resolve;
+      });
+      let signalStarted = () => {};
+      const bodyStarted = new Promise((resolve) => {
+        signalStarted = resolve;
+      });
+      let rollbackError;
+      const txPromise = withConnectionTransaction([primary, sibling], async () => {
+        await primary.put({ name: "iso", type: "x", option: "dirty", success: true });
+        signalStarted();
+        await bodyCanFinish;
+        throw new Error("forced rollback");
+      }).catch((err) => {
+        rollbackError = err;
+      });
+      await bodyStarted;
+      const readPromise = primary.get({ name: "iso", type: "x" });
+      await new Promise((resolve) => setTimeout(resolve, 25));
+      releaseBody();
+      await txPromise;
+      expect10(rollbackError?.message).toBe("forced rollback");
+      expect10(await readPromise).toMatchObject({ option: "before" });
+      expect10(await primary.get({ name: "iso", type: "x" })).toMatchObject({ option: "before" });
+    }, opts.timeout);
+    itImpl("does not show uncommitted rows to a concurrent pushed-down join", async () => {
+      await primary.put({ name: "join-iso", type: "j", option: "before", success: true });
+      await sibling.put({ name: "join-key", type: "j", option: "rhs", success: true });
+      let releaseBody = () => {};
+      const bodyCanFinish = new Promise((resolve) => {
+        releaseBody = resolve;
+      });
+      let signalStarted = () => {};
+      const bodyStarted = new Promise((resolve) => {
+        signalStarted = resolve;
+      });
+      let rollbackError;
+      const txPromise = withConnectionTransaction([primary, sibling], async () => {
+        await primary.put({ name: "join-iso", type: "j", option: "dirty", success: true });
+        signalStarted();
+        await bodyCanFinish;
+        throw new Error("forced rollback");
+      }).catch((err) => {
+        rollbackError = err;
+      });
+      await bodyStarted;
+      const joinPromise = primary.join({ type: "inner", on: [{ left: "type", right: "type" }] }, sibling);
+      await new Promise((resolve) => setTimeout(resolve, 25));
+      releaseBody();
+      await txPromise;
+      expect10(rollbackError?.message).toBe("forced rollback");
+      const rows = await joinPromise;
+      expect10(rows).toHaveLength(1);
+      expect10(rows[0].left).toMatchObject({ name: "join-iso", option: "before" });
+      expect10(rows[0].right).toMatchObject({ name: "join-key", option: "rhs" });
+    }, opts.timeout);
+    itImpl("throws sibling-op for a storage that was not enlisted", async () => {
+      let error;
+      await withConnectionTransaction([primary, sibling], async () => {
+        await primary.put({ name: "enlisted", type: "x", option: "ok", success: true });
+        try {
+          await outsider.put({ name: "outsider", type: "x", option: "no", success: true });
+        } catch (err) {
+          error = err;
+        }
+      });
+      expect10(error).toBeInstanceOf(ConnectionReentryError);
+      expect10(error.mode).toBe("sibling-op");
+      expect10(await outsider.get({ name: "outsider", type: "x" })).toBeUndefined();
+      expect10(await primary.get({ name: "enlisted", type: "x" })).toBeDefined();
+    }, opts.timeout);
+  });
+}
+// src/tabular-storage/assertions/withTransactionRollback.ts
+import { afterEach as afterEach10, beforeEach as beforeEach10, describe as describe11, expect as expect11, it as it12 } from "vitest";
+function withTransactionRollbackBlock(opts) {
+  const expectFails = new Set(opts.expectedFailures ?? []);
+  const itImpl = expectFails.has("withTransactionRollback") ? itExpectFail : it12;
+  describe11.skipIf(!opts.capabilities.supportsTransactions)("withTransactionRollback", () => {
+    let storage;
+    beforeEach10(async () => {
+      storage = await opts.createStorage();
+      await storage.setupDatabase?.();
+    });
+    afterEach10(async () => {
+      await storage.deleteAll();
+      storage.destroy?.();
+      await opts.releaseStorage?.(storage);
+    });
+    itImpl("rolls back writes when callback throws", async () => {
+      const baseline = { name: "before", type: "tx", option: "base", success: true };
+      await storage.put(baseline);
+      await expect11(storage.withTransaction(async (tx) => {
+        await tx.put({ name: "inside", type: "tx", option: "intra", success: false });
+        throw new Error("forced rollback");
+      })).rejects.toBeDefined();
+      const intraRow = await storage.get({ name: "inside", type: "tx" });
+      expect11(intraRow).toBeUndefined();
+      const beforeRow = await storage.get({ name: "before", type: "tx" });
+      expect11(beforeRow).toBeDefined();
+      expect11(beforeRow?.option).toBe("base");
+    }, opts.timeout);
+  });
+}
+// src/tabular-storage/joinFixtures.ts
+var AuthorPrimaryKeyNames = ["id"];
+var AuthorSchema = {
+  type: "object",
+  properties: {
+    id: { type: "string" },
+    tenant: { type: "string" },
+    name: { type: "string" },
+    country: { anyOf: [{ type: "string" }, { type: "null" }] }
+  },
+  required: ["id", "tenant", "name", "country"],
+  additionalProperties: false
+};
+var PostPrimaryKeyNames = ["id"];
+var PostSchema = {
+  type: "object",
+  properties: {
+    id: { type: "string" },
+    tenant: { type: "string" },
+    author_id: { anyOf: [{ type: "string" }, { type: "null" }] },
+    title: { type: "string" },
+    views: { type: "number" }
+  },
+  required: ["id", "tenant", "author_id", "title", "views"],
+  additionalProperties: false
+};
+var JOIN_FIXTURE_AUTHORS = [
+  { id: "a1", tenant: "t1", name: "Ann", country: "US" },
+  { id: "a2", tenant: "t1", name: "Bob", country: null },
+  { id: "a3", tenant: "t2", name: "Cid", country: "FR" }
+];
+var JOIN_FIXTURE_POSTS = [
+  { id: "p1", tenant: "t1", author_id: "a1", title: "one", views: 10 },
+  { id: "p2", tenant: "t1", author_id: "a1", title: "two", views: 5 },
+  { id: "p3", tenant: "t1", author_id: "a2", title: "three", views: 7 },
+  { id: "p4", tenant: "t1", author_id: "zz", title: "orphan", views: 1 },
+  { id: "p5", tenant: "t1", author_id: null, title: "anon", views: 3 },
+  { id: "p6", tenant: "t2", author_id: "a1", title: "cross", views: 9 }
+];
+async function seedJoinFixtures(posts, authors) {
+  await authors.putBulk(JOIN_FIXTURE_AUTHORS);
+  await posts.putBulk(JOIN_FIXTURE_POSTS);
+}
+// src/tabular-storage/runTabularJoinContract.ts
+import { StorageInvalidColumnError, StorageValidationError } from "@workglow/storage";
+import { afterEach as afterEach11, beforeEach as beforeEach11, describe as describe12, expect as expect12, it as it13, vi as vi3 } from "vitest";
+var pairs = (rows) => rows.map((r) => `${r.left.id}:${r.right?.id ?? "-"}`);
+function runTabularJoinContract(createPosts, createAuthors, opts = {}) {
+  const on = [{ left: "author_id", right: "id" }];
+  describe12(`join (${opts.expectSqlPushdown ? "SQL pushdown" : "hash join"})`, () => {
+    let posts;
+    let authors;
+    beforeEach11(async () => {
+      posts = await createPosts();
+      authors = await createAuthors();
+      await posts.setupDatabase?.();
+      await authors.setupDatabase?.();
+      await seedJoinFixtures(posts, authors);
+    });
+    afterEach11(async () => {
+      await posts.deleteAll();
+      await authors.deleteAll();
+      posts.destroy?.();
+      authors.destroy?.();
+      vi3.restoreAllMocks();
+    });
+    it13.skipIf(opts.expectSqlPushdown === undefined)("takes the expected execution path", async () => {
+      const rightQuery = vi3.spyOn(authors, "query");
+      await posts.join({ type: "inner", on }, authors);
+      if (opts.expectSqlPushdown) {
+        expect12(rightQuery).not.toHaveBeenCalled();
+      } else {
+        expect12(rightQuery).toHaveBeenCalled();
+      }
+    }, opts.timeout);
+    it13("inner join pairs every match and drops orphans and null keys", async () => {
+      const rows = await posts.join({ type: "inner", on }, authors);
+      expect12(pairs(rows).sort()).toEqual(["p1:a1", "p2:a1", "p3:a2", "p6:a1"]);
+      const row = rows.find((r) => r.left.id === "p1");
+      expect12(row?.left).toEqual(JOIN_FIXTURE_POSTS[0]);
+      expect12(row?.right).toEqual(JOIN_FIXTURE_AUTHORS[0]);
+    }, opts.timeout);
+    it13("left join keeps orphans and null keys with right undefined", async () => {
+      const rows = await posts.join({ type: "left", on }, authors);
+      expect12(pairs(rows).sort()).toEqual(["p1:a1", "p2:a1", "p3:a2", "p4:-", "p5:-", "p6:a1"]);
+      expect12(rows.find((r) => r.left.id === "p4")?.right).toBeUndefined();
+      expect12(rows.find((r) => r.left.id === "p5")?.right).toBeUndefined();
+    }, opts.timeout);
+    it13("a right-side filter under a left join does not drop unmatched left rows", async () => {
+      const rows = await posts.join({ type: "left", on, where: { right: { name: "Ann" } } }, authors);
+      expect12(pairs(rows).sort()).toEqual(["p1:a1", "p2:a1", "p3:-", "p4:-", "p5:-", "p6:a1"]);
+    }, opts.timeout);
+    it13("a right-side filter under an inner join narrows the result", async () => {
+      const rows = await posts.join({ type: "inner", on, where: { right: { country: null } } }, authors);
+      expect12(pairs(rows)).toEqual(["p3:a2"]);
+    }, opts.timeout);
+    it13("a left-side filter narrows the left rows", async () => {
+      const rows = await posts.join({ type: "left", on, where: { left: { views: { value: 5, operator: ">" } } } }, authors);
+      expect12(pairs(rows).sort()).toEqual(["p1:a1", "p3:a2", "p6:a1"]);
+    }, opts.timeout);
+    it13("joins on a compound key", async () => {
+      const rows = await posts.join({
+        type: "inner",
+        on: [
+          { left: "tenant", right: "tenant" },
+          { left: "author_id", right: "id" }
+        ]
+      }, authors);
+      expect12(pairs(rows).sort()).toEqual(["p1:a1", "p2:a1", "p3:a2"]);
+    }, opts.timeout);
+    it13("orders by a left column", async () => {
+      const rows = await posts.join({ type: "left", on, orderBy: [{ side: "left", column: "views", direction: "DESC" }] }, authors);
+      expect12(rows.map((r) => r.left.views)).toEqual([10, 9, 7, 5, 3, 1]);
+    }, opts.timeout);
+    it13("orders by a right column with unmatched rows first under ASC", async () => {
+      const rows = await posts.join({
+        type: "left",
+        on,
+        orderBy: [
+          { side: "right", column: "name", direction: "ASC" },
+          { side: "left", column: "id", direction: "ASC" }
+        ]
+      }, authors);
+      expect12(pairs(rows)).toEqual(["p4:-", "p5:-", "p1:a1", "p2:a1", "p6:a1", "p3:a2"]);
+    }, opts.timeout);
+    it13("orders by a right column with unmatched rows last under DESC", async () => {
+      const rows = await posts.join({
+        type: "left",
+        on,
+        orderBy: [
+          { side: "right", column: "name", direction: "DESC" },
+          { side: "left", column: "id", direction: "DESC" }
+        ]
+      }, authors);
+      expect12(pairs(rows)).toEqual(["p3:a2", "p6:a1", "p2:a1", "p1:a1", "p5:-", "p4:-"]);
+    }, opts.timeout);
+    it13("applies limit and offset to the joined rows", async () => {
+      const rows = await posts.join({
+        type: "inner",
+        on,
+        orderBy: [{ side: "left", column: "id", direction: "ASC" }],
+        offset: 1,
+        limit: 2
+      }, authors);
+      expect12(pairs(rows)).toEqual(["p2:a1", "p3:a2"]);
+    }, opts.timeout);
+    it13("offset without limit skips rows", async () => {
+      const rows = await posts.join({
+        type: "inner",
+        on,
+        orderBy: [{ side: "left", column: "id", direction: "ASC" }],
+        offset: 3
+      }, authors);
+      expect12(pairs(rows)).toEqual(["p6:a1"]);
+    }, opts.timeout);
+    it13("honours a caller's own criterion on the join column", async () => {
+      const rows = await posts.join({ type: "inner", on, where: { right: { id: "a2" } } }, authors);
+      expect12(pairs(rows)).toEqual(["p3:a2"]);
+    }, opts.timeout);
+    it13("returns [] rather than undefined when nothing matches", async () => {
+      const rows = await posts.join({ type: "inner", on, where: { left: { title: "no such title" } } }, authors);
+      expect12(rows).toEqual([]);
+    }, opts.timeout);
+    it13("joins many distinct keys", async () => {
+      const n = 1100;
+      await authors.putBulk(Array.from({ length: n }, (_, i) => ({
+        id: `b${i}`,
+        tenant: "t9",
+        name: `n${i}`,
+        country: null
+      })));
+      await posts.putBulk(Array.from({ length: n }, (_, i) => ({
+        id: `q${i}`,
+        tenant: "t9",
+        author_id: `b${i}`,
+        title: `t${i}`,
+        views: i
+      })));
+      const rows = await posts.join({ type: "inner", on, where: { left: { tenant: "t9" } } }, authors);
+      expect12(rows).toHaveLength(n);
+      expect12(rows.every((r) => r.right.id === r.left.author_id)).toBe(true);
+    }, opts.timeout);
+    it13("rejects an unknown column on either side before running", async () => {
+      await expect12(posts.join({ type: "inner", on: [{ left: "nope", right: "id" }] }, authors)).rejects.toBeInstanceOf(StorageInvalidColumnError);
+      await expect12(posts.join({ type: "inner", on: [{ left: "author_id", right: "nope" }] }, authors)).rejects.toBeInstanceOf(StorageInvalidColumnError);
+      await expect12(posts.join({ type: "inner", on, orderBy: [{ side: "right", column: "views", direction: "ASC" }] }, authors)).rejects.toBeInstanceOf(StorageInvalidColumnError);
+    }, opts.timeout);
+    it13("rejects a forged join type, side, direction, limit or offset", async () => {
+      await expect12(posts.join({ type: "cross; DROP TABLE x", on }, authors)).rejects.toBeInstanceOf(StorageValidationError);
+      await expect12(posts.join({ type: "inner", on, orderBy: [{ side: "x", column: "id", direction: "ASC" }] }, authors)).rejects.toBeInstanceOf(StorageValidationError);
+      await expect12(posts.join({
+        type: "inner",
+        on,
+        orderBy: [{ side: "left", column: "id", direction: "ASC; --" }]
+      }, authors)).rejects.toBeInstanceOf(StorageValidationError);
+      await expect12(posts.join({ type: "inner", on, limit: 0 }, authors)).rejects.toBeInstanceOf(StorageValidationError);
+      await expect12(posts.join({ type: "inner", on, offset: -1 }, authors)).rejects.toBeInstanceOf(StorageValidationError);
+      await expect12(posts.join({ type: "inner", on: [] }, authors)).rejects.toBeInstanceOf(StorageValidationError);
+    }, opts.timeout);
+  });
+  joinBoundedLeftReadBlock(createPosts, createAuthors, seedJoinFixtures, opts);
+  joinStrategyParityBlock(createPosts, createAuthors, seedJoinFixtures, opts);
+}
+// src/tabular-storage/runTabularStorageContract.ts
+import { describe as describe13 } from "vitest";
+
+// src/tabular-storage/types.ts
+var VectorItemPrimaryKeyNames = ["id"];
+var VectorItemSchema = {
+  type: "object",
+  properties: {
+    id: { type: "string" },
+    embedding: { type: "array", format: "TypedArray:Float32Array" }
+  },
+  required: ["id", "embedding"],
+  additionalProperties: false
+};
+
+// src/tabular-storage/runTabularStorageContract.ts
+function runTabularStorageContract(opts) {
+  describe13.skipIf(opts.skip)(`Tabular storage contract: ${opts.name}`, () => {
+    subscribeToChangesBlock(opts);
+    vectorColumnFormatBlock(opts);
+    withTransactionRollbackBlock(opts);
+    withConnectionTransactionBlock(opts);
+    countMatchesQueryBlock(opts);
+    inListCriterionBlock(opts);
+    notInListCriterionBlock(opts);
+    joinPushdownBlock(opts);
+    guardParityBlock(opts);
+  });
+}
+export {
+  AuthorPrimaryKeyNames,
+  AuthorSchema,
+  CompoundPrimaryKeyNames,
+  CompoundSchema,
+  JOIN_FIXTURE_AUTHORS,
+  JOIN_FIXTURE_POSTS,
+  PostPrimaryKeyNames,
+  PostSchema,
+  VectorItemPrimaryKeyNames,
+  VectorItemSchema,
+  countMatchesQueryBlock,
+  guardParityBlock,
+  inListCriterionBlock,
+  joinBoundedLeftReadBlock,
+  joinPushdownBlock,
+  joinStrategyParityBlock,
+  notInListCriterionBlock,
+  runTabularJoinContract,
+  runTabularStorageContract,
+  seedJoinFixtures,
+  subscribeToChangesBlock,
+  vectorColumnFormatBlock,
+  withConnectionTransactionBlock,
+  withTransactionRollbackBlock
+};
+
+//# debugId=FCE7FDB7D993910B64756E2164756E21