spine-framework 0.3.145 → 0.4.1

package/.framework/functions/_shared/principal.ts

@@ -1,3 +1,14 @@
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/principal.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/functions/_shared/principal.ts"]
+// CIL[DOC-MACRO purpose="Shared principal and authorization module for Spine functions"]
+// CIL[DOC-RESPONSIBILITY responsibility="Defines the Principal model, resolves request principals from headers and tokens, and provides role/scope predicates"]
+// CIL[DOC-CONTEXT module="functions/_shared/principal" layer="shared" related_files=".framework/functions/_shared/db.ts"]
+// CIL[DOC-CONTRACT inputs="HTTP event headers and tokens" outputs="Principal objects and authorization booleans" errors="Invalid or inactive credentials, rate limit exceeded, lookup errors" side_effects="Writes API key usage logs; updates people.auth_uid when linking by email"]
+// CIL[DOC-MICRO logic_summary="Imports shared db/supabase clients and crypto; declares the Principal interface and anonymous/system constants; exports resolvers and helper functions" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="framework developers, ai agents, security reviewers"]
+
+
 
 
 
@@ -14,36 +25,26 @@
 
 
 
-// CIL[BEGIN chunk_id="principal_imports_1784020784" type="module_header" identity="imports" parent="none"]
-// CIL[DOC-MACRO purpose="Import database, auth client, and WebSocket dependencies"]
-// CIL[DOC-RESPONSIBILITY responsibility="Import required modules for principal resolution"]
-// CIL[DOC-CONTEXT module="principal" layer="shared" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/src/components/ui/dialog.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="database, auth client, WebSocket" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Import database connections, Supabase client, and WebSocket" 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: shared. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/RolesPage.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"]
 import { getUserDb, adminDb } from './db'
 import { createClient } from '@supabase/supabase-js'
 import WebSocket from 'ws'
-import { timingSafeEqual } from 'crypto'
-// CIL[END chunk_id="principal_imports_1784020784"]
-// CIL[BEGIN chunk_id="principal_internalsecret_1784020785" type="function" identity="isInternalInvokeAuthorized" parent="none"]
-// CIL[DOC-MACRO purpose="Gate internal-only principal headers behind a shared secret"]
-// CIL[DOC-RESPONSIBILITY responsibility="Prevent x-cron-id/x-trigger-id header spoofing on public endpoints"]
-// CIL[DOC-CONTEXT module="principal" layer="shared" related_files="[\".framework/functions/system-cron.ts\"]"]
-// CIL[DOC-CONTRACT inputs="event" outputs="boolean" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Compares x-internal-secret header against INTERNAL_INVOKE_SECRET env var using a timing-safe comparison; returns false (deny) if the secret is unset or missing/mismatched" notable_decisions="[\"Without this gate, any caller could set x-cron-id/x-trigger-id and impersonate the associated machine principal by guessing or reusing a leaked schedule/trigger id.\"]"]
-// CIL[DOC-CONFIDENCE pass="first" score="0.95" flags="none"]
+import { timingSafeEqual, createHash } from 'crypto'
+// CIL[DOC-VECTOR type="context" content="purpose='Shared principal and authorization module for Spine functions'; No verified external callers; imports: .framework/functions/_shared/db.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/functions/_shared/principal.ts:module_header:module_header"]
+
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/principal.ts:isInternalInvokeAuthorized:function" type="function" identity="isInternalInvokeAuthorized" parent="~/.framework/functions/_shared/principal.ts"]
+// CIL[DOC-MACRO purpose="Verify that a request carries the trusted internal invocation secret"]
+// CIL[DOC-RESPONSIBILITY responsibility="Validate shared secret header using timing-safe comparison"]
+// CIL[DOC-CONTEXT module="functions/_shared/principal" layer="shared" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/principal.ts"]
+// CIL[DOC-CONTRACT inputs="event object with headers" outputs="boolean" errors="none (returns false on any failure)" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Compare x-internal-secret against INTERNAL_INVOKE_SECRET using timingSafeEqual" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-AUDIENCE audience="developer"]
-// CIL[DOC-NOTE type="caution" content="INTERNAL_INVOKE_SECRET must be set wherever the framework itself issues x-cron-id/x-trigger-id headers (currently no code path does), or those callers will silently fall back to ANONYMOUS_PRINCIPAL."]
 function isInternalInvokeAuthorized(event: any): boolean {
   const expected = (globalThis as any).process?.env?.INTERNAL_INVOKE_SECRET
   if (!expected) return false
@@ -51,32 +52,56 @@ function isInternalInvokeAuthorized(event: any): boolean {
   const provided = event.headers?.['x-internal-secret'] || event.headers?.['X-Internal-Secret']
   if (!provided || typeof provided !== 'string') return false
 
-  const expectedBuf = Buffer.from(expected)
-  const providedBuf = Buffer.from(provided)
-  if (expectedBuf.length !== providedBuf.length) return false
+  // Hash both sides so the comparison always runs on equal-length (32-byte)
+  // inputs — an early-exit on length mismatch would leak the expected secret's
+  // length via response timing.
+  const expectedHash = createHash('sha256').update(expected).digest()
+  const providedHash = createHash('sha256').update(provided).digest()
 
   try {
-    return timingSafeEqual(expectedBuf, providedBuf)
+    return timingSafeEqual(expectedHash, providedHash)
   } catch {
     return false
   }
 }
-// CIL[END chunk_id="principal_internalsecret_1784020785"]
-// CIL[BEGIN chunk_id="principal_authclient_1784020784" type="variable" identity="supabase" parent="none"]
-// CIL[DOC-MACRO purpose="Create Supabase auth client for JWT validation"]
-// CIL[DOC-RESPONSIBILITY responsibility="Initialize auth client with environment configuration"]
-// CIL[DOC-CONTEXT module="principal" layer="shared" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/components/layout/Sidebar.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="supabase client" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Configures Supabase client with auth and realtime settings" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: shared. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/TypeDetailPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/components/layout/Sidebar.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='Verify that a request carries the trusted internal invocation secret'; No verified external callers; imports: .framework/functions/_shared/db.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/functions/_shared/principal.ts:isInternalInvokeAuthorized:function"]
+
+
+
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/principal.ts:env:constant" type="constant" identity="env" parent="~/.framework/functions/_shared/principal.ts"]
+// CIL[DOC-MACRO purpose="Access process environment variables"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide a safe fallback for environment lookups"]
+// CIL[DOC-CONTEXT module="functions/_shared/principal" layer="shared" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/principal.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Record of environment variables" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Return global process.env or an empty object" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 const env = (globalThis as any).process?.env || {}
+// CIL[DOC-VECTOR type="context" content="purpose='Access process environment variables'; No verified external callers; imports: .framework/functions/_shared/db.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/functions/_shared/principal.ts:env:constant"]
+
+
+
+
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/principal.ts:supabase:constant" type="constant" identity="supabase" parent="~/.framework/functions/_shared/principal.ts"]
+// CIL[DOC-MACRO purpose="Create a Supabase client configured for function use"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide an authenticated Supabase client with realtime transport"]
+// CIL[DOC-CONTEXT module="functions/_shared/principal" layer="shared" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/principal.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Supabase client" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Instantiate createClient with URL, anon key and auth/realtime options" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 const supabase = createClient(
   env.SUPABASE_URL || 'https://placeholder.supabase.co',
   env.SUPABASE_ANON_KEY || 'placeholder',
@@ -84,22 +109,26 @@ const supabase = createClient(
     auth: { autoRefreshToken: false, persistSession: false },
     realtime: { transport: WebSocket as any }
   }
+
+
 )
