@workglow/storage 0.0.84 → 0.0.86

package/dist/node.js

@@ -1,18 +1,4 @@
-// src/tabular/CachedTabularRepository.ts
-import { createServiceToken as createServiceToken3 } from "@workglow/util";
-
-// src/tabular/InMemoryTabularRepository.ts
-import {
-  createServiceToken as createServiceToken2,
-  makeFingerprint as makeFingerprint2
-} from "@workglow/util";
-
-// src/tabular/ITabularRepository.ts
-function isSearchCondition(value) {
-  return typeof value === "object" && value !== null && "value" in value && "operator" in value && typeof value.operator === "string";
-}
-
-// src/tabular/TabularRepository.ts
+// src/tabular/BaseTabularStorage.ts
 import {
   createServiceToken,
   EventEmitter,
@@ -20,16 +6,20 @@ import {
 } from "@workglow/util";
 var TABULAR_REPOSITORY = createServiceToken("storage.tabularRepository");
 
-class TabularRepository {
+class BaseTabularStorage {
   schema;
   primaryKeyNames;
   events = new EventEmitter;
   indexes;
   primaryKeySchema;
   valueSchema;
-  constructor(schema, primaryKeyNames, indexes = []) {
+  autoGeneratedKeyName = null;
+  autoGeneratedKeyStrategy = null;
+  clientProvidedKeys;
+  constructor(schema, primaryKeyNames, indexes = [], clientProvidedKeys = "if-missing") {
     this.schema = schema;
     this.primaryKeyNames = primaryKeyNames;
+    this.clientProvidedKeys = clientProvidedKeys;
     const primaryKeyProps = {};
     const valueProps = {};
     const primaryKeySet = new Set(primaryKeyNames);
@@ -72,6 +62,28 @@ class TabularRepository {
         }
       }
     }
+    const autoGeneratedKeys = [];
+    for (const key of primaryKeyNames) {
+      const keyStr = String(key);
+      const propDef = schema.properties[keyStr];
+      if (propDef && typeof propDef === "object" && "x-auto-generated" in propDef) {
+        if (propDef["x-auto-generated"] === true) {
+          autoGeneratedKeys.push(keyStr);
+        }
+      }
+    }
+    if (autoGeneratedKeys.length > 1) {
+      throw new Error(`Multiple auto-generated keys detected: ${autoGeneratedKeys.join(", ")}. ` + `Only the first primary key column can be auto-generated.`);
+    }
+    if (autoGeneratedKeys.length > 0) {
+      const autoGenKeyName = autoGeneratedKeys[0];
+      const firstPrimaryKey = String(primaryKeyNames[0]);
+      if (autoGenKeyName !== firstPrimaryKey) {
+        throw new Error(`Auto-generated key "${autoGenKeyName}" must be the first primary key column. ` + `Current first primary key is "${firstPrimaryKey}".`);
+      }
+      this.autoGeneratedKeyName = autoGenKeyName;
+      this.autoGeneratedKeyStrategy = this.determineGenerationStrategy(autoGenKeyName, schema.properties[autoGenKeyName]);
+    }
   }
   filterCompoundKeys(primaryKey, potentialKeys) {
     const isPrefix = (prefix, arr) => {
@@ -193,6 +205,32 @@ class TabularRepository {
     }
     return bestMatch;
   }
+  hasAutoGeneratedKey() {
+    return this.autoGeneratedKeyName !== null;
+  }
+  isAutoGeneratedKey(name) {
+    return this.autoGeneratedKeyName !== null && String(this.autoGeneratedKeyName) === name;
+  }
+  determineGenerationStrategy(columnName, typeDef) {
+    let actualType = typeDef;
+    if (typeDef && typeof typeDef === "object") {
+      if (typeDef.anyOf && Array.isArray(typeDef.anyOf)) {
+        actualType = typeDef.anyOf.find((t) => t.type !== "null") || typeDef;
+      } else if (typeDef.oneOf && Array.isArray(typeDef.oneOf)) {
+        actualType = typeDef.oneOf.find((t) => t.type !== "null") || typeDef;
+      }
+    }
+    if (typeof actualType !== "object") {
+      return "uuid";
+    }
+    if (actualType.type === "integer") {
+      return "autoincrement";
+    }
+    return "uuid";
+  }
+  generateKeyValue(columnName, strategy) {
+    throw new Error(`generateKeyValue not implemented for ${this.constructor.name}. ` + `Column: ${columnName}, Strategy: ${strategy}`);
+  }
   async setupDatabase() {}
   destroy() {}
   async[Symbol.asyncDispose]() {
@@ -202,22 +240,67 @@ class TabularRepository {
     this.destroy();
   }
 }
+// src/tabular/CachedTabularStorage.ts
+import {
+  createServiceToken as createServiceToken3
+} from "@workglow/util";
 
-// src/tabular/InMemoryTabularRepository.ts
+// src/tabular/InMemoryTabularStorage.ts
+import {
+  createServiceToken as createServiceToken2,
+  makeFingerprint as makeFingerprint2,
+  uuid4
+} from "@workglow/util";
+
+// src/tabular/ITabularStorage.ts
+function isSearchCondition(value) {
+  return typeof value === "object" && value !== null && "value" in value && "operator" in value && typeof value.operator === "string";
+}
+
+// src/tabular/InMemoryTabularStorage.ts
 var MEMORY_TABULAR_REPOSITORY = createServiceToken2("storage.tabularRepository.inMemory");
 
-class InMemoryTabularRepository extends TabularRepository {
+class InMemoryTabularStorage extends BaseTabularStorage {
   values = new Map;
-  constructor(schema, primaryKeyNames, indexes = []) {
-    super(schema, primaryKeyNames, indexes);
+  autoIncrementCounter = 0;
+  constructor(schema, primaryKeyNames, indexes = [], clientProvidedKeys = "if-missing") {
+    super(schema, primaryKeyNames, indexes, clientProvidedKeys);
   }
   async setupDatabase() {}
+  generateKeyValue(columnName, strategy) {
+    if (strategy === "autoincrement") {
+      return ++this.autoIncrementCounter;
+    } else {
+      return uuid4();
+    }
+  }
   async put(value) {
-    const { key } = this.separateKeyValueFromCombined(value);
+    let entityToStore = value;
+    if (this.hasAutoGeneratedKey() && this.autoGeneratedKeyName) {
+      const keyName = this.autoGeneratedKeyName;
+      const clientProvidedValue = value[keyName];
+      const hasClientValue = clientProvidedValue !== undefined && clientProvidedValue !== null;
+      let shouldGenerate = false;
+      if (this.clientProvidedKeys === "never") {
+        shouldGenerate = true;
+      } else if (this.clientProvidedKeys === "always") {
+        if (!hasClientValue) {
+          throw new Error(`Auto-generated key "${keyName}" is required when clientProvidedKeys is "always"`);
+        }
+        shouldGenerate = false;
+      } else {
+        shouldGenerate = !hasClientValue;
+      }
+      if (shouldGenerate) {
+        const generatedValue = this.generateKeyValue(keyName, this.autoGeneratedKeyStrategy);
+        entityToStore = { ...value, [keyName]: generatedValue };
+      }
+    }
+    const { key } = this.separateKeyValueFromCombined(entityToStore);
     const id = await makeFingerprint2(key);
-    this.values.set(id, value);
-    this.events.emit("put", value);
-    return value;
+    this.values.set(id, entityToStore);
+    this.events.emit("put", entityToStore);
+    return entityToStore;
   }
   async putBulk(values) {
     return await Promise.all(values.map(async (value) => this.put(value)));
@@ -338,23 +421,23 @@ class InMemoryTabularRepository extends TabularRepository {
   }
 }
 
-// src/tabular/CachedTabularRepository.ts
+// src/tabular/CachedTabularStorage.ts
 var CACHED_TABULAR_REPOSITORY = createServiceToken3("storage.tabularRepository.cached");
 
-class CachedTabularRepository extends TabularRepository {
+class CachedTabularStorage extends BaseTabularStorage {
   cache;
   durable;
   cacheInitialized = false;
-  constructor(durable, cache, schema, primaryKeyNames, indexes) {
+  constructor(durable, cache, schema, primaryKeyNames, indexes, clientProvidedKeys = "if-missing") {
     if (!schema || !primaryKeyNames) {
-      throw new Error("Schema and primaryKeyNames must be provided when creating CachedTabularRepository");
+      throw new Error("Schema and primaryKeyNames must be provided when creating CachedTabularStorage");
     }
-    super(schema, primaryKeyNames, indexes || []);
+    super(schema, primaryKeyNames, indexes || [], clientProvidedKeys);
     this.durable = durable;
     if (cache) {
       this.cache = cache;
     } else {
-      this.cache = new InMemoryTabularRepository(schema, primaryKeyNames, indexes || []);
+      this.cache = new InMemoryTabularStorage(schema, primaryKeyNames, indexes || [], clientProvidedKeys);
     }
     this.setupEventForwarding();
   }
@@ -481,7 +564,36 @@ class CachedTabularRepository extends TabularRepository {
     this.cache.destroy();
   }
 }
-// src/kv/IKvRepository.ts
+// src/tabular/TabularStorageRegistry.ts
+import {
+  createServiceToken as createServiceToken4,
+  globalServiceRegistry,
+  registerInputResolver
+} from "@workglow/util";
+var TABULAR_REPOSITORIES = createServiceToken4("storage.tabular.repositories");
+if (!globalServiceRegistry.has(TABULAR_REPOSITORIES)) {
+  globalServiceRegistry.register(TABULAR_REPOSITORIES, () => new Map, true);
+}
+function getGlobalTabularRepositories() {
+  return globalServiceRegistry.get(TABULAR_REPOSITORIES);
+}
+function registerTabularRepository(id, repository) {
+  const repos = getGlobalTabularRepositories();
+  repos.set(id, repository);
+}
+function getTabularRepository(id) {
+  return getGlobalTabularRepositories().get(id);
+}
+function resolveRepositoryFromRegistry(id, format, registry) {
+  const repos = registry.has(TABULAR_REPOSITORIES) ? registry.get(TABULAR_REPOSITORIES) : getGlobalTabularRepositories();
+  const repo = repos.get(id);
+  if (!repo) {
+    throw new Error(`Tabular storage "${id}" not found in registry`);
+  }
+  return repo;
+}
+registerInputResolver("storage:tabular", resolveRepositoryFromRegistry);
+// src/kv/IKvStorage.ts
 var DefaultKeyValueSchema = {
   type: "object",
   properties: {
@@ -491,14 +603,14 @@ var DefaultKeyValueSchema = {
   additionalProperties: false
 };
 var DefaultKeyValueKey = ["key"];
-// src/kv/InMemoryKvRepository.ts
-import { createServiceToken as createServiceToken5 } from "@workglow/util";
+// src/kv/InMemoryKvStorage.ts
+import { createServiceToken as createServiceToken6 } from "@workglow/util";
 
-// src/kv/KvRepository.ts
-import { createServiceToken as createServiceToken4, EventEmitter as EventEmitter2, makeFingerprint as makeFingerprint3 } from "@workglow/util";
-var KV_REPOSITORY = createServiceToken4("storage.kvRepository");
+// src/kv/KvStorage.ts
+import { createServiceToken as createServiceToken5, EventEmitter as EventEmitter2, makeFingerprint as makeFingerprint3 } from "@workglow/util";
+var KV_REPOSITORY = createServiceToken5("storage.kvRepository");
 
-class KvRepository {
+class KvStorage {
   keySchema;
   valueSchema;
   events = new EventEmitter2;
@@ -526,8 +638,8 @@ class KvRepository {
   }
 }
 
-// src/kv/KvViaTabularRepository.ts
-class KvViaTabularRepository extends KvRepository {
+// src/kv/KvViaTabularStorage.ts
+class KvViaTabularStorage extends KvStorage {
   async setupDatabase() {
     await this.tabularRepository.setupDatabase?.();
   }
@@ -602,22 +714,22 @@ class KvViaTabularRepository extends KvRepository {
   }
 }
 
-// src/kv/InMemoryKvRepository.ts
-var MEMORY_KV_REPOSITORY = createServiceToken5("storage.kvRepository.inMemory");
+// src/kv/InMemoryKvStorage.ts
+var MEMORY_KV_REPOSITORY = createServiceToken6("storage.kvRepository.inMemory");
 
-class InMemoryKvRepository extends KvViaTabularRepository {
+class InMemoryKvStorage extends KvViaTabularStorage {
   tabularRepository;
   constructor(keySchema = { type: "string" }, valueSchema = {}) {
     super(keySchema, valueSchema);
-    this.tabularRepository = new InMemoryTabularRepository(DefaultKeyValueSchema, DefaultKeyValueKey);
+    this.tabularRepository = new InMemoryTabularStorage(DefaultKeyValueSchema, DefaultKeyValueKey);
   }
 }
 // src/queue/InMemoryQueueStorage.ts
-import { createServiceToken as createServiceToken7, EventEmitter as EventEmitter3, makeFingerprint as makeFingerprint4, sleep, uuid4 } from "@workglow/util";
+import { createServiceToken as createServiceToken8, EventEmitter as EventEmitter3, makeFingerprint as makeFingerprint4, sleep, uuid4 as uuid42 } from "@workglow/util";
 
 // src/queue/IQueueStorage.ts
-import { createServiceToken as createServiceToken6 } from "@workglow/util";
-var QUEUE_STORAGE = createServiceToken6("jobqueue.storage");
+import { createServiceToken as createServiceToken7 } from "@workglow/util";
+var QUEUE_STORAGE = createServiceToken7("jobqueue.storage");
 var JobStatus = {
   PENDING: "PENDING",
   PROCESSING: "PROCESSING",
@@ -628,7 +740,7 @@ var JobStatus = {
 };
 
 // src/queue/InMemoryQueueStorage.ts
-var IN_MEMORY_QUEUE_STORAGE = createServiceToken7("jobqueue.storage.inMemory");
+var IN_MEMORY_QUEUE_STORAGE = createServiceToken8("jobqueue.storage.inMemory");
 
 class InMemoryQueueStorage {
   queueName;
@@ -656,8 +768,8 @@ class InMemoryQueueStorage {
     await sleep(0);
     const now = new Date().toISOString();
     const jobWithPrefixes = job;
-    jobWithPrefixes.id = jobWithPrefixes.id ?? uuid4();
-    jobWithPrefixes.job_run_id = jobWithPrefixes.job_run_id ?? uuid4();
+    jobWithPrefixes.id = jobWithPrefixes.id ?? uuid42();
+    jobWithPrefixes.job_run_id = jobWithPrefixes.job_run_id ?? uuid42();
     jobWithPrefixes.queue = this.queueName;
     jobWithPrefixes.fingerprint = await makeFingerprint4(jobWithPrefixes.input);
     jobWithPrefixes.status = JobStatus.PENDING;
@@ -804,9 +916,9 @@ class InMemoryQueueStorage {
     return this.events.subscribe("change", filteredCallback);
   }
 }
-// src/limiter/InMemoryRateLimiterStorage.ts
-import { createServiceToken as createServiceToken8, sleep as sleep2 } from "@workglow/util";
-var IN_MEMORY_RATE_LIMITER_STORAGE = createServiceToken8("ratelimiter.storage.inMemory");
+// src/queue-limiter/InMemoryRateLimiterStorage.ts
+import { createServiceToken as createServiceToken9, sleep as sleep2 } from "@workglow/util";
+var IN_MEMORY_RATE_LIMITER_STORAGE = createServiceToken9("ratelimiter.storage.inMemory");
 
 class InMemoryRateLimiterStorage {
   prefixValues;
@@ -863,9 +975,9 @@ class InMemoryRateLimiterStorage {
     this.nextAvailableTimes.delete(key);
   }
 }
-// src/limiter/IRateLimiterStorage.ts
-import { createServiceToken as createServiceToken9 } from "@workglow/util";
-var RATE_LIMITER_STORAGE = createServiceToken9("ratelimiter.storage");
+// src/queue-limiter/IRateLimiterStorage.ts
+import { createServiceToken as createServiceToken10 } from "@workglow/util";
+var RATE_LIMITER_STORAGE = createServiceToken10("ratelimiter.storage");
 // src/util/HybridSubscriptionManager.ts
 class HybridSubscriptionManager {
   subscribers = new Set;
@@ -1139,21 +1251,141 @@ class PollingSubscriptionManager {
     this.initialized = false;
   }
 }
-// src/tabular/FsFolderTabularRepository.ts
+// src/vector/InMemoryVectorStorage.ts
+import { cosineSimilarity } from "@workglow/util";
+
+// src/vector/IVectorStorage.ts
+function getVectorProperty(schema) {
+  for (const [key, value] of Object.entries(schema.properties)) {
+    if (typeof value !== "boolean" && value.type === "array" && (value.format === "TypedArray" || value.format?.startsWith("TypedArray:"))) {
+      return key;
+    }
+  }
+  return;
+}
+function getMetadataProperty(schema) {
+  for (const [key, value] of Object.entries(schema.properties)) {
+    if (typeof value !== "boolean" && value.type === "object" && value.format === "metadata") {
+      return key;
+    }
+  }
+  return;
+}
+
+// src/vector/InMemoryVectorStorage.ts
+function matchesFilter(metadata, filter) {
+  for (const [key, value] of Object.entries(filter)) {
+    if (metadata[key] !== value) {
+      return false;
+    }
+  }
+  return true;
+}
+function textRelevance(text, query) {
+  const textLower = text.toLowerCase();
+  const queryLower = query.toLowerCase();
+  const queryWords = queryLower.split(/\s+/).filter((w) => w.length > 0);
+  if (queryWords.length === 0) {
+    return 0;
+  }
+  let matches = 0;
+  for (const word of queryWords) {
+    if (textLower.includes(word)) {
+      matches++;
+    }
+  }
+  return matches / queryWords.length;
+}
+
+class InMemoryVectorStorage extends InMemoryTabularStorage {
+  vectorDimensions;
+  VectorType;
+  vectorPropertyName;
+  metadataPropertyName;
+  constructor(schema, primaryKeyNames, indexes = [], dimensions, VectorType = Float32Array) {
+    super(schema, primaryKeyNames, indexes);
+    this.vectorDimensions = dimensions;
+    this.VectorType = VectorType;
+    const vectorProp = getVectorProperty(schema);
+    if (!vectorProp) {
+      throw new Error("Schema must have a property with type array and format TypedArray");
+    }
+    this.vectorPropertyName = vectorProp;
+    this.metadataPropertyName = getMetadataProperty(schema);
+  }
+  getVectorDimensions() {
+    return this.vectorDimensions;
+  }
+  async similaritySearch(query, options = {}) {
+    const { topK = 10, filter, scoreThreshold = 0 } = options;
+    const results = [];
+    const allEntities = await this.getAll() || [];
+    for (const entity of allEntities) {
+      const vector = entity[this.vectorPropertyName];
+      const metadata = this.metadataPropertyName ? entity[this.metadataPropertyName] : {};
+      if (filter && !matchesFilter(metadata, filter)) {
+        continue;
+      }
+      const score = cosineSimilarity(query, vector);
+      if (score < scoreThreshold) {
+        continue;
+      }
+      results.push({
+        ...entity,
+        score
+      });
+    }
+    results.sort((a, b) => b.score - a.score);
+    const topResults = results.slice(0, topK);
+    return topResults;
+  }
+  async hybridSearch(query, options) {
+    const { topK = 10, filter, scoreThreshold = 0, textQuery, vectorWeight = 0.7 } = options;
+    if (!textQuery || textQuery.trim().length === 0) {
+      return this.similaritySearch(query, { topK, filter, scoreThreshold });
+    }
+    const results = [];
+    const allEntities = await this.getAll() || [];
+    for (const entity of allEntities) {
+      const vector = entity[this.vectorPropertyName];
+      const metadata = this.metadataPropertyName ? entity[this.metadataPropertyName] : {};
+      if (filter && !matchesFilter(metadata, filter)) {
+        continue;
+      }
+      const vectorScore = cosineSimilarity(query, vector);
+      const metadataText = Object.values(metadata).join(" ").toLowerCase();
+      const textScore = textRelevance(metadataText, textQuery);
+      const combinedScore = vectorWeight * vectorScore + (1 - vectorWeight) * textScore;
+      if (combinedScore < scoreThreshold) {
+        continue;
+      }
+      results.push({
+        ...entity,
+        score: combinedScore
+      });
+    }
+    results.sort((a, b) => b.score - a.score);
+    const topResults = results.slice(0, topK);
+    return topResults;
+  }
+}
+// src/tabular/FsFolderTabularStorage.ts
 import {
-  createServiceToken as createServiceToken10,
+  createServiceToken as createServiceToken11,
   makeFingerprint as makeFingerprint5,
-  sleep as sleep3
+  sleep as sleep3,
+  uuid4 as uuid43
 } from "@workglow/util";
 import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
-var FS_FOLDER_TABULAR_REPOSITORY = createServiceToken10("storage.tabularRepository.fsFolder");
+var FS_FOLDER_TABULAR_REPOSITORY = createServiceToken11("storage.tabularRepository.fsFolder");
 
-class FsFolderTabularRepository extends TabularRepository {
+class FsFolderTabularStorage extends BaseTabularStorage {
   folderPath;
+  autoIncrementCounter = 0;
   pollingManager = null;
-  constructor(folderPath, schema, primaryKeyNames, indexes = []) {
-    super(schema, primaryKeyNames, indexes);
+  constructor(folderPath, schema, primaryKeyNames, indexes = [], clientProvidedKeys = "if-missing") {
+    super(schema, primaryKeyNames, indexes, clientProvidedKeys);
     this.folderPath = path.join(folderPath);
   }
   async setupDirectory() {
@@ -1166,11 +1398,39 @@ class FsFolderTabularRepository extends TabularRepository {
       } catch {}
     }
   }
+  generateKeyValue(columnName, strategy) {
+    if (strategy === "autoincrement") {
+      return ++this.autoIncrementCounter;
+    } else {
+      return uuid43();
+    }
+  }
   async put(entity) {
+    let entityToStore = entity;
+    if (this.hasAutoGeneratedKey() && this.autoGeneratedKeyName) {
+      const keyName = this.autoGeneratedKeyName;
+      const clientProvidedValue = entity[keyName];
+      const hasClientValue = clientProvidedValue !== undefined && clientProvidedValue !== null;
+      let shouldGenerate = false;
+      if (this.clientProvidedKeys === "never") {
+        shouldGenerate = true;
+      } else if (this.clientProvidedKeys === "always") {
+        if (!hasClientValue) {
+          throw new Error(`Auto-generated key "${keyName}" is required when clientProvidedKeys is "always"`);
+        }
+        shouldGenerate = false;
+      } else {
+        shouldGenerate = !hasClientValue;
+      }
+      if (shouldGenerate) {
+        const generatedValue = this.generateKeyValue(keyName, this.autoGeneratedKeyStrategy);
+        entityToStore = { ...entity, [keyName]: generatedValue };
+      }
+    }
     await this.setupDirectory();
-    const filePath = await this.getFilePath(entity);
+    const filePath = await this.getFilePath(entityToStore);
     try {
-      await writeFile(filePath, JSON.stringify(entity));
+      await writeFile(filePath, JSON.stringify(entityToStore));
     } catch (error) {
       try {
         await sleep3(1);
@@ -1179,8 +1439,8 @@ class FsFolderTabularRepository extends TabularRepository {
         console.error("Error writing file", filePath, error2);
       }
     }
-    this.events.emit("put", entity);
-    return entity;
+    this.events.emit("put", entityToStore);
+    return entityToStore;
   }
   async putBulk(entities) {
     await this.setupDirectory();
@@ -1244,7 +1504,7 @@ class FsFolderTabularRepository extends TabularRepository {
     return jsonFiles.length;
   }
   async search(key) {
-    throw new Error("Search not supported for FsFolderTabularRepository");
+    throw new Error("Search not supported for FsFolderTabularStorage");
   }
   async getFilePath(value) {
     const { key } = this.separateKeyValueFromCombined(value);
@@ -1253,7 +1513,7 @@ class FsFolderTabularRepository extends TabularRepository {
     return fullPath;
   }
   async deleteSearch(_criteria) {
-    throw new Error("deleteSearch is not supported for FsFolderTabularRepository");
+    throw new Error("deleteSearch is not supported for FsFolderTabularStorage");
   }
   getPollingManager() {
     if (!this.pollingManager) {
@@ -1287,14 +1547,16 @@ class FsFolderTabularRepository extends TabularRepository {
     super.destroy();
   }
 }
-// src/tabular/PostgresTabularRepository.ts
-import { createServiceToken as createServiceToken11 } from "@workglow/util";
+// src/tabular/PostgresTabularStorage.ts
+import {
+  createServiceToken as createServiceToken12
+} from "@workglow/util";
 
-// src/tabular/BaseSqlTabularRepository.ts
-class BaseSqlTabularRepository extends TabularRepository {
+// src/tabular/BaseSqlTabularStorage.ts
+class BaseSqlTabularStorage extends BaseTabularStorage {
   table;
-  constructor(table = "tabular_store", schema, primaryKeyNames, indexes = []) {
-    super(schema, primaryKeyNames, indexes);
+  constructor(table = "tabular_store", schema, primaryKeyNames, indexes = [], clientProvidedKeys = "if-missing") {
+    super(schema, primaryKeyNames, indexes, clientProvidedKeys);
     this.table = table;
     this.validateTableAndSchema();
   }
@@ -1473,13 +1735,13 @@ class BaseSqlTabularRepository extends TabularRepository {
   }
 }
 
-// src/tabular/PostgresTabularRepository.ts
-var POSTGRES_TABULAR_REPOSITORY = createServiceToken11("storage.tabularRepository.postgres");
+// src/tabular/PostgresTabularStorage.ts
+var POSTGRES_TABULAR_REPOSITORY = createServiceToken12("storage.tabularRepository.postgres");
 
-class PostgresTabularRepository extends BaseSqlTabularRepository {
+class PostgresTabularStorage extends BaseSqlTabularStorage {
   db;
-  constructor(db, table = "tabular_store", schema, primaryKeyNames, indexes = []) {
-    super(table, schema, primaryKeyNames, indexes);
+  constructor(db, table = "tabular_store", schema, primaryKeyNames, indexes = [], clientProvidedKeys = "if-missing") {
+    super(table, schema, primaryKeyNames, indexes, clientProvidedKeys);
     this.db = db;
   }
   async setupDatabase() {
@@ -1490,6 +1752,7 @@ class PostgresTabularRepository extends BaseSqlTabularRepository {
       )
     `;
     await this.db.query(sql);
+    await this.createVectorIndexes();
     const pkColumns = this.primaryKeyColumns();
     const createdIndexes = new Set;
     for (const columns of this.indexes) {
@@ -1513,6 +1776,14 @@ class PostgresTabularRepository extends BaseSqlTabularRepository {
       }
     }
   }
+  isVectorFormat(format) {
+    if (!format)
+      return false;
+    return format.startsWith("TypedArray:") || format === "TypedArray";
+  }
+  getVectorDimensions(typeDef) {
+    return;
+  }
   mapTypeToSQL(typeDef) {
     const actualType = this.getNonNullType(typeDef);
     if (typeof actualType === "boolean") {
@@ -1532,6 +1803,12 @@ class PostgresTabularRepository extends BaseSqlTabularRepository {
           return "VARCHAR(2048)";
         if (actualType.format === "uuid")
           return "UUID";
+        if (this.isVectorFormat(actualType.format)) {
+          const dimension = this.getVectorDimensions(actualType);
+          if (typeof dimension === "number") {
+            return `vector(${dimension})`;
+          }
+        }
         if (typeof actualType.maxLength === "number") {
           return `VARCHAR(${actualType.maxLength})`;
         }
@@ -1599,6 +1876,17 @@ class PostgresTabularRepository extends BaseSqlTabularRepository {
   }
   constructPrimaryKeyColumns($delimiter = "") {
     const cols = Object.entries(this.primaryKeySchema.properties).map(([key, typeDef]) => {
+      if (this.isAutoGeneratedKey(key)) {
+        if (this.autoGeneratedKeyStrategy === "autoincrement") {
+          const sqlType2 = this.mapTypeToSQL(typeDef);
+          const isSmallInt = sqlType2.includes("SMALLINT");
+          const isBigInt = sqlType2.includes("BIGINT");
+          const serialType = isBigInt ? "BIGSERIAL" : isSmallInt ? "SMALLSERIAL" : "SERIAL";
+          return `${$delimiter}${key}${$delimiter} ${serialType}`;
+        } else if (this.autoGeneratedKeyStrategy === "uuid") {
+          return `${$delimiter}${key}${$delimiter} UUID DEFAULT gen_random_uuid()`;
+        }
+      }
       const sqlType = this.mapTypeToSQL(typeDef);
       let constraints = "NOT NULL";
       if (this.shouldBeUnsigned(typeDef)) {
@@ -1626,6 +1914,22 @@ class PostgresTabularRepository extends BaseSqlTabularRepository {
       return "";
     }
   }
+  jsToSqlValue(column, value) {
+    const typeDef = this.schema.properties[column];
+    if (typeDef) {
+      const actualType = this.getNonNullType(typeDef);
+      if (typeof actualType !== "boolean" && this.isVectorFormat(actualType.format)) {
+        if (value && ArrayBuffer.isView(value) && !(value instanceof DataView)) {
+          const array = Array.from(value);
+          return `[${array.join(",")}]`;
+        }
+        if (typeof value === "string") {
+          return value;
+        }
+      }
+    }
+    return super.jsToSqlValue(column, value);
+  }
   sqlToJsValue(column, value) {
     const typeDef = this.schema.properties[column];
     if (typeDef) {
@@ -1633,6 +1937,19 @@ class PostgresTabularRepository extends BaseSqlTabularRepository {
         return null;
       }
       const actualType = this.getNonNullType(typeDef);
+      if (typeof actualType !== "boolean" && this.isVectorFormat(actualType.format)) {
+        if (typeof value === "string") {
+          try {
+            const array = JSON.parse(value);
+            return new Float32Array(array);
+          } catch (e) {
+            console.warn(`Failed to parse vector for column ${column}:`, e);
+          }
+        }
+        if (value && typeof value === "object") {
+          return value;
+        }
+      }
       if (typeof actualType !== "boolean" && (actualType.type === "number" || actualType.type === "integer")) {
         const v = value;
         if (typeof v === "number")
@@ -1656,30 +1973,105 @@ class PostgresTabularRepository extends BaseSqlTabularRepository {
     }
     return false;
   }
+  getVectorColumns() {
+    const vectorColumns = [];
+    for (const [key, typeDef] of Object.entries(this.schema.properties)) {
+      const actualType = this.getNonNullType(typeDef);
+      if (typeof actualType !== "boolean" && this.isVectorFormat(actualType.format)) {
+        const dimension = this.getVectorDimensions(actualType);
+        if (typeof dimension === "number") {
+          vectorColumns.push({ column: key, dimension });
+        } else {
+          console.warn(`Invalid vector format for column ${key}: ${actualType.format}, skipping`);
+        }
+      }
+    }
+    return vectorColumns;
+  }
+  async createVectorIndexes() {
+    const vectorColumns = this.getVectorColumns();
+    if (vectorColumns.length === 0) {
+      return;
+    }
+    try {
+      await this.db.query("CREATE EXTENSION IF NOT EXISTS vector");
+    } catch (error) {
+      console.warn("pgvector extension not available, vector columns will use TEXT fallback:", error);
+      return;
+    }
+    for (const { column } of vectorColumns) {
+      const indexName = `${this.table}_${column}_hnsw_idx`;
+      try {
+        await this.db.query(`
+          CREATE INDEX IF NOT EXISTS "${indexName}"
+          ON "${this.table}"
+          USING hnsw ("${column}" vector_cosine_ops)
+        `);
+      } catch (error) {
+        console.warn(`Failed to create HNSW index on ${column}:`, error);
+      }
+    }
+  }
   async put(entity) {
     const db = this.db;
-    const { key, value } = this.separateKeyValueFromCombined(entity);
-    const sql = `
-      INSERT INTO "${this.table}" (
-        ${this.primaryKeyColumnList('"')} ${this.valueColumnList() ? ", " + this.valueColumnList('"') : ""}
-      )
-      VALUES (
-        ${[...this.primaryKeyColumns(), ...this.valueColumns()].map((_, i) => `$${i + 1}`).join(", ")}
-      )
-      ${!this.valueColumnList() ? "" : `
+    const columnsToInsert = [];
+    const paramsToInsert = [];
+    let paramIndex = 1;
+    const pkColumns = this.primaryKeyColumns();
+    for (const col of pkColumns) {
+      const colStr = String(col);
+      if (this.isAutoGeneratedKey(colStr)) {
+        const clientProvidedValue = entity[col];
+        const hasClientValue = clientProvidedValue !== undefined && clientProvidedValue !== null;
+        let shouldUseClientValue = false;
+        if (this.clientProvidedKeys === "never") {
+          shouldUseClientValue = false;
+        } else if (this.clientProvidedKeys === "always") {
+          if (!hasClientValue) {
+            throw new Error(`Auto-generated key "${colStr}" is required when clientProvidedKeys is "always"`);
+          }
+          shouldUseClientValue = true;
+        } else {
+          shouldUseClientValue = hasClientValue;
+        }
+        if (shouldUseClientValue) {
+          columnsToInsert.push(colStr);
+          paramsToInsert.push(this.jsToSqlValue(colStr, clientProvidedValue));
+        }
+        continue;
+      }
+      columnsToInsert.push(colStr);
+      const value = entity[col];
+      paramsToInsert.push(this.jsToSqlValue(colStr, value));
+    }
+    const valueColumns = this.valueColumns();
+    for (const col of valueColumns) {
+      const colStr = String(col);
+      columnsToInsert.push(colStr);
+      const value = entity[col];
+      paramsToInsert.push(this.jsToSqlValue(colStr, value));
+    }
+    const columnList = columnsToInsert.map((c) => `"${c}"`).join(", ");
+    const placeholders = columnsToInsert.map((_, i) => `$${i + 1}`).join(", ");
+    const conflictClause = valueColumns.length > 0 ? `
       ON CONFLICT (${this.primaryKeyColumnList('"')}) DO UPDATE
       SET 
-      ${this.valueColumns().map((col, i) => `"${col}" = $${i + this.primaryKeyColumns().length + 1}`).join(", ")}
-      `}
+      ${valueColumns.map((col) => {
+      const colIdx = columnsToInsert.indexOf(String(col));
+      return `"${col}" = $${colIdx + 1}`;
+    }).join(", ")}
+      ` : "";
+    const sql = `
+      INSERT INTO "${this.table}" (${columnList})
+      VALUES (${placeholders})
+      ${conflictClause}
       RETURNING *
     `;
-    const primaryKeyParams = this.getPrimaryKeyAsOrderedArray(key);
-    const valueParams = this.getValueAsOrderedArray(value);
-    const params = [...primaryKeyParams, ...valueParams];
+    const params = paramsToInsert;
     const result = await db.query(sql, params);
     const updatedEntity = result.rows[0];
-    for (const key2 in this.schema.properties) {
-      updatedEntity[key2] = this.sqlToJsValue(key2, updatedEntity[key2]);
+    for (const key in this.schema.properties) {
+      updatedEntity[key] = this.sqlToJsValue(key, updatedEntity[key]);
     }
     this.events.emit("put", updatedEntity);
     return updatedEntity;
@@ -1687,45 +2079,7 @@ class PostgresTabularRepository extends BaseSqlTabularRepository {
   async putBulk(entities) {
     if (entities.length === 0)
       return [];
-    const db = this.db;
-    const allParams = [];
-    const valuesPerRow = this.primaryKeyColumns().length + this.valueColumns().length;
-    let paramIndex = 1;
-    const valuesClauses = entities.map((entity) => {
-      const { key, value } = this.separateKeyValueFromCombined(entity);
-      const primaryKeyParams = this.getPrimaryKeyAsOrderedArray(key);
-      const valueParams = this.getValueAsOrderedArray(value);
-      const entityParams = [...primaryKeyParams, ...valueParams];
-      allParams.push(...entityParams);
-      const placeholders = Array(valuesPerRow).fill(0).map(() => `$${paramIndex++}`).join(", ");
-      return `(${placeholders})`;
-    }).join(", ");
-    const sql = `
-      INSERT INTO "${this.table}" (
-        ${this.primaryKeyColumnList('"')} ${this.valueColumnList() ? ", " + this.valueColumnList('"') : ""}
-      )
-      VALUES ${valuesClauses}
-      ${!this.valueColumnList() ? "" : `
-      ON CONFLICT (${this.primaryKeyColumnList('"')}) DO UPDATE
-      SET 
-      ${this.valueColumns().map((col) => {
-      return `"${col}" = EXCLUDED."${col}"`;
-    }).join(", ")}
-      `}
-      RETURNING *
-    `;
-    const result = await db.query(sql, allParams);
-    const updatedEntities = result.rows.map((row) => {
-      const entity = row;
-      for (const key in this.schema.properties) {
-        entity[key] = this.sqlToJsValue(key, entity[key]);
-      }
-      return entity;
-    });
-    for (const entity of updatedEntities) {
-      this.events.emit("put", entity);
-    }
-    return updatedEntities;
+    return await Promise.all(entities.map((entity) => this.put(entity)));
   }
   async get(key) {
     const db = this.db;
@@ -1846,35 +2200,53 @@ class PostgresTabularRepository extends BaseSqlTabularRepository {
     this.events.emit("delete", criteriaKeys[0]);
   }
   subscribeToChanges(callback, options) {
-    throw new Error("subscribeToChanges is not supported for PostgresTabularRepository");
+    throw new Error("subscribeToChanges is not supported for PostgresTabularStorage");
   }
   destroy() {
     super.destroy();
   }
 }
-// src/tabular/SqliteTabularRepository.ts
+// src/tabular/SqliteTabularStorage.ts
 import { Sqlite } from "@workglow/sqlite";
-import { createServiceToken as createServiceToken12 } from "@workglow/util";
-var SQLITE_TABULAR_REPOSITORY = createServiceToken12("storage.tabularRepository.sqlite");
+import {
+  createServiceToken as createServiceToken13,
+  uuid4 as uuid44
+} from "@workglow/util";
+var SQLITE_TABULAR_REPOSITORY = createServiceToken13("storage.tabularRepository.sqlite");
 var Database = Sqlite.Database;
 
-class SqliteTabularRepository extends BaseSqlTabularRepository {
+class SqliteTabularStorage extends BaseSqlTabularStorage {
   db;
-  constructor(dbOrPath, table = "tabular_store", schema, primaryKeyNames, indexes = []) {
-    super(table, schema, primaryKeyNames, indexes);
+  constructor(dbOrPath, table = "tabular_store", schema, primaryKeyNames, indexes = [], clientProvidedKeys = "if-missing") {
+    super(table, schema, primaryKeyNames, indexes, clientProvidedKeys);
     if (typeof dbOrPath === "string") {
       this.db = new Database(dbOrPath);
     } else {
       this.db = dbOrPath;
     }
   }
+  constructPrimaryKeyColumns($delimiter = "") {
+    const cols = Object.entries(this.primaryKeySchema.properties).map(([key, typeDef]) => {
+      if (this.isAutoGeneratedKey(key) && this.autoGeneratedKeyStrategy === "autoincrement") {
+        return `${$delimiter}${key}${$delimiter} INTEGER PRIMARY KEY AUTOINCREMENT`;
+      }
+      const sqlType = this.mapTypeToSQL(typeDef);
+      return `${$delimiter}${key}${$delimiter} ${sqlType} NOT NULL`;
+    }).join(", ");
+    return cols;
+  }
   async setupDatabase() {
-    const sql = `
-      CREATE TABLE IF NOT EXISTS \`${this.table}\` (
-        ${this.constructPrimaryKeyColumns()} ${this.constructValueColumns()},
-        PRIMARY KEY (${this.primaryKeyColumnList()}) 
-      )
-    `;
+    const hasAutoIncrementKey = this.hasAutoGeneratedKey() && this.autoGeneratedKeyStrategy === "autoincrement";
+    const sql = hasAutoIncrementKey ? `
+        CREATE TABLE IF NOT EXISTS \`${this.table}\` (
+          ${this.constructPrimaryKeyColumns()} ${this.constructValueColumns()}
+        )
+      ` : `
+        CREATE TABLE IF NOT EXISTS \`${this.table}\` (
+          ${this.constructPrimaryKeyColumns()} ${this.constructValueColumns()},
+          PRIMARY KEY (${this.primaryKeyColumnList()}) 
+        )
+      `;
     this.db.exec(sql);
     const pkColumns = this.primaryKeyColumns();
     const createdIndexes = new Set;
@@ -2015,21 +2387,71 @@ class SqliteTabularRepository extends BaseSqlTabularRepository {
         return "TEXT /* unknown type */";
     }
   }
+  generateKeyValue(columnName, strategy) {
+    if (strategy === "uuid") {
+      return uuid44();
+    }
+    throw new Error(`SQLite autoincrement keys are generated by the database, not client-side. Column: ${columnName}`);
+  }
   async put(entity) {
     const db = this.db;
-    const { key, value } = this.separateKeyValueFromCombined(entity);
+    let entityToInsert = entity;
+    if (this.hasAutoGeneratedKey() && this.autoGeneratedKeyName) {
+      const keyName = String(this.autoGeneratedKeyName);
+      const clientProvidedValue = entity[keyName];
+      const hasClientValue = clientProvidedValue !== undefined && clientProvidedValue !== null;
+      let shouldUseClientValue = false;
+      if (this.clientProvidedKeys === "never") {
+        shouldUseClientValue = false;
+      } else if (this.clientProvidedKeys === "always") {
+        if (!hasClientValue) {
+          throw new Error(`Auto-generated key "${keyName}" is required when clientProvidedKeys is "always"`);
+        }
+        shouldUseClientValue = true;
+      } else {
+        shouldUseClientValue = hasClientValue;
+      }
+      if (this.autoGeneratedKeyStrategy === "uuid" && !shouldUseClientValue) {
+        const generatedValue = this.generateKeyValue(keyName, "uuid");
+        entityToInsert = { ...entity, [keyName]: generatedValue };
+      } else if (this.autoGeneratedKeyStrategy === "uuid" && shouldUseClientValue) {
+        entityToInsert = entity;
+      }
+    }
+    let columnsToInsert = [];
+    let paramsToInsert = [];
+    const pkColumns = this.primaryKeyColumns();
+    for (const col of pkColumns) {
+      const colStr = String(col);
+      if (this.isAutoGeneratedKey(colStr) && this.autoGeneratedKeyStrategy === "autoincrement" && this.clientProvidedKeys !== "always") {
+        const clientProvidedValue = entityToInsert[colStr];
+        const hasClientValue = clientProvidedValue !== undefined && clientProvidedValue !== null;
+        if (this.clientProvidedKeys === "if-missing" && hasClientValue) {
+          columnsToInsert.push(colStr);
+          paramsToInsert.push(this.jsToSqlValue(colStr, clientProvidedValue));
+        }
+        continue;
+      }
+      columnsToInsert.push(colStr);
+      const value = entityToInsert[colStr];
+      paramsToInsert.push(this.jsToSqlValue(colStr, value));
+    }
+    const valueColumns = this.valueColumns();
+    for (const col of valueColumns) {
+      const colStr = String(col);
+      columnsToInsert.push(colStr);
+      const value = entityToInsert[colStr];
+      paramsToInsert.push(this.jsToSqlValue(colStr, value));
+    }
+    const columnList = columnsToInsert.map((c) => `\`${c}\``).join(", ");
+    const placeholders = columnsToInsert.map(() => "?").join(", ");
     const sql = `
-      INSERT OR REPLACE INTO \`${this.table}\` (${this.primaryKeyColumnList()} ${this.valueColumnList() ? ", " + this.valueColumnList() : ""})
-      VALUES (
-        ${this.primaryKeyColumns().map((i) => "?")}
-        ${this.valueColumns().length > 0 ? ", " + this.valueColumns().map((i) => "?") : ""}
-      )
+      INSERT OR REPLACE INTO \`${this.table}\` (${columnList})
+      VALUES (${placeholders})
       RETURNING *
     `;
     const stmt = db.prepare(sql);
-    const primaryKeyParams = this.getPrimaryKeyAsOrderedArray(key);
-    const valueParams = this.getValueAsOrderedArray(value);
-    const params = [...primaryKeyParams, ...valueParams];
+    const params = paramsToInsert;
     for (let i = 0;i < params.length; i++) {
       let param = params[i];
       if (param === undefined) {
@@ -2084,46 +2506,7 @@ class SqliteTabularRepository extends BaseSqlTabularRepository {
   async putBulk(entities) {
     if (entities.length === 0)
       return [];
-    const db = this.db;
-    const updatedEntities = [];
-    const transaction = db.transaction((entitiesToInsert) => {
-      for (const entity of entitiesToInsert) {
-        const { key, value } = this.separateKeyValueFromCombined(entity);
-        const sql = `
-          INSERT OR REPLACE INTO \`${this.table}\` (${this.primaryKeyColumnList()} ${this.valueColumnList() ? ", " + this.valueColumnList() : ""})
-          VALUES (
-            ${this.primaryKeyColumns().map(() => "?").join(", ")}
-            ${this.valueColumns().length > 0 ? ", " + this.valueColumns().map(() => "?").join(", ") : ""}
-          )
-          RETURNING *
-        `;
-        const stmt = db.prepare(sql);
-        const primaryKeyParams = this.getPrimaryKeyAsOrderedArray(key);
-        const valueParams = this.getValueAsOrderedArray(value);
-        const params = [...primaryKeyParams, ...valueParams];
-        for (let i = 0;i < params.length; i++) {
-          let param = params[i];
-          if (param === undefined) {
-            params[i] = null;
-          } else if (param !== null && typeof param === "object") {
-            const paramObj = param;
-            if (!(paramObj instanceof Uint8Array) && (typeof Buffer === "undefined" || !(paramObj instanceof Buffer))) {
-              params[i] = JSON.stringify(paramObj);
-            }
-          }
-        }
-        const updatedEntity = stmt.get(...params);
-        for (const k in this.schema.properties) {
-          updatedEntity[k] = this.sqlToJsValue(k, updatedEntity[k]);
-        }
-        updatedEntities.push(updatedEntity);
-      }
-    });
-    transaction(entities);
-    for (const entity of updatedEntities) {
-      this.events.emit("put", entity);
-    }
-    return updatedEntities;
+    return await Promise.all(entities.map((entity) => this.put(entity)));
   }
   async get(key) {
     const db = this.db;
@@ -2248,21 +2631,23 @@ class SqliteTabularRepository extends BaseSqlTabularRepository {
     this.events.emit("delete", criteriaKeys[0]);
   }
   subscribeToChanges(callback, options) {
-    throw new Error("subscribeToChanges is not supported for SqliteTabularRepository");
+    throw new Error("subscribeToChanges is not supported for SqliteTabularStorage");
   }
   destroy() {
     super.destroy();
   }
 }
-// src/tabular/SupabaseTabularRepository.ts
-import { createServiceToken as createServiceToken13 } from "@workglow/util";
-var SUPABASE_TABULAR_REPOSITORY = createServiceToken13("storage.tabularRepository.supabase");
+// src/tabular/SupabaseTabularStorage.ts
+import {
+  createServiceToken as createServiceToken14
+} from "@workglow/util";
+var SUPABASE_TABULAR_REPOSITORY = createServiceToken14("storage.tabularRepository.supabase");
 
-class SupabaseTabularRepository extends BaseSqlTabularRepository {
+class SupabaseTabularStorage extends BaseSqlTabularStorage {
   client;
   realtimeChannel = null;
-  constructor(client, table = "tabular_store", schema, primaryKeyNames, indexes = []) {
-    super(table, schema, primaryKeyNames, indexes);
+  constructor(client, table = "tabular_store", schema, primaryKeyNames, indexes = [], clientProvidedKeys = "if-missing") {
+    super(table, schema, primaryKeyNames, indexes, clientProvidedKeys);
     this.client = client;
   }
   async setupDatabase() {
@@ -2389,6 +2774,17 @@ class SupabaseTabularRepository extends BaseSqlTabularRepository {
   }
   constructPrimaryKeyColumns($delimiter = "") {
     const cols = Object.entries(this.primaryKeySchema.properties).map(([key, typeDef]) => {
+      if (this.isAutoGeneratedKey(key)) {
+        if (this.autoGeneratedKeyStrategy === "autoincrement") {
+          const sqlType2 = this.mapTypeToSQL(typeDef);
+          const isSmallInt = sqlType2.includes("SMALLINT");
+          const isBigInt = sqlType2.includes("BIGINT");
+          const serialType = isBigInt ? "BIGSERIAL" : isSmallInt ? "SMALLSERIAL" : "SERIAL";
+          return `${$delimiter}${key}${$delimiter} ${serialType}`;
+        } else if (this.autoGeneratedKeyStrategy === "uuid") {
+          return `${$delimiter}${key}${$delimiter} UUID DEFAULT gen_random_uuid()`;
+        }
+      }
       const sqlType = this.mapTypeToSQL(typeDef);
       let constraints = "NOT NULL";
       if (this.shouldBeUnsigned(typeDef)) {
@@ -2448,7 +2844,27 @@ class SupabaseTabularRepository extends BaseSqlTabularRepository {
     return false;
   }
   async put(entity) {
-    const normalizedEntity = { ...entity };
+    let entityToInsert = { ...entity };
+    if (this.hasAutoGeneratedKey() && this.autoGeneratedKeyName) {
+      const keyName = String(this.autoGeneratedKeyName);
+      const clientProvidedValue = entity[keyName];
+      const hasClientValue = clientProvidedValue !== undefined && clientProvidedValue !== null;
+      let shouldOmitKey = false;
+      if (this.clientProvidedKeys === "never") {
+        shouldOmitKey = true;
+      } else if (this.clientProvidedKeys === "always") {
+        if (!hasClientValue) {
+          throw new Error(`Auto-generated key "${keyName}" is required when clientProvidedKeys is "always"`);
+        }
+        shouldOmitKey = false;
+      } else {
+        shouldOmitKey = !hasClientValue;
+      }
+      if (shouldOmitKey) {
+        delete entityToInsert[keyName];
+      }
+    }
+    const normalizedEntity = { ...entityToInsert };
     const requiredSet = new Set(this.valueSchema.required ?? []);
     for (const key in this.valueSchema.properties) {
       if (!(key in normalizedEntity) || normalizedEntity[key] === undefined) {
@@ -2470,29 +2886,7 @@ class SupabaseTabularRepository extends BaseSqlTabularRepository {
   async putBulk(entities) {
     if (entities.length === 0)
       return [];
-    const requiredSet = new Set(this.valueSchema.required ?? []);
-    const normalizedEntities = entities.map((entity) => {
-      const normalized = { ...entity };
-      for (const key in this.valueSchema.properties) {
-        if (!(key in normalized) || normalized[key] === undefined) {
-          if (!requiredSet.has(key)) {
-            normalized[key] = null;
-          }
-        }
-      }
-      return normalized;
-    });
-    const { data, error } = await this.client.from(this.table).upsert(normalizedEntities, { onConflict: this.primaryKeyColumnList() }).select();
-    if (error)
-      throw error;
-    const updatedEntities = data;
-    for (const entity of updatedEntities) {
-      for (const key in this.schema.properties) {
-        entity[key] = this.sqlToJsValue(key, entity[key]);
-      }
-      this.events.emit("put", entity);
-    }
-    return updatedEntities;
+    return await Promise.all(entities.map((entity) => this.put(entity)));
   }
   async get(key) {
     let query = this.client.from(this.table).select("*");
@@ -2665,26 +3059,26 @@ class SupabaseTabularRepository extends BaseSqlTabularRepository {
     }
   }
 }
-// src/kv/FsFolderJsonKvRepository.ts
-import { createServiceToken as createServiceToken14 } from "@workglow/util";
-var FS_FOLDER_JSON_KV_REPOSITORY = createServiceToken14("storage.kvRepository.fsFolderJson");
+// src/kv/FsFolderJsonKvStorage.ts
+import { createServiceToken as createServiceToken15 } from "@workglow/util";
+var FS_FOLDER_JSON_KV_REPOSITORY = createServiceToken15("storage.kvRepository.fsFolderJson");
 
-class FsFolderJsonKvRepository extends KvViaTabularRepository {
+class FsFolderJsonKvStorage extends KvViaTabularStorage {
   folderPath;
   tabularRepository;
   constructor(folderPath, keySchema = { type: "string" }, valueSchema = {}) {
     super(keySchema, valueSchema);
     this.folderPath = folderPath;
-    this.tabularRepository = new FsFolderTabularRepository(folderPath, DefaultKeyValueSchema, DefaultKeyValueKey);
+    this.tabularRepository = new FsFolderTabularStorage(folderPath, DefaultKeyValueSchema, DefaultKeyValueKey);
   }
 }
-// src/kv/FsFolderKvRepository.ts
-import { createServiceToken as createServiceToken15 } from "@workglow/util";
+// src/kv/FsFolderKvStorage.ts
+import { createServiceToken as createServiceToken16 } from "@workglow/util";
 import { mkdir as mkdir2, readFile as readFile2, rm as rm2, unlink, writeFile as writeFile2 } from "fs/promises";
 import path2 from "path";
-var FS_FOLDER_KV_REPOSITORY = createServiceToken15("storage.kvRepository.fsFolder");
+var FS_FOLDER_KV_REPOSITORY = createServiceToken16("storage.kvRepository.fsFolder");
 
-class FsFolderKvRepository extends KvRepository {
+class FsFolderKvStorage extends KvStorage {
   folderPath;
   pathWriter;
   constructor(folderPath, pathWriter, keySchema = { type: "string" }, valueSchema = { contentEncoding: "blob" }) {
@@ -2758,11 +3152,11 @@ class FsFolderKvRepository extends KvRepository {
     throw new Error("Not implemented");
   }
 }
-// src/kv/PostgresKvRepository.ts
-import { createServiceToken as createServiceToken16 } from "@workglow/util";
-var POSTGRES_KV_REPOSITORY = createServiceToken16("storage.kvRepository.postgres");
+// src/kv/PostgresKvStorage.ts
+import { createServiceToken as createServiceToken17 } from "@workglow/util";
+var POSTGRES_KV_REPOSITORY = createServiceToken17("storage.kvRepository.postgres");
 
-class PostgresKvRepository extends KvViaTabularRepository {
+class PostgresKvStorage extends KvViaTabularStorage {
   db;
   dbName;
   tabularRepository;
@@ -2770,14 +3164,14 @@ class PostgresKvRepository extends KvViaTabularRepository {
     super(keySchema, valueSchema);
     this.db = db;
     this.dbName = dbName;
-    this.tabularRepository = new PostgresTabularRepository(db, dbName, DefaultKeyValueSchema, DefaultKeyValueKey);
+    this.tabularRepository = new PostgresTabularStorage(db, dbName, DefaultKeyValueSchema, DefaultKeyValueKey);
   }
 }
-// src/kv/SqliteKvRepository.ts
-import { createServiceToken as createServiceToken17 } from "@workglow/util";
-var SQLITE_KV_REPOSITORY = createServiceToken17("storage.kvRepository.sqlite");
+// src/kv/SqliteKvStorage.ts
+import { createServiceToken as createServiceToken18 } from "@workglow/util";
+var SQLITE_KV_REPOSITORY = createServiceToken18("storage.kvRepository.sqlite");
 
-class SqliteKvRepository extends KvViaTabularRepository {
+class SqliteKvStorage extends KvViaTabularStorage {
   db;
   dbName;
   tabularRepository;
@@ -2785,14 +3179,14 @@ class SqliteKvRepository extends KvViaTabularRepository {
     super(keySchema, valueSchema);
     this.db = db;
     this.dbName = dbName;
-    this.tabularRepository = new SqliteTabularRepository(db, dbName, DefaultKeyValueSchema, DefaultKeyValueKey);
+    this.tabularRepository = new SqliteTabularStorage(db, dbName, DefaultKeyValueSchema, DefaultKeyValueKey);
   }
 }
-// src/kv/SupabaseKvRepository.ts
-import { createServiceToken as createServiceToken18 } from "@workglow/util";
-var SUPABASE_KV_REPOSITORY = createServiceToken18("storage.kvRepository.supabase");
+// src/kv/SupabaseKvStorage.ts
+import { createServiceToken as createServiceToken19 } from "@workglow/util";
+var SUPABASE_KV_REPOSITORY = createServiceToken19("storage.kvRepository.supabase");
 
-class SupabaseKvRepository extends KvViaTabularRepository {
+class SupabaseKvStorage extends KvViaTabularStorage {
   client;
   tableName;
   tabularRepository;
@@ -2800,12 +3194,12 @@ class SupabaseKvRepository extends KvViaTabularRepository {
     super(keySchema, valueSchema);
     this.client = client;
     this.tableName = tableName;
-    this.tabularRepository = tabularRepository ?? new SupabaseTabularRepository(client, tableName, DefaultKeyValueSchema, DefaultKeyValueKey);
+    this.tabularRepository = tabularRepository ?? new SupabaseTabularStorage(client, tableName, DefaultKeyValueSchema, DefaultKeyValueKey);
   }
 }
 // src/queue/PostgresQueueStorage.ts
-import { createServiceToken as createServiceToken19, makeFingerprint as makeFingerprint6, uuid4 as uuid42 } from "@workglow/util";
-var POSTGRES_QUEUE_STORAGE = createServiceToken19("jobqueue.storage.postgres");
+import { createServiceToken as createServiceToken20, makeFingerprint as makeFingerprint6, uuid4 as uuid45 } from "@workglow/util";
+var POSTGRES_QUEUE_STORAGE = createServiceToken20("jobqueue.storage.postgres");
 
 class PostgresQueueStorage {
   db;
@@ -2902,7 +3296,7 @@ class PostgresQueueStorage {
   async add(job) {
     const now = new Date().toISOString();
     job.queue = this.queueName;
-    job.job_run_id = job.job_run_id ?? uuid42();
+    job.job_run_id = job.job_run_id ?? uuid45();
     job.fingerprint = await makeFingerprint6(job.input);
     job.status = JobStatus.PENDING;
     job.progress = 0;
@@ -3134,8 +3528,8 @@ class PostgresQueueStorage {
   }
 }
 // src/queue/SqliteQueueStorage.ts
-import { createServiceToken as createServiceToken20, makeFingerprint as makeFingerprint7, sleep as sleep4, uuid4 as uuid43 } from "@workglow/util";
-var SQLITE_QUEUE_STORAGE = createServiceToken20("jobqueue.storage.sqlite");
+import { createServiceToken as createServiceToken21, makeFingerprint as makeFingerprint7, sleep as sleep4, uuid4 as uuid46 } from "@workglow/util";
+var SQLITE_QUEUE_STORAGE = createServiceToken21("jobqueue.storage.sqlite");
 
 class SqliteQueueStorage {
   db;
@@ -3217,7 +3611,7 @@ class SqliteQueueStorage {
   }
   async add(job) {
     const now = new Date().toISOString();
-    job.job_run_id = job.job_run_id ?? uuid43();
+    job.job_run_id = job.job_run_id ?? uuid46();
     job.queue = this.queueName;
     job.fingerprint = await makeFingerprint7(job.input);
     job.status = JobStatus.PENDING;
@@ -3470,8 +3864,8 @@ class SqliteQueueStorage {
   }
 }
 // src/queue/SupabaseQueueStorage.ts
-import { createServiceToken as createServiceToken21, makeFingerprint as makeFingerprint8, uuid4 as uuid44 } from "@workglow/util";
-var SUPABASE_QUEUE_STORAGE = createServiceToken21("jobqueue.storage.supabase");
+import { createServiceToken as createServiceToken22, makeFingerprint as makeFingerprint8, uuid4 as uuid47 } from "@workglow/util";
+var SUPABASE_QUEUE_STORAGE = createServiceToken22("jobqueue.storage.supabase");
 
 class SupabaseQueueStorage {
   client;
@@ -3587,7 +3981,7 @@ class SupabaseQueueStorage {
   async add(job) {
     const now = new Date().toISOString();
     job.queue = this.queueName;
-    job.job_run_id = job.job_run_id ?? uuid44();
+    job.job_run_id = job.job_run_id ?? uuid47();
     job.fingerprint = await makeFingerprint8(job.input);
     job.status = JobStatus.PENDING;
     job.progress = 0;
@@ -3969,9 +4363,9 @@ class SupabaseQueueStorage {
     return manager.subscribe(callback, { intervalMs });
   }
 }
-// src/limiter/PostgresRateLimiterStorage.ts
-import { createServiceToken as createServiceToken22 } from "@workglow/util";
-var POSTGRES_RATE_LIMITER_STORAGE = createServiceToken22("ratelimiter.storage.postgres");
+// src/queue-limiter/PostgresRateLimiterStorage.ts
+import { createServiceToken as createServiceToken23 } from "@workglow/util";
+var POSTGRES_RATE_LIMITER_STORAGE = createServiceToken23("ratelimiter.storage.postgres");
 
 class PostgresRateLimiterStorage {
   db;
@@ -4107,9 +4501,9 @@ class PostgresRateLimiterStorage {
     await this.db.query(`DELETE FROM ${this.nextAvailableTableName} WHERE queue_name = $1${prefixConditions}`, [queueName, ...prefixParams]);
   }
 }
-// src/limiter/SqliteRateLimiterStorage.ts
-import { createServiceToken as createServiceToken23, sleep as sleep5, toSQLiteTimestamp } from "@workglow/util";
-var SQLITE_RATE_LIMITER_STORAGE = createServiceToken23("ratelimiter.storage.sqlite");
+// src/queue-limiter/SqliteRateLimiterStorage.ts
+import { createServiceToken as createServiceToken24, sleep as sleep5, toSQLiteTimestamp } from "@workglow/util";
+var SQLITE_RATE_LIMITER_STORAGE = createServiceToken24("ratelimiter.storage.sqlite");
 
 class SqliteRateLimiterStorage {
   db;
@@ -4246,9 +4640,9 @@ class SqliteRateLimiterStorage {
     this.db.prepare(`DELETE FROM ${this.nextAvailableTableName} WHERE queue_name = ?${prefixConditions}`).run(queueName, ...prefixParams);
   }
 }
-// src/limiter/SupabaseRateLimiterStorage.ts
-import { createServiceToken as createServiceToken24 } from "@workglow/util";
-var SUPABASE_RATE_LIMITER_STORAGE = createServiceToken24("ratelimiter.storage.supabase");
+// src/queue-limiter/SupabaseRateLimiterStorage.ts
+import { createServiceToken as createServiceToken25 } from "@workglow/util";
+var SUPABASE_RATE_LIMITER_STORAGE = createServiceToken25("ratelimiter.storage.supabase");
 
 class SupabaseRateLimiterStorage {
   client;
@@ -4399,13 +4793,311 @@ class SupabaseRateLimiterStorage {
       throw nextError;
   }
 }
-// src/kv/IndexedDbKvRepository.ts
-import { createServiceToken as createServiceToken26 } from "@workglow/util";
+// src/vector/PostgresVectorStorage.ts
+import { cosineSimilarity as cosineSimilarity2 } from "@workglow/util";
+class PostgresVectorStorage extends PostgresTabularStorage {
+  vectorDimensions;
+  VectorType;
+  vectorPropertyName;
+  metadataPropertyName;
+  constructor(db, table, schema, primaryKeyNames, indexes = [], dimensions, VectorType = Float32Array) {
+    super(db, table, schema, primaryKeyNames, indexes);
+    this.vectorDimensions = dimensions;
+    this.VectorType = VectorType;
+    const vectorProp = getVectorProperty(schema);
+    if (!vectorProp) {
+      throw new Error("Schema must have a property with type array and format TypedArray");
+    }
+    this.vectorPropertyName = vectorProp;
+    this.metadataPropertyName = getMetadataProperty(schema);
+  }
+  getVectorDimensions() {
+    return this.vectorDimensions;
+  }
+  async similaritySearch(query, options = {}) {
+    const { topK = 10, filter, scoreThreshold = 0 } = options;
+    try {
+      const queryVector = `[${Array.from(query).join(",")}]`;
+      const vectorCol = String(this.vectorPropertyName);
+      const metadataCol = this.metadataPropertyName ? String(this.metadataPropertyName) : null;
+      let sql = `
+        SELECT 
+          *,
+          1 - (${vectorCol} <=> $1::vector) as score
+        FROM "${this.table}"
+      `;
+      const params = [queryVector];
+      let paramIndex = 2;
+      if (filter && Object.keys(filter).length > 0 && metadataCol) {
+        const conditions = [];
+        for (const [key, value] of Object.entries(filter)) {
+          conditions.push(`${metadataCol}->>'${key}' = $${paramIndex}`);
+          params.push(String(value));
+          paramIndex++;
+        }
+        sql += ` WHERE ${conditions.join(" AND ")}`;
+      }
+      if (scoreThreshold > 0) {
+        sql += filter ? " AND" : " WHERE";
+        sql += ` (1 - (${vectorCol} <=> $1::vector)) >= $${paramIndex}`;
+        params.push(scoreThreshold);
+        paramIndex++;
+      }
+      sql += ` ORDER BY ${vectorCol} <=> $1::vector LIMIT $${paramIndex}`;
+      params.push(topK);
+      const result = await this.db.query(sql, params);
+      const results = [];
+      for (const row of result.rows) {
+        const vectorResult = await this.db.query(`SELECT ${vectorCol}::text FROM "${this.table}" WHERE ${this.getPrimaryKeyWhereClause(row)}`, this.getPrimaryKeyValues(row));
+        const vectorStr = vectorResult.rows[0]?.[vectorCol] || "[]";
+        const vectorArray = JSON.parse(vectorStr);
+        results.push({
+          ...row,
+          [this.vectorPropertyName]: new this.VectorType(vectorArray),
+          score: parseFloat(row.score)
+        });
+      }
+      return results;
+    } catch (error) {
+      console.warn("pgvector query failed, falling back to in-memory search:", error);
+      return this.searchFallback(query, options);
+    }
+  }
+  async hybridSearch(query, options) {
+    const { topK = 10, filter, scoreThreshold = 0, textQuery, vectorWeight = 0.7 } = options;
+    if (!textQuery || textQuery.trim().length === 0) {
+      return this.similaritySearch(query, { topK, filter, scoreThreshold });
+    }
+    try {
+      const queryVector = `[${Array.from(query).join(",")}]`;
+      const tsQuery = textQuery.split(/\s+/).join(" & ");
+      const vectorCol = String(this.vectorPropertyName);
+      const metadataCol = this.metadataPropertyName ? String(this.metadataPropertyName) : null;
+      let sql = `
+        SELECT 
+          *,
+          (
+            $2 * (1 - (${vectorCol} <=> $1::vector)) +
+            $3 * ts_rank(to_tsvector('english', ${metadataCol || "''"}::text), to_tsquery('english', $4))
+          ) as score
+        FROM "${this.table}"
+      `;
+      const params = [queryVector, vectorWeight, 1 - vectorWeight, tsQuery];
+      let paramIndex = 5;
+      if (filter && Object.keys(filter).length > 0 && metadataCol) {
+        const conditions = [];
+        for (const [key, value] of Object.entries(filter)) {
+          conditions.push(`${metadataCol}->>'${key}' = $${paramIndex}`);
+          params.push(String(value));
+          paramIndex++;
+        }
+        sql += ` WHERE ${conditions.join(" AND ")}`;
+      }
+      if (scoreThreshold > 0) {
+        sql += filter ? " AND" : " WHERE";
+        sql += ` (
+          $2 * (1 - (${vectorCol} <=> $1::vector)) +
+          $3 * ts_rank(to_tsvector('english', ${metadataCol || "''"}::text), to_tsquery('english', $4))
+        ) >= $${paramIndex}`;
+        params.push(scoreThreshold);
+        paramIndex++;
+      }
+      sql += ` ORDER BY score DESC LIMIT $${paramIndex}`;
+      params.push(topK);
+      const result = await this.db.query(sql, params);
+      const results = [];
+      for (const row of result.rows) {
+        const vectorResult = await this.db.query(`SELECT ${vectorCol}::text FROM "${this.table}" WHERE ${this.getPrimaryKeyWhereClause(row)}`, this.getPrimaryKeyValues(row));
+        const vectorStr = vectorResult.rows[0]?.[vectorCol] || "[]";
+        const vectorArray = JSON.parse(vectorStr);
+        results.push({
+          ...row,
+          [this.vectorPropertyName]: new this.VectorType(vectorArray),
+          score: parseFloat(row.score)
+        });
+      }
+      return results;
+    } catch (error) {
+      console.warn("pgvector hybrid query failed, falling back to in-memory search:", error);
+      return this.hybridSearchFallback(query, options);
+    }
+  }
+  async searchFallback(query, options) {
+    const { topK = 10, filter, scoreThreshold = 0 } = options;
+    const allRows = await this.getAll() || [];
+    const results = [];
+    for (const row of allRows) {
+      const vector = row[this.vectorPropertyName];
+      const metadata = this.metadataPropertyName ? row[this.metadataPropertyName] : {};
+      if (filter && !this.matchesFilter(metadata, filter)) {
+        continue;
+      }
+      const score = cosineSimilarity2(query, vector);
+      if (score >= scoreThreshold) {
+        results.push({ ...row, score });
+      }
+    }
+    results.sort((a, b) => b.score - a.score);
+    const topResults = results.slice(0, topK);
+    return topResults;
+  }
+  async hybridSearchFallback(query, options) {
+    const { topK = 10, filter, scoreThreshold = 0, textQuery, vectorWeight = 0.7 } = options;
+    const allRows = await this.getAll() || [];
+    const results = [];
+    const queryLower = textQuery.toLowerCase();
+    const queryWords = queryLower.split(/\s+/).filter((w) => w.length > 0);
+    for (const row of allRows) {
+      const vector = row[this.vectorPropertyName];
+      const metadata = this.metadataPropertyName ? row[this.metadataPropertyName] : {};
+      if (filter && !this.matchesFilter(metadata, filter)) {
+        continue;
+      }
+      const vectorScore = cosineSimilarity2(query, vector);
+      const metadataText = JSON.stringify(metadata).toLowerCase();
+      let textScore = 0;
+      if (queryWords.length > 0) {
+        let matches = 0;
+        for (const word of queryWords) {
+          if (metadataText.includes(word)) {
+            matches++;
+          }
+        }
+        textScore = matches / queryWords.length;
+      }
+      const combinedScore = vectorWeight * vectorScore + (1 - vectorWeight) * textScore;
+      if (combinedScore >= scoreThreshold) {
+        results.push({ ...row, score: combinedScore });
+      }
+    }
+    results.sort((a, b) => b.score - a.score);
+    const topResults = results.slice(0, topK);
+    return topResults;
+  }
+  getPrimaryKeyWhereClause(row) {
+    const conditions = this.primaryKeyNames.map((key, idx) => `${String(key)} = $${idx + 1}`);
+    return conditions.join(" AND ");
+  }
+  getPrimaryKeyValues(row) {
+    return this.primaryKeyNames.map((key) => row[key]);
+  }
+  matchesFilter(metadata, filter) {
+    for (const [key, value] of Object.entries(filter)) {
+      if (metadata[key] !== value) {
+        return false;
+      }
+    }
+    return true;
+  }
+}
+// src/vector/SqliteVectorStorage.ts
+import { cosineSimilarity as cosineSimilarity3 } from "@workglow/util";
+function matchesFilter2(metadata, filter) {
+  for (const [key, value] of Object.entries(filter)) {
+    if (metadata[key] !== value) {
+      return false;
+    }
+  }
+  return true;
+}
 
-// src/tabular/IndexedDbTabularRepository.ts
+class SqliteVectorStorage extends SqliteTabularStorage {
+  vectorDimensions;
+  VectorType;
+  vectorPropertyName;
+  metadataPropertyName;
+  constructor(dbOrPath, table = "vectors", schema, primaryKeyNames, indexes = [], dimensions, VectorType = Float32Array) {
+    super(dbOrPath, table, schema, primaryKeyNames, indexes);
+    this.vectorDimensions = dimensions;
+    this.VectorType = VectorType;
+    const vectorProp = getVectorProperty(schema);
+    if (!vectorProp) {
+      throw new Error("Schema must have a property with type array and format TypedArray");
+    }
+    this.vectorPropertyName = vectorProp;
+    this.metadataPropertyName = getMetadataProperty(schema);
+  }
+  getVectorDimensions() {
+    return this.vectorDimensions;
+  }
+  deserializeVector(vectorJson) {
+    const array = JSON.parse(vectorJson);
+    return new this.VectorType(array);
+  }
+  async similaritySearch(query, options = {}) {
+    const { topK = 10, filter, scoreThreshold = 0 } = options;
+    const results = [];
+    const allEntities = await this.getAll() || [];
+    for (const entity of allEntities) {
+      const vectorRaw = entity[this.vectorPropertyName];
+      const vector = this.deserializeVector(vectorRaw);
+      const metadata = this.metadataPropertyName ? entity[this.metadataPropertyName] : {};
+      if (filter && !matchesFilter2(metadata, filter)) {
+        continue;
+      }
+      const score = cosineSimilarity3(query, vector);
+      if (score < scoreThreshold) {
+        continue;
+      }
+      results.push({
+        ...entity,
+        score
+      });
+    }
+    results.sort((a, b) => b.score - a.score);
+    const topResults = results.slice(0, topK);
+    return topResults;
+  }
+  async hybridSearch(query, options) {
+    const { topK = 10, filter, scoreThreshold = 0, textQuery, vectorWeight = 0.7 } = options;
+    if (!textQuery || textQuery.trim().length === 0) {
+      return this.similaritySearch(query, { topK, filter, scoreThreshold });
+    }
+    const results = [];
+    const allEntities = await this.getAll() || [];
+    const queryLower = textQuery.toLowerCase();
+    const queryWords = queryLower.split(/\s+/).filter((w) => w.length > 0);
+    for (const entity of allEntities) {
+      const vectorRaw = entity[this.vectorPropertyName];
+      const vector = this.deserializeVector(vectorRaw);
+      const metadata = this.metadataPropertyName ? entity[this.metadataPropertyName] : {};
+      if (filter && !matchesFilter2(metadata, filter)) {
+        continue;
+      }
+      const vectorScore = cosineSimilarity3(query, vector);
+      const metadataText = JSON.stringify(metadata).toLowerCase();
+      let textScore = 0;
+      if (queryWords.length > 0) {
+        let matches = 0;
+        for (const word of queryWords) {
+          if (metadataText.includes(word)) {
+            matches++;
+          }
+        }
+        textScore = matches / queryWords.length;
+      }
+      const combinedScore = vectorWeight * vectorScore + (1 - vectorWeight) * textScore;
+      if (combinedScore < scoreThreshold) {
+        continue;
+      }
+      results.push({
+        ...entity,
+        score: combinedScore
+      });
+    }
+    results.sort((a, b) => b.score - a.score);
+    const topResults = results.slice(0, topK);
+    return topResults;
+  }
+}
+// src/kv/IndexedDbKvStorage.ts
+import { createServiceToken as createServiceToken27 } from "@workglow/util";
+
+// src/tabular/IndexedDbTabularStorage.ts
 import {
-  createServiceToken as createServiceToken25,
-  makeFingerprint as makeFingerprint9
+  createServiceToken as createServiceToken26,
+  makeFingerprint as makeFingerprint9,
+  uuid4 as uuid48
 } from "@workglow/util";
 
 // src/util/IndexedDbTable.ts
@@ -4554,7 +5246,7 @@ async function performIncrementalMigration(db, tableName, diff, options = {}) {
     options.onMigrationProgress?.(`Migration complete`, 1);
   });
 }
-async function performDestructiveMigration(db, tableName, primaryKey, expectedIndexes, options = {}) {
+async function performDestructiveMigration(db, tableName, primaryKey, expectedIndexes, options = {}, autoIncrement = false) {
   if (!options.allowDestructiveMigration) {
     throw new Error(`Destructive migration required for ${tableName} but not allowed. ` + `Primary key has changed. Set allowDestructiveMigration=true to proceed with data loss, ` + `or provide a dataTransformer to migrate data.`);
   }
@@ -4599,7 +5291,7 @@ async function performDestructiveMigration(db, tableName, primaryKey, expectedIn
     if (db2.objectStoreNames.contains(tableName)) {
       db2.deleteObjectStore(tableName);
     }
-    const store = db2.createObjectStore(tableName, { keyPath: primaryKey });
+    const store = db2.createObjectStore(tableName, { keyPath: primaryKey, autoIncrement });
     for (const idx of expectedIndexes) {
       store.createIndex(idx.name, idx.keyPath, idx.options);
     }
@@ -4617,7 +5309,7 @@ async function performDestructiveMigration(db, tableName, primaryKey, expectedIn
   options.onMigrationProgress?.(`Destructive migration complete`, 1);
   return newDb;
 }
-async function createNewDatabase(tableName, primaryKey, expectedIndexes, options = {}) {
+async function createNewDatabase(tableName, primaryKey, expectedIndexes, options = {}, autoIncrement = false) {
   options.onMigrationProgress?.(`Creating new database: ${tableName}`, 0);
   try {
     await deleteIndexedDbTable(tableName);
@@ -4629,7 +5321,7 @@ async function createNewDatabase(tableName, primaryKey, expectedIndexes, options
     if (!db2.objectStoreNames.contains(METADATA_STORE_NAME)) {
       db2.createObjectStore(METADATA_STORE_NAME, { keyPath: "tableName" });
     }
-    const store = db2.createObjectStore(tableName, { keyPath: primaryKey });
+    const store = db2.createObjectStore(tableName, { keyPath: primaryKey, autoIncrement });
     for (const idx of expectedIndexes) {
       store.createIndex(idx.name, idx.keyPath, idx.options);
     }
@@ -4645,7 +5337,7 @@ async function createNewDatabase(tableName, primaryKey, expectedIndexes, options
   options.onMigrationProgress?.(`Database created successfully`, 1);
   return db;
 }
-async function ensureIndexedDbTable(tableName, primaryKey, expectedIndexes = [], options = {}) {
+async function ensureIndexedDbTable(tableName, primaryKey, expectedIndexes = [], options = {}, autoIncrement = false) {
   try {
     let db;
     let wasJustCreated = false;
@@ -4657,7 +5349,7 @@ async function ensureIndexedDbTable(tableName, primaryKey, expectedIndexes = [],
       }
     } catch (err) {
       options.onMigrationProgress?.(`Database ${tableName} does not exist or has version conflict, creating...`, 0);
-      return await createNewDatabase(tableName, primaryKey, expectedIndexes, options);
+      return await createNewDatabase(tableName, primaryKey, expectedIndexes, options, autoIncrement);
     }
     if (wasJustCreated) {
       options.onMigrationProgress?.(`Creating new database: ${tableName}`, 0);
@@ -4670,7 +5362,7 @@ async function ensureIndexedDbTable(tableName, primaryKey, expectedIndexes = [],
         if (!db2.objectStoreNames.contains(METADATA_STORE_NAME)) {
           db2.createObjectStore(METADATA_STORE_NAME, { keyPath: "tableName" });
         }
-        const store2 = db2.createObjectStore(tableName, { keyPath: primaryKey });
+        const store2 = db2.createObjectStore(tableName, { keyPath: primaryKey, autoIncrement });
         for (const idx of expectedIndexes) {
           store2.createIndex(idx.name, idx.keyPath, idx.options);
         }
@@ -4700,7 +5392,7 @@ async function ensureIndexedDbTable(tableName, primaryKey, expectedIndexes = [],
     if (!db.objectStoreNames.contains(tableName)) {
       options.onMigrationProgress?.(`Object store ${tableName} does not exist, creating...`, 0);
       db.close();
-      return await createNewDatabase(tableName, primaryKey, expectedIndexes, options);
+      return await createNewDatabase(tableName, primaryKey, expectedIndexes, options, autoIncrement);
     }
     const transaction = db.transaction(tableName, "readonly");
     const store = transaction.objectStore(tableName);
@@ -4723,7 +5415,7 @@ async function ensureIndexedDbTable(tableName, primaryKey, expectedIndexes = [],
     }
     if (diff.needsObjectStoreRecreation) {
       options.onMigrationProgress?.(`Schema change requires object store recreation for ${tableName}`, 0);
-      db = await performDestructiveMigration(db, tableName, primaryKey, expectedIndexes, options);
+      db = await performDestructiveMigration(db, tableName, primaryKey, expectedIndexes, options, autoIncrement);
     } else {
       options.onMigrationProgress?.(`Performing incremental migration for ${tableName}`, 0);
       db = await performIncrementalMigration(db, tableName, diff, options);
@@ -4745,18 +5437,18 @@ async function dropIndexedDbTable(tableName) {
   return deleteIndexedDbTable(tableName);
 }
 
-// src/tabular/IndexedDbTabularRepository.ts
-var IDB_TABULAR_REPOSITORY = createServiceToken25("storage.tabularRepository.indexedDb");
+// src/tabular/IndexedDbTabularStorage.ts
+var IDB_TABULAR_REPOSITORY = createServiceToken26("storage.tabularRepository.indexedDb");
 
-class IndexedDbTabularRepository extends TabularRepository {
+class IndexedDbTabularStorage extends BaseTabularStorage {
   table;
   db;
   setupPromise = null;
   migrationOptions;
   hybridManager = null;
   hybridOptions;
-  constructor(table = "tabular_store", schema, primaryKeyNames, indexes = [], migrationOptions = {}) {
-    super(schema, primaryKeyNames, indexes);
+  constructor(table = "tabular_store", schema, primaryKeyNames, indexes = [], migrationOptions = {}, clientProvidedKeys = "if-missing") {
+    super(schema, primaryKeyNames, indexes, clientProvidedKeys);
     this.table = table;
     this.migrationOptions = migrationOptions;
     this.hybridOptions = {
@@ -4803,21 +5495,64 @@ class IndexedDbTabularRepository extends TabularRepository {
       });
     }
     const primaryKey = pkColumns.length === 1 ? pkColumns[0] : pkColumns;
-    return await ensureIndexedDbTable(this.table, primaryKey, expectedIndexes, this.migrationOptions);
+    const useAutoIncrement = this.hasAutoGeneratedKey() && this.autoGeneratedKeyStrategy === "autoincrement" && pkColumns.length === 1;
+    return await ensureIndexedDbTable(this.table, primaryKey, expectedIndexes, this.migrationOptions, useAutoIncrement);
+  }
+  generateKeyValue(columnName, strategy) {
+    if (strategy === "uuid") {
+      return uuid48();
+    }
+    throw new Error(`IndexedDB autoincrement keys are generated by the database, not client-side. Column: ${columnName}`);
   }
   async put(record) {
     const db = await this.getDb();
-    const { key } = this.separateKeyValueFromCombined(record);
+    let recordToStore = record;
+    if (this.hasAutoGeneratedKey() && this.autoGeneratedKeyName) {
+      const keyName = String(this.autoGeneratedKeyName);
+      const clientProvidedValue = record[keyName];
+      const hasClientValue = clientProvidedValue !== undefined && clientProvidedValue !== null;
+      if (this.autoGeneratedKeyStrategy === "uuid") {
+        let shouldGenerate = false;
+        if (this.clientProvidedKeys === "never") {
+          shouldGenerate = true;
+        } else if (this.clientProvidedKeys === "always") {
+          if (!hasClientValue) {
+            throw new Error(`Auto-generated key "${keyName}" is required when clientProvidedKeys is "always"`);
+          }
+          shouldGenerate = false;
+        } else {
+          shouldGenerate = !hasClientValue;
+        }
+        if (shouldGenerate) {
+          const generatedValue = this.generateKeyValue(keyName, "uuid");
+          recordToStore = { ...record, [keyName]: generatedValue };
+        }
+      } else if (this.autoGeneratedKeyStrategy === "autoincrement") {
+        if (this.clientProvidedKeys === "always" && !hasClientValue) {
+          throw new Error(`Auto-generated key "${keyName}" is required when clientProvidedKeys is "always"`);
+        }
+        if (this.clientProvidedKeys === "never") {
+          const { [keyName]: _, ...rest } = record;
+          recordToStore = rest;
+        }
+      }
+    }
     return new Promise((resolve, reject) => {
       const transaction = db.transaction(this.table, "readwrite");
       const store = transaction.objectStore(this.table);
-      const request = store.put(record);
+      const request = store.put(recordToStore);
       request.onerror = () => {
         reject(request.error);
       };
       request.onsuccess = () => {
-        this.events.emit("put", record);
-        resolve(record);
+        if (this.hasAutoGeneratedKey() && this.autoGeneratedKeyName && this.autoGeneratedKeyStrategy === "autoincrement") {
+          const keyName = String(this.autoGeneratedKeyName);
+          if (recordToStore[keyName] === undefined) {
+            recordToStore = { ...recordToStore, [keyName]: request.result };
+          }
+        }
+        this.events.emit("put", recordToStore);
+        resolve(recordToStore);
       };
       transaction.oncomplete = () => {
         this.hybridManager?.notifyLocalChange();
@@ -4825,38 +5560,7 @@ class IndexedDbTabularRepository extends TabularRepository {
     });
   }
   async putBulk(records) {
-    const db = await this.getDb();
-    return new Promise((resolve, reject) => {
-      const transaction = db.transaction(this.table, "readwrite");
-      const store = transaction.objectStore(this.table);
-      let completed = 0;
-      let hasError = false;
-      transaction.onerror = () => {
-        if (!hasError) {
-          hasError = true;
-          reject(transaction.error);
-        }
-      };
-      transaction.oncomplete = () => {
-        if (!hasError) {
-          this.hybridManager?.notifyLocalChange();
-          resolve(records);
-        }
-      };
-      for (const record of records) {
-        const request = store.put(record);
-        request.onsuccess = () => {
-          this.events.emit("put", record);
-          completed++;
-        };
-        request.onerror = () => {
-          if (!hasError) {
-            hasError = true;
-            reject(request.error);
-          }
-        };
-      }
-    });
+    return await Promise.all(records.map((record) => this.put(record)));
   }
   getPrimaryKeyAsOrderedArray(key) {
     return super.getPrimaryKeyAsOrderedArray(key).map((value) => typeof value === "bigint" ? value.toString() : value);
@@ -5149,21 +5853,21 @@ class IndexedDbTabularRepository extends TabularRepository {
   }
 }
 
-// src/kv/IndexedDbKvRepository.ts
-var IDB_KV_REPOSITORY = createServiceToken26("storage.kvRepository.indexedDb");
+// src/kv/IndexedDbKvStorage.ts
+var IDB_KV_REPOSITORY = createServiceToken27("storage.kvRepository.indexedDb");
 
-class IndexedDbKvRepository extends KvViaTabularRepository {
+class IndexedDbKvStorage extends KvViaTabularStorage {
   dbName;
   tabularRepository;
   constructor(dbName, keySchema = { type: "string" }, valueSchema = {}) {
     super(keySchema, valueSchema);
     this.dbName = dbName;
-    this.tabularRepository = new IndexedDbTabularRepository(dbName, DefaultKeyValueSchema, DefaultKeyValueKey);
+    this.tabularRepository = new IndexedDbTabularStorage(dbName, DefaultKeyValueSchema, DefaultKeyValueKey);
   }
 }
-// src/limiter/IndexedDbRateLimiterStorage.ts
-import { createServiceToken as createServiceToken27 } from "@workglow/util";
-var INDEXED_DB_RATE_LIMITER_STORAGE = createServiceToken27("ratelimiter.storage.indexedDb");
+// src/queue-limiter/IndexedDbRateLimiterStorage.ts
+import { createServiceToken as createServiceToken28 } from "@workglow/util";
+var INDEXED_DB_RATE_LIMITER_STORAGE = createServiceToken28("ratelimiter.storage.indexedDb");
 
 class IndexedDbRateLimiterStorage {
   executionDb;
@@ -5383,8 +6087,8 @@ class IndexedDbRateLimiterStorage {
   }
 }
 // src/queue/IndexedDbQueueStorage.ts
-import { createServiceToken as createServiceToken28, makeFingerprint as makeFingerprint10, uuid4 as uuid45 } from "@workglow/util";
-var INDEXED_DB_QUEUE_STORAGE = createServiceToken28("jobqueue.storage.indexedDb");
+import { createServiceToken as createServiceToken29, makeFingerprint as makeFingerprint10, uuid4 as uuid49 } from "@workglow/util";
+var INDEXED_DB_QUEUE_STORAGE = createServiceToken29("jobqueue.storage.indexedDb");
 
 class IndexedDbQueueStorage {
   queueName;
@@ -5464,8 +6168,8 @@ class IndexedDbQueueStorage {
     const db = await this.getDb();
     const now = new Date().toISOString();
     const jobWithPrefixes = job;
-    jobWithPrefixes.id = jobWithPrefixes.id ?? uuid45();
-    jobWithPrefixes.job_run_id = jobWithPrefixes.job_run_id ?? uuid45();
+    jobWithPrefixes.id = jobWithPrefixes.id ?? uuid49();
+    jobWithPrefixes.job_run_id = jobWithPrefixes.job_run_id ?? uuid49();
     jobWithPrefixes.queue = this.queueName;
     jobWithPrefixes.fingerprint = await makeFingerprint10(jobWithPrefixes.input);
     jobWithPrefixes.status = JobStatus.PENDING;
@@ -5952,19 +6656,25 @@ class IndexedDbQueueStorage {
   }
 }
 export {
+  registerTabularRepository,
   isSearchCondition,
+  getVectorProperty,
+  getTabularRepository,
+  getMetadataProperty,
+  getGlobalTabularRepositories,
   ensureIndexedDbTable,
   dropIndexedDbTable,
-  TabularRepository,
   TABULAR_REPOSITORY,
-  SupabaseTabularRepository,
+  TABULAR_REPOSITORIES,
+  SupabaseTabularStorage,
   SupabaseRateLimiterStorage,
   SupabaseQueueStorage,
-  SupabaseKvRepository,
-  SqliteTabularRepository,
+  SupabaseKvStorage,
+  SqliteVectorStorage,
+  SqliteTabularStorage,
   SqliteRateLimiterStorage,
   SqliteQueueStorage,
-  SqliteKvRepository,
+  SqliteKvStorage,
   SUPABASE_TABULAR_REPOSITORY,
   SUPABASE_RATE_LIMITER_STORAGE,
   SUPABASE_QUEUE_STORAGE,
@@ -5975,10 +6685,11 @@ export {
   SQLITE_KV_REPOSITORY,
   RATE_LIMITER_STORAGE,
   QUEUE_STORAGE,
-  PostgresTabularRepository,
+  PostgresVectorStorage,
+  PostgresTabularStorage,
   PostgresRateLimiterStorage,
   PostgresQueueStorage,
-  PostgresKvRepository,
+  PostgresKvStorage,
   PollingSubscriptionManager,
   POSTGRES_TABULAR_REPOSITORY,
   POSTGRES_RATE_LIMITER_STORAGE,
@@ -5986,18 +6697,19 @@ export {
   POSTGRES_KV_REPOSITORY,
   MEMORY_TABULAR_REPOSITORY,
   MEMORY_KV_REPOSITORY,
-  KvViaTabularRepository,
-  KvRepository,
+  KvViaTabularStorage,
+  KvStorage,
   KV_REPOSITORY,
   JobStatus,
-  IndexedDbTabularRepository,
+  IndexedDbTabularStorage,
   IndexedDbRateLimiterStorage,
   IndexedDbQueueStorage,
-  IndexedDbKvRepository,
-  InMemoryTabularRepository,
+  IndexedDbKvStorage,
+  InMemoryVectorStorage,
+  InMemoryTabularStorage,
   InMemoryRateLimiterStorage,
   InMemoryQueueStorage,
-  InMemoryKvRepository,
+  InMemoryKvStorage,
   IN_MEMORY_RATE_LIMITER_STORAGE,
   IN_MEMORY_QUEUE_STORAGE,
   INDEXED_DB_RATE_LIMITER_STORAGE,
@@ -6005,16 +6717,17 @@ export {
   IDB_TABULAR_REPOSITORY,
   IDB_KV_REPOSITORY,
   HybridSubscriptionManager,
-  FsFolderTabularRepository,
-  FsFolderKvRepository,
-  FsFolderJsonKvRepository,
+  FsFolderTabularStorage,
+  FsFolderKvStorage,
+  FsFolderJsonKvStorage,
   FS_FOLDER_TABULAR_REPOSITORY,
   FS_FOLDER_KV_REPOSITORY,
   FS_FOLDER_JSON_KV_REPOSITORY,
   DefaultKeyValueSchema,
   DefaultKeyValueKey,
-  CachedTabularRepository,
-  CACHED_TABULAR_REPOSITORY
+  CachedTabularStorage,
+  CACHED_TABULAR_REPOSITORY,
+  BaseTabularStorage
 };
 
-//# debugId=B146DFB53B6D14EB64756E2164756E21
+//# debugId=CDE752B27E94EEDB64756E2164756E21