fix(podcast): reject explicit cross-subject image collisions

[i-xtsu-sixyou-ken-mei]

Intent

Turn the current scene-image review feedback into a narrow planner guard without bringing back the old identity hard gate that starved episodes.

The concrete production failure is the Tether episode where a scene anchored to Tether could select a Brave result whose metadata/source explicitly identified a different known episode subject (Yamandú Orsi).

Context

Recent main already fixed the earlier feedback layers:

• visual anchors rank person > named entity > object
• subject queries lead with an identity hint (Tether stablecoin issuer, not bare Tether)
• query matching uses token boundaries
• Brave spellcheck is disabled, covering the Blonskr -> Blonsky incident
• searched assets already rotate per subject, so this PR does not add another reuse cap

The remaining hole is selection-time contradiction. The pool intentionally stopped requiring every candidate to mention the requested entity after an earlier hard gate discarded 423/423 viable images. That decision is still correct: editorial image metadata is often weak. But the planner currently treats even a result that explicitly names a different catalog subject as merely low-ranked rather than contradictory.

Scope

• Reject an image for a named subject when:
  • the candidate does not name any entity of the current subject, and
  • the candidate explicitly names another known subject from the same episode.
• Apply the same guard to the subject's own pool and cross-subject fallback.
• Keep generic candidates that name neither subject eligible.
• Add regression coverage using the production-shaped Tether / Yamandú Orsi case.

Out of scope

• No new Brave requests or request-budget changes.
• No return to candidate must mention current entity filtering.
• No new reuse cap; current planner already rotates least-used assets and caps distinct searched assets per subject.
• No visual-version bump; this is a planner selection correction and should not re-plan all unfinished episodes automatically.

Product contract / invariants

• This PR does not change the existing resilient-image invariant.
• This PR intentionally changes an invariant with explicit product approval.

Affected invariant:

apps/podcast-pipeline/AGENTS.md — entity mention remains a ranking bonus rather than a required identity match, and cross-subject fallback remains available.

Why this is aligned rather than a hard-gate reversal:

A candidate that names no catalog subject remains eligible. Only positive evidence that the image is about a different known episode subject is excluded for the current named scene.

Acceptance criteria

• A Tether subject keeps a generic result such as “Bitcoin mining facility in Uruguay”.
• The same subject excludes a result explicitly titled/sourced as Yamandú Orsi when Orsi is another subject in the episode.
• Cross-subject fallback applies the same contradiction rule.
• Unnamed/generic editorial candidates remain available.
• Brave request counts and fallback ladder are unchanged.

Implementation

episode-image-pool.ts derives the current subject's normalized entities from the existing pool key. Before serving subject entries or fallback entries, it checks candidate metadata against the other named subject keys in the same episode. It only filters when another subject matches and the current subject does not.

This deliberately uses the same mentionsAnyEntity boundary-aware matcher as existing ranking, so short names do not regress to substring matching.

Contract alignment

• Implementation preserves the resilient pool/fallback model.
• Regression tests cover both own-pool and fallback behavior.
• Scoped AGENTS.md remains accurate: current-entity mention is still not required and cross-subject fallback still exists.
• README / runbook remains accurate; request budget and ladder are unchanged.

Validation

• Regression tests added in episode-image-pool.test.ts for the production-shaped Tether → Orsi collision.
• GitHub CI will run the repository test/type/lint rails on this branch.

Validation gaps

No live Brave call is required for this regression: provider responses are deterministic fixtures matching the stored production evidence. CI status should be checked before merge.

Known unrelated failures

None known.

Reviewer notes

The important line is the distinction between absence of identity evidence (still allowed) and positive evidence for another known subject (now excluded). Broadening this into a general current-entity hard gate would recreate the 423/423 starvation failure this pool architecture was designed to avoid.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated
zap-engine-control-center	Skipped		Sep 8, 2026 2:10am UTC