[Sprint 1 | API | d3v07] Change lifecycle routes: acknowledge, snooze, resolve

[d3v07]

Context

ChangeReport detail already has the key operator actions in the handoff: acknowledge, snooze, and resolve. This issue owns only the change lifecycle routes and persistence semantics so it can ship independently from pipeline, billing, and UI work.

Acceptance Criteria

• Implement POST /v1/changes/:id/acknowledge exactly to the API contract
• Implement POST /v1/changes/:id/snooze with typed until handling and validation
• Implement POST /v1/changes/:id/resolve with typed resolution payload
• Persist state changes using the append-only change_reports model from the data handoff
• Use FINAL or equivalent correctness handling for reads where ClickHouse replacement semantics require it
• Emit change.stateChanged over SSE when state changes
• Return the standard Redline error envelope for 401, 404, 409, and 422 cases
• Tests cover success, missing change, invalid payload, stale/conflicting state, and SSE emission

Files to Touch

• apps/api/src/routes/changes.ts
• apps/api/src/db/changeReports.ts
• apps/api/src/stream/events.ts
• apps/api/src/server.ts
• packages/shared/src/types.ts
• packages/shared/src/schemas.ts
• tests/api/changes.lifecycle.test.ts

Prompt

/plan
Implement the Redline change lifecycle slice from the handoff. Focus only on acknowledge, snooze, and resolve routes; append-only persistence; conflict handling; and the `change.stateChanged` SSE event. Branch must stand alone from other issue branches and must not wait for UI, Stripe, Slack, or agent pipeline work.

Test Plan

1. Run the API route tests for acknowledge, snooze, and resolve
2. Verify invalid payloads return 422 with the standard error envelope
3. Verify stale/conflicting transitions return 409
4. Verify the persisted ChangeReport reads back with updated state
5. Verify one change.stateChanged event is emitted per successful transition

Redline Handoff Adherence

• API shape from handoff/API.html
• Persistence shape from handoff/Data Model.html
• No citation, no claim remains enforced on ChangeReport reads
• This issue has no dependency on other Sprint 1 issues

Per-Issue PR Workflow (REQUIRED)

1. Branch from main: d3v07/change-state-transitions
2. Implement without waiting on any other issue branch
3. PR to main: Closes #1
4. Review pass for route validation, persistence correctness, and SSE behavior
5. Address comments
6. Leave final merge to main for the owner

Definition of Done

• Branch pushed: d3v07/change-state-transitions
• PR opened against main
• Route tests pass
• SSE event verified
• No secrets or local env values committed