@nightowlsdev/storage-supabase

`createSupabaseStorage(opts)` returns a `StorageAdapter` implementing the core `agents` / `runs` / `events` / `messages` / `scratchpad` seams plus suspend/resume followup tracking, a redacted Realtime broadcast event bus (`events.subscribe`), cross-process cache invalidation via Postgres LISTEN/NOTIFY (`subscribeInvalidations`, so a `publishAgentVersion` on one instance evicts every other instance's RowCache), and a writable versioned agent repo (`agentsWritable`, surfaced as `agents`). It authenticates with the secret (BYPASSRLS) key and is the real authz boundary, scoping every query by tenant in code. Use the Session/Direct Postgres port 5432 (never the 6543 transaction pooler, it throws). `createMastraPgStore` provides a Postgres-backed Mastra store (defaults `disableInit:true`, schema `nightowls`) for durable suspend/resume, injected via `defineSwarm`/`SwarmEngine({ mastraStore })`; `createMastraVectorStore` + `createPostgresFloor` cover vector memory and the multi-lane turn-serialization floor. Ships inlined `MIGRATIONS` and a `nightOwlsPlugin` manifest the CLI ejects into `supabase/migrations/` (you apply them with your own tooling; Night Owls never runs DDL). Management helpers like `publishAgentVersion` reuse the adapter's typed `ctx` handle. There is no credit/billing ledger here, credit metering is host-owned in the platform app, not in this OSS package.

storage-supabase is the durable, multi-tenant StorageAdapter every self-hosted Night Owls deployment runs on. createSupabaseStorage(opts) implements the core agents / runs / events / messages / scratchpad seams over Postgres, plus a redacted Realtime event bus, cross-process cache invalidation over LISTEN/NOTIFY, an append-only versioned agent repo, and a cross-instance container floor for serverless mutual exclusion. createMastraPgStore backs durable suspend/resume so a run parked on an approval survives a process restart or a cold start. It also ships the opt-in FR-072 message-search plane — createMessageSearch({ pool, embedder, embedderTag, dimensions }) over a pgvector sidecar — so conversation history becomes semantically searchable without touching the Mastra-owned message table. It ships its own inlined MIGRATIONS that the CLI ejects — Night Owls never connects to your DB or runs DDL.

createSupabaseStorage opens a pg Pool (search_path nightowls,public) plus a supabase-js client and returns a SupabaseStorage — a StorageAdapter with a typed ctx handle and a close() teardown. Because the pool uses the BYPASSRLS secret key, every store method scopes by tenant in code; the SQL RLS is only defence-in-depth for the browser and Realtime paths. Durable suspend/resume comes from createMastraPgStore (a @mastra/pg PostgresStore in the nightowls schema, disableInit:true), injected via defineSwarm / SwarmEngine({ mastraStore }); createPostgresFloor gives serverless mutual exclusion; subscribeInvalidations registers a LISTEN subscription so a publishAgentVersion NOTIFY on one instance evicts every other instance's cache. The tables come from the inlined MIGRATIONS the CLI ejects into supabase/migrations/, which you apply with your own tooling.

An opt-in plane over the same pool that makes conversation history semantically searchable. nightowls.mastra_messages stays untouched — Mastra owns it — so the plane writes a sidecar instead. It is wired in three moves: eject a second migration, construct the plane, let a runner drive the indexing.

messageSearchMigration({ dimensions }) is EJECTABLE and deliberately NOT part of MIGRATIONS: the embedding column is vector(n) and only the host knows n, so this follows knowledge's dimension-parameterized precedent — call it, append the result to the set your CLI ejects into supabase/migrations/, and apply it with your own tooling. It creates two service-only tables (RLS on with no policy plus an explicit revoke of the schema's blanket grants — 0034's lesson applied at birth): nightowls.mastra_message_embeddings, a sidecar keyed (message_id, model) whose foreign keys cascade from mastra_messages and orgs, and nightowls.message_embed_state, the per-(org, container, model) manifest holding the cursors and the repair-cycle state.

createMessageSearch({ pool, embedder, embedderTag, dimensions }) returns the four operations. The embedder is a STRUCTURAL host-injected function — (texts: string[]) => Promise<number[][]>, batch in and batch out, same length and same order — so no provider is hard-pinned: core's createEmbeddingFactory behind a small embedMany adapter, a raw Ollama call, or a local model all satisfy it. embedderTag is required and is stored on every row: an unlabelled corpus cannot be filtered at search time, re-embedded, or retired. dimensions must equal the migration's vector(n); the plane validates that against the live column once and caches it, and assertMessageSearchSchema({ pool, dimensions }) is exported separately for hosts that want the check to fail at boot instead of on first use.

indexContainer(tenantId, container) is the incremental indexer. It runs two passes under ONE per-(org, container, model) advisory lock held on a single checked-out client, spending a budget counted in EXAMINED CANDIDATES (default 200) split 75/25 creation/repair, an unspent share rolling to the other pass — unchanged, failed and delete-candidate rows all cost a slot, so the call is bounded regardless of outcome. The creation pass keysets forward over newly qualifying messages. The repair pass rotates between a live-side walk (rediscovering rows that are missing, moved in, or drifted on any copied field) and an orphan-side walk (deleting embeddings whose message no longer qualifies for that org and container); when a cycle opens it stamps a high-water boundary, which is what gives both walks a fixed end and makes them wrap in bounded work even under sustained writes. The returned done is true only when the creation probe found nothing, the last CLOSED cycle was clean, and no cycle is mid-flight — advisory under concurrent writes, never a proof.

No transaction is ever held across the embedder: a batch embeds, then ONE transaction re-guards each row against its LIVE state, upserts, and advances the cursor. A failing batch is bisected to isolate the actual poison, which is recorded in failed and stepped past (the repair pass rediscovers it later); three isolated failures in one call abort it as a presumed embedder outage, with no further cursor advance, so a resume retries from where it stopped. backfillTenant(tenantId) spends a GLOBAL budget across the union of containers found in live threads, the manifest and the embeddings table — an orphan-only container is never stranded — and its returned afterContainer echoes the last FULLY COMPLETED container, so feeding the result back verbatim resumes inside an unfinished container instead of skipping it. pruneModel(tenantId, model) retires one embedder tag container by container under the same locks; prune only once every host has stopped configuring that tag, since a still-configured host would lawfully re-index.

AUTHORIZATION IS LIVE, and this is the invariant the whole design turns on. The sidecar's org_id / org_scope / container / thread_id / role / created_at columns are a denormalized COPY that accelerates the ANN candidate scan and authorizes nothing: no match survives without joining the live message row and its thread, matching the tenant's org, passing Rule A on threads.org_scope, and resolving to the same canonical container. Every projected field — role, thread, container, timestamp, preview — is read from the live rows, never from the copy.

DRIFT is handled by a second, separate hash domain, because Mastra rewrites mastra_messages IN PLACE (content, role, thread and resourceId can all change without the timestamps moving). source_hash is md5 of the RAW message content, stored at index time and re-checked against md5 of the live content at search time; a mismatch excludes the row, so a rewritten message is never returned under its old text and a moved thread never discloses under its old scope. The repair pass then re-embeds it and refreshes every copied field. The embedded text is derived and capped separately from that hash, so truncating a long message never makes it look stale — otherwise it would be re-embedded on every cycle forever.

searchMessages(tenantId, opts) never throws for a bad query or an unusable plane. It returns a discriminated { ok: true, matches } | { ok: false, reason: "unavailable" | "bad-input", detail }, which runner-nextjs's searchRoute() maps to 503 and 400. Each match carries a preview from the LIVE content plus anchorSeq — the latest events.seq at or before the message, as a decimal string — which is what lets a client page the conversation around the hit. Nothing on this plane runs on the write path: no embedder outage, dimension mismatch, missing table or contended lock can fail a turn, a resume or a drive.