Migrate from jsonapi-serializer to Alba gem

## Overview Replace the jsonapi-serializer gem with the Alba gem for JSON serialization across the Rails API. Alba is a faster, more lightweight JSON serializer for Ruby with better performance characteristics and a simpler API. ## IMPORTANT: Breaking API Change **This migration involves a BREAKING CHANGE to the API response format.** - The migration will **drop the JSON:API specification format** (https://jsonapi.org/) - The API will change from the complex JSON:API structure to simpler plain JSON - This is a **breaking change** for any API consumers expecting JSON:API format ### Current JSON:API Format (Example): ```json { "data": { "id": "1", "type": "tickets", "attributes": { "title": "Fix bug", "status": "backlog" }, "relationships": { "project": { "data": { "id": "2", "type": "projects" } } }, "links": { "self": "/api/v1/tickets/1" } } } ``` ### New Plain JSON Format (Example): ```json { "id": 1, "title": "Fix bug", "status": "backlog", "project": { "id": 2, "name": "My Project" } } ``` ### Impact: - All API consumers (MCP agents, frontend clients, external integrations) must be updated - Response parsing logic must change to expect plain JSON objects - The `data` wrapper, `type` field, and separated `attributes`/`relationships` will be removed - Nested relationships will be included directly in the response rather than as separate structures ### Consumers That Will Need Updates: - MCP agent implementations (tinker-worker, tinker-reviewer, tinker-orchestrator) - Any frontend consuming the API - External API integrations - API client tests expecting JSON:API format ## Current State - Gem: `jsonapi-serializer` (line 29 in /rails/Gemfile) - 7 serializer files in /rails/app/serializers/: - TicketSerializer (most complex, with relationships, computed attributes, links) - ProjectSerializer - AgentSerializer - CommentSerializer - CodeDiffSerializer - AgentMemorySerializer - ArtifactSerializer - API controllers use `render_jsonapi` and `render_jsonapi_collection` helper methods in BaseController ## Migration Scope This migration involves: 1. **Gem replacement**: Update Gemfile to use `alba` instead of `jsonapi-serializer` 2. **Serializer conversion**: Convert all 7 serializers from JSONAPI::Serializer format to Alba format 3. **Controller updates**: Modify BaseController helper methods (`render_jsonapi`, `render_jsonapi_collection`) for Alba serialization 4. **API contract change**: Response format changes from JSON:API spec to plain JSON 5. **Consumer updates**: Update all API consumers to handle plain JSON responses ## Key Differences to Address - Alba uses a different attribute definition syntax - Alba's relationship handling differs (has_many, belongs_to) - Conditional attributes require different approach - Link generation syntax is different in Alba - Collection serialization has different API - **Response structure is plain JSON, not JSON:API format** ## Dependencies - Test suite should be updated to verify Alba serialization produces plain JSON - All API consumers (MCP agents) must be updated to parse plain JSON - Consider adding API versioning if backward compatibility is needed ## Files to Modify - /rails/Gemfile - /rails/app/serializers/*.rb (7 files) - /rails/app/controllers/api/v1/base_controller.rb - MCP agent code consuming the API (separate project/tickets) ## Risk Assessment - **HIGH Risk**: Breaking API change will break all existing consumers - **Mitigation**: - Comprehensive test coverage before deploying - Coordinate deployment with API consumer updates - Consider feature flag or API versioning if gradual rollout needed - Document new response format clearly