feat(api): Track 3.4 — additive publicStatus field on every stage

[slittycode]

Fourth and final piece of Track 3 from the merged external-repo review. Closes Track 3.

What this adds

Every stage object in the run snapshot (stages.measurement, stages.pitchNoteTranslation, stages.interpretation) now carries a publicStatus field alongside the existing status field. Additive — nothing removed, nothing renamed.

"stages": {
  "measurement": {
    "status": "blocked",      // 8-state internal vocabulary, unchanged
    "publicStatus": "queued"  // 5-state collapse, new
    // ...
  },
  "interpretation": {
    "status": "not_requested",
    "publicStatus": null      // not in pipeline
    // ...
  }
}

Mapping

Internal status (8)	Public publicStatus (5+null)	Why
queued	"queued"	1:1
running	"running"	1:1
blocked	"queued"	Transient internal scheduling — client sees it as queued
ready	"queued"	Scheduled but not yet running — client sees it as queued
completed	"completed"	1:1
failed	"failed"	1:1
interrupted	"interrupted"	1:1
not_requested	null	Stage not in pipeline; distinguishes "you didn't ask" from "queued"

null is explicit in JSON (not key omission) so clients in strongly-typed languages can read one shape without branching on key presence.

Why additive instead of contract-changing

This was the explicit user decision when scoping the piece. The contract-changing alternative (replace 8 internal states with 5 in the response) would have:

• Required UI code updates (the UI already handles 8 states)
• Risked breaking any other consumer that depended on the broader vocabulary
• Required a schema v2 bump per docs/adr/0001-phase1-json-schema-v1.md's compatibility policy

The additive choice keeps internal scheduling vocabulary stable (useful for tooling, debugging, internal UI) while exposing a tidier external surface for new consumers. Trade-off acknowledged in the commit message: it doubles the status fields forever; collapsing to one would be a v2-era task.

Files

File	Role
apps/backend/stage_status.py (new)	Pure module with the canonical 8→5 mapping table, to_public_status() helper, and PUBLIC_STATUS_VALUES exported set.
apps/backend/server_phase1.py	_normalize_run_snapshot now annotates each stage with publicStatus via a new _annotate_public_status helper. Original status preserved.
apps/backend/tests/test_stage_status.py (new, 16 tests)	Pins every cell of the mapping plus a completeness check that fires if the set of internal states drifts without explicit mapping update.
apps/backend/tests/test_server.py (+1 test)	Integration test asserting publicStatus appears on all three stages of a fresh run, with "queued" for measurement and null for the two not_requested stages.
apps/ui/src/types/backend.ts	New PublicStageStatus type (the 5-value union). publicStatus: PublicStageStatus | null added to all three top-level stage interfaces.
apps/ui/src/services/analysisRunsClient.ts	New parsePublicStageStatus helper (lenient — accepts null/missing for legacy compat). Threaded into the three stage parsers.
docs/adr/0001-phase1-json-schema-v1.md	Documents the additive field, mapping table, and rationale.

Verification

• 16 backend test_stage_status tests pass locally:

  $ python -m unittest tests.test_stage_status
  ................
  Ran 16 tests in 0.001s
  OK
  

• UI npm run lint: clean. npm run test:unit: 398/398 (unchanged from main).
• 1 new integration test in test_server.py exercises _normalize_run_snapshot end-to-end via get_analysis_run.

What this PR does NOT do

• Does NOT change the existing status field on any stage. Same 8-state vocabulary, same values.
• Does NOT add publicStatus to attempt summaries (attemptsSummary[] inside pitch-note and interpretation stages). Those are debug/audit views, not the canonical stage status.
• Does NOT make existing UI code use publicStatus. Adding the field is the API change; consuming it is a separate decision per surface. The UI continues to use status everywhere.
• Does NOT remove not_requested from anywhere. It's still in the internal vocabulary; publicStatus just exposes null for that case.

Track 3 closeout

This is the last piece. Full Track 3 sequencing as shipped:

• ✅ Piece 1: URL ingestion (feat(api): Track 3.1 — URL-mode ingestion for POST /api/analysis-runs #36)
• ✅ Piece 2: X-Admin-Key on DELETE (feat(api): Track 3.2 — X-Admin-Key gates cross-user DELETE on /api/analysis-runs #37)
• ✅ Piece 3: GET …/source-audio re-serve (feat(api): Track 3.3 — GET /api/analysis-runs/{run_id}/source-audio #40)
• ▶ Piece 4: this PR — additive publicStatus

After this lands, all four Track 3 pieces from the external-repo review are on main.

https://claude.ai/code/session_01Uh2eNT1oqjixcox8UX3BTg

---

Generated by Claude Code

[slittycode]

Verdict: APPROVE (posted as COMMENT — can't self-approve)

Summary

Adds an additive publicStatus field (5-value collapse) alongside the existing internal status field (8-value) on every stage in the run snapshot. Nothing removed, nothing renamed, no measurement values touched. 16/16 unit tests pass locally; the new integration test in test_server.py is sound but requires venv/FastAPI to run (CI handles it). This is a clean infra change.

Findings

No blocking or should-fix findings.

Worth considering (not blocking):

_normalize_run_snapshot relies on _annotate_public_status returning shallow-copied stage dicts so that measurement["result"] = _build_phase1(raw_result) mutates the copy already installed into snapshot["stages"]. The comment in the code calls this out ("Reuse the dict we already copied"). Both functions are in the same module and the comment is honest about the dependency — fine as-is.

The removal of the old early-return pattern (if measurement or raw_result not a dict, return snapshot unchanged) in favor of conditionals is an improvement: publicStatus is now annotated on all stages even when measurement hasn't populated a result yet, which is correct for queued state. This is not a bug — noting the semantics changed intentionally.

Test results

test_stage_status: 16/16 pass. The completeness guard (test_internal_states_unchanged, test_all_non_null_mappings_are_public_values) is a particularly good call — it will catch silent mapping drift if a new internal state gets added without a deliberate public-side decision.

test_server integration test: structurally correct, can't execute locally (no venv), normal.

Frontend lint: pre-existing type errors unrelated to this PR. The TranscriptionDetail errors at line 621–625 are not in this diff; the infrastructure errors (React, Vite types) are missing node_modules.

Phase boundary check

Clean. analyze.py and all analyze_*.py DSP modules untouched. _build_phase1 called identically to before. Phase1Result in types/measurement.ts not touched. The change is entirely in the HTTP normalization layer (_normalize_run_snapshot) and the run snapshot types — the right place for it.

---

Generated by Claude Code