spine-framework 0.3.125 → 0.3.127

package/.framework/functions/_shared/middleware.ts

@@ -1,189 +1,145 @@
-/**
- * @module middleware
- * @audience both
- * @layer shared-core
- * @stability stable
- *
- * HTTP handler factory and request context types for all Spine Netlify functions.
- * This module owns the boundary between raw HTTP events and the typed execution
- * context (`RequestContext`) used by every handler. It also provides guard
- * utilities (`requireUserContext`, `requireSystemContextWithAudit`) used to
- * enforce authentication at the top of handlers.
- *
- * The key invariant: `createHandler` always resolves a `Principal` via
- * `resolvePrincipal` before calling the inner handler. Handlers never receive
- * an unauthenticated context — anonymous requests are rejected at the wrapper.
- *
- * IMPORTANT: `result.data` is never unwrapped in `createHandler`. Handlers
- * return records directly. Unwrapping would collide with records that have a
- * `.data` JSONB column.
- *
- * @seeAlso principal.ts (resolvePrincipal, getPrincipalDb, isSystemAdmin)
- * @seeAlso audit.ts (emitAudit — called after every successful handler)
- * @seeAlso db.ts (adminDb, getUserDb — selected by getPrincipalDb)
- * @seeAlso index.ts (re-exports CoreContext, createHandler, requireUserContext)
- */
-
 import { 
   Principal, 
   resolvePrincipal, 
   isSystemAdmin, 
   getPrincipalDb
 } from './principal'
-import { emitAudit } from './audit'
-
-// ─── CONTEXT TYPES ───────────────────────────────────────────────────────────
-
-/**
- * Minimal execution context passed to all Spine core functions.
- *
- * This is the canonical context for `pipeline-runner`, `trigger-engine`,
- * `agent-runner`, `audit`, and any custom code in `v2-custom/`. It contains
- * only what core logic needs: identity, account scope, and a DB client.
- *
- * `RequestContext` (used inside HTTP handlers) extends this with HTTP-specific
- * fields (`appId`, `query`). Direct importers and CLI callers construct
- * `CoreContext` directly without going through `createHandler`.
- *
- * @inputSpec principal: Principal — must be a resolved principal (not null)
- * @inputSpec accountId: string | null — null is allowed for system-level ops only
- * @inputSpec db: SupabaseClient — use adminDb for system ops, getUserDb for RLS
- * @inputSpec requestId: string — UUID; ties execution to audit log entries
- * @calledBy pipeline-runner.ts, trigger-engine.ts, agent-runner.ts, audit.ts,
- *   tests/integration/helpers.ts (makeTestCtx), cli/context.ts
- *
- * @example Import usage (v2-custom/)
- * ```ts
- * import { CoreContext, adminDb, SYSTEM_PRINCIPAL } from '../_shared/index'
- * const ctx: CoreContext = {
- *   principal: SYSTEM_PRINCIPAL,
- *   accountId: 'uuid-of-account',
- *   db: adminDb,
- *   requestId: crypto.randomUUID()
- * }
- * await runPipeline(pipelineId, data, ctx)
- * ```
- *
- * @example CLI usage
- * ```bash
- * # CLI constructs CoreContext from .xenv credentials automatically
- * spine pipelines run <pipeline-id>
- * ```
- */
+import { adminDb } from './db'
+import { emitAudit, emitSpan } from './audit'
+import {
+  TraceContext,
+  Span,
+  startSpan,
+  endSpan,
+  parseTraceParent,
+  parseTraceState,
+  formatTraceParent,
+  formatTraceState,
+  generateSpanId,
+  isSampled,
+  traceDb
+} from './tracing'
+
+// CIL[BEGIN chunk_id="middleware_moduleheader_1784066609" type="module_header" identity="module_header" parent="none"]
+// CIL[DOC-MACRO purpose="Request middleware and context management"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide API request handling and authentication"]
+// CIL[DOC-CONTEXT module="_shared/middleware" layer="infrastructure" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="types and handlers" errors="none" side_effects="request processing"]
+// CIL[DOC-MICRO logic_summary="Defines CoreContext, RequestContext, HandlerFunction and HandlerResult types" 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: infrastructure. 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/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="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+
 export interface CoreContext {
-  /** Resolved principal for this execution */
   principal: Principal
-  /** Primary account scope — null for system-level operations */
   accountId: string | null
-  /** Database client — use adminDb for system ops, getUserDb for RLS-scoped */
   db: any
-  /** Unique ID for this execution (used in audit logs) */
   requestId: string
+  source?: string
+  logLevel?: string
+  trace?: TraceContext
 }
 
