refactor(naming): use semantic temporal and score identifiers

[seonghobae]

Problem

BandScope exposed organization-owned generic single-word identifiers in two bounded contexts where domain language is already available:

• Tempo Stability internals used names such as run, beats, bpms, window, flagged, changes, before, after, deviation, intervals, and cv.
• The score-PDF viewer/adapter and its tests used a product-owned data prop/argument plus generic internal names such as status, zoom, container, observer, canvas, page, scale, viewport, retry, duplicate cancelled authorities, result, error, and stale test-mock vocabulary.

Exact ownership and scope

• Protected base at branch creation: develop@749511c3ad4000090048718f685c6bee6b3d2c25.
• Branch: refactor/temporal-semantic-identifiers-2026-09-02.
• Current exact head: b2e7cdb3f1c473b95e6887dacc38f51eb8c3a5b7.
• Owner surfaces:
  • services/analysis-engine/src/bandscope_analysis/temporal/stability.py
  • apps/desktop/src/features/score/ScoreViewer.tsx
  • apps/desktop/src/features/score/ScoreViewer.test.tsx
  • apps/desktop/src/features/score/ScoreView.tsx
  • apps/desktop/src/features/score/ScoreView.test.tsx
  • apps/desktop/src/features/score/pdfjs.ts
  • apps/desktop/src/features/score/pdfjs.test.ts
• docs/product-technical-gap-baseline.md remains canonically introduced by stacked docs(gap): refresh product-technical baseline (74 repos, live census) #1116, so this narrow naming PR does not create a competing baseline owner.

Test-first repair lineage

Tempo Stability

• RED 3fb96a3f01a127520e726fbe99023dafa4701f14 adds an AST naming regression requiring bounded-context temporal identifiers while the production module still contains the legacy names.
• GREEN 3f08af6eadf8bb4defcc5ba8020d5f142cee14aa replaces the private implementation vocabulary with tempo_change_run, beat_times_array, local_bpm_values, comparison_window_beats, flagged_boundaries, before_bpm_median, after_bpm_median, relative_bpm_deviation, beat_intervals, and bpm_variation_coefficient.
• 3c6bb2d0a34b9f41b0f4986b6bd9ddf7bc99e1b9 keeps the regression test's own non-throwaway identifier semantic (module_identifiers).

Score viewer / pdf.js ACL

• RED 4e0b2b5133e673f670e4d685500d2e1fa1afd544 changes the component contract tests to require scorePdfBytes; production still expected data at that exact commit, so the test is intentionally RED by construction.
• GREEN 492346e2183a6bc0714377acf9a58fdab32169c4 changes ScoreViewerProps.data → scorePdfBytes and internal names to viewerStatus, scoreTranslator, zoomScale, viewerContainer, resizeObserver, scoreCanvas, pdfPage, viewportScale, pageViewport, and retryPdfLoad.
• 3c68966cc3251f4e389382d033fb96b02f31863b updates the repository consumer in ScoreView.tsx from <ScoreViewer data={pdfBytes}> to <ScoreViewer scorePdfBytes={pdfBytes}>.
• 3562504091802b658fb9df7645a7e35009dff04b changes loadScorePdf(data) to loadScorePdf(scorePdfBytes) while intentionally preserving pdf.js's externally mandated getDocument({ data: ... }) field only at the adapter boundary.
• 5794465d48fb8d9ff2ff941d891053fe8facc5e9 updates the adapter regression to prove the semantic internal byte name is translated to the exact vendor data field while preserving defensive-copy and hardened-parser options.
• 25ea6dff470bbeb0059291757f4a5e85c74dcb05 removes the remaining generic callback parameter status in the touched component contract in favor of viewerStatus.
• bdd1cb2e130d1bc08a89fcf233738cb1d394431a separates the two independent cancellation authorities as pdfLoadCancelled and pageRenderCancelled.
• 29fd07fb8decdc936904bd1fd6739c34fc6d3363 aligns touched ScoreViewer test fixtures with bounded PDF/viewer vocabulary while preserving Promise/pdf.js/ResizeObserver external members.
• 16ea794447afcdcce68ac83c09deedcb6833be78 fixes the repository-local ScoreView.test.tsx mock that still destructured the obsolete data prop after production switched to scorePdfBytes; without this propagation, viewer-byte assertions exercised undefined instead of the new contract. The same commit qualifies the mock translator's generic key as translationKey.
• 1571ed5ec00cc1a141c566a90fa0017d358a0c4c qualifies ScoreView-owned bridge/view state vocabulary (bridgeError, fallbackMessage, rawErrorMessage, firstErrorLine, scoreTranslator, scoreAttachments, selectedScoreAttachment, scoreError, scoreAttachment, scorePdfBytes, attachmentResult, removalConfirmed, scoreAttachmentEntry).
• b2e7cdb3f1c473b95e6887dacc38f51eb8c3a5b7 immediately restores the pre-existing cyan opening-spinner presentation after the whole-file source update, preserving the naming-only behavior boundary before fresh verification.

The cancellation/test/source follow-up commits are behavior-neutral except for repairing the stale mock contract so existing viewer behavior tests exercise the actual scorePdfBytes prop. No test is skipped, weakened, xfailed, or replaced with model-only evidence.

Compatibility boundary

This PR intentionally preserves the existing TempoChange / TempoStability serialized keys (time, from_bpm, to_bpm, stability, tempo_changes) and public analyze_tempo_stability(beat_times) entrypoint because those shapes cross existing analysis consumers and require a separately verified migration/ACL if changed.

For score parsing, pdf.js owns the external data option name, so it remains exactly data inside the getDocument adapter object. BandScope-owned callers use scorePdfBytes. Promise members such as promise, pdf.js members such as numPages/getPage, Tauri command payload fields, React's key, and ResizeObserver platform contracts remain at their external/framework boundaries. Repository-local ScoreViewer consumers and mocks are translated coherently; no compatibility alias or duplicate generic internal PDF field is retained.

No database table/column/index/constraint, ORM mapping, persistence format, dependency, network, filesystem, subprocess, IPC, model, or release-format change occurs here. No DB migration, FK/index rewrite, UPSERT change, locking/read-write change, or rollback data transform is required.

Verification / merge gate

Keep Draft and unmerged until the unchanged exact head has the focused temporal/score regressions plus every applicable repository and central CI/build/release/security/SAST/SBOM/supply-chain/coverage/review gate terminal-success, zero valid unresolved current-head findings, and a qualifying independent non-author last-push approval under ordinary branch protection. Predecessor/base/model-only/queued evidence does not transfer.

Fresh exact-head CodeQL PR run 33642724317 on b2e7cdb3... terminated startup_failure before creating any jobs. This reproduces the shared required-workflow admission incident on the final source head rather than a score-viewer test/job failure. Other exact-head workflows are queued/pending and there are currently no review submissions, so this PR remains Draft and cannot merge.

Security Notes

Tempo changes remain pure in-memory numeric computation with existing fail-closed malformed-input behavior. Score parsing remains validated-resource-only and preserves the hardened local-worker, enableXfa: false, useWorkerFetch: false, defensive-copy boundary. The naming change adds no authority, remote fetch, storage, or execution path.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}