@prabhask5/stellar-engine 1.1.6 → 1.1.8

package/dist/supabase/client.d.ts

@@ -1,15 +1,88 @@
 /**
- * Supabase Client - Lazy Initialization via Proxy
+ * @fileoverview Supabase Client — Lazy Initialization via ES Proxy
  *
- * Uses runtime config instead of build-time $env/static/public.
- * The Proxy pattern preserves the exact same API surface.
+ * This module exports a single `supabase` constant that looks and behaves
+ * exactly like a `SupabaseClient` instance, but is actually an ES `Proxy`
+ * that defers client creation until the **first property access**. This
+ * "lazy singleton" pattern solves a critical bootstrapping problem:
+ *
+ *   The Supabase URL and anon key are loaded at **runtime** (via
+ *   `getConfig()` from `../runtime/runtimeConfig`), not at build time.
+ *   Modules that `import { supabase }` at the top level would otherwise
+ *   crash because the config has not been initialized yet when the import
+ *   executes.
+ *
+ * How the Proxy pattern works:
+ *   1. `supabase` is exported as `new Proxy({} as SupabaseClient, handler)`.
+ *   2. The handler's `get` trap intercepts every property access (e.g.
+ *      `supabase.auth`, `supabase.from(...)`).
+ *   3. On first access, `getOrCreateClient()` reads the runtime config and
+ *      calls `createClient(url, key, options)` to build the real client.
+ *   4. The real client is cached in a module-level `realClient` variable;
+ *      subsequent accesses reuse it (standard singleton).
+ *   5. Function values are `.bind(client)` to preserve `this` context.
+ *
+ * Additional responsibilities:
+ *   - **Corrupted session cleanup**: Before the client is created, any
+ *     malformed `sb-*` entries in localStorage are detected and removed to
+ *     prevent "can't access property 'hash'" runtime errors.
+ *   - **Unhandled rejection handler**: A global listener catches Supabase
+ *     auth errors that escape normal error handling, clears storage, and
+ *     performs a single guarded page reload to recover.
+ *   - **iOS PWA detection**: The client sends a custom `x-client-info`
+ *     header indicating whether it is running as a standalone PWA on iOS,
+ *     which helps with server-side debugging of session eviction issues.
+ *
+ * Security considerations:
+ *   - The anon key is a **public** key (safe to include in client bundles).
+ *   - PKCE flow is used instead of the implicit flow for stronger OAuth
+ *     security and better compatibility with PWA environments.
+ *   - Session persistence uses localStorage; the module proactively scrubs
+ *     corrupted entries to prevent denial-of-service via bad local state.
+ *
+ * @module supabase/client
  */
 import { type SupabaseClient } from '@supabase/supabase-js';
+/**
+ * Override the storage key prefix used by the Supabase client.
+ *
+ * Must be called **before** the first access to the `supabase` export,
+ * since the prefix is baked into the client options at creation time.
+ *
+ * @param prefix - The new prefix string (e.g. the app's name).
+ *
+ * @example
+ * ```ts
+ * _setClientPrefix('myapp');
+ * // Later accesses will use storageKey 'myapp-auth'
+ * ```
+ */
 export declare function _setClientPrefix(prefix: string): void;
 /**
- * Proxy-based lazy singleton.
- * Delegates all property access to the real SupabaseClient,
- * which is created on first access using getConfig().
+ * The public Supabase client — a Proxy-based lazy singleton.
+ *
+ * **Why a Proxy?**
+ * The Supabase URL and anon key are not available at import time (they come
+ * from a runtime config that is loaded asynchronously). A Proxy lets every
+ * module `import { supabase }` at the top level without worrying about
+ * initialization order. The real client is created transparently on first
+ * property access.
+ *
+ * **How it works:**
+ * - The `get` trap intercepts every property read (e.g. `supabase.auth`,
+ *   `supabase.from`).
+ * - It calls `getOrCreateClient()` to ensure the real client exists.
+ * - It forwards the property access via `Reflect.get`.
+ * - Function values are `.bind(client)` to keep `this` correct when the
+ *   caller destructures methods (e.g. `const { from } = supabase`).
+ *
+ * @example
+ * ```ts
+ * import { supabase } from './client';
+ *
+ * // Works immediately — the Proxy defers creation until this line runs:
+ * const { data } = await supabase.from('users').select('*');
+ * ```
  */
 export declare const supabase: SupabaseClient;
 //# sourceMappingURL=client.d.ts.map

