feat(storage): add SqlDialect, FTS, BlobCodec, Exporter abstractions

- SqlDialect interface with SQLite + Postgres implementations
- IFullTextSearch with FTS5 + tsvector/GIN implementations
- IBlobCodec with Node (Buffer) + Browser (DataView) implementations
- IDatabaseExporter with VACUUM INTO + pg_dump implementations
- createStorageFeatures() factory selects by adapter.kind + runtime
- 41 unit tests covering all implementations

Author: jddunn

src/codecs/BrowserBlobCodec.ts

@@ -0,0 +1,37 @@
+import type { IBlobCodec } from '../core/contracts/blobCodec.js';
+
+/**
+ * Browser-compatible BLOB codec using typed arrays.
+ *
+ * Encodes number[] vectors as Float32Array binary BLOBs and computes
+ * SHA-256 hashes via `crypto.subtle` (with a Node.js fallback for
+ * test environments where SubtleCrypto may not be available).
+ */
+export class BrowserBlobCodec implements IBlobCodec {
+  encode(vec: number[]): Uint8Array {
+    const f32 = new Float32Array(vec);
+    return new Uint8Array(f32.buffer);
+  }
+
+  decode(blob: Uint8Array | ArrayBufferLike): number[] {
+    const bytes = blob instanceof Uint8Array ? blob : new Uint8Array(blob);
+    const f32 = new Float32Array(
+      bytes.buffer,
+      bytes.byteOffset,
+      bytes.byteLength / 4,
+    );
+    return Array.from(f32);
+  }
+
+  async sha256(input: string): Promise<string> {
+    if (typeof globalThis.crypto?.subtle?.digest === 'function') {
+      const encoded = new TextEncoder().encode(input);
+      const hashBuffer = await globalThis.crypto.subtle.digest('SHA-256', encoded);
+      const hashArray = new Uint8Array(hashBuffer);
+      return Array.from(hashArray).map((b) => b.toString(16).padStart(2, '0')).join('');
+    }
+    // Fallback for Node.js test environments
+    const { createHash } = await import('node:crypto');
+    return createHash('sha256').update(input, 'utf8').digest('hex');
+  }
+}

src/codecs/NodeBlobCodec.ts

@@ -0,0 +1,34 @@
+import crypto from 'node:crypto';
+import type { IBlobCodec } from '../core/contracts/blobCodec.js';
+
+/**
+ * Node.js Buffer-based BLOB codec.
+ *
+ * Encodes number[] vectors as Float32 little-endian binary BLOBs using
+ * `Buffer.writeFloatLE` / `Buffer.readFloatLE`, and computes SHA-256
+ * hashes using the `node:crypto` module.
+ */
+export class NodeBlobCodec implements IBlobCodec {
+  encode(vec: number[]): Uint8Array {
+    const buf = Buffer.alloc(vec.length * 4);
+    for (let i = 0; i < vec.length; i++) {
+      buf.writeFloatLE(vec[i]!, i * 4);
+    }
+    return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+  }
+
+  decode(blob: Uint8Array | ArrayBufferLike): number[] {
+    const bytes = blob instanceof Uint8Array ? blob : new Uint8Array(blob);
+    const buf = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const count = buf.length / 4;
+    const vec: number[] = new Array(count);
+    for (let i = 0; i < count; i++) {
+      vec[i] = buf.readFloatLE(i * 4);
+    }
+    return vec;
+  }
+
+  async sha256(input: string): Promise<string> {
+    return crypto.createHash('sha256').update(input, 'utf8').digest('hex');
+  }
+}

src/core/contracts/blobCodec.ts

@@ -0,0 +1,16 @@
+/**
+ * Binary BLOB codec for encoding/decoding vectors and computing hashes.
+ *
+ * Node.js implementations use Buffer.
+ * Browser implementations use Uint8Array + DataView.
+ */
+export interface IBlobCodec {
+  /** Encode a number[] vector to a binary BLOB value (Float32 little-endian). */
+  encode(vec: number[]): Uint8Array;
+
+  /** Decode a BLOB column value back to number[]. */
+  decode(blob: Uint8Array | ArrayBufferLike): number[];
+
+  /** SHA-256 hex digest. Async to support crypto.subtle in browsers. */
+  sha256(input: string): Promise<string>;
+}

src/core/contracts/dialect.ts