-/**
- * HTTP-layer execution context — extends `CoreContext` with request-specific fields.
- *
- * Constructed inside `createHandler` after principal resolution. Not used by
- * core logic directly — core functions accept `CoreContext`. The extra fields
- * are available to handlers that need them (e.g., `query.action`, `appId`).
- *
- * @inputSpec appId: string | null — from `x-app-id` header; null if absent
- * @inputSpec query: Record<string, string> — parsed queryStringParameters from event
- * @calledBy All 19 API handler functions (as the first argument)
- * @seeAlso CoreContext (parent interface)
- */
 export interface RequestContext extends CoreContext {
-  /** App ID from `x-app-id` header — used for app-scoped operations */
   appId: string | null
-  /** Parsed query string parameters from the Netlify event */
   query: Record<string, string>
-  /** Request path from the Netlify event */
   requestPath: string
 }
 
-/**
- * Signature for all Spine HTTP handler functions.
- *
- * Every handler file exports a default that calls `createHandler(myHandler)`.
- * The `body` parameter is the parsed JSON body, or null for GET requests.
- *
- * @inputSpec ctx: RequestContext — fully resolved context; never null
- * @inputSpec body: any — parsed JSON body or null; undefined for GET requests
- * @outputSpec Promise<any> — return value is wrapped in `{ data: result }` by createHandler
- */
 export type HandlerFunction = (ctx: RequestContext, body?: any) => Promise<any>
 
-/**
- * Standard envelope shape returned by `createHandler` to the HTTP client.
- *
- * On success: `{ data: <handler result>, error: null, meta: { requestId, duration } }`
- * On error: `{ data: null, error: <message> }` with appropriate HTTP status code.
- *
- * @outputSpec data: any — handler return value, never unwrapped
- * @outputSpec error: string | undefined — error message; present only on failure
- * @outputSpec meta: object | undefined — requestId + duration on success
- */
 export interface HandlerResult {
   data?: any
   error?: string
   meta?: any
 }
 
