Problem
Individual analysis features must not invent their own sampling-rate or duration limits. A feature-local ChordRecognizer.recognize() guard can disagree with the desktop intake boundary, other analyzers, cache keys, resampling behavior, and user-facing error handling. That creates inconsistent denial-of-service protection and makes valid long-form rehearsals fail only after reaching a downstream feature.
Buyer-visible outcome
Users should receive one predictable validation result before expensive decoding or analysis starts. Every downstream feature should consume a bounded, canonical audio artifact and should not silently apply a different duration or sampling-rate policy.
Required design
- Define a versioned
audio_resource_policy shared by desktop intake, IPC, analysis orchestration, and feature analyzers.
- Bound encoded file bytes, decoded sample count, channel count, source sampling rate, resampled sampling rate, duration, memory estimate, and per-job CPU/GPU budgets.
- Validate before allocation where metadata is trustworthy, then revalidate decoded output because container metadata is untrusted.
- Preserve one explicit policy for real rehearsal recordings; do not hard-code a five-minute limit without product evidence and documented override behavior.
- Use checked arithmetic for every size conversion and fail closed on overflow, non-finite values, malformed headers, decompression bombs, or policy disagreement.
- Return localized payload-free errors and record the policy version and rejection reason in audit/provenance metadata.
- Keep identifiers and database object names at least two words and use
snake_case by default.
Verification
- Realistic short rehearsal, full-song, and long rehearsal fixtures at supported sampling rates and channel counts.
- Boundary tests immediately below, at, and above each limit.
- Malformed metadata, decoded-size expansion, oversized channel count, extreme sampling rate, integer overflow, zero/negative/non-finite metadata, and cancellation tests.
- Exact parity between desktop preflight, service API, and every analyzer.
- Peak RSS, CPU time, GPU/VRAM, and cancellation latency measurements.
- Production statement/branch coverage and public docstrings at 100% for the new policy layer.
CHANGELOG.md, architecture/doctoring, rollback guidance, and APA 7 primary-source references.
Relation to PR #732
PR #732 should remain focused on the NumPy observation/Viterbi reference optimization. Its feature-local sampling-rate and 300-second duration checks should be removed and implemented through this canonical policy in a separate reviewed slice.
Problem
Individual analysis features must not invent their own sampling-rate or duration limits. A feature-local
ChordRecognizer.recognize()guard can disagree with the desktop intake boundary, other analyzers, cache keys, resampling behavior, and user-facing error handling. That creates inconsistent denial-of-service protection and makes valid long-form rehearsals fail only after reaching a downstream feature.Buyer-visible outcome
Users should receive one predictable validation result before expensive decoding or analysis starts. Every downstream feature should consume a bounded, canonical audio artifact and should not silently apply a different duration or sampling-rate policy.
Required design
audio_resource_policyshared by desktop intake, IPC, analysis orchestration, and feature analyzers.snake_caseby default.Verification
CHANGELOG.md, architecture/doctoring, rollback guidance, and APA 7 primary-source references.Relation to PR #732
PR #732 should remain focused on the NumPy observation/Viterbi reference optimization. Its feature-local sampling-rate and 300-second duration checks should be removed and implemented through this canonical policy in a separate reviewed slice.