override: document the DoNormalizerPermGroup hook accurately

The old comment claimed the hook "does not interfere with" the
Normalizer(Sym(n), U) path. That is wrong: that path reduces via
NormalizerParentSA and then runs its residual backtrack through
DoNormalizerPermGroup (resolved by name), so the hook does fire there,
on the reduced problem. It correctly does not fire only when GAP settles
the normaliser with no backtrack at all (e.g. a full imprimitive wreath)
-- which is the intent: the hook compares backtrack against backtrack and
leaves GAP's non-backtrack reductions in place.

Also reword the CHANGES entry, which oversold the hook as a transparent
replacement for Normalizer; it is a benchmarking hook. To run Vole end to
end, call Vole.Normalizer directly.

Author: ChrisJefferson

CHANGES.md

@@ -24,9 +24,11 @@ substantial performance work on that machinery.
   section for the safety boundary).
 - `Vole.DDPD`: disjoint direct-product decomposition of a permutation group
   (Chang–Jefferson), used to factor highly-intransitive normaliser problems.
-- An optional hook to install Vole's normaliser in place of ⪆'s
-  `DoNormalizerPermGroup`, so existing code calling `Normalizer` can use Vole
-  transparently.
+- An optional benchmarking hook that routes ⪆'s `DoNormalizerPermGroup`
+  — the backtrack core that `Normalizer` falls into — to Vole, for
+  backtrack-vs-backtrack comparison. ⪆'s efficient non-backtrack
+  reductions are deliberately left in place; to run Vole end to end, call
+  `Vole.Normalizer` directly.
 - A settable branching-cell selector strategy, via the `selector` option or
   the `VOLE_SELECTOR` environment variable.
 - A new manual section, *Normalisers and canonical images of groups*,

gap/override.gi

@@ -64,13 +64,20 @@ end;
 # backtrack vs GAP's backtrack" rather than "Vole's whole pipeline
 # vs GAP's whole pipeline".
 #
-# Caveat: a separate dispatcher `DoNormalizerSA` (gpprmsya.gi:1400)
-# intercepts `Normalizer(Sym(n), U)` and reduces to
-# `Normalizer(NormalizerParentSA(G,U), U)` before
-# `NormalizerPermGroup` is reached — this hook does not interfere
-# with that path.  For large primitive / affine inputs GAP's
-# pre-backtrack maths is what wins, not its backtrack itself; see
-# the loss-hunt analysis.
+# `Normalizer(Sym(n), U)` takes a different route in: it dispatches
+# to `DoNormalizerSA` (gpprmsya.gi:1400), which first reduces via
+# `NormalizerParentSA` and then runs the backtrack on the reduced
+# parent P -- either through the recursive `Normalizer(P, U)` or, if
+# there is no reduction, via TryNextMethod to the generic method.
+# Either way that residual backtrack still bottoms out in
+# `DoNormalizerPermGroup` (resolved by name), so the hook DOES fire
+# here, on the reduced problem.  When `NormalizerParentSA` settles
+# the normaliser purely from symmetric-group structure (e.g. a full
+# imprimitive wreath), there is no backtrack at all and the hook
+# correctly does not fire.  That asymmetry is the whole point: the
+# hook pits backtrack against backtrack and leaves GAP's efficient
+# non-backtrack reductions in place.  To run Vole end to end instead,
+# call Vole.Normalizer directly.
 #
 # Contract: `DoNormalizerPermGroup(G, E, L, Omega)` returns the
 # normaliser N_G(E) acting on Omega.  Vole.Normalizer(G, E) already