package/dist/supabase/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/supabase/client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAM1E,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,QAE9C;AAqJD;;;;GAIG;AACH,eAAO,MAAM,QAAQ,EAAE,cASrB,CAAC"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/supabase/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAe1E;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,QAE9C;AAwND;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,QAAQ,EAAE,cASrB,CAAC"}

package/dist/supabase/client.js

@@ -1,18 +1,92 @@
 /**
- * Supabase Client - Lazy Initialization via Proxy
+ * @fileoverview Supabase Client — Lazy Initialization via ES Proxy
  *
- * Uses runtime config instead of build-time $env/static/public.
- * The Proxy pattern preserves the exact same API surface.
+ * This module exports a single `supabase` constant that looks and behaves
+ * exactly like a `SupabaseClient` instance, but is actually an ES `Proxy`
+ * that defers client creation until the **first property access**. This
+ * "lazy singleton" pattern solves a critical bootstrapping problem:
+ *
+ *   The Supabase URL and anon key are loaded at **runtime** (via
+ *   `getConfig()` from `../runtime/runtimeConfig`), not at build time.
+ *   Modules that `import { supabase }` at the top level would otherwise
+ *   crash because the config has not been initialized yet when the import
+ *   executes.
+ *
+ * How the Proxy pattern works:
+ *   1. `supabase` is exported as `new Proxy({} as SupabaseClient, handler)`.
+ *   2. The handler's `get` trap intercepts every property access (e.g.
+ *      `supabase.auth`, `supabase.from(...)`).
+ *   3. On first access, `getOrCreateClient()` reads the runtime config and
+ *      calls `createClient(url, key, options)` to build the real client.
+ *   4. The real client is cached in a module-level `realClient` variable;
+ *      subsequent accesses reuse it (standard singleton).
+ *   5. Function values are `.bind(client)` to preserve `this` context.
+ *
+ * Additional responsibilities:
+ *   - **Corrupted session cleanup**: Before the client is created, any
+ *     malformed `sb-*` entries in localStorage are detected and removed to
+ *     prevent "can't access property 'hash'" runtime errors.
+ *   - **Unhandled rejection handler**: A global listener catches Supabase
+ *     auth errors that escape normal error handling, clears storage, and
+ *     performs a single guarded page reload to recover.
+ *   - **iOS PWA detection**: The client sends a custom `x-client-info`
+ *     header indicating whether it is running as a standalone PWA on iOS,
+ *     which helps with server-side debugging of session eviction issues.
+ *
+ * Security considerations:
+ *   - The anon key is a **public** key (safe to include in client bundles).
+ *   - PKCE flow is used instead of the implicit flow for stronger OAuth
+ *     security and better compatibility with PWA environments.
+ *   - Session persistence uses localStorage; the module proactively scrubs
+ *     corrupted entries to prevent denial-of-service via bad local state.
+ *
+ * @module supabase/client
  */
 import { createClient } from '@supabase/supabase-js';
 import { getConfig } from '../runtime/runtimeConfig';
 import { debugLog, debugWarn, debugError } from '../debug';
+// =============================================================================
+// SECTION: Client Prefix Configuration
+// =============================================================================
+/**
+ * Prefix used for the Supabase `storageKey` and custom headers.
+ * Defaults to `'stellar'`; can be overridden by the host application
+ * via {@link _setClientPrefix} before the client is first accessed.
+ */
 let _prefix = 'stellar';
+/**
+ * Override the storage key prefix used by the Supabase client.
+ *
+ * Must be called **before** the first access to the `supabase` export,
+ * since the prefix is baked into the client options at creation time.
+ *
+ * @param prefix - The new prefix string (e.g. the app's name).
+ *
+ * @example
+ * ```ts
+ * _setClientPrefix('myapp');
+ * // Later accesses will use storageKey 'myapp-auth'
+ * ```
+ */
 export function _setClientPrefix(prefix) {
     _prefix = prefix;
 }