-// CIL[END chunk_id="principal_authclient_1784020784"]
-// CIL[BEGIN chunk_id="principal_interface_1784020784" type="interface" identity="Principal" parent="none"]
-// CIL[DOC-MACRO purpose="Define principal interface for authentication and authorization"]
-// CIL[DOC-RESPONSIBILITY responsibility="Provide comprehensive principal structure with provenance"]
-// CIL[DOC-CONTEXT module="principal" layer="shared" related_files="[\".framework/functions/_shared/schema-utils.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/components/layout/Sidebar.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="Principal interface" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Interface with identity, permissions, provenance, and auth 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: shared. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, custom/apps/portal/pages/ContentPage.tsx, .framework/src/components/layout/Sidebar.tsx, 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="context" content="purpose='Create a Supabase client configured for function use'; No verified external callers; imports: .framework/functions/_shared/db.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/functions/_shared/principal.ts:supabase:constant"]
+
+
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/principal.ts:Principal:interface" type="interface" identity="Principal" parent="~/.framework/functions/_shared/principal.ts"]
+// CIL[DOC-MACRO purpose="Define the canonical identity shape used across Spine"]
+// CIL[DOC-RESPONSIBILITY responsibility="Describe a principal's id, type, account, roles, scopes, machine metadata and provenance"]
+// CIL[DOC-CONTEXT module="functions/_shared/principal" layer="shared" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/principal.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="TypeScript interface" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Declare human or machine identity with provenance and optional auth context" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export interface Principal {
   id: string
   type: 'human' | 'machine'
@@ -123,26 +152,36 @@ export interface Principal {
     ipAddress?: string
     userAgent?: string
   }
+
+
+  // SECURITY: authContext carries raw credentials needed to build the
+  // user-scoped DB client (getPrincipalDb). It is transport-only — never pass
+  // a Principal to JSON.stringify, emitAudit, or any logging path. Use
+  // formatPrincipalForAudit() for serialized views. apiKey is deliberately
+  // absent: raw API keys are verified and discarded during resolution and must
+  // never be stored on objects that may be cached or serialized.
   authContext?: {
     jwt?: string
-    apiKey?: string
   }
 }
-// CIL[END chunk_id="principal_interface_1784020784"]
-// CIL[BEGIN chunk_id="principal_anonymous_1784020784" type="constant" identity="ANONYMOUS_PRINCIPAL" parent="none"]
-// CIL[DOC-MACRO purpose="Define anonymous principal for unauthenticated access"]
-// CIL[DOC-RESPONSIBILITY responsibility="Provide fallback principal when no authentication present"]
-// CIL[DOC-CONTEXT module="principal" layer="shared" related_files="[\".framework/src/components/layout/Sidebar.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="ANONYMOUS_PRINCIPAL constant" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Machine principal with no permissions and manual provenance" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: shared. Direct callers: 0. Direct calls: 0. Related files: .framework/src/components/layout/Sidebar.tsx, .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/src/pages/admin/IntegrationsPage.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='Define the canonical identity shape used across Spine'; No verified external callers; imports: .framework/functions/_shared/db.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/functions/_shared/principal.ts:Principal:interface"]
+
+
+
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/principal.ts:ANONYMOUS_PRINCIPAL:constant" type="constant" identity="ANONYMOUS_PRINCIPAL" parent="~/.framework/functions/_shared/principal.ts"]
+// CIL[DOC-MACRO purpose="Provide a default principal for unauthenticated requests"]
+// CIL[DOC-RESPONSIBILITY responsibility="Represent an anonymous machine principal with no scopes"]
+// CIL[DOC-CONTEXT module="functions/_shared/principal" layer="shared" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/principal.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Principal" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Return an anonymous machine principal with manual provenance" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const ANONYMOUS_PRINCIPAL: Principal = {
   id: 'anonymous',
   type: 'machine',
