spine-framework 0.3.124 → 0.3.126

package/.framework/src/lib/api.ts

@@ -1,87 +1,147 @@
-/**
- * @module src/lib/api
- * @audience installer
- * @layer frontend-hook
- * @stability stable
- *
- * Authenticated fetch wrapper and account context for all Spine frontend
- * API calls. Injects the Supabase JWT and `X-Account-Id` header into every
- * request made via `apiFetch`.
- *
- * **Account context** is a module-level singleton set once after login:
- * ```ts
- * setAccountId(ctx.account_id) // called in AuthContext after auth.context()
- * ```
- * All subsequent `apiFetch` calls include `X-Account-Id` automatically.
- *
- * **401 interceptor:** Register a callback via `onUnauthorized(cb)` to be
- * notified when any non-auth API call returns 401. AuthContext uses this to
- * trigger logout when the session expires mid-use.
- *
- * INVARIANT: Call `setAccountId` before making any authenticated API requests.
- *   If `_accountId` is null, the backend may reject scoped requests.
- *
- * @seeAlso src/lib/supabase.ts (supabase client used for getSession)
- * @seeAlso src/hooks/useApi.ts (wraps apiFetch with React state management)
- * @seeAlso src/contexts/AuthContext.tsx (calls setAccountId after login)
- */
 
-import { supabase } from './supabase'
 
-// ─── ACCOUNT CONTEXT ─────────────────────────────────────────────────────────
 
-let _accountId: string | null = null
 
-/**
- * Sets the module-level account ID injected into all subsequent `apiFetch`
- * calls as `X-Account-Id`. Pass `null` to clear (e.g. on logout).
- *
- * @param id - UUID of the active account, or null to clear
- * @sideEffects Mutates module-level `_accountId`
- * @calledBy src/contexts/AuthContext.tsx (after successful login)
- */
+
+
+
+
+
+
+// CIL[BEGIN chunk_id="api_imports_1783716639" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import Supabase client for authentication"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide Supabase client dependency"]
+// CIL[DOC-CONTEXT module="api" layer="utility" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/schema-utils.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="supabase client" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Import statement for external dependency" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developer"]
+// CIL[DOC-VECTOR type="context" content="Layer: utility. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/principal.ts, .framework/functions/_shared/schema-utils.ts, custom/apps/portal/pages/ContentPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+import { supabase } from './supabase'
+// CIL[END chunk_id="api_imports_1783716639"]
+// CIL[BEGIN chunk_id="api__accountid_1783716639" type="variable" identity="_accountId" parent="none"]
+// CIL[DOC-MACRO purpose="Store current account context"]
+// CIL[DOC-RESPONSIBILITY responsibility="Maintain account ID state"]
+// CIL[DOC-CONTEXT module="api" layer="state" related_files="[\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="account ID storage" errors="none" side_effects="state_modification"]
+// CIL[DOC-MICRO logic_summary="Module-level variable for account context" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: state. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/RolesPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+let _accountId: string | null = null
+// CIL[END chunk_id="api__accountid_1783716639"]
+// CIL[BEGIN chunk_id="api_setaccountid_1783716639" type="function" identity="setAccountId" parent="none"]
+// CIL[DOC-MACRO purpose="Set current account context"]
+// CIL[DOC-RESPONSIBILITY responsibility="Update account ID state"]
+// CIL[DOC-CONTEXT module="api" layer="state" related_files="[\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="state_modification"]
+// CIL[DOC-MICRO logic_summary="Assign account ID to module variable" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: state. Direct callers: 1. Direct calls: 0. Related files: .framework/src/pages/admin/RolesPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 1. Total affected: 1."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export function setAccountId(id: string | null) {
   _accountId = id
 }
-
-/**
- * Returns the currently active account ID, or null if not set.
- *
- * @returns UUID string or null
- * @sideEffects none
- * @calledBy src/hooks/useApi.ts, any component needing the current account scope
- */
+// CIL[END chunk_id="api_setaccountid_1783716639"]
+// CIL[BEGIN chunk_id="api_getaccountid_1783716639" type="function" identity="getAccountId" parent="none"]
+// CIL[DOC-MACRO purpose="Get current account context"]
+// CIL[DOC-RESPONSIBILITY responsibility="Retrieve account ID state"]
+// CIL[DOC-CONTEXT module="api" layer="state" related_files="[\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="account_id: string|null" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Return account ID from module variable" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: state. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/RolesPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export function getAccountId(): string | null {
   return _accountId
 }
