feat(backend): add publish readiness contract and pricing diagnostics

add backend readiness contract for publish prechecks

add pricing diagnostics to explain publish-blocking conditions
make publish decisions more explicit and easier to debug for clients

backend/docs/smoke-regression.md

@@ -31,67 +31,35 @@ export SCHEME_ID="82086336d385427f9d56244f9e1dd772"
 - GET /api/v1/schemes/{scheme_id}/current -> 200
 - GET /api/v1/schemes/{scheme_id}/versions -> 200
 
-Validate:
-- scheme_id is stable
-- current version exists
-- version list contains current version
-- status and counts are consistent
-
 ## 3. Structure read model
 
 - GET /api/v1/schemes/{scheme_id}/current/sectors -> 200
 - GET /api/v1/schemes/{scheme_id}/current/groups -> 200
 - GET /api/v1/schemes/{scheme_id}/current/seats -> 200
 
-Validate:
-- total counts are non-negative
-- known sample scheme returns expected object lists
-- seats contain seat_id / sector_id / group_id contract where applicable
-
 ## 4. SVG / display pipeline
 
 - GET /api/v1/schemes/{scheme_id}/current/svg -> 200
 - GET /api/v1/schemes/{scheme_id}/current/svg/display -> 200
 - GET /api/v1/schemes/{scheme_id}/current/svg/display/meta -> 200
-- GET /api/v1/schemes/{scheme_id}/current/svg/display?mode=optimized -> 200 or explicit controlled failure
-- GET /api/v1/schemes/{scheme_id}/current/svg/display/meta?mode=optimized -> 200 or explicit controlled failure
 
-Validate:
-- response content type for svg endpoints is image/svg+xml
-- meta returns scheme_id, scheme_version_id, view_box, width, height
-- no 500 on passthrough mode
-- unsupported mode returns 422
-
-## 5. Pricing read / write contract
+## 5. Pricing read model
 
 - GET /api/v1/schemes/{scheme_id}/pricing -> 200
+- GET /api/v1/schemes/{scheme_id}/pricing/coverage -> 200
+- GET /api/v1/schemes/{scheme_id}/pricing/unpriced-seats -> 200
+- GET /api/v1/schemes/{scheme_id}/pricing/explain/{seat_id} -> 200
 - GET /api/v1/schemes/{scheme_id}/current/seats/{seat_id}/price -> 200 for priced seat
-- GET /api/v1/schemes/{scheme_id}/test/seats/{seat_id} -> 200 for known seat
-- POST /api/v1/schemes/{scheme_id}/pricing/categories?expected_scheme_version_id={draft_version_id} -> 200 for valid draft
-- POST /api/v1/schemes/{scheme_id}/pricing/categories?expected_scheme_version_id=deadbeef... -> 409 for stale draft
+- GET /api/v1/schemes/{scheme_id}/test/seats/{seat_id} -> 200 for known priced and unpriced seats
 
-Validate:
-- pricing bundle contains categories and rules arrays
-- effective seat price resolves according to domain priority
-- test seat preview explains selectable / has_price state and returns reason_code / reason_message
-- pricing write responses are stable and typed
-- stale pricing mutation returns `detail.code = stale_draft_version`
+## 6. Draft publish / readiness
 
-## 6. Draft publish preview
-
-- GET /api/v1/schemes/{scheme_id}/draft/validation -> 200
 - GET /api/v1/schemes/{scheme_id}/publish/validation -> 200
+- GET /api/v1/schemes/{scheme_id}/draft/publish-readiness -> 200
 - POST /api/v1/schemes/{scheme_id}/draft/pricing/snapshot -> 200 when scheme is in draft
 - GET /api/v1/schemes/{scheme_id}/draft/publish-preview?refresh=true -> 200
 - GET /api/v1/schemes/{scheme_id}/draft/publish-preview -> 200
-- GET /api/v1/schemes/{scheme_id}/draft/publish-preview?refresh=true&baseline_scheme_version_id={published_version_id} -> 200
-
-Validate:
-- refresh and cached read both succeed
-- preview summary contains is_publishable / has_structure_changes / has_artifacts / snapshot_available
-- pricing_coverage is internally consistent
-- baseline override returns override strategy when explicit baseline is provided
-- preview retention does not grow unbounded for same version+variant
+- POST /api/v1/schemes/{scheme_id}/publish?expected_scheme_version_id=deadbeef... -> 409 typed stale conflict
 
 ## 7. Admin / ops
 