@@ -154,21 +193,27 @@ export const ANONYMOUS_PRINCIPAL: Principal = {
     invokedAt: new Date().toISOString()
   }
 }
-// CIL[END chunk_id="principal_anonymous_1784020784"]
-// CIL[BEGIN chunk_id="principal_system_1784020784" type="constant" identity="SYSTEM_PRINCIPAL" parent="none"]
-// CIL[DOC-MACRO purpose="Define system principal for internal operations"]
-// CIL[DOC-RESPONSIBILITY responsibility="Provide unrestricted internal principal for system tasks"]
-// CIL[DOC-CONTEXT module="principal" layer="shared" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/components/layout/Sidebar.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="SYSTEM_PRINCIPAL constant" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Internal machine principal with full permissions" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: shared. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/components/layout/Sidebar.tsx, .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/TypeDetailPage.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='Provide a default principal for unauthenticated requests'; No verified external callers; imports: .framework/functions/_shared/db.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/functions/_shared/principal.ts:ANONYMOUS_PRINCIPAL:constant"]
+
+
+
+
+
+
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/principal.ts:SYSTEM_PRINCIPAL:constant" type="constant" identity="SYSTEM_PRINCIPAL" parent="~/.framework/functions/_shared/principal.ts"]
+// CIL[DOC-MACRO purpose="Provide a privileged internal principal for system operations"]
+// CIL[DOC-RESPONSIBILITY responsibility="Represent the system machine principal with full scope"]
+// CIL[DOC-CONTEXT module="functions/_shared/principal" layer="shared" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/principal.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Principal" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Return a machine principal with wildcard scope and internal flag" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const SYSTEM_PRINCIPAL: Principal = {
   id: 'system',
   type: 'machine',
@@ -182,21 +227,26 @@ export const SYSTEM_PRINCIPAL: Principal = {
     invokedAt: new Date().toISOString()
   }
 }
