feat(backend): core runtime — scaffold, watchdog, orchestrator, SSE, push, intake, 3 tools, loader, demo endpoints

[simerugby]

What (the Phase-1 backend lane — closes #13 #14 #15 #16 #17 #18 #19 #20 #21 #22 #23)

The full backend runtime, built on the frozen contracts (#66, #68) and the seed shape contract (#64).

Issue	Delivered
BE.1	App factory, /health, env-only settings, python backend/run.py
BE.2	Watchdog: deterministic ingest→normalize→threshold→debounce, fully data-driven from alarm_dictionary.csv (zero hardcoded thresholds, zero LLM), event-time debounce so replays behave identically
BE.3	Orchestrator state machine incl. the pivot loop; agents pluggable via the frozen contracts.Agent protocol; no diagnosis logic in /backend — dummy agents return canned shapes, real agents swap in by registry name (handoff notes in backend/README.md)
BE.4	GET /api/stream: SSE identical in wire semantics to contracts/mock_stream/replay.py — frontend swap = base-URL flip. Heartbeat, Last-Event-ID resume, concurrent clients
BE.5	Push payload contract-validated at runtime; simctl primary (payload file IS the simctl input), APNs flag-gated (INT.7), no Apple dependency
BE.6	POST /api/validation: validated against the frozen schema (422 with precise errors), idempotent on client_event_id, 409 on wrong state/incident
BE.7-9	Cost/Inventory/Dispatch: deterministic over seeds; DRAFT tool signatures from #66 implemented exactly as drafted (backend hereby approves them); no-stock + no-crew conflict paths flagged
BE.10	Loader per data/schema.md with FK validation + loud SeedErrors; sample-row fallback seeds until DEMO.2 lands real volumes
BE.11	POST /api/demo/inject-fault (drives the REAL watchdog path, any alarm family) + reset < 5 s

Verification

• 23 tests green (cd backend && pytest): watchdog threshold/debounce/no-duplicate, every state transition incl. pivot loop, intake idempotency/409/422, tool determinism + conflict cases, seed FK errors, agent-timeout graceful handling.
• Every envelope the live runtime emits is validated against contracts/events.schema.json in the E2E tests — backend cannot drift from what web/iOS build against.
• SSE tested over a real uvicorn server (2 concurrent clients + header-based resume).
• Live curl run of both demo scenarios: inject → stream → validate → report → reset, and the pivot: contradicting measurement → phase_started {cause: pivot} → re-diagnosis → single push → outcome: downgraded.
• Rebased on latest main (post [AGV.2+P0.5] VultronRetriever client + corpus ingestion + tests #69/[AGA.1] Validation agent (confirm/pivot) #70/[AGV.1+P0.4+P0.3] Vultr inference client + pinned model + env hygiene #71); trial merge clean.

For reviewers

• @vgtray / @aminssutt: backend/README.md § Plugging real agents documents the registry handoff — your agents replace the dummies with zero backend changes. aminssutt's Validation agent ([AGA.1] Validation agent (confirm/pivot) #70) should slot straight into the validation registry key.
• The demo push file lands in $ARC_PUSH_OUT_DIR — @daniwavy5032 can drive the iOS simulator from it with the documented one-liner.

🤖 Generated with Claude Code