Add Supabase vector storage with pgvector support

[sroussey]

Implements SupabaseVectorStorage, a scoped vector storage backend for Supabase using pgvector for similarity search. Extends the existing SupabaseTabularStorage to add vector-specific operations while enforcing tenant/project/knowledge-base isolation at the application layer.

Key Changes

• SupabaseVectorStorage class (providers/supabase/src/storage/SupabaseVectorStorage.ts): New vector storage implementation that:

  • Extends SupabaseTabularStorage for row persistence
  • Delegates similarity search to server-side match_<table> RPC functions (pgvector)
  • Enforces scope binding via withScope() — all reads/writes are constrained to a tenant/project/knowledge-base scope
  • Converts TypedArray vectors to pgvector text format ([a,b,c]) on write and restores them on read
  • Validates metadata filter keys to prevent injection attacks
  • Overrides all inherited tabular methods to inject scope criteria, preventing cross-scope data leakage

• Database schema and RPCs (providers/supabase/migrations/0001_kb_chunks_pgvector.sql):

  • Creates kb_chunks_* tables for 5 vector dimensions (384, 768, 1024, 1536, 3072)
  • Each table has scope columns (tenant_id, project_id, kb_id) and a pgvector column
  • HNSW indexes for fast similarity search; 3072-dim table uses halfvec cast to work around pgvector's 2000-dim HNSW limit
  • match_kb_chunks_* RPC functions that perform cosine similarity search with scope filtering and optional metadata filtering
  • Row-level security policies for tenant isolation (defense-in-depth; service role bypasses RLS)

• Shared documents table (providers/supabase/migrations/0002_shared_documents.sql): Simple table for document metadata with RLS tenant isolation

• Integration tests:

  • SupabaseVectorStorage.integration.test.ts: Tests vector persistence, similarity ranking, scope isolation, and metadata filter validation against a PGlite-backed mock
  • kb_chunks_rls.test.ts: Verifies RLS policies enforce tenant isolation at the database level
  • shared_documents_rls.test.ts: Verifies RLS on the shared documents table
  • SupabaseMockClient.pgvector.test.ts: Tests the mock client's pgvector extension and RPC routing

• Mock client enhancements (packages/test/src/test/helpers/SupabaseMockClient.ts):

  • Added pgvector extension support to PGlite
  • Enhanced RPC routing to handle multi-statement SQL (migrations) via exec_sql RPC
  • Positional parameter routing for RPC functions (required for PGlite test mocks)

• Dependencies: Added @electric-sql/pglite-pgvector for pgvector support in tests

Notable Implementation Details

• Scope enforcement: Scope columns are always stamped from the resolved scope, never from client input. All inherited read/delete methods are overridden to inject scope criteria, preventing a single knowledge base from accessing data across scopes.
• Vector serialization: Vectors are stored as pgvector text in the database but returned to callers as their original TypedArray type, preserving the schema contract.
• Metadata filtering: Uses JSONB containment (@>) for flexible filtering; filter keys are validated against /^[a-zA-Z_][a-zA-Z0-9_]*$/ to prevent injection.
• Score threshold handling: Accepts NULL for no threshold (returns all results), matching pgvector conventions.
• Independent scoped instances: withScope() constructs a fresh instance rather than cloning the prototype, avoiding aliasing of mutable state (realtime channels, event listeners).

https://claude.ai/code/session_01VHcJsxLqN1yMVghTLXfP1k

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	62.17%	24969 / 40156
🔵	Statements	62.02%	25827 / 41643
🔵	Functions	63.11%	4721 / 7480
🔵	Branches	50.82%	12243 / 24088

File Coverage

No changed files found.

Generated in workflow #2560 for commit c4d8919 by the Vitest Coverage Report Action