spine-framework 0.3.124 → 0.3.126

package/.framework/functions/_shared/trigger-engine.ts

@@ -1,54 +1,46 @@
-/**
- * @module trigger-engine
- * @audience both
- * @layer shared-core
- * @stability stable
- *
- * Event-driven trigger dispatch system. API handlers call `fire*Triggers` after
- * a successful write to check whether any active triggers should fire. Matching
- * triggers cause `runPipeline` to be invoked with structured `triggerData`.
- *
- * Public surface:
- *   - `checkAndFireTriggers` — full trigger evaluation and firing loop
- *   - `fireCreateTriggers` — convenience wrapper for `*_created` events
- *   - `fireUpdateTriggers` — convenience wrapper for `*_updated` events
- *   - `fireDeleteTriggers` — convenience wrapper for `*_deleted` events
- *
- * Trigger condition evaluation (in order, all must pass):
- *   1. `config.entity_type` — exact match on entityType param
- *   2. `config.type_slug` — match on `entityData.type_slug` (items only)
- *   3. `config.filters` — field-level predicates with operators
- *      (`$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$exists`)
- *
- * INVARIANT: trigger evaluation and firing errors are caught per-trigger —
- *   a single failing trigger never prevents other triggers from firing.
- * INVARIANT: `checkAndFireTriggers` never throws — all errors are caught
- *   and logged. Callers do not need to wrap in try/catch.
- * INVARIANT: `adminDb` (service role) is used for trigger lookups and stats
- *   updates; `runPipeline` then uses the passed `ctx` for stage execution.
- *
- * @seeAlso pipeline-runner.ts (runPipeline — called when a trigger fires)
- * @seeAlso audit.ts (emitAudit for trigger.fired / trigger.failed)
- * @seeAlso index.ts (fire*Triggers re-exported for v2-custom/ and CLI)
- */
 
+
+
+
+
+
+
+
+
+// CIL[BEGIN chunk_id="triggerengine_imports_1784020784" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import dependencies for trigger engine functionality"]
+// CIL[DOC-RESPONSIBILITY responsibility="Import context, database, audit, and pipeline modules"]
+// CIL[DOC-CONTEXT module="trigger-engine" layer="shared" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/schema-utils.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="CoreContext, adminDb, emitAudit, runPipeline" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Import required modules for trigger processing and execution" 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/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/principal.ts, .framework/functions/_shared/schema-utils.ts, custom/apps/portal/pages/ContentPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 import { CoreContext } from './middleware'
 import { adminDb } from './db'
 import { emitAudit } from './audit'
 import { runPipeline } from './pipeline-runner'
-
-// ─── TYPES ───────────────────────────────────────────────────────────────
-
-/**
- * All entity lifecycle event types that triggers can subscribe to.
- *
- * Format: `<entity>_<lifecycle>` where entity is one of:
- * `item | account | person | thread | message | attachment | link`
- * and lifecycle is `created | updated | deleted`.
- *
- * @calledBy checkAndFireTriggers, fireCreateTriggers, fireUpdateTriggers,
- *   fireDeleteTriggers, all API handlers that write to these entity tables
- */
+// CIL[END chunk_id="triggerengine_imports_1784020784"]
+// CIL[BEGIN chunk_id="triggerengine_eventtype_1784020784" type="type" identity="EventType" parent="none"]
+// CIL[DOC-MACRO purpose="Define event types for trigger system"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide union type for all triggerable events"]
+// CIL[DOC-CONTEXT module="trigger-engine" layer="shared" related_files="[\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="EventType union" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Union of entity lifecycle events across different entity types" 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/principal.ts, .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/IntegrationsPage.tsx, .framework/src/pages/admin/TypeDetailPage.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="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export type EventType = 
   | 'item_created' | 'item_updated' | 'item_deleted'
   | 'account_created' | 'account_updated' | 'account_deleted'
@@ -57,16 +49,21 @@ export type EventType =
   | 'message_created' | 'message_updated' | 'message_deleted'
   | 'attachment_created' | 'attachment_updated' | 'attachment_deleted'
   | 'link_created' | 'link_updated' | 'link_deleted'
