fix(podcasts): complete plays without an explicit date

[ryan-winkler]

Summary

A podcast play recorded without a completion date stored NULL. Play counts read history rows WHERE end_date IS NOT NULL, so the episode showed status Completed and a play count of zero. The first three commits on this branch resolve one completion timestamp in the shared service, so the web form and the REST API cannot disagree.

Review of that change found four more defects on the same path. This update corrects them.

• Record a play at the current server time when the caller sends a blank date or no date.
• Anchor duplicate detection to the timestamp that is being recorded.
• Read completion dates in one place, so the web form and the REST API apply the same rule.
• Refuse a date that the web form cannot read, instead of recording the current time.
• Regenerate the published API contract, which no longer matched the endpoint.

What review found

Four independent reviews ran against the diff: a QA pass, a red team and blue team panel, a staff engineering panel, and an accessibility panel for ADHD and AuDHD users. A DRY audit ran over the result.

1. A dateless play unmasked already-imported plays

Duplicate detection compared a new play against the newest play only. After one dateless play, that newest play was always today, so every re-imported old play looked new.

Measured before the correction:

Sequence	Result
Import a 2020 play twice	duplicate=True, 1 play. Correct.
Import 2020, record a dateless play, import 2020 again	duplicate=False, 3 plays. Incorrect.

Duplicate detection now matches history rows near the timestamp that is being recorded. The query is one indexed range lookup, and it replaces a sort and a subtraction.

2. The web form recorded a time the user did not choose

podcast_save parsed dates itself. When the value could not be read, both parsers returned None. Before this branch that stored NULL. After the fallback was added, it stored the current time and reported success. The user kept a timestamp they never entered, and nothing told them.

The REST API answered 400 for the same input.

The completion-date reader now lives in app.helpers.parse_completion_datetime. api.helpers.try_parse_datetime_input calls it. The web form reports the problem and records nothing.

3. The error path closed the modal and discarded the input

The first correction redirected away from the form. For an HTMX request that removes the modal, so the user must find the episode again and type the date again. The accessibility panel identified this as an executive-function cost, and the red team identified the same defect as a broken HTMX flow.

An HTMX request now receives HX-Reswap: none and a toast. The modal stays open and the typed date stays on screen.

4. The published contract did not match the endpoint

src/api/contracts/openapi.yaml still carried the previous description. The file is served at runtime by api/contract_views.py, so API clients read a rule the code no longer applied.

The artifact is regenerated in this update.

A byte-exact gate for this already exists and works. At commit 8715914c, app.tests.test_api_contracts.OpenAPIArtifactTests fails 2 of 11 tests. CI on this branch had not been run, so the failure was never reported.

Wording

User-facing text states what happened and what to do next.

Before	After
Play already recorded for {episode}	Floppy recorded a play for {episode} less than five minutes ago. Floppy did not add a second play.
(none)	Floppy cannot read the date "{value}". Enter the date as YYYY-MM-DD. To record this play at the current time, keep the date empty.

The previous duplicate message read as success while the play count did not change.

Validation

Commands run locally against this branch:

• manage.py test api — 454 tests, all pass.
• manage.py test app — all pass.
• manage.py test api.tests.test_fork_podcast — 17 tests, all pass.
• ruff check src — all checks pass.
• python -m app.domain_vocabulary --check — in sync. No model vocabulary changed.
• manage.py spectacular ... --fail-on-warn --validate — regenerated and committed.

Each new regression test was confirmed to fail without its correction:

• test_reimported_play_stays_a_duplicate_after_a_dateless_play fails with AssertionError: False is not true against the previous duplicate logic.

Browser verification against a local server, signed in as a real user:

Step	Result
Record a play with a blank date	Progress moves 0/2 to 1/2. end_date is stored.
Send the same play again	No second play. One history row.
Send an unreadable date	Nothing recorded. Error reported.
Send an unreadable date over HTMX	200, HX-Reswap: none, error toast, modal stays open.

Database state after the sequence: one row, status=Completed, end_date set, completed_play_count=1, one history row.

Performance

• No new query on the create path.
• Duplicate detection is one indexed range query. It replaces an ordered fetch of the newest history row.
• A duplicate play costs 3 queries.
• timezone.now() is called only when no date is supplied.

Measured separately and not caused by this branch: one new play costs about 80 queries, from signals and cache invalidation. This is recorded below as follow-up work.

Offline and packaged app

The play path was tested with sockets blocked. It makes no network call. It depends only on the database and the system clock, so it works offline and in a packaged build.

Risks and rollback

• A blank date now means "completed now". A user who knows the exact time can still supply it.
• Rows that already hold end_date = NULL are not rewritten. See follow-up work.
• Duplicate detection changed shape. A play within five minutes of any recorded play is now suppressed, not only within five minutes of the newest one. This is the intended correction.
• No migration and no schema change. The branch is revertible.

Follow-up work, not in this PR

1. Podcast.end_date moves backwards when an older play is recorded. Every review panel proposed end_date = max(existing, completed_at). That correction does not work here: a probe confirmed history rows copy the parent row at save time, so keeping the newer value would log the backfilled play under the wrong timestamp. The durable fix separates the play log from the parent projection. This needs its own issue.
2. app/music_album_views.song_save still contains the date-parsing block that was removed here, and fork_services_music.record_song_play has no duplicate detection and assigns end_date unconditionally, so music can still clear a good timestamp. Highest remaining drift risk.
3. Rows already stored with Completed and end_date = NULL still report zero plays. A silent backfill would invent a timestamp the user never chose, so an operator-run command is the better shape. Needs a product decision.
4. About 80 queries per play.
5. try_parse_datetime_input is now a one-line delegate with a name that suggests it returns None on failure. Renaming touches 14 call sites in 6 files, so it belongs in a separate mechanical change.

Relationships

• Fixes [BUG] Podcast episode without date causes crashes #827.
• Related: [BUG] Pocket Casts import can create duplicate episodes and incorrect listening dates #600 covers podcast listening-date correctness for the Pocket Casts import, which this does not change.
• Depends on nothing.

Post-mortem

• Trigger: the web form and the REST API both accepted an empty date.
• Fault: the shared service stored that empty value on a completed play.
• Visible effect: read paths use end_date as the completion signal, so a completed episode reported zero plays.
• Why review was needed a second time: the first correction resolved the timestamp but left three related paths wrong. Duplicate detection still compared against the newest play, the web form still parsed dates itself, and the published contract still described the old rule.
• Prevention: regression tests now cover both entry surfaces, the duplicate window on both sides of its edge, and the modal error path.
• Process note: the contract gate was already in place and already failing. The regression reached review because CI was never run on the branch, not because a check was missing.