docs/reference/ts-reports.md

Timestamps reports

Reader-facing issue reporting on the Timestamps tab: a visitor (anonymous or signed-in) flags a problem on the verse they're hearing, an owner resolves it, and everyone sees persisted flags in the analysis grid. Two surfaces:

• Drop-up (footer Report button) — pick a category, in order timing → tajweed → phonemes → silence → audio → other. audio / other open an inline comment composer (verse-level); timing / tajweed / phonemes / silence enter report mode (tajweed + silence expand to subtype rows first).
• Report mode — an in-grid mode that replaces the waveform with a control strip and turns the analysis grid into the click surface, so a contributor annotates specific cells without a modal blocking them.

Backed by one SQLite table; the per-reciter shard content is never touched.

Data model — table ts_reports

Migrations: 0025_ts_reports.sql (table), 0026_ts_reports_hidden.sql (hidden_at soft delete), 0027_ts_reports_rule_tags.sql (selected_rule_tags). The legacy ts_verse_flags table (0024) is superseded and left in place pending a manual row migration.

One row per (slug, verse_key, category, target_key, identity) — identity is EITHER a signed-in hf_user_id OR an anonymous browser anon_token (exactly one). Re-filing the same category+target updates in place (upsert). Key columns:

Column	Meaning
category	audio · timing · tajweed · phonemes · silence · other
subtype	tajweed: wrong_rule|missing_rule; silence: pause_boundary|pause_wasl|pause_missed; else NULL
timing_onset / timing_offset	timing (and silence pause_boundary): each early|late|NULL (NULL = that boundary is fine), ≥1 set. The human label (too short/long, shifted, starts/finishes early/late) is derived via qua_shared...ts_reports.timing_label() — never stored
target_kind + word_index / source_letter_index / cell_index / phoneme_flat_index / share_group	the flexible target descriptor (verse|word|cell|phoneme|cell_group|gap). phonemes reports only target phoneme. silence reports target a gap — the word-boundary between word_index and word_index+1, keyed on the preceding word (only word_index is set). A cross-word merger/bridge phoneme has phoneme_flat_index = -1 (see Bridge phonemes)
target_key	canonical descriptor string (kind:wi:sli:ci:pi:sg, plus :subtype for tajweed only) the per-identity unique index keys on — built in repo_ts_reports.target_key(). Timing/phonemes/silence are subtype-free in the key → one report per target+identity (so a gap holds one silence stance per user — last write wins)
snap_*	denormalized snapshot of the targeted shard content at create time — the drift fingerprint (no per-cell hash). Includes snap_onset_ms/snap_offset_ms, the target's boundary ms for timing + silence-gap staleness
selected_rule_tags	JSON: the internal tajweed tag id(s) the reporter marked wrong (wrong_rule only)
comment	mandatory for audio/other + every tajweed; optional for timing; never for phonemes or silence
status / resolved_*	single terminal resolved outcome + optional owner note
stale / stale_at	set when a shard regen changed the targeted content (see Staleness below)
hidden_at	soft-delete stamp — NULL = visible. Every read filters hidden_at IS NULL; re-filing un-hides

Grouping (a domain concept, no schema column)

• Timing and phonemes reports group by word: every cell/phoneme flagged in one (slug, verse_key, word_index, category, identity) is ONE logical report — one owner notification, resolved as a unit via the /word/<wi>/<category>/resolve endpoint. Computed from existing columns via repo_ts_reports.word_group_key(); never a stored group_key. The route word-grouped set is _WORD_GROUPED = {timing, phonemes}.
• Tajweed reports are per cell PER subtype — the same cell can carry both a wrong_rule and a missing_rule report (two rows, two notifications). The subtype rides in target_key for tajweed only, so same cell + same subtype still upserts. No SQL migration: the unique index is unchanged; the key string carries the distinction.
• Silence reports are per gap (one stance per boundary per identity) and each fires its own owner notification (the batch else branch, one-per-gap). The three subtypes share the subtype-free gap target_key, so switching subtype on the same gap upserts.

Rows stay per-cell either way (so per-cell subtype + comment survive); grouping lives only in the notify/resolve/display layers.

Bridge phonemes (cross-word mergers)

A cross-word merger (idgham / iltiqaa) phoneme sits in the gap between two words. The FE renderer stamps it with phoneme_flat_index = -1 and word_index = the word it renders before (the following word for a cross-word idgham). Since at most one bridge renders before any word, (word_index, -1) is already a unique kind='phoneme' key — no schema change. Such a report groups under that following word. The snapshot resolver (_bridge_phone_for_target) re-finds the merger phone by walking each word's phones[] for a row carrying a bridge rule (slot 5), mapping it to wi when it is the word's first phone else wi+1 (the iltiqaa-kasra connector is found via its cell tag on the preceding word).

