@supabase/lite 0.0.1-next.2 → 0.0.1-next.4

package/STATUS.md

@@ -0,0 +1,844 @@
+# Status & Compatibility
+
+Feature and API compatibility tracking for @supabase/lite. For usage docs, see [README.md](https://github.com/supabase-community/lite/blob/HEAD/README.md).
+
+## Status Legend
+
+| Status           | Icon | Meaning                                                  |
+|------------------|------|----------------------------------------------------------|
+| **Supported**    | ✅    | Works end-to-end                                         |
+| **Partial**      | ⚠️   | Parsed/recognized but limited (see notes)                |
+| **Incompatible** | ❌    | Not possible due to platform limitations                 |
+| **Backlog**      | 🔄   | Backlog for future consideration/implementation          |
+| **N/A**          | ⚫    | Not applicable (client-side only, TypeScript-only, etc.) |
+
+---
+
+## Database Support
+
+| Runtime                    | Module                    | Status |
+|----------------------------|---------------------------|--------|
+| Node.js (SQLite)           | `node:sqlite`             | ✅      |
+| Bun (SQLite)               | `bun:sqlite`              | ✅      |
+| Browser (SQLite WASM)      | `@sqlite.org/sqlite-wasm` | ✅      |
+| Cloudflare D1              | Workers binding           | ✅      |
+| Cloudflare Durable Objects | DO SQLite                 | ✅      |
+| PGlite                     | `@electric-sql/pglite`    | ✅      |
+| PostgreSQL                 | `postgres` (node driver)  | ✅      |
+| Supabase Cloud             | Cloud connection          | ✅      |
+| LibSQL                     | `@libsql/client`          | 🔄     |
+| Turso                      | `@tursodatabase/database` | 🔄     |
+| SQLite.ai                  |                           | 🔄     |
+
+---
+
+## Postgres-to-SQLite Translation
+
+When using SQLite databases, SQL schemas written in Postgres dialect are translated on the fly. The translator extends the Postgres deparser. It passes through 1:1 compatible syntax unchanged, rewrites constructs that have SQLite equivalents (for example `SERIAL` → `INTEGER PRIMARY KEY AUTOINCREMENT`, `NOW()` → `datetime('now')`), silently drops Postgres-only decorators (storage parameters, locking clauses), and errors on features that have no SQLite counterpart (`LATERAL` joins, table inheritance).
+
+📋 See [`app/POSTGRES-SQLITE-COMPAT.md`](https://github.com/supabase-community/lite/blob/HEAD/app/POSTGRES-SQLITE-COMPAT.md) for the full auto-generated compatibility reference (82 entries).
+
+Here is an example of a Postgres schema that is translated to SQLite:
+
+```sql
+-- Postgres DDL
+CREATE TYPE order_status AS ENUM('pending', 'processing', 'shipped', 'delivered');
+
+CREATE TABLE users
+(
+   id         SERIAL PRIMARY KEY,
+   email      VARCHAR(255) UNIQUE NOT NULL,
+   name       TEXT                NOT NULL,
+   is_active  BOOLEAN   DEFAULT true,
+   tags       TEXT[],
+   metadata   JSONB,
+   created_at TIMESTAMP DEFAULT NOW()
+);
+
+CREATE TABLE orders
+(
+   id         BIGSERIAL PRIMARY KEY,
+   user_id    INTEGER REFERENCES users (id) ON DELETE CASCADE,
+   status     order_status DEFAULT 'pending',
+   total      NUMERIC(10, 2) CHECK (total >= 0) NOT NULL,
+   items      JSONB,
+   notes      TEXT,
+   ordered_at TIMESTAMP    DEFAULT NOW()
+);
+
+ALTER TABLE users ENABLE ROW LEVEL SECURITY;
+ALTER TABLE orders ENABLE ROW LEVEL SECURITY;
+
+CREATE
+POLICY user_orders ON orders FOR
+SELECT
+   USING (
+   user_id = auth.uid (
+   ))
+```
+
+Translated to SQLite:
+
+```sql
+-- CREATE TYPE not emitted
+
+CREATE TABLE users
+(
+   id         INTEGER PRIMARY KEY AUTOINCREMENT,
+   email      TEXT UNIQUE NOT NULL CHECK (length(email) <= 255),
+   name       TEXT        NOT NULL,
+   is_active  INTEGER DEFAULT true CHECK (is_active IN (0, 1)),
+   tags       TEXT CHECK (
+      tags IS NULL
+         OR (
+         json_valid(tags)
+            AND json_type(tags) = 'array'
+         )
+      ),
+   metadata   TEXT CHECK (
+      metadata IS NULL
+         OR json_valid(metadata)
+      ),
+   created_at TEXT    DEFAULT (datetime('now')) CHECK (
+      created_at IS NULL
+         OR datetime(created_at) IS NOT NULL
+      )
+) STRICT;
+
+CREATE TABLE orders
+(
+   id         INTEGER PRIMARY KEY AUTOINCREMENT,
+   user_id    INTEGER REFERENCES users (id) ON DELETE CASCADE,
+   status     TEXT DEFAULT 'pending' CHECK (
+      status IN ('pending', 'processing', 'shipped', 'delivered')
+      ),
+   total      REAL CHECK (total >= 0) NOT NULL CHECK (
+      ABS(ROUND(total * 100) - total * 100) < 0.0001
+         AND ABS(total) < 100000000
+      ),
+   items      TEXT CHECK (
+      items IS NULL
+         OR json_valid(items)
+      ),
+   notes      TEXT,
+   ordered_at TEXT DEFAULT (datetime('now')) CHECK (
+      ordered_at IS NULL
+         OR datetime(ordered_at) IS NOT NULL
+      )
+) STRICT;
+
+-- RLS statements not emitted
+```
+
+### Translated Field Types
+
+| PostgreSQL type / syntax | SQLite storage | Field implementation | Mapping / validation |
+|--------------------------|----------------|----------------------|----------------------|
+| `int2`, `smallint`, `int4`, `integer`, `int`, `int8`, `bigint` | `INTEGER` | `IntegerField` | Integer storage. |
+| `serial`, `serial4`, `bigserial`, `serial8`, `smallserial`, `serial2` | `INTEGER` | `SerialField` | Primary keys become `INTEGER PRIMARY KEY AUTOINCREMENT`. |
+| `float4`, `real`, `float8`, `double precision` | `REAL` | `RealField` | Real-number storage. |
+| `numeric`, `decimal` | `REAL` | `RealField` | Precision/scale emits portable `CHECK` constraints when declared. |
+| `text` | `TEXT` | `TextField` | Text storage. |
+| `varchar`, `varchar(n)`, `character varying`, `character varying(n)`, `char`, `char(n)`, `character`, `character(n)` | `TEXT` | `TextField` | Length-constrained forms emit `length(...) <= n`. |
+| `bpchar` | `TEXT` | `TextField` | Text storage. |
+| `name` | `TEXT` | `TextField` | Emits a 63-character length check. |
+| `bytea` | `BLOB` | `BlobField` | Binary storage. |
+| `bool`, `boolean` | `INTEGER` | `BooleanField` | Stored as `0`/`1` with `CHECK (... IN (0, 1))`. |
+| `date` | `TEXT` | `DateField` | Emits `date(...) IS NOT NULL` validation. |
+| `time`, `time without time zone`, `timetz`, `time with time zone` | `TEXT` | `TimeField` | Emits `time(...) IS NOT NULL` validation. |
+| `timestamp`, `timestamp without time zone`, `timestamptz`, `timestamp with time zone` | `TEXT` | `TimestampField` | Emits `datetime(...) IS NOT NULL` validation. |
+| `interval` | `TEXT` | `IntervalField` | Stored as text; interval arithmetic is not emulated. |
+| `json`, `jsonb` | `TEXT` | `JsonField` | Stored as JSON text with `json_valid(...)` checks. |
+| `uuid` | `TEXT` | `UuidField` | Validates UUID shape and normalizes to lowercase. |
+| `inet` | `TEXT` | `InetField` | Validates IPv4/IPv6 strings with optional CIDR prefixes. |
+| `CREATE TYPE ... AS ENUM` | `TEXT` | `EnumField` | Emits allowed-value `CHECK (... IN (...))`. |
+| `<type>[]`, `_type` arrays | `TEXT` | `ArrayField` | Stores JSON arrays and delegates element serialization where possible. |
+
+Unsupported PostgreSQL data types currently include `oid`, `xid`, `xid8`, `cid`, `money`, `citext`, `cidr`, `macaddr`, `macaddr8`, `bit`, `bit varying`, `varbit`, geometric types (`point`, `line`, `lseg`, `box`, `path`, `polygon`, `circle`), `xml`, text-search types (`tsvector`, `tsquery`), range and multirange types, `reg*` catalog reference types, internal types (`tid`, `pg_lsn`, `internal`), pseudo-types, and handler types.
+
+### Row Level Security (RLS)
+
+RLS is supported on all database backends. The enforcement strategy differs by dialect:
+
+- **SQLite:** Policies are extracted from the Postgres DDL during translation and enforced at the application layer by rewriting the PostgREST AST before query execution. `USING` conditions are merged into the query's `WHERE` clause; `WITH CHECK` conditions are evaluated in-memory against INSERT/UPDATE values.
+- **PGlite / PostgreSQL:** Native Postgres RLS. Each request runs inside a transaction with `SET LOCAL role` and `set_config('request.jwt.claim.sub', ...)` so the database enforces policies directly.
+
+**Auth context:** `auth.role` is resolved from the JWT `role` claim (set during token signing). A missing JWT or missing claim defaults to `"anon"`. This matches PostgREST behavior, where `request.jwt.claim.role` determines the database role. `auth.uid()` resolves to the JWT `sub` claim. `auth.jwt()` exposes the full JWT payload.
+
+**Supported:**
+
+| Feature                                        | SQLite | PGlite/Postgres | Notes                                                       |
+|------------------------------------------------|--------|-----------------|-------------------------------------------------------------|
+| `ENABLE ROW LEVEL SECURITY`                    | ✅      | ✅               | Default-deny when no policies match                         |
+| `CREATE POLICY ... USING (expr)`               | ✅      | ✅               | SQLite: merged into `WHERE`; Postgres: native               |
+| `CREATE POLICY ... WITH CHECK (expr)`          | ✅      | ✅               | SQLite: validated in-memory; Postgres: native               |
+| `AS PERMISSIVE` (default)                      | ✅      | ✅               | Multiple permissive policies `OR`'d                         |
+| `AS RESTRICTIVE`                               | ✅      | ✅               | `AND`'d with combined permissive result                     |
+| `FOR SELECT / INSERT / UPDATE / DELETE / ALL`  | ✅      | ✅               | Per-command policy targeting                                |
+| `TO role` (`anon`, `authenticated`, `PUBLIC`)  | ✅      | ✅               | Role-based policy filtering; omitting `TO` = PUBLIC (warns) |
+| Auth placeholders (`auth.uid()`, `auth.jwt()`) | ✅      | ✅               | Resolved at runtime from JWT context                        |
+
+**Known limitations (SQLite):**
+
+| Limitation                              | Details                                                                                                                                                     |
+|-----------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Subquery `WITH CHECK` on `INSERT`       | `WITH CHECK` expressions containing subqueries (e.g. `user_id IN (SELECT ...)`) cannot be evaluated in-memory. Currently throws an error.                   |
+| `UPSERT` applies `INSERT` policies only | Postgres applies `UPDATE` policies on conflict; supalite applies `INSERT WITH CHECK` to all upsert rows since conflict resolution is unknown pre-execution. |
+| `FORCE ROW LEVEL SECURITY`              | Not differentiated from `ENABLE ROW LEVEL SECURITY`; table owner is not exempt.                                                                            |
+| `RETURNING` + `SELECT` policy           | Postgres errors if `RETURNING` references rows not visible to `SELECT` policy. Not checked.                                                                 |
+| `DROP POLICY` / `ALTER POLICY`          | Not yet supported in the DDL translator.                                                                                                                    |
+
+📖 See [`internal/docs/postgres/rls.md`](https://github.com/supabase-community/lite/blob/HEAD/internal/docs/postgres/rls.md) for the full RLS reference and behavior matrix.
+
+**PGlite / PostgreSQL auto-setup:** When any table has `ENABLE ROW LEVEL SECURITY`, supalite creates `anon` and `authenticated` roles (if missing) and grants default privileges on all tables and sequences in the relevant schemas. No manual `CREATE ROLE` or `GRANT` statements needed.
+
+### PL/pgSQL Trigger Functions
+
+Postgres trigger functions (`RETURNS TRIGGER`, `LANGUAGE plpgsql`) are translated into inline SQLite `CREATE TRIGGER` statements. The function body is parsed and stored in a registry. When the corresponding `CREATE TRIGGER` is reached, the body is inlined directly.
+
+**Supported statements:**
+
+| Statement                   | Example                                     | SQLite translation                                                      |
+|-----------------------------|---------------------------------------------|-------------------------------------------------------------------------|
+| `NEW.col = expr`            | `NEW.updated_at = now()`                    | `UPDATE table SET updated_at = datetime('now') WHERE rowid = NEW.rowid` |
+| `NEW.col := expr`           | `NEW.name := upper(NEW.name)`               | Same as above                                                           |
+| `INSERT INTO ...`           | `INSERT INTO profiles (id) VALUES (NEW.id)` | Pass-through inside trigger body                                        |
+| `UPDATE ...` / `DELETE ...` | Any DML                                     | Pass-through inside trigger body                                        |
+| `RETURN NEW` / `RETURN OLD` | Required in PG                              | Not emitted (implicit in SQLite)                                        |
+
+Multiple `NEW.col = expr` assignments are merged into a single `UPDATE ... SET` statement.
+
+**Trigger options:** `BEFORE`/`AFTER` timing, `INSERT`/`UPDATE`/`DELETE` events (and combinations), `UPDATE OF col1, col2`, `FOR EACH ROW`. `SECURITY DEFINER` is silently ignored.
+
+**Common Supabase patterns:** `handle_new_user` (insert into profiles on signup), `updated_at` timestamps, audit logging with `OLD`/`NEW` refs, counter updates.
+
+**Unsupported (throws descriptive error):** `DECLARE`, `IF`/`ELSIF`/`ELSE`, `LOOP`, `RAISE`, `PERFORM`, `SELECT INTO`, `EXECUTE`, variables, non-trigger functions.
+
+---
+
+## Database API (PostgREST-compatible)
+
+Request pipeline: HTTP request → PostgREST parser → internal AST → dialect-specific SQL (SQLite or Postgres).
+
+SQLite compatibility targets the [Cloudflare workerd SQLite version](https://github.com/cloudflare/workerd/blob/3861a920e639af7c3ab6bf10ee42f1235c415ac2/MODULE.bazel#L26) (currently 3.47).
+
+All operators are parsed into the AST. The "Status" column reflects whether a working **deparser handler** exists for that operator on each dialect.
+
+### Core Operations
+
+| Method     | SQLite | Postgres | Notes                                                               |
+|------------|--------|----------|---------------------------------------------------------------------|
+| `from()`   | ✅      | ✅        | Table/view selection                                                |
+| `select()` | ✅      | ✅        | Columns, aliases, aggregates (implicit GROUP BY), JSON paths, casts |
+| `insert()` | ✅      | ✅        | Single/batch, RETURNING (SQLite 3.35+)                              |
+| `update()` | ✅      | ✅        | With WHERE, RETURNING (SQLite 3.35+)                                |
+| `delete()` | ✅      | ✅        | With WHERE, RETURNING (SQLite 3.35+)                                |
+| `upsert()` | ✅      | ✅        | ON CONFLICT (SQLite 3.24+)                                          |
+
+### Comparison Filters
+
+| Method         | SQLite | Postgres | Notes                          |
+|----------------|--------|----------|--------------------------------|
+| `eq()`         | ✅      | ✅        |                                |
+| `neq()`        | ✅      | ✅        |                                |
+| `gt()`         | ✅      | ✅        |                                |
+| `gte()`        | ✅      | ✅        |                                |
+| `lt()`         | ✅      | ✅        |                                |
+| `lte()`        | ✅      | ✅        |                                |
+| `in()`         | ✅      | ✅        |                                |
+| `notIn()`      | ✅      | ✅        |                                |
+| `is()`         | ✅      | ✅        | `NULL`, `true`, `false` checks |
+| `isDistinct()` | ✅      | ✅        |                                |
+
+### Pattern Matching
+
+| Method         | SQLite | Postgres | Notes                                                 |
+|----------------|--------|----------|-------------------------------------------------------|
+| `like()`       | ✅      | ✅        |                                                       |
+| `ilike()`      | ✅      | ✅        | SQLite lowers both operands before `LIKE`             |
+| `likeAllOf()`  | ✅      | ✅        | SQLite expands quantified `LIKE` to `AND` predicates  |
+| `likeAnyOf()`  | ✅      | ✅        | SQLite expands quantified `LIKE` to `OR` predicates   |
+| `ilikeAllOf()` | ✅      | ✅        | SQLite lowers operands and expands to `AND` predicates |
+| `ilikeAnyOf()` | ✅      | ✅        | SQLite lowers operands and expands to `OR` predicates |
+
+### Array & JSON Filters
+
+| Method          | SQLite | Postgres | Notes                                                                                         |
+|-----------------|--------|----------|-----------------------------------------------------------------------------------------------|
+| `contains()`    | ⚠️     | ✅        | SQLite: scalar arrays via `json_each`; shallow objects via `json_extract`. See caveats below. |
+| `containedBy()` | ⚠️     | ✅        | SQLite: scalar arrays via `NOT EXISTS` over `json_each`. Objects/nested not supported.        |
+| `overlaps()`    | ⚠️     | ✅        | SQLite: scalar arrays via `EXISTS` over `json_each`. Objects/nested not supported.            |
+| `->` / `->>`    | ✅      | ✅        | JSON path in `select`, `order`, and `where` filters                                           |
+| `jsonb` column  | ✅      | ✅        | Stored as TEXT + `json_valid()` check on SQLite                                               |
+
+**SQLite containment caveats:**
+
+- ✅ **Arrays of scalars** (`tags=cs.{a,b}`): matches Postgres `@>` semantics via `json_each`.
+- ✅ **Shallow objects with scalar values** (`meta=cs.{"theme":"dark"}`): matched per-key with `json_extract(col, '$.key') = value`.
+- ✅ **NULL columns** are safely skipped (no `json_each(NULL)` error).
+- ✅ **Empty array input:** `cs []` → always true for non-null; `cd []` → only empty array matches; `ov []` → always false.
+- ❌ **Arrays of objects** (`[{a:1}] @> [{a:1}]`): `json_each` yields JSON text for object elements; equality against JS-serialized binds is not reliable. _Follow-up:_ emit a per-element `EXISTS` with recursive key matching, or a correlated subquery comparing `json_extract` of each target key.
+- ❌ **Nested objects in `cs` filter** (`data=cs.{"user":{"id":1}}`): `json_extract` returns the sub-object as JSON text which won't equal the JS-object bind. _Follow-up:_ recursively walk the filter object and emit one `json_extract` comparison per leaf scalar key (`json_extract(col, '$.user.id') = 1`).
+- ❌ **`cd`/`ov` with object values:** the operators currently require array inputs. _Follow-up:_ define semantics (does `cd` mean "all top-level keys in set"?) and add handlers.
+
+### Full-Text Search
+
+| Method                 | SQLite | Postgres | Notes                                        |
+|------------------------|--------|----------|----------------------------------------------|
+| `textSearch()` (fts)   | ❌     | ✅        | Not implemented on SQLite; FTS5 candidate (backlog) |
+| `textSearch()` (plfts) | ❌     | ✅        | Not implemented on SQLite                    |
+| `textSearch()` (phfts) | ❌     | ✅        | Not implemented on SQLite                    |
+| `textSearch()` (wfts)  | ❌     | ✅        | Not implemented on SQLite                    |
+
+### Advanced Filters
+
+| Method     | SQLite | Postgres | Notes                                           |
+|------------|--------|----------|-------------------------------------------------|
+| `match()`  | ✅      | ✅        | Multiple eq, expanded by parser, uses base ops |
+| `or()`     | ✅      | ✅        | Logical OR via `$or` in AST                     |
+| `not()`    | ✅      | ✅        | Logical NOT via `$not` in AST                   |
+| `filter()` | ✅      | ✅        | Delegates to individual operator handlers       |
+
+### Regex
+
+| Method          | SQLite | Postgres | Notes                                            |
+|-----------------|--------|----------|--------------------------------------------------|
+| `regexMatch()`  | ❌     | ✅        | Not implemented on SQLite; would require `regexp` extension  |
+| `regexIMatch()` | ❌     | ✅        | Not implemented on SQLite; would require `regexp` extension  |
+
+### Range Operators
+
+| Method            | SQLite | Postgres | Notes                    |
+|-------------------|--------|----------|--------------------------|
+| `rangeGt()`       | ❌      | ✅        | No range types in SQLite |
+| `rangeGte()`      | ❌      | ✅        |                          |
+| `rangeLt()`       | ❌      | ✅        |                          |
+| `rangeLte()`      | ❌      | ✅        |                          |
+| `rangeAdjacent()` | ❌      | ✅        |                          |
+
+### Quantified Comparison Operators
+
+| Method                  | SQLite | Postgres | Notes                        |
+|-------------------------|--------|----------|------------------------------|
+| `eq(any)` / `eq(all)`   | ❌     | ✅        | Not implemented on SQLite    |
+| `neq(any)` / `neq(all)` | ❌     | ✅        |                              |
+| `gt(any)` / `gt(all)`   | ❌     | ✅        |                              |
+| `gte(any)` / `gte(all)` | ❌     | ✅        |                              |
+| `lt(any)` / `lt(all)`   | ❌     | ✅        |                              |
+| `lte(any)` / `lte(all)` | ❌     | ✅        |                              |
+
+> Postgres `col=eq(any).{1,2,3}` compiles to `col = ANY(ARRAY[…])`. SQLite has no array type and no `ANY`/`ALL` quantified form on scalars; emulating it would require expanding to `OR`/`AND` chains over the literal list. Not implemented.
+
+### Transforms
+
+| Method          | SQLite | Postgres | Notes                           |
+|-----------------|--------|----------|---------------------------------|
+| `order()`       | ✅      | ✅        | NULLS FIRST/LAST (SQLite 3.30+) |
+| `limit()`       | ✅      | ✅        |                                 |
+| `range()`       | ✅      | ✅        | LIMIT + OFFSET                  |
+| `single()`      | ✅      | ✅        | Via Prefer header               |
+| `maybeSingle()` | ✅      | ✅        | Via Prefer header               |
+
+### Resource Embedding
+
+| Feature               | SQLite | Postgres | Notes                                                                                           |
+|-----------------------|--------|----------|-------------------------------------------------------------------------------------------------|
+| Foreign key joins     | ✅      | ✅        | Auto-resolved from introspection; embed null/not-null filters use relationship existence checks |
+| Spread (`...`)        | ✅      | ✅        | Inline embedded columns; array spreads preserve JSON object/array values and related ordering   |
+| Inner join (`!inner`) | ✅      | ✅        |                                                                                                 |
+| Nested embedding      | ✅      | ✅        | Multi-level joins                                                                               |
+| Aggregates            | ✅      | ✅        | count, sum, avg, min, max; spread aggregates return PGRST127                                    |
+
+### Response Shaping & Utilities
+
+| Method           | SQLite | Postgres | Notes                                 |
+|------------------|--------|----------|---------------------------------------|
+| `csv()`          | ✅     | ✅       | Input + output via `text/csv` Accept/Content-Type |
+| `geojson()`      | ❌      | ❌       | Requires SpatiaLite or PostGIS; not wired up |
+| `explain()`      | ⚠️     | ⚠️       | Returns compiled SQL via `application/vnd.pgrst.plan`; real plan output not surfaced |
+| `abortSignal()`  | ✅      | ✅        | Signal check before execution         |
+| `setHeader()`    | ✅      | ✅        | HTTP layer                            |
+| `throwOnError()` | ✅      | ✅        | JS error mode                         |
+| `maxAffected()`  | ✅      | ✅        | Check `changes()` after execution     |
+
+### Control & Specialized
+
+| Method            | SQLite | Postgres | Notes                                                 |
+|-------------------|--------|----------|-------------------------------------------------------|
+| `rpc()`           | ❌     | ✅        | Not supported on SQLite. Postgres RPC depends on stored procedures (`CREATE FUNCTION ... LANGUAGE sql/plpgsql`); SQLite has no stored-procedure model and we don't intend to introduce a parallel JS-function registry. Use a regular HTTP/server endpoint for custom logic. |
+| `schema()`        | ❌      | ✅        | SQLite has single schema                              |
+| `rollback()`      | ❌      | ❌        | PostgREST-specific, not implemented                   |
+| `returns()`       | ⚫      | ⚫        | TypeScript-only, no runtime effect                    |
+| `overrideTypes()` | ⚫      | ⚫        | TypeScript-only, no runtime effect                    |
+
+### Summary: Database API
+
+| Category        | SQLite                  | Postgres                |
+|-----------------|-------------------------|-------------------------|
+| Core CRUD (6)   | ✅ 6  ⚠️ 0  ❌ 0          | ✅ 6  ⚠️ 0  ❌ 0          |
+| Comparison (10) | ✅ 10 ⚠️ 0  ❌ 0          | ✅ 10 ⚠️ 0  ❌ 0          |
+| Pattern (6)     | ✅ 6  ⚠️ 0  ❌ 0          | ✅ 6  ⚠️ 0  ❌ 0          |
+| Array/JSON (3)  | ✅ 0  ⚠️ 3  ❌ 0          | ✅ 3  ⚠️ 0  ❌ 0          |
+| Full-Text (4)   | ✅ 0  ⚠️ 0  ❌ 4          | ✅ 4  ⚠️ 0  ❌ 0          |
+| Advanced (4)    | ✅ 4  ⚠️ 0  ❌ 0          | ✅ 4  ⚠️ 0  ❌ 0          |
+| Regex (2)       | ✅ 0  ⚠️ 0  ❌ 2          | ✅ 2  ⚠️ 0  ❌ 0          |
+| Range (5)       | ✅ 0  ⚠️ 0  ❌ 5          | ✅ 5  ⚠️ 0  ❌ 0          |
+| Quantified (12) | ✅ 0  ⚠️ 0  ❌ 12         | ✅ 12 ⚠️ 0  ❌ 0          |
+| Transforms (5)  | ✅ 5  ⚠️ 0  ❌ 0          | ✅ 5  ⚠️ 0  ❌ 0          |
+| Embedding (5)   | ✅ 5  ⚠️ 0  ❌ 0          | ✅ 5  ⚠️ 0  ❌ 0          |
+| Response (7)    | ✅ 5  ⚠️ 1  ❌ 1          | ✅ 5  ⚠️ 1  ❌ 1          |
+| Control (5)     | ✅ 0  ⚠️ 0  ❌ 3  ⚫ 2     | ✅ 2  ⚠️ 0  ❌ 1  ⚫ 2     |
+| **Total (74)**  | **✅ 41 ⚠️ 4  ❌ 27 ⚫ 2** | **✅ 69 ⚠️ 1  ❌ 2  ⚫ 2** |
+
+> Counting effective availability (✅ + ⚠️ + ⚫): **47/74 on SQLite**, **72/74 on Postgres** (`geojson()` and `rollback()` are the only gaps on Postgres). The 2 ⚫ methods (`returns`, `overrideTypes`) are TypeScript-only and need no backend.
+
+### PostgREST spec: SQLite skip breakdown
+
+The 263 cases skipped on SQLite (out of 1,702) cluster into a small set of upstream Postgres features that have no SQLite analogue. Generated by `cd app && bun run test:spec:analyze:sqlite` (writes `.context/sqlite-analysis.json`).
+
+| Category | Skipped | Why                                                                                  |
+|----------|--------:|--------------------------------------------------------------------------------------|
+| `feature_haskell_divergence_strict` | 46 | Strict Haskell PostgREST behaviour (header parsing, prefer modes) lite intentionally diverges from |
+| `domain_type`                       | 37 | Postgres `CREATE DOMAIN` types; no SQLite equivalent                                |
+| `pg_only_operators`                 | 36 | Postgres-specific operator syntax (`~`, `~*`, dictionary FTS, etc.)                  |
+| `tx_preferences`                    | 36 | `Prefer: tx=commit/rollback` and pre-request GUCs; no SQLite txn boundary           |
+| `cache_fk_names`                    | 23 | FK disambiguation paths exercising specific PG catalog metadata                      |
+| `pg_dictionary_fts`                 | 16 | Language-tagged full-text search dictionaries                                        |
+| `feature_error_codes`               | 11 | PostgREST/PG-specific SQLSTATE shapes                                                |
+| `cache_pg_types`                    | 10 | JSON operator behaviour tied to PG type cache                                        |
+| `pg_extension_specific`             | 10 | CORS / custom media types relying on PG extensions                                   |
+| `view_embedding`                    | 10 | View-FK resolution in PG-only metadata                                               |
+| `state_dependent`                   |  8 | Cases dependent on connection-pool/session state                                     |
+| `pg_role_set`                       |  4 | `SET LOCAL role` / JWT-driven role switching                                         |
+| `lite_anon_bearer_fallback`         |  4 | Lite-specific JWT fallback handling                                                  |
+| `computed_column`                   |  3 | PG `STORED`/`VIRTUAL` generated columns                                              |
+| `mutating_views`                    |  1 | Updatable view rules                                                                 |
+| `postgis`                           |  1 | PostGIS spatial types                                                                |
+| `xml_io`                            |  1 | XML output                                                                           |
+| `mutation_embed_two_query_limit`    |  2 | Embedded mutation w/ two-query plan                                                  |
+| `computed_relations`                |  1 | PG computed relationship overrides                                                   |
+| `collation_locale`                  |  1 | Locale-sensitive ordering                                                            |
+| `jsonb_dedup`                       |  2 | PG `jsonb` duplicate-key dedup semantics                                             |
+
+Run `bun run test:spec:analyze` (or `:sqlite-postgres`, `:pglite`, `:postgres`) to regenerate per backend.
+
+---
+
+## Auth API (GoTrue-compatible)
+
+Backend implementation in `app/src/auth/`. GoTrue-compatible HTTP endpoints at `/auth/v1/*`.
+
+### ✅ Implemented
+
+| Method                 | Endpoint                               | Notes                                                                 |
+|------------------------|----------------------------------------|-----------------------------------------------------------------------|
+| `signUp()`             | `POST /signup`                         | Email/password, optional metadata, email confirmation                 |
+| `signInWithPassword()` | `POST /token?grant_type=password`      | JWT + refresh token                                                   |
+| `signInWithOtp()`      | `POST /otp`                            | Magic link / OTP via email                                            |
+| `verifyOtp()`          | `POST /verify`                         | Supports: signup, magiclink, recovery, email_change, reauthentication |
+| `refreshSession()`     | `POST /token?grant_type=refresh_token` | Token rotation, immediate reuse compatibility, session expiry checks  |
+| `signOut()`            | `POST /logout`                         | Scopes: local, global, others                                         |
+| `getUser()`            | `GET /user`                            | JWT-authenticated                                                     |
+| `updateUser()`         | `PUT /user`                            | Metadata, password, email change                                      |
+| `recover()`            | `POST /recover`                        | Password reset email                                                  |
+| `resend()`             | `POST /resend`                         | Resend confirmation / email change                                    |
+| `reauthenticate()`     | `GET /reauthenticate`                  | Request reauthentication nonce                                        |
+
+Supporting infrastructure:
+
+- JWT signing/verification
+- Password hashing (bcrypt-compatible)
+- Refresh token rotation with revocation, reuse, and parent-chain tracking
+- Session management (create, validate, refresh, expire, delete)
+- Configurable email signup, confirmations, and secure/insecure email change
+- Mailer integration (confirmation, recovery, magic link, email change)
+
+### 🔄 Planned
+
+| Method                      | Notes                                                         |
+|-----------------------------|---------------------------------------------------------------|
+| `signInWithOAuth()`         | Config schema exists, major providers (Google, GitHub, Apple) |
+| `exchangeCodeForSession()`  | PKCE flow for OAuth                                           |
+| `signInAnonymously()`       | Create anonymous session                                      |
+| `linkIdentity()`            | Link OAuth identity to existing user                          |
+| `unlinkIdentity()`          | Remove linked identity                                        |
+| `admin.createUser()`        | Direct user creation (skip confirmation)                      |
+| `admin.listUsers()`         | Paginated user list                                           |
+| `admin.getUserById()`       | Fetch user by ID                                              |
+| `admin.updateUserById()`    | Direct user update                                            |
+| `admin.deleteUser()`        | User deletion                                                 |
+| `admin.inviteUserByEmail()` | Send invite                                                   |
+| `admin.generateLink()`      | Generate verification/reset links                             |
+| `admin.signOut()`           | Admin-initiated logout                                        |
+| `admin.mfa.listFactors()`   | List user MFA factors                                         |
+| `admin.mfa.deleteFactor()`  | Remove MFA factor                                             |
+
+### ⚫ Not Planned
+
+| Method                                 | Reason                         |
+|----------------------------------------|--------------------------------|
+| `mfa.enroll()`                         | MFA deferred                   |
+| `mfa.challenge()`                      | MFA deferred                   |
+| `mfa.verify()`                         | MFA deferred                   |
+| `mfa.challengeAndVerify()`             | MFA deferred                   |
+| `mfa.unenroll()`                       | MFA deferred                   |
+| `mfa.listFactors()`                    | MFA deferred                   |
+| `mfa.getAuthenticatorAssuranceLevel()` | MFA deferred                   |
+| `mfa.webauthn.*` (5 methods)           | WebAuthn deferred              |
+| `signInWithSSO()`                      | SAML/SSO deferred              |
+| `signInWithWeb3()`                     | Web3 deferred                  |
+| `signInWithIdToken()`                  | OIDC token validation deferred |
+| `oauth.getAuthorizationDetails()`      | OAuth server deferred          |
+| `oauth.approveAuthorization()`         | OAuth server deferred          |
+| `oauth.denyAuthorization()`            | OAuth server deferred          |
+| `oauth.listGrants()`                   | OAuth server deferred          |
+| `oauth.revokeGrant()`                  | OAuth server deferred          |
+| `oauth.listClients()`                  | OAuth admin deferred           |
+| `oauth.createClient()`                 | OAuth admin deferred           |
+| `oauth.getClient()`                    | OAuth admin deferred           |
+| `oauth.updateClient()`                 | OAuth admin deferred           |
+| `oauth.deleteClient()`                 | OAuth admin deferred           |
+| `oauth.regenerateClientSecret()`       | OAuth admin deferred           |
+
+### ⚫ Client-Side Only (N/A)
+
+These methods exist in `@supabase/supabase-js` but are client-side concerns, not backend endpoints:
+
+| Method                    | Notes                                                |
+|---------------------------|------------------------------------------------------|
+| `onAuthStateChange()`     | Client event listener                                |
+| `startAutoRefresh()`      | Client timer                                         |
+| `stopAutoRefresh()`       | Client timer                                         |
+| `getSession()`            | Client storage read                                  |
+| `setSession()`            | Client storage write                                 |
+| `initialize()`            | Client initialization                                |
+| `getClaims()`             | Client JWT parsing                                   |
+| `isThrowOnErrorEnabled()` | Client error mode                                    |
+| `resetPasswordForEmail()` | Client-side wrapper for `recover()`                  |
+| `getUserIdentities()`     | Client-side wrapper for identity data in `getUser()` |
+
+### Summary: Auth API
+
+| Status            | Count |
+|-------------------|-------|
+| ✅ Implemented     | 11    |
+| 🔄 Planned        | 15    |
+| ⚫ Not Planned     | 27    |
+| ⚫ Client-side N/A | 10    |
+
+### Auth spec: SQLite skip breakdown
+
+The 247 cases skipped against the supabase-spec Auth corpus break down by deferred feature. Generated by `cd app && bun run test:spec:auth:analyze:sqlite` (writes `.context/auth-analysis-sqlite.json`).
+
+| Category                        | Skipped | Why                                                                |
+|---------------------------------|--------:|--------------------------------------------------------------------|
+| `admin_api`                     | 69      | `/admin/*` endpoints (createUser, listUsers, generateLink, etc.)   |
+| `mfa`                           | 44      | TOTP/WebAuthn enroll/challenge/verify                              |
+| `non_runnable_spec_placeholder` | 29      | Upstream rows with `expected.status: null`; see `app/test/supabase-spec/auth/NON_RUNNABLE_PLACEHOLDERS.md` |
+| `oauth`                         | 24      | OAuth2/PKCE provider flows                                         |
+| `phone_sms`                     | 23      | Phone signup / SMS OTP                                             |
+| `saml_sso`                      | 18      | SAML / SSO                                                         |
+| `session_admin`                 | 12      | Admin session management                                           |
+| `anonymous`                     | 10      | `signInAnonymously()` and conversion flows                         |
+| `identity_linking`              | 9       | `linkIdentity()` / `unlinkIdentity()`                              |
+| `notification_hooks`            | 9       | Send-email/SMS hooks                                               |
+
+---
+
+## Storage API
+
+Backend implementation in `app/src/storage/`. HTTP endpoints at `/storage/v1/*`. Pluggable storage backends (filesystem, S3).
+
+### ✅ Implemented
+
+| Endpoint                               | Method   | Notes                                         |
+|----------------------------------------|----------|-----------------------------------------------|
+| `POST /bucket`                         | Create   | id, name, public, file_size_limit, mime types |
+| `GET /bucket`                          | List     |                                               |
+| `GET /bucket/:id`                      | Get      |                                               |
+| `PUT /bucket/:id`                      | Update   | public, file_size_limit, allowed_mime_types   |
+| `DELETE /bucket/:id`                   | Delete   | Fails if non-empty                            |
+| `POST /bucket/:id/empty`               | Empty    |                                               |
+| `POST /object/:bucketId/*`             | Upload   | Multipart form-data, upsert via `x-upsert`    |
+| `PUT /object/:bucketId/*`              | Replace  |                                               |
+| `GET /object/:bucketId/*`              | Download | Authenticated                                 |
+| `GET /object/public/:bucketId/*`       | Download | Public buckets, no auth                       |
+| `HEAD /object/:bucketId/*`             | Exists   |                                               |
+| `DELETE /object/:bucketId`             | Remove   | Batch delete by prefixes                      |
+| `POST /object/list/:bucketId`          | List     | prefix, limit, offset, sortBy, search         |
+| `POST /object/move`                    | Move     |                                               |
+| `POST /object/copy`                    | Copy     |                                               |
+| `GET /object/info/:bucketId/*`         | Info     | Object metadata                               |
+| `POST /object/sign/:bucketId/*`        | Sign     | Create signed download URL (JWT)              |
+| `POST /object/upload/sign/:bucketId/*` | Sign     | Create signed upload URL                      |
+| `GET /object/sign/:bucketId/*`         | Download | Via signed URL token                          |
+| `PUT /object/upload/sign/:bucketId/*`  | Upload   | Via signed upload URL                         |
+
+### Storage Adapters
+
+| Adapter            | Status | Notes                                      |
+|--------------------|--------|--------------------------------------------|
+| Filesystem         | ✅      | Local file storage                         |
+| S3 / S3-compatible | ✅      | MinIO, AWS S3, Cloudflare R2 via aws4fetch |
+| Cloudflare R2      | ✅      | Via S3 adapter                             |
+
+### Transformation Adapters
+
+| Adapter    | Status | Notes                       |
+|------------|--------|-----------------------------|
+| Noop       | ✅      | Passthrough (no transforms) |
+| Sharp      | ✅      | Resize, format conversion   |
+| Cloudflare | ✅      | URL-based image transforms  |
+
+### 🔄 Not Yet Implemented
+
+| Feature                        | Notes                                                      |
+|--------------------------------|------------------------------------------------------------|
+| `/status` health endpoint      | Oracle returns 200 with no auth                            |
+| Role-based access control      | service_role-only for admin ops, anon/authenticated gating |
+| RLS policies on storage tables | Per-user object access via row-level security              |
+| Bucket list query params       | `?search=`, `?limit=`, `?offset=` on `GET /bucket`         |
+| S3-compatible protocol         | `PUT/GET/DELETE` via S3 API paths (`/s3/`)                 |
+| TUS resumable uploads          | `POST/PATCH/HEAD` on `/upload/resumable`                   |
+| Webhooks                       | ObjectCreated/ObjectRemoved events                         |
+
+### Summary: Storage API
+
+| Status              | Count                        |
+|---------------------|------------------------------|
+| ✅ Endpoints         | 20                           |
+| ✅ Adapters          | 3 storage + 3 transformation |
+| 🔄 Missing features | 7                            |
+
+### Spec Test Results
+
+Tests run via supabase-spec JSON test cases against Postgres (pgserve). Run: `cd app && bun run test:phenotype:storage`
+
+| Category         | Pass | Fail | Notes                                       |
+|------------------|------|------|---------------------------------------------|
+| bucket_crud      | 36   | 2    | Fails: anon/authenticated access            |
+| object_upload    | 19   | 3    | Fails: anon access, size limit, auth format |
+| access_control   | --   | 48   | Needs RLS + role-based access               |
+| object_read      | --   | 28   | Cascade from setup/access issues            |
+| object_list      | --   | 26   | Cascade from setup/access issues            |
+| signed_urls      | --   | 24   | Cascade from setup/access issues            |
+| errors           | --   | 27   | Auth error format (401 vs 400)              |
+| object_move_copy | --   | 21   | Cascade from setup/access issues            |
+| object_naming    | --   | 15   | Cascade from setup/access issues            |
+| user_metadata    | --   | 10   | Cascade from setup/access issues            |
+| file_types       | --   | 8    | Cascade from setup/access issues            |
+| health           | --   | 3    | Missing `/status` endpoint                  |
+| object_delete    | --   | 3    | Cascade from setup/access issues            |
+
+> Many failures cascade from a few root issues (missing role-based access, auth error format). Fixing role checking, `/status`, and error format would flip a large number of tests.
+
+---
+
+## CLI
+
+Backend implementation in `app/src/cli/`. Aligned to upstream `supabase` CLI command shape (v2.98.2). Reference: [`internal/docs/cli/`](https://github.com/supabase-community/lite/tree/HEAD/internal/docs/cli/). Lite-only commands carry a `[lite]` tag in `--help` output.
+
+Help groups match upstream: **Local Development** (commands you run from a project) and **Management APIs** (commands that manage remote resources).
+
+### Top-Level
+
+| Command   | Status | Notes                                                              |
+|-----------|--------|--------------------------------------------------------------------|
+| `init`    | ✅      | Parity at verb level; flags differ from upstream                   |
+| `start`   | ✅      | In-process; no Docker stack flags (`-x`, `--ignore-health-check`)  |
+| `status`  | 🧪      | `[experimental]` `[lite]`: shows linked project metadata          |
+| `login`   | 🧪      | `[experimental]` Email/password against supalite cloud             |
+| `logout`  | 🧪      | `[experimental]` Parity                                            |
+| `link`    | 🧪      | `[experimental]` Parity at verb; no `--password`/`--skip-pooler`   |
+| `unlink`  | 🧪      | `[experimental]` Parity                                            |
+| `dev`     | ✅      | `[lite]`: schema-watching dev server; emits experimental warning  |
+| `repl`    | ✅      | `[lite]`: Node-only interactive REPL                              |
+| `debug`   | ✅      | `[lite]`: runtime info dump                                       |
+| `signup`  | 🧪      | `[experimental]` `[lite]`: register supalite cloud account        |
+| `whoami`  | 🧪      | `[experimental]` `[lite]`: current authenticated user             |
+| `upgrade` | ✅      | `[lite]`: migrate supalite project to hosted/local Supabase       |
+| `bootstrap` | ⚫    | Not planned (starter-template scaffolding belongs to upstream CLI) |
+| `stop`    | 🔄     | Not registered yet                                                 |
+| `services` | 🚫    | Not applicable; no Docker stack                                   |
+| `seed buckets` | 🔄 | Depends on storage support                                         |
+| `test db` / `test new` | 🚫 | Not applicable on SQLite (no pgTAP)                            |
+
+### `db` group
+
+| Command       | Status | Notes                                                                |
+|---------------|--------|----------------------------------------------------------------------|
+| `db diff`     | ✅      | Re-export of `db schema --diff` handler; `--local` semantics only    |
+| `db query`    | ✅      | Renamed from top-level `exec`; supports `--remote` and `--config`    |
+| `db schema`   | ✅      | `[lite]`: moved from top-level; `--diff` and `--sql` modes          |
+| `db push`     | 🔄     | Not registered; use `lite cloud deploy`                             |
+| `db pull`, `db reset`, `db dump`, `db lint`, `db advisors` | 🔄 | Not registered                       |
+| `db start`    | 🚫     | Not applicable; in-process, no separate DB start                    |
+
+### `migration` group
+
+| Command             | Status | Notes                                                  |
+|---------------------|--------|--------------------------------------------------------|
+| `migration diff`    | ✅      | `[lite]`: diff DB state against `schemas/*.sql`       |
+| `migration new`, `migration list`, `migration up`, `migration down`, `migration repair`, `migration squash`, `migration fetch` | 🔄 | Not registered |
+
+### `cloud` group `[lite]` `[experimental]`
+
+| Command         | Status | Notes                                                                       |
+|-----------------|--------|-----------------------------------------------------------------------------|
+| `cloud deploy`  | 🧪      | Pushes schema + config + seed to linked supalite cloud (renamed from `push`) |
+| `cloud diff`    | 🧪      | Diffs local against linked remote (renamed from `diff`)                     |
+
+### `config` group
+
+Not registered. `config push` (upstream pushes `config.toml` to the linked project's API config) is folded into `cloud deploy` until it's worth splitting.
+
+### `projects` group `[experimental]`
+
+| Command           | Status | Notes                                                  |
+|-------------------|--------|--------------------------------------------------------|
+| `projects list`   | 🧪      | List supalite cloud projects                           |
+| `projects create` | 🧪      | Create project; flags differ (no `--org-id`/`--region`) |
+| `projects api-keys` | 🔄   | Not registered                                         |
+| `projects delete`   | 🔄   | Not registered                                         |
+
+### Management API groups
+
+All management-API groups are deferred per LITE-177. None registered as placeholders to keep `--help` output clean. Re-evaluate per group as supalite cloud exposes matching endpoints.
+
+| Group | Status | Reason |
+|-------|--------|--------|
+| `orgs`, `secrets`, `branches`, `domains`, `network-bans`, `network-restrictions`, `ssl-enforcement`, `vanity-subdomains`, `encryption`, `sso` | 🔄 | Depends on supalite cloud surface area |
+| `gen`, `functions`, `inspect`, `storage`, `telemetry` | 🔄 | Depends on respective service support |
+| `backups`, `snippets`, `postgres-config`, `services` | 🚫 | Not applicable (SQLite / no dashboard / no Docker / no GUC) |
+
+### Environment & `.env`
+
+Mirrors upstream behavior documented in [`internal/docs/cli/environment.md`](https://github.com/supabase-community/lite/blob/HEAD/internal/docs/cli/environment.md). Loader runs in `ProjectLocalApi.readConfig` before TOML parsing; `env(VAR)` substitution runs after parsing, before schema validation.
+
+| Behavior                                                         | Status | Notes                                                            |
+|------------------------------------------------------------------|--------|------------------------------------------------------------------|
+| Dotenv directory walk (config dir → CWD)                         | ✅      | First-write-wins; deeper dir wins over parent                    |
+| `SUPABASE_ENV` flavor (default `development`; `test` skips `.env.local`) | ✅ | Filename order: `.env.<flavor>.local` → `.env.local` → `.env.<flavor>` → `.env` |
+| Process env never overwritten by files                           | ✅      | Shell/CI wins over every file                                    |
+| `env(VAR_NAME)` substitution in config                           | ✅      | Anchored match; missing → empty string                           |
+| `secrets set --env-file`                                         | ⚫      | Depends on `secrets` group (deferred)                            |
+| `functions serve --env-file` / `supabase/functions/.env`         | ⚫      | Depends on `functions` group (deferred)                          |
+
+### Summary: CLI
+
+| Status                      | Count |
+|-----------------------------|-------|
+| ✅ Implemented               | 22    |
+| 🔄 Planned (not registered) | 17    |
+| 🚫 Not Applicable           | 7     |
+
+> Counts include only commands tracked in this file (excludes management-API groups represented as a single row each).
+
+---
+
+## Other Services
+
+| Service            | Status | Notes                                                                                                 |
+|--------------------|--------|-------------------------------------------------------------------------------------------------------|
+| **Storage**        | 🔄     | Config schema defined (`app/src/config/storage.ts`). Buckets, file size limits, image transformation. |
+| **Drivers**        | ✅      | Minimal email, SMS, and cache driver interfaces. Configured via `options.drivers`, exposed at `app.drivers`. |
+| **Realtime**       | 🔄     | Config schema defined (`app/src/config/realtime.ts`).                                                 |
+| **Edge Functions** | 🔄     | Config schema defined (`app/src/config/functions.ts`). Per-function JWT verification, entrypoints.    |
+| **Vite plugin**    | ✅      | `@supabase/lite/vite` subpath export mounts supalite as middleware in a Vite dev server (`app/src/vite/`). |
+
+---
+
+## Upgrade to Supabase
+
+See [UPGRADE.md](https://github.com/supabase-community/lite/blob/HEAD/UPGRADE.md) for the upgrade command contract, target behavior, known gaps, and test strategy.
+
+| Capability                 | Status | Notes                                                                                           |
+|----------------------------|--------|-------------------------------------------------------------------------------------------------|
+| Self-service upgrade       | ⚠️     | User-mode CLI flow creates a hosted Supabase project by default, or upgrades the current directory into a local Supabase CLI workdir with `--target local`; applies schema, migrates auth/data, syncs hosted config, and preserves hosted sessions via signing-key import with weak-secret assessment. Disposable local Supabase rehearsals are available as opt-in Docker integration coverage. |
+| Auth schema migration      | ⚠️     | Core `auth.*` divergences are documented; auth export has explicit local/Supabase generated-column rules. |
+| User table data migration  | ✅     | Emits FK-ordered INSERTs, deserializes SQLite shim-backed fields before Postgres literal generation, and resets serial/bigserial sequences after explicit migrated IDs. |
+| SQLite shim health audit   | ✅     | `lite upgrade --dry-run` scans shim-backed fields with affected counts, sample raw values, and sample row IDs; `--json` switches the audit output to structured JSON. |
+| Storage/realtime migration | 🔄     | Upgrade command warns; migration support is deferred until those services land.                  |
+
+---
+
+## Testing
+
+| Test Suite | Passing           | Skipped     | Failed          | Assertions        | Files          |
+|------------|-------------------|-------------|-----------------|-------------------|----------------|
+| App        | **2,221 passing** | 486 skipped | 0 failed        | 17,186 assertions | 150 test files |
+| App (vitest: node + D1 + DO + KV) | **34 passing** | 0 skipped | 0 failed | 80 assertions | 4 test files |
+| Repo       | **3,248 passing** | 540 skipped | 0 failed | 30,961 assertions | 155 test files |
+
+Latest `cd app && bun test`, `cd app && bun run vitest`, and root `bun test --recursive` completed with zero failures.
+
+PostgREST spec status (`cd app && bun run test:spec:status`):
+
+| Backend | Total | Passing | Pass % | Skipped | Skip % | Failed |
+|---------|------:|--------:|-------:|--------:|-------:|-------:|
+| Postgres | 2,460 | **1,752** | 71.2% | 708 | 28.8% | 0 |
+| PGlite | 2,460 | **1,746** | 71.0% | 714 | 29.0% | 0 |
+| SQLite | 1,702 | **1,439** | 84.5% | 263 | 15.5% | 0 |
+| SQLite-Postgres | 1,702 | **1,479** | 86.9% | 223 | 13.1% | 0 |
+
+Auth supabase-spec status (`cd app && bun run test:spec:auth`):
+
+| Backend | Total | Passing | Pass % | Skipped | Skip % | Failed |
+|---------|------:|--------:|-------:|--------:|-------:|-------:|
+| Postgres | 488 | **241** | 49.4% | 247 | 50.6% | 0 |
+| PGlite | 488 | **241** | 49.4% | 247 | 50.6% | 0 |
+| SQLite | 488 | **241** | 49.4% | 247 | 50.6% | 0 |
+| SQLite-Postgres | 488 | **241** | 49.4% | 247 | 50.6% | 0 |
+
+### Methodology
+
+Feature status tables above are validated by ported test suites run against both the **vendor implementation** and **this project**, ensuring claimed compatibility is real.
+
+**PostgREST (Database API):** 501 test cases extracted from the upstream [PostgREST Haskell test suite](https://github.com/PostgREST/postgrest) into JSON specs (`packages/postgrest-test-suite/`). Verified by running against real PostgREST and PostgreSQL via Docker. All 501 pass against vendor. The same suite runs against lite's implementation on four backends (`postgres`, `pglite`, `sqlite`, `sqlite-postgres`), with skips documented per dialect for known incompatibilities (JSON operators, range types, full-text search locale differences). Run `bun run test:spec:status` in `app/` to regenerate the baseline table. `sqlite-postgres` exercises the deparser path end users hit with `driver: "sqlite-postgres"`.
+
+**Auth (GoTrue):** 51 test cases across 12 spec files (`packages/gotrue-test-suite/`) covering all 11 implemented endpoints. Verified by running against the vendor GoTrue Docker image (v2.186.0) with PostgreSQL + Inbucket (email trap). The same suite runs against lite's auth implementation on both SQLite and PostgreSQL. The upstream `supabase-spec` Auth JSON cases also run against lite's SQLite auth implementation under `app/test/supabase-spec/auth/`; the baseline now unskips passing email/password/refresh/user, error-shape, health/settings/JWKS, response-shape, email side-effect, logout/reauthenticate DB-change, magic-link, email OTP/verify token, refresh rotation, session lifecycle, short JWT-expiry, non-phone config-variant, recovery password-change, and duplicate-signup/form-token response-shape cases. Remaining Auth skips are hard-scoped product areas or non-runnable upstream placeholder rows documented in `app/test/supabase-spec/auth/NON_RUNNABLE_PLACEHOLDERS.md`; there are no current addressable Auth skips. Run `bun run test:spec:auth:analyze` in `app/` to execute all Auth JSON cases and group current mismatch signatures.
+
+Both test suites are reusable packages exposing `definePostgrestTests()` and `defineAuthTests()`. They accept either a URL (for vendor) or a fetch handler (for direct in-process testing).
+
+### Running Tests
+
+```bash
+bun test                    # all app tests (bun:sqlite connection suite runs here)
+bun test:coverage           # all app tests + coverage report
+bun test:postgrest          # PostgREST suite against Postgres
+bun test:gotrue             # GoTrue suite against vendor Docker
+bun run test:spec:auth      # supabase-spec Auth JSON suite against SQLite
+bun run test:spec:auth:analyze # grouped Auth supabase-spec mismatch report
+bun run vitest              # node:sqlite + D1 + DO connection suites
+```
+
+**Connection contract suite** (`app/test/db/connection-suite/`): one
+`suite.ts` defines the contract every `SqliteConnection` must honour
+(bind normalization, CRUD, RLS-guarded select, transactions,
+introspection), and runs against each backend via thin per-runner
+entries. `bun:sqlite` uses `bun:test` (runs as part of `bun test`);
+`node:sqlite`, `D1`, and `DurableObject` use `vitest`, with D1/DO routed
+through `@cloudflare/vitest-pool-workers`. See the suite README for scope
+differences per runtime.
+
+Full GoTrue test suite:
+
+```bash
+cd packages/gotrue-test-suite && bun test
+```
+
+Full PostgREST test suite:
+
+```bash
+cd packages/postgrest-test-suite && bun run test:postgres
+cd packages/postgrest-test-suite && bun run test:pgserve
+```
+
+---
+
+## Documentation
+
+Detailed API research docs are in `internal/docs/sdk/`:
+
+- [`internal/docs/sdk/database/`](https://github.com/supabase-community/lite/blob/HEAD/internal/docs/sdk/database/README.md): 66 database methods with SQLite compatibility analysis
+- [`internal/docs/sdk/auth/`](https://github.com/supabase-community/lite/blob/HEAD/internal/docs/sdk/auth/README.md): 68 auth methods with implementation complexity analysis