@@ -0,0 +1,61 @@
+/**
+ * SQL dialect abstraction for cross-platform SQL generation.
+ *
+ * Each method returns a SQL string fragment or full statement.
+ * Implementations are pure string transformers — no database calls.
+ */
+export interface SqlDialect {
+  /** Dialect identifier. */
+  readonly name: 'sqlite' | 'postgres';
+
+  /**
+   * Generate an INSERT OR IGNORE statement.
+   * SQLite: `INSERT OR IGNORE INTO t (a, b) VALUES (?, ?)`
+   * Postgres: `INSERT INTO t (a, b) VALUES ($1, $2) ON CONFLICT DO NOTHING`
+   */
+  insertOrIgnore(table: string, columns: string[], placeholders: string[]): string;
+
+  /**
+   * Generate an INSERT OR REPLACE (upsert) statement.
+   * SQLite: `INSERT OR REPLACE INTO t (a, b) VALUES (?, ?)`
+   * Postgres: `INSERT INTO t (a, b) VALUES ($1, $2) ON CONFLICT (pk) DO UPDATE SET ...`
+   *
+   * @param primaryKey - Required for Postgres ON CONFLICT clause. Defaults to first column.
+   */
+  insertOrReplace(table: string, columns: string[], placeholders: string[], primaryKey?: string): string;
+
+  /**
+   * Generate a JSON field extraction expression.
+   * SQLite: `json_extract(col, '$.key')`
+   * Postgres: `(col::jsonb)->>'key'`
+   */
+  jsonExtract(column: string, jsonPath: string): string;
+
+  /**
+   * Generate a null-coalesce expression.
+   * SQLite: `ifnull(expr, fallback)`
+   * Postgres: `COALESCE(expr, fallback)`
+   */
+  ifnull(expr: string, fallback: string): string;
+
+  /**
+   * Column definition for an auto-incrementing integer primary key.
+   * SQLite: `INTEGER PRIMARY KEY AUTOINCREMENT`
+   * Postgres: `INTEGER GENERATED ALWAYS AS IDENTITY PRIMARY KEY`
+   */
+  autoIncrementPrimaryKey(): string;
+
+  /**
+   * Generate a PRAGMA statement or equivalent.
+   * SQLite: `PRAGMA key = value`
+   * Postgres: returns null (skip — Postgres enforces FKs by default, etc.)
+   */
+  pragma(key: string, value: string): string | null;
+
+  /**
+   * Parameter placeholder for the given 0-based index.
+   * SQLite: `?`
+   * Postgres: `$1`, `$2`, etc.
+   */
+  placeholder(index: number): string;
+}

src/core/contracts/exporter.ts

@@ -0,0 +1,13 @@
+/**
+ * Database export abstraction.
+ *
+ * SQLite: VACUUM INTO or db.export().
+ * Postgres: pg_dump via child_process.
+ */
+export interface IDatabaseExporter {
+  /** Export the full database to a file at the given path. */
+  exportToFile(outputPath: string): Promise<void>;
+
+  /** Export the full database as raw bytes. */
+  exportToBytes(): Promise<Uint8Array>;
+}

src/core/contracts/features.ts

@@ -0,0 +1,44 @@
+import type { SqlDialect } from './dialect.js';
+import type { IFullTextSearch } from './fts.js';
+import type { IBlobCodec } from './blobCodec.js';
+import type { IDatabaseExporter } from './exporter.js';
+import type { StorageAdapter } from './index.js';
+import { SqliteDialect } from '../../dialects/SqliteDialect.js';
+import { PostgresDialect } from '../../dialects/PostgresDialect.js';
+import { SqliteFts5 } from '../../fts/SqliteFts5.js';
+import { PostgresFts } from '../../fts/PostgresFts.js';
+import { NodeBlobCodec } from '../../codecs/NodeBlobCodec.js';
+import { BrowserBlobCodec } from '../../codecs/BrowserBlobCodec.js';
+import { SqliteFileExporter } from '../../exporters/SqliteFileExporter.js';
+import { PostgresExporter } from '../../exporters/PostgresExporter.js';
+
+/**
+ * Bundle of platform-aware database features.
+ *
+ * Created by `createStorageFeatures(adapter)` — consumers use this
+ * instead of writing raw platform-specific SQL.
+ */
+export interface StorageFeatures {
+  readonly dialect: SqlDialect;
+  readonly fts: IFullTextSearch;
+  readonly blobCodec: IBlobCodec;
+  readonly exporter: IDatabaseExporter;
+}
+
+/**
+ * Create a platform-aware feature bundle for the given storage adapter.
+ *
+ * Inspects `adapter.kind` and the runtime environment to select the right
+ * dialect, FTS, BLOB codec, and exporter implementations.
+ */
+export function createStorageFeatures(adapter: StorageAdapter): StorageFeatures {
+  const isPostgres = adapter.kind === 'postgres';
+  const isBrowser = typeof window !== 'undefined' && typeof window.document !== 'undefined';
+
+  return {
+    dialect: isPostgres ? new PostgresDialect() : new SqliteDialect(),
+    fts: isPostgres ? new PostgresFts() : new SqliteFts5(),
+    blobCodec: isBrowser ? new BrowserBlobCodec() : new NodeBlobCodec(),
+    exporter: isPostgres ? new PostgresExporter() : new SqliteFileExporter(adapter),
+  };
+}

