Persist bounded Spotify ingest recovery guidance (supersedes #1001)

Draft
SI
12d ago
+681-25

Failed Spotify Context requests currently store one generic message. This successor stores bounded authored code/guidance through the existing fail_context_request RPC and gives album/playlist/artist URLs explicit schema-level routing.

Supersedes #1001 source9c2701a82b37430f0cbf82d881d5a9f141a631a0 in its exact nine-file scope, on main95ee06218e4ae24c9a27f706939e6925b8e9dbe0 without old history. Related recoupable/app#2126. Draft: owning current Docs acceptance required before merge; not completion of the child or dependencies.

Provider HTTP/JSON/schema/standard transport failures are classified only at fetch. Globally only three exact storage-wrapped identity conflicts are recognized; arbitrary Zod/syntax/timeout/auth/storage errors stay unknown. Persisted guidance contains no raw bodies, exception details, causes, IDs or logs. 404/410 does not prove deletion; unknown commit outcomes do not prove zero writes. No automatic-retry/no-charge guarantee.

Runner changes only p_error. Owner checks, claim token, terminal skips and commit ordering remain unchanged. Relinked IDs fail before commit. No new RPC/field/schema/state/job/spend/migration. Canonical URL/fingerprint unchanged; original-locator retention remains separate. YouTube parsing unchanged; ingestion disabled.

Initial RED then166tests PASS across failure/pipeline/URL/operations/guest/published-example suites. Strict source and all-changed-file scoped types, repository lint, formatting/diff checks PASS. Independent review PASS. No generic full-suite/TypeScript rerun; previously reported unrelated global type failures remain visible.

Integration with API1215at4977dce3: non-checkout merge-tree reports only additive README conflict; retain both pending sections. Its handlers/classifier/source binding and Docs31 remain untouched. Background stored errors are distinct from operation response envelopes. No integrated runtime claim.

Minimal Docs dependency: seven persisted codes/conditional guidance; no deletion/zero-write guarantees; album-to-ingest_release and playlist/artist400 guidance; unchanged canonical normalization; pending availability. No duplicate Docs intake opened.

No provider request, DB/migration execution, activation, server/build/browser/auth/credential change. Mocked fixtures do not verify real Spotify, persisted DB, retry or intended-account/native journeys.

Summary by cubic

Replaces the single generic Spotify ingest failure message with bounded, classified recovery guidance stored through the existing fail_context_request RPC.

  • Persists one of seven authored codes—unsupported_input, recording_unavailable, provider_outage, provider_rejected, provider_response_invalid, identity_conflict, unknown—each with conditional retry guidance. Guidance never carries provider bodies, exception details, IDs, or logs.
  • Album, playlist, and artist URLs now return explicit schema-level messages on HTTP 400: album locators point to ingest_release, playlists and artist pages are named as unsupported track inputs.
  • Failure classification happens only at the provider fetch, JSON/schema decode, and exact storage identity-conflict boundaries; everything else stays unknown.
  • 404/410 is not presented as proof of deletion, and unknown or lost commit responses do not claim zero writes.