-// CIL[END chunk_id="principal_system_1784020784"]
-// CIL[BEGIN chunk_id="principal_resolve_1784020784" type="function" identity="resolvePrincipal" parent="none"]
-// CIL[DOC-MACRO purpose="Resolve principal from event headers and authentication"]
-// CIL[DOC-RESPONSIBILITY responsibility="Determine caller identity from various auth methods"]
-// CIL[DOC-CONTEXT module="principal" layer="shared" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="Principal" errors="authentication failures" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Checks API key, then (only if isInternalInvokeAuthorized) cron/trigger, then JWT auth in priority order" notable_decisions="[\"cron/trigger headers require INTERNAL_INVOKE_SECRET to be honored, closing a header-spoofing auth bypass\"]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: shared. 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="Requires INTERNAL_INVOKE_SECRET env var for cron/trigger principal resolution."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='Provide a privileged internal principal for system operations'; No verified external callers; imports: .framework/functions/_shared/db.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/functions/_shared/principal.ts:SYSTEM_PRINCIPAL:constant"]
+
+
+
+
+
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/principal.ts:resolvePrincipal:function" type="function" identity="resolvePrincipal" parent="~/.framework/functions/_shared/principal.ts"]
+// CIL[DOC-MACRO purpose="Resolve a Principal from incoming request headers"]
+// CIL[DOC-RESPONSIBILITY responsibility="Dispatch to machine, cron, trigger or human resolution based on headers"]
+// CIL[DOC-CONTEXT module="functions/_shared/principal" layer="shared" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/principal.ts"]
+// CIL[DOC-CONTRACT inputs="event object with headers" outputs="Principal" errors="Invalid or inactive credentials" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Check x-api-key, internal cron/trigger headers, or Bearer token, falling back to ANONYMOUS_PRINCIPAL" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export async function resolvePrincipal(event: any): Promise<Principal> {
   const apiKey = event.headers?.['x-api-key'] || event.headers?.['X-Api-Key']
   if (apiKey) {
@@ -228,21 +278,22 @@ export async function resolvePrincipal(event: any): Promise<Principal> {
   
   return ANONYMOUS_PRINCIPAL
 }
-// CIL[END chunk_id="principal_resolve_1784020784"]
-// CIL[BEGIN chunk_id="principal_resolvemachine_1784020784" type="function" identity="resolveMachinePrincipal" parent="none"]
-// CIL[DOC-MACRO purpose="Resolve machine principal from API key"]
-// CIL[DOC-RESPONSIBILITY responsibility="Validate API key and return machine principal"]
-// CIL[DOC-CONTEXT module="principal" layer="shared" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="Principal" errors="invalid API key" side_effects="database query"]
-// CIL[DOC-MICRO logic_summary="Validates machine principal via RPC and builds principal object" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: shared. 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='Resolve a Principal from incoming request headers'; No verified external callers; imports: .framework/functions/_shared/db.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/functions/_shared/principal.ts:resolvePrincipal:function"]
+
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/principal.ts:resolveMachinePrincipal:function" type="function" identity="resolveMachinePrincipal" parent="~/.framework/functions/_shared/principal.ts"]
+// CIL[DOC-MACRO purpose="Resolve a machine principal from an API key"]
+// CIL[DOC-RESPONSIBILITY responsibility="Validate key prefix and hash, enforce rate limits, and return the principal"]
+// CIL[DOC-CONTEXT module="functions/_shared/principal" layer="shared" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/principal.ts"]
+// CIL[DOC-CONTRACT inputs="apiKey: string, event: any" outputs="Principal" errors="Invalid or inactive machine principal, rate limit exceeded" side_effects="Inserts api_key_usage_logs row"]
+// CIL[DOC-MICRO logic_summary="Query api_keys by prefix, verify hash, count recent usage, log request, and build the principal" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 async function resolveMachinePrincipal(apiKey: string, event: any): Promise<Principal> {
   const keyPrefix = apiKey.slice(0, 8)
 
@@ -251,14 +302,18 @@ async function resolveMachinePrincipal(apiKey: string, event: any): Promise<Prin
     .select('*')
     .eq('key_prefix', keyPrefix)
     .eq('is_active', true)
-    .or(`expires_at.is.null,expires_at.gte.${new Date().toISOString()}`)
-    .limit(1)
+    .order('created_at', { ascending: false })
+    .limit(10)
 
   if (error || !rows || rows.length === 0) {
     throw new Error('Invalid or inactive machine principal')
   }
 
-  const key = rows[0]
+  const now = Date.now()
+  const key = rows.find((k: any) => !k.expires_at || new Date(k.expires_at).getTime() >= now)
+  if (!key) {
+    throw new Error('Invalid or inactive machine principal')
+  }
   const { verifyApiKey } = await import('./hash-api-key')
   if (!verifyApiKey(apiKey, key.key_hash)) {
     throw new Error('Invalid or inactive machine principal')
@@ -278,6 +333,32 @@ async function resolveMachinePrincipal(apiKey: string, event: any): Promise<Prin
     throw new Error('Rate limit exceeded for this API key')
   }
 
+  // Secondary per-IP ceiling: the per-key limit alone cannot catch a caller
+  // rotating through many valid keys. rate_limit_hit (migration 035) is the
+  // atomic DB counter — key on the trusted client IP + endpoint so expensive
+  // endpoints can be tuned separately. Fail-open: a limiter outage must not
+  // take down machine authentication.
+  const clientIp = getClientIp(event)
+  if (clientIp) {
+    const ipWindowSeconds = 60
+    const ipLimit = Number(env.SPINE_IP_RATE_LIMIT || 300)
+    const ipWindowStart = new Date(
+      Math.floor(now / (ipWindowSeconds * 1000)) * ipWindowSeconds * 1000
+    ).toISOString()
+    try {
+      const { data: ipCount } = await adminDb.rpc('rate_limit_hit', {
+        p_key: `ip:${clientIp}:${event.path || '/'}`,
+        p_window_start: ipWindowStart,
+      })
+      if (typeof ipCount === 'number' && ipCount > ipLimit) {
+        throw new Error('Rate limit exceeded for this address')
+      }
+    } catch (err: any) {
+      if (err?.message === 'Rate limit exceeded for this address') throw err
+      console.warn('IP rate limit check failed (fail-open):', err?.message)
+    }
+  }
+
   await adminDb.from('api_key_usage_logs').insert({
     api_key_id: key.id,
     account_id: key.account_id,
@@ -289,11 +370,14 @@ async function resolveMachinePrincipal(apiKey: string, event: any): Promise<Prin
     metadata: { source: 'resolve_machine_principal' }
   })
 
+  const isGlobal = (key.scopes || []).includes('*:*')
+
   return {
     id: key.id,
     type: 'machine',
     accountId: key.account_id,
     scopes: key.scopes || [],
+    roles: isGlobal ? ['system_admin'] : [],
     machineType: (key.machine_type as any) || 'integration',
     isInternal: key.is_internal,
     provenance: {
@@ -303,27 +387,30 @@ async function resolveMachinePrincipal(apiKey: string, event: any): Promise<Prin
       apiKeyId: key.id,
       ipAddress: getClientIp(event),
       userAgent: event.headers?.['user-agent'] || event.headers?.['User-Agent']
-    },
-    authContext: { apiKey }
+    }
+    // The raw API key is intentionally NOT stored on the principal — the key is
+    // verified above and discarded. getPrincipalDb() returns adminDb for machine
+    // principals regardless, so no downstream consumer needs the credential.
   }
 }
+// CIL[DOC-VECTOR type="context" content="purpose='Resolve a machine principal from an API key'; No verified external callers; imports: .framework/functions/_shared/db.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/functions/_shared/principal.ts:resolveMachinePrincipal:function"]
+
 
 
-// CIL[END chunk_id="principal_resolvemachine_1784020784"]
-// CIL[BEGIN chunk_id="principal_resolvecron_1784020784" type="function" identity="resolveCronPrincipal" parent="none"]
-// CIL[DOC-MACRO purpose="Resolve machine principal for scheduled execution"]
-// CIL[DOC-RESPONSIBILITY responsibility="Validate schedule and return associated machine principal"]
-// CIL[DOC-CONTEXT module="principal" layer="shared" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="Principal" errors="invalid schedule" side_effects="database query"]
-// CIL[DOC-MICRO logic_summary="Validates schedule and creator, returns machine principal" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/principal.ts:resolveCronPrincipal:function" type="function" identity="resolveCronPrincipal" parent="~/.framework/functions/_shared/principal.ts"]
+// CIL[DOC-MACRO purpose="Resolve a machine principal for a cron schedule"]
+// CIL[DOC-RESPONSIBILITY responsibility="Lookup a schedule, validate its creator, and return its associated machine principal"]
+// CIL[DOC-CONTEXT module="functions/_shared/principal" layer="shared" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/principal.ts"]
+// CIL[DOC-CONTRACT inputs="scheduleId string" outputs="Principal" errors="Invalid or inactive schedule, validation failed" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Fetch schedule with machine join, call validate_schedule_creator RPC, and build principal with cron provenance" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: shared. 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"]
 async function resolveCronPrincipal(scheduleId: string): Promise<Principal> {
   const { data: schedule, error: scheduleError } = await adminDb
     .from('schedules')
@@ -363,21 +450,22 @@ async function resolveCronPrincipal(scheduleId: string): Promise<Principal> {
     }
   }
 }