src/core/contracts/fts.ts

@@ -0,0 +1,71 @@
+/**
+ * Full-text search abstraction.
+ *
+ * SQLite implementations use FTS5 virtual tables.
+ * Postgres implementations use tsvector columns with GIN indexes.
+ * Methods return SQL strings — no database calls.
+ */
+export interface IFullTextSearch {
+  /**
+   * Generate DDL to create the full-text search index.
+   *
+   * @param config.table - Name for the FTS index/virtual table.
+   * @param config.columns - Columns to index.
+   * @param config.contentTable - Source table (for external-content FTS5).
+   * @param config.tokenizer - Tokenizer config (e.g. 'porter ascii').
+   */
+  createIndex(config: {
+    table: string;
+    columns: string[];
+    contentTable?: string;
+    tokenizer?: string;
+  }): string;
+
+  /**
+   * Generate a WHERE clause fragment for full-text matching.
+   * SQLite: `memory_traces_fts MATCH ?`
+   * Postgres: `memory_traces._tsv @@ plainto_tsquery('english', $1)`
+   */
+  matchClause(indexName: string, queryPlaceholder: string): string;
+
+  /**
+   * Generate an ORDER BY rank expression.
+   * SQLite: `memory_traces_fts.rank`
+   * Postgres: `ts_rank(memory_traces._tsv, plainto_tsquery('english', $1))`
+   */
+  rankExpression(indexName: string, queryPlaceholder?: string): string;
+
+  /**
+   * Generate the rebuild/reindex command.
+   * SQLite: `INSERT INTO fts_table(fts_table) VALUES('rebuild')`
+   * Postgres: `UPDATE content_table SET _tsv = to_tsvector('english', col1 || ' ' || col2)`
+   */
+  rebuildCommand(indexName: string): string;
+
+  /**
+   * Generate an INSERT to sync external-content FTS after a row insert.
+   * SQLite: `INSERT INTO fts_table (rowid, col1, col2) VALUES (expr, ?, ?)`
+   * Postgres: `UPDATE content_table SET _tsv = to_tsvector(...) WHERE ...`
+   */
+  syncInsert(indexName: string, rowIdExpr: string, columns: string[]): string;
+
+  /**
+   * Sanitize natural-language input into a safe search query.
+   * SQLite: wraps words in quotes, strips FTS5 operators.
+   * Postgres: pass-through (plainto_tsquery handles it).
+   */
+  sanitizeQuery(input: string): string;
+
+  /**
+   * Generate a SELECT joining the FTS index to the content table.
+   * This handles the structural difference between FTS5 (separate virtual table
+   * joined via rowid) and Postgres (tsvector column on the content table itself).
+   *
+   * @param contentTable - The base table (e.g. 'memory_traces').
+   * @param contentAlias - Alias for the content table (e.g. 't').
+   * @param ftsAlias - Alias for the FTS table/column (e.g. 'fts').
+   * @param indexName - FTS index/virtual table name.
+   * @returns FROM/JOIN clause fragment.
+   */
+  joinClause(contentTable: string, contentAlias: string, ftsAlias: string, indexName: string): string;
+}

src/core/contracts/index.ts

@@ -283,3 +283,11 @@ export * from './performance';
  */
 export * from './hooks';
 
