Document identityConflicts on failed context reads

SI
5d ago
+1-0

Summary

Context read can return a failed request carrying output.identityConflicts when the submitted Spotify track is already mapped to a different ISRC. This is the database quarantine for the recoupable/app#2119 acceptance item "Conflicting track-to-recording mappings are visible and excluded from accepted context pending resolution".

This PR adds a description to the read action's request variant in api-reference/openapi/context.json. It documents:

  • the identity_conflict: error prefix
  • the [{providerId, observedIsrc, existingIsrcs, linkIds}] shape
  • what linkIds contains: a new conflict link for a legacy mapping, or the existing accepted link, which is never downgraded
  • that nothing is accepted for that request
  • that brief refuses the request until the mapping is resolved and the request is retried

It adds no new operation, schema, MDX page or nav entry.

Refs recoupable/app#2119 (child of epic recoupable/app#2116).

Merge sequencing

docs (this PR) → database recoupable/database#100 → api recoupable/api#1007. No app PR for this slice. Depends on no OPEN PR. The sentence used to sit on the read/brief 200 response description line. Nine sibling docs PRs also rewrite that line, so it now lives on the read request variant, which none of them touch.

Verification

  • Ran: python3 -c "import json;json.load(open('api-reference/openapi/context.json'))" → parses OK, and the read variant carries the description.
  • Red → green: not applicable (documentation-only, additive one-line edit).
  • Not verified: hosted Mintlify deployment/rendering, live providers, production database.

Out of scope / known gaps

  • No new operation, Zod schema or MDX page. Review, merge and split operations are not documented because they do not exist yet (accept/correct/withdraw is recoupable/app#2124).
  • Artist-identity ambiguity still rejects transactionally and is not described as quarantined.

🤖 Generated with Claude Code