feat: content-hash conversation identity (server-only hashing)

[basilebong]

Summary

Conversation identity moves to a server-computed content hash of the canonical turn JSON (with sha256 of each RecordedAudio's WAV bytes substituted in). The dev sets a free-form name; renaming doesn't change identity, editing a turn or a WAV does. The SDK does zero hashing — no cross-language parity fixture to keep in sync.

This branch also carries main's #65 (server-as-analyzer: stereo WAV upload + VAD + turn derivation + SSE progress). The two surfaces are independent.

API request flow

sequenceDiagram
    autonumber
    participant SDK as Python SDK
    participant Xray as xray server
    participant Agent as Voice agent
    participant Worker as bunqueue worker

    SDK->>Xray: POST /v1/conversations multipart spec + audio parts
    Note over Xray: hash = sha256(canonical turns), upsert by hash
    Xray-->>SDK: 200 hash

    SDK->>Xray: POST /v1/replays JSON conversation_hash
    Xray-->>SDK: 201 id, lifecycle_state pending

    SDK->>Agent: runtime.run(conversation)
    Agent->>Xray: POST /v1/otlp/v1/traces xray.replay.id
    Agent-->>SDK: AgentResponses

    SDK->>Xray: POST /v1/replays/:id/audio stereo WAV
    SDK->>Xray: POST /v1/replays/:id/analyze
    Xray->>Worker: enqueue
    Xray-->>SDK: 202 job_id

    SDK->>Xray: GET /v1/replays/:id/events SSE
    Worker->>Xray: VAD, speech_segments, replay_turns
    Xray-->>SDK: state / progress / completed

    SDK->>Xray: GET /v1/replays/:id
    Xray-->>SDK: turns + tool_calls + model_usage + spans

    SDK->>Xray: PATCH /v1/replays/:id lifecycle_state
    Note over SDK,Xray: 409 tolerated — server-owns-lifecycle
    Xray-->>SDK: 200

Loading

What changed for callers

• POST /v1/conversations — multipart/form-data: spec JSON ({name, turns}, ≤256 KB measured in UTF-8 bytes) plus one file part per RecordedAudio turn, keyed by the turn's declared upload_key (any [A-Za-z0-9_.-] string, ≤50 MB each). Server hashes, returns the full conversation row ({hash, name, created_at, last_run_at, turns}).
• POST /v1/replays — JSON {conversation_hash, run_config?}, returns the replay row at lifecycle_state: "pending".
• conversations PK is hash; replays.conversation_hash FKs into it.
• Audio paths: recorded conversation audio at <XRAY_AUDIO_ROOT>/recorded/<sha256>.wav (deduplicated across conversations, written via tmp + rename(2) so concurrent identical uploads never expose a partial file); full-replay stereo mixdown at <XRAY_AUDIO_ROOT>/<replay_id>/replay.wav.
• Python SDK: Conversation(name=..., turns=...); xray.run(...) returns RunResult.conversation_hash. Existing data wiped (pre-1.0).
• SDK resilience: a dev-authored judge raising no longer strands the replay row — orchestrator logs and proceeds to PATCH. The final PATCH tolerates 409, accepting the server's lifecycle when SSE wait drops before the terminal event.

Atomicity

Audio files are written content-addressed (recorded/<sha256>.wav) before the conversation upsert — a partial write + failed upsert leaves a harmless orphan that the next submission finds in place. Typed errors at every boundary: RecordedAudioUploadKeyError (missing/unreferenced upload_key), ConversationNotFoundError (404), ReplayLifecycleTransitionError (409 on terminal-state mutations).

Verify

pnpm typecheck && pnpm check && pnpm test     # 262 pass
cd sdk/python && uv run pyright && uv run pytest  # 42 pass

[basilebong]

This change is part of the following stack:

• feat: content-hash conversation identity (server-only hashing) #64 ◀
  • fix: port seed + client SPA to content-hash server schema #69

_{Change managed by git-spice.}

[LukasPoque]

Fixed all review findings and committed them, @basilebong maybe you can make a review and then its fine to merge IMHO