spine-framework 0.3.144 → 0.4.0

package/.framework/functions/_shared/audit.ts

@@ -1,40 +1,36 @@
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/audit.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/functions/_shared/audit.ts"]
+// CIL[DOC-MACRO purpose="Module header for the shared audit logging utilities"]
+// CIL[DOC-RESPONSIBILITY responsibility="Declare module-level imports and establish the audit helper module boundary"]
+// CIL[DOC-CONTEXT module="audit" layer="functions/_shared" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/principal.ts,.framework/functions/_shared/tracing.ts"]
+// CIL[DOC-CONTRACT inputs="N/A" outputs="N/A" errors="N/A" side_effects="N/A"]
+// CIL[DOC-MICRO logic_summary="No executable logic; groups audit and tracing imports" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="contributor"]
+
 
 
 
-// CIL[BEGIN chunk_id="audit_moduleheader_1784068075" type="module_header" identity="module_header" parent="none"]
-// CIL[DOC-MACRO purpose="Audit logging system imports"]
-// CIL[DOC-RESPONSIBILITY responsibility="Import dependencies for audit functionality"]
-// CIL[DOC-CONTEXT module="_shared/audit" layer="infrastructure" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="imports" errors="none" side_effects="module imports"]
-// CIL[DOC-MICRO logic_summary="Imports CoreContext, database, and principal utilities" 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/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/RolesPage.tsx, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 import { CoreContext } from './middleware'
 import { adminDb } from './db'
 import { Principal, formatPrincipalForAudit } from './principal'
 import { Span, TraceContext } from './tracing'
-// CIL[END chunk_id="audit_moduleheader_1784068075"]
-// CIL[BEGIN chunk_id="audit_emitaudit_1784068075" type="function" identity="emitAudit" parent="none"]
-// CIL[DOC-MACRO purpose="Emit audit log entries"]
-// CIL[DOC-RESPONSIBILITY responsibility="Write structured audit logs to database"]
-// CIL[DOC-CONTEXT module="_shared/audit" layer="infrastructure" related_files="[\".framework/src/components/ui/dialog.tsx\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\".framework/migrations/015_simplify_apps_table.sql\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="Promise<void>" errors="database errors" side_effects="database writes"]
-// CIL[DOC-MICRO logic_summary="Inserts audit records with principal context and metadata" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="external_symbols_unknown"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: 0. Direct calls: 0. Related files: .framework/src/components/ui/dialog.tsx, custom/apps/cortex/functions/custom_cil-embeddings.ts, .framework/migrations/015_simplify_apps_table.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="context" content="purpose='Module header for the shared audit logging utilities'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/principal.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/audit.ts:module_header:module_header"]
+
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/audit.ts:traceFields:function" type="function" identity="traceFields" parent="~/.framework/functions/_shared/audit.ts"]
+// CIL[DOC-MACRO purpose="Extract OpenTelemetry trace fields from the request context for log enrichment"]
+// CIL[DOC-RESPONSIBILITY responsibility="Return a partial record of trace and span identifiers when a trace context is present"]
+// CIL[DOC-CONTEXT module="audit" layer="functions/_shared" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/principal.ts,.framework/functions/_shared/tracing.ts"]
+// CIL[DOC-CONTRACT inputs="ctx: CoreContext" outputs="Partial<Record<string, any>> with trace_id, span_id, parent_span_id, trace_flags, tracestate, sampled" errors="None" side_effects="None"]
+// CIL[DOC-MICRO logic_summary="Cast request context to access trace; if absent return empty object; otherwise copy trace fields" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 function traceFields(ctx: CoreContext): Partial<Record<string, any>> {
   const trace = (ctx as any).trace as TraceContext | undefined
   if (!trace) return {}
@@ -47,7 +43,23 @@ function traceFields(ctx: CoreContext): Partial<Record<string, any>> {
     sampled: trace.sampled
   }
 }
+// CIL[DOC-VECTOR type="context" content="purpose='Extract OpenTelemetry trace fields from the request context for log enrichment'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/principal.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/audit.ts:traceFields:function"]
+
 
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/audit.ts:emitAudit:function" type="function" identity="emitAudit" parent="~/.framework/functions/_shared/audit.ts"]
+// CIL[DOC-MACRO purpose="Write a structured audit event to the logs table"]
+// CIL[DOC-RESPONSIBILITY responsibility="Persist an audit record capturing the principal, target, outcome, and optional metadata"]
+// CIL[DOC-CONTEXT module="audit" layer="functions/_shared" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/principal.ts,.framework/functions/_shared/tracing.ts"]
+// CIL[DOC-CONTRACT inputs="ctx: CoreContext, action: string, target: {type,id?,account_id?}, metadata?: {changes?,result?,error?,...}" outputs="Promise<void>" errors="Log insertion failures are caught and written to stderr" side_effects="Inserts a row into the logs table"]
+// CIL[DOC-MICRO logic_summary="Determine log level from result; build message from principal; insert row with trace fields, target, and metadata; errors are swallowed" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export async function emitAudit(
   ctx: CoreContext,
   action: string,
@@ -92,7 +104,23 @@ export async function emitAudit(
     console.error('Failed to emit audit log:', err)
   }
 }
