ombi-mcp/docs/megaplans/m2/02-spec-harmonisation.md

Phase 02 — Specification Harmonisation

Objective

Bring docs/schema/ into agreement with the Phase 01 behaviour: the routing contract, input catalogue, output contract and endpoint ledger must describe the TVDB v1 info route, the per-origin theMovieDbId labelling and the new tvmaze namespace, and the embedded internal/tools/schemas.json must be regenerated so the advertised output schema accepts the new namespace.

Prerequisites

• Phase 01 complete — the code and tests are the source of truth this phase documents.
• Source documents to mutate: docs/schema/02-tool-mapping.md, docs/schema/03-input-schemas.md, docs/schema/04-results.md, docs/schema/05-endpoint-coverage.md, docs/schema/06-verification.md; regenerate internal/tools/schemas.json via go run ./tools/schemagen from the repository root (never hand-edit).

Specification

Mutations

1. docs/schema/02-tool-mapping.md — read_media.details routing: TV tvdb uses the legacy v1 Search/tv/info/{tvdbId} route; record that v2 Search/tv/{tvdbId} is a TMDB-keyed alias of moviedb despite its parameter name and must never serve a TVDB lookup. Add the identifier-origin paragraph: v1 TVMaze-backed routes emit theMovieDbId→tvdb and seriesId→tvmaze; v2 routes emit tmdb; RecentlyAdded tv keeps tmdb pending verification. Note the TV season expansion reads details in the same provider namespace.
2. docs/schema/03-input-schemas.md — read_media prose: provider selects the namespace id belongs to; tvdb resolves via the v1 info route. write_request_create prose: provider selects the id namespace and season expansion reads details in the same namespace.
3. docs/schema/04-results.md — identifier.namespace enum gains tvmaze; media_page projection rules document that theMovieDbId is origin-dependent (v1 TV → tvdb + seriesId→tvmaze; v2 → tmdb) and labels follow the origin route, never the field name.
4. docs/schema/05-endpoint-coverage.md — #193 GET /api/v2/Search/tv/{tvdbId} demotes D→A with the TMDB-alias annotation (never used for tvdb); #235 GET /api/v1/Search/tv/info/{tvdbId} promotes A→D as the true TVDB details route owned by read_media / details, noting it is also read privately by write_request_create season expansion and that theMovieDbId carries TVDB while seriesId carries TVMaze; #234 notes the same TVMaze id layout for read_search / text. Disposition totals are net-zero (D 257 / A 37).
5. docs/schema/06-verification.md — new gap-table row "TV search/details id provenance" carrying the Verify items: live-confirm the v1 tv/info/{tvdbId} route shape, the RecentlyAdded TV id namespace, the multi-search TV id namespace, and the by_request externalProviderId namespace.
6. internal/tools/schemas.json — regenerate from the updated docs; the identifier def's namespace enum must contain tvmaze.

Target artefacts

• docs/schema/02-tool-mapping.md — details routing + identifier-origin paragraph + season-expansion namespace note.
• docs/schema/03-input-schemas.md — provider-semantics prose on read_media and write_request_create.
• docs/schema/04-results.md — tvmaze enum value + origin-dependent labelling rule.
• docs/schema/05-endpoint-coverage.md — #193 demoted/annotated, #235 promoted/annotated, #234 annotated.
• docs/schema/06-verification.md — id-provenance Verify row.
• internal/tools/schemas.json — regenerated, contains tvmaze.

Verification gates

• grep -n tvmaze internal/tools/schemas.json finds the regenerated enum value; grep -n tvmaze docs/schema/04-results.md finds the documented enum value.
• Ledger dispositions remain D 257 / A 37 / P 59 / I 12 / X 12 and 377 operations / 321 paths.
• #193 carries the TMDB-alias note and disposition A; #235 carries disposition D and the TVMaze/seriesId note.
• docs/schema/02-tool-mapping.md states the v1 info route for tvdb and the per-origin labelling rule.
• docs/schema/06-verification.md lists the id-provenance Verify items.
• go run ./tools/schemagen succeeds (31 input schemas, 37 defs); CGO_ENABLED=0 go build ./... clean.
• No environment-specific URL or secret in any committed doc.

Evidence labels

• Documented — the ledger annotations cite upstream behaviour verified in Phase 01 (v2 alias routes, TVMaze Id/SeriesId mapping).
• Design — wording choices in the routing prose and the decision to keep RecentlyAdded/multi-search labels at tmdb pending verification are contract decisions, not upstream facts.
• Verify — the provenance row in 06-verification.md is the consolidated Verify list; nothing in this phase asserts an unverified namespace as fact.