-
-/**
- * Trigger record shape as loaded from the `triggers` table.
- *
- * @inputSpec event_type: EventType string stored in triggers.event_type
- * @inputSpec pipeline_id: UUID — target pipeline to run when this trigger fires
- * @inputSpec config.filters: Record<string, any> — field-level predicates
- * @inputSpec config.entity_type: string | undefined — entity type filter
- * @inputSpec config.type_slug: string | undefined — item type slug filter
- */
+// CIL[END chunk_id="triggerengine_eventtype_1784020784"]
+// CIL[BEGIN chunk_id="triggerengine_triggerinterface_1784020784" type="interface" identity="Trigger" parent="none"]
+// CIL[DOC-MACRO purpose="Define trigger interface for event-driven automation"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide structure for trigger configuration and metadata"]
+// CIL[DOC-CONTEXT module="trigger-engine" layer="shared" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/functions/_shared/principal.ts\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Trigger interface" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Interface with trigger metadata, event type, pipeline, and config" 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/functions/_shared/principal.ts, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/IntegrationsPage.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"]
 interface Trigger {
   id: string
   name: string
@@ -79,56 +76,21 @@ interface Trigger {
   }
   is_active: boolean
 }
-
-// ─── PRIMARY EXPORT ────────────────────────────────────────────────────────────
-
-/**
- * Queries active triggers for `eventType`, evaluates each against the entity
- * data, and fires the associated pipeline for every matching trigger.
- *
- * Execution per trigger:
- *   1. `evaluateTriggerConditions` — all conditions must pass
- *   2. `runPipeline(trigger.pipeline_id, triggerData, ctx)` — fire pipeline
- *   3. Update `triggers.last_triggered` and increment `trigger_count` via RPC
- *   4. Emit `trigger.fired` audit log (or `trigger.failed` on error)
- *
- * `triggerData` passed to the pipeline:
- * ```json
- * {
- *   "event": "item_updated",
- *   "entity": { "type": "item", "id": "<uuid>", "data": {...} },
- *   "trigger": { "id": "<uuid>", "name": "My Trigger" },
- *   "fired_at": "2024-01-15T10:00:00.000Z"
- * }
- * ```
- *
- * @param eventType - The lifecycle event (e.g. 'item_updated')
- * @param entityType - The entity table name (e.g. 'item', 'person')
- * @param entityId - UUID of the entity that changed
- * @param entityData - Full record data for condition evaluation
- * @param ctx - CoreContext with requestId, accountId, and principal
- * @returns Promise<void> — always resolves; never throws
- * @throws never — all errors are caught per-trigger and logged
- * @inputSpec eventType: EventType — must be one of the 21 defined event types
- * @inputSpec entityId: string — UUID of the changed entity
- * @inputSpec entityData: any — full record (used for condition evaluation)
- * @outputSpec void
- * @sideEffects DB read: triggers table
- * @sideEffects DB write (per matching trigger): triggers.last_triggered, trigger_count
- * @sideEffects Calls runPipeline (per matching trigger) — which writes pipeline_executions
- * @sideEffects DB write: emitAudit (trigger.fired or trigger.failed per trigger)
- * @calledBy All API handlers after successful create/update/delete writes
- * @calledBy fireCreateTriggers, fireUpdateTriggers, fireDeleteTriggers
- * @calls evaluateTriggerConditions, runPipeline, emitAudit
- * @testUnit tests/unit/trigger-engine.test.ts
- * @testIntegration tests/integration/trigger-engine.test.ts
- *
- * @example
- * ```ts
- * // In an API handler after a successful item update:
- * await fireUpdateTriggers('item', updatedItem.id, updatedItem, ctx)
- * ```
- */
+// CIL[END chunk_id="triggerengine_triggerinterface_1784020784"]
+// CIL[BEGIN chunk_id="triggerengine_checkandfire_1784020784" type="function" identity="checkAndFireTriggers" parent="none"]
+// CIL[DOC-MACRO purpose="Check and fire triggers for entity events"]
+// CIL[DOC-RESPONSIBILITY responsibility="Query active triggers, evaluate conditions, execute pipelines"]
+// CIL[DOC-CONTEXT module="trigger-engine" layer="shared" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="void" errors="Database errors, pipeline failures" side_effects="Database updates, audit logs, pipeline execution"]
+// CIL[DOC-MICRO logic_summary="Fetch triggers, evaluate conditions, run pipelines, update trigger stats, emit audit events" 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/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/principal.ts, .framework/functions/_shared/schema-utils.ts, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export async function checkAndFireTriggers(
   eventType: EventType,
   entityType: string,
