@workglow/storage 0.2.31 → 0.2.32

package/dist/tabular/TelemetryTabularStorage.d.ts

@@ -4,7 +4,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import type { DataPortSchemaObject, FromSchema, TypedArraySchemaOptions } from "@workglow/util/schema";
-import type { AutoGeneratedKeys, CoveringIndexQueryOptions, DeleteSearchCriteria, InsertEntity, ITabularStorage, QueryOptions, SearchCriteria, SimplifyPrimaryKey, TabularChangePayload, TabularEventListener, TabularEventName, TabularEventParameters, TabularSubscribeOptions } from "./ITabularStorage";
+import type { ITabularMigrationApplier } from "../migrations";
+import type { AutoGeneratedKeys, CoveringIndexQueryOptions, DeleteSearchCriteria, InsertEntity, ITabularStorage, Page, PageRequest, QueryOptions, SearchCriteria, SimplifyPrimaryKey, TabularChangePayload, TabularEventListener, TabularEventName, TabularEventParameters, TabularSubscribeOptions } from "./ITabularStorage";
 /**
  * Telemetry wrapper for any ITabularStorage implementation.
  * Creates spans for all storage operations.
@@ -23,12 +24,21 @@ export declare class TelemetryTabularStorage<Schema extends DataPortSchemaObject
     count(criteria?: SearchCriteria<Entity>): Promise<number>;
     deleteSearch(criteria: DeleteSearchCriteria<Entity>): Promise<void>;
     getBulk(offset: number, limit: number): Promise<Entity[] | undefined>;
+    getPage(request?: PageRequest<Entity>): Promise<Page<Entity>>;
+    queryPage(criteria: SearchCriteria<Entity>, request?: PageRequest<Entity>): Promise<Page<Entity>>;
     query(criteria: SearchCriteria<Entity>, options?: QueryOptions<Entity>): Promise<Entity[] | undefined>;
     queryIndex<K extends keyof Entity & string>(criteria: SearchCriteria<Entity>, options: CoveringIndexQueryOptions<Entity, K>): Promise<Pick<Entity, K>[]>;
     records(pageSize?: number): AsyncGenerator<Entity, void, undefined>;
     pages(pageSize?: number): AsyncGenerator<Entity[], void, undefined>;
     subscribeToChanges(callback: (change: TabularChangePayload<Entity>) => void, options?: TabularSubscribeOptions): () => void;
+    withTransaction<T>(fn: (tx: this) => Promise<T>): Promise<T>;
     setupDatabase(): Promise<void>;
+    /**
+     * Forwards to the inner storage's applier so callers that wrap a
+     * migration-aware storage in TelemetryTabularStorage still observe
+     * declared migrations.
+     */
+    getMigrationApplier(): ITabularMigrationApplier | null;
     destroy(): void;
     [Symbol.dispose](): void;
     [Symbol.asyncDispose](): Promise<void>;