-
-// ─── 401 INTERCEPTOR ─────────────────────────────────────────────────────────
-
-/** Paths that are expected to return 401 (don't trigger the interceptor) */
-const AUTH_PATHS = ['/api/auth']
-
+// CIL[END chunk_id="api_getaccountid_1783716639"]
+// CIL[BEGIN chunk_id="api_authpaths_1783716639" type="variable" identity="AUTH_PATHS" parent="none"]
+// CIL[DOC-MACRO purpose="Define authentication API endpoints"]
+// CIL[DOC-RESPONSIBILITY responsibility="Maintain auth path configuration"]
+// CIL[DOC-CONTEXT module="api" layer="config" related_files="[\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/schema-utils.ts\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="auth paths array" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Constant array of auth endpoint paths" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: config. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/IntegrationsPage.tsx, .framework/functions/_shared/principal.ts, .framework/functions/_shared/schema-utils.ts, custom/apps/cortex/functions/custom_cil-embeddings.ts, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+const AUTH_PATHS = ['/api/auth', '/api/admin-data']
+// CIL[END chunk_id="api_authpaths_1783716639"]
+// CIL[BEGIN chunk_id="api__unauthorizedcallback_1783716639" type="variable" identity="_onUnauthorizedCallback" parent="none"]
+// CIL[DOC-MACRO purpose="Store unauthorized response handler"]
+// CIL[DOC-RESPONSIBILITY responsibility="Maintain callback state for 401 errors"]
+// CIL[DOC-CONTEXT module="api" layer="state" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="callback storage" errors="none" side_effects="state_modification"]
+// CIL[DOC-MICRO logic_summary="Module-level variable for unauthorized callback" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: state. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 let _onUnauthorizedCallback: (() => void) | null = null
-
-/**
- * Register a callback to be invoked when a non-auth API call returns 401.
- * Returns an unregister function. Only one callback may be active at a time.
- *
- * @param cb - Callback invoked once on 401
- * @returns Unregister function
- * @calledBy AuthContext (registers logout handler)
- */
+// CIL[END chunk_id="api__unauthorizedcallback_1783716639"]
+// CIL[BEGIN chunk_id="api_onunauthorized_1783716639" type="function" identity="onUnauthorized" parent="none"]
+// CIL[DOC-MACRO purpose="Register unauthorized response handler"]
+// CIL[DOC-RESPONSIBILITY responsibility="Manage 401 error callback lifecycle"]
+// CIL[DOC-CONTEXT module="api" layer="error_handling" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="cleanup: () => void" errors="none" side_effects="state_modification"]
+// CIL[DOC-MICRO logic_summary="Set callback and return cleanup function" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: error_handling. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export function onUnauthorized(cb: () => void): () => void {
   _onUnauthorizedCallback = cb
   return () => { _onUnauthorizedCallback = null }
 }
-
-// ─── INTERNAL HELPERS ─────────────────────────────────────────────────────────
-
-/**
- * Normalises any `HeadersInit` variant to a plain `Record<string, string>`
- * so headers can be safely spread and merged.
- * @throws never
- */
+// CIL[END chunk_id="api_onunauthorized_1783716639"]
+// CIL[BEGIN chunk_id="api_normalizeheaders_1783716639" type="function" identity="normalizeHeaders" parent="none"]
+// CIL[DOC-MACRO purpose="Convert headers to plain object format"]
+// CIL[DOC-RESPONSIBILITY responsibility="Normalize header data structures"]
+// CIL[DOC-CONTEXT module="api" layer="utility" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Record<string,string>" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Handle Headers, array, and object formats" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: utility. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 function normalizeHeaders(headers?: HeadersInit): Record<string, string> {
    if (!headers) return {}
 
@@ -97,27 +157,29 @@ function normalizeHeaders(headers?: HeadersInit): Record<string, string> {
      Object.entries(headers).map(([key, value]) => [key, String(value)])
    )
  }
