gronod
eccbe48ff0
Build and publish / Test and build (darwin) (push) Successful in 2m3s
Build and publish / Test and build (linux) (push) Successful in 2m45s
Build and publish / Test and build (windows) (push) Successful in 3m13s
Build and publish / Build and publish Docker image (push) Successful in 2m30s
Ombi's v2 Search/tv/{tvdbId} route is a TMDB-keyed alias despite its parameter name, so read_media details and write_request_create season expansion resolved the wrong series for TVDB ids (Gitea issue #1). Repoint tvdb to the legacy v1 Search/tv/info route, label theMovieDbId by origin route (tvdb on TVMaze-backed v1 results, tmdb on the v2 engine) and emit the new tvmaze identifier namespace from seriesId.
47 lines
4.7 KiB
Markdown
47 lines
4.7 KiB
Markdown
# 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
|
|
|
|
- [x] `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.
|
|
- [x] Ledger dispositions remain D 257 / A 37 / P 59 / I 12 / X 12 and 377 operations / 321 paths.
|
|
- [x] #193 carries the TMDB-alias note and disposition A; #235 carries disposition D and the TVMaze/`seriesId` note.
|
|
- [x] `docs/schema/02-tool-mapping.md` states the v1 info route for tvdb and the per-origin labelling rule.
|
|
- [x] `docs/schema/06-verification.md` lists the id-provenance Verify items.
|
|
- [x] `go run ./tools/schemagen` succeeds (31 input schemas, 37 defs); `CGO_ENABLED=0 go build ./...` clean.
|
|
- [x] 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.
|