spine-framework 0.4.2 → 0.4.4

package/.framework/tests/unit/trigger-engine.test.ts

@@ -21,20 +21,17 @@ vi.mock('../../functions/_shared/audit.ts', () => ({
   emitAudit: vi.fn().mockResolvedValue(undefined)
 }))
 
-vi.mock('../../functions/_shared/pipeline-runner.ts', () => ({
-  runPipeline: vi.fn().mockResolvedValue({
-    executionId: 'mock-exec-id',
-    pipelineId: 'mock-pipeline-id',
-    status: 'completed',
-    stages: [],
-    durationMs: 10
-  })
-}))
-
 import { checkAndFireTriggers, fireCreateTriggers, fireUpdateTriggers } from '../../functions/_shared/trigger-engine.ts'
-import { runPipeline } from '../../functions/_shared/pipeline-runner.ts'
 import { emitAudit } from '../../functions/_shared/audit.ts'
 import { adminDb } from '../../functions/_shared/db.ts'
+
+// dispatchTriggerPipeline POSTs to /.netlify/functions/pipeline-runner-background.
+// Stub fetch globally and the env vars it reads; the dispatch returns
+// immediately (fire-and-forget) so a resolved ok:true is the happy path.
+const mockFetch = vi.fn().mockResolvedValue({ ok: true, status: 200, text: async () => '' })
+vi.stubGlobal('fetch', mockFetch)
+vi.stubEnv('INTERNAL_INVOKE_SECRET', 'test-secret')
+vi.stubEnv('SITE_URL', 'http://test.local')
 // CIL[DOC-VECTOR type="context" content="purpose='Test setup and imports for trigger engine tests'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/trigger-engine.ts,.framework/functions/_shared/pipeline-runner.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"]
