[Sprint 1 | API | d3v07] Org-scoped SSE stream contract

[d3v07]

Context

The product is always-on: the UI should see scan progress, detected changes, action delivery, state changes, and entitlement changes over one EventSource stream. This issue owns only the /v1/stream contract and server-side event fan-out.

Acceptance Criteria

• Implement /v1/stream as a long-lived EventSource endpoint
• Authenticate via query-param token because EventSource cannot send custom headers
• Scope all events to the resolved org
• Send :heartbeat keepalives every 15 seconds
• Support reconnect behavior with stable event ids where the server has enough recent event history
• Emit documented event shapes for scheduler.tick, run.stage, change.detected, action.delivered, change.stateChanged, and org.entitlements.changed
• Add a small in-memory event broker suitable for hackathon demo runtime
• Tests cover auth failure, heartbeat, org scoping, event shape, and reconnect behavior

Files to Touch

• apps/api/src/routes/stream.ts
• apps/api/src/stream/broker.ts
• apps/api/src/stream/events.ts
• apps/api/src/auth.ts
• apps/api/src/server.ts
• packages/shared/src/types.ts
• packages/shared/src/schemas.ts
• tests/api/stream.test.ts

Prompt

/plan
Implement the Redline `/v1/stream` SSE contract from the handoff. Build query-param auth, org-scoped EventSource fan-out, heartbeat keepalives, documented event shapes, and reconnect support. This branch must stand alone from other issue branches.

Test Plan

1. Run stream route tests
2. Verify unauthenticated requests fail with the standard error envelope
3. Verify connected clients receive heartbeat comments every 15 seconds
4. Verify events only deliver to clients in the same org
5. Verify each documented event kind serializes to the expected payload shape

Redline Handoff Adherence

• SSE contract from handoff/API.html
• Scheduler cadence from handoff/Runbook.html
• Always-on product behavior from handoff/Product Decisions.html
• This issue has no dependency on Add Vendor, Stripe, evidence brief, Slack, or lifecycle routes

Per-Issue PR Workflow (REQUIRED)

1. Branch from main: d3v07/sse-stream-contract
2. Implement without waiting on any other issue branch
3. PR to main: Closes this issue
4. Review pass for auth, org scoping, and event shape stability
5. Address comments
6. Leave final merge to main for the owner

Definition of Done

• Branch pushed: d3v07/sse-stream-contract
• PR opened against main
• Stream tests pass
• Heartbeat and org scoping verified
• No secrets or local env values committed