+// Dialect & feature contracts --------------------------------------------------
+export type { SqlDialect } from './dialect.js';
+export type { IFullTextSearch } from './fts.js';
+export type { IBlobCodec } from './blobCodec.js';
+export type { IDatabaseExporter } from './exporter.js';
+export type { StorageFeatures } from './features.js';
+export { createStorageFeatures } from './features.js';
+

src/dialects/PostgresDialect.ts

@@ -0,0 +1,51 @@
+import type { SqlDialect } from '../core/contracts/dialect.js';
+
+/**
+ * PostgreSQL dialect implementation.
+ *
+ * Generates Postgres-compatible SQL syntax including `ON CONFLICT DO NOTHING`,
+ * `ON CONFLICT ... DO UPDATE SET`, `jsonb` extraction operators, `COALESCE()`,
+ * `GENERATED ALWAYS AS IDENTITY`, and `$N` positional placeholders.
+ */
+export class PostgresDialect implements SqlDialect {
+  readonly name = 'postgres' as const;
+
+  insertOrIgnore(table: string, columns: string[], placeholders: string[]): string {
+    return `INSERT INTO ${table} (${columns.join(', ')}) VALUES (${placeholders.join(', ')}) ON CONFLICT DO NOTHING`;
+  }
+
+  insertOrReplace(table: string, columns: string[], placeholders: string[], primaryKey?: string): string {
+    const pk = primaryKey ?? columns[0];
+    const updates = columns
+      .filter((col) => col !== pk)
+      .map((col) => `${col} = EXCLUDED.${col}`)
+      .join(', ');
+    return `INSERT INTO ${table} (${columns.join(', ')}) VALUES (${placeholders.join(', ')}) ON CONFLICT (${pk}) DO UPDATE SET ${updates}`;
+  }
+
+  jsonExtract(column: string, jsonPath: string): string {
+    const path = jsonPath.replace(/^\$\./, '');
+    const parts = path.split('.');
+    if (parts.length === 1) {
+      return `(${column}::jsonb)->>'${parts[0]}'`;
+    }
+    const args = parts.map((p) => `'${p}'`).join(', ');
+    return `jsonb_extract_path_text(${column}::jsonb, ${args})`;
+  }
+
+  ifnull(expr: string, fallback: string): string {
+    return `COALESCE(${expr}, ${fallback})`;
+  }
+
+  autoIncrementPrimaryKey(): string {
+    return 'INTEGER GENERATED ALWAYS AS IDENTITY PRIMARY KEY';
+  }
+
+  pragma(_key: string, _value: string): string | null {
+    return null;
+  }
+
+  placeholder(index: number): string {
+    return `$${index + 1}`;
+  }
+}

src/dialects/SqliteDialect.ts

@@ -0,0 +1,40 @@
+import type { SqlDialect } from '../core/contracts/dialect.js';
+
+/**
+ * SQLite dialect implementation.
+ *
+ * Generates standard SQLite SQL syntax including `INSERT OR IGNORE`,
+ * `INSERT OR REPLACE`, `json_extract()`, `ifnull()`, `PRAGMA`, and
+ * positional `?` placeholders.
+ */
+export class SqliteDialect implements SqlDialect {
+  readonly name = 'sqlite' as const;
+
+  insertOrIgnore(table: string, columns: string[], placeholders: string[]): string {
+    return `INSERT OR IGNORE INTO ${table} (${columns.join(', ')}) VALUES (${placeholders.join(', ')})`;
+  }
+
+  insertOrReplace(table: string, columns: string[], placeholders: string[], _primaryKey?: string): string {
+    return `INSERT OR REPLACE INTO ${table} (${columns.join(', ')}) VALUES (${placeholders.join(', ')})`;
+  }
+
+  jsonExtract(column: string, jsonPath: string): string {
+    return `json_extract(${column}, '${jsonPath}')`;
+  }
+
+  ifnull(expr: string, fallback: string): string {
+    return `ifnull(${expr}, ${fallback})`;
+  }
+
+  autoIncrementPrimaryKey(): string {
+    return 'INTEGER PRIMARY KEY AUTOINCREMENT';
+  }
+
+  pragma(key: string, value: string): string | null {
+    return `PRAGMA ${key} = ${value}`;
+  }
+
+  placeholder(_index: number): string {
+    return '?';
+  }
+}