@@ -129,13 +126,18 @@ function mockDbTriggers(triggers: any[]) {
 // CIL[DOC-MICRO logic_summary="Sets up mocks for trigger query and stat update operations" notable_decisions="[]"]
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
-function mockDbTriggersWithUpdate(triggers: any[]) {
+function mockDbTriggersWithUpdate(triggers: any[], execId = 'exec-mock-id') {
   const updateChain = {
     update: vi.fn().mockReturnThis(),
     eq: vi.fn().mockResolvedValue({ data: null, error: null })
   }
+  const insertChain = {
+    insert: vi.fn().mockReturnThis(),
+    select: vi.fn().mockReturnThis(),
+    single: vi.fn().mockResolvedValue({ data: { id: execId }, error: null })
+  }
   let callCount = 0
-  vi.mocked(adminDb.from).mockImplementation(() => {
+  vi.mocked(adminDb.from).mockImplementation((table: string) => {
     callCount++
     if (callCount === 1) {
       return {
@@ -144,6 +146,7 @@ function mockDbTriggersWithUpdate(triggers: any[]) {
         order: vi.fn().mockResolvedValue({ data: triggers, error: null })
       } as any
     }
+    if (table === 'pipeline_executions') return insertChain as any
     return updateChain as any
   })
   vi.mocked(adminDb.rpc).mockResolvedValue({ data: 1, error: null } as any)
@@ -172,7 +175,7 @@ describe('checkAndFireTriggers', () => {
   it('does nothing when no triggers match the event type', async () => {
     mockDbTriggers([])
     await checkAndFireTriggers('item_created', 'items', 'item-1', {}, makeCtx())
-    expect(runPipeline).not.toHaveBeenCalled()
+    expect(mockFetch).not.toHaveBeenCalled()
   })
 
   it('does nothing when DB query errors', async () => {
@@ -183,82 +186,163 @@ describe('checkAndFireTriggers', () => {
     }
     vi.mocked(adminDb.from).mockReturnValue(chain as any)
     await checkAndFireTriggers('item_created', 'items', 'item-1', {}, makeCtx())
-    expect(runPipeline).not.toHaveBeenCalled()
+    expect(mockFetch).not.toHaveBeenCalled()
   })
 
-  it('fires pipeline for a matching trigger with no conditions', async () => {
+  it('dispatches pipeline for a matching trigger with no conditions', async () => {
     mockDbTriggersWithUpdate([makeTrigger()])
     await checkAndFireTriggers('item_created', 'items', 'item-1', {}, makeCtx())
-    expect(runPipeline).toHaveBeenCalledOnce()
-    expect(runPipeline).toHaveBeenCalledWith(
-      'pipeline-1',
-      expect.objectContaining({
-        event: 'item_created',
-        entity: expect.objectContaining({ type: 'items', id: 'item-1' })
-      }),
-      expect.any(Object)
+    expect(mockFetch).toHaveBeenCalledOnce()
+    const [url, init] = mockFetch.mock.calls[0]
+    expect(url).toBe('http://test.local/.netlify/functions/pipeline-runner-background')
+    const body = JSON.parse(init.body as string)
+    expect(body.pipeline_id).toBe('pipeline-1')
+    expect(body.trigger_data.event).toBe('item_created')
+    expect(body.trigger_data.entity.id).toBe('item-1')
+    expect(init.headers['X-Internal-Secret']).toBe('test-secret')
+  })
+
+  it('pre-creates a queued pipeline_executions row before dispatch', async () => {
+    const insertChain = {
+      insert: vi.fn().mockReturnThis(),
+      select: vi.fn().mockReturnThis(),
+      single: vi.fn().mockResolvedValue({ data: { id: 'exec-queued-1' }, error: null })
+    }
+    vi.mocked(adminDb.from).mockImplementation((table: string) => {
+      if (table === 'triggers') {
+        return {
+          select: vi.fn().mockReturnThis(),
+          eq: vi.fn().mockReturnThis(),
+          order: vi.fn().mockResolvedValue({ data: [makeTrigger()], error: null })
+        } as any
+      }
+      if (table === 'pipeline_executions') return insertChain as any
+      return { update: vi.fn().mockReturnThis(), eq: vi.fn().mockResolvedValue({ data: null, error: null }) } as any
+    })
+    await checkAndFireTriggers('item_created', 'items', 'item-1', {}, makeCtx())
+    expect(insertChain.insert).toHaveBeenCalledWith(
+      expect.objectContaining({ status: 'queued', pipeline_id: 'pipeline-1' })
     )
+    // The execution_id from the queued row is forwarded in the dispatch body.
+    const body = JSON.parse(mockFetch.mock.calls[0][1].body as string)
+    expect(body.execution_id).toBe('exec-queued-1')
   })
 
   it('passes trigger metadata in the trigger data', async () => {
     mockDbTriggersWithUpdate([makeTrigger({ id: 'trig-xyz', name: 'My Trigger' })])
     await checkAndFireTriggers('item_created', 'items', 'item-1', {}, makeCtx())
-    expect(runPipeline).toHaveBeenCalledWith(
-      'pipeline-1',
-      expect.objectContaining({
-        trigger: { id: 'trig-xyz', name: 'My Trigger' }
-      }),
-      expect.any(Object)
-    )
+    const body = JSON.parse(mockFetch.mock.calls[0][1].body as string)
+    expect(body.trigger_data.trigger).toEqual({ id: 'trig-xyz', name: 'My Trigger' })
+    expect(body.trigger_id).toBe('trig-xyz')
   })
 
-  it('emits audit on successful trigger fire', async () => {
+  it('emits audit on successful trigger fire with queued status', async () => {
     mockDbTriggersWithUpdate([makeTrigger()])
     await checkAndFireTriggers('item_created', 'items', 'item-1', {}, makeCtx())
     expect(emitAudit).toHaveBeenCalledWith(
       expect.any(Object),
       'trigger.fired',
       expect.objectContaining({ type: 'trigger', id: 'trigger-1' }),
-      expect.objectContaining({ execution_status: 'completed' })
+      expect.objectContaining({ execution_status: 'queued' })
     )
   })
 
-  it('emits audit.failed and continues when runPipeline throws', async () => {
-    mockDbTriggers([makeTrigger({ id: 'bad-trigger' })])
-    vi.mocked(runPipeline).mockRejectedValueOnce(new Error('Pipeline exploded'))
+  it('emits audit.failed and continues when the execution insert throws', async () => {
+    vi.mocked(adminDb.from).mockImplementation((table: string) => {
+      if (table === 'triggers') {
+        return {
+          select: vi.fn().mockReturnThis(),
+          eq: vi.fn().mockReturnThis(),
+          order: vi.fn().mockResolvedValue({ data: [makeTrigger({ id: 'bad-trigger' })], error: null })
+        } as any
+      }
+      if (table === 'pipeline_executions') {
+        throw new Error('pipeline_executions insert exploded')
+      }
+      return { update: vi.fn().mockReturnThis(), eq: vi.fn().mockResolvedValue({ data: null, error: null }) } as any
+    })
+    vi.mocked(adminDb.rpc).mockResolvedValue({ data: 1, error: null } as any)
     await checkAndFireTriggers('item_created', 'items', 'item-1', {}, makeCtx())
     expect(emitAudit).toHaveBeenCalledWith(
       expect.any(Object),
       'trigger.failed',
       expect.objectContaining({ id: 'bad-trigger' }),
-      expect.objectContaining({ error: 'Pipeline exploded' })
+      expect.objectContaining({ error: 'pipeline_executions insert exploded' })
+    )
+  })
+
+  it('still emits trigger.fired with queued status when dispatch fetch fails', async () => {
+    mockDbTriggersWithUpdate([makeTrigger()])
+    mockFetch.mockRejectedValueOnce(new Error('network unreachable'))
+    await checkAndFireTriggers('item_created', 'items', 'item-1', {}, makeCtx())
+    // dispatchTriggerPipeline catches the fetch error internally — the
+    // trigger.fired audit still fires with execution_status='queued'.
+    expect(emitAudit).toHaveBeenCalledWith(
+      expect.any(Object),
+      'trigger.fired',
+      expect.objectContaining({ id: 'trigger-1' }),
+      expect.objectContaining({ execution_status: 'queued' })
     )
   })
 
-  it('fires all matching triggers, not just the first', async () => {
+  it('dispatches all matching triggers, not just the first', async () => {
     const t1 = makeTrigger({ id: 'trig-1', pipeline_id: 'pipe-1' })
     const t2 = makeTrigger({ id: 'trig-2', pipeline_id: 'pipe-2' })
     mockDbTriggersWithUpdate([t1, t2])
-    vi.mocked(runPipeline)
-      .mockResolvedValueOnce({ executionId: 'exec-1', pipelineId: 'pipe-1', status: 'completed', stages: [], durationMs: 5 })
-      .mockResolvedValueOnce({ executionId: 'exec-2', pipelineId: 'pipe-2', status: 'completed', stages: [], durationMs: 5 })
-
     await checkAndFireTriggers('item_created', 'items', 'item-1', {}, makeCtx())
-    expect(runPipeline).toHaveBeenCalledTimes(2)
-    expect(runPipeline).toHaveBeenCalledWith('pipe-1', expect.any(Object), expect.any(Object))
-    expect(runPipeline).toHaveBeenCalledWith('pipe-2', expect.any(Object), expect.any(Object))
+    expect(mockFetch).toHaveBeenCalledTimes(2)
+    const bodies = mockFetch.mock.calls.map(([, init]) => JSON.parse(init.body as string))
+    expect(bodies[0].pipeline_id).toBe('pipe-1')
+    expect(bodies[1].pipeline_id).toBe('pipe-2')
   })
 
-  it('continues to fire remaining triggers after one fails', async () => {
+  it('continues to dispatch remaining triggers after a DB error on one', async () => {
     const t1 = makeTrigger({ id: 'trig-fail', pipeline_id: 'pipe-1' })
     const t2 = makeTrigger({ id: 'trig-ok', pipeline_id: 'pipe-2' })
-    mockDbTriggers([t1, t2])
-    vi.mocked(runPipeline)
-      .mockRejectedValueOnce(new Error('pipe-1 failed'))
-      .mockResolvedValueOnce({ executionId: 'exec-2', pipelineId: 'pipe-2', status: 'completed', stages: [], durationMs: 5 })
+    let insertCount = 0
+    vi.mocked(adminDb.from).mockImplementation((table: string) => {
+      if (table === 'triggers') {
+        return {
+          select: vi.fn().mockReturnThis(),
+          eq: vi.fn().mockReturnThis(),
+          order: vi.fn().mockResolvedValue({ data: [t1, t2], error: null })
+        } as any
+      }
+      if (table === 'pipeline_executions') {
+        insertCount++
+        if (insertCount === 1) throw new Error('insert failed for trig-fail')
+        return {
+          insert: vi.fn().mockReturnThis(),
+          select: vi.fn().mockReturnThis(),
+          single: vi.fn().mockResolvedValue({ data: { id: 'exec-2' }, error: null })
+        } as any
+      }
+      return { update: vi.fn().mockReturnThis(), eq: vi.fn().mockResolvedValue({ data: null, error: null }) } as any
+    })
+    vi.mocked(adminDb.rpc).mockResolvedValue({ data: 1, error: null } as any)
+    await checkAndFireTriggers('item_created', 'items', 'item-1', {}, makeCtx())
+    // trig-fail errored during insert; trig-ok still dispatched.
+    expect(mockFetch).toHaveBeenCalledTimes(1)
+    expect(emitAudit).toHaveBeenCalledWith(
+      expect.any(Object),
+      'trigger.failed',
+      expect.objectContaining({ id: 'trig-fail' }),
+      expect.objectContaining({ error: 'insert failed for trig-fail' })
+    )
+    expect(emitAudit).toHaveBeenCalledWith(
+      expect.any(Object),
+      'trigger.fired',
+      expect.objectContaining({ id: 'trig-ok' }),
+      expect.objectContaining({ execution_status: 'queued' })
+    )
+  })
 
+  it('bounds the dispatch fetch with a 5s abort signal', async () => {
+    mockDbTriggersWithUpdate([makeTrigger()])
     await checkAndFireTriggers('item_created', 'items', 'item-1', {}, makeCtx())
-    expect(runPipeline).toHaveBeenCalledTimes(2)
+    const init = mockFetch.mock.calls[0][1]
+    expect(init.signal).toBeInstanceOf(AbortSignal)
+    expect(init.signal.aborted).toBe(false)
   })
 })
 // CIL[DOC-VECTOR type="context" content="purpose='Test checkAndFireTriggers core functionality'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/trigger-engine.ts,.framework/functions/_shared/pipeline-runner.ts"]
@@ -286,70 +370,70 @@ describe('trigger condition filtering', () => {
     const trigger = makeTrigger({ config: { entity_type: 'people' } })
     mockDbTriggers([trigger])
     await checkAndFireTriggers('item_created', 'items', 'item-1', {}, makeCtx())
-    expect(runPipeline).not.toHaveBeenCalled()
+    expect(mockFetch).not.toHaveBeenCalled()
   })
 
   it('fires trigger when entity_type filter matches', async () => {
     const trigger = makeTrigger({ config: { entity_type: 'items' } })
     mockDbTriggersWithUpdate([trigger])
     await checkAndFireTriggers('item_created', 'items', 'item-1', {}, makeCtx())
-    expect(runPipeline).toHaveBeenCalledOnce()
+    expect(mockFetch).toHaveBeenCalledOnce()
   })
 
   it('skips trigger when type_slug filter does not match', async () => {
     const trigger = makeTrigger({ config: { type_slug: 'invoice' } })
     mockDbTriggers([trigger])
     await checkAndFireTriggers('item_created', 'items', 'item-1', { type_slug: 'support_ticket' }, makeCtx())
-    expect(runPipeline).not.toHaveBeenCalled()
+    expect(mockFetch).not.toHaveBeenCalled()
   })
 
   it('fires trigger when type_slug filter matches', async () => {
     const trigger = makeTrigger({ config: { type_slug: 'support_ticket' } })
     mockDbTriggersWithUpdate([trigger])
     await checkAndFireTriggers('item_created', 'items', 'item-1', { type_slug: 'support_ticket' }, makeCtx())
-    expect(runPipeline).toHaveBeenCalledOnce()
+    expect(mockFetch).toHaveBeenCalledOnce()
   })
 
   it('skips trigger when simple filter value does not match', async () => {
     const trigger = makeTrigger({ config: { filters: { status: 'open' } } })
     mockDbTriggers([trigger])
     await checkAndFireTriggers('item_created', 'items', 'item-1', { status: 'closed' }, makeCtx())
-    expect(runPipeline).not.toHaveBeenCalled()
+    expect(mockFetch).not.toHaveBeenCalled()
   })
 
   it('fires trigger when simple filter value matches', async () => {
     const trigger = makeTrigger({ config: { filters: { status: 'open' } } })
     mockDbTriggersWithUpdate([trigger])
     await checkAndFireTriggers('item_created', 'items', 'item-1', { status: 'open' }, makeCtx())
-    expect(runPipeline).toHaveBeenCalledOnce()
+    expect(mockFetch).toHaveBeenCalledOnce()
   })
 
   it('fires trigger when array filter includes the value', async () => {
     const trigger = makeTrigger({ config: { filters: { priority: ['high', 'critical'] } } })
     mockDbTriggersWithUpdate([trigger])
     await checkAndFireTriggers('item_created', 'items', 'item-1', { priority: 'high' }, makeCtx())
-    expect(runPipeline).toHaveBeenCalledOnce()
+    expect(mockFetch).toHaveBeenCalledOnce()
   })
 
   it('skips trigger when value not in array filter', async () => {
     const trigger = makeTrigger({ config: { filters: { priority: ['high', 'critical'] } } })
     mockDbTriggers([trigger])
     await checkAndFireTriggers('item_created', 'items', 'item-1', { priority: 'low' }, makeCtx())
-    expect(runPipeline).not.toHaveBeenCalled()
+    expect(mockFetch).not.toHaveBeenCalled()
   })
 
   it('resolves nested dot-notation filter paths', async () => {
     const trigger = makeTrigger({ config: { filters: { 'data.region': 'us-west' } } })
     mockDbTriggersWithUpdate([trigger])
     await checkAndFireTriggers('item_created', 'items', 'item-1', { data: { region: 'us-west' } }, makeCtx())
-    expect(runPipeline).toHaveBeenCalledOnce()
+    expect(mockFetch).toHaveBeenCalledOnce()
   })
 
   it('resolves Postgres-style ->> filter paths against the data column', async () => {
     const trigger = makeTrigger({ config: { filters: { "data->>'sender_type'": { $eq: 'agent' } } } })
     mockDbTriggersWithUpdate([trigger])
     await checkAndFireTriggers('message_created', 'messages', 'msg-1', { data: { sender_type: 'agent' } }, makeCtx())
-    expect(runPipeline).toHaveBeenCalledOnce()
+    expect(mockFetch).toHaveBeenCalledOnce()
   })
 
   it('maps plural table names to singular event types (fireCreateTriggers)', async () => {
@@ -357,51 +441,55 @@ describe('trigger condition filtering', () => {
     mockDbTriggersWithUpdate([trigger])
     // admin-data passes the table name 'items'; the seeded event is 'item_created'
     await fireCreateTriggers('items', 'item-1', {}, makeCtx())
-    expect(runPipeline).toHaveBeenCalledOnce()
-    expect(runPipeline).toHaveBeenCalledWith(
-      'pipeline-1',
-      expect.objectContaining({ event: 'item_created' }),
-      expect.any(Object)
-    )
+    expect(mockFetch).toHaveBeenCalledOnce()
+    const body = JSON.parse(mockFetch.mock.calls[0][1].body as string)
+    expect(body.pipeline_id).toBe('pipeline-1')
+    expect(body.trigger_data.event).toBe('item_created')
   })
 
   it('maps plural table names to singular event types (fireUpdateTriggers)', async () => {
     const trigger = makeTrigger({ config: { entity_type: 'items' } })
     mockDbTriggersWithUpdate([trigger])
     await fireUpdateTriggers('items', 'item-1', {}, makeCtx())
-    expect(runPipeline).toHaveBeenCalledWith(
-      'pipeline-1',
-      expect.objectContaining({ event: 'item_updated' }),
-      expect.any(Object)
-    )
+    const body = JSON.parse(mockFetch.mock.calls[0][1].body as string)
+    expect(body.pipeline_id).toBe('pipeline-1')
+    expect(body.trigger_data.event).toBe('item_updated')
   })
 
   it('maps people → person for event types', async () => {
     const trigger = makeTrigger({ config: { entity_type: 'people' } })
     mockDbTriggersWithUpdate([trigger])
     await fireCreateTriggers('people', 'person-1', {}, makeCtx())
-    expect(runPipeline).toHaveBeenCalledWith(
-      'pipeline-1',
-      expect.objectContaining({ event: 'person_created' }),
-      expect.any(Object)
-    )
+    const body = JSON.parse(mockFetch.mock.calls[0][1].body as string)
+    expect(body.pipeline_id).toBe('pipeline-1')
+    expect(body.trigger_data.event).toBe('person_created')
   })
 
   it('resolves type_slug from entityData.type_id when the slug is not inline', async () => {
     const trigger = makeTrigger({ config: { entity_type: 'items', type_slug: 'kb_article' } })
-    const chain = {
+    const insertChain = {
+      insert: vi.fn().mockReturnThis(),
       select: vi.fn().mockReturnThis(),
-      eq: vi.fn().mockReturnThis(),
-      order: vi.fn().mockResolvedValue({ data: [trigger], error: null }),
-      maybeSingle: vi.fn().mockResolvedValue({ data: { slug: 'kb_article' }, error: null }),
-      update: vi.fn().mockReturnThis()
+      single: vi.fn().mockResolvedValue({ data: { id: 'exec-1' }, error: null })
     }
     vi.mocked(adminDb.from).mockImplementation((table: string) => {
-      if (table === 'types') return chain as any
-      return chain as any
+      if (table === 'types') {
+        return {
+          select: vi.fn().mockReturnThis(),
+          eq: vi.fn().mockReturnThis(),
+          maybeSingle: vi.fn().mockResolvedValue({ data: { slug: 'kb_article' }, error: null })
+        } as any
+      }
+      if (table === 'pipeline_executions') return insertChain as any
+      return {
+        select: vi.fn().mockReturnThis(),
+        eq: vi.fn().mockReturnThis(),
+        order: vi.fn().mockResolvedValue({ data: [trigger], error: null }),
+        update: vi.fn().mockReturnThis()
+      } as any
     })
     await checkAndFireTriggers('item_created', 'items', 'item-1', { type_id: 'type-uuid-1', status: 'published' }, makeCtx())
-    expect(runPipeline).toHaveBeenCalledOnce()
+    expect(mockFetch).toHaveBeenCalledOnce()
   })
 
   // CIL[DOC-NOTE type="behavior" content="The demo seed filter { data->>'ca_kb_candidate': { $eq: true } } relies on strict boolean equality — the jsonb value is a real boolean, so a string 'true' operand would never fire."]
@@ -414,7 +502,7 @@ describe('trigger condition filtering', () => {
     })
     mockDbTriggersWithUpdate([trigger])
     await checkAndFireTriggers('item_updated', 'items', 'item-1', { type_slug: 'demo_support_ticket', data: { ca_kb_candidate: true } }, makeCtx())
-    expect(runPipeline).toHaveBeenCalledOnce()
+    expect(mockFetch).toHaveBeenCalledOnce()
   })
 
   it('does not fire a boolean data->> field when $eq uses the string "true"', async () => {
@@ -423,7 +511,7 @@ describe('trigger condition filtering', () => {
     })
     mockDbTriggers([trigger])
     await checkAndFireTriggers('item_updated', 'items', 'item-1', { data: { ca_kb_candidate: true } }, makeCtx())
-    expect(runPipeline).not.toHaveBeenCalled()
+    expect(mockFetch).not.toHaveBeenCalled()
   })
 
   it('skips a boolean $eq filter when the data flag is false', async () => {
@@ -432,7 +520,7 @@ describe('trigger condition filtering', () => {
     })
     mockDbTriggers([trigger])
     await checkAndFireTriggers('item_updated', 'items', 'item-1', { data: { ca_kb_candidate: false } }, makeCtx())
-    expect(runPipeline).not.toHaveBeenCalled()
+    expect(mockFetch).not.toHaveBeenCalled()
   })
 })
 // CIL[DOC-VECTOR type="context" content="purpose='Test trigger condition filtering logic'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/trigger-engine.ts,.framework/functions/_shared/pipeline-runner.ts"]
@@ -465,9 +553,9 @@ describe('filter operators', () => {
     }
     await checkAndFireTriggers('item_created', 'items', 'item-1', entityData, makeCtx())
     if (shouldFire) {
-      expect(runPipeline).toHaveBeenCalledOnce()
+      expect(mockFetch).toHaveBeenCalledOnce()
     } else {
-      expect(runPipeline).not.toHaveBeenCalled()
+      expect(mockFetch).not.toHaveBeenCalled()
     }
     vi.clearAllMocks()
   }
@@ -510,4 +598,103 @@ describe('filter operators', () => {
 // 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/tests/unit/trigger-engine.test.ts:describe_filterOperators:block"]
+// CIL[END stable_id="~/.framework/tests/unit/trigger-engine.test.ts:describe_filterOperators:block"]
+// CIL[BEGIN stable_id="~/.framework/tests/unit/trigger-engine.test.ts:describe_fireOnTransition:block" type="block" identity="describe_fireOnTransition" parent="none"]
+// CIL[DOC-MACRO purpose="Test fire_on_transition trigger semantics"]
+// CIL[DOC-RESPONSIBILITY responsibility="Verify transition-only triggers fire once when a record enters the matching state and skip repeat updates"]
+// CIL[DOC-CONTEXT module="tests/unit/trigger-engine" layer="test-unit" related_files=".framework/functions/_shared/trigger-engine.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="test assertions" errors="none" side_effects="Tests trigger-engine.ts module"]
+// CIL[DOC-MICRO logic_summary="Covers transition-in firing, already-matching skip, missing-previous fallback, non-flagged repeat firing, and fireUpdateTriggers prev passthrough" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.8" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+describe('fire_on_transition triggers', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  const publishTrigger = () => makeTrigger({
+    event_type: 'item_updated',
+    config: {
+      entity_type: 'items',
+      type_slug: 'demo_kb_article',
+      fire_on_transition: true,
+      filters: { status: { $eq: 'published' } }
+    }
+  })
+
+  it('fires when the record transitions into the matching state', async () => {
+    mockDbTriggersWithUpdate([publishTrigger()])
+    const entityData = { status: 'published', type_slug: 'demo_kb_article' }
+    const previous = { status: 'draft', type_slug: 'demo_kb_article' }
+    await checkAndFireTriggers('item_updated', 'items', 'item-1', entityData, makeCtx(), previous)
+    expect(mockFetch).toHaveBeenCalledOnce()
+  })
+
+  it('skips when the record already matched before the update', async () => {
+    mockDbTriggersWithUpdate([publishTrigger()])
+    const entityData = { status: 'published', type_slug: 'demo_kb_article' }
+    const previous = { status: 'published', type_slug: 'demo_kb_article' }
+    await checkAndFireTriggers('item_updated', 'items', 'item-1', entityData, makeCtx(), previous)
+    expect(mockFetch).not.toHaveBeenCalled()
+    expect(adminDb.rpc).not.toHaveBeenCalled()
+  })
+
+  it('fires when no previous snapshot is provided (conservative)', async () => {
+    mockDbTriggersWithUpdate([publishTrigger()])
+    const entityData = { status: 'published', type_slug: 'demo_kb_article' }
+    await checkAndFireTriggers('item_updated', 'items', 'item-1', entityData, makeCtx())
+    expect(mockFetch).toHaveBeenCalledOnce()
+  })
+
+  it('still fires on repeat matches when the flag is absent', async () => {
+    const trigger = makeTrigger({
+      event_type: 'item_updated',
+      config: {
+        entity_type: 'items',
+        type_slug: 'demo_kb_article',
+        filters: { status: { $eq: 'published' } }
+      }
+    })
+    mockDbTriggersWithUpdate([trigger])
+    const entityData = { status: 'published', type_slug: 'demo_kb_article' }
+    const previous = { status: 'published', type_slug: 'demo_kb_article' }
+    await checkAndFireTriggers('item_updated', 'items', 'item-1', entityData, makeCtx(), previous)
+    expect(mockFetch).toHaveBeenCalledOnce()
+  })
+
+  it('revoke-style trigger fires only when leaving the published state', async () => {
+    const trigger = makeTrigger({
+      event_type: 'item_updated',
+      config: {
+        entity_type: 'items',
+        type_slug: 'demo_kb_article',
+        fire_on_transition: true,
+        filters: { status: { $ne: 'published' } }
+      }
+    })
+    mockDbTriggersWithUpdate([trigger])
+
+    // published → draft: previous fails the $ne filter, new matches → fires
+    await checkAndFireTriggers('item_updated', 'items', 'item-1',
+      { status: 'draft', type_slug: 'demo_kb_article' }, makeCtx(),
+      { status: 'published', type_slug: 'demo_kb_article' })
+    expect(mockFetch).toHaveBeenCalledOnce()
+
+    // draft → draft (already non-published): previous also matches → skip
+    vi.clearAllMocks()
+    mockDbTriggersWithUpdate([trigger])
+    await checkAndFireTriggers('item_updated', 'items', 'item-1',
+      { status: 'draft', type_slug: 'demo_kb_article' }, makeCtx(),
+      { status: 'draft', type_slug: 'demo_kb_article' })
+    expect(mockFetch).not.toHaveBeenCalled()
+  })
+
+  it('fireUpdateTriggers forwards the previous snapshot', async () => {
+    mockDbTriggersWithUpdate([publishTrigger()])
+    await fireUpdateTriggers('items', 'item-1',
+      { status: 'published', type_slug: 'demo_kb_article' }, makeCtx(),
+      { status: 'published', type_slug: 'demo_kb_article' })
+    expect(mockFetch).not.toHaveBeenCalled()
+  })
+})
+// CIL[END stable_id="~/.framework/tests/unit/trigger-engine.test.ts:describe_fireOnTransition:block"]

package/.framework/tests/unit/trigger-scheduler.test.ts

@@ -0,0 +1,78 @@
+// CIL[BEGIN stable_id="~/.framework/tests/unit/trigger-scheduler.test.ts:module_header:module_header" type="module_header" identity="module_header" parent="none"]
+// CIL[DOC-MACRO purpose="Tests for trigger-scheduler's Netlify Clockwork detection and context fabrication"]
+// CIL[DOC-RESPONSIBILITY responsibility="Verify scheduled invocations bypass middleware auth via fabricated system ctx while HTTP requests take the normal path"]
+// CIL[DOC-CONTEXT module="tests/unit/trigger-scheduler" layer="test-unit" related_files=".framework/functions/trigger-scheduler.ts,.framework/functions/system-cron.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="test assertions" errors="none" side_effects="Mocks system-cron handler and db"]
+// CIL[DOC-MICRO logic_summary="Mocks the cron handler export, invokes trigger-scheduler with scheduled and non-scheduled event shapes, asserts the fabricated ctx carries SYSTEM_PRINCIPAL" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.8" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+const { cronHandler } = vi.hoisted(() => ({
+  cronHandler: vi.fn().mockResolvedValue({ statusCode: 200 })
+}))
+
+vi.mock('../../functions/system-cron.ts', () => ({
+  handler: cronHandler
+}))
+
+vi.mock('../../functions/_shared/db.ts', () => ({
+  adminDb: {}
+}))
+
+import { handler } from '../../functions/trigger-scheduler.ts'
+
+describe('trigger-scheduler', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('fabricates a system-principal ctx for Netlify Clockwork invocations', async () => {
+    const event = {
+      path: '/.netlify/functions/trigger-scheduler',
+      httpMethod: 'POST',
+      headers: {
+        'x-nf-event': 'schedule',
+        'user-agent': 'Netlify Clockwork',
+      },
+      body: JSON.stringify({ next_run: '2026-10-23T21:07:00.000Z' }),
+    }
+    await handler(event, {})
+
+    expect(cronHandler).toHaveBeenCalledOnce()
+    const [ctx] = cronHandler.mock.calls[0]
+    // The fabricated ctx flows straight into the cron handler — createHandler
+    // short-circuits on requestId+principal without re-resolving auth.
+    expect(ctx.requestId).toBeTruthy()
+    expect(ctx.principal.id).toBe('system')
+    expect(ctx.principal.machineType).toBe('internal')
+    expect(ctx.source).toBe('netlify-scheduler')
+  })
+
+  it('forwards non-scheduled HTTP requests to the normal middleware path', async () => {
+    const event = {
+      path: '/.netlify/functions/trigger-scheduler',
+      httpMethod: 'POST',
+      headers: { 'x-internal-secret': 'some-secret' },
+      body: '{}',
+    }
+    await handler(event, {})
+
+    expect(cronHandler).toHaveBeenCalledOnce()
+    // The raw event goes through untouched — createHandler resolves auth.
+    expect(cronHandler.mock.calls[0][0]).toBe(event)
+  })
+
+  it('does not trust a spoofed x-nf-event header without the next_run payload', async () => {
+    const event = {
+      path: '/.netlify/functions/trigger-scheduler',
+      httpMethod: 'POST',
+      headers: { 'x-nf-event': 'schedule' },
+      body: '{}',
+    }
+    await handler(event, {})
+
+    expect(cronHandler.mock.calls[0][0]).toBe(event)
+  })
+})
+// CIL[END stable_id="~/.framework/tests/unit/trigger-scheduler.test.ts:module_header:module_header"]