Unify error structure across WorkflowInstance and TaskExecution

[ricardozanini]

Summary

Unifies error handling across WorkflowInstance and TaskExecution to align with Serverless Workflow 1.0.0 Error specification (RFC 9457 Problem Details).

Previously, TaskExecution had a simple errorMessage string field while WorkflowInstance had a complex Error object. This PR makes both use the same structured Error type with five fields: type, title, detail, status, and instance.

Changes

Database Layer

• Added 5 error columns to task_instances table: error_type, error_title, error_detail, error_status, error_instance
• Updated PostgreSQL trigger normalize_task_event() to extract error fields from JSONB events

Domain Model

• Renamed WorkflowInstanceError → Error (reusable by both types)
• Added Error field to TaskExecution (replaced errorMessage string)

Storage Layer (JPA)

• Renamed WorkflowInstanceErrorEntity → ErrorEntity (embeddable)
• Added ErrorEntity field to TaskInstanceEntity
• Renamed WorkflowInstanceErrorEntityMapper → ErrorEntityMapper
• Updated both entity mappers to use ErrorEntityMapper

GraphQL API

• Created IntFilter for integer field filtering
• Created ErrorFilter for nested error structure filtering
• Updated TaskExecutionFilter: replaced errorMessage with error field
• Added error field to WorkflowInstanceFilter
• Updated FilterConverter to handle error filtering with all operators

Testing

• Added 3 new integration tests:
  • testWorkflowInstanceWithErrorStructure() - verifies error object structure
  • testTaskExecutionWithErrorStructure() - verifies task error structure
  • testErrorFiltering() - verifies filtering by error fields
• All 23 integration tests passing
• Full e2e verification in KIND cluster completed

Documentation

• Updated CLAUDE.md with unified error handling guidance
• Added e2e verification documentation
• Added quick start guides for KIND deployment

Breaking Changes

⚠️ GraphQL Schema Change

The TaskExecution type has changed:

• Removed: errorMessage: String
• Added: error: Error (with fields: type, title, detail, status, instance)

Existing clients querying errorMessage will need to update their queries to use the new nested error structure.

Before:

query {
  getTaskExecutions {
    id
    errorMessage
  }
}

After:

query {
  getTaskExecutions {
    id
    error {
      type
      title
      detail
      status
      instance
    }
  }
}

Verification

✅ Clean build: mvn clean install
✅ All tests pass: 23/23 tests (0 failures)
✅ E2E verification in KIND cluster
✅ GraphQL error queries working
✅ Error filtering working (all operators)
✅ Database triggers extracting error fields

Test Results

• Integration Tests: 23/23 passing
• E2E Tests: Full deployment verified in KIND
• GraphQL Queries: Error structure queries working
• Error Filtering: Tested with eq, gte, and other operators
• Database: Triggers correctly normalize error events

Related Issues

Closes #9 (if applicable - update issue number)

Checklist

• Code follows project conventions (CLAUDE.md)
• Tests added and passing
• Documentation updated
• E2E verification completed
• No security vulnerabilities introduced
• Breaking changes documented

Screenshots/Examples

GraphQL Query with Error Structure:

query {
  getWorkflowInstance(id: "test-faulted-wf-001") {
    id
    status
    error {
      type
      title
      detail
      status
      instance
    }
  }
}

Error Filtering:

query {
  getWorkflowInstances(
    filter: {
      error: {
        status: { eq: 500 }
        type: { like: "communication" }
      }
    }
  ) {
    id
    status
    error {
      type
      status
    }
  }
}

🤖 Generated with Claude Code