+// CIL[DOC-VECTOR type="context" content="purpose='Write a structured audit event to the logs table'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/principal.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/audit.ts:emitAudit:function"]
+
 
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/audit.ts:emitSpan:function" type="function" identity="emitSpan" parent="~/.framework/functions/_shared/audit.ts"]
+// CIL[DOC-MACRO purpose="Write a structured span completion log to the logs table"]
+// CIL[DOC-RESPONSIBILITY responsibility="Persist a span record including timing, status, and associated metadata"]
+// CIL[DOC-CONTEXT module="audit" layer="functions/_shared" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/principal.ts,.framework/functions/_shared/tracing.ts"]
+// CIL[DOC-CONTRACT inputs="ctx: CoreContext, span: Span, options?: {action?,target?,level?,kind?,event_category?,metadata?}" outputs="Promise<void>" errors="Log insertion failures are caught and written to stderr" side_effects="Inserts a row into the logs table"]
+// CIL[DOC-MICRO logic_summary="Compute level and outcome from span status; insert span details, attributes, and optional overrides; errors are swallowed" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export async function emitSpan(
   ctx: CoreContext,
   span: Span,
@@ -142,21 +170,22 @@ export async function emitSpan(
     console.error('Failed to emit span log:', err)
   }
 }
-// CIL[END chunk_id="audit_emitaudit_1784068075"]
-// CIL[BEGIN chunk_id="audit_emitlog_1784068075" type="function" identity="emitLog" parent="none"]
-// CIL[DOC-MACRO purpose="Emit general log entries"]
-// CIL[DOC-RESPONSIBILITY responsibility="Wrapper for audit logging with change tracking"]
-// CIL[DOC-CONTEXT module="_shared/audit" layer="infrastructure" related_files="[\".framework/src/components/ui/dialog.tsx\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\".framework/migrations/015_simplify_apps_table.sql\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="Promise<void>" errors="audit errors" side_effects="database writes"]
-// CIL[DOC-MICRO logic_summary="Delegates to emitAudit with structured change data" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="external_symbols_unknown"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: 0. Direct calls: 0. Related files: .framework/src/components/ui/dialog.tsx, custom/apps/cortex/functions/custom_cil-embeddings.ts, .framework/migrations/015_simplify_apps_table.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="context" content="purpose='Write a structured span completion log to the logs table'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/principal.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/audit.ts:emitSpan:function"]
+
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/audit.ts:emitLog:function" type="function" identity="emitLog" parent="~/.framework/functions/_shared/audit.ts"]
+// CIL[DOC-MACRO purpose="Emit a simplified audit log by delegating to emitAudit with optional target and changes"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide a convenient wrapper over emitAudit for generic log events"]
+// CIL[DOC-CONTEXT module="audit" layer="functions/_shared" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/principal.ts,.framework/functions/_shared/tracing.ts"]
+// CIL[DOC-CONTRACT inputs="ctx: CoreContext, eventType: string, target?: {type,id}, changes?: {before?,after?}, metadata?: Record<string,any>" outputs="Promise<void>" errors="Failures are caught and written to stderr" side_effects="Calls emitAudit; may insert a logs row"]
+// CIL[DOC-MICRO logic_summary="Build a target from provided values or fall back to the request account; forward to emitAudit with changes and metadata" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export async function emitLog(
   ctx: CoreContext,
   eventType: string,
@@ -177,21 +206,22 @@ export async function emitLog(
     console.error('Failed to emit log:', error)
   }
 }
-// CIL[END chunk_id="audit_emitlog_1784068075"]
-// CIL[BEGIN chunk_id="audit_emitactivity_1784068075" type="function" identity="emitActivity" parent="none"]
-// CIL[DOC-MACRO purpose="Emit activity log entries"]
-// CIL[DOC-RESPONSIBILITY responsibility="Log user activities with activity prefix"]
-// CIL[DOC-CONTEXT module="_shared/audit" layer="infrastructure" related_files="[\".framework/src/components/ui/dialog.tsx\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\".framework/migrations/015_simplify_apps_table.sql\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="Promise<void>" errors="log errors" side_effects="database writes"]
-// CIL[DOC-MICRO logic_summary="Wraps emitLog with activity. prefix for categorization" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="external_symbols_unknown"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: 0. Direct calls: 0. Related files: .framework/src/components/ui/dialog.tsx, custom/apps/cortex/functions/custom_cil-embeddings.ts, .framework/migrations/015_simplify_apps_table.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="context" content="purpose='Emit a simplified audit log by delegating to emitAudit with optional target and changes'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/principal.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/audit.ts:emitLog:function"]
+
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/audit.ts:emitActivity:function" type="function" identity="emitActivity" parent="~/.framework/functions/_shared/audit.ts"]
+// CIL[DOC-MACRO purpose="Emit an activity audit event with a namespaced type and arbitrary details"]
+// CIL[DOC-RESPONSIBILITY responsibility="Record a domain activity by delegating to emitLog"]
+// CIL[DOC-CONTEXT module="audit" layer="functions/_shared" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/principal.ts,.framework/functions/_shared/tracing.ts"]
+// CIL[DOC-CONTRACT inputs="ctx: CoreContext, type: string, details?: Record<string,any>" outputs="Promise<void>" errors="Failures from emitLog are propagated" side_effects="Calls emitLog; may insert a logs row"]
+// CIL[DOC-MICRO logic_summary="Prefix the provided type with 'activity.' and forward to emitLog with the details payload" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export async function emitActivity(
   ctx: CoreContext,
   type: string,
@@ -199,4 +229,10 @@ export async function emitActivity(
 ): Promise<void> {
   await emitLog(ctx, `activity.${type}`, undefined, undefined, details)
 }
-// CIL[END chunk_id="audit_emitactivity_1784068075"]
+// CIL[DOC-VECTOR type="context" content="purpose='Emit an activity audit event with a namespaced type and arbitrary details'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/principal.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/audit.ts:emitActivity:function"]