spine-framework 0.3.145 → 0.4.1

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

@@ -1,3 +1,12 @@
+// CIL[BEGIN stable_id="~/.framework/src/lib/api.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/src/lib/api.ts"]
+// CIL[DOC-MACRO purpose="API client for Spine: auth, account, and request tracing helpers."]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide authenticated fetch utilities and session tracing for the framework."]
+// CIL[DOC-CONTEXT module="framework-api" layer="lib" related_files=".framework/src/lib/supabase.ts"]
+// CIL[DOC-CONTRACT inputs="module imports" outputs="auth headers, account ID, trace IDs, wrapped fetch" errors="none" side_effects="registers unauthorized callback"]
+// CIL[DOC-MICRO logic_summary="Exports helpers for Supabase auth, account scoping, and W3C trace context propagation." notable_decisions="Uses crypto.randomUUID for hex IDs; propagates traceparent on every request."]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="framework consumers and app developers"]
 
 
 
@@ -8,140 +17,141 @@
 
 
 
-// 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="context" content="purpose='API client for Spine: auth, account, and request tracing helpers.'; No verified external callers; imports: .framework/src/lib/supabase.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // 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[END stable_id="~/.framework/src/lib/api.ts:module_header:module_header"]
+
+// CIL[BEGIN stable_id="~/.framework/src/lib/api.ts:_accountid:constant" type="constant" identity="_accountid" parent="~/.framework/src/lib/api.ts"]
+// CIL[DOC-MACRO purpose="Holds the currently selected account ID in memory."]
+// CIL[DOC-RESPONSIBILITY responsibility="Store mutable account ID state for authenticated requests."]
+// CIL[DOC-CONTEXT module="framework-api" layer="lib" related_files=".framework/src/lib/api.ts,.framework/src/lib/supabase.ts"]
+// CIL[DOC-CONTRACT inputs="set by setAccountId" outputs="read by getAuthHeaders and getAccountId" errors="none" side_effects="module-scoped mutable state"]
+// CIL[DOC-MICRO logic_summary="Module-level nullable string storing the active account ID." notable_decisions="Null default; no persistence."]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" 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."]
+let _accountId: string | null = null
+// CIL[DOC-VECTOR type="context" content="purpose='Holds the currently selected account ID in memory.'; No verified external callers; imports: .framework/src/lib/supabase.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/lib/api.ts:_accountid:constant"]
+
+
+// CIL[BEGIN stable_id="~/.framework/src/lib/api.ts:setAccountId:function" type="function" identity="setAccountId" parent="~/.framework/src/lib/api.ts"]
+// CIL[DOC-MACRO purpose="Set the active account ID for subsequent API calls."]
+// CIL[DOC-RESPONSIBILITY responsibility="Update the in-memory account ID variable."]
+// CIL[DOC-CONTEXT module="framework-api" layer="lib" related_files=".framework/src/lib/api.ts,.framework/src/lib/supabase.ts"]
+// CIL[DOC-CONTRACT inputs="id: string | null" outputs="void" errors="none" side_effects="mutates _accountId"]
+// CIL[DOC-MICRO logic_summary="Assigns the provided id to the _accountId module variable." notable_decisions="Accepts null to clear selection."]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export function setAccountId(id: string | null) {
   _accountId = id
 }
-// 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="context" content="purpose='Set the active account ID for subsequent API calls.'; No verified external callers; imports: .framework/src/lib/supabase.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/lib/api.ts:setAccountId:function"]
+
+// CIL[BEGIN stable_id="~/.framework/src/lib/api.ts:getAccountId:function" type="function" identity="getAccountId" parent="~/.framework/src/lib/api.ts"]
+// CIL[DOC-MACRO purpose="Return the currently selected account ID."]
+// CIL[DOC-RESPONSIBILITY responsibility="Expose the in-memory account ID value."]
+// CIL[DOC-CONTEXT module="framework-api" layer="lib" related_files=".framework/src/lib/api.ts,.framework/src/lib/supabase.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="string | null" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Returns the current _accountId value." notable_decisions="Simple getter."]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export function getAccountId(): string | null {
   return _accountId
 }
