Document resolve_songwriter_identity Context action

SI
5d ago
+58-3

Summary

Documents the new resolve_songwriter_identity action of the shared POST /api/context operation (HTTP and MCP context tool). It links one saved ingest_songwriter_name request (an unresolved, workspace-private name candidate) to one organization professional that the operator explicitly selected from GET /api/organizations/professionals and confirmed with confirmed: true. This closes the gap where a saved songwriter name stayed identityConfirmed: false with no way to connect it to the professional roster, and addresses the ticket's "resolve ambiguous names before enrichment" item without name matching.

The OpenAPI change in api-reference/openapi/context.json is additive: a new oneOf request schema, an example, and the receipt shape {resolution: {id, request_id, subject_id, professional_id, resolved_by, resolution_basis, created_at}, created} in the 200 description. The response documents the limits: exact replays return the saved receipt; a different professional for an already resolved request, or a reused key with different input, is a conflict (409); a professional from another workspace or revoked membership is denied. The action creates no roster member, professional, login account, enrichment, rights or mandate. MDX pages stay frontmatter-only and the nav is unchanged.

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

Merge sequencing

docs (this PR) → database recoupable/database#110 (20261010213600_context_songwriter_identity_resolution.sql) → api recoupable/api#1022 (resolve_songwriter_identity). There is no app change in this slice. Does not depend on any other open PR.

Verification

  • Ran: python3 -c "import json;json.load(open('api-reference/openapi/context.json'))". The file parses, and the new const: "resolve_songwriter_identity" branch is present.
  • Contract cross-checked against the api implementation: idempotency_key uses the same pattern and 1–128 length as contextIngestSchema, confirmed is the literal true, and errors return 409 from contextOperationHandler.
  • Red → green: not applicable (documentation only; the api and database PRs carry the failing-first tests).
  • Review round (HEAD fd4c22c): the request_id description now says songwriter-name requests come from the ingest_songwriter_name action (delegated MCP tool import_songwriter_context), which this reference does not yet document; cross-workspace and revoked-membership selections are stated as 409 (what contextOperationHandler returns) instead of "denied"; the shared 409 text no longer tells resolution callers to retry a conflict that retrying cannot change. Re-ran the json.load parse: OK, the request oneOf still has 6 actions.
  • Not verified: Mintlify preview rendering, hosted deployment, live providers, production database.

Out of scope / known gaps

  • Chat UI for linking a saved songwriter name to a professional (can follow once the API action is merged).
  • Enrichment/research for resolved songwriters (plan still reports songwriter research as not implemented).
  • Company-name resolution, roster side-effect audit of Spotify onboarding (#2147/#2140), rights/mandates.

🤖 Generated with Claude Code