@workglow/storage 0.2.31 → 0.2.32

package/dist/browser.js

@@ -27,7 +27,7 @@ class StorageEmptyCriteriaError extends StorageValidationError {
 class StorageInvalidLimitError extends StorageValidationError {
   static type = "StorageInvalidLimitError";
   constructor(limit) {
-    super(`Query limit must be greater than 0, got ${limit}`);
+    super(`Query limit must be a positive integer, got ${limit}`);
   }
 }
 
@@ -60,8 +60,214 @@ class CoveringIndexMissingError extends StorageError {
   }
 }
 
+// src/tabular/Cursor.ts
+var CURSOR_VERSION = 1;
+var MAX_CURSOR_LENGTH = 8 * 1024;
+function encodeCursor(payload) {
+  const json = JSON.stringify(payload);
+  let base64;
+  if (typeof Buffer !== "undefined") {
+    base64 = Buffer.from(json, "utf8").toString("base64");
+  } else {
+    const bytes = new TextEncoder().encode(json);
+    let binary = "";
+    const CHUNK = 32768;
+    for (let i = 0;i < bytes.length; i += CHUNK) {
+      binary += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+    }
+    base64 = btoa(binary);
+  }
+  let trimEnd = base64.length;
+  while (trimEnd > 0 && base64.charCodeAt(trimEnd - 1) === 61) {
+    trimEnd--;
+  }
+  const urlSafe = base64.slice(0, trimEnd).replace(/\+/g, "-").replace(/\//g, "_");
+  if (urlSafe.length > MAX_CURSOR_LENGTH) {
+    throw new StorageValidationError(`Encoded cursor exceeds maximum length (${urlSafe.length} > ${MAX_CURSOR_LENGTH})`);
+  }
+  return urlSafe;
+}
+function decodeCursor(cursor) {
+  if (typeof cursor !== "string" || cursor.length === 0) {
+    throw new StorageValidationError("Cursor must be a non-empty string");
+  }
+  if (cursor.length > MAX_CURSOR_LENGTH) {
+    throw new StorageValidationError(`Cursor exceeds maximum length (${cursor.length} > ${MAX_CURSOR_LENGTH})`);
+  }
+  const padded = cursor.replace(/-/g, "+").replace(/_/g, "/");
+  const padding = padded.length % 4 === 0 ? "" : "=".repeat(4 - padded.length % 4);
+  let json;
+  try {
+    if (typeof Buffer !== "undefined") {
+      json = Buffer.from(padded + padding, "base64").toString("utf8");
+    } else {
+      const binary = atob(padded + padding);
+      const bytes = new Uint8Array(binary.length);
+      for (let i = 0;i < binary.length; i++)
+        bytes[i] = binary.charCodeAt(i);
+      json = new TextDecoder().decode(bytes);
+    }
+  } catch {
+    throw new StorageValidationError("Cursor is not valid base64url");
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    throw new StorageValidationError("Cursor payload is not valid JSON");
+  }
+  const p = parsed;
+  if (!p || typeof p !== "object" || p.v !== CURSOR_VERSION || !Array.isArray(p.c) || !Array.isArray(p.n) || !Array.isArray(p.d) || p.n.length !== p.c.length || p.n.length !== p.d.length || !p.n.every((name) => typeof name === "string") || !p.d.every((dir) => dir === "a" || dir === "d") || !p.c.every((v) => v === null || typeof v === "string" || typeof v === "number" || typeof v === "boolean")) {
+    throw new StorageValidationError(`Cursor format is unsupported (expected v${CURSOR_VERSION})`);
+  }
+  return p;
+}
+function assertCursorMatches(payload, effectiveOrder) {
+  if (payload.n.length !== effectiveOrder.length) {
+    throw new StorageValidationError(`Cursor has ${payload.n.length} component(s); request expects ${effectiveOrder.length}`);
+  }
+  for (let i = 0;i < effectiveOrder.length; i++) {
+    if (payload.n[i] !== effectiveOrder[i].column) {
+      throw new StorageValidationError(`Cursor column ${i} is "${payload.n[i]}"; request expects "${effectiveOrder[i].column}"`);
+    }
+    const expected = effectiveOrder[i].direction === "ASC" ? "a" : "d";
+    if (payload.d[i] !== expected) {
+      throw new StorageValidationError(`Cursor column "${effectiveOrder[i].column}" was minted for ${payload.d[i] === "a" ? "ASC" : "DESC"}; request expects ${effectiveOrder[i].direction}`);
+    }
+  }
+}
+// src/migrations/MigrationRunner.ts
+var MIGRATIONS_TABLE = "_storage_migrations";
+function sortMigrations(migrations) {
+  return [...migrations].sort((a, b) => {
+    if (a.component !== b.component)
+      return a.component < b.component ? -1 : 1;
+    return a.version - b.version;
+  });
+}
+// src/migrations/TabularMigrationOrchestrator.ts
+async function runTabularMigrations(applier, defaultComponent, migrations, options = {}) {
+  if (migrations.length === 0)
+    return;
+  await applier.ensureBookkeeping();
+  const byComponent = new Map;
+  for (const m of migrations) {
+    const c = m.component ?? defaultComponent;
+    let bucket = byComponent.get(c);
+    if (!bucket) {
+      bucket = [];
+      byComponent.set(c, bucket);
+    }
+    bucket.push(m);
+  }
+  for (const [component, group] of byComponent) {
+    const sorted = [...group].sort((a, b) => a.version - b.version);
+    const applied = await applier.appliedVersions(component);
+    const fresh = options.freshTable ?? !await applier.tableExists();
+    if (applied.size === 0 && fresh) {
+      await applier.markAllApplied(component, sorted.map((m) => ({ version: m.version, description: m.description })));
+      for (const m of sorted) {
+        options.onProgress?.({
+          component,
+          version: m.version,
+          phase: "completed",
+          description: m.description,
+          fraction: 1
+        });
+      }
+      continue;
+    }
+    for (const m of sorted) {
+      if (applied.has(m.version))
+        continue;
+      options.onProgress?.({
+        component,
+        version: m.version,
+        phase: "starting",
+        description: m.description
+      });
+      try {
+        await applier.applyMigration(component, m.version, m.description, m.ops, (fraction) => {
+          options.onProgress?.({
+            component,
+            version: m.version,
+            phase: "running",
+            description: m.description,
+            fraction
+          });
+        });
+        options.onProgress?.({
+          component,
+          version: m.version,
+          phase: "completed",
+          description: m.description,
+          fraction: 1
+        });
+      } catch (err) {
+        options.onProgress?.({
+          component,
+          version: m.version,
+          phase: "failed",
+          description: m.description,
+          error: err
+        });
+        throw err;
+      }
+    }
+  }
+}
+// src/migrations/runBackfill.ts
+async function runBackfill(storage, batchSize, transform) {
+  let cursor;
+  while (true) {
+    const page = await storage.getPage({ limit: batchSize, cursor });
+    for (const row of page.items) {
+      const out = await transform(row);
+      if (out === row)
+        continue;
+      if (out === undefined) {
+        await storage.delete(row);
+      } else {
+        await storage.put(out);
+      }
+    }
+    if (!page.nextCursor)
+      break;
+    cursor = page.nextCursor;
+  }
+}
 // src/tabular/BaseTabularStorage.ts
 var TABULAR_REPOSITORY = createServiceToken("storage.tabularRepository");
+function toCursorValue(value) {
+  if (value === null || value === undefined)
+    return null;
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return value;
+  }
+  if (value instanceof Date)
+    return value.toISOString();
+  if (typeof value === "bigint") {
+    throw new StorageValidationError("bigint values are not supported as cursor keys — string-encoded bigints don't sort numerically. Use a number column or override `getPage` for this storage.");
+  }
+  throw new StorageValidationError(`Cannot encode value of type ${typeof value} into a pagination cursor; use a key column with a primitive type.`);
+}
+function compareKeyValues(a, b) {
+  const an = toCursorValue(a);
+  const bn = toCursorValue(b);
+  if (an === null && bn === null)
+    return 0;
+  if (an === null)
+    return -1;
+  if (bn === null)
+    return 1;
+  const av = typeof an === "boolean" ? Number(an) : an;
+  const bv = typeof bn === "boolean" ? Number(bn) : bn;
+  if (av < bv)
+    return -1;
+  if (av > bv)
+    return 1;
+  return 0;
+}
 
 class BaseTabularStorage {
   schema;
@@ -70,12 +276,18 @@ class BaseTabularStorage {
   indexes;
   primaryKeySchema;
   valueSchema;
+  tabularMigrations;
+  migrationComponent = "tabular:unnamed";
   autoGeneratedKeyName = null;
   autoGeneratedKeyStrategy = null;
   clientProvidedKeys;
-  constructor(schema, primaryKeyNames, indexes = [], clientProvidedKeys = "if-missing") {
+  constructor(schema, primaryKeyNames, indexes = [], clientProvidedKeys = "if-missing", tabularMigrations, migrationName) {
     this.schema = schema;
     this.primaryKeyNames = primaryKeyNames;
+    this.tabularMigrations = tabularMigrations;
+    if (migrationName) {
+      this.migrationComponent = `tabular:${migrationName}`;
+    }
     this.clientProvidedKeys = clientProvidedKeys;
     const primaryKeyProps = {};
     const valueProps = {};
@@ -196,37 +408,160 @@ class BaseTabularStorage {
     if (pageSize <= 0) {
       throw new RangeError(`pageSize must be greater than 0, got ${pageSize}`);
     }
-    let offset = 0;
+    let cursor;
     while (true) {
-      const page = await this.getBulk(offset, pageSize);
-      if (!page || page.length === 0) {
-        break;
-      }
-      for (const entity of page) {
+      const page = await this.getPage({ limit: pageSize, cursor });
+      for (const entity of page.items) {
         yield entity;
       }
-      if (page.length < pageSize) {
+      if (!page.nextCursor || page.items.length === 0)
         break;
-      }
-      offset += pageSize;
+      cursor = page.nextCursor;
     }
   }
   async* pages(pageSize = 100) {
     if (pageSize <= 0) {
       throw new RangeError(`pageSize must be greater than 0, got ${pageSize}`);
     }
-    let offset = 0;
+    let cursor;
     while (true) {
-      const page = await this.getBulk(offset, pageSize);
-      if (!page || page.length === 0) {
-        break;
+      const page = await this.getPage({ limit: pageSize, cursor });
+      if (page.items.length > 0) {
+        yield page.items.slice();
       }
-      yield page;
-      if (page.length < pageSize) {
+      if (!page.nextCursor || page.items.length === 0)
         break;
+      cursor = page.nextCursor;
+    }
+  }
+  async getPage(request = {}) {
+    return this.runPage(undefined, request);
+  }
+  async queryPage(criteria, request = {}) {
+    return this.runPage(criteria, request);
+  }
+  async runPage(criteria, request) {
+    this.validatePageRequest(request);
+    const limit = request.limit ?? 100;
+    const pkColumns = this.primaryKeyColumns();
+    const orderBy = request.orderBy;
+    const effectiveOrderBy = this.buildEffectiveOrderBy(orderBy, pkColumns);
+    const effectiveOrderForCursor = effectiveOrderBy.map((o) => ({
+      column: String(o.column),
+      direction: o.direction
+    }));
+    let cursorPayload;
+    if (request.cursor !== undefined) {
+      cursorPayload = decodeCursor(request.cursor);
+      assertCursorMatches(cursorPayload, effectiveOrderForCursor);
+    }
+    const pkCol = pkColumns[0];
+    const userCriteria = criteria ?? {};
+    const userTouchesPk = pkColumns.length === 1 && Object.prototype.hasOwnProperty.call(userCriteria, pkCol);
+    const canPushKeyset = pkColumns.length === 1 && effectiveOrderBy.length === 1 && effectiveOrderBy[0].column === pkCol && !userTouchesPk;
+    let queryCriteria = userCriteria;
+    const useFallback = !canPushKeyset;
+    if (cursorPayload && canPushKeyset) {
+      const direction = effectiveOrderBy[0].direction;
+      const op = direction === "ASC" ? ">" : "<";
+      const lastPk = cursorPayload.c[0];
+      const keysetCondition = {
+        value: lastPk,
+        operator: op
+      };
+      queryCriteria = {
+        ...userCriteria,
+        [pkCol]: keysetCondition
+      };
+    } else if (cursorPayload && useFallback) {
+      const leading = effectiveOrderBy[0];
+      const leadingCol = leading.column;
+      const leadingCursor = cursorPayload.c[0];
+      const userTouchesLeading = Object.prototype.hasOwnProperty.call(userCriteria, leadingCol);
+      if (leading.direction === "ASC" && leadingCursor !== null && !userTouchesLeading) {
+        const leadingCondition = {
+          value: leadingCursor,
+          operator: ">="
+        };
+        queryCriteria = {
+          ...userCriteria,
+          [leadingCol]: leadingCondition
+        };
+      }
+    }
+    const fetchLimit = useFallback ? undefined : limit;
+    const queryOptions = {
+      orderBy: effectiveOrderBy,
+      ...fetchLimit !== undefined ? { limit: fetchLimit } : {}
+    };
+    let rows;
+    let forcedFallback = false;
+    if (Object.keys(queryCriteria).length === 0) {
+      rows = await this.getAll(queryOptions);
+    } else {
+      try {
+        rows = await this.query(queryCriteria, queryOptions);
+      } catch (err) {
+        const userHadNoCriteria = !criteria || Object.keys(criteria).length === 0;
+        if (err instanceof StorageUnsupportedError && userHadNoCriteria) {
+          rows = await this.getAll({ orderBy: effectiveOrderBy });
+          forcedFallback = true;
+        } else {
+          throw err;
+        }
       }
-      offset += pageSize;
     }
+    let items = rows ?? [];
+    if (useFallback || forcedFallback) {
+      items = this.sortInMemory(items.slice(), effectiveOrderBy);
+      if (cursorPayload) {
+        items = this.applyKeysetFilter(items, cursorPayload, effectiveOrderBy, pkColumns);
+      }
+    }
+    if (items.length > limit) {
+      items = items.slice(0, limit);
+    }
+    const nextCursor = items.length === limit ? this.buildCursor(items[items.length - 1], effectiveOrderBy) : undefined;
+    return { items, nextCursor };
+  }
+  buildEffectiveOrderBy(orderBy, pkColumns) {
+    const result = orderBy ? orderBy.slice() : [];
+    const seen = new Set(result.map((o) => o.column));
+    for (const pk of pkColumns) {
+      if (!seen.has(pk)) {
+        result.push({ column: pk, direction: "ASC" });
+      }
+    }
+    return result;
+  }
+  sortInMemory(rows, orderBy) {
+    rows.sort((a, b) => {
+      for (const { column, direction } of orderBy) {
+        const cmp = compareKeyValues(a[column], b[column]);
+        if (cmp !== 0)
+          return direction === "ASC" ? cmp : -cmp;
+      }
+      return 0;
+    });
+    return rows;
+  }
+  applyKeysetFilter(rows, cursor, effectiveOrderBy, _pkColumns) {
+    return rows.filter((row) => {
+      for (let i = 0;i < effectiveOrderBy.length; i++) {
+        const { column, direction } = effectiveOrderBy[i];
+        const cmp = compareKeyValues(row[column], cursor.c[i]);
+        if (cmp === 0)
+          continue;
+        return direction === "ASC" ? cmp > 0 : cmp < 0;
+      }
+      return false;
+    });
+  }
+  buildCursor(row, effectiveOrderBy) {
+    const n = effectiveOrderBy.map((spec) => String(spec.column));
+    const d = effectiveOrderBy.map((spec) => spec.direction === "ASC" ? "a" : "d");
+    const c = effectiveOrderBy.map((spec) => toCursorValue(row[spec.column]));
+    return encodeCursor({ v: 1, n, d, c });
   }
   subscribeToChanges(_callback, _options) {
     throw new Error(`subscribeToChanges is not implemented for ${this.constructor.name}. ` + `All concrete repository implementations should override this method.`);
@@ -254,17 +589,7 @@ class BaseTabularStorage {
         }
       }
     }
-    if (options?.orderBy) {
-      const validDirections = ["ASC", "DESC"];
-      for (const { column, direction } of options.orderBy) {
-        if (!(column in this.schema.properties)) {
-          throw new StorageInvalidColumnError(String(column));
-        }
-        if (!validDirections.includes(direction)) {
-          throw new StorageValidationError(`Invalid sort direction "${direction}". Must be "ASC" or "DESC"`);
-        }
-      }
-    }
+    this.validateOrderBy(options?.orderBy);
   }
   validateGetAllOptions(options) {
     if (!options)
@@ -275,18 +600,32 @@ class BaseTabularStorage {
     if (options.offset !== undefined && options.offset < 0) {
       throw new StorageValidationError(`Query offset must be non-negative, got ${options.offset}`);
     }
-    if (options.orderBy) {
-      const validDirections = ["ASC", "DESC"];
-      for (const { column, direction } of options.orderBy) {
-        if (!(column in this.schema.properties)) {
-          throw new StorageInvalidColumnError(String(column));
-        }
-        if (!validDirections.includes(direction)) {
-          throw new StorageValidationError(`Invalid sort direction "${direction}". Must be "ASC" or "DESC"`);
-        }
+    this.validateOrderBy(options.orderBy);
+  }
+  validateOrderBy(orderBy) {
+    if (!orderBy)
+      return;
+    const validDirections = ["ASC", "DESC"];
+    for (const { column, direction } of orderBy) {
+      if (typeof column !== "string") {
+        throw new StorageInvalidColumnError(String(column));
+      }
+      if (!(column in this.schema.properties)) {
+        throw new StorageInvalidColumnError(String(column));
+      }
+      if (!validDirections.includes(direction)) {
+        throw new StorageValidationError(`Invalid sort direction "${direction}". Must be "ASC" or "DESC"`);
       }
     }
   }
+  validatePageRequest(request) {
+    if (request.limit !== undefined) {
+      if (!Number.isInteger(request.limit) || request.limit <= 0) {
+        throw new StorageInvalidLimitError(request.limit);
+      }
+    }
+    this.validateOrderBy(request.orderBy);
+  }
   validateSelect(options) {
     if (!options.select || options.select.length === 0) {
       throw new StorageValidationError("queryIndex requires a non-empty select array");
@@ -405,6 +744,21 @@ class BaseTabularStorage {
   generateKeyValue(columnName, strategy) {
     throw new Error(`generateKeyValue not implemented for ${this.constructor.name}. ` + `Column: ${columnName}, Strategy: ${strategy}`);
   }
+  async withTransaction(fn) {
+    return await fn(this);
+  }
+  getMigrationApplier() {
+    return null;
+  }
+  async applyTabularMigrations(options) {
+    if (!this.tabularMigrations || this.tabularMigrations.length === 0)
+      return;
+    const applier = this.getMigrationApplier();
+    if (!applier) {
+      throw new Error(`${this.constructor.name} declared migrations but has no migration applier wired up.`);
+    }
+    await runTabularMigrations(applier, this.migrationComponent, this.tabularMigrations, options);
+  }
   async setupDatabase() {}
   destroy() {}
   async[Symbol.asyncDispose]() {
@@ -421,8 +775,8 @@ class BaseSqlTabularStorage extends BaseTabularStorage {
   _valColsCache = new Map;
   _pkColListCache = new Map;
   _valColListCache = new Map;
-  constructor(table = "tabular_store", schema, primaryKeyNames, indexes = [], clientProvidedKeys = "if-missing") {
-    super(schema, primaryKeyNames, indexes, clientProvidedKeys);
+  constructor(table = "tabular_store", schema, primaryKeyNames, indexes = [], clientProvidedKeys = "if-missing", tabularMigrations, migrationName) {
+    super(schema, primaryKeyNames, indexes, clientProvidedKeys, tabularMigrations, migrationName ?? table);
     this.table = table;
     this.validateTableAndSchema();
   }
@@ -612,6 +966,90 @@ class BaseSqlTabularStorage extends BaseTabularStorage {
       throw new Error(`Duplicate keys found in schemas: ${duplicates.join(", ")}`);
     }
   }
+  buildKeysetWhere(effectiveOrderBy, cursorValues, quote, placeholder, startIndex) {
+    if (effectiveOrderBy.length !== cursorValues.length) {
+      throw new Error(`Keyset arity mismatch: ${effectiveOrderBy.length} order columns vs ${cursorValues.length} cursor values`);
+    }
+    const clauses = [];
+    const params = [];
+    let idx = startIndex;
+    for (let i = 0;i < effectiveOrderBy.length; i++) {
+      const parts = [];
+      for (let j = 0;j < i; j++) {
+        const colExpr2 = `${quote}${String(effectiveOrderBy[j].column)}${quote}`;
+        if (cursorValues[j] === null) {
+          parts.push(`${colExpr2} IS NULL`);
+        } else {
+          parts.push(`${colExpr2} = ${placeholder(idx)}`);
+          params.push(cursorValues[j]);
+          idx++;
+        }
+      }
+      const colExpr = `${quote}${String(effectiveOrderBy[i].column)}${quote}`;
+      const v = cursorValues[i];
+      const dir = effectiveOrderBy[i].direction;
+      if (v === null) {
+        parts.push(dir === "ASC" ? `${colExpr} IS NOT NULL` : `1 = 0`);
+      } else {
+        if (dir === "ASC") {
+          parts.push(`${colExpr} > ${placeholder(idx)}`);
+        } else {
+          parts.push(`(${colExpr} < ${placeholder(idx)} OR ${colExpr} IS NULL)`);
+        }
+        params.push(v);
+        idx++;
+      }
+      clauses.push(`(${parts.join(" AND ")})`);
+    }
+    return { whereClause: clauses.join(" OR "), params, nextIndex: idx };
+  }
+  async runSqlPage(criteria, request, dialect) {
+    this.validatePageRequest(request);
+    const limit = request.limit ?? 100;
+    const pkColumns = this.primaryKeyColumns();
+    const orderBy = request.orderBy;
+    const effectiveOrderBy = this.buildEffectiveOrderBy(orderBy, pkColumns);
+    const effectiveOrderForCursor = effectiveOrderBy.map((o) => ({
+      column: String(o.column),
+      direction: o.direction
+    }));
+    let cursorPayload;
+    if (request.cursor !== undefined) {
+      cursorPayload = decodeCursor(request.cursor);
+      assertCursorMatches(cursorPayload, effectiveOrderForCursor);
+    }
+    const params = [];
+    let paramIdx = 1;
+    const whereClauses = [];
+    if (criteria && Object.keys(criteria).length > 0) {
+      const built = dialect.buildSearchWhere(criteria, paramIdx);
+      whereClauses.push(built.whereClause);
+      params.push(...built.params);
+      paramIdx = built.nextIndex;
+    }
+    if (cursorPayload) {
+      const cursorValues = cursorPayload.c.map((v, i) => this.jsToSqlValue(String(effectiveOrderBy[i].column), v));
+      const built = this.buildKeysetWhere(effectiveOrderBy, cursorValues, dialect.quote, dialect.placeholder, paramIdx);
+      whereClauses.push(`(${built.whereClause})`);
+      params.push(...built.params);
+      paramIdx = built.nextIndex;
+    }
+    const q = dialect.quote;
+    const orderByClause = effectiveOrderBy.map((o) => {
+      const nulls = o.direction === "ASC" ? "NULLS FIRST" : "NULLS LAST";
+      return `${q}${String(o.column)}${q} ${o.direction} ${nulls}`;
+    }).join(", ");
+    let sql = `SELECT * FROM ${q}${this.table}${q}`;
+    if (whereClauses.length > 0) {
+      sql += ` WHERE ${whereClauses.join(" AND ")}`;
+    }
+    sql += ` ORDER BY ${orderByClause}`;
+    sql += ` LIMIT ${dialect.placeholder(paramIdx)}`;
+    params.push(limit);
+    const items = await dialect.executeSelect(sql, params);
+    const nextCursor = items.length === limit ? this.buildCursor(items[items.length - 1], effectiveOrderBy) : undefined;
+    return { items, nextCursor };
+  }
 }
 // src/tabular/CachedTabularStorage.ts
 import { createServiceToken as createServiceToken3, getLogger } from "@workglow/util";
@@ -619,6 +1057,55 @@ import { createServiceToken as createServiceToken3, getLogger } from "@workglow/
 // src/tabular/InMemoryTabularStorage.ts
 import { createServiceToken as createServiceToken2, makeFingerprint as makeFingerprint2, uuid4 } from "@workglow/util";
 
+// src/tabular/InMemoryTabularMigrationApplier.ts
+class InMemoryTabularMigrationApplier {
+  storage;
+  storeName;
+  applied = new Map;
+  constructor(storage, storeName) {
+    this.storage = storage;
+    this.storeName = storeName;
+  }
+  async ensureBookkeeping() {}
+  async appliedVersions(component) {
+    return new Set(this.applied.get(component) ?? []);
+  }
+  async tableExists() {
+    return await this.storage.size() > 0;
+  }
+  async markAllApplied(component, versions) {
+    if (versions.length === 0)
+      return;
+    let set = this.applied.get(component);
+    if (!set) {
+      set = new Set;
+      this.applied.set(component, set);
+    }
+    for (const v of versions)
+      set.add(v.version);
+    await this.persist();
+  }
+  async applyMigration(component, version, _description, ops, onProgress) {
+    let processed = 0;
+    const total = Math.max(ops.length, 1);
+    for (const op of ops) {
+      if (op.kind === "backfill") {
+        await runBackfill(this.storage, op.batchSize ?? 500, op.transform);
+      }
+      processed++;
+      onProgress?.(processed / total);
+    }
+    let set = this.applied.get(component);
+    if (!set) {
+      set = new Set;
+      this.applied.set(component, set);
+    }
+    set.add(version);
+    await this.persist();
+  }
+  async persist() {}
+}
+
 // src/tabular/coveringIndexPicker.ts
 function pickCoveringIndex(input) {
   const { table, indexes, criteriaColumns, orderByColumns, selectColumns, primaryKeyColumns } = input;
@@ -679,10 +1166,17 @@ class InMemoryTabularStorage extends BaseTabularStorage {
   values = new Map;
   autoIncrementCounter = 0;
   _lastPutWasInsert = false;
-  constructor(schema, primaryKeyNames, indexes = [], clientProvidedKeys = "if-missing") {
-    super(schema, primaryKeyNames, indexes, clientProvidedKeys);
+  constructor(schema, primaryKeyNames, indexes = [], clientProvidedKeys = "if-missing", tabularMigrations, migrationName = "inmemory") {
+    super(schema, primaryKeyNames, indexes, clientProvidedKeys, tabularMigrations, migrationName);
+  }
+  async setupDatabase() {
+    if (this.tabularMigrations && this.tabularMigrations.length > 0) {
+      await this.applyTabularMigrations();
+    }
+  }
+  getMigrationApplier() {
+    return new InMemoryTabularMigrationApplier(this, "inmemory");
   }
-  async setupDatabase() {}
   generateKeyValue(columnName, strategy) {
     if (strategy === "autoincrement") {
       return ++this.autoIncrementCounter;
@@ -1064,6 +1558,7 @@ class CachedTabularStorage extends BaseTabularStorage {
     await this.cache.deleteAll();
   }
   async getAll(options) {
+    this.validateGetAllOptions(options);
     await this.initializeCache();
     let results = await this.cache.getAll();
     if (!results || results.length === 0) {
@@ -1098,6 +1593,14 @@ class CachedTabularStorage extends BaseTabularStorage {
     await this.durable.deleteSearch(criteria);
     await this.cache.deleteSearch(criteria);
   }
+  async withTransaction(fn) {
+    await this.initializeCache();
+    try {
+      return await this.durable.withTransaction(fn);
+    } finally {
+      await this.invalidateCache();
+    }
+  }
   async invalidateCache() {
     await this.cache.deleteAll();
     this.cacheInitialized = false;
@@ -1121,6 +1624,14 @@ class CachedTabularStorage extends BaseTabularStorage {
       callback(change);
     }, options);
   }
+  async setupDatabase() {
+    await this.durable.setupDatabase();
+    await this.cache.setupDatabase();
+  }
+  getMigrationApplier() {
+    const inner = this.durable;
+    return inner.getMigrationApplier?.() ?? null;
+  }
   destroy() {
     this.durable.destroy();
     this.cache.destroy();
@@ -1129,6 +1640,21 @@ class CachedTabularStorage extends BaseTabularStorage {
 // src/tabular/HuggingFaceTabularStorage.ts
 import { createServiceToken as createServiceToken4 } from "@workglow/util";
 var HF_TABULAR_REPOSITORY = createServiceToken4("storage.tabularRepository.huggingface");
+var HF_OFFSET_CURSOR_NAME = "hfOffset";
+function encodeOffsetCursor(offset) {
+  return encodeCursor({ v: 1, n: [HF_OFFSET_CURSOR_NAME], d: ["a"], c: [offset] });
+}
+function decodeOffsetCursor(cursor) {
+  const payload = decodeCursor(cursor);
+  if (payload.n[0] !== HF_OFFSET_CURSOR_NAME) {
+    throw new StorageValidationError("Cursor was not produced by HuggingFaceTabularStorage");
+  }
+  const value = payload.c[0];
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    throw new StorageValidationError("Invalid HuggingFace pagination cursor");
+  }
+  return value;
+}
 
 class HuggingFaceTabularStorage extends BaseTabularStorage {
   dataset;
@@ -1136,8 +1662,8 @@ class HuggingFaceTabularStorage extends BaseTabularStorage {
   split;
   token;
   baseUrl;
-  constructor(dataset, config, split, schema, primaryKeyNames, options) {
-    super(schema, primaryKeyNames, options?.indexes ?? [], "never");
+  constructor(dataset, config, split, schema, primaryKeyNames, options, tabularMigrations) {
+    super(schema, primaryKeyNames, options?.indexes ?? [], "never", tabularMigrations, `hf:${dataset}/${config}/${split}`);
     this.dataset = dataset;
     this.config = config;
     this.split = split;
@@ -1189,6 +1715,12 @@ class HuggingFaceTabularStorage extends BaseTabularStorage {
         }
       }
     }
+    if (this.tabularMigrations && this.tabularMigrations.length > 0) {
+      await this.applyTabularMigrations();
+    }
+  }
+  getMigrationApplier() {
+    return new InMemoryTabularMigrationApplier(this, `hf:${this.dataset}/${this.config}/${this.split}`);
   }
   async get(key) {
     const keyObj = this.separateKeyValueFromCombined({ ...key }).key;
@@ -1272,6 +1804,34 @@ class HuggingFaceTabularStorage extends BaseTabularStorage {
     }
     return entities;
   }
+  async getPage(request = {}) {
+    this.validatePageRequest(request);
+    const limit = request.limit ?? 100;
+    if (request.orderBy && request.orderBy.length > 0) {
+      throw new StorageUnsupportedError("orderBy in getPage", "HuggingFaceTabularStorage");
+    }
+    const HF_PAGE_CAP = 100;
+    let offset = request.cursor ? decodeOffsetCursor(request.cursor) : 0;
+    const items = [];
+    let endOfDataset = false;
+    while (items.length < limit) {
+      const remaining = limit - items.length;
+      const chunkSize = Math.min(remaining, HF_PAGE_CAP);
+      const rows = await this.getBulk(offset, chunkSize) ?? [];
+      if (rows.length === 0) {
+        endOfDataset = true;
+        break;
+      }
+      items.push(...rows);
+      offset += rows.length;
+      if (rows.length < chunkSize) {
+        endOfDataset = true;
+        break;
+      }
+    }
+    const nextCursor = endOfDataset ? undefined : encodeOffsetCursor(offset);
+    return { items, nextCursor };
+  }
   async size() {
     const data = await this.fetchApi("/size", {});
     return data.size.num_rows;
@@ -1478,6 +2038,155 @@ function registerTabularStorageDefaults(registry = globalServiceRegistry) {
   registerInputCompactor("storage:tabular", compactTabularRepository, registry);
 }
 registerTabularStorageDefaults();
+// src/sql/Dialect.ts
+var SqliteDialect = {
+  name: "sqlite",
+  quoteId(id) {
+    return "`" + id.replace(/`/g, "``") + "`";
+  },
+  placeholder(_index) {
+    return "?";
+  }
+};
+var PostgresDialect = {
+  name: "postgres",
+  quoteId(id) {
+    return '"' + id.replace(/"/g, '""') + '"';
+  },
+  placeholder(index) {
+    return `$${index}`;
+  }
+};
+
+// src/tabular/sqlMigrationDdl.ts
+function selectDialect(name) {
+  return name === "sqlite" ? SqliteDialect : PostgresDialect;
+}
+function buildAddColumnSql(dialect, table, column, sqlType, nullable, hasDefault = false, defaultLiteralSql) {
+  const d = selectDialect(dialect);
+  let sql = `ALTER TABLE ${d.quoteId(table)} ADD COLUMN ${d.quoteId(column)} ${sqlType}`;
+  if (!nullable)
+    sql += " NOT NULL";
+  if (hasDefault && defaultLiteralSql !== undefined) {
+    sql += ` DEFAULT ${defaultLiteralSql}`;
+  }
+  return sql;
+}
+function buildDropColumnSql(dialect, table, column) {
+  const d = selectDialect(dialect);
+  return `ALTER TABLE ${d.quoteId(table)} DROP COLUMN ${d.quoteId(column)}`;
+}
+function buildRenameColumnSql(dialect, table, from, to) {
+  const d = selectDialect(dialect);
+  return `ALTER TABLE ${d.quoteId(table)} RENAME COLUMN ${d.quoteId(from)} TO ${d.quoteId(to)}`;
+}
+function buildAddIndexSql(dialect, table, indexName, columns, unique) {
+  const d = selectDialect(dialect);
+  const cols = columns.map((c) => d.quoteId(c)).join(", ");
+  return `CREATE ${unique ? "UNIQUE " : ""}INDEX IF NOT EXISTS ` + `${d.quoteId(indexName)} ON ${d.quoteId(table)} (${cols})`;
+}
+function buildDropIndexSql(dialect, indexName) {
+  const d = selectDialect(dialect);
+  return `DROP INDEX IF EXISTS ${d.quoteId(indexName)}`;
+}
+// src/tabular/SqlTabularMigrationApplier.ts
+class SqlTabularMigrationApplier {
+  async ensureBookkeeping() {
+    await this.executeSql(this.bookkeepingDdl());
+  }
+  async appliedVersions(component) {
+    return this.queryAppliedVersions(component);
+  }
+  async tableExists() {
+    return this.probeTableExists();
+  }
+  async markAllApplied(component, versions) {
+    if (versions.length === 0)
+      return;
+    for (const v of versions) {
+      await this.recordApplied(component, v.version, v.description);
+    }
+  }
+  async applyMigration(component, version, description, ops, onProgress) {
+    const storage = this.storage();
+    await storage.withTransaction(async (tx) => {
+      let processed = 0;
+      const total = Math.max(ops.length, 1);
+      for (const op of ops) {
+        await this.applyOp(op, tx);
+        processed++;
+        onProgress?.(processed / total);
+      }
+      await this.recordAppliedTx(component, version, description, tx);
+    });
+  }
+  async applyOp(op, tx) {
+    switch (op.kind) {
+      case "addColumn": {
+        const sqlType = this.mapTypeToSQL(op.schema);
+        const nullable = this.isNullableSchema(op.schema);
+        const hasDefault = op.default !== undefined;
+        const sql = buildAddColumnSql(this.dialectName(), this.table(), op.name, sqlType, nullable, hasDefault, hasDefault ? this.literalSql(op.default) : undefined);
+        await this.executeSqlTx(sql, tx);
+        return;
+      }
+      case "dropColumn": {
+        await this.executeSqlTx(buildDropColumnSql(this.dialectName(), this.table(), op.name), tx);
+        return;
+      }
+      case "renameColumn": {
+        await this.executeSqlTx(buildRenameColumnSql(this.dialectName(), this.table(), op.from, op.to), tx);
+        return;
+      }
+      case "addIndex": {
+        await this.executeSqlTx(buildAddIndexSql(this.dialectName(), this.table(), op.name, op.columns, op.unique ?? false), tx);
+        return;
+      }
+      case "dropIndex": {
+        await this.executeSqlTx(buildDropIndexSql(this.dialectName(), op.name), tx);
+        return;
+      }
+      case "backfill": {
+        await runBackfill(tx, op.batchSize ?? 500, op.transform);
+        return;
+      }
+    }
+  }
+  literalSql(value) {
+    if (value === null)
+      return "NULL";
+    if (typeof value === "string")
+      return `'${value.replace(/'/g, "''")}'`;
+    if (typeof value === "number") {
+      if (!Number.isFinite(value)) {
+        throw new Error(`Unsupported numeric default for tabular migration: ${value} (must be finite)`);
+      }
+      return String(value);
+    }
+    if (typeof value === "boolean") {
+      return this.dialectName() === "sqlite" ? value ? "1" : "0" : value ? "TRUE" : "FALSE";
+    }
+    throw new Error(`Unsupported default value for tabular migration: ${typeof value} (${String(value)})`);
+  }
+  bookkeepingDdl() {
+    if (this.dialectName() === "sqlite") {
+      return `CREATE TABLE IF NOT EXISTS ${MIGRATIONS_TABLE} (
+        component TEXT NOT NULL,
+        version INTEGER NOT NULL,
+        description TEXT,
+        applied_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+        PRIMARY KEY (component, version)
+      )`;
+    }
+    return `CREATE TABLE IF NOT EXISTS ${MIGRATIONS_TABLE} (
+      component TEXT NOT NULL,
+      version INTEGER NOT NULL,
+      description TEXT,
+      applied_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+      PRIMARY KEY (component, version)
+    )`;
+  }
+}
 // src/tabular/TelemetryTabularStorage.ts
 import { traced } from "@workglow/util";
 
@@ -1518,6 +2227,12 @@ class TelemetryTabularStorage {
   getBulk(offset, limit) {
     return traced("workglow.storage.tabular.getBulk", this.storageName, () => this.inner.getBulk(offset, limit));
   }
+  getPage(request) {
+    return traced("workglow.storage.tabular.getPage", this.storageName, () => this.inner.getPage(request));
+  }
+  queryPage(criteria, request) {
+    return traced("workglow.storage.tabular.queryPage", this.storageName, () => this.inner.queryPage(criteria, request));
+  }
   query(criteria, options) {
     return traced("workglow.storage.tabular.query", this.storageName, () => this.inner.query(criteria, options));
   }
@@ -1533,9 +2248,19 @@ class TelemetryTabularStorage {
   subscribeToChanges(callback, options) {
     return this.inner.subscribeToChanges(callback, options);
   }
+  withTransaction(fn) {
+    return traced("workglow.storage.tabular.withTransaction", this.storageName, () => this.inner.withTransaction((innerTx) => {
+      const txWrapper = new TelemetryTabularStorage(this.storageName, innerTx);
+      return fn(txWrapper);
+    }));
+  }
   setupDatabase() {
     return this.inner.setupDatabase();
   }
+  getMigrationApplier() {
+    const inner = this.inner;
+    return inner.getMigrationApplier?.() ?? null;
+  }
   destroy() {
     return this.inner.destroy();
   }
@@ -2016,6 +2741,176 @@ class PollingSubscriptionManager {
     this.initializing = false;
   }
 }
+// src/sql/PredicateBuilder.ts
+function buildSearchWhere(dialect, criteria, schemaProps, convertValue, startIndex = 1) {
+  const conditions = [];
+  const params = [];
+  let paramIndex = startIndex;
+  for (const column of Object.keys(criteria)) {
+    if (!(column in schemaProps)) {
+      throw new Error(`Schema must have a "${String(column)}" field to use it in search criteria`);
+    }
+    const criterion = criteria[column];
+    let operator = "=";
+    let value;
+    if (isSearchCondition(criterion)) {
+      operator = criterion.operator;
+      value = criterion.value;
+    } else {
+      value = criterion;
+    }
+    conditions.push(`${dialect.quoteId(String(column))} ${operator} ${dialect.placeholder(paramIndex)}`);
+    params.push(convertValue(column, value));
+    paramIndex++;
+  }
+  return {
+    whereClause: conditions.join(" AND "),
+    params
+  };
+}
+// src/sql/PrefixDdl.ts
+var SAFE_IDENTIFIER = /^[a-zA-Z][a-zA-Z0-9_]*$/;
+var SQL_RESERVED_WORDS = new Set([
+  "all",
+  "alter",
+  "and",
+  "as",
+  "asc",
+  "between",
+  "by",
+  "case",
+  "check",
+  "column",
+  "constraint",
+  "create",
+  "cross",
+  "current",
+  "default",
+  "delete",
+  "desc",
+  "distinct",
+  "drop",
+  "else",
+  "end",
+  "exists",
+  "false",
+  "for",
+  "foreign",
+  "from",
+  "full",
+  "function",
+  "grant",
+  "group",
+  "having",
+  "in",
+  "index",
+  "inner",
+  "insert",
+  "into",
+  "is",
+  "join",
+  "key",
+  "left",
+  "like",
+  "limit",
+  "natural",
+  "not",
+  "null",
+  "offset",
+  "on",
+  "or",
+  "order",
+  "outer",
+  "primary",
+  "references",
+  "returning",
+  "right",
+  "select",
+  "set",
+  "table",
+  "then",
+  "true",
+  "union",
+  "unique",
+  "update",
+  "user",
+  "using",
+  "values",
+  "view",
+  "when",
+  "where",
+  "with"
+]);
+function assertPrefixesSafe(prefixes) {
+  for (const p of prefixes) {
+    if (!SAFE_IDENTIFIER.test(p.name)) {
+      throw new Error(`Prefix column name must start with a letter and contain only letters, digits, and underscores, got: ${p.name}`);
+    }
+    if (SQL_RESERVED_WORDS.has(p.name.toLowerCase())) {
+      throw new Error(`Prefix column name "${p.name}" is a reserved SQL keyword. Pick a different identifier (e.g. "${p.name}_id").`);
+    }
+  }
+}
+function assertPrefixValuesPresent(prefixes, prefixValues) {
+  for (const p of prefixes) {
+    const v = prefixValues[p.name];
+    if (v === undefined || v === null) {
+      throw new Error(`Missing prefix value for column "${p.name}". Every prefix declared in \`prefixes\` ` + `must have a corresponding entry in \`prefixValues\`.`);
+    }
+  }
+}
+function prefixColumnType(dialect, type) {
+  if (type === "uuid") {
+    return dialect.name === "postgres" ? "UUID" : "TEXT";
+  }
+  return "INTEGER";
+}
+function buildPrefixColumnsSql(dialect, prefixes) {
+  if (prefixes.length === 0)
+    return "";
+  assertPrefixesSafe(prefixes);
+  return prefixes.map((p) => `${p.name} ${prefixColumnType(dialect, p.type)} NOT NULL`).join(`,
+        `) + `,
+        `;
+}
+function getPrefixColumnNames(prefixes) {
+  return prefixes.map((p) => p.name);
+}
+function getPrefixIndexPrefix(prefixes) {
+  if (prefixes.length === 0)
+    return "";
+  assertPrefixesSafe(prefixes);
+  return prefixes.map((p) => p.name).join(", ") + ", ";
+}
+function getPrefixIndexSuffix(prefixes) {
+  if (prefixes.length === 0)
+    return "";
+  assertPrefixesSafe(prefixes);
+  return "_" + prefixes.map((p) => p.name).join("_");
+}
+function buildPrefixWhereClause(dialect, prefixes, prefixValues, startParam = 1) {
+  if (prefixes.length === 0)
+    return { conditions: "", params: [] };
+  assertPrefixesSafe(prefixes);
+  assertPrefixValuesPresent(prefixes, prefixValues);
+  const conditions = prefixes.map((p, i) => `${p.name} = ${dialect.placeholder(startParam + i)}`).join(" AND ");
+  const params = prefixes.map((p) => prefixValues[p.name]);
+  return { conditions: " AND " + conditions, params };
+}
+function getPrefixParamValues(prefixes, prefixValues) {
+  if (prefixes.length === 0)
+    return [];
+  assertPrefixValuesPresent(prefixes, prefixValues);
+  return prefixes.map((p) => prefixValues[p.name]);
+}
+function buildPrefixInsertFragments(dialect, prefixes, startParam = 1) {
+  if (prefixes.length === 0)
+    return { columns: "", placeholders: "" };
+  assertPrefixesSafe(prefixes);
+  const columns = prefixes.map((p) => p.name).join(", ") + ", ";
+  const placeholders = prefixes.map((_, i) => dialect.placeholder(startParam + i)).join(", ") + ", ";
+  return { columns, placeholders };
+}
 // src/vector/InMemoryVectorStorage.ts
 import { cosineSimilarity } from "@workglow/util/schema";
 
@@ -2290,8 +3185,8 @@ class SharedInMemoryTabularStorage extends BaseTabularStorage {
   isInitialized = false;
   syncInProgress = false;
   pendingMessages = [];
-  constructor(channelName = "tabular_store", schema, primaryKeyNames, indexes = [], clientProvidedKeys = "if-missing") {
-    super(schema, primaryKeyNames, indexes, clientProvidedKeys);
+  constructor(channelName = "tabular_store", schema, primaryKeyNames, indexes = [], clientProvidedKeys = "if-missing", tabularMigrations) {
+    super(schema, primaryKeyNames, indexes, clientProvidedKeys, tabularMigrations, channelName);
     this.channelName = channelName;
     this.inMemoryRepo = new InMemoryTabularStorage(schema, primaryKeyNames, indexes, clientProvidedKeys);
     this.setupEventForwarding();
@@ -2415,6 +3310,12 @@ class SharedInMemoryTabularStorage extends BaseTabularStorage {
       return;
     this.isInitialized = true;
     await this.syncFromOtherTabs();
+    if (this.tabularMigrations && this.tabularMigrations.length > 0) {
+      await this.applyTabularMigrations();
+    }
+  }
+  getMigrationApplier() {
+    return new InMemoryTabularMigrationApplier(this, this.channelName);
   }
   async put(value) {
     const result = await this.inMemoryRepo.put(value);
@@ -2472,14 +3373,36 @@ class SharedInMemoryTabularStorage extends BaseTabularStorage {
   }
 }
 export {
+  sortMigrations,
+  runTabularMigrations,
+  runBackfill,
   registerTabularStorageDefaults,
   registerTabularRepository,
+  prefixColumnType,
   pickCoveringIndex,
   isSearchCondition,
   getVectorProperty,
   getTabularRepository,
+  getPrefixParamValues,
+  getPrefixIndexSuffix,
+  getPrefixIndexPrefix,
+  getPrefixColumnNames,
   getMetadataProperty,
   getGlobalTabularRepositories,
+  encodeCursor,
+  decodeCursor,
+  buildSearchWhere,
+  buildRenameColumnSql,
+  buildPrefixWhereClause,
+  buildPrefixInsertFragments,
+  buildPrefixColumnsSql,
+  buildDropIndexSql,
+  buildDropColumnSql,
+  buildAddIndexSql,
+  buildAddColumnSql,
+  assertPrefixesSafe,
+  assertPrefixValuesPresent,
+  assertCursorMatches,
   TelemetryVectorStorage,
   TelemetryTabularStorage,
   TelemetryKvStorage,
@@ -2491,17 +3414,23 @@ export {
   StorageInvalidColumnError,
   StorageError,
   StorageEmptyCriteriaError,
+  SqliteDialect,
+  SqlTabularMigrationApplier,
   SharedInMemoryTabularStorage,
   SHARED_IN_MEMORY_TABULAR_REPOSITORY,
+  PostgresDialect,
   PollingSubscriptionManager,
+  MIGRATIONS_TABLE,
   MEMORY_TABULAR_REPOSITORY,
   MEMORY_KV_REPOSITORY,
+  MAX_CURSOR_LENGTH,
   LazyEncryptedCredentialStore,
   KvViaTabularStorage,
   KvStorage,
   KV_REPOSITORY,
   InMemoryVectorStorage,
   InMemoryTabularStorage,
+  InMemoryTabularMigrationApplier,
   InMemoryKvStorage,
   HybridSubscriptionManager,
   HuggingFaceTabularStorage,
@@ -2516,4 +3445,4 @@ export {
   BaseSqlTabularStorage
 };
 
-//# debugId=A14C904C88169CB964756E2164756E21
+//# debugId=2D7847D1C483B82F64756E2164756E21