-// 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="context" content="purpose='Return the currently selected account ID.'; No verified external callers; imports: .framework/src/lib/supabase.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // 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[END stable_id="~/.framework/src/lib/api.ts:getAccountId:function"]
+
+
+// CIL[BEGIN stable_id="~/.framework/src/lib/api.ts:AUTH_PATHS:constant" type="constant" identity="AUTH_PATHS" parent="~/.framework/src/lib/api.ts"]
+// CIL[DOC-MACRO purpose="List of auth-related API paths used to suppress unauthorized callbacks."]
+// CIL[DOC-RESPONSIBILITY responsibility="Define paths that should not trigger the unauthorized callback on 401."]
+// CIL[DOC-CONTEXT module="framework-api" layer="lib" related_files=".framework/src/lib/api.ts,.framework/src/lib/supabase.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="readonly string array" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Constant array of auth/admin API path prefixes." notable_decisions="Frozen at module scope."]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" 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."]
+const AUTH_PATHS = ['/api/auth', '/api/admin-data']
+// CIL[DOC-VECTOR type="context" content="purpose='List of auth-related API paths used to suppress unauthorized callbacks.'; No verified external callers; imports: .framework/src/lib/supabase.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // 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
-// 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[END stable_id="~/.framework/src/lib/api.ts:AUTH_PATHS:constant"]
+
+
+
+
+// CIL[BEGIN stable_id="~/.framework/src/lib/api.ts:_onunauthorizedcallback:constant" type="constant" identity="_onunauthorizedcallback" parent="~/.framework/src/lib/api.ts"]
+// CIL[DOC-MACRO purpose="Holds the registered 401 callback for the app."]
+// CIL[DOC-RESPONSIBILITY responsibility="Store the callback invoked when a request returns 401."]
+// CIL[DOC-CONTEXT module="framework-api" layer="lib" related_files=".framework/src/lib/api.ts,.framework/src/lib/supabase.ts"]
+// CIL[DOC-CONTRACT inputs="set by onUnauthorized" outputs="invoked by apiFetch" errors="none" side_effects="module-scoped mutable state"]
+// CIL[DOC-MICRO logic_summary="Module-level nullable callback for unauthorized request handling." notable_decisions="Single callback only."]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" 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."]
+let _onUnauthorizedCallback: (() => void) | null = null
+// CIL[DOC-VECTOR type="context" content="purpose='Holds the registered 401 callback for the app.'; No verified external callers; imports: .framework/src/lib/supabase.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/lib/api.ts:_onunauthorizedcallback:constant"]
+
+
+
+// CIL[BEGIN stable_id="~/.framework/src/lib/api.ts:onUnauthorized:function" type="function" identity="onUnauthorized" parent="~/.framework/src/lib/api.ts"]
+// CIL[DOC-MACRO purpose="Register a callback to run when a 401 response is received."]
+// CIL[DOC-RESPONSIBILITY responsibility="Manage the unauthorized callback subscription and cleanup."]
+// CIL[DOC-CONTEXT module="framework-api" layer="lib" related_files=".framework/src/lib/api.ts,.framework/src/lib/supabase.ts"]
+// CIL[DOC-CONTRACT inputs="cb: () => void" outputs="unsubscribe function" errors="none" side_effects="sets _onUnauthorizedCallback"]
+// CIL[DOC-MICRO logic_summary="Assigns the provided callback and returns a cleanup function that clears it." notable_decisions="Only one callback can be registered at a time; cleanup returns callback to null."]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export function onUnauthorized(cb: () => void): () => void {
   _onUnauthorizedCallback = cb
   return () => { _onUnauthorizedCallback = null }
 }