Staleness (per-category, on shard regen)

recheck_reports_staleness re-resolves every open report against the new shard and mark_stales only those whose category-relevant content changed (audio never stales). For timing, that is the targeted cell's identity (chars/role) changing OR a boundary the report flagged moving: if onset is set and the target's start ms shifted by more than config.TS_REPORT_BOUNDARY_STALE_MS (default 100), or likewise offset and the end ms — staled for owner re-check (NOT auto-resolved). A pure ms shift on a boundary the report did not flag does not stale it. The boundary ms are captured at create in snap_onset_ms/snap_offset_ms. For phonemes, the targeted phone's identity (chars / role / rule tag, incl. a bridge's merger rule) changing — or the phone vanishing — stales it.

Silence reports don't just stale, they AUTO-RESOLVE when the regen confirms them (_silence_action, gap-present = offset_ms > onset_ms from the gap snapshot): a pause_missed resolves once a gap appears at its boundary, a pause_wasl (and a pause_boundary whose gap vanished entirely) once the gap is gone. A pause_boundary whose gap remains stales on a flagged-boundary shift past the threshold (like timing). A vanished boundary (word structure changed) stales for owner re-check. Auto-resolve goes through repo_ts_reports.resolve_auto (system resolver, resolved_by_* NULL, the reason in resolver_comment) and notifies both owners and the (signed-in) reporter via notify_ts_report_auto_resolved — all inside the regen transaction (durable_transaction is nesting-safe).

Visibility

timing grid flags + the verse-level audio/other reports are public — returned to every viewer. silence gap flags are public too. tajweed + phonemes flags are non-public: the repo (_visibility_filter, applied in verse_counts + list_for_verse) returns them only to the reporter (matched by hf_user_id or anon_token) or to a caller holding timestamps.view_nonpublic_reports (maintainer + owner by default). Non-holders never receive those rows or their counts (true hide, not just un-rendered) — so the FE simply renders what it gets. The read endpoints pass an existing anon token (never minting one — see peekAnonToken) so an anonymous reporter still sees their own non-public flags.

Backend

File	What
inspector/services/db/repo_ts_reports.py	create (upsert), create_many (batch, one identity/verse/txn), resolve (per id), resolve_group (timing/phoneme word-group, all identities), resolve_auto (system-resolve a silence report on regen), delete (soft), verse_counts + list_for_verse (both take the viewer ctx + _visibility_filter), list_open_for_recheck, word_group_key
inspector/routes/timestamps/reports.py	thin blueprint over the repo + snapshot + notify (see endpoints below)
inspector/services/ts_reports/ts_target_snapshot.py	build_snapshot (resolve a target → snapshot dict, incl. the gap kind), _silence_action (silence resolve/stale decision), recheck_reports_staleness (post-regen: re-resolve open reports — mark_stale the changed, auto-resolve + notify the agreed silence ones; audio never stales)
inspector/services/notifications/emit.py	notify_owners_ts_report (optional source_key for word-group coalescing), notify_reporter_ts_report_resolved, notify_ts_report_auto_resolved (reporter + owners, regen auto-resolve)
qua_shared/schemas/wire/ts_reports.py	wire models + _validate_report_item (shared single + batch validation)

⚠️ The package is services/ts_reports/ (NOT services/timestamps/, which would collide with the services.timestamps attribute bound in services/__init__.py).

Endpoints (/api/ts/<slug>/reports)

Method + path	Body → response	Gate
GET /reports	→ TsReciterReports (per-verse open/resolved counts; non-public counts filtered by viewer)	public
GET /reports/<verse_key>	→ TsVerseReports (?stale=1 owner-only; author redacted; non-public rows filtered by viewer)	public
POST /reports	TsReportCreateRequest → TsReport	timestamps.report (anon)
POST /reports/batch	TsReportBatchCreateRequest → TsReportBatchResult	timestamps.report
POST /reports/<id>/resolve	TsReportResolveRequest → TsReport	timestamps.resolve_report
POST /reports/<verse_key>/word/<wi>/<cat>/resolve	TsReportResolveRequest → TsVerseReports (timing/phonemes)	timestamps.resolve_report
DELETE /reports/<id>	soft-delete the caller's own	timestamps.report

