Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
16.0 KB
Raw Blame
import { describe, expect, it, vi } from 'vitest'
import type { DbClient } from '../src/db.js'
import type {
  GovernedEventReadRepositoryV1,
  GovernedEventReadRowV1,
} from '../src/services/tracing/contracts.js'
import {
  GovernedEventReadService,
  GovernedReadInvalidQueryError,
  GovernedReadScopeMismatchError,
} from '../src/services/tracing/governedEventReadService.js'
import { PostgresGovernedEventReadRepository } from '../src/services/tracing/postgresGovernedEventReadRepository.js'

const readDurationObserve = vi.hoisted(() => vi.fn())

vi.mock('../src/observability/metrics.js', () => ({
  governedTraceReadDurationSeconds: { observe: readDurationObserve },
}))

const ROW: GovernedEventReadRowV1 = {
  streamSequence: '5',
  eventFamily: 'agent_run',
  eventId: 'event-5',
  schemaVersion: 1,
  occurredAt: '2026-07-10T09:00:00.000Z',
  ingestedAt: '2026-07-10T09:00:01.000Z',
  correlationRef: 'run-1',
  sessionId: 'session-1',
  actorKind: 'human_via_agent',
  actorSub: 'user-1',
  serviceOrAgentSub: 'agent-1',
  initiatingHumanSub: 'user-1',
  actingAgentSub: 'agent-1',
  resourceAud: 'mcp://host-1',
  effectiveScopes: ['tools:read'],
  authorizationDecision: 'allow',
  tokenExchangeId: 'exchange-1',
  eventType: 'run_start',
  outcome: 'started',
  targetType: 'run',
  targetRef: 'run-1',
  recipeNamespace: 'sandbox-recipes',
  recipeName: 'chatllm',
  hostRef: 'sandbox-recipes/chatllm',
  operatorUserId: null,
  operatorPrincipalId: null,
  operatorPrincipalKind: 'system',
  operatorDisplayName: null,
  delegatedActorSub: null,
  sourceKind: 'mcp_host_runtime',
  sourceService: 'mcp-host',
  serviceSub: 'mcp-host/standalone',
  targetUserId: null,
  targetUserSub: null,
  targetUserDisplayName: null,
  teamId: null,
  targetTeamDisplayName: null,
  telemetryType: null,
  reasonCode: null,
  clusterName: null,
  namespace: null,
  workloadKind: null,
  workloadRef: null,
  controller: null,
  payload: {
    summary: 'run started',
    rawPrompt: 'must-not-be-released',
    costUsd: 99,
  },
}