@@ -136,7 +98,6 @@ export async function checkAndFireTriggers(
   entityData: any,
   ctx: CoreContext
 ): Promise<void> {
-  // Find matching active triggers
   const { data: triggers, error } = await adminDb
     .from('triggers')
     .select('*')
@@ -153,7 +114,6 @@ export async function checkAndFireTriggers(
     return
   }
 
-  // Evaluate each trigger's conditions
   for (const trigger of triggers) {
     try {
       const shouldFire = evaluateTriggerConditions(trigger, entityType, entityData)
@@ -162,7 +122,6 @@ export async function checkAndFireTriggers(
         continue
       }
 
-      // Prepare trigger data for pipeline
       const triggerData = {
         event: eventType,
         entity: {
@@ -177,10 +136,8 @@ export async function checkAndFireTriggers(
         fired_at: new Date().toISOString()
       }
 
-      // Fire the pipeline
       const result = await runPipeline(trigger.pipeline_id, triggerData, ctx)
 
-      // Update trigger statistics
       await adminDb
         .from('triggers')
         .update({
@@ -216,28 +173,21 @@ export async function checkAndFireTriggers(
     }
   }
 }
-
-// ─── CONDITION EVALUATION ───────────────────────────────────────────────────────────
-
-/**
- * Returns true if all of a trigger's conditions match the entity event.
- *
- * Condition checks (in order):
- *   1. `config.entity_type` must equal `entityType` (if set)
- *   2. `config.type_slug` must equal `entityData.type_slug` (if set)
- *   3. Each `config.filters` key must match the entity field:
- *      - Array: value must be in the array
- *      - Object: `evaluateOperator` checks each `$op: expected` pair
- *      - Scalar: exact equality
- *
- * @param trigger - Trigger record with config
- * @param entityType - Entity table name from the calling handler
- * @param entityData - Full record data for field-level filter checks
- * @returns boolean — true if all conditions pass; false to skip this trigger
- * @throws never
- * @calledBy checkAndFireTriggers (per trigger in the matching set)
- * @calls getNestedValue, evaluateOperator
- */
+// CIL[END chunk_id="triggerengine_checkandfire_1784020784"]
+// CIL[BEGIN chunk_id="triggerengine_evaluatetriggerconditions_1784020784" type="function" identity="evaluateTriggerConditions" parent="none"]
+// CIL[DOC-MACRO purpose="Evaluate if trigger conditions match entity data"]
+// CIL[DOC-RESPONSIBILITY responsibility="Check entity type, type slug, and filter conditions"]
+// CIL[DOC-CONTEXT module="trigger-engine" layer="shared" related_files="[\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/migrations/025_retype_threads_messages.sql\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="boolean" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Validate trigger config against entity data using filters and operators" 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/pages/admin/IntegrationsPage.tsx, .framework/functions/_shared/schema-utils.ts, .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"]
 function evaluateTriggerConditions(
   trigger: Trigger,
   entityType: string,
@@ -245,33 +195,27 @@ function evaluateTriggerConditions(
 ): boolean {
   const config = trigger.config || {}
 
-  // Check entity type filter
   if (config.entity_type && config.entity_type !== entityType) {
     return false
   }
 
-  // Check type_slug filter (for items)
   if (config.type_slug && entityData?.type_slug !== config.type_slug) {
     return false
   }
 
-  // Check custom filters
   if (config.filters) {
     for (const [key, expectedValue] of Object.entries(config.filters)) {
       const actualValue = getNestedValue(entityData, key)
       
       if (Array.isArray(expectedValue)) {
-        // Array means "any of these values"
         if (!expectedValue.includes(actualValue)) {
           return false
         }
       } else if (typeof expectedValue === 'object' && expectedValue !== null) {
-        // Object means operators: { $gt: 5, $lt: 10 }
         if (!evaluateOperator(actualValue, expectedValue)) {
           return false
         }
       } else {
-        // Simple equality
         if (actualValue !== expectedValue) {
           return false
         }
@@ -281,35 +225,41 @@ function evaluateTriggerConditions(
 
   return true
 }
-
-/**
- * Extracts a value from a nested object using dot-notation path.
- *
- * @param obj - Source object
- * @param path - Dot-separated key path (e.g. 'data.status', 'type_slug')
- * @returns The value at the path, or `undefined` if any segment is missing
- * @throws never
- * @calledBy evaluateTriggerConditions (filter key resolution)
- */
+// CIL[END chunk_id="triggerengine_evaluatetriggerconditions_1784020784"]
+// CIL[BEGIN chunk_id="triggerengine_getnestedvalue_1784020784" type="function" identity="getNestedValue" parent="none"]
+// CIL[DOC-MACRO purpose="Get nested value from object using dot notation"]
+// CIL[DOC-RESPONSIBILITY responsibility="Navigate object hierarchy to retrieve nested property"]
+// CIL[DOC-CONTEXT module="trigger-engine" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="any" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Split path by dots and traverse object to get nested value" 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="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 function getNestedValue(obj: any, path: string): any {
   return path.split('.').reduce((current, key) => {
     return current?.[key]
   }, obj)
 }
-
-/**
- * Evaluates MongoDB-style operator conditions against an actual value.
- *
- * Supported operators: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`,
- * `$in`, `$nin`, `$exists`. Unknown operators return false.
- *
- * @param actual - Actual field value from the entity
- * @param operators - Object of `{ $op: expectedValue }` pairs
- * @returns boolean — true only if all operators pass
- * @throws never — warns on unknown operators
- * @inputSpec operators: Record<string, any> — all keys must start with `$`
- * @calledBy evaluateTriggerConditions (object filter branch)
- */
+// CIL[END chunk_id="triggerengine_getnestedvalue_1784020784"]
+// CIL[BEGIN chunk_id="triggerengine_evaluateoperator_1784020784" type="function" identity="evaluateOperator" parent="none"]
+// CIL[DOC-MACRO purpose="Evaluate comparison operators for trigger conditions"]
+// CIL[DOC-RESPONSIBILITY responsibility="Process MongoDB-style operators like $eq, $gt, $in"]
+// CIL[DOC-CONTEXT module="trigger-engine" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="boolean" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Evaluate multiple operators against actual value, return false on any failure" 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="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 function evaluateOperator(actual: any, operators: Record<string, any>): boolean {
   for (const [op, expected] of Object.entries(operators)) {
     switch (op) {
@@ -348,24 +298,21 @@ function evaluateOperator(actual: any, operators: Record<string, any>): boolean
   }
   return true
 }
-
-// ─── CONVENIENCE HELPERS ────────────────────────────────────────────────────────────
-
-/**
- * Fires `<entityType>_created` triggers. Thin wrapper around
- * `checkAndFireTriggers` that constructs the correct EventType.
- *
- * @param entityType - Entity table name (e.g. 'item', 'person')
- * @param entityId - UUID of the newly created entity
- * @param entityData - The created record (for condition evaluation)
- * @param ctx - CoreContext
- * @returns Promise<void> — always resolves
- * @throws never
- * @sideEffects same as checkAndFireTriggers
- * @calledBy Any API handler's create path (e.g. items.ts, people.ts)
- * @calls checkAndFireTriggers
- * @testUnit tests/unit/trigger-engine.test.ts — 'fireCreateTriggers'
- */
+// CIL[END chunk_id="triggerengine_evaluateoperator_1784020784"]
+// CIL[BEGIN chunk_id="triggerengine_firecreate_1784020784" type="function" identity="fireCreateTriggers" parent="none"]
+// CIL[DOC-MACRO purpose="Fire triggers for entity creation events"]
+// CIL[DOC-RESPONSIBILITY responsibility="Trigger event processing pipeline for created entities"]
+// CIL[DOC-CONTEXT module="trigger-engine" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="void" errors="none" side_effects="Pipeline execution, audit logging"]
+// CIL[DOC-MICRO logic_summary="Create event type string and delegate to checkAndFireTriggers" 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="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export async function fireCreateTriggers(
   entityType: string,
   entityId: string,
@@ -375,21 +322,21 @@ export async function fireCreateTriggers(
   const eventType = `${entityType}_created` as EventType
   await checkAndFireTriggers(eventType, entityType, entityId, entityData, ctx)
 }
-
-/**
- * Fires `<entityType>_updated` triggers. Thin wrapper around
- * `checkAndFireTriggers` that constructs the correct EventType.
- *
- * @param entityType - Entity table name (e.g. 'item', 'person')
- * @param entityId - UUID of the updated entity
- * @param entityData - The updated record (for condition evaluation)
- * @param ctx - CoreContext
- * @returns Promise<void> — always resolves
- * @throws never
- * @sideEffects same as checkAndFireTriggers
- * @calledBy Any API handler's update path
- * @calls checkAndFireTriggers
- */
+// CIL[END chunk_id="triggerengine_firecreate_1784020784"]
+// CIL[BEGIN chunk_id="triggerengine_fireupdate_1784020784" type="function" identity="fireUpdateTriggers" parent="none"]
+// CIL[DOC-MACRO purpose="Fire triggers for entity update events"]
+// CIL[DOC-RESPONSIBILITY responsibility="Trigger event processing pipeline for updated entities"]
+// CIL[DOC-CONTEXT module="trigger-engine" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="void" errors="none" side_effects="Pipeline execution, audit logging"]
+// CIL[DOC-MICRO logic_summary="Create event type string and delegate to checkAndFireTriggers" 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="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export async function fireUpdateTriggers(
   entityType: string,
   entityId: string,
@@ -399,21 +346,21 @@ export async function fireUpdateTriggers(
   const eventType = `${entityType}_updated` as EventType
   await checkAndFireTriggers(eventType, entityType, entityId, entityData, ctx)
 }
-
-/**
- * Fires `<entityType>_deleted` triggers. Thin wrapper around
- * `checkAndFireTriggers` that constructs the correct EventType.
- *
- * @param entityType - Entity table name (e.g. 'item', 'person')
- * @param entityId - UUID of the deleted entity
- * @param entityData - The record snapshot before deletion (for condition evaluation)
- * @param ctx - CoreContext
- * @returns Promise<void> — always resolves
- * @throws never
- * @sideEffects same as checkAndFireTriggers
- * @calledBy Any API handler's delete path
- * @calls checkAndFireTriggers
- */
+// CIL[END chunk_id="triggerengine_fireupdate_1784020784"]
+// CIL[BEGIN chunk_id="triggerengine_firedelete_1784020784" type="function" identity="fireDeleteTriggers" parent="none"]
+// CIL[DOC-MACRO purpose="Fire triggers for entity deletion events"]
+// CIL[DOC-RESPONSIBILITY responsibility="Trigger event processing pipeline for deleted entities"]
+// CIL[DOC-CONTEXT module="trigger-engine" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="void" errors="none" side_effects="Pipeline execution, audit logging"]
+// CIL[DOC-MICRO logic_summary="Create event type string and delegate to checkAndFireTriggers" 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="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export async function fireDeleteTriggers(
   entityType: string,
   entityId: string,
@@ -423,3 +370,4 @@ export async function fireDeleteTriggers(
   const eventType = `${entityType}_deleted` as EventType
   await checkAndFireTriggers(eventType, entityType, entityId, entityData, ctx)
 }
+// CIL[END chunk_id="triggerengine_firedelete_1784020784"]