feat(api): add HTTP REST API server with SSE streaming

[pocky]

Summary

• Add awf serve command that exposes the full AWF workflow engine over HTTP, enabling remote execution and monitoring without shelling out to the CLI
• Implement a complete REST API (/api/workflows, /api/executions, /api/history) with async workflow launch (202 Accepted + execution_id), lifecycle control (cancel, resume), and real-time Server-Sent Events streaming per execution
• Build the API layer as a proper hexagonal adapter (internal/interfaces/api/) using Huma v2 + chi v5, with auto-generated OpenAPI 3.1 spec and Swagger UI at /docs; arch-lint enforces the layer boundary (no infra imports)
• Fix concurrency safety in ExecutionContext by adding mutex-protected getters/setters required by the SSE streaming goroutines; document bridge shutdown sequence (httpSrv.Shutdown → sseWG.Wait)

Changes

API Layer (new interface adapter)

• internal/interfaces/api/server.go: HTTP server struct with Huma/chi wiring, graceful shutdown (30s drain), ReadHeaderTimeout anti-Slowloris, route registration
• internal/interfaces/api/server_test.go: Unit tests for server struct — route registration, graceful shutdown, API initialization
• internal/interfaces/api/bridge.go: Bridge adapter wrapping WorkflowService/ExecutionService; sync.Map tracks active executions; mirrors tui/bridge.go pattern
• internal/interfaces/api/handlers_executions.go: Handlers for workflow run, list/get/cancel/resume executions, SSE streaming endpoint
• internal/interfaces/api/handlers_history.go: Handlers for GET /api/history with filtering (workflow, status, since/until) and GET /api/history/stats
• internal/interfaces/api/handlers_history_test.go: Unit tests for history and stats handlers
• internal/interfaces/api/handlers_executions_test.go: Updated execution handler tests
• internal/interfaces/api/sse.go: SSE event types, constants, 200ms-polling stream loop, sync.WaitGroup-tracked goroutines, auto-close on terminal state
• internal/interfaces/api/sse_test.go: SSE event struct, constant, and streaming behavior tests
• internal/interfaces/api/doc.go: Architecture overview and component descriptions for the api package

CLI Command

• internal/interfaces/cli/serve.go: awf serve Cobra command with --host/--port flags, pack discoverer wiring, signal.NotifyContext shutdown, startup/shutdown log messages
• internal/interfaces/cli/serve_test.go: Unit tests for serve command flag parsing and defaults
• internal/interfaces/cli/root.go: Register serve subcommand

Domain & Application

• internal/domain/workflow/context.go: Add mutex-protected GetStartedAt, SetStartedAt, GetCompletedAt, SetCompletedAt getters/setters for concurrent SSE access
• internal/application/execution_service.go: Use new ExecutionContext setter methods; expose GetActiveExecutions for bridge polling

Configuration & Architecture

• .go-arch-lint.yml: Add interfaces-api component with huma and chi vendor entries; enforce layer isolation
• CLAUDE.md: Add architecture rules for mutex-protected state and server WaitGroup shutdown pattern; add test conventions for HTTP server unit tests and fixture organization

Documentation

• docs/user-guide/api.md: Complete HTTP API reference — all endpoints, request/response examples (Huma envelope format, RFC 7807 errors), SSE event types, cURL/JS/Python client examples, security considerations
• docs/user-guide/commands.md: Add awf serve command reference with flags
• docs/README.md: Link to new API user guide
• docs/ADR/README.md: Register ADR-015 (gRPC plugin transport) and ADR-016 (HTTP interface adapter with Huma + SSE)
• README.md: Add HTTP REST API feature bullet and awf serve command to the command table
• CHANGELOG.md: Document F097 in [Unreleased] section

Test Fixtures & Integration Tests

• tests/fixtures/api/api-simple-success.yaml: Minimal two-step workflow fixture for success path
• tests/fixtures/api/api-failing.yaml: Workflow fixture that fails for error-path coverage
• tests/fixtures/api/api-slow.yaml: Slow-running workflow fixture for SSE streaming tests
• tests/integration/api/functional_test.go: End-to-end functional tests — workflow discovery, async run, SSE streaming, cancel, history
• tests/integration/api/server_integration_test.go: Server lifecycle integration tests — startup, shutdown, route availability
• tests/integration/testhelpers/helpers.go: Shared test helper utilities extended for API test setup

Test plan

• make build succeeds and awf serve --help shows --host/--port flags
• Start awf serve, open http://localhost:2511/docs in a browser — Swagger UI loads and all routes are listed
• POST /api/workflows/<name>/run returns 202, then GET /api/executions/{id}/events streams step.started / step.completed / workflow.completed events and closes the connection
• make test-race passes with zero data races across the internal/interfaces/api/ package

Closes #349

---

Generated with awf commit workflow