-// CIL[END chunk_id="principal_resolvecron_1784020784"]
-// CIL[BEGIN chunk_id="principal_resolvetrigger_1784020784" type="function" identity="resolveTriggerPrincipal" parent="none"]
-// CIL[DOC-MACRO purpose="Resolve machine principal for trigger execution"]
-// CIL[DOC-RESPONSIBILITY responsibility="Validate trigger and return configured machine principal"]
-// CIL[DOC-CONTEXT module="principal" layer="shared" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="Principal" errors="invalid trigger" side_effects="database query"]
-// CIL[DOC-MICRO logic_summary="Validates trigger, finds action's machine principal, returns principal" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: shared. 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='Resolve a machine principal for a cron schedule'; No verified external callers; imports: .framework/functions/_shared/db.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/functions/_shared/principal.ts:resolveCronPrincipal:function"]
+
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/principal.ts:resolveTriggerPrincipal:function" type="function" identity="resolveTriggerPrincipal" parent="~/.framework/functions/_shared/principal.ts"]
+// CIL[DOC-MACRO purpose="Resolve a machine principal for a trigger invocation"]
+// CIL[DOC-RESPONSIBILITY responsibility="Load trigger, find its action's default machine, and return the principal"]
+// CIL[DOC-CONTEXT module="functions/_shared/principal" layer="shared" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/principal.ts"]
+// CIL[DOC-CONTRACT inputs="triggerId: string, event: any" outputs="Principal" errors="Invalid trigger, no machine configured" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Fetch trigger with action join, resolve default machine from api_keys, and build trigger provenance" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 async function resolveTriggerPrincipal(triggerId: string, event: any): Promise<Principal> {
   const { data: trigger, error: triggerError } = await adminDb
     .from('triggers')
@@ -423,22 +511,57 @@ async function resolveTriggerPrincipal(triggerId: string, event: any): Promise<P
     }
   }
 }