describe('PostgresGovernedEventReadRepository', () => {
  it('materializes a bounded stream page before joining the normalized view', async () => {
    const query = vi.fn().mockResolvedValue({
      rows: [
        {
          stream_sequence: '5',
          event_family: 'agent_run',
          event_id: 'event-5',
          schema_version: 1,
          occurred_at: ROW.occurredAt,
          ingested_at: ROW.ingestedAt,
          correlation_ref: 'run-1',
          session_id: 'session-1',
          actor_kind: 'human_via_agent',
          actor_sub: 'user-1',
          service_or_agent_sub: 'agent-1',
          initiating_human_sub: 'user-1',
          acting_agent_sub: 'agent-1',
          resource_aud: 'mcp://host-1',
          effective_scopes: ['tools:read'],
          authorization_decision: 'allow',
          token_exchange_id: 'exchange-1',
          event_type: 'run_start',
          outcome: 'started',
          target_type: 'run',
          target_ref: 'run-1',
          recipe_namespace: 'sandbox-recipes',
          recipe_name: 'chatllm',
          host_ref: 'sandbox-recipes/chatllm',
          operator_user_id: null,
          operator_principal_id: null,
          operator_principal_kind: 'system',
          operator_display_name: null,
          team_id: null,
          target_team_display_name: null,
          payload: ROW.payload,
        },
      ],
      rowCount: 1,
    })
    const repository = new PostgresGovernedEventReadRepository({ query } as DbClient)

    const rows = await repository.readAfter({
      scope: {
        kind: 'workflow_run',
        runId: 'run-1',
        recipeNamespace: 'sandbox-recipes',
        recipeName: 'chatllm',
      },
      families: ['agent_run'],
      order: 'oldest',
      afterSequence: '0',
      highWatermark: '10',
      limit: 25,
      occurredFrom: null,
      occurredTo: null,
    })

    expect(rows).toHaveLength(1)
    expect(rows[0]).toMatchObject({
      sessionId: 'session-1',
      initiatingHumanSub: 'user-1',
      actingAgentSub: 'agent-1',
      resourceAud: 'mcp://host-1',
      effectiveScopes: ['tools:read'],
      authorizationDecision: 'allow',
      tokenExchangeId: 'exchange-1',
    })
    const [sql, params] = query.mock.calls[0] as [string, unknown[]]
    expect(sql).toContain('WITH stream_page AS MATERIALIZED')
    expect(sql).toContain('LEFT JOIN teams target_team')
    expect(sql.indexOf('FROM governed_event_stream')).toBeLessThan(
      sql.indexOf('JOIN governed_event_read_v1')
    )
    expect(sql).toContain('s.run_id =')
    expect(sql).toContain('ORDER BY s.stream_sequence ASC')
    expect(sql).toContain('LIMIT')
    expect(sql).toContain('LEFT JOIN infrastructure_telemetry_events telemetry')
    expect(sql).toContain('LEFT JOIN control_admin_users operator_admin')
    expect(sql).toContain('agent.session_id')
    expect(sql).toContain("'ready_replicas', telemetry.ready_replicas")
    expect(sql).toContain("'cpu_usage_core_seconds', telemetry.cpu_usage_core_seconds")
    expect(params.at(-1)).toBe(25)
  })

  it('rejects repository limits above the hard page bound', async () => {
    const repository = new PostgresGovernedEventReadRepository({ query: vi.fn() } as DbClient)
    await expect(
      repository.readAfter({
        scope: { kind: 'stream' },
        families: ['agent_run'],
        order: 'oldest',
        afterSequence: '0',
        highWatermark: '10',
        limit: 201,
        occurredFrom: null,
        occurredTo: null,
      })
    ).rejects.toThrow('between 1 and 200')
  })

  it('uses a descending boundary for latest-first repository pages', async () => {
    const query = vi.fn().mockResolvedValue({ rows: [], rowCount: 0 })
    const repository = new PostgresGovernedEventReadRepository({ query } as DbClient)

    await repository.readAfter({
      scope: { kind: 'stream' },
      families: ['infrastructure_telemetry'],
      order: 'latest',
      afterSequence: '11',
      highWatermark: '10',
      limit: 25,
      occurredFrom: null,
      occurredTo: null,
    })

    const sql = String(query.mock.calls[0]?.[0])
    expect(sql).toContain('s.stream_sequence < $1::bigint')
    expect(sql).toContain('ORDER BY s.stream_sequence DESC')
    expect(sql).not.toContain('s.stream_sequence > $1::bigint')
  })
})