-// 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="context" content="purpose='Register a callback to run when a 401 response is received.'; No verified external callers; imports: .framework/src/lib/supabase.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/lib/api.ts:onUnauthorized:function"]
+
+
+
+// CIL[BEGIN stable_id="~/.framework/src/lib/api.ts:normalizeHeaders:function" type="function" identity="normalizeHeaders" parent="~/.framework/src/lib/api.ts"]
+// CIL[DOC-MACRO purpose="Normalize HeadersInit into a flat Record<string, string>."]
+// CIL[DOC-RESPONSIBILITY responsibility="Convert various header input forms into a consistent object."]
+// CIL[DOC-CONTEXT module="framework-api" layer="lib" related_files=".framework/src/lib/api.ts,.framework/src/lib/supabase.ts"]
+// CIL[DOC-CONTRACT inputs="headers?: HeadersInit" outputs="Record<string, string>" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Handles undefined, Headers object, array of pairs, and plain object by coercing all values to strings." notable_decisions="Lowercases keys are preserved as-is; values are String(value)-coerced."]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 function normalizeHeaders(headers?: HeadersInit): Record<string, string> {
    if (!headers) return {}
 
@@ -157,21 +167,22 @@ function normalizeHeaders(headers?: HeadersInit): Record<string, string> {
      Object.entries(headers).map(([key, value]) => [key, String(value)])
    )
  }
-// 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="context" content="purpose='Normalize HeadersInit into a flat Record<string, string>.'; No verified external callers; imports: .framework/src/lib/supabase.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/lib/api.ts:normalizeHeaders:function"]
+
+// CIL[BEGIN stable_id="~/.framework/src/lib/api.ts:getAuthHeaders:function" type="function" identity="getAuthHeaders" parent="~/.framework/src/lib/api.ts"]
+// CIL[DOC-MACRO purpose="Build authorization headers from the current Supabase session and account."]
+// CIL[DOC-RESPONSIBILITY responsibility="Produce headers including bearer token and account ID when available."]
+// CIL[DOC-CONTEXT module="framework-api" layer="lib" related_files=".framework/src/lib/api.ts,.framework/src/lib/supabase.ts"]
+// CIL[DOC-CONTRACT inputs="none (uses supabase global and _accountId)" outputs="Promise<Record<string, string>>" errors="none" side_effects="calls supabase.auth.getSession()"]
+// CIL[DOC-MICRO logic_summary="Retrieves the Supabase session, adds Authorization bearer token if present, and adds X-Account-Id if _accountId is set." notable_decisions="Returns empty headers when no session or account."]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export async function getAuthHeaders(): Promise<Record<string, string>> {
   const headers: Record<string, string> = {}
 
@@ -188,43 +199,134 @@ 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="context" content="purpose='Build authorization headers from the current Supabase session and account.'; No verified external callers; imports: .framework/src/lib/supabase.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/lib/api.ts:getAuthHeaders:function"]
+
+
+
+// CIL[BEGIN stable_id="~/.framework/src/lib/api.ts:_sessionTraceId:constant" type="constant" identity="_sessionTraceId" parent="~/.framework/src/lib/api.ts"]
+// CIL[DOC-MACRO purpose="Caches the generated session trace ID for reuse."]
+// CIL[DOC-RESPONSIBILITY responsibility="Hold the lazy-initialized session-level trace identifier."]
+// CIL[DOC-CONTEXT module="framework-api" layer="lib" related_files=".framework/src/lib/api.ts,.framework/src/lib/supabase.ts"]
+// CIL[DOC-CONTRACT inputs="initialized by getSessionTraceId" outputs="read by getSessionTraceId" errors="none" side_effects="module-scoped mutable state"]
+// CIL[DOC-MICRO logic_summary="Nullable string caching the 32-character session trace ID." notable_decisions="Lazily initialized on first access."]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 let _sessionTraceId: string | null = null
+// CIL[DOC-VECTOR type="context" content="purpose='Caches the generated session trace ID for reuse.'; No verified external callers; imports: .framework/src/lib/supabase.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/lib/api.ts:_sessionTraceId:constant"]
+
+
+
+
+
+// CIL[BEGIN stable_id="~/.framework/src/lib/api.ts:_sessionTraceState:constant" type="constant" identity="_sessionTraceState" parent="~/.framework/src/lib/api.ts"]
+// CIL[DOC-MACRO purpose="Stores the last tracestate header received from a response."]
+// CIL[DOC-RESPONSIBILITY responsibility="Hold the latest server-provided tracestate value."]
+// CIL[DOC-CONTEXT module="framework-api" layer="lib" related_files=".framework/src/lib/api.ts,.framework/src/lib/supabase.ts"]
+// CIL[DOC-CONTRACT inputs="set by apiFetch on response" outputs="read by future apiFetch headers (not yet)" errors="none" side_effects="module-scoped mutable state"]
+// CIL[DOC-MICRO logic_summary="String cache for the most recent response tracestate header." notable_decisions="Currently written but not read back into outgoing headers."]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="experimental"]
 let _sessionTraceState: string = ''