-// Clear corrupted Supabase auth data from localStorage if it exists
-// This prevents "can't access property 'hash'" errors during initialization
+// =============================================================================
+// SECTION: Corrupted Session Cleanup
+// =============================================================================
+/**
+ * Scan localStorage for corrupted Supabase auth entries and remove them.
+ *
+ * Supabase stores session data under keys prefixed with `sb-`. If the
+ * browser was closed mid-write, or if a bug produced malformed JSON, these
+ * entries can cause runtime errors like "can't access property 'hash' of
+ * undefined" on the next page load.
+ *
+ * This function runs **once** at module evaluation time (before the client
+ * is created) and acts as a defensive self-healing mechanism.
+ *
+ * @internal
+ */
 function clearCorruptedAuthData() {
     if (typeof localStorage === 'undefined')
         return;
@@ -41,7 +115,9 @@ function clearCorruptedAuthData() {
                     }
                 }
                 catch {
-                    // JSON parse failed - data is corrupted
+                    /* JSON.parse failed — the stored value is not valid JSON, which
+                       means the data was partially written or otherwise corrupted.
+                       Removing it is the safest recovery action. */
                     debugWarn('[Auth] Clearing malformed session data:', key);
                     localStorage.removeItem(key);
                 }
@@ -52,7 +128,13 @@ function clearCorruptedAuthData() {
         debugError('[Auth] Error checking localStorage:', e);
     }
 }