-// ─── HANDLER FACTORY ─────────────────────────────────────────────────────────
-
-/**
- * Wraps a handler function with principal resolution, request parsing, audit
- * logging, and error handling. This is the entry point for every Netlify function.
- *
- * Execution flow:
- *   1. Detect nested calls (event already has requestId + principal) → pass through
- *   2. Generate `requestId`, parse headers, query params
- *   3. Call `resolvePrincipal(event)` → reject anonymous with 401
- *   4. Call `getPrincipalDb(principal)` → select correct DB client
- *   5. Build `RequestContext`, parse + merge body
- *   6. Call inner handler, measure duration
- *   7. Emit `request.<method>` audit log (account-scoped requests only)
- *   8. Return `json({ data: result, error: null, meta })` envelope
- *   9. On any thrown error → return `error(message, 500)`
- *
- * @param handler - The inner handler function implementing the route logic
- * @returns Netlify-compatible async function `(event, context) => Response`
- * @throws never — all errors are caught and returned as HTTP 500
- * @inputSpec handler: HandlerFunction — must return a Promise
- * @outputSpec Netlify Lambda response object with statusCode, headers, body
- * @sideEffects DB read: principal resolution (people, api_keys tables)
- * @sideEffects DB write: emitAudit to logs table (account-scoped requests only)
- * @calledBy Every function in functions/*.ts as the default export wrapper
- * @calls resolvePrincipal, getPrincipalDb, emitAudit, json, error
- * @testIntegration tests/integration/admin-data-accounts.test.ts
- *
- * @example API handler file pattern
- * ```ts
- * import { createHandler, RequestContext } from './_shared/middleware'
- * export const handler = createHandler(async (ctx: RequestContext, body) => {
- *   const action = ctx.query.action || 'list'
- *   if (action === 'list') return listItems(ctx)
- *   throw new Error(`Unknown action: ${action}`)
- * })
- * ```
- */
+function isValidUuid(value: any): value is string {
+  if (typeof value !== 'string') return false
+  const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-9a-f][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+  return uuidRegex.test(value)
+}
+
+function buildTraceContext(event: any, requestId: string): TraceContext {
+  const traceparentHeader =
+    event.headers?.['traceparent'] ||
+    event.headers?.['Traceparent'] ||
+    event.headers?.['TRACEPARENT']
+  const tracestateHeader =
+    event.headers?.['tracestate'] ||
+    event.headers?.['Tracestate'] ||
+    event.headers?.['TRACESTATE']
+
+  const parsed = parseTraceParent(traceparentHeader)
+  if (parsed) {
+    const traceState = parseTraceState(tracestateHeader)
+    return {
+      traceId: parsed.traceId,
+      spanId: generateSpanId(),
+      parentSpanId: parsed.spanId,
+      traceFlags: parsed.traceFlags,
+      traceState: formatTraceState(traceState),
+      sampled: isSampled(parsed.traceFlags)
+    }
+  }
+
+  return {
+    traceId: requestId.replace(/-/g, '').toLowerCase(),
+    spanId: generateSpanId(),
+    traceFlags: 1,
+    sampled: true
+  }
+}
+
+function traceResponseHeaders(trace?: TraceContext, requestId?: string): Record<string, string> {
+  const headers: Record<string, string> = {}
+  if (requestId) headers['X-Request-ID'] = requestId
+  if (trace) headers['traceparent'] = formatTraceParent(trace.traceId, trace.spanId, trace.traceFlags)
+  if (trace?.traceState) headers['tracestate'] = trace.traceState
+  return headers
+}
+
+function mergeHeaders(base: Record<string, string>, extra?: Record<string, string>): Record<string, string> {
+  return { ...base, ...extra }
+}
+// CIL[END chunk_id="middleware_moduleheader_1784066609"]
+// CIL[BEGIN chunk_id="middleware_createhandler_1784066609" type="function" identity="createHandler" parent="none"]
+// CIL[DOC-MACRO purpose="Create authenticated request handler"]
+// CIL[DOC-RESPONSIBILITY responsibility="Wrap handlers with authentication and context"]
+// CIL[DOC-CONTEXT module="_shared/middleware" layer="infrastructure" related_files="[\".framework/functions/_shared/principal.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/components/ui/dialog.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="wrapped handler" errors="auth errors" side_effects="audit logging"]
+// CIL[DOC-MICRO logic_summary="Wraps handler with authentication, context building, and audit logging" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/principal.ts, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/src/components/ui/dialog.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export function createHandler(handler: HandlerFunction) {
   return async (event: any, context: any) => {
-    // Detect nested call: if event is already a RequestContext with a principal,
-    // skip event parsing and call the raw handler directly
     if (event && event.requestId && event.principal) {
       return handler(event, context)
     }
 
-    const requestId = crypto.randomUUID()
-    const startTime = Date.now()
-    
+    const rawRequestId = event.headers?.['x-request-id'] || event.headers?.['X-Request-Id']
+    const requestId = isValidUuid(rawRequestId) ? rawRequestId : crypto.randomUUID()
+    const traceContext = buildTraceContext(event, requestId)
+    const span = startSpan({ trace: traceContext }, 'request')
+    let principal: Principal | null = null
+
     try {
-      // Parse headers
       const appId = event.headers?.['x-app-id'] || event.headers?.['X-App-Id']
-      
-      // Parse query string parameters
+      const source = event.headers?.['x-source'] || event.headers?.['X-Source']
+      const logLevel = event.headers?.['x-log-level'] || event.headers?.['X-Log-Level']
+
       const queryParams: Record<string, string> = {}
       if (event.queryStringParameters) {
         Object.assign(queryParams, event.queryStringParameters)
@@ -192,16 +148,19 @@ export function createHandler(handler: HandlerFunction) {
         queryParams.method = event.httpMethod
       }
 
-      const principal = await resolvePrincipal(event)
-      
+      principal = await resolvePrincipal(event)
+
       if (!principal || principal.id === 'anonymous') {
-        return error('Authentication required', 401)
+        endSpan(span, { status: 'error', attributes: { error: 'Authentication required' } })
+        await emitSpan({ db: adminDb, principal: principal as any, accountId: null, requestId, trace: traceContext } as any, span, {
+          action: 'request.unauthenticated',
+          target: { type: 'request', id: requestId }
+        })
+        return error('Authentication required', 401, requestId, traceContext)
       }
-      
-      // Get RLS-scoped database client based on principal type
+
       const ctxDb = getPrincipalDb(principal)
-      
-      // Build request context
+
       const ctx: RequestContext = {
         requestId,
         principal,
@@ -210,15 +169,21 @@ export function createHandler(handler: HandlerFunction) {
         appId: appId || null,
         query: queryParams,
         requestPath: event.path || '/',
+        source,
+        logLevel,
+        trace: traceContext
       }
-      
-      // Parse body
+
+      ctx.db = traceDb(ctx, ctxDb, emitSpan)
+
       let body = null
       if (event.body) {
         try {
           body = JSON.parse(event.body)
         } catch (e) {
-          return error('Invalid JSON in request body', 400)
+          endSpan(span, { status: 'error', attributes: { error: 'Invalid JSON in request body' } })
+          await emitSpan(ctx, span, { action: 'request.parse_error', target: { type: 'request', id: requestId, account_id: ctx.accountId } })
+          return error('Invalid JSON in request body', 400, requestId, ctx.trace)
         }
       }
       if (ctx.query.id) {
@@ -229,75 +194,86 @@ export function createHandler(handler: HandlerFunction) {
           body.id = ctx.query.id
         }
       }
-      
-      // Capture request details for audit
+
       const httpMethod = event.httpMethod || queryParams.method || 'GET'
       const requestPath = event.path || '/'
-      
-      // Execute handler
+
       const result = await handler(ctx, body)
-      const durationMs = Date.now() - startTime
-      
-      // Emit audit log for successful request
-      if (ctx.accountId) {
-        await emitAudit(ctx, `request.${httpMethod.toLowerCase()}`, {
-          type: 'request',
-          id: requestId,
-          account_id: ctx.accountId
-        }, {
+      endSpan(span, { status: 'ok' })
+
+      await emitSpan(ctx, span, {
+        action: `request.${httpMethod.toLowerCase()}`,
+        target: { type: 'request', id: requestId, account_id: ctx.accountId },
+        metadata: {
           path: requestPath,
           method: httpMethod,
-          duration_ms: durationMs,
           principal_type: principal.type,
           principal_id: principal.id,
           app_id: ctx.appId
-        })
-      }
-      
-      // Return success response.
-      // Never unwrap result.data here — handlers return the record directly.
-      // Using result.data would collide with records that have a .data JSONB column.
+        }
+      })
+
       return json({
         data: result,
         error: null,
         meta: {
           requestId,
-          duration: durationMs
+          duration: span.durationMs
         }
-      })
-      
+      }, 200, requestId, ctx.trace)
+
     } catch (err: any) {
       console.error(`[${requestId}] Handler error:`, err)
       const status = typeof err.statusCode === 'number' ? err.statusCode : 500
-      return error(err.message || 'Internal server error', status)
+      endSpan(span, { status: 'error', attributes: { error: err.message || 'Internal server error' } })
+      const fallbackCtx: CoreContext = {
+        db: adminDb,
+        principal: principal || ({} as Principal),
+        accountId: principal?.accountId || null,
+        requestId,
+        trace: traceContext
+      }
+      await emitSpan(fallbackCtx, span, {
+        action: 'request.error',
+        target: { type: 'request', id: requestId, account_id: fallbackCtx.accountId },
+        metadata: { status, error: err.message || 'Internal server error' }
+      })
+      return error(err.message || 'Internal server error', status, requestId, traceContext)
     }
   }
 }