-// CIL[END chunk_id="principal_resolvetrigger_1784020784"]
-// CIL[BEGIN chunk_id="principal_resolvehuman_1784020784" type="function" identity="resolveHumanPrincipal" parent="none"]
-// CIL[DOC-MACRO purpose="Resolve human principal from JWT token"]
-// CIL[DOC-RESPONSIBILITY responsibility="Validate JWT and return human principal with roles"]
-// CIL[DOC-CONTEXT module="principal" layer="shared" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="Principal" errors="invalid token" side_effects="database query"]
-// CIL[DOC-MICRO logic_summary="Validates JWT, finds person record, builds principal with role" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: shared. 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='Resolve a machine principal for a trigger invocation'; No verified external callers; imports: .framework/functions/_shared/db.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/functions/_shared/principal.ts:resolveTriggerPrincipal:function"]
+
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/principal.ts:resolveHumanPrincipal:function" type="function" identity="resolveHumanPrincipal" parent="~/.framework/functions/_shared/principal.ts"]
+// CIL[DOC-MACRO purpose="Resolve a human principal from a JWT bearer token"]
+// CIL[DOC-RESPONSIBILITY responsibility="Validate Supabase user, map to internal person, and build the principal"]
+// CIL[DOC-CONTEXT module="functions/_shared/principal" layer="shared" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/principal.ts"]
+// CIL[DOC-CONTRACT inputs="token: string, event: any" outputs="Principal" errors="Person lookup error, person not found" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Get Supabase user, resolve internal person id, load person with role, and construct human principal; result cached ~60s keyed by token hash, provenance refreshed on hit; principals lacking both account_id and role_id are never cached" notable_decisions="cache avoids three sequential auth/people lookups on every polled request; provenance timestamps are refreshed per request so audit stays honest; unplaced (mid-registration, both fields null) principals skip the cache so placement lands on the next request instead of stalling 60s"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// Module-level cache: sha256(token) → resolved human principal. Resolution
+// costs 3 sequential round-trips (supabase.auth.getUser, person-id mapping,
+// people+role join) and runs on every request — polling-heavy clients were
+// paying ~1s of auth overhead per poll. 60s TTL bounds staleness for
+// role/account changes. The authContext.jwt in the cached entry is only ever
+// served back to the request that presented the same token. Principals for
+// people missing BOTH account_id and role_id (registration placement still
+// in flight) are never cached — see the comment at the cache write.
+//
+// SECURITY NOTE: role revocations, account deactivations, and account
+// reassignments take up to 60 seconds to propagate to in-flight requests on
+// warm function instances. This is a deliberate performance trade-off. Incident
+// response: a full function redeploy clears the in-memory cache immediately. A
+// DB-backed invalidation channel (e.g. a version counter on the people row)
+// would close the window but costs a round-trip per cached hit.
+const humanPrincipalCache = new Map<string, { principal: Principal; expiresAt: number }>()
+const PRINCIPAL_CACHE_TTL_MS = 60_000
+const PRINCIPAL_CACHE_MAX = 500
+
 async function resolveHumanPrincipal(token: string, event: any): Promise<Principal> {
+  const cacheKey = createHash('sha256').update(token).digest('hex')
+  const cached = humanPrincipalCache.get(cacheKey)
+  if (cached && cached.expiresAt > Date.now()) {
+    // Refresh request-scoped provenance so audit/log rows keep honest metadata
+    return {
+      ...cached.principal,
+      provenance: {
+        ...cached.principal.provenance,
+        invokedAt: new Date().toISOString(),
+        ipAddress: getClientIp(event),
+        userAgent: event.headers?.['user-agent'] || event.headers?.['User-Agent']
+      }
+    }
+  }
+
   const { data: { user }, error } = await supabase.auth.getUser(token)
   
   if (error || !user) {
@@ -464,7 +587,7 @@ async function resolveHumanPrincipal(token: string, event: any): Promise<Princip
   const role = Array.isArray(person.role) ? person.role[0] : person.role
   const roleSlugs = role?.slug ? [role.slug] : []
   
-  return {
+  const principal: Principal = {
     id: personId,
     type: 'human',
     accountId: person.account_id || null,
@@ -480,32 +603,70 @@ async function resolveHumanPrincipal(token: string, event: any): Promise<Princip
     },
     authContext: { jwt: token }
   }
+
+  // Never cache an unplaced principal. Between signUp (people row created)
+  // and complete_registration_placement (account_id + role_id stamped
+  // atomically), requests would otherwise pin accountId:null for the full
+  // TTL — the documented ~60s "Account context required" stall. Both-null
+  // is the exact signature of "placement hasn't run yet" — a contact with
+  // an account but no role is a valid steady state and still caches.
+  if (!person.account_id && !person.role_id) {
+    return principal
+  }
+
+  if (humanPrincipalCache.size >= PRINCIPAL_CACHE_MAX) {
+    for (const [key, entry] of humanPrincipalCache) {
+      if (entry.expiresAt <= Date.now()) humanPrincipalCache.delete(key)
+    }
+    if (humanPrincipalCache.size >= PRINCIPAL_CACHE_MAX) humanPrincipalCache.clear()
+  }
+  humanPrincipalCache.set(cacheKey, { principal, expiresAt: Date.now() + PRINCIPAL_CACHE_TTL_MS })
+
+  return principal
 }
-// CIL[END chunk_id="principal_resolvehuman_1784020784"]
-// CIL[BEGIN chunk_id="principal_resolveinternal_1784020784" type="function" identity="resolveInternalPersonId" parent="none"]
-// CIL[DOC-MACRO purpose="Resolve internal person ID from auth user ID and email"]
-// CIL[DOC-RESPONSIBILITY responsibility="Map external auth ID to internal person record"]
-// CIL[DOC-CONTEXT module="principal" layer="shared" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="internal person ID" errors="none" side_effects="database update"]
-// CIL[DOC-MICRO logic_summary="Looks up by email first, then auth ID, updates auth_uid if missing" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: shared. 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='Resolve a human principal from a JWT bearer token'; No verified external callers; imports: .framework/functions/_shared/db.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"]
-async function resolveInternalPersonId(authUserId: string, email?: string): Promise<string> {
+// CIL[END stable_id="~/.framework/functions/_shared/principal.ts:resolveHumanPrincipal:function"]
+
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/principal.ts:resolveInternalPersonId:function" type="function" identity="resolveInternalPersonId" parent="~/.framework/functions/_shared/principal.ts"]
+// CIL[DOC-MACRO purpose="Map a Supabase auth user to an internal person id"]
+// CIL[DOC-RESPONSIBILITY responsibility="Link auth user to person by email or auth_uid, falling back to the auth id"]
+// CIL[DOC-CONTEXT module="functions/_shared/principal" layer="shared" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/principal.ts"]
+// CIL[DOC-CONTRACT inputs="authUserId: string, email?: string" outputs="person id string" errors="none" side_effects="Updates people.auth_uid when linking by email"]
+// CIL[DOC-MICRO logic_summary="auth_uid lookup first (authoritative); email fallback only binds rows that are NOT invite stubs — invited/pending status or a stored invite_token is never claimed by email alone" notable_decisions="Invite stubs are claimed exclusively by the token-gated path in handle_new_auth_user (migration 052); binding one here by email would bypass token/expiry/revocation checks"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-NOTE type="security" content="Registration/invitation hardening: previously this bound auth_uid to ANY person row matching the JWT email with auth_uid NULL — including unclaimed invite stubs — bypassing the invite token entirely."]
+export async function resolveInternalPersonId(authUserId: string, email?: string): Promise<string> {
+  // auth_uid binding is authoritative — resolve it before any email fallback.
+  const { data: byAuthId } = await adminDb
+    .from('people')
+    .select('id')
+    .eq('auth_uid', authUserId)
+    .maybeSingle()
+
+  if (byAuthId) return byAuthId.id
+
   if (email) {
     const { data: byEmail } = await adminDb
       .from('people')
-      .select('id, auth_uid')
+      .select('id, auth_uid, status, data')
       .eq('email', email)
       .maybeSingle()
-    
+
     if (byEmail) {
       if (!byEmail.auth_uid) {
+        // Never claim an invite stub by email alone — only bind rows that
+        // are not invited/pending and carry no stored invite token.
+        const isInviteStub =
+          byEmail.status === 'invited' ||
+          byEmail.status === 'pending' ||
+          !!(byEmail.data && (byEmail.data as any).invite_token)
+        if (isInviteStub) return authUserId
         await adminDb
           .from('people')
           .update({ auth_uid: authUserId })
@@ -514,54 +675,54 @@ async function resolveInternalPersonId(authUserId: string, email?: string): Prom
       return byEmail.id
     }
   }
-  
-  const { data: byAuthId } = await adminDb
-    .from('people')
-    .select('id')
-    .eq('auth_uid', authUserId)
-    .maybeSingle()
-  
-  if (byAuthId) return byAuthId.id
-  
+
   return authUserId
 }
-// CIL[END chunk_id="principal_resolveinternal_1784020784"]
-// CIL[BEGIN chunk_id="principal_getclientip_1784020784" type="function" identity="getClientIp" parent="none"]
-// CIL[DOC-MACRO purpose="Extract client IP address from event headers"]
-// CIL[DOC-RESPONSIBILITY responsibility="Parse various IP header formats for provenance"]
-// CIL[DOC-CONTEXT module="principal" layer="shared" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="IP string or undefined" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Checks common IP headers in priority order" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: shared. 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='Map a Supabase auth user to an internal person id'; No verified external callers; imports: .framework/functions/_shared/db.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/functions/_shared/principal.ts:resolveInternalPersonId:function"]
+
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/principal.ts:getClientIp:function" type="function" identity="getClientIp" parent="~/.framework/functions/_shared/principal.ts"]
+// CIL[DOC-MACRO purpose="Extract the client IP from request headers or context"]
+// CIL[DOC-RESPONSIBILITY responsibility="Return the most likely originating IP for a request"]
+// CIL[DOC-CONTEXT module="functions/_shared/principal" layer="shared" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/principal.ts"]
+// CIL[DOC-CONTRACT inputs="event with headers and requestContext" outputs="ip string or undefined" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Prefer Netlify's x-nf-client-connection-ip (set by the edge, not client-controllable), then x-forwarded-for's first hop, x-real-ip, and requestContext.identity.sourceIp" notable_decisions="x-nf-client-connection-ip first because x-forwarded-for is client-spoofable and feeds rate limiting/provenance"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 function getClientIp(event: any): string | undefined {
-  return event.headers?.['x-forwarded-for'] ||
-         event.headers?.['X-Forwarded-For'] ||
+  // x-nf-client-connection-ip is set by Netlify's edge and cannot be spoofed by
+  // the client; x-forwarded-for's first hop is client-controllable, so it is a
+  // fallback only. Used for provenance AND IP rate limiting — spoofability
+  // would let a caller mint fresh buckets by rotating the header.
+  return event.headers?.['x-nf-client-connection-ip'] ||
+         event.headers?.['X-Nf-Client-Connection-Ip'] ||
+         (event.headers?.['x-forwarded-for'] || event.headers?.['X-Forwarded-For'] || '').split(',')[0].trim() ||
          event.headers?.['x-real-ip'] ||
          event.headers?.['X-Real-Ip'] ||
-         event.requestContext?.identity?.sourceIp
+         event.requestContext?.identity?.sourceIp ||
+         undefined
 }
-// CIL[END chunk_id="principal_getclientip_1784020784"]
-// CIL[BEGIN chunk_id="principal_machinescope_1784020784" type="function" identity="machineHasScope" parent="none"]
-// CIL[DOC-MACRO purpose="Check if machine principal has required scope"]
-// CIL[DOC-RESPONSIBILITY responsibility="Validate machine principal permissions"]
-// CIL[DOC-CONTEXT module="principal" layer="shared" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="boolean" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Checks exact scope, resource wildcard, or global wildcard" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: shared. 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='Extract the client IP from request headers or context'; No verified external callers; imports: .framework/functions/_shared/db.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/functions/_shared/principal.ts:getClientIp:function"]
+
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/principal.ts:machineHasScope:function" type="function" identity="machineHasScope" parent="~/.framework/functions/_shared/principal.ts"]
+// CIL[DOC-MACRO purpose="Check whether a machine principal holds a given scope"]
+// CIL[DOC-RESPONSIBILITY responsibility="Evaluate scope including resource wildcard and global wildcard matches"]
+// CIL[DOC-CONTEXT module="functions/_shared/principal" layer="shared" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/principal.ts"]
+// CIL[DOC-CONTRACT inputs="principal: Principal, scope: string" outputs="boolean" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Return true if scope, resource wildcard, or global wildcard is present" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export function machineHasScope(principal: Principal, scope: string): boolean {
   if (principal.type !== 'machine') return false
   
@@ -576,58 +737,61 @@ export function machineHasScope(principal: Principal, scope: string): boolean {
   
   return false
 }
-// CIL[END chunk_id="principal_machinescope_1784020784"]
-// CIL[BEGIN chunk_id="principal_humanrole_1784020784" type="function" identity="humanHasRole" parent="none"]
-// CIL[DOC-MACRO purpose="Check if human principal has required role"]
-// CIL[DOC-RESPONSIBILITY responsibility="Validate human principal role membership"]
-// CIL[DOC-CONTEXT module="principal" layer="shared" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="boolean" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Checks if principal type is human and role is in roles array" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: shared. 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='Check whether a machine principal holds a given scope'; No verified external callers; imports: .framework/functions/_shared/db.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/functions/_shared/principal.ts:machineHasScope:function"]
+
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/principal.ts:humanHasRole:function" type="function" identity="humanHasRole" parent="~/.framework/functions/_shared/principal.ts"]
+// CIL[DOC-MACRO purpose="Check whether a human principal has a role"]
+// CIL[DOC-RESPONSIBILITY responsibility="Test principal roles array for a role slug"]
+// CIL[DOC-CONTEXT module="functions/_shared/principal" layer="shared" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/principal.ts"]
+// CIL[DOC-CONTRACT inputs="principal: Principal, roleSlug: string" outputs="boolean" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Return true if principal is human and roles includes the slug" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export function humanHasRole(principal: Principal, roleSlug: string): boolean {
   if (principal.type !== 'human') return false
   return principal.roles?.includes(roleSlug) || false
 }
-// CIL[END chunk_id="principal_humanrole_1784020784"]
-// CIL[BEGIN chunk_id="principal_systemadmin_1784020784" type="function" identity="isSystemAdmin" parent="none"]
-// CIL[DOC-MACRO purpose="Check if principal is system administrator"]
-// CIL[DOC-RESPONSIBILITY responsibility="Validate system admin role for privileged operations"]
-// CIL[DOC-CONTEXT module="principal" layer="shared" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="boolean" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Checks if human principal has system_admin role" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: shared. 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='Check whether a human principal has a role'; No verified external callers; imports: .framework/functions/_shared/db.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/functions/_shared/principal.ts:humanHasRole:function"]
+
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/principal.ts:isSystemAdmin:function" type="function" identity="isSystemAdmin" parent="~/.framework/functions/_shared/principal.ts"]
+// CIL[DOC-MACRO purpose="Determine if a principal is a system administrator"]
+// CIL[DOC-RESPONSIBILITY responsibility="Check roles for system_admin by slug or object shape"]
+// CIL[DOC-CONTEXT module="functions/_shared/principal" layer="shared" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/principal.ts"]
+// CIL[DOC-CONTRACT inputs="principal" outputs="boolean" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Return true if roles contains system_admin as a string or slug property" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export function isSystemAdmin(principal: Principal): boolean {
-  return humanHasRole(principal, 'system_admin')
+  return principal?.roles?.some(r => r === 'system_admin' || r?.slug === 'system_admin') || false
 }
