diff --git a/src/Titano.Core/Analysis/HolyGrailEngine.cs b/src/Titano.Core/Analysis/HolyGrailEngine.cs
new file mode 100644
index 00000000..38c4e5ca
--- /dev/null
+++ b/src/Titano.Core/Analysis/HolyGrailEngine.cs
@@ -0,0 +1,221 @@
+using Titano.Core.Mathematics;
+
+namespace Titano.Core.Analysis;
+
+/// Parameters of .
+public sealed record HolyGrailOptions
+{
+ public static HolyGrailOptions Default { get; } = new();
+
+ /// Transition length in frames; null = half the typical distance between received steps.
+ public int? TransitionFrames { get; init; }
+
+ /// Transition length when fewer than two steps were received and none is configured.
+ public int SingleStepTransitionFrames { get; init; } = 12;
+
+ /// Largest allowed frame-to-frame change of the target curve, in EV.
+ public double MaxStepEv { get; init; } = 0.3;
+
+ /// Metadata EV changes smaller than this are not steps.
+ public double MinimumStepEv { get; init; } = 0.05;
+
+ /// A step is received when the measured jump has the expected sign and at least this fraction of its size.
+ public double MinimumReceivedFraction { get; init; } = 0.5;
+
+ /// Frames measured on each side of a step.
+ public int MeasureFrames { get; init; } = 6;
+
+ public DeflickerOptions Deflicker { get; init; } = DeflickerOptions.Default;
+}
+
+/// One metadata exposure step and how it was redistributed.
+/// First frame shot with the new settings.
+/// Luminance change implied by the metadata (−ΔEV).
+/// Detrended luminance jump measured across the step (NaN when not measurable).
+/// Whether the pixels actually changed; ignored steps get no transition.
+/// Frame position where the smooth transition starts (fractional).
+/// Transition length in frames (0 when not received).
+public sealed record ExposureTransition(int Index, double ExpectedEv, double MeasuredEv, bool Received, double Start, double Length);
+
+/// Target log2 luminance per frame.
+/// Target − measured.
+/// Cumulative received steps (the abrupt exposure offsets in the pixels).
+/// The same steps spread over their transitions.
+/// Largest |Target[i] − Target[i−1]|.
+public sealed record HolyGrailResult(
+ double[] Target,
+ double[] CorrectionEv,
+ double[] StepOffsets,
+ double[] SmoothedOffsets,
+ IReadOnlyList Transitions,
+ DeflickerResult Deflicker,
+ double MaxFrameStepEv);
+
+///
+/// Holy-grail exposure-step redistribution (BRIEF §10.3, §11.2). Metadata EV steps are checked against the measured
+/// luminance (detrended medians on both sides), steps the pixels did not receive are ignored, and each received step
+/// is removed from the series, the step-free series deflickered, and the step added back as a smoothstep transition
+/// centred on it. Transitions lengthen until no frame-to-frame change of the target exceeds
+/// ; ramps are kept inside the sequence so the total change is preserved.
+///
+public static class HolyGrailEngine
+{
+ /// Measured log2 luminance per frame (NaN = unusable).
+ /// Metadata EV (ISO 100) per frame; null when unknown.
+ public static HolyGrailResult Compute(ReadOnlySpan logLuminance, ReadOnlySpan exposureEv, HolyGrailOptions? options = null)
+ {
+ options ??= HolyGrailOptions.Default;
+ var n = logLuminance.Length;
+ if (exposureEv.Length != n) throw new ArgumentException("One exposure value per frame is required.", nameof(exposureEv));
+ if (!(options.MaxStepEv > 0)) throw new ArgumentOutOfRangeException(nameof(options), "MaxStepEv must be positive.");
+ var luminance = logLuminance.ToArray();
+
+ var transitions = DetectSteps(luminance, exposureEv, options);
+ var offsets = new double[n];
+ foreach (var t in transitions)
+ {
+ if (!t.Received) continue;
+ for (var i = t.Index; i < n; i++) offsets[i] += t.ExpectedEv;
+ }
+ var flat = new double[n];
+ for (var i = 0; i < n; i++) flat[i] = luminance[i] - offsets[i];
+ var deflicker = DeflickerEngine.Compute(flat, options.Deflicker);
+
+ var received = transitions.Where(t => t.Received).ToList();
+ var lengths = InitialLengths(received, deflicker.Target, n, options);
+ var smoothed = new double[n];
+ var target = new double[n];
+ var maxStep = 0.0;
+ for (var attempt = 0; attempt < 40; attempt++)
+ {
+ Ramps(received, lengths, n, smoothed);
+ for (var i = 0; i < n; i++) target[i] = deflicker.Target[i] + smoothed[i];
+ maxStep = MaxStep(target);
+ if (maxStep <= options.MaxStepEv || lengths.All(l => l >= n - 1)) break;
+ for (var k = 0; k < lengths.Length; k++) lengths[k] = Math.Min(n - 1, Math.Max(lengths[k] + 1, lengths[k] * 1.25));
+ }
+
+ var correction = new double[n];
+ for (var i = 0; i < n; i++) correction[i] = double.IsFinite(luminance[i]) ? target[i] - luminance[i] : 0;
+ var report = new List(transitions.Count);
+ var r = 0;
+ foreach (var t in transitions)
+ {
+ if (!t.Received)
+ {
+ report.Add(t);
+ continue;
+ }
+ report.Add(t with { Start = RampStart(t.Index, lengths[r], n), Length = lengths[r] });
+ r++;
+ }
+ return new HolyGrailResult(target, correction, offsets, smoothed, report, deflicker, maxStep);
+ }
+
+ private static List DetectSteps(double[] luminance, ReadOnlySpan exposureEv, HolyGrailOptions options)
+ {
+ var candidates = new List<(int Index, double Expected)>();
+ double? last = null;
+ for (var i = 0; i < exposureEv.Length; i++)
+ {
+ if (exposureEv[i] is not { } ev || !double.IsFinite(ev)) continue;
+ if (last is { } p && Math.Abs(ev - p) >= options.MinimumStepEv) candidates.Add((i, -(ev - p)));
+ last = ev;
+ }
+
+ var result = new List(candidates.Count);
+ for (var c = 0; c < candidates.Count; c++)
+ {
+ var (index, expected) = candidates[c];
+ var from = Math.Max(c > 0 ? candidates[c - 1].Index : 0, index - options.MeasureFrames);
+ var to = Math.Min(c + 1 < candidates.Count ? candidates[c + 1].Index : luminance.Length, index + options.MeasureFrames);
+ var measured = MeasureJump(luminance, from, index, to);
+ var received = double.IsNaN(measured)
+ || (Math.Sign(measured) == Math.Sign(expected) && Math.Abs(measured) >= options.MinimumReceivedFraction * Math.Abs(expected));
+ result.Add(new ExposureTransition(index, expected, measured, received, 0, 0));
+ }
+ return result;
+ }
+
+ ///
+ /// Jump between frames [from, index) and [index, to): the scene trend (median first difference on both sides,
+ /// excluding the step itself) is removed, then the medians of the two sides are compared. NaN when a side has no
+ /// valid frame.
+ ///
+ private static double MeasureJump(double[] luminance, int from, int index, int to)
+ {
+ var differences = new List();
+ for (var j = from + 1; j < to; j++)
+ {
+ if (j == index) continue;
+ var d = luminance[j] - luminance[j - 1];
+ if (double.IsFinite(d)) differences.Add(d);
+ }
+ var slope = differences.Count > 0 ? Statistics.Median(differences.ToArray()) : 0;
+ var left = new List();
+ var right = new List();
+ for (var j = from; j < to; j++)
+ {
+ if (!double.IsFinite(luminance[j])) continue;
+ var detrended = luminance[j] - slope * (j - (index - 0.5));
+ (j < index ? left : right).Add(detrended);
+ }
+ if (left.Count == 0 || right.Count == 0) return double.NaN;
+ return Statistics.Median(right.ToArray()) - Statistics.Median(left.ToArray());
+ }
+
+ /// Half the typical spacing of received steps (or the configured length), lengthened per step so a lone
+ /// smoothstep (peak slope 1.5·|s|/L) fits in the budget left by the scene's own frame-to-frame change.
+ private static double[] InitialLengths(List received, double[] sceneTarget, int n, HolyGrailOptions options)
+ {
+ double baseLength;
+ if (options.TransitionFrames is { } configured) baseLength = configured;
+ else if (received.Count >= 2)
+ {
+ var spacing = new double[received.Count - 1];
+ for (var i = 1; i < received.Count; i++) spacing[i - 1] = received[i].Index - received[i - 1].Index;
+ baseLength = Math.Round(Statistics.Median(spacing) / 2);
+ }
+ else baseLength = options.SingleStepTransitionFrames;
+ baseLength = Math.Max(2, baseLength);
+
+ var budget = options.MaxStepEv - MaxStep(sceneTarget);
+ var lengths = new double[received.Count];
+ for (var k = 0; k < lengths.Length; k++)
+ {
+ var needed = budget > 0 ? Math.Ceiling(1.5 * Math.Abs(received[k].ExpectedEv) / budget) : n - 1;
+ lengths[k] = Math.Min(Math.Max(1, n - 1), Math.Max(baseLength, needed));
+ }
+ return lengths;
+ }
+
+ private static void Ramps(List received, double[] lengths, int n, double[] smoothed)
+ {
+ Array.Clear(smoothed);
+ for (var k = 0; k < received.Count; k++)
+ {
+ var length = lengths[k];
+ var start = RampStart(received[k].Index, length, n);
+ var amount = received[k].ExpectedEv;
+ for (var i = 0; i < n; i++)
+ {
+ var t = Math.Clamp((i - start) / length, 0, 1);
+ smoothed[i] += amount * t * t * (3 - 2 * t);
+ }
+ }
+ }
+
+ /// Ramp centred on the boundary between frames index − 1 and index, shifted to lie inside [0, n − 1].
+ private static double RampStart(int index, double length, int n) => Math.Clamp(index - 0.5 - length / 2, 0, Math.Max(0, n - 1 - length));
+
+ private static double MaxStep(double[] series)
+ {
+ var max = 0.0;
+ for (var i = 1; i < series.Length; i++)
+ {
+ var d = Math.Abs(series[i] - series[i - 1]);
+ if (double.IsFinite(d)) max = Math.Max(max, d);
+ }
+ return max;
+ }
+}
diff --git a/tests/Titano.Core.Tests/Analysis/HolyGrailEngineTests.cs b/tests/Titano.Core.Tests/Analysis/HolyGrailEngineTests.cs
new file mode 100644
index 00000000..3becabf6
--- /dev/null
+++ b/tests/Titano.Core.Tests/Analysis/HolyGrailEngineTests.cs
@@ -0,0 +1,88 @@
+using System.Globalization;
+using Titano.Core.Analysis;
+using Titano.Core.Diagnostics.Synthetic;
+using Titano.Testing;
+
+namespace Titano.Core.Tests.Analysis;
+
+public sealed class HolyGrailEngineTests(TestContext context)
+{
+ ///
+ /// Sunset: the scene darkens 8 EV while the camera opens up 2/3 EV every 20 frames, plus one metadata change
+ /// the pixels never received. BRIEF §20.4: no target step above 0.3 EV; the total change is preserved.
+ ///
+ [Test]
+ public void SunsetStepsAreRedistributedWithinTheGate()
+ {
+ var steps = Enumerable.Range(1, 11).Select(k => new SyntheticExposureStep(k * 20, -2.0 / 3, k % 3 == 0 ? ExposureChange.Iso : ExposureChange.Shutter)).ToList();
+ steps.Add(new SyntheticExposureStep(130, -1.0 / 3, ExposureChange.Aperture, Received: false));
+ var sequence = SyntheticSequence.Create(new SyntheticSequenceOptions
+ {
+ FrameCount = 240,
+ Seed = 9,
+ StartEv = 2,
+ EndEv = -6,
+ FlickerEv = 0.03,
+ ExposureSteps = steps,
+ });
+ var measured = AnalysisFixtures.MeasureSeries(sequence);
+ var ev = sequence.Frames.Select(f => f.ExposureValue).ToArray();
+ var result = HolyGrailEngine.Compute(measured, ev);
+
+ var rawMaxStep = Enumerable.Range(1, measured.Length - 1).Max(i => Math.Abs(measured[i] - measured[i - 1]));
+ var maxStep = Enumerable.Range(1, measured.Length - 1).Max(i => Math.Abs(result.Target[i] - result.Target[i - 1]));
+ var truth = sequence.SceneEv.Select((s, i) => s + sequence.ExposureOffsetEv[i]).ToArray();
+ var totalTruth = truth[^1] - truth[0];
+ var totalTarget = result.Target[^1] - result.Target[0];
+ context.Log(string.Create(CultureInfo.InvariantCulture,
+ $"raw max step {rawMaxStep:F3} EV, target max step {maxStep:F3} EV, total change target {totalTarget:F3} vs truth {totalTruth:F3} EV, transition {result.Transitions[0].Length} frames"));
+
+ Assert.Equal(12, result.Transitions.Count);
+ var ignored = Assert.NotNull(result.Transitions.SingleOrDefault(t => !t.Received));
+ Assert.Equal(130, ignored.Index);
+ Assert.True(result.Transitions.Where(t => t.Index != 130).All(t => t.Received));
+ Assert.Greater(rawMaxStep, 0.5);
+ Assert.LessOrEqual(maxStep, 0.3);
+ Assert.Approximately(maxStep, result.MaxFrameStepEv, 1e-12);
+ Assert.Approximately(totalTruth, totalTarget, 0.05);
+ // Default transition: half the 20-frame step spacing.
+ Assert.Equal(10.0, result.Transitions[0].Length);
+ }
+
+ [Test]
+ public void LargeStepGetsALongerTransition()
+ {
+ var n = 100;
+ var measured = Enumerable.Range(0, n).Select(i => i >= 50 ? 1.5 : 0.0).ToArray();
+ var ev = Enumerable.Range(0, n).Select(i => (double?)(i >= 50 ? 10.5 : 12.0)).ToArray();
+ var result = HolyGrailEngine.Compute(measured, ev, new HolyGrailOptions { TransitionFrames = 4 });
+ Assert.LessOrEqual(result.MaxFrameStepEv, 0.3);
+ Assert.GreaterOrEqual(result.Transitions[0].Length, 7.5);
+ Assert.Approximately(1.5, result.Target[^1] - result.Target[0], 1e-9);
+ Assert.Approximately(1.5, result.Transitions[0].MeasuredEv, 1e-9);
+ }
+
+ [Test]
+ public void StepsNearTheEndsStayInsideTheSequence()
+ {
+ var n = 30;
+ var measured = Enumerable.Range(0, n).Select(i => i >= 2 ? 1.0 : 0.0).ToArray();
+ var ev = Enumerable.Range(0, n).Select(i => (double?)(i >= 2 ? 11.0 : 12.0)).ToArray();
+ var result = HolyGrailEngine.Compute(measured, ev, new HolyGrailOptions { TransitionFrames = 8 });
+ Assert.Equal(0.0, result.Transitions[0].Start);
+ Assert.Approximately(0, result.SmoothedOffsets[0], 1e-12);
+ Assert.Approximately(1, result.SmoothedOffsets[^1], 1e-12);
+ Assert.LessOrEqual(result.MaxFrameStepEv, 0.3);
+ }
+
+ [Test]
+ public void NoMetadataStepsMeansPlainDeflicker()
+ {
+ var measured = Enumerable.Range(0, 60).Select(i => 0.01 * i + (i % 2 == 0 ? 0.05 : -0.05)).ToArray();
+ var ev = new double?[60];
+ var result = HolyGrailEngine.Compute(measured, ev);
+ var plain = DeflickerEngine.Compute(measured);
+ Assert.Empty(result.Transitions);
+ Assert.SequenceEqual(plain.Target, result.Target);
+ }
+}