-
-// ─── PUBLIC HANDLER FACTORY ────────────────────────────────────────────────────
-
-/**
- * Wraps a handler function without requiring authentication.
- * Used for public endpoints like check-first-user, check-domain, validate-token.
- * 
- * Similar to createHandler but allows anonymous principals.
- */
+// CIL[END chunk_id="middleware_createhandler_1784066609"]
+// CIL[BEGIN chunk_id="middleware_createpublichandler_1784066609" type="function" identity="createPublicHandler" parent="none"]
+// CIL[DOC-MACRO purpose="Create public request handler"]
+// CIL[DOC-RESPONSIBILITY responsibility="Wrap handlers without authentication requirement"]
+// CIL[DOC-CONTEXT module="_shared/middleware" layer="infrastructure" related_files="[\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/components/ui/dialog.tsx\",\".framework/migrations/025_retype_threads_messages.sql\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="wrapped handler" errors="request errors" side_effects="context building"]
+// CIL[DOC-MICRO logic_summary="Wraps handler with context building but no authentication" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/TypeDetailPage.tsx, .framework/src/components/ui/dialog.tsx, .framework/migrations/025_retype_threads_messages.sql, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export function createPublicHandler(handler: HandlerFunction) {
   return async (event: any, context: any) => {
-    // Detect nested call: if event is already a RequestContext with a principal,
-    // skip event parsing and call the raw handler directly
     if (event && event.requestId && event.principal) {
       return handler(event, context)
     }
 
-    const requestId = crypto.randomUUID()
-    const startTime = Date.now()
-    
+    const rawRequestId = event.headers?.['x-request-id'] || event.headers?.['X-Request-Id']
+    const requestId = isValidUuid(rawRequestId) ? rawRequestId : crypto.randomUUID()
+    const traceContext = buildTraceContext(event, requestId)
+    const span = startSpan({ trace: traceContext }, 'request')
+    let principal: Principal | null = null
+
     try {
-      // Parse headers
       const appId = event.headers?.['x-app-id'] || event.headers?.['X-App-Id']
-      
-      // Parse query string parameters
+      const source = event.headers?.['x-source'] || event.headers?.['X-Source']
+      const logLevel = event.headers?.['x-log-level'] || event.headers?.['X-Log-Level']
+
       const queryParams: Record<string, string> = {}
       if (event.queryStringParameters) {
         Object.assign(queryParams, event.queryStringParameters)
@@ -306,14 +282,10 @@ export function createPublicHandler(handler: HandlerFunction) {
         queryParams.method = event.httpMethod
       }
 
-      // Resolve principal - may be anonymous for public endpoints
-      const principal = await resolvePrincipal(event)
-      
-      // Get RLS-scoped database client based on principal type
-      // For anonymous users, this returns adminDb (service role)
+      principal = await resolvePrincipal(event)
+
       const ctxDb = getPrincipalDb(principal)
-      
-      // Build request context
+
       const ctx: RequestContext = {
         requestId,
         principal,
@@ -322,15 +294,21 @@ export function createPublicHandler(handler: HandlerFunction) {
         appId: appId || null,
         query: queryParams,
         requestPath: event.path || '/',
+        source,
+        logLevel,
+        trace: traceContext
       }
-      
-      // Parse body
+
+      ctx.db = traceDb(ctx, ctxDb, emitSpan)
+
       let body = null
       if (event.body) {
         try {
           body = JSON.parse(event.body)
         } catch (e) {
-          return error('Invalid JSON in request body', 400)
+          endSpan(span, { status: 'error', attributes: { error: 'Invalid JSON in request body' } })
+          await emitSpan(ctx, span, { action: 'request.parse_error', target: { type: 'request', id: requestId, account_id: ctx.accountId } })
+          return error('Invalid JSON in request body', 400, requestId, ctx.trace)
         }
       }
       if (ctx.query.id) {
@@ -341,100 +319,122 @@ export function createPublicHandler(handler: HandlerFunction) {
           body.id = ctx.query.id
         }
       }
-      
-      // Execute handler
+
       const result = await handler(ctx, body)
-      const durationMs = Date.now() - startTime
-      
-      // Return success response
+      endSpan(span, { status: 'ok' })
+
+      await emitSpan(ctx, span, {
+        action: 'request.public',
+        target: { type: 'request', id: requestId, account_id: ctx.accountId },
+        metadata: {
+          path: event.path || '/',
+          method: event.httpMethod || 'GET',
+          principal_type: principal?.type,
+          principal_id: principal?.id,
+          app_id: ctx.appId
+        }
+      })
+
       return json({
         data: result,
         error: null,
         meta: {
           requestId,
-          duration: durationMs
+          duration: span.durationMs
         }
-      })
-      
+      }, 200, requestId, ctx.trace)
+
     } catch (err: any) {
       console.error(`[${requestId}] Public handler error:`, err)
       const status = typeof err.statusCode === 'number' ? err.statusCode : 500
-      return error(err.message || 'Internal server error', status)
+      endSpan(span, { status: 'error', attributes: { error: err.message || 'Internal server error' } })
+      const fallbackCtx: CoreContext = {
+        db: adminDb,
+        principal: principal || ({} as Principal),
+        accountId: principal?.accountId || null,
+        requestId,
+        trace: traceContext
+      }
+      await emitSpan(fallbackCtx, span, {
+        action: 'request.error',
+        target: { type: 'request', id: requestId, account_id: fallbackCtx.accountId },
+        metadata: { status, error: err.message || 'Internal server error' }
+      })
+      return error(err.message || 'Internal server error', status, requestId, traceContext)
     }
   }
 }