-
-// ─── AUTH HEADERS ─────────────────────────────────────────────────────────────────
-
-/**
- * Builds the auth header map for a request: `Authorization: Bearer <jwt>`
- * and, if set, `X-Account-Id: <accountId>`.
- *
- * Called internally by `apiFetch` — do not call directly unless constructing
- * a manual `fetch` outside of `apiFetch`.
- *
- * @returns Plain header object; empty if no active session
- * @throws never — missing session returns empty headers, not an error
- * @sideEffects DB read: supabase.auth.getSession (reads localStorage)
- * @calledBy apiFetch
- */
+// CIL[END chunk_id="api_normalizeheaders_1783716639"]
+// CIL[BEGIN chunk_id="api_getauthheaders_1783716639" type="function" identity="getAuthHeaders" parent="none"]
+// CIL[DOC-MACRO purpose="Build authentication headers for API requests"]
+// CIL[DOC-RESPONSIBILITY responsibility="Generate auth and account context headers"]
+// CIL[DOC-CONTEXT module="api" layer="auth" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Record<string,string>" errors="supabase_errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Get session token and add account ID to headers" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: auth. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export async function getAuthHeaders(): Promise<Record<string, string>> {
   const headers: Record<string, string> = {}
 
   const { data: { session } } = await supabase.auth.getSession()
   if (session?.access_token) {
     headers['Authorization'] = `Bearer ${session.access_token}`
+  } else {
+    
   }
 
   if (_accountId) {
@@ -126,38 +188,43 @@ export async function getAuthHeaders(): Promise<Record<string, string>> {
 
   return headers
 }
+// CIL[END chunk_id="api_getauthheaders_1783716639"]
+// CIL[BEGIN chunk_id="api_apifetch_1783716639" type="function" identity="apiFetch" parent="none"]
+// CIL[DOC-MACRO purpose="Authenticated HTTP request wrapper"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle API requests with auth and error handling"]
+// CIL[DOC-CONTEXT module="api" layer="client" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Response" errors="network_errors" side_effects="callback_execution"]
+// CIL[DOC-MICRO logic_summary="Add auth headers, clean invalid tokens, handle 401s" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: client. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+let _sessionTraceId: string | null = null
+let _sessionTraceState: string = ''
+
+function generateHexId(length: number): string {
+  const uuid = crypto.randomUUID().replace(/-/g, '')
+  if (length > uuid.length) {
+    return (uuid + crypto.randomUUID().replace(/-/g, '')).slice(0, length).toLowerCase()
+  }
+  return uuid.slice(0, length).toLowerCase()
+}
+
+function getSessionTraceId(): string {
+  if (!_sessionTraceId) {
+    _sessionTraceId = generateHexId(32)
+  }
+  return _sessionTraceId
+}
+
+function buildTraceParent(): string {
+  return `00-${getSessionTraceId()}-${generateHexId(16)}-01`
+}
 
-// ─── FETCH WRAPPER ────────────────────────────────────────────────────────────────
-
-/**
- * Authenticated fetch wrapper. Injects `Authorization` + `X-Account-Id`
- * headers, strips invalid Bearer values (`null`/`undefined`/empty), and
- * forwards all other options (including `signal` for AbortController).
- *
- * If a non-auth endpoint returns 401, the registered `onUnauthorized`
- * callback fires (typically triggers logout).
- *
- * Use this for ALL Spine API calls from the frontend. Never call `fetch`
- * directly for API routes.
- *
- * @param path - API path, e.g. `'/.netlify/functions/items'`
- * @param options - Standard `RequestInit` options (method, body, signal, etc.)
- * @returns Raw `Response` — callers must check `response.ok` / status
- * @throws Network errors from `fetch` (e.g. `TypeError: Failed to fetch`)
- * @inputSpec path: string — relative URL to a Netlify function
- * @inputSpec options.signal: AbortSignal | undefined — forwarded for cancellation
- * @outputSpec Response — with auth headers injected; not yet parsed
- * @sideEffects Network request; reads localStorage via getAuthHeaders;
- *   may trigger onUnauthorized callback on 401
- * @calledBy src/hooks/useApi.ts, useEntityList.ts, useEntityRecord.ts
- *
- * @example
- * ```ts
- * const res = await apiFetch('/.netlify/functions/items?action=list')
- * if (!res.ok) throw new Error(await res.text())
- * const { data } = await res.json()
- * ```
- */
 export async function apiFetch(path: string, options: RequestInit = {}): Promise<Response> {
   const authHeaders = await getAuthHeaders()
   const optionHeaders = normalizeHeaders(options.headers)
@@ -171,17 +238,28 @@ export async function apiFetch(path: string, options: RequestInit = {}): Promise
     delete optionHeaders.authorization
   }
 
+  const traceparent = buildTraceParent()
+
   const fetchOptions = {
     ...options,
     headers: {
       ...authHeaders,
       ...optionHeaders,
+      traceparent,
     },
   }
 
   const response = await fetch(path, fetchOptions)
 
-  // 401 on a non-auth endpoint means the session has expired
+  const requestId = response.headers.get('X-Request-ID') || response.headers.get('x-request-id')
+  const responseTraceparent = response.headers.get('traceparent') || response.headers.get('Traceparent')
+  if (requestId) {
+    console.log('[Spine] requestId:', requestId, 'traceparent:', responseTraceparent || traceparent)
+  }
+
+  const responseTracestate = response.headers.get('tracestate') || response.headers.get('Tracestate')
+  if (responseTracestate) _sessionTraceState = responseTracestate
+
   if (response.status === 401 && _onUnauthorizedCallback) {
     const isAuthPath = AUTH_PATHS.some(p => path.startsWith(p))
     if (!isAuthPath) {
@@ -191,3 +269,4 @@ export async function apiFetch(path: string, options: RequestInit = {}): Promise
 
   return response
 }
+// CIL[END chunk_id="api_apifetch_1783716639"]

package/.framework/src/lib/supabase.ts

@@ -1,94 +1,128 @@
-/**
- * @module src/lib/supabase
- * @audience installer
- * @layer frontend-hook
- * @stability stable
- *
- * Browser-side Supabase client singleton and session helpers for the Spine
- * frontend. Reads `VITE_SUPABASE_URL` and `VITE_SUPABASE_ANON_KEY` from
- * Vite env at build time; throws immediately on missing values so
- * misconfigured builds fail loudly rather than silently.
- *
- * INVARIANT: `supabase` is a module-level singleton — do not call
- *   `createClient` again in components or hooks. Import this module instead.
- *
- * @seeAlso src/lib/api.ts (uses supabase.auth.getSession for apiFetch headers)
- * @seeAlso src/contexts/AuthContext.tsx (wraps supabase.auth for React state)
- */
 
-import { createClient } from '@supabase/supabase-js'
 
+
+
+
+
+// CIL[BEGIN chunk_id="supabase_module_header_1783672456" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import Supabase client"]
+// CIL[DOC-RESPONSIBILITY responsibility="Import Supabase client factory"]
+// CIL[DOC-CONTEXT module="supabase" layer="frontend-hook" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="createClient function" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports Supabase client creation function" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developer"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-hook. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/pages/operations/OperationsDashboard.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+import { createClient } from '@supabase/supabase-js'
+// CIL[END chunk_id="supabase_module_header_1783672456"]
+// CIL[BEGIN chunk_id="supabase_envvars_1783672456" type="variable" identity="environmentVariables" parent="none"]
+// CIL[DOC-MACRO purpose="Load Supabase environment variables"]
+// CIL[DOC-RESPONSIBILITY responsibility="Validate and store Supabase config"]
+// CIL[DOC-CONTEXT module="supabase" layer="frontend-hook" related_files="[\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Environment variables" errors="Error on missing vars" side_effects="May throw error"]
+// CIL[DOC-MICRO logic_summary="Loads and validates required Supabase env vars" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-hook. Direct callers: 0. Direct calls: 0. Related files: \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 const supabaseUrl = import.meta.env.VITE_SUPABASE_URL
 const supabaseAnonKey = import.meta.env.VITE_SUPABASE_ANON_KEY
 
 if (!supabaseUrl || !supabaseAnonKey) {
   throw new Error('Missing Supabase environment variables')
 }
-
-// ─── CLIENT SINGLETON ─────────────────────────────────────────────────────────
-
-/**
- * Browser-side Supabase client with persistent session, auto-refresh, and
- * URL-based session detection enabled. This is the only Supabase client
- * instance in the frontend; all auth and RLS-scoped queries flow through it.
- *
- * @inputSpec VITE_SUPABASE_URL: string — valid Supabase project URL
- * @inputSpec VITE_SUPABASE_ANON_KEY: string — anon (public) key
- * @throws Error('Missing Supabase environment variables') at module load if
- *   either env var is absent
- * @sideEffects Reads localStorage for persisted session on construction
- * @calledBy src/lib/api.ts (getAuthHeaders), src/contexts/AuthContext.tsx
- */
+// CIL[END chunk_id="supabase_envvars_1783672456"]
+// CIL[BEGIN chunk_id="supabase_client_1783672456" type="variable" identity="supabase" parent="none"]
+// CIL[DOC-MACRO purpose="Create Supabase client singleton"]
+// CIL[DOC-RESPONSIBILITY responsibility="Initialize Supabase client with auth config"]
+// CIL[DOC-CONTEXT module="supabase" layer="frontend-hook" related_files="[\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/components/ui/dialog.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Supabase client instance" errors="none" side_effects="Reads localStorage"]
+// CIL[DOC-MICRO logic_summary="Configures session persistence, auto-refresh, and a no-op auth lock to bypass navigator.locks" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-NOTE type="caution" content="No-op lock bypasses navigator.locks to avoid NavigatorLockAcquireTimeoutError during login"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-hook. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/TypeDetailPage.tsx, .framework/src/components/ui/dialog.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export const supabase = createClient(supabaseUrl, supabaseAnonKey, {
   auth: {
     persistSession: true,
     autoRefreshToken: true,
     detectSessionInUrl: true,
+    lock: async <T>(_name: string, _acquireTimeout: number, fn: () => Promise<T>): Promise<T> => await fn(),
   },
 })