@@ -100,25 +68,7 @@ Validate:
 - GET /api/v1/admin/artifacts/publish-preview/audit -> 200
 - POST /api/v1/admin/artifacts/publish-preview/cleanup?dry_run=true -> 200
 
-Optional:
-- POST /api/v1/admin/schemes/{scheme_id}/current/display/regenerate?mode=passthrough -> 200
-- POST /api/v1/admin/display/backfill?mode=passthrough&limit=10&only_missing=true -> 200
-
-Validate:
-- audit endpoint does not report orphan files or missing files for DB rows in normal state
-- validation report is readable and deterministic
-- admin routes do not produce 500 for healthy scheme state
-
-## 8. Audit trail
-
-- GET /api/v1/schemes/{scheme_id}/audit -> 200
-
-Validate:
-- recent publish preview / pricing / version events are present when corresponding operations were run
-- audit total is non-negative
-- event payloads stay JSON-serializable
-
-## 9. Fail criteria
+## 8. Fail criteria
 
 Regression is considered failed if any of the following happen:
 
@@ -126,56 +76,6 @@ Regression is considered failed if any of the following happen:
 - any stable read endpoint returns 500
 - passthrough display endpoint fails on known-good sample
 - publish preview refresh or cached read returns 500
-- pricing bundle contract changes unexpectedly
-- pricing write contract regresses or stops returning typed payloads
-- stale draft guard stops returning 409 on pricing mutations
-- admin audit/cleanup endpoints fail on healthy environment
-- artifact retention grows without bound for repeated preview refresh on same variant
-
-## 10. Operator note
-
-Run this checklist after:
-- schema changes
-- pricing schema/repository refactors
-- artifact lifecycle changes
-- display pipeline changes
-- route reorganization
-- startup/import/config changes
-
-
-## 3.1. Draft editor read model
-
-- GET /api/v1/schemes/{scheme_id}/draft/structure -> 200 when current version is draft
-- GET /api/v1/schemes/{scheme_id}/draft/seats/records/{seat_record_id} -> 200 for known seat record
-- GET /api/v1/schemes/{scheme_id}/draft/sectors/records/{sector_record_id} -> 200 for known sector record
-- GET /api/v1/schemes/{scheme_id}/draft/groups/records/{group_record_id} -> 200 for known group record
-
-Validate:
-- returned record belongs to current draft scheme_version_id
-- single-entity endpoints match items visible in draft structure
-- missing draft record returns 404, not 500
-
-
-Additional draft read-side stale checks:
-- GET /api/v1/schemes/{scheme_id}/draft/structure?expected_scheme_version_id={current_version_id} -> 200
-- GET /api/v1/schemes/{scheme_id}/draft/compare-preview?expected_scheme_version_id={current_version_id} -> 200
-- GET /api/v1/schemes/{scheme_id}/draft/seats/records/{seat_record_id}?expected_scheme_version_id={current_version_id} -> 200
-- GET /api/v1/schemes/{scheme_id}/draft/sectors/records/{sector_record_id}?expected_scheme_version_id={current_version_id} -> 200
-- GET /api/v1/schemes/{scheme_id}/draft/groups/records/{group_record_id}?expected_scheme_version_id={current_version_id} -> 200
-- same endpoints with stale expected_scheme_version_id -> 409
-
-
-## 11. Typed error contract
-
-Validate representative failures return JSON detail objects with:
-- code
-- message
-
-Recommended checks:
-- stale_draft_version -> 409
-- stale_current_version -> 409
-- duplicate_sector_id / duplicate_group_id -> 422
-- unknown_sector_id / unknown_group_id -> 422
-- invalid_amount -> 422
-- publish_validation_failed -> 409
-
+- readiness endpoint contract breaks unexpectedly
+- pricing diagnostics endpoints fail on healthy environment
+- publish stale guard is not typed and deterministic