package/dist/tabular/TelemetryTabularStorage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TelemetryTabularStorage.d.ts","sourceRoot":"","sources":["../../src/tabular/TelemetryTabularStorage.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,oBAAoB,EACpB,UAAU,EACV,uBAAuB,EACxB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,KAAK,EACV,iBAAiB,EACjB,yBAAyB,EACzB,oBAAoB,EACpB,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,cAAc,EACd,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,EACpB,gBAAgB,EAChB,sBAAsB,EACtB,uBAAuB,EACxB,MAAM,mBAAmB,CAAC;AAE3B;;;GAGG;AACH,qBAAa,uBAAuB,CAClC,MAAM,SAAS,oBAAoB,EACnC,eAAe,SAAS,aAAa,CAAC,MAAM,MAAM,CAAC,YAAY,CAAC,CAAC,EACjE,MAAM,GAAG,UAAU,CAAC,MAAM,EAAE,uBAAuB,CAAC,EACpD,UAAU,GAAG,kBAAkB,CAAC,MAAM,EAAE,eAAe,CAAC,EACxD,UAAU,GAAG,YAAY,CAAC,MAAM,EAAE,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAC5D,YAAW,eAAe,CAAC,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,CAAC;IAEjF,SAAS,CAAC,QAAQ,CAAC,WAAW,EAAE,MAAM;IACtC,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,eAAe,CACvC,MAAM,EACN,eAAe,EACf,MAAM,EACN,UAAU,EACV,UAAU,CACX;IARH,YACqB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,eAAe,CACvC,MAAM,EACN,eAAe,EACf,MAAM,EACN,UAAU,EACV,UAAU,CACX,EACC;IAEJ,GAAG,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAEtC;IAED,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAI/C;IAED,GAAG,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAEhD;IAED,MAAM,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAI9C;IAED,MAAM,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,SAAS,CAAC,CAIpE;IAED,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAIzB;IAED,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAEtB;IAED,KAAK,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAIxD;IAED,YAAY,CAAC,QAAQ,EAAE,oBAAoB,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAIlE;IAED,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,SAAS,CAAC,CAIpE;IAED,KAAK,CACH,QAAQ,EAAE,cAAc,CAAC,MAAM,CAAC,EAChC,OAAO,CAAC,EAAE,YAAY,CAAC,MAAM,CAAC,GAC7B,OAAO,CAAC,MAAM,EAAE,GAAG,SAAS,CAAC,CAI/B;IAED,UAAU,CAAC,CAAC,SAAS,MAAM,MAAM,GAAG,MAAM,EACxC,QAAQ,EAAE,cAAc,CAAC,MAAM,CAAC,EAChC,OAAO,EAAE,yBAAyB,CAAC,MAAM,EAAE,CAAC,CAAC,GAC5C,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,CAI5B;IAGD,OAAO,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,cAAc,CAAC,MAAM,EAAE,IAAI,EAAE,SAAS,CAAC,CAElE;IAED,KAAK,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,cAAc,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,SAAS,CAAC,CAElE;IAED,kBAAkB,CAChB,QAAQ,EAAE,CAAC,MAAM,EAAE,oBAAoB,CAAC,MAAM,CAAC,KAAK,IAAI,EACxD,OAAO,CAAC,EAAE,uBAAuB,GAChC,MAAM,IAAI,CAEZ;IAED,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAE7B;IAED,OAAO,IAAI,IAAI,CAEd;IAED,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAEvB;IAED,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAErC;IAGD,EAAE,CAAC,KAAK,SAAS,gBAAgB,EAC/B,IAAI,EAAE,KAAK,EACX,EAAE,EAAE,oBAAoB,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,CAAC,GAClD,IAAI,CAEN;IAED,GAAG,CAAC,KAAK,SAAS,gBAAgB,EAChC,IAAI,EAAE,KAAK,EACX,EAAE,EAAE,oBAAoB,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,CAAC,GAClD,IAAI,CAEN;IAED,IAAI,CAAC,KAAK,SAAS,gBAAgB,EACjC,IAAI,EAAE,KAAK,EACX,GAAG,IAAI,EAAE,sBAAsB,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,CAAC,GACzD,IAAI,CAEN;IAED,IAAI,CAAC,KAAK,SAAS,gBAAgB,EACjC,IAAI,EAAE,KAAK,EACX,EAAE,EAAE,oBAAoB,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,CAAC,GAClD,IAAI,CAEN;IAED,MAAM,CAAC,KAAK,SAAS,gBAAgB,EACnC,IAAI,EAAE,KAAK,GACV,OAAO,CAAC,sBAAsB,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC,CAE5D;CACF"}
+{"version":3,"file":"TelemetryTabularStorage.d.ts","sourceRoot":"","sources":["../../src/tabular/TelemetryTabularStorage.ts"],"names":[],"mappings":"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"}

package/dist/tabular/sqlMigrationDdl.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export declare function buildAddColumnSql(dialect: "sqlite" | "postgres", table: string, column: string, sqlType: string, nullable: boolean, hasDefault?: boolean, defaultLiteralSql?: string): string;
+export declare function buildDropColumnSql(dialect: "sqlite" | "postgres", table: string, column: string): string;
+export declare function buildRenameColumnSql(dialect: "sqlite" | "postgres", table: string, from: string, to: string): string;
+export declare function buildAddIndexSql(dialect: "sqlite" | "postgres", table: string, indexName: string, columns: readonly string[], unique: boolean): string;
+export declare function buildDropIndexSql(dialect: "sqlite" | "postgres", indexName: string): string;
+//# sourceMappingURL=sqlMigrationDdl.d.ts.map

package/dist/tabular/sqlMigrationDdl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlMigrationDdl.d.ts","sourceRoot":"","sources":["../../src/tabular/sqlMigrationDdl.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,QAAQ,GAAG,UAAU,EAC9B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,OAAO,EACjB,UAAU,GAAE,OAAe,EAC3B,iBAAiB,CAAC,EAAE,MAAM,GACzB,MAAM,CAQR;AAED,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,QAAQ,GAAG,UAAU,EAC9B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb,MAAM,CAGR;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,QAAQ,GAAG,UAAU,EAC9B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,GACT,MAAM,CAGR;AAED,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,QAAQ,GAAG,UAAU,EAC9B,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,MAAM,EAAE,OAAO,GACd,MAAM,CAOR;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,QAAQ,GAAG,UAAU,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAG3F"}