-
-// ─── SESSION HELPERS ─────────────────────────────────────────────────────────
-
-/**
- * Returns the current Supabase auth session, or `null` if unauthenticated.
- *
- * @returns Session object or null
- * @throws Supabase AuthError on unexpected failure
- * @sideEffects none (read-only)
- * @calledBy AuthContext.tsx, login flows
- */
+// CIL[END chunk_id="supabase_client_1783672456"]
+// CIL[BEGIN chunk_id="supabase_getcurrentsession_1783672456" type="function" identity="getCurrentSession" parent="none"]
+// CIL[DOC-MACRO purpose="Get current Supabase session"]
+// CIL[DOC-RESPONSIBILITY responsibility="Retrieve active auth session"]
+// CIL[DOC-CONTEXT module="supabase" layer="frontend-hook" related_files="[\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Session object or null" errors="Supabase AuthError" side_effects="Reads localStorage"]
+// CIL[DOC-MICRO logic_summary="Calls Supabase getSession and handles errors" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-hook. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/RolesPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export const getCurrentSession = async () => {
   const { data: { session }, error } = await supabase.auth.getSession()
   if (error) throw error
   return session
 }
-
-/**
- * Returns the currently authenticated Supabase user, or `null` if not signed in.
- *
- * @returns User object or null
- * @throws Supabase AuthError on unexpected failure
- * @sideEffects none (read-only)
- * @calledBy AuthContext.tsx
- */
+// CIL[END chunk_id="supabase_getcurrentsession_1783672456"]
+// CIL[BEGIN chunk_id="supabase_getcurrentuser_1783672456" type="function" identity="getCurrentUser" parent="none"]
+// CIL[DOC-MACRO purpose="Get current Supabase user"]
+// CIL[DOC-RESPONSIBILITY responsibility="Retrieve authenticated user data"]
+// CIL[DOC-CONTEXT module="supabase" layer="frontend-hook" related_files="[\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="User object or null" errors="Supabase AuthError" side_effects="Reads localStorage"]
+// CIL[DOC-MICRO logic_summary="Calls Supabase getUser and handles errors" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-hook. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/RolesPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export const getCurrentUser = async () => {
   const { data: { user }, error } = await supabase.auth.getUser()
   if (error) throw error
   return user
 }