Batch create builds each snapshot BEFORE the transaction (shard reads out of the write window), then _fan_batch_notifications fires one owner notification per new timing/phoneme word-group (source_key=word_group_key(...), coalesced by repo_notifications.create's (hf_user_id, source_key) idempotency) and one per new tajweed cell / silence gap; re-submitted (created=False) rows never notify. Capabilities: timestamps.report (anon-eligible), timestamps.resolve_report, timestamps.see_reporter_identity, timestamps.view_stale_reports, timestamps.view_nonpublic_reports (maintainer-default; gates seeing tajweed + phoneme flags) — registered in qua_shared/schemas/config/capabilities.py.

Frontend (inspector/frontend/src/tabs/timestamps/)

File	What
stores/report-mode.ts	the mode state machine (inactive / timing / tajweed + subtype / phonemes / silence + subtype), staged Map keyed by cell, focusedCellKey, reportContext; enterTiming / enterTajweed / enterSilence pause + force letters-only (snapshot/restore showLetters/showPhonemes), tajweed additionally forceAllTajweedEnabled; enterPhonemes instead forces showPhonemes ON and leaves showLetters at the user's setting (the inverse). Seed own flags by category+subtype; a StagedPhoneme carries just the target and a StagedSilence carries the gap + (for pause_boundary) onset/offset — both complete on select (binary silence subtypes too); focusCell/isStagedComplete auto-discard an incomplete cell on focus-move; exitReportMode restores display + tajweed snapshots, exitLoop, clears
stores/tajweed-settings.ts	forceAllTajweedEnabled() / restoreTajweedSettings() — transient (non-persisted) bulk enable used by tajweed report mode
stores/ts-reports.ts	reportedVerses (reciter counts → button highlight) + currentVerseReports / loadVerseReports (the focus verse's reports → in-grid public flags + report-mode seeds)
utils/report-target.ts	the ONE keying place — cellKey/wordKey/gapKey/targetCellKey (DOM- and wire-derived keys must agree), cellTargetFromEl, elCellKey, elHasTajweed. A gap tile (pause bridge / missed slot) carries data-gap-word-index → gapKey
utils/rendered-blocks.ts	builds the analysis grid — RenderedPauseBridge.fromWordIndex (the gap's preceding word) + per-RenderedUnit gapWordIndex/missedMark for the missed-pause slot at each contiguous word boundary (splitWaqf lifts the preceding word's stop sign, else ||)
utils/cell-model.ts	threads cellIndex (raw word.cells[] index = the target's cell_index) and ruleTags (internal tajweed tag ids = the picker's options) onto rendered cells
components/UnifiedDisplay.svelte	stamps data-cell-index/-source-letter-index/-share-group/-has-tj/-tj-tags/-phoneme-flat-index/-gap-word-index (pause bridges + missed slots); a delegated capture-phase click that STAGES via focusCell (auto-discard) instead of seeking. Timing + silence loop/seek (silence loops the two words straddling the gap); tajweed/phonemes stage only. Phonemes mode is a multi-select toggle. Silence spotlights the gap tiles: pause_boundary/pause_wasl target the existing .pause-bridge, pause_missed targets the inserted .missed-slot; everything else dims (report-dim on words + off-type gaps) + inerts. Reactive report-* passes (mode-scoped report-timing/-tajweed/-phonemes/-silence/-missed/-existing; staged/focused/public flags). A publicly-flagged missed slot gets a native "Reported missing pause" title. data-has-tj='1' ⇐ the cell carries a ruleTag (pickable rule) OR a badge/silent name
components/TimestampsFooterReport.svelte + report/ReportMenu.svelte + ReportComposer.svelte	the drop-up: category list, inline audio/other composer (fixed-height field so it never reflows the drop-up), and onenterMode('timing'|'tajweed'|'phonemes'|'silence', subtype?) → report mode (timing/phonemes enter directly; tajweed + silence expand subtype rows)
components/report/ReportControlStrip.svelte	the strip that replaces the waveform — header (title + static subtype label), Cancel + Submit, and ONE inline row per staged cell (label · control · comment · ✕). Phonemes collapse to ONE row per word of removable chips. Silence rows: pause_boundary reuses the Start/End onset/offset axes + derived label; pause_wasl / pause_missed are binary (a static stance label, no control, no comment)
services/report-submit.ts + reports-client.ts	build TsReportBatchCreateRequest from staged + reconcile removed own reports (deleteReport); the fetch client

Mount: TimestampsTab.svelte swaps <TimestampsWaveform> ↔ <ReportControlStrip> on $reportModeActive in .waveform-words-row, and loadVerseReports on every verse change (also exits an active session if the verse moves — report mode is verse-scoped).

Flag rendering

The report-* classes are toggled imperatively on a cached node list from a reactive one-shot, never inside the 60fps updateHighlights() (the disjoint class names keep the two off each other). The spotlight dims + inerts (report-dim opacity + report-inert pointer-events:none, killing click AND hover tooltip) the cells that can't carry the current report: in tajweed wrong_rule, every cell with data-has-tj!='1' (no rule); in timing, every cell with data-cell-timed!='1' (a silent letter has no duration to call too-long/short — words stay live); in phonemes, every [data-cell-index] letter/diacritic cell (only .mega-phoneme spans stay live). So only rule-bearing cells (tajweed), timed letters (timing), or phoneme spans (phonemes) stay interactive. Because flag rows render only what the backend returns, non-public tajweed/phoneme flags simply don't appear for non-reporters (no FE gate needed). The wrong_rule rule-picker offers only labelable tags — sentinels like silent_unclassified are dropped (ruleHasLabel), so it never shows a raw tag id; the cell's true rule name still shows on the grid hover tooltip via data-tj-rules. report-flag-staged / report-flag-public draw a red outline ring (outline, not box-shadow, so it never collides with the tajweed underline and never reflows); report-focused adds the accent ring. Styles live in styles/timestamps.css; the tooltip line is appended by _tipTextFor.

Invariants / gotchas

• Verse lock for the whole session. Entering report mode pauses playback and TimestampsTab.armVerseLock() arms a whole-verse loop ([verse start, next verse start) — covers the trailing silence). That pin stops free play from auto-advancing and suppresses shuffle (maybeFireShuffle also bails on reportModeActive). Selecting a timing cell narrows the loop to that cell, and selecting a silence gap loops the two words straddling it (audio context); selecting a tajweed or phonemes cell does NOT touch the loop or play/pause (you judge a rule/phoneme against the running verse, not an isolated cell). Only a manual ayah/reciter change moves the focus verse → _syncVerseReports exits the session + discards staged. exitReportMode clears the loop.
• Auto-discard incomplete. Moving focus to another cell drops the previously focused annotation when it is still missing a required field (timing subtype / tajweed rule pick when >1 option / mandatory comment); report-submit re-filters defensively. No hard block — keeps flagging frictionless.
• Subtype is fixed at entry. The drop-up's wrong_rule / missing_rule rows enter the session with that subtype; the strip shows it as a static label (no in-mode toggle). A different subtype on the same cell is a separate session + separate report.
• cell_index is the raw word.cells[] index (matches backend word_cells(word)), captured before the hamza-waṣl transform; synthesized cells fall back to source_letter_index.
• Display forcing differs by mode. timing + tajweed + silence force letters-only (the click surface is cells / gap tiles, not phonemes) — both footer toggles are locked. phonemes mode forces the phoneme row ON and leaves the letters row at the user's setting, so the letters toggle stays operable while the phonemes toggle is locked on.
• Missed-pause slots are always in the DOM, invisible until needed. A .missed-slot renders at every contiguous word boundary but is display:none at rest; it's revealed (spotlit, clickable) only in pause_missed report mode, or shown with a red ring + native title for ALL viewers when publicly flagged — so the "red border in the gap with no cell there" works without re-rendering the grid.
• One key function. DOM keys (elCellKey) and wire keys (targetCellKey) must agree or public flags won't land on the right cell.
• dev-remote can't exercise the real endpoints (the deployed dev Space predates this) — drive the FE with Playwright route stubs; the real flow is covered by the backend tests.

Tests

• inspector/tests/db/test_repo_ts_reports.py — create/upsert/counts, soft-delete
  • re-file un-hide, create_many word-grouping (timing + phonemes), resolve_group, bridge-phoneme target uniqueness, visibility filtering of non-public counts + rows, silence one-stance-per-gap upsert + public visibility + resolve_auto.
• inspector/tests/routes/test_route_ts_reports.py — gating, redaction, batch notification counts (one per timing/phoneme word, one per tajweed cell), group resolve (timing + phonemes), non-public visibility (hidden from other viewers, shown to the reporter + a capability holder).
• inspector/tests/services/test_ts_target_snapshot.py — phoneme + bridge-phoneme resolution, per-category staleness, and the silence gap resolution + auto-resolve decision matrix (_silence_action).
• qua_shared/tests/test_ts_reports_wire.py — per-category validators (incl. phonemes + silence/gap), batch models, selected_rule_tags gate, single/batch validation parity.