Pieces API + records/dashboard/bins overhaul

[spencerhhubert]

Draft — stacked on spencer/hive-sync-from-sorthive-01 (its commits are excluded from this diff).

Overview

A clean, unified Pieces API that the records page, the recent-pieces dropdown, exports, and the websocket all draw from — replacing a read surface that had grown into four divergent paths (piece_records, the in-memory known-object LRU, piece_image_store, and a 10-item recent-objects blob). One piece shape, tiered payloads, lazy subresources. Plus the records/dashboard/bins UI work that rides on it. Net effect is smaller: old endpoints are deleted, not left in parallel.

Backend — unified read API

• server/routers/pieces.py (new):
  • GET /api/pieces — keyset cursor pagination (on the autoincrement id, since seen_at is nullable), filters (status, part_id, color_id, run_id, dead, date range), recent/oldest sort. Returns light PieceSummary rows (uuid, timestamps, classification, bin, price, has_images, preview_url) — no images, no metadata blob.
  • GET /api/pieces/{uuid} — tiered {origin, summary, detail, detail_available}: memory-first (full known-object detail) with disk fallback (durable summary), the same pattern the image store already uses. Memory hits do zero SQLite work — this endpoint is polled per active piece during sorting.
  • GET /api/pieces/{uuid}/images — unchanged, remains the lazy image subresource.
  • GET /api/pieces/export.csv — streamed CSV of the whole filtered set (keyset-chunked), not capped to a page.
  • GET /api/pieces/aggregates — cached chart series (pieces/day, status breakdown, unique parts over time, PPM/day, per-color, top parts, value/day).
  • overview / value / lifetime (+ lifetime/export.csv) relocated under /api/pieces.
• Deleted /api/records/* and /api/known-objects/{uuid}, plus the recent_known_objects blob and its websocket-connect replay. Clients refill from GET /api/pieces instead.
• piece_records gains a nullable brickognize_preview_url column (guarded ALTER) so summary rows carry a thumbnail without an image fetch.

Backend — performance & correctness

• Metric snapshots moved to their own local_metrics.sqlite (buffered flush, bounded retention). These per-second, write-only diagnostic rows had grown into millions and bloated the shared DB, slowing every query against it; the legacy tables drain and drop in the background at idle priority.
• Value stats cached — previously recomputed uncached on every request with a per-part price lookup (~1.2s); now a process-wide price cache + short-TTL memo brings warm requests to tens of ms.
• Lifetime best-hour PPM de-correlated from a per-bucket subquery to a single grouped query.
• Thread-safe price DB access — the shared read connection to the parts metadata DB was not safe for concurrent execute(); parallel lookups could error and cache bad results. Serialized with a lock; the price cache is also pre-warmed off the request path at startup.

Backend — classification status (Area 8)

• New failed ClassificationStatus for transport-error identifications (persisted, distributable so a failed piece discards rather than jamming the channel). Previously "failed to identify" was indistinguishable from a genuine classified outcome in some UI paths.

Frontend

• One client piece store (lib/pieces/) — REST summaries and live known_object websocket events reduce into a single per-machine Piece shape with one upsert reducer. The recent-pieces dropdown, the records list's live rows, and the tracked detail page all read it; the dropdown refills from GET /api/pieces instead of the removed websocket replay.
• Records page consumes the new API and is componentized (~370 lines, down from ~1040): merged History + Lifetime into one stat header, cursor pagination, live rows on page one, per-day table paginated by two-week blocks, backend CSV export buttons, and lazy hand-rolled SVG charts (no new dependency). Top cards load first; images and charts hydrate after.
• Tracked detail page gains the disk fallback (no longer 404s when the piece has aged out of memory).
• PieceStatusBadge — one shared badge replacing hand-rolled chips that had diverged across pages. The green "Classified" is now gated strictly on classification_status === 'classified'; a failed/unidentified piece can no longer read as classified anywhere (records, dropdown, tracked, bin modal). Fixes a dropdown lifecycle chip that showed green for any piece whose classification simply finished, success or not.
• Dashboard — removed the Bins card and the Logs tab; added per-view rotate 180° / nudge ±1° C-channel buttons in the three camera title bars (operator-clicked UI, wired to the existing move-degrees control with the correct gear ratio).
• Settings — the incident-handling block moved off the dashboard into its own component under the Models settings page.
• Bins page — grid cells now preview server-grouped items with a ×N quantity badge instead of duplicate thumbnails (matching the modal); per-section grouping within each layer, a client-side find-a-part search that highlights matching bins, and at-a-glance count/fill/category/recency on each card.

Notes

• Draft: intended for review while stacked on its parent branch; not yet exercised end-to-end against live hardware.
• events.ts carries a one-line failed union addition; a full codegen regen is deferred to its own change (the generator rewrites unrelated types).
• The metrics-DB split stops future growth but doesn't reclaim already-allocated pages; a manual VACUUM during downtime would shrink the file.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
sorter-v2-docs	Ready	Preview, Comment	Jul 3, 2026 2:58am
sorteros-setup	Ready	Preview, Comment	Jul 3, 2026 2:58am