spine-framework 0.4.3 → 0.4.4

package/.framework/tests/unit/kb-ingest-lease.test.ts

@@ -93,6 +93,13 @@ function resolveQuery(q: QueryLog, opts: any): any {
   if (q.table === 'items') {
     if (has('update')) return { data: null, error: null }
     if (has('or')) return { data: opts.staleItems ?? [], error: null }
+    // Per-id point reads: a superseded doc has already been archived by
+    // the time kbRevoke's execution-time status fence re-reads it.
+    const idEq = q.ops.find(([n, a]) => n === 'eq' && a?.[0] === 'id')?.[1]?.[1]
+    if (idEq && idEq !== ITEM_ID) {
+      const stale = (opts.staleItems ?? []).find((s: any) => s.id === idEq)
+      if (stale) return { data: { ...stale, status: 'archived' }, error: null }
+    }
     return { data: opts.record ?? null, error: null }
   }
   if (q.table === 'types') {
@@ -273,6 +280,18 @@ describe('kbRevoke — lease clearing', () => {
     expect(leaseDelete.ops.find(([n]) => n === 'eq')?.[1]).toEqual(['document_id', ITEM_ID])
   })
 
+  it('skips revocation when the document is currently published — stale queued work fence', async () => {
+    const queries = setupDb({ record: makeRecord({ status: 'published' }) })
+    const rpcCalls = setupRpc({})
+
+    const res = await kbRevoke(ctx, { id: ITEM_ID })
+
+    expect(res).toMatchObject({ ok: true, skipped: true, count: 0 })
+    expect(rpcNamed(rpcCalls, 'revoke_embeddings_for_item')).toHaveLength(0)
+    expect(queriesWithOp(queries, 'embeddings', 'delete')).toHaveLength(0)
+    expect(queriesWithOp(queries, 'document_leases', 'delete')).toHaveLength(0)
+  })
+
   it('non-published ingest routes through kbRevoke and clears the lease', async () => {
     const queries = setupDb({ record: makeRecord({ status: 'draft' }) })
     setupRpc({})

package/.framework/tests/unit/pipeline-runner-background.test.ts

@@ -0,0 +1,120 @@
+// CIL[BEGIN stable_id="~/.framework/tests/unit/pipeline-runner-background.test.ts:module_header:module_header" type="module_header" identity="module_header" parent="none"]
+// CIL[DOC-MACRO purpose="Unit tests for the pipeline-runner-background dispatch function"]
+// CIL[DOC-RESPONSIBILITY responsibility="Verify auth gating, payload validation, and correct runPipeline invocation"]
+// CIL[DOC-CONTEXT module="tests/unit/pipeline-runner-background" layer="test-unit" related_files=".framework/functions/pipeline-runner-background.ts,.framework/functions/_shared/pipeline-runner.ts,.framework/functions/_shared/db.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="test assertions" errors="none" side_effects="Mocks pipeline-runner and db modules"]
+// CIL[DOC-MICRO logic_summary="Stubs INTERNAL_INVOKE_SECRET, mocks runPipeline and sweepStaleExecutions, exercises the raw handler function" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+vi.mock('../../functions/_shared/db.ts', () => ({
+  adminDb: { from: vi.fn(), rpc: vi.fn() }
+}))
+
+vi.mock('../../functions/_shared/pipeline-runner.ts', () => ({
+  runPipeline: vi.fn(),
+  sweepStaleExecutions: vi.fn().mockResolvedValue(undefined)
+}))
+
+vi.mock('../../functions/_shared/audit.ts', () => ({
+  emitAudit: vi.fn().mockResolvedValue(undefined),
+  emitSpan: vi.fn().mockResolvedValue(undefined),
+  emitLog: vi.fn().mockResolvedValue(undefined)
+}))
+
+import { handler } from '../../functions/pipeline-runner-background.ts'
+import { runPipeline } from '../../functions/_shared/pipeline-runner.ts'
+// CIL[END stable_id="~/.framework/tests/unit/pipeline-runner-background.test.ts:module_header:module_header"]
+
+function makeEvent(body: any, secret = 'test-secret'): any {
+  return {
+    httpMethod: 'POST',
+    path: '/.netlify/functions/pipeline-runner-background',
+    headers: { 'x-internal-secret': secret },
+    body: JSON.stringify(body),
+    queryStringParameters: {}
+  }
+}
+
+describe('pipeline-runner-background handler', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    vi.stubEnv('INTERNAL_INVOKE_SECRET', 'test-secret')
+    vi.mocked(runPipeline).mockResolvedValue({
+      executionId: 'exec-1',
+      pipelineId: 'pipe-1',
+      status: 'completed',
+      stages: [],
+      durationMs: 5
+    })
+  })
+
+  it('returns 403 when the internal secret is wrong', async () => {
+    const res = await handler(makeEvent({ pipeline_id: 'pipe-1' }, 'wrong-secret'), {})
+    expect(res.statusCode).toBe(403)
+    expect(runPipeline).not.toHaveBeenCalled()
+  })
+
+  it('returns 403 when the internal secret is absent', async () => {
+    const event = makeEvent({ pipeline_id: 'pipe-1' })
+    delete event.headers['x-internal-secret']
+    const res = await handler(event, {})
+    expect(res.statusCode).toBe(403)
+    expect(runPipeline).not.toHaveBeenCalled()
+  })
+
+  it('returns 400 when pipeline_id is missing from the body', async () => {
+    const res = await handler(makeEvent({ trigger_data: {}, account_id: 'acct-1' }), {})
+    expect(res.statusCode).toBe(400)
+    expect(runPipeline).not.toHaveBeenCalled()
+  })
+
+  it('calls runPipeline with the dispatched pipeline_id and execution_id', async () => {
+    const payload = {
+      pipeline_id: 'pipe-42',
+      trigger_data: { event: 'item_created', entity_id: 'item-9' },
+      account_id: 'acct-7',
+      execution_id: 'exec-queued-99',
+      trigger_id: 'trig-3'
+    }
+    const res = await handler(makeEvent(payload), {})
+
+    expect(runPipeline).toHaveBeenCalledOnce()
+    const [calledPipelineId, calledTriggerData, calledCtx, calledOpts] =
+      vi.mocked(runPipeline).mock.calls[0]
+    expect(calledPipelineId).toBe('pipe-42')
+    expect(calledTriggerData).toMatchObject({ event: 'item_created', entity_id: 'item-9' })
+    expect(calledOpts?.executionId).toBe('exec-queued-99')
+    expect(calledCtx.accountId).toBe('acct-7')
+
+    const body = JSON.parse(res.body)
+    expect(body.ok).toBe(true)
+    expect(body.execution_id).toBe('exec-1')
+    expect(body.status).toBe('completed')
+  })
+
+  it('returns ok:false when the pipeline itself reports failure', async () => {
+    vi.mocked(runPipeline).mockResolvedValue({
+      executionId: 'exec-1',
+      pipelineId: 'pipe-1',
+      status: 'failed',
+      stages: [],
+      durationMs: 5,
+      error: 'stage exploded'
+    })
+    const res = await handler(makeEvent({ pipeline_id: 'pipe-1', execution_id: 'exec-1' }), {})
+    const body = JSON.parse(res.body)
+    expect(body.ok).toBe(false)
+    expect(body.status).toBe('failed')
+  })
+
+  it('returns 500 when runPipeline throws', async () => {
+    vi.mocked(runPipeline).mockRejectedValue(new Error('Pipeline not found'))
+    const res = await handler(makeEvent({ pipeline_id: 'pipe-1', execution_id: 'exec-1' }), {})
+    expect(res.statusCode).toBe(500)
+    const body = JSON.parse(res.body)
+    expect(body.error).toBe('Pipeline not found')
+    expect(body.execution_id).toBe('exec-1')
+  })
+})

