Enforce the state-machine transition table in POST /api/streams/[id]/start (server-side)

[greatest0fallt1me]

Description

The backend start handler at app/api/streams/[id]/start/route.ts unconditionally flips any stream to active without consulting the authoritative transition table in app/lib/state-machine.ts. A stream that is already ended, withdrawn, or paused-but-already-active can be illegally restarted, corrupting the lifecycle invariant draft → active → paused → ended → withdrawn. This is a server-side state-machine correctness bug, not a UI concern.

Requirements and Context

• Route app/api/streams/[id]/start/route.ts must call transition(stream.status, "start") from app/lib/state-machine.ts and reject illegal transitions with 409 ILLEGAL_TRANSITION.
• Preserve idempotent start on an already-active stream (the transition table already models this).
• Keep the existing rate-limit and org-policy checks intact.
• Must be secure, tested, and documented
• Should be efficient and easy to review

Suggested Execution

1. Fork the repo and create a branch

   git checkout -b bug/start-state-machine-enforcement

2. Implement changes
   • app/api/streams/[id]/start/route.ts — replace the unconditional status mutation with a transition() call
   • app/lib/state-machine.ts — reuse, do not duplicate, the transition logic
   • Map ILLEGAL_TRANSITION to the shared { error: { code, message } } envelope with HTTP 409
3. Test and commit
   • npm test -- app/api/streams
   • Cover edge cases: start from draft, paused, ended, withdrawn, and a missing stream
   • Include test output and notes in the PR

Example commit message

fix: enforce state-machine transitions in stream start handler

Acceptance Criteria

• Starting an ended or withdrawn stream returns 409 ILLEGAL_TRANSITION
• Starting a draft/paused stream still succeeds and sets active
• start handler imports and uses transition() from app/lib/state-machine.ts
• Jest coverage for the start route ≥ 90%

Guidelines

• Minimum 90% test coverage; cover every illegal-transition branch
• Clear documentation and inline comments
• Timeframe: 96 hours

[Windowlight]

@Windowlight has applied to work on this issue as part of the Stellar Wave Program's 5th wave.

I’m interested in this issue and believe my experience with contracts, backend systems, and frontend implementation makes me a good fit. Happy to provide updates as I work through it. Thanks

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Windowlight to this issue.

[drips-wave]

Congratulations, @Windowlight! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 2, 2026.

🧑‍💻 @Windowlight: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