feat(processor): implement pre-gain compensation for clamped LUFS ceilings

[flexiondotorg]

Summary

Implements (pre-gain before alimiter) to address LUFS normalisation shortfalls on very quiet recordings. When the peak limiter ceiling gets clamped to the safety floor due to headroom constraints, pre-gain is inserted before the alimiter to restore the target loudness whilst respecting peak limits.

This resolves the issue where recordings below -50 dBFS cannot reach the target LUFS level without exceeding 0 dB peak after limiting.

Changes

Phase 1: Constants and diagnostics

• Extract limiter constants to package level: safetyMarginDB=1.5, minLimiterCeilingDB=-24.0
• Add PreGainDB and LimiterClamped fields to NormalisationResult
• Enable clamping flag propagation through the normalisation pipeline

Phase 2: Pre-gain implementation

• Modify buildLoudnormFilterSpec() to detect when limiter ceiling is clamped
• Calculate pre-gain deficit = minLimiterCeilingDB - idealCeiling
• Insert volume={deficit}dB filter before alimiter in Pass 4 chain
• Re-derive limiter ceiling from post-gain measured values
• Adjust measured_I and measured_TP for loudnorm metadata accuracy
• Return (string, float64, bool) with pre-gain metadata

Phase 3: Comprehensive test coverage

• New TestBuildLoudnormFilterSpec_PreGain with 4 scenarios
• Extended TestCalculateLimiterCeiling with 2 new clamping cases
• New TestPreGainCeilingRederivation with 4 re-derivation scenarios
• All 293 new test lines verify deficit arithmetic and ceiling consistency

Phase 4: Diagnostics

• Extend peak limiter report to show pre-gain application and deficit amount

Phase 5: Documentation

• Update README.md with pre-gain strategy overview
• Update AGENTS.md with implementation details
• New section in FilterLimiter-CBS-Volumax.md documenting the compensation mechanism

Testing

• Unit tests: 293 new assertions across 3 test functions covering edge cases
• just lint passes
• just test passes (all processor tests, including pre-gain scenarios)

[cubic-dev-ai]

2 issues found across 6 files

Confidence score: 4/5

• This PR is likely safe to merge with minimal risk: the reported issues are moderate and focused on documentation accuracy and test coverage rather than a confirmed runtime break.
• In docs/FilterLimiter-CBS-Volumax.md, the worked pre-gain math no longer matches implementation constants, which can mislead users/operators configuring the limiter.
• In internal/processor/normalise_test.go, the non-clamped limiter test only covers inputs where alimiter= already exists, so a regression that drops limiter insertion for normal peak-limited inputs could slip through CI.
• Pay close attention to docs/FilterLimiter-CBS-Volumax.md and internal/processor/normalise_test.go - align documented arithmetic with current constants and broaden the non-clamped limiter assertion path.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="docs/FilterLimiter-CBS-Volumax.md">

<violation number="1" location="docs/FilterLimiter-CBS-Volumax.md:186">
P2: The worked example's pre-gain arithmetic doesn't match the current implementation constants, so the table documents the feature incorrectly.</violation>
</file>

<file name="internal/processor/normalise_test.go">

<violation number="1" location="internal/processor/normalise_test.go:445">
P2: The non-clamped limiter case only asserts the branch when `alimiter=` is already present, so this test will miss a regression that drops the limiter for ordinary peak-limited inputs.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

0 issues found across 2 files (changes from recent commits).

_{Requires human review: Modifies core audio normalization logic and filter chain processing, introducing complex arithmetic for pre-gain compensation which requires manual verification by a human reviewer.}

[cubic-dev-ai]

1 issue found across 2 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="internal/processor/normalise_test.go">

<violation number="1" location="internal/processor/normalise_test.go:670">
P3: This test bypasses the clamped-target propagation it claims to verify by assigning `effectiveTargetI` into `config` directly instead of exercising `ApplyNormalisation`'s real forwarding path.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

0 issues found across 1 file (changes from recent commits).

_{Requires human review: Modifies core audio normalization logic and filter chain construction in a critical processing path, which requires human domain expertise to verify.}