docs(stack): EQL v3 Supabase integration design spec

[tobyhede]

Summary

Adds the design spec for EQL v3 on Supabase, at parity with the existing v2 encryptedSupabase adapter, using native eql_v3.* domain columns.

Core principle: v3 mirrors v2 exactly — same query mechanism (direct EQL operators), same operator-visibility caveat and Exposed-schemas requirement, same install/permissions story. Only the column types (v2 composite eql_v2_encrypted → per-domain eql_v3.*) and internal encoding differ. An earlier draft's separate v3 query path (function pattern / generated columns / RPC) was dropped: it tried to eliminate a caveat v2 already lives with, and didn't even help the ORE-range case it was invoked for.

What the spec covers

• SDK adapter — encryptedSupabaseV3 + a narrow dialect fork of EncryptedQueryBuilderImpl (column recognition, property↔DB name, mutation/query-term encoding, reconstructRow, the text_search equality operand).
• DB bundle + install — opclass-stripped v3 Supabase SQL bundle (provenance/re-sync named), v3 installer path, SUPABASE_PERMISSIONS_SQL keyed to eql_v3, and the manual Exposed-schemas step.
• The one v3-only wrinkle — the text_search domain CHECK (hm+ob+bf) rejects an hm-only equality operand; fixed by building the operand from the full envelope.
• Tests/docs/release — live integration suite (incl. a Date-column round-trip and CS_*-gated ORE range), type-level tests, doc updates (incl. re-creating the deleted supabase-sdk.md), changeset.

Notes for reviewers

• Findings are grounded in inspection + live Supabase spikes; file:line references and git provenance (ee56fb68 add / def9f4bd delete of supabase-sdk.md) are verified against the tree.
• Status: proposed. Open questions remain (branch/commit placement; confirming the text_search operand via a real encryptQuery).
• Stacked on feat/eql-v3-text-search-schema — this PR targets that branch, so the diff is the spec only.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 5e8bf92

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 4c95fb70-9b90-49a3-8d05-c8c3d20ec1e2

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/eql-v3-supabase-design

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}