+// CIL[DOC-VECTOR type="context" content="purpose='Stores the last tracestate header received from a response.'; No verified external callers; imports: .framework/src/lib/supabase.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/lib/api.ts:_sessionTraceState:constant"]
+
 
+
+
+// CIL[BEGIN stable_id="~/.framework/src/lib/api.ts:generateHexId:function" type="function" identity="generateHexId" parent="~/.framework/src/lib/api.ts"]
+// CIL[DOC-MACRO purpose="Generate a random lowercase hex string of the requested length."]
+// CIL[DOC-RESPONSIBILITY responsibility="Produce cryptographic random hex IDs for trace context."]
+// CIL[DOC-CONTEXT module="framework-api" layer="lib" related_files=".framework/src/lib/api.ts,.framework/src/lib/supabase.ts"]
+// CIL[DOC-CONTRACT inputs="length: number" outputs="string" errors="none" side_effects="none (but uses crypto)"]
+// CIL[DOC-MICRO logic_summary="Uses crypto.randomUUID, strips dashes, and concatenates or slices to the desired length." notable_decisions="Falls back to a second UUID if requested length exceeds 32."]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 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()
 }
+// CIL[DOC-VECTOR type="context" content="purpose='Generate a random lowercase hex string of the requested length.'; No verified external callers; imports: .framework/src/lib/supabase.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/lib/api.ts:generateHexId:function"]
 
+
+// CIL[BEGIN stable_id="~/.framework/src/lib/api.ts:getSessionTraceId:function" type="function" identity="getSessionTraceId" parent="~/.framework/src/lib/api.ts"]
+// CIL[DOC-MACRO purpose="Return the cached session trace ID, generating it on first call."]
+// CIL[DOC-RESPONSIBILITY responsibility="Lazy-initialize and reuse the 32-character session trace ID."]
+// CIL[DOC-CONTEXT module="framework-api" layer="lib" related_files=".framework/src/lib/api.ts,.framework/src/lib/supabase.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="string" errors="none" side_effects="may set _sessionTraceId"]
+// CIL[DOC-MICRO logic_summary="Checks _sessionTraceId and, if null, generates a 32-char hex ID and caches it." notable_decisions="Generates once per module session."]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 function getSessionTraceId(): string {
   if (!_sessionTraceId) {
     _sessionTraceId = generateHexId(32)
   }
   return _sessionTraceId
 }
+// CIL[DOC-VECTOR type="context" content="purpose='Return the cached session trace ID, generating it on first call.'; No verified external callers; imports: .framework/src/lib/supabase.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/lib/api.ts:getSessionTraceId:function"]
 