describe('GovernedEventReadService', () => {
  it('captures one high watermark, applies family field policy, and emits an opaque cursor', async () => {
    const repository: GovernedEventReadRepositoryV1 = {
      captureHighWatermark: vi.fn().mockResolvedValue('10'),
      readAfter: vi.fn().mockResolvedValue([ROW]),
    }
    const service = new GovernedEventReadService(repository)

    const first = await service.read({ scope: { kind: 'stream' }, limit: 1 })

    expect(first.events[0].payload).toEqual({ summary: 'run started' })
    expect(first.nextCursor).toBeTruthy()
    expect(first.nextCursor).not.toContain('run-1')
    expect(first.capturedHighWatermark).toBe('10')

    await service.read({ scope: { kind: 'stream' }, limit: 1, cursor: first.nextCursor! })
    expect(repository.captureHighWatermark).toHaveBeenCalledTimes(1)
    expect(repository.readAfter).toHaveBeenLastCalledWith(
      expect.objectContaining({
        afterSequence: '5',
        highWatermark: '10',
        limit: 1,
        order: 'oldest',
      })
    )
    expect(readDurationObserve).toHaveBeenCalledWith({ family: 'mixed' }, expect.any(Number))
  })

  it('records one bounded family label when a read selects one family', async () => {
    const repository: GovernedEventReadRepositoryV1 = {
      captureHighWatermark: vi.fn().mockResolvedValue('10'),
      readAfter: vi.fn().mockResolvedValue([ROW]),
    }
    const service = new GovernedEventReadService(repository)

    await service.read({ scope: { kind: 'stream' }, families: ['agent_run'] })

    expect(readDurationObserve).toHaveBeenLastCalledWith(
      { family: 'agent_run' },
      expect.any(Number)
    )
  })

  it('reads newest pages backward from the captured high watermark', async () => {
    const repository: GovernedEventReadRepositoryV1 = {
      captureHighWatermark: vi.fn().mockResolvedValue('10'),
      readAfter: vi.fn().mockResolvedValue([
        { ...ROW, streamSequence: '10', eventId: 'event-10' },
        { ...ROW, streamSequence: '9', eventId: 'event-9' },
      ]),
    }
    const service = new GovernedEventReadService(repository)

    const page = await service.read({
      scope: { kind: 'stream' },
      families: ['infrastructure_telemetry'],
      order: 'latest',
      limit: 2,
    })

    expect(repository.readAfter).toHaveBeenCalledWith(
      expect.objectContaining({ afterSequence: '11', highWatermark: '10', order: 'latest' })
    )
    expect(page.events.map(event => event.streamSequence)).toEqual(['10', '9'])
    expect(page.nextCursor).toBeTruthy()
  })

  it('releases only the operator-safe infrastructure capacity evidence', async () => {
    const infrastructureRow: GovernedEventReadRowV1 = {
      ...ROW,
      eventFamily: 'infrastructure_telemetry',
      eventType: 'usage_sample',
      targetRef: 'control-plane/control-api',
      payload: {
        ready_replicas: 2,
        desired_replicas: 3,
        cpu_request_cores: 1,
        cpu_usage_core_seconds: 75,
        interval_start: '2026-07-10T09:00:00.000Z',
        interval_end: '2026-07-10T09:01:00.000Z',
        summary: 'capacity sample',
        raw_node_name: 'must-not-be-released',
      },
    }
    const repository: GovernedEventReadRepositoryV1 = {
      captureHighWatermark: vi.fn().mockResolvedValue('10'),
      readAfter: vi.fn().mockResolvedValue([infrastructureRow]),
    }
    const service = new GovernedEventReadService(repository)

    const page = await service.read({
      scope: { kind: 'stream' },
      families: ['infrastructure_telemetry'],
    })

    expect(page.events[0]?.payload).toEqual({
      ready_replicas: 2,
      desired_replicas: 3,
      cpu_request_cores: 1,
      cpu_usage_core_seconds: 75,
      interval_start: '2026-07-10T09:00:00.000Z',
      interval_end: '2026-07-10T09:01:00.000Z',
      summary: 'capacity sample',
    })
  })

  it('separates a recreated workload from its predecessor by releasing the Kubernetes uid', async () => {
    // A Host deleted and recreated under the same name shares namespace/name,
    // so `workload_ref` cannot tell the two objects apart. The uid is the only
    // field that can, and the list payload has to carry it for a workload-scoped
    // read to be partitionable without one detail fetch per row.
    const predecessor: GovernedEventReadRowV1 = {
      ...ROW,
      streamSequence: '9',
      eventFamily: 'infrastructure_telemetry',
      eventType: 'health_transition',
      targetRef: 'clerum-hosts/analytics',
      payload: {
        workload_ref: 'clerum-hosts/analytics',
        kubernetes_kind: 'Host',
        kubernetes_name: 'analytics',
        kubernetes_uid: '11111111-1111-4111-8111-111111111111',
        state: 'degraded',
        raw_node_name: 'must-not-be-released',
      },
    }
    const successor: GovernedEventReadRowV1 = {
      ...ROW,
      streamSequence: '10',
      eventFamily: 'infrastructure_telemetry',
      eventType: 'reconcile_outcome',
      targetRef: 'clerum-hosts/analytics',
      payload: {
        workload_ref: 'clerum-hosts/analytics',
        kubernetes_kind: 'Host',
        kubernetes_name: 'analytics',
        kubernetes_uid: '22222222-2222-4222-8222-222222222222',
        state: 'ready',
        raw_node_name: 'must-not-be-released',
      },
    }
    const repository: GovernedEventReadRepositoryV1 = {
      captureHighWatermark: vi.fn().mockResolvedValue('10'),
      readAfter: vi.fn().mockResolvedValue([predecessor, successor]),
    }
    const service = new GovernedEventReadService(repository)

    const page = await service.read({
      scope: { kind: 'stream' },
      families: ['infrastructure_telemetry'],
    })

    expect(page.events[0]?.payload).toEqual({
      workload_ref: 'clerum-hosts/analytics',
      kubernetes_kind: 'Host',
      kubernetes_name: 'analytics',
      kubernetes_uid: '11111111-1111-4111-8111-111111111111',
      state: 'degraded',
    })
    expect(page.events[1]?.payload).toEqual({
      workload_ref: 'clerum-hosts/analytics',
      kubernetes_kind: 'Host',
      kubernetes_name: 'analytics',
      kubernetes_uid: '22222222-2222-4222-8222-222222222222',
      state: 'ready',
    })
    const uids = page.events.map(event => event.payload.kubernetes_uid)
    expect(new Set(uids).size).toBe(2)
  })

  it('releases the safe permission classification needed by the administrative list', async () => {
    const administrativeRow: GovernedEventReadRowV1 = {
      ...ROW,
      eventFamily: 'administrative',
      eventType: 'permission_grant',
      targetType: 'permission',
      targetRef: 'agent:agent-1',
      payload: {
        resource_class: 'agent_access',
        status: 'granted',
        count: 1,
        raw_permission: 'must-not-be-released',
      },
    }
    const repository: GovernedEventReadRepositoryV1 = {
      captureHighWatermark: vi.fn().mockResolvedValue('10'),
      readAfter: vi.fn().mockResolvedValue([administrativeRow]),
    }
    const service = new GovernedEventReadService(repository)

    const page = await service.read({
      scope: { kind: 'stream' },
      families: ['administrative'],
    })

    expect(page.events[0]?.payload).toEqual({
      resource_class: 'agent_access',
      status: 'granted',
      count: 1,
    })
  })

  it('rejects invalid or query-mismatched cursors as typed bad requests', async () => {
    const repository: GovernedEventReadRepositoryV1 = {
      captureHighWatermark: vi.fn().mockResolvedValue('10'),
      readAfter: vi.fn().mockResolvedValue([ROW]),
    }
    const service = new GovernedEventReadService(repository)

    await expect(
      service.read({ scope: { kind: 'stream' }, cursor: 'not-base64-json' })
    ).rejects.toBeInstanceOf(GovernedReadInvalidQueryError)

    const first = await service.read({ scope: { kind: 'stream' }, limit: 1 })
    await expect(
      service.read({
        scope: { kind: 'stream' },
        families: ['agent_run'],
        cursor: first.nextCursor!,
      })
    ).rejects.toMatchObject({
      code: 'governed_read_invalid_query',
      status: 400,
      message: 'governed event cursor does not belong to this query',
    })
  })

  it('rejects a run-id lookup without workflow or host relationship scope', async () => {
    const repository: GovernedEventReadRepositoryV1 = {
      captureHighWatermark: vi.fn(),
      readAfter: vi.fn(),
    }
    const service = new GovernedEventReadService(repository)

    await expect(
      service.read({ scope: { kind: 'run_id', runId: 'run-1' } } as never)
    ).rejects.toThrow('runId cannot be queried without')
    expect(repository.captureHighWatermark).not.toHaveBeenCalled()
  })

  it('fails closed when hydrated workflow rows do not match the scoped recipe', async () => {
    const repository: GovernedEventReadRepositoryV1 = {
      captureHighWatermark: vi.fn().mockResolvedValue('10'),
      readAfter: vi.fn().mockResolvedValue([{ ...ROW, recipeName: 'other-recipe' }]),
    }
    const service = new GovernedEventReadService(repository)

    await expect(
      service.read({
        scope: {
          kind: 'workflow_run',
          runId: 'run-1',
          recipeNamespace: 'sandbox-recipes',
          recipeName: 'chatllm',
        },
      })
    ).rejects.toBeInstanceOf(GovernedReadScopeMismatchError)
  })

  it('rejects pages above 200 and time windows above 31 days before repository access', async () => {
    const repository: GovernedEventReadRepositoryV1 = {
      captureHighWatermark: vi.fn(),
      readAfter: vi.fn(),
    }
    const service = new GovernedEventReadService(repository)

    await expect(service.read({ scope: { kind: 'stream' }, limit: 201 })).rejects.toThrow(
      'between 1 and 200'
    )
    await expect(
      service.read({
        scope: { kind: 'stream' },
        occurredFrom: '2026-01-01T00:00:00.000Z',
        occurredTo: '2026-03-01T00:00:00.000Z',
      })
    ).rejects.toThrow('at most 31 days')
    expect(repository.captureHighWatermark).not.toHaveBeenCalled()
  })
})