package/.framework/tests/unit/pipeline-runner.test.ts

@@ -30,7 +30,7 @@ vi.mock('../../functions/ai-interactions.ts', () => ({
 
 import { adminDb } from '../../functions/_shared/db.ts'
 import { emitAudit } from '../../functions/_shared/audit.ts'
-import { runPipeline } from '../../functions/_shared/pipeline-runner.ts'
+import { runPipeline, sweepStaleExecutions } from '../../functions/_shared/pipeline-runner.ts'
 // CIL[DOC-VECTOR type="context" content="purpose='Test setup and imports for pipeline runner tests'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/audit.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"]
@@ -276,6 +276,105 @@ describe('runPipeline — lifecycle', () => {
       expect.objectContaining({ pipeline_id: 'pipe-1' })
     )
   })
+
+  it('claims a pre-created queued execution row when opts.executionId is supplied', async () => {
+    mockPipeline([])
+    const PRE_CREATED_ID = 'exec-pre-created-1'
+    const updateSpy = vi.fn().mockReturnThis()
+    const eqSpy = vi.fn().mockReturnThis()
+    const claimSelectSpy = vi.fn().mockResolvedValue({ data: [{ id: PRE_CREATED_ID }], error: null })
+    const claimChain = { update: updateSpy, eq: eqSpy, select: claimSelectSpy, insert: vi.fn().mockReturnThis() }
+    vi.mocked(adminDb.from).mockImplementation((table: string) => {
+      if (table === 'pipelines') {
+        return {
+          select: vi.fn().mockReturnThis(),
+          eq: vi.fn().mockReturnThis(),
+          single: vi.fn().mockResolvedValue({ data: { id: 'pipe-1', stages: [], is_active: true }, error: null })
+        } as any
+      }
+      if (table === 'pipeline_executions') return claimChain as any
+      return {
+        select: vi.fn().mockReturnThis(),
+        insert: vi.fn().mockReturnThis(),
+        update: vi.fn().mockReturnThis(),
+        eq: vi.fn().mockReturnThis(),
+        single: vi.fn().mockResolvedValue({ data: null, error: null })
+      } as any
+    })
+
+    const result = await runPipeline('pipe-1', { x: 1 }, makeCtx(), { executionId: PRE_CREATED_ID })
+    expect(result.executionId).toBe(PRE_CREATED_ID)
+    expect(result.status).toBe('completed')
+    // The claim path must call update, not insert.
+    expect(updateSpy).toHaveBeenCalledWith(
+      expect.objectContaining({ status: 'running' })
+    )
+    expect(eqSpy).toHaveBeenCalledWith('id', PRE_CREATED_ID)
+    expect(eqSpy).toHaveBeenCalledWith('status', 'queued')
+    // and it must NOT have inserted a fresh row
+    expect(claimChain.insert).not.toHaveBeenCalled()
+  })
+
+  it('inserts with the same id when the queued row is absent (fallback path)', async () => {
+    const PRE_CREATED_ID = 'exec-missing-1'
+    const insertSpy = vi.fn().mockReturnThis()
+    const singleSpy = vi.fn().mockResolvedValue({ data: { id: PRE_CREATED_ID }, error: null })
+    vi.mocked(adminDb.from).mockImplementation((table: string) => {
+      if (table === 'pipelines') {
+        return {
+          select: vi.fn().mockReturnThis(),
+          eq: vi.fn().mockReturnThis(),
+          single: vi.fn().mockResolvedValue({ data: { id: 'pipe-1', stages: [], is_active: true }, error: null })
+        } as any
+      }
+      if (table === 'pipeline_executions') {
+        const chain: any = {
+          update: vi.fn().mockReturnThis(),
+          eq: vi.fn().mockReturnThis(),
+          select: vi.fn().mockResolvedValue({ data: [], error: null }),   // claim finds no rows
+          insert: insertSpy,
+          single: singleSpy
+        }
+        // insert().select().single() — select must chain to an object with single
+        insertSpy.mockImplementation(() => ({
+          select: vi.fn().mockImplementation(() => ({ single: singleSpy }))
+        }))
+        return chain
+      }
+      return {
+        select: vi.fn().mockReturnThis(),
+        update: vi.fn().mockReturnThis(),
+        eq: vi.fn().mockReturnThis(),
+        single: vi.fn().mockResolvedValue({ data: null, error: null })
+      } as any
+    })
+
+    const result = await runPipeline('pipe-1', {}, makeCtx(), { executionId: PRE_CREATED_ID })
+    expect(result.executionId).toBe(PRE_CREATED_ID)
+    expect(insertSpy).toHaveBeenCalledWith(
+      expect.objectContaining({ id: PRE_CREATED_ID, status: 'running' })
+    )
+  })
+
+  it('throws when claiming a queued execution row fails', async () => {
+    vi.mocked(adminDb.from).mockImplementation((table: string) => {
+      if (table === 'pipelines') {
+        return {
+          select: vi.fn().mockReturnThis(),
+          eq: vi.fn().mockReturnThis(),
+          single: vi.fn().mockResolvedValue({ data: { id: 'pipe-1', stages: [], is_active: true }, error: null })
+        } as any
+      }
+      return {
+        update: vi.fn().mockReturnThis(),
+        eq: vi.fn().mockReturnThis(),
+        select: vi.fn().mockResolvedValue({ data: null, error: { message: 'row not found' } })
+      } as any
+    })
+    await expect(
+      runPipeline('pipe-1', {}, makeCtx(), { executionId: 'missing-exec' })
+    ).rejects.toThrow('Failed to claim queued execution missing-exec')
+  })
 })
 // CIL[DOC-VECTOR type="context" content="purpose='Test runPipeline lifecycle and error handling'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/audit.ts"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