-// Add global handler for unhandled Supabase auth errors
+// =============================================================================
+// SECTION: Global Error Recovery
+// =============================================================================
+/* Register a global unhandled-rejection handler that catches Supabase auth
+   errors which escape normal try/catch boundaries. This is a last-resort
+   recovery mechanism: clear the corrupted storage and reload once. A
+   sessionStorage flag (`__stellar_auth_reload`) guards against reload loops. */
 if (typeof window !== 'undefined') {
     // Clear reload guard on successful startup (app loaded without crashing)
     try {
@@ -73,7 +155,8 @@ if (typeof window !== 'undefined') {
                 try {
                     const keys = Object.keys(localStorage).filter((k) => k.startsWith('sb-'));
                     keys.forEach((k) => localStorage.removeItem(k));
-                    // Guard against reload loop: only reload once per session
+                    /* Guard against reload loop: only reload once per browser session.
+                       Without this guard, a persistent error could cause infinite reloads. */
                     if (!sessionStorage.getItem('__stellar_auth_reload')) {
                         sessionStorage.setItem('__stellar_auth_reload', '1');
                         window.location.reload();
@@ -86,17 +169,51 @@ if (typeof window !== 'undefined') {
         }
     });
 }
-// Run cleanup before creating client
+// =============================================================================
+// SECTION: Module-Level Initialization
+// =============================================================================
+/* Run the corruption cleanup synchronously at module load time, before any
+   code can attempt to read the (potentially corrupted) session data. */
 clearCorruptedAuthData();
-// Detect if running as iOS PWA (standalone mode)
+/**
+ * Detect if the app is running as an iOS PWA (standalone mode).
+ *
+ * iOS PWAs have unique session-persistence challenges: Safari's
+ * Intelligent Tracking Prevention (ITP) and aggressive localStorage
+ * eviction can cause sessions to disappear unexpectedly. Knowing we are
+ * in this environment lets us log more aggressively and send a custom
+ * header for server-side debugging.
+ */
 const isIOSPWA = typeof window !== 'undefined' &&
     // @ts-expect-error - navigator.standalone is iOS-specific
     (window.navigator.standalone === true || window.matchMedia('(display-mode: standalone)').matches);
 if (isIOSPWA) {
     debugLog('[Auth] Running as iOS PWA - using enhanced auth persistence');
 }
-// Lazy singleton: actual client is created on first access
+// =============================================================================
+// SECTION: Lazy Singleton Client
+// =============================================================================
+/** The cached SupabaseClient instance, created on first access. */
 let realClient = null;
+/**
+ * Create (or return the cached) SupabaseClient instance.
+ *
+ * On first invocation this reads the runtime config, constructs the client
+ * with appropriate auth options, and wires up an `onAuthStateChange`
+ * listener for debug logging. Subsequent calls return the cached instance.
+ *
+ * Client configuration highlights:
+ * - `persistSession: true` — sessions survive page reloads via localStorage.
+ * - `autoRefreshToken: true` — the SDK refreshes tokens before they expire.
+ * - `flowType: 'pkce'` — PKCE is more secure than the implicit flow and
+ *   works better with PWA and mobile browser environments.
+ * - `storageKey: '{prefix}-auth'` — namespaced to avoid collisions when
+ *   multiple Supabase-backed apps share the same origin.
+ *
+ * @returns The fully-initialized `SupabaseClient`.
+ *
+ * @internal Called exclusively by the Proxy `get` trap below.
+ */
 function getOrCreateClient() {
     if (realClient)
         return realClient;
@@ -130,7 +247,9 @@ function getOrCreateClient() {
     if (typeof window !== 'undefined') {
         realClient.auth.onAuthStateChange((event, session) => {
             debugLog(`[Auth] State change: ${event}`, session ? `User: ${session.user?.id}` : 'No session');
-            // If session is lost unexpectedly, this helps identify the issue
+            /* iOS PWAs can lose sessions silently when Safari evicts localStorage.
+               Logging SIGNED_OUT events specifically for PWAs makes this visible
+               in remote debugging tools. */
             if (event === 'SIGNED_OUT' && isIOSPWA) {
                 debugWarn('[Auth] Signed out on iOS PWA - session may have been evicted');
             }
@@ -141,10 +260,34 @@ function getOrCreateClient() {
     }
     return realClient;
 }
+// =============================================================================
+// SECTION: Proxy Export
+// =============================================================================
 /**
- * Proxy-based lazy singleton.
- * Delegates all property access to the real SupabaseClient,
- * which is created on first access using getConfig().
+ * The public Supabase client — a Proxy-based lazy singleton.
+ *
+ * **Why a Proxy?**
+ * The Supabase URL and anon key are not available at import time (they come
+ * from a runtime config that is loaded asynchronously). A Proxy lets every
+ * module `import { supabase }` at the top level without worrying about
+ * initialization order. The real client is created transparently on first
+ * property access.
+ *
+ * **How it works:**
+ * - The `get` trap intercepts every property read (e.g. `supabase.auth`,
+ *   `supabase.from`).
+ * - It calls `getOrCreateClient()` to ensure the real client exists.
+ * - It forwards the property access via `Reflect.get`.
+ * - Function values are `.bind(client)` to keep `this` correct when the
+ *   caller destructures methods (e.g. `const { from } = supabase`).
+ *
+ * @example
+ * ```ts
+ * import { supabase } from './client';
+ *
+ * // Works immediately — the Proxy defers creation until this line runs:
+ * const { data } = await supabase.from('users').select('*');
+ * ```
  */
 export const supabase = new Proxy({}, {
     get(_target, prop, receiver) {

package/dist/supabase/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/supabase/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/supabase/client.ts"],"names":[],"mappings":"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"}

package/dist/supabase/validate.d.ts

@@ -1,20 +1,114 @@
 /**
- * Supabase Validation
+ * @fileoverview Supabase Validation Module
  *
- * 1. Credential validation: Tests connectivity using provided credentials (setup flows).
- * 2. Schema validation: Verifies that all configured Supabase tables exist and are accessible.
+ * Provides two complementary validation capabilities:
+ *
+ * 1. **Credential validation** (`validateSupabaseCredentials`):
+ *    Tests that a given Supabase URL and anon key are well-formed and can
+ *    reach the Supabase REST API. Used during setup / onboarding flows
+ *    where the user manually enters their project credentials.
+ *
+ * 2. **Schema validation** (`validateSchema`):
+ *    Verifies that every table declared in the engine config actually exists
+ *    in the Supabase project and is accessible under the current RLS policies.
+ *    This is a "smoke test" that catches misconfiguration early, before the
+ *    sync engine attempts real reads/writes and produces cryptic errors.
+ *
+ * Security considerations:
+ *   - Credential validation creates a **temporary** `SupabaseClient` scoped
+ *     to the function call; it does not leak into the module-level singleton.
+ *   - Schema validation queries use `LIMIT 0`, so no user data is fetched —
+ *     the query only confirms that the table exists and RLS allows access.
+ *   - Error messages are deliberately generic to avoid leaking internal
+ *     database structure to end users; detailed errors go to `debugError`.
+ *
+ * Integration patterns:
+ *   - Called from setup wizards, admin panels, and health-check utilities.
+ *   - `validateSchema` uses the shared `supabase` proxy from `./client.ts`,
+ *     so it benefits from the same lazy-init and session management.
+ *
+ * @module supabase/validate
+ */
+/**
+ * Validate Supabase credentials by attempting a lightweight API call.
+ *
+ * This function is designed for **setup flows** where a user provides their
+ * Supabase URL and anon key and the app needs to verify them before saving.
+ *
+ * Validation steps:
+ * 1. Parse the URL to ensure it is syntactically valid.
+ * 2. Create a disposable `SupabaseClient` with the provided credentials.
+ * 3. Issue a `SELECT id FROM <testTable> LIMIT 1` query.
+ * 4. Interpret the response:
+ *    - Success or "relation does not exist" => credentials are valid (the
+ *      API responded, so URL + key are correct; the table simply may not
+ *      have been created yet).
+ *    - "Invalid API key" / PGRST301 => credentials are wrong.
+ *    - Network error => Supabase is unreachable.
+ *
+ * @param url       - The Supabase project URL (e.g. `https://xyz.supabase.co`).
+ * @param anonKey   - The project's anonymous (public) API key.
+ * @param testTable - Optional table name to query. Defaults to `'_health_check'`.
+ *                    Using a table that does not exist is fine — we only care
+ *                    whether the API responds, not whether the table is present.
+ * @returns An object with `valid: true` on success, or `valid: false` plus an
+ *          `error` message describing what went wrong.
+ *
+ * @example
+ * ```ts
+ * const result = await validateSupabaseCredentials(
+ *   'https://abc.supabase.co',
+ *   'eyJhbGci...',
+ *   'profiles'
+ * );
+ * if (!result.valid) {
+ *   showError(result.error);
+ * }
+ * ```
+ *
+ * @see {@link validateSchema} — for post-setup table existence checks
  */
 export declare function validateSupabaseCredentials(url: string, anonKey: string, testTable?: string): Promise<{
     valid: boolean;
     error?: string;
 }>;
 /**
- * Validates that all configured Supabase tables exist and are accessible.
+ * Validate that all tables declared in the engine configuration exist in
+ * Supabase and are accessible under the current RLS policies.
+ *
+ * For each table the function executes:
+ * ```sql
+ * SELECT id FROM <table> LIMIT 0
+ * ```
+ * This returns **zero rows** (no data egress, minimal latency) but still
+ * exercises the full PostgREST pipeline — table lookup, RLS policy
+ * evaluation, and column resolution. If any of these steps fail, the table
+ * is flagged.
+ *
+ * When device verification is enabled in the engine config, the
+ * `trusted_devices` table is automatically appended to the check list.
+ *
+ * Error categorization:
+ * - **Missing table**: The relation does not exist in the database.
+ * - **Permission denied (42501)**: The table exists but RLS or grants
+ *   prevent the anon role from reading it.
+ * - **Other**: Any unexpected PostgREST or network error.
+ *
+ * @returns An object containing:
+ *   - `valid` — `true` when all tables pass, `false` otherwise.
+ *   - `missingTables` — names of tables that do not exist at all.
+ *   - `errors` — human-readable descriptions of every issue found.
  *
- * Fires `SELECT id FROM <table> LIMIT 0` per table — returns zero rows (no data egress)
- * but validates the table exists and RLS allows access.
+ * @example
+ * ```ts
+ * const { valid, missingTables, errors } = await validateSchema();
+ * if (!valid) {
+ *   console.error('Schema issues:', errors);
+ *   // Prompt user to run migrations or fix RLS policies
+ * }
+ * ```
  *
- * If device verification is enabled, also validates the `trusted_devices` table.
+ * @see {@link validateSupabaseCredentials} — for pre-setup credential checks
  */
 export declare function validateSchema(): Promise<{
     valid: boolean;

package/dist/supabase/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/supabase/validate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,wBAAsB,2BAA2B,CAC/C,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAqC7C;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC;IAC9C,KAAK,EAAE,OAAO,CAAC;IACf,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAAC,CA4CD"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/supabase/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAWH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAsB,2BAA2B,CAC/C,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA0C7C;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC;IAC9C,KAAK,EAAE,OAAO,CAAC;IACf,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAAC,CAiDD"}

package/dist/supabase/validate.js

@@ -1,13 +1,80 @@
 /**
- * Supabase Validation
+ * @fileoverview Supabase Validation Module
  *
- * 1. Credential validation: Tests connectivity using provided credentials (setup flows).
- * 2. Schema validation: Verifies that all configured Supabase tables exist and are accessible.
+ * Provides two complementary validation capabilities:
+ *
+ * 1. **Credential validation** (`validateSupabaseCredentials`):
+ *    Tests that a given Supabase URL and anon key are well-formed and can
+ *    reach the Supabase REST API. Used during setup / onboarding flows
+ *    where the user manually enters their project credentials.
+ *
+ * 2. **Schema validation** (`validateSchema`):
+ *    Verifies that every table declared in the engine config actually exists
+ *    in the Supabase project and is accessible under the current RLS policies.
+ *    This is a "smoke test" that catches misconfiguration early, before the
+ *    sync engine attempts real reads/writes and produces cryptic errors.
+ *
+ * Security considerations:
+ *   - Credential validation creates a **temporary** `SupabaseClient` scoped
+ *     to the function call; it does not leak into the module-level singleton.
+ *   - Schema validation queries use `LIMIT 0`, so no user data is fetched —
+ *     the query only confirms that the table exists and RLS allows access.
+ *   - Error messages are deliberately generic to avoid leaking internal
+ *     database structure to end users; detailed errors go to `debugError`.
+ *
+ * Integration patterns:
+ *   - Called from setup wizards, admin panels, and health-check utilities.
+ *   - `validateSchema` uses the shared `supabase` proxy from `./client.ts`,
+ *     so it benefits from the same lazy-init and session management.
+ *
+ * @module supabase/validate
  */
 import { createClient } from '@supabase/supabase-js';
 import { getEngineConfig } from '../config';
 import { supabase } from './client';
 import { debugError, debugLog } from '../debug';
+// =============================================================================
+// SECTION: Credential Validation
+// =============================================================================
+/**
+ * Validate Supabase credentials by attempting a lightweight API call.
+ *
+ * This function is designed for **setup flows** where a user provides their
+ * Supabase URL and anon key and the app needs to verify them before saving.
+ *
+ * Validation steps:
+ * 1. Parse the URL to ensure it is syntactically valid.
+ * 2. Create a disposable `SupabaseClient` with the provided credentials.
+ * 3. Issue a `SELECT id FROM <testTable> LIMIT 1` query.
+ * 4. Interpret the response:
+ *    - Success or "relation does not exist" => credentials are valid (the
+ *      API responded, so URL + key are correct; the table simply may not
+ *      have been created yet).
+ *    - "Invalid API key" / PGRST301 => credentials are wrong.
+ *    - Network error => Supabase is unreachable.
+ *
+ * @param url       - The Supabase project URL (e.g. `https://xyz.supabase.co`).
+ * @param anonKey   - The project's anonymous (public) API key.
+ * @param testTable - Optional table name to query. Defaults to `'_health_check'`.
+ *                    Using a table that does not exist is fine — we only care
+ *                    whether the API responds, not whether the table is present.
+ * @returns An object with `valid: true` on success, or `valid: false` plus an
+ *          `error` message describing what went wrong.
+ *
+ * @example
+ * ```ts
+ * const result = await validateSupabaseCredentials(
+ *   'https://abc.supabase.co',
+ *   'eyJhbGci...',
+ *   'profiles'
+ * );
+ * if (!result.valid) {
+ *   showError(result.error);
+ * }
+ * ```
+ *
+ * @see {@link validateSchema} — for post-setup table existence checks
+ */
 export async function validateSupabaseCredentials(url, anonKey, testTable) {
     try {
         new URL(url);
@@ -16,6 +83,9 @@ export async function validateSupabaseCredentials(url, anonKey, testTable) {
         return { valid: false, error: 'Invalid Supabase URL format' };
     }
     try {
+        /* Create a throwaway client scoped to this validation call. We
+           intentionally do NOT reuse the module-level singleton because the
+           credentials being tested may differ from the app's active config. */
         const tempClient = createClient(url, anonKey);
         // Test REST API reachability by attempting a simple query
         const { error } = await tempClient
@@ -30,7 +100,9 @@ export async function validateSupabaseCredentials(url, anonKey, testTable) {
                     error: 'Invalid Supabase credentials. Check your URL and Anon Key.'
                 };
             }
-            // Table doesn't exist but API is reachable — credentials work, schema not set up yet
+            /* Table doesn't exist but the API responded — this means the URL and
+               anon key are correct; the schema just hasn't been set up yet. We
+               treat this as a successful credential validation. */
             if (error.message?.includes('relation') && error.message?.includes('does not exist')) {
                 return { valid: true };
             }
@@ -44,13 +116,46 @@ export async function validateSupabaseCredentials(url, anonKey, testTable) {
         return { valid: false, error: `Could not connect to Supabase: ${message}` };
     }
 }
+// =============================================================================
+// SECTION: Schema Validation
+// =============================================================================
 /**
- * Validates that all configured Supabase tables exist and are accessible.
+ * Validate that all tables declared in the engine configuration exist in
+ * Supabase and are accessible under the current RLS policies.
+ *
+ * For each table the function executes:
+ * ```sql
+ * SELECT id FROM <table> LIMIT 0
+ * ```
+ * This returns **zero rows** (no data egress, minimal latency) but still
+ * exercises the full PostgREST pipeline — table lookup, RLS policy
+ * evaluation, and column resolution. If any of these steps fail, the table
+ * is flagged.
+ *
+ * When device verification is enabled in the engine config, the
+ * `trusted_devices` table is automatically appended to the check list.
+ *
+ * Error categorization:
+ * - **Missing table**: The relation does not exist in the database.
+ * - **Permission denied (42501)**: The table exists but RLS or grants
+ *   prevent the anon role from reading it.
+ * - **Other**: Any unexpected PostgREST or network error.
+ *
+ * @returns An object containing:
+ *   - `valid` — `true` when all tables pass, `false` otherwise.
+ *   - `missingTables` — names of tables that do not exist at all.
+ *   - `errors` — human-readable descriptions of every issue found.
  *
- * Fires `SELECT id FROM <table> LIMIT 0` per table — returns zero rows (no data egress)
- * but validates the table exists and RLS allows access.
+ * @example
+ * ```ts
+ * const { valid, missingTables, errors } = await validateSchema();
+ * if (!valid) {
+ *   console.error('Schema issues:', errors);
+ *   // Prompt user to run migrations or fix RLS policies
+ * }
+ * ```
  *
- * If device verification is enabled, also validates the `trusted_devices` table.
+ * @see {@link validateSupabaseCredentials} — for pre-setup credential checks
  */
 export async function validateSchema() {
     const config = getEngineConfig();
@@ -59,10 +164,14 @@ export async function validateSchema() {
     if (config.auth?.deviceVerification?.enabled) {
         tableNames.push('trusted_devices');
     }
+    /** Tables whose relation does not exist in the database at all. */
     const missingTables = [];
+    /** Human-readable error descriptions for all issues encountered. */
     const errors = [];
     for (const tableName of tableNames) {
         try {
+            /* SELECT id LIMIT 0 — validates table existence and RLS access
+               without fetching any actual data rows. */
             const { error } = await supabase.from(tableName).select('id').limit(0);
             if (error) {
                 if (error.message?.includes('relation') && error.message?.includes('does not exist')) {