+// CIL[END chunk_id="middleware_createpublichandler_1784066609"]
+// CIL[BEGIN chunk_id="middleware_json_1784066609" type="function" identity="json" parent="none"]
+// CIL[DOC-MACRO purpose="Create JSON response"]
+// CIL[DOC-RESPONSIBILITY responsibility="Format API responses as JSON"]
+// CIL[DOC-CONTEXT module="_shared/middleware" layer="infrastructure" related_files="[\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/components/ui/dialog.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="HTTP response" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Creates HTTP response with JSON body and CORS 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: infrastructure. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/TypeDetailPage.tsx, .framework/src/components/ui/dialog.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+export function json(data: any, status: number = 200, requestId?: string, trace?: TraceContext) {
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+    'Access-Control-Allow-Origin': '*',
+    'Access-Control-Allow-Headers': 'Content-Type, Authorization, X-Account-Id, X-App-Id, X-Request-ID, X-Source, X-Log-Level, traceparent, tracestate',
+    'Access-Control-Allow-Methods': 'GET, POST, PATCH, DELETE, OPTIONS'
+  }
+
+  if (requestId) headers['X-Request-ID'] = requestId
+  if (trace) {
+    headers['traceparent'] = formatTraceParent(trace.traceId, trace.spanId, trace.traceFlags)
+    if (trace.traceState) headers['tracestate'] = trace.traceState
+  }
 