@@ -920,3 +1019,56 @@ describe('send_email — recipient resolution + outbound send', () => {
     expect(result.stages[0].output.skipped).toMatch(/not configured/)
   })
 })
+
+// CIL[BEGIN stable_id="~/.framework/tests/unit/pipeline-runner.test.ts:describe_sweepStaleExecutions:block" type="block" identity="describe_sweepStaleExecutions" parent="none"]
+// CIL[DOC-MACRO purpose="Test stale execution sweeper"]
+// CIL[DOC-RESPONSIBILITY responsibility="Verify sweepStaleExecutions marks stale rows failed and leaves fresh rows alone"]
+// CIL[DOC-CONTEXT module="tests/unit/pipeline-runner" layer="test-unit" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/pipeline-runner.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="test assertions" errors="none" side_effects="Tests sweepStaleExecutions"]
+// CIL[DOC-MICRO logic_summary="Mocks adminDb.from('pipeline_executions').update chain and verifies the correct statuses and cutoff are targeted" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+describe('sweepStaleExecutions', () => {
+  beforeEach(() => vi.clearAllMocks())
+
+  it('marks running/pending/queued rows older than the stale window as failed', async () => {
+    const updateSpy = vi.fn().mockReturnThis()
+    const inSpy = vi.fn().mockReturnThis()
+    const ltSpy = vi.fn().mockResolvedValue({ error: null })
+    vi.mocked(adminDb.from).mockReturnValue({
+      update: updateSpy,
+      in: inSpy,
+      lt: ltSpy
+    } as any)
+
+    await sweepStaleExecutions()
+
+    expect(adminDb.from).toHaveBeenCalledWith('pipeline_executions')
+    expect(updateSpy).toHaveBeenCalledWith(
+      expect.objectContaining({ status: 'failed' })
+    )
+    expect(inSpy).toHaveBeenCalledWith('status', ['running', 'pending', 'queued'])
+    // lt cutoff must be ~10 minutes ago
+    const cutoffArg = ltSpy.mock.calls[0][1] as string
+    const cutoffMs = new Date(cutoffArg).getTime()
+    const expectedMs = Date.now() - 10 * 60 * 1000
+    expect(Math.abs(cutoffMs - expectedMs)).toBeLessThan(5000)
+  })
+
+  it('logs a warning but does not throw when the sweep update fails', async () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    vi.mocked(adminDb.from).mockReturnValue({
+      update: vi.fn().mockReturnThis(),
+      in: vi.fn().mockReturnThis(),
+      lt: vi.fn().mockResolvedValue({ error: { message: 'DB gone' } })
+    } as any)
+
+    await expect(sweepStaleExecutions()).resolves.toBeUndefined()
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining('pipeline_executions stale sweep failed'),
+      'DB gone'
+    )
+    warnSpy.mockRestore()
+  })
+})
+// CIL[END stable_id="~/.framework/tests/unit/pipeline-runner.test.ts:describe_sweepStaleExecutions:block"]

package/.framework/tests/unit/principal-cache.test.ts

@@ -135,4 +135,19 @@ describe('resolvePrincipal human cache — mid-registration guard', () => {
     expect(mockPeopleSingle).toHaveBeenCalledTimes(1)
   })
 })
+
+describe('internal invoke secret', () => {
+  it('resolves a bare x-internal-secret to the system principal', async () => {
+    vi.stubEnv('INTERNAL_INVOKE_SECRET', 'test-secret')
+    const p = await resolvePrincipal({ headers: { 'x-internal-secret': 'test-secret' } })
+    expect(p.id).toBe('system')
+    expect(p.machineType).toBe('internal')
+  })
+
+  it('does not trust a wrong secret', async () => {
+    vi.stubEnv('INTERNAL_INVOKE_SECRET', 'test-secret')
+    const p = await resolvePrincipal({ headers: { 'x-internal-secret': 'wrong' } })
+    expect(p.id).toBe('anonymous')
+  })
+})
 // CIL[END stable_id="~/.framework/tests/unit/principal-cache.test.ts:module_header:module_header"]