Data Flow

Queue Messages

Each queue carries a specific message schema validated with Zod at both the producer and consumer.

errors-detected

Sent by LogTailer when a new (or reopened) error is detected:

{
  fingerprint: string,      // SHA-256 hex
  incidentId: string,       // ULID
  serviceName: string,
  triggerRoute: string,
  errorClass: "client_4xx" | "server_5xx" | "unhandled_exception",
  sampleEvent: ObservabilityEvent,
  occurrenceCount: number,
  firstSeen: string,        // ISO 8601
  lastSeen: string
}

triage-ready

Sent by TestGen after reproduction testing:

{
  incidentId: string,
  fingerprint: string,
  serviceName: string,
  repoUrl: string,
  testCaseR2Key: string,    // R2 path to test-case.ts
  testResultR2Key: string,  // R2 path to test-result.json
  reproductionConfirmed: boolean,
  sampleEvent: ObservabilityEvent
}

fix-ready

Sent by CodeTriage after root cause analysis:

{
  incidentId: string,
  fingerprint: string,
  serviceName: string,
  repoUrl: string,
  commitSha: string,
  testCaseR2Key: string,
  triageResult: {
    rootCauseFile: string,
    rootCauseLines: [number, number],
    rootCauseExplanation: string,
    fixStrategy: string,
    confidence: "high" | "medium" | "low",
    affectedFiles: string[]
  },
  githubIssueNumber: number
}

completed

Sent by FixAgent after PR creation:

{
  incidentId: string,
  fingerprint: string,
  serviceName: string,
  status: "resolved" | "wontfix" | "needs_human",
  githubPrNumber?: number,
  githubPrUrl?: string
}

Error Fingerprinting

The fingerprint algorithm normalizes dynamic values before hashing:

Pattern	Replacement
UUIDs (xxxxxxxx-xxxx-...)	{uuid}
ISO timestamps	{timestamp}
JWTs (eyJ...)	{token}
Email addresses	{email}
Numeric IDs (4+ digits)	{id}

The fingerprint input is: "{serviceName}|{normalizedMessage}|{triggerRoute}|{topFrames}"

This means two errors with different request IDs but the same root cause produce the same fingerprint.

R2 Artifact Layout

sentinel-artifacts/
  incidents/{incidentId}/
    test-case.ts              # Generated bun:test reproduction test
    test-result.json          # { reproductionConfirmed, generatedAt }
    sample-event.json         # Original observability event
    patch.diff                # Git diff of the fix (added by FixAgent)
    pr-body.md                # PR description markdown (added by FixAgent)

D1 Database Flow

Write Path

1. LogTailer → INSERT INTO incidents (new error detected)
2. Each agent → INSERT INTO agent_runs (audit trail)
3. LLM calls → INSERT INTO llm_calls (cost tracking)
4. TestGen/FixAgent → INSERT INTO artifacts (R2 references)
5. FixAgent → INSERT INTO github_artifacts (PR/issue references)

Read Path

1. LogTailer → SELECT FROM service_configs (which services to poll)
2. LogTailer → SELECT FROM incidents WHERE fingerprint = ? (dedup check)
3. Orchestrator → SELECT FROM incidents with filters (dashboard)
4. Orchestrator → SELECT FROM artifacts WHERE incident_id = ? (detail view)