package/dist/vector/IVectorStorage.d.ts

@@ -6,9 +6,69 @@
 import type { DataPortSchemaObject, FromSchema, TypedArray, TypedArraySchemaOptions } from "@workglow/util/schema";
 import type { EventParameters } from "@workglow/util";
 import type { AutoGeneratedKeys, InsertEntity, ITabularStorage, SimplifyPrimaryKey, TabularEventListeners } from "../tabular/ITabularStorage";
-export type AnyVectorStorage = Omit<IVectorStorage<any, any, any, any>, "queryIndex"> & {
+export type AnyVectorStorage = Omit<IVectorStorage<any, any, any, any>, "queryIndex" | "withTransaction"> & {
     queryIndex(criteria: any, options: any): Promise<any[]>;
+    withTransaction<T>(fn: (tx: any) => Promise<T>): Promise<T>;
 };
+/**
+ * Distance metric used by vector indexes.
+ *
+ * - `cosine`: cosine distance (1 - cosine similarity). Default for embedding
+ *   models that produce normalised vectors. Recommended starting point for
+ *   text/RAG workloads.
+ * - `l2`: euclidean distance. Use when vectors carry magnitude information.
+ * - `ip`: negative inner product. Use when embeddings are pre-normalised AND
+ *   you want a slightly cheaper similarity computation than cosine.
+ */
+export type VectorDistanceMetric = "cosine" | "l2" | "ip";
+/**
+ * HNSW index parameters. HNSW is the default approximate-nearest-neighbour
+ * algorithm in pgvector and other modern vector indexes; tuning these knobs
+ * trades index build cost and memory for recall and query latency.
+ *
+ * Defaults from pgvector when unspecified: `m = 16`, `efConstruction = 64`,
+ * `efSearch = 40`.
+ *
+ * - `m`: number of bi-directional links per layer. Higher = better recall,
+ *   more memory, slower build. Typical values: 8 (low-recall), 16 (default),
+ *   32 (high-recall).
+ * - `efConstruction`: candidate-list size during index build. Higher = better
+ *   recall, much slower build. Typical values: 64 (default), 200, 400.
+ * - `efSearch`: candidate-list size at query time. Higher = better recall,
+ *   slower queries. Typical values: 40 (default), 80, 200. This is the knob
+ *   you want to tune at query time once the index is built.
+ */
+export interface HnswIndexOptions {
+    readonly m?: number;
+    readonly efConstruction?: number;
+    readonly efSearch?: number;
+}
+/**
+ * IVFFlat index parameters (pgvector). Offers faster builds than HNSW at the
+ * cost of recall, useful for very large corpora.
+ *
+ * - `lists`: number of inverted lists. pgvector docs recommend `rows / 1000`
+ *   for up to 1M rows, then `sqrt(rows)` for larger sets.
+ * - `probes`: number of lists scanned at query time. Higher = better recall,
+ *   slower queries. Default `1`.
+ */
+export interface IvfflatIndexOptions {
+    readonly lists: number;
+    readonly probes?: number;
+}
+/**
+ * Vector-index tuning options threaded into the storage constructor and
+ * applied during {@link IVectorStorage} setup / migration.
+ *
+ * Only one of `hnsw` or `ivfflat` should be set; if both are absent the
+ * backend uses a sensible default (HNSW on pgvector, COSINE-only for
+ * sqlite-vec which does not yet support HNSW tuning).
+ */
+export interface VectorIndexOptions {
+    readonly distance?: VectorDistanceMetric;
+    readonly hnsw?: HnswIndexOptions;
+    readonly ivfflat?: IvfflatIndexOptions;
+}
 /**
  * Options for vector search operations
  */

package/dist/vector/IVectorStorage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"IVectorStorage.d.ts","sourceRoot":"","sources":["../../src/vector/IVectorStorage.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"IVectorStorage.d.ts","sourceRoot":"","sources":["../../src/vector/IVectorStorage.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@workglow/storage",
   "type": "module",
-  "version": "0.2.31",
+  "version": "0.2.32",
   "repository": {
     "type": "git",
     "url": "https://github.com/workglow-dev/workglow.git",
@@ -26,7 +26,7 @@
     "test": "bun test"
   },
   "peerDependencies": {
-    "@workglow/util": "0.2.31"
+    "@workglow/util": "0.2.32"
   },
   "peerDependenciesMeta": {
     "@workglow/util": {
@@ -34,7 +34,7 @@
     }
   },
   "devDependencies": {
-    "@workglow/util": "0.2.31"
+    "@workglow/util": "0.2.32"
   },
   "exports": {
     ".": {

package/src/tabular/README.md

@@ -21,6 +21,7 @@ A collection of storage implementations for tabular data with multiple backend s
   - [PostgresTabularStorage](#postgrestabularstorage)
   - [IndexedDbTabularStorage](#indexeddbtabularstorage)
   - [FsFolderTabularStorage](#fsfoldertabularstorage)
+- [Migrations](#migrations)
 - [Events](#events)
 - [Testing](#testing)
 - [License](#license)
@@ -434,6 +435,78 @@ const repo = new FsFolderTabularStorage<
 >("./data/users", schema, primaryKeys);
 ```
 
+## Migrations
+
+Tabular storages accept an optional `tabularMigrations` constructor parameter — a versioned, ordered list of declarative ops that evolve older deployments to the current target schema. Migrations work uniformly across all backends (SQL, IndexedDB, schemaless) and reuse the `_storage_migrations` bookkeeping table the rest of the migration system already uses.
+
+```typescript
+import { SqliteTabularStorage } from "@workglow/sqlite/storage";
+import type { ITabularMigration } from "@workglow/storage";
+
+const migrations: ITabularMigration[] = [
+  {
+    version: 1,
+    description: "add archived flag",
+    ops: [
+      // Note: ALTER TABLE ADD COLUMN NOT NULL fails on populated tables in
+      // SQL backends without a DEFAULT, so use a nullable schema.
+      {
+        kind: "addColumn",
+        name: "archived",
+        schema: { anyOf: [{ type: "boolean" }, { type: "null" }] },
+      },
+      { kind: "addIndex", name: "idx_archived", columns: ["archived"] },
+    ],
+  },
+  {
+    version: 2,
+    description: "rename status -> state",
+    ops: [{ kind: "renameColumn", from: "status", to: "state" }],
+  },
+  {
+    version: 3,
+    description: "lowercase emails",
+    ops: [
+      {
+        kind: "backfill",
+        batchSize: 500,
+        transform: (row) => ({ ...row, email: (row.email as string).toLowerCase() }),
+      },
+    ],
+  },
+];
+
+const repo = new SqliteTabularStorage(
+  db,
+  "users",
+  schema,
+  ["id"] as const,
+  [],
+  "if-missing",
+  migrations
+);
+await repo.setupDatabase(); // applies pending migrations
+```
+
+**Op coverage:** `addColumn`, `dropColumn`, `renameColumn`, `addIndex`, `dropIndex`, `backfill`.
+
+**Backend behavior:**
+
+- **SQL backends** (SQLite, Postgres, Supabase): DDL ops translate to native `ALTER TABLE` / `CREATE INDEX`. Each migration runs inside a single `withTransaction` so DDL + backfill + bookkeeping commit atomically.
+- **IndexedDB**: `addIndex` / `dropIndex` run inside an upgrade transaction. `backfill` runs on a normal readwrite transaction afterward (IDB upgrade transactions cannot span async work).
+- **InMemory / SharedInMemory / FsFolder / HuggingFace**: DDL ops are no-ops (records are JS objects). `backfill` runs through the normal `getPage` / `put` / `delete` API. FsFolder persists bookkeeping to `_storage_migrations.json` beside the data; others hold it in process.
+
+**Fresh-DB fast path:** when a storage is constructed at the target schema and the underlying table/store is empty, the orchestrator records every declared migration as already-applied without running its ops. This keeps backfills from running against zero rows on a fresh deployment.
+
+**Adoption:**
+
+- Existing storages without `tabularMigrations` continue unchanged — the migration system is fully opt-in.
+- **Fresh-DB fast path:** when a storage is opened with declared migrations against a brand-new database (no prior bookkeeping AND no pre-existing table), every declared migration is recorded as already-applied without executing its ops. A fresh deployment therefore never runs `addColumn` against a table that was just created at the target schema.
+- **Index ops are idempotent at the DDL level:** `addIndex` / `dropIndex` emit `CREATE INDEX IF NOT EXISTS` / `DROP INDEX IF EXISTS` on SQL backends, and the IndexedDB applier guards `createIndex` / `deleteIndex` with `objectStore.indexNames.contains`. Retries after partial failures are safe.
+- **Column ops are NOT idempotent at the DDL level:** `addColumn` / `dropColumn` / `renameColumn` emit plain `ALTER TABLE` statements. Re-running a successful migration is prevented by the bookkeeping table (`_storage_migrations` records the applied `(component, version)`), not by the DDL itself.
+
+See `docs/superpowers/specs/2026-05-07-unified-tabular-migrations-design.md` for the full design and `docs/superpowers/plans/2026-05-07-unified-tabular-migrations.md` for implementation notes.
+
 ## Events
 
 All implementations emit events:

package/src/vector/README.md

@@ -347,6 +347,85 @@ Quantized vectors reduce storage and can improve performance:
 - **Cons:** Requires PostgreSQL server and pgvector extension
 - **Setup:** `CREATE EXTENSION vector;`
 
+## Vector Index Tuning
+
+`PostgresVectorStorage` (from `@workglow/postgres/storage`) and
+`SqliteAiVectorStorage` (from `@workglow/sqlite/storage`) accept a
+`VectorIndexOptions` constructor argument that controls the underlying index
+type and its recall/latency trade-offs.
+
+```typescript
+import { PostgresVectorStorage } from "@workglow/postgres/storage";
+
+const repo = new PostgresVectorStorage(
+  pool,
+  "vectors",
+  schema,
+  ["id"],
+  [],
+  768,
+  Float32Array,
+  {
+    distance: "cosine",
+    hnsw: { m: 16, efConstruction: 64, efSearch: 80 },
+    // or, for very large corpora:
+    // ivfflat: { lists: 1000, probes: 10 },
+  }
+);
+```
+
+### Recall vs latency cheat sheet
+
+| Backend | Index | Tunable | Recall ↑ knob | Latency ↓ knob | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `PostgresVectorStorage` (pgvector) | HNSW (default) | `m`, `efConstruction`, `efSearch` | raise `m` (8 → 16 → 32), `efConstruction` (64 → 200 → 400), `efSearch` (40 → 80 → 200) | lower the same knobs | `m` and `efConstruction` are build-time; rebuilding the index is required to change them. `efSearch` is per-session — see note below. |
+| `PostgresVectorStorage` (pgvector) | IVFFlat | `lists`, `probes` | raise `probes` (1 → 10 → 50) | lower `probes` | Use when build time matters more than peak recall. Pgvector docs: `lists ≈ rows / 1000` up to 1M rows, `≈ sqrt(rows)` beyond. |
+| `SqliteAiVectorStorage` (sqlite-vector) | brute-force `vector_full_scan` | cosine only | n/a (always exact) | shrink corpus / lower `topK` | sqlite-vector does not yet expose HNSW; recall is 100% but latency is O(n). The constructor rejects non-cosine distances rather than silently producing wrong scores. |
+| `InMemoryVectorStorage` | brute-force JS cosine | n/a | n/a (always exact) | shrink corpus / lower `topK` | Recall is 100%; intended for tests and small corpora only. |
+| `IndexedDbVectorStorage` | brute-force JS cosine | n/a | n/a (always exact) | shrink corpus / lower `topK` | Browser-only; same trade-offs as InMemory. |
+
+### Applying `efSearch` / `probes` at query time
+
+Pgvector reads `hnsw.ef_search` and `ivfflat.probes` from the active session.
+With a node-postgres `Pool`, every `pool.query()` checks out a fresh client, so
+running `SET hnsw.ef_search = N` before the search query has no effect. To apply
+query-time tuning, either:
+
+1. Set it on the role/database so all connections inherit it:
+   `ALTER ROLE workglow SET hnsw.ef_search = 80;`
+2. Run searches against a single checked-out client inside a transaction:
+   ```sql
+   BEGIN;
+   SET LOCAL hnsw.ef_search = 80;
+   SELECT * FROM vectors ORDER BY embedding <=> $1::vector LIMIT 10;
+   COMMIT;
+   ```
+
+`PostgresVectorStorage.getQueryTuning()` returns the configured values so a
+caller can wire them into either approach.
+
+## Migrations
+
+Production code should run schema changes through versioned migrations rather
+than the legacy `setupDatabase()` shim. Each SQL backend exposes
+`migrate()` (idempotent, safe to call repeatedly) and `getMigrations()`
+(returns the migration set so callers can compose several backends under a
+single runner).
+
+```typescript
+import { PostgresMigrationRunner } from "@workglow/postgres/storage";
+
+const runner = new PostgresMigrationRunner(pool);
+await runner.run([
+  ...queue.getMigrations(),
+  ...rateLimiter.getMigrations(),
+]);
+```
+
+`setupDatabase()` is `@deprecated` on `IQueueStorage`, `IRateLimiterStorage`,
+and `ITabularStorage` — it now delegates to `migrate()` for SQL backends so
+existing tests keep working.
+
 ## Integration with KnowledgeBase
 
 The chunk vector repository works alongside `KnowledgeBase` for hierarchical document storage: