From bbdc64b9dcea09973638f421c9f121bd2af1c2b4 Mon Sep 17 00:00:00 2001 From: 4gray Date: Wed, 29 Jul 2026 19:34:39 +0200 Subject: [PATCH] docs(portals): record the key-addressing limit a pin write cannot close Co-Authored-By: Claude Opus 5 --- docs/architecture/vod-multi-source.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/architecture/vod-multi-source.md b/docs/architecture/vod-multi-source.md index 637a8ef2b..55b3adfd1 100644 --- a/docs/architecture/vod-multi-source.md +++ b/docs/architecture/vod-multi-source.md @@ -172,6 +172,15 @@ The renderer passes `write[0]` as the pin's own `matchKey` and the rest as `aliasKeys`; `setVodSourcePin` upserts one row per key and retires the leftovers inside the same transaction, so no key list can half-apply. +Known limit, inherent to addressing rows by key alone: a write can only touch +keys the renderer can *name*. Re-pin a film during a pre-enrichment window and +the `tmdb:{id}` row from an earlier, enriched session is not among them, so it +survives pointing at the old source — and outranks the title key once the id +arrives again. Nothing can enumerate it from the page's side; closing it needs a +reverse index from film to key. The window is small in practice (TMDB responses +are cached in `tmdb_metadata`, so a revisit usually resolves the id at once) and +does not exist at all with enrichment off. + A write stores the new key **before** retiring the old rows. The other order destroys the stored preference and can then fail to replace it, leaving nothing persisted while the row still shows the old pin; lookups are most-trusted-first,