-
-/**
- * Forces a session token refresh. Call this when a request returns 401 due
- * to an expired JWT. Supabase auto-refresh normally handles this, but this
- * function is exposed for explicit refresh flows.
- *
- * @returns `{ session, user }` after refresh
- * @throws Supabase AuthError if refresh fails (e.g. refresh token expired)
- * @sideEffects Updates localStorage session via Supabase client
- * @calledBy AuthContext.tsx (manual token refresh)
- */
+// CIL[END chunk_id="supabase_getcurrentuser_1783672456"]
+// CIL[BEGIN chunk_id="supabase_refreshsession_1783672456" type="function" identity="refreshSession" parent="none"]
+// CIL[DOC-MACRO purpose="Refresh Supabase session"]
+// CIL[DOC-RESPONSIBILITY responsibility="Force session token refresh"]
+// CIL[DOC-CONTEXT module="supabase" layer="frontend-hook" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Session data" errors="Supabase AuthError" side_effects="Updates localStorage"]
+// CIL[DOC-MICRO logic_summary="Calls Supabase refreshSession and handles errors" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-hook. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export const refreshSession = async () => {
   const { data, error } = await supabase.auth.refreshSession()
   if (error) throw error
   return data
 }
+// CIL[END chunk_id="supabase_refreshsession_1783672456"]