+
+// CIL[BEGIN stable_id="~/.framework/src/lib/api.ts:buildTraceParent:function" type="function" identity="buildTraceParent" parent="~/.framework/src/lib/api.ts"]
+// CIL[DOC-MACRO purpose="Build a W3C traceparent header value."]
+// CIL[DOC-RESPONSIBILITY responsibility="Compose a traceparent string from session and span IDs."]
+// CIL[DOC-CONTEXT module="framework-api" layer="lib" related_files=".framework/src/lib/api.ts,.framework/src/lib/supabase.ts"]
+// CIL[DOC-CONTRACT inputs="none (uses getSessionTraceId and generateHexId)" outputs="string" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Returns `00-{sessionTraceId}-{16-char span id}-01` in W3C traceparent format." notable_decisions="Fixed version 00 and sampled flag 01."]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 function buildTraceParent(): string {
   return `00-${getSessionTraceId()}-${generateHexId(16)}-01`
 }
+// CIL[DOC-VECTOR type="context" content="purpose='Build a W3C traceparent header value.'; No verified external callers; imports: .framework/src/lib/supabase.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/lib/api.ts:buildTraceParent:function"]
+
 
+// CIL[BEGIN stable_id="~/.framework/src/lib/api.ts:apiFetch:function" type="function" identity="apiFetch" parent="~/.framework/src/lib/api.ts"]
+// CIL[DOC-MACRO purpose="Make an authenticated HTTP request with traceparent and 401 handling."]
+// CIL[DOC-RESPONSIBILITY responsibility="Wrap fetch with auth headers, trace context, and unauthorized callback dispatch."]
+// CIL[DOC-CONTEXT module="framework-api" layer="lib" related_files=".framework/src/lib/api.ts,.framework/src/lib/supabase.ts"]
+// CIL[DOC-CONTRACT inputs="path: string, options: RequestInit = {}" outputs="Promise<Response>" errors="none explicit" side_effects="may invoke _onUnauthorizedCallback, mutates _sessionTraceState, logs request ID"]
+// CIL[DOC-MICRO logic_summary="Builds auth and trace headers, merges user headers, calls fetch, logs request/trace IDs, updates tracestate, and triggers the unauthorized callback for non-auth 401s." notable_decisions="Cleans up Bearer null/undefined/empty from user headers; suppresses callback for AUTH_PATHS."]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export async function apiFetch(path: string, options: RequestInit = {}): Promise<Response> {
   const authHeaders = await getAuthHeaders()
   const optionHeaders = normalizeHeaders(options.headers)
@@ -240,12 +342,21 @@ export async function apiFetch(path: string, options: RequestInit = {}): Promise
 
   const traceparent = buildTraceParent()
 
+  // Best-effort app hint for server-side app-scoped behavior (knowledge
+  // envelope, logging). Derived from the route prefix; the server validates
+  // the slug against installed apps and the principal's required_roles.
+  const appSegment = typeof window !== 'undefined'
+    ? (window.location.pathname.split('/')[1] || '')
+    : ''
+  const appHint = /^[a-z][a-z0-9-]*$/.test(appSegment) ? appSegment : null
+
   const fetchOptions = {
     ...options,
     headers: {
       ...authHeaders,
       ...optionHeaders,
       traceparent,
+      ...(appHint && !optionHeaders['x-app-id'] ? { 'x-app-id': appHint } : {}),
     },
   }
 
@@ -253,7 +364,14 @@ export async function apiFetch(path: string, options: RequestInit = {}): Promise
 
   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) {
+  // Debug-only: per-request tracing noise is opt-in — every apiFetch call
+  // logs otherwise, which floods the console during polling-heavy views.
+  // Enable with localStorage.spine_debug_api = '1'.
+  if (
+    requestId &&
+    typeof localStorage !== 'undefined' &&
+    localStorage.getItem('spine_debug_api') === '1'
+  ) {
     console.log('[Spine] requestId:', requestId, 'traceparent:', responseTraceparent || traceparent)
   }
 
@@ -269,4 +387,10 @@ export async function apiFetch(path: string, options: RequestInit = {}): Promise
 
   return response
 }
-// CIL[END chunk_id="api_apifetch_1783716639"]
+// CIL[DOC-VECTOR type="context" content="purpose='Make an authenticated HTTP request with traceparent and 401 handling.'; No verified external callers; imports: .framework/src/lib/supabase.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/lib/api.ts:apiFetch:function"]