-// ─── RESPONSE HELPERS ────────────────────────────────────────────────────────
-
-/**
- * Builds a JSON HTTP response object compatible with Netlify Functions.
- *
- * Always includes CORS headers permitting requests from any origin. Used
- * internally by `createHandler` and directly by handlers that need a custom
- * status code (e.g., 201 Created).
- *
- * @param data - Any JSON-serializable value to include as the response body
- * @param status - HTTP status code (default: 200)
- * @returns Netlify Lambda response object
- * @throws never
- * @inputSpec data: any — must be JSON-serializable; circular refs will throw at stringify
- * @inputSpec status: number — valid HTTP status code (default 200)
- * @outputSpec { statusCode, headers, body: string } — body is JSON.stringify(data)
- * @sideEffects none
- * @calledBy createHandler, error, cors, and directly by some handlers
- * @testUnit none — trivial; verified by integration tests on every request
- */
-export function json(data: any, status: number = 200) {
   return {
     statusCode: status,
-    headers: {
-      'Content-Type': 'application/json',
-      'Access-Control-Allow-Origin': '*',
-      'Access-Control-Allow-Headers': 'Content-Type, Authorization, X-Account-Id, X-App-Id',
-      'Access-Control-Allow-Methods': 'GET, POST, PATCH, DELETE, OPTIONS'
-    },
+    headers,
     body: JSON.stringify(data)
   }
 }