-// CIL[END chunk_id="principal_systemadmin_1784020784"]
-// CIL[BEGIN chunk_id="principal_getdb_1784020784" type="function" identity="getPrincipalDb" parent="none"]
-// CIL[DOC-MACRO purpose="Get appropriate database connection for principal"]
-// CIL[DOC-RESPONSIBILITY responsibility="Return user DB for humans, admin DB for machines"]
-// CIL[DOC-CONTEXT module="principal" layer="shared" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="database connection" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Returns user DB for authenticated humans, admin DB otherwise" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: shared. 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='Determine if a principal is a system administrator'; No verified external callers; imports: .framework/functions/_shared/db.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/functions/_shared/principal.ts:isSystemAdmin:function"]
+
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/principal.ts:getPrincipalDb:function" type="function" identity="getPrincipalDb" parent="~/.framework/functions/_shared/principal.ts"]
+// CIL[DOC-MACRO purpose="Select the appropriate database client for a principal"]
+// CIL[DOC-RESPONSIBILITY responsibility="Return user-scoped db for humans with JWT, otherwise admin db"]
+// CIL[DOC-CONTEXT module="functions/_shared/principal" layer="shared" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/principal.ts"]
+// CIL[DOC-CONTRACT inputs="principal" outputs="Supabase client" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Use getUserDb with JWT for humans, otherwise return adminDb" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export function getPrincipalDb(principal: Principal) {
   if (principal.type === 'human' && principal.authContext?.jwt) {
     return getUserDb(principal.authContext.jwt)
@@ -635,21 +799,24 @@ export function getPrincipalDb(principal: Principal) {
   
   return adminDb
 }
-// CIL[END chunk_id="principal_getdb_1784020784"]
-// CIL[BEGIN chunk_id="principal_audit_1784020784" type="function" identity="formatPrincipalForAudit" parent="none"]
-// CIL[DOC-MACRO purpose="Format principal for audit logging"]
-// CIL[DOC-RESPONSIBILITY responsibility="Create audit-safe representation of principal"]
-// CIL[DOC-CONTEXT module="principal" layer="shared" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="audit object" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Returns principal fields formatted for audit logs" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: shared. 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='Select the appropriate database client for a principal'; No verified external callers; imports: .framework/functions/_shared/db.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/functions/_shared/principal.ts:getPrincipalDb:function"]
+
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/principal.ts:formatPrincipalForAudit:function" type="function" identity="formatPrincipalForAudit" parent="~/.framework/functions/_shared/principal.ts"]
+// CIL[DOC-MACRO purpose="Serialize a principal for audit logs"]
+// CIL[DOC-RESPONSIBILITY responsibility="Produce a safe, structured view of principal identity and provenance"]
+// CIL[DOC-CONTEXT module="functions/_shared/principal" layer="shared" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/principal.ts"]
+// CIL[DOC-CONTRACT inputs="principal" outputs="audit object" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Return id, type, account_id, human/machine fields, and provenance spread" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// Deliberately omits authContext — it holds the raw credential (JWT) and must
+// never reach audit rows, log output, or any serialized payload.
 export function formatPrincipalForAudit(principal: Principal): object {
   return {
     id: principal.id,
@@ -667,4 +834,10 @@ export function formatPrincipalForAudit(principal: Principal): object {
     provenance: principal.provenance
   }
 }
-// CIL[END chunk_id="principal_audit_1784020784"]
+// CIL[DOC-VECTOR type="context" content="purpose='Serialize a principal for audit logs'; No verified external callers; imports: .framework/functions/_shared/db.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/functions/_shared/principal.ts:formatPrincipalForAudit:function"]