-
-/**
- * Builds a JSON error response with `{ data: null, error: message }` shape.
- *
- * Use this to return structured error responses from handlers. The message
- * is safe to surface to clients — do not pass internal error details.
- *
- * @param message - Human-readable error message safe to return to client
- * @param status - HTTP status code (default: 400)
- * @returns Netlify Lambda response object
- * @throws never
- * @inputSpec message: string — client-safe error description
- * @inputSpec status: number — HTTP status code (400, 401, 403, 404, 500)
- * @outputSpec { statusCode: status, body: '{"data":null,"error":"<message>"}' }
- * @sideEffects none
- * @calledBy createHandler (on caught errors), requireUserContext,
- *   requireSystemContextWithAudit, and many individual handlers
- */
-export function error(message: string, status: number = 400) {
+// CIL[END chunk_id="middleware_json_1784066609"]
+// CIL[BEGIN chunk_id="middleware_error_1784066609" type="function" identity="error" parent="none"]
+// CIL[DOC-MACRO purpose="Create error response"]
+// CIL[DOC-RESPONSIBILITY responsibility="Format API error responses"]
+// CIL[DOC-CONTEXT module="_shared/middleware" layer="infrastructure" related_files="[\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/components/ui/dialog.tsx\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="HTTP error response" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Creates JSON error response with status code" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/TypeDetailPage.tsx, .framework/src/components/ui/dialog.tsx."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+export function error(message: string, status: number = 400, requestId?: string, trace?: TraceContext) {
   return json({
     data: null,
     error: message
-  }, status)
+  }, status, requestId, trace)
 }
-
-/**
- * Parses the JSON body from a Netlify event object.
- *
- * Returns `null` if there is no body. Throws a descriptive error on malformed
- * JSON so the error surfaces cleanly from `createHandler`'s catch block.
- *
- * @param event - Raw Netlify event object
- * @returns Parsed body object or null
- * @throws Error('Invalid JSON in request body') — when body is present but not valid JSON
- * @inputSpec event.body: string | null | undefined — raw JSON string from HTTP request
- * @outputSpec any — parsed JSON object, or null if no body
- * @sideEffects none
- * @calledBy Handlers that need body outside of createHandler's automatic parsing
- */
+// CIL[END chunk_id="middleware_error_1784066609"]
+// CIL[BEGIN chunk_id="middleware_parsebody_1784066609" type="function" identity="parseBody" parent="none"]
+// CIL[DOC-MACRO purpose="Parse request body JSON"]
+// CIL[DOC-RESPONSIBILITY responsibility="Extract and validate JSON from request"]
+// CIL[DOC-CONTEXT module="_shared/middleware" layer="infrastructure" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="parsed body" errors="invalid JSON" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Parses JSON body or throws error for invalid JSON" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export function parseBody(event: any): any {
   if (!event.body) return null
   
@@ -444,43 +444,21 @@ export function parseBody(event: any): any {
     throw new Error('Invalid JSON in request body')
   }
 }
-
-// ─── AUTH GUARDS ─────────────────────────────────────────────────────────────
-
-/**
- * Overloaded guard that requires a resolved human principal with an account scope.
- *
- * **Overload 1 — wrapper:** wrap a handler to enforce auth before it runs.
- * **Overload 2 — inline:** call with `ctx` directly; returns an error response
- *   object if auth is missing, or `null` if auth is present (allowing the
- *   caller to do `const authErr = requireUserContext(ctx); if (authErr) return authErr`).
- *
- * Rejects requests where:
- *   - `ctx.principal` is absent
- *   - `ctx.principal.id === 'anonymous'`
- *   - `ctx.accountId` is null or empty (machine principals without an account)
- *
- * @inputSpec ctx or handler: RequestContext or HandlerFunction
- * @outputSpec HandlerFunction (overload 1) or HandlerResult | null (overload 2)
- * @throws Error('User context required') — in wrapper mode if not authenticated
- * @sideEffects none
- * @calledBy API handlers that require an authenticated human with account scope
- * @testIntegration tests/integration/isolation.test.ts
- *
- * @example Inline guard pattern (preferred)
- * ```ts
- * const authErr = requireUserContext(ctx)
- * if (authErr) return authErr
- * // ctx.principal and ctx.accountId are guaranteed non-null below here
- * ```
- *
- * @example Wrapper pattern
- * ```ts
- * export const handler = createHandler(requireUserContext(async (ctx, body) => {
- *   return listItems(ctx)
- * }))
- * ```
- */
+// CIL[END chunk_id="middleware_parsebody_1784066609"]
+// CIL[BEGIN chunk_id="middleware_requireusercontext_1784066609" type="function" identity="requireUserContext" parent="none"]
+// CIL[DOC-MACRO purpose="Require authenticated user context"]
+// CIL[DOC-RESPONSIBILITY responsibility="Enforce user authentication and account"]
+// CIL[DOC-CONTEXT module="_shared/middleware" layer="infrastructure" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="wrapped handler or error" errors="auth errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Ensures principal is authenticated and has 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: infrastructure. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export function requireUserContext(handler: HandlerFunction): HandlerFunction
 export function requireUserContext(ctx: RequestContext): HandlerResult | null
 export function requireUserContext(arg: HandlerFunction | RequestContext): HandlerFunction | HandlerResult | null {
@@ -500,35 +478,21 @@ export function requireUserContext(arg: HandlerFunction | RequestContext): Handl
   }
   return null
 }
-
-/**
- * Overloaded guard that requires a `system_admin` principal.
- *
- * **Overload 1 — wrapper:** wrap a handler; throws if not system_admin.
- * **Overload 2 — inline:** call with `ctx`; returns error response or null.
- *   Also accepts an optional `triggeredBy` string to set on the context for
- *   audit trail chaining (e.g. pipeline execution ID).
- *
- * Rejects requests where:
- *   - `ctx.principal` is absent or anonymous
- *   - `ctx.principal` does not have the `system_admin` role
- *
- * @param arg - Handler to wrap, or RequestContext to validate inline
- * @param triggeredBy - Optional: ID of the triggering entity (set on ctx)
- * @returns HandlerFunction (overload 1) or HandlerResult | null (overload 2)
- * @throws Error('System context required') — in wrapper mode if not system_admin
- * @inputSpec ctx.principal.roles: string[] — must include 'system_admin'
- * @outputSpec HandlerFunction | HandlerResult | null
- * @sideEffects sets `ctx.triggeredBy` when validation passes (inline mode)
- * @calledBy system-cron.ts, pipeline-executions.ts, and admin-only handlers
- * @testIntegration tests/integration/isolation.test.ts
- *
- * @example Inline guard pattern
- * ```ts
- * const authErr = requireSystemContextWithAudit(ctx, 'cron-job-id')
- * if (authErr) return authErr
- * ```
- */
+// CIL[END chunk_id="middleware_requireusercontext_1784066609"]
+// CIL[BEGIN chunk_id="middleware_requiresystemcontextwithaudit_1784066609" type="function" identity="requireSystemContextWithAudit" parent="none"]
+// CIL[DOC-MACRO purpose="Require system admin context with audit"]
+// CIL[DOC-RESPONSIBILITY responsibility="Enforce system admin authentication"]
+// CIL[DOC-CONTEXT module="_shared/middleware" layer="infrastructure" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="wrapped handler or error" errors="auth errors" side_effects="audit tracking"]
+// CIL[DOC-MICRO logic_summary="Ensures principal is system admin and tracks triggeredBy" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export function requireSystemContextWithAudit(handler: HandlerFunction): HandlerFunction
 export function requireSystemContextWithAudit(ctx: RequestContext, triggeredBy?: string): HandlerResult | null
 export function requireSystemContextWithAudit(
@@ -559,22 +523,22 @@ export function requireSystemContextWithAudit(
   ;(ctx as any).triggeredBy = triggeredBy || ctx.principal.id
   return null
 }
-
-// ─── UTILITY ─────────────────────────────────────────────────────────────────
-
-/**
- * Returns a 200 JSON response for CORS preflight requests.
- *
- * Netlify automatically handles OPTIONS at the CDN level for most routes, but
- * handlers that need to explicitly handle OPTIONS can call this.
- *
- * @returns json({ message: 'CORS enabled' }, 200) with CORS headers
- * @throws never
- * @inputSpec none
- * @outputSpec Netlify Lambda response with CORS headers
- * @sideEffects none
- * @calledBy Handler files that explicitly handle OPTIONS method
- */
+// CIL[END chunk_id="middleware_requiresystemcontextwithaudit_1784066609"]
+// CIL[BEGIN chunk_id="middleware_cors_1784066609" type="function" identity="cors" parent="none"]
+// CIL[DOC-MACRO purpose="Handle CORS preflight requests"]
+// CIL[DOC-RESPONSIBILITY responsibility="Return CORS-enabled response"]
+// CIL[DOC-CONTEXT module="_shared/middleware" layer="infrastructure" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="CORS response" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Returns simple CORS response for preflight requests" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export function cors() {
   return json({ message: 'CORS enabled' }, 200)
 }
+// CIL[END chunk_id="middleware_cors_1784066609"]