RUSTIFY: cache filtered annotation views on frozen lists (~4% less allocation)

The filtered+direction-sorted annotation list that TraversalMethodBase.Reset rebuilds on
every Transduce call depends only on (annotation list, filter, direction) — not on which
FST asks. Measured on the sena grammar, ~89% of the 63k Reset calls per 20 words re-derive
a view already built for the same frozen list: COW clones share the frozen source's int
projection, and rule filters are a handful of compiler-cached non-capturing lambdas, so the
same (list, filter, direction) triple recurs across all the rules in a stratum.

Reset now consults a small cache of filtered views chained on the AnnotationList itself
(lock-free CAS publish; ~filters x directions entries). Only FROZEN lists cache — a frozen
list and its annotations' FeatureStructs are immutable, so a view is final; unfrozen lists
never cache because rules edit matched nodes' FeatureStructs in place, which would silently
invalidate a cached view. Shape.Freeze() now freezes the (already-final) int projection so
the gate applies to it, which also hardens the COW invariant: unexpected mutation of a
shared projection now throws instead of corrupting.

Byte-identical: 827 SIL.Machine + 63 HermitCrab tests pass, and the 60-word uncapped sena
signature diff is empty. Measured ~3.7% less per-word allocation (thread-local counter at
dop=1) plus the skipped tree-walk + insertion sort on every cache hit; dop=16 throughput
unchanged-to-better.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: johnml1135

src/SIL.Machine/Annotations/AnnotationList.cs

@@ -42,6 +42,57 @@ internal void IncrementVersion()
             _version++;
         }
 
+        // Cache of filtered+direction-sorted annotation views for FST traversal (see
+        // TraversalMethodBase.Reset). Only populated on FROZEN lists — a frozen list (and its
+        // annotations' FeatureStructs) is immutable, so the filtered view is final; for unfrozen
+        // lists a rule's in-place FeatureStruct edit could silently invalidate a cached view, so
+        // they never cache. Keyed by filter-delegate reference: filters come from a handful of
+        // compiler-cached non-capturing lambdas (one per rule-class call site), so the chain stays
+        // tiny (≤ filters × directions). Lock-free CAS publish; a lost race just rebuilds once.
+        private sealed class FilteredView
+        {
+            internal readonly object Filter;
+            internal readonly Direction Direction;
+            internal readonly List<Annotation<TOffset>> Annotations;
+            internal readonly FilteredView Next;
+
+            internal FilteredView(
+                object filter,
+                Direction direction,
+                List<Annotation<TOffset>> annotations,
+                FilteredView next
+            )
+            {
+                Filter = filter;
+                Direction = direction;
+                Annotations = annotations;
+                Next = next;
+            }
+        }
+
+        private FilteredView _filteredViews;
+
+        internal List<Annotation<TOffset>> GetFilteredView(object filter, Direction dir)
+        {
+            for (FilteredView v = _filteredViews; v != null; v = v.Next)
+            {
+                if (ReferenceEquals(v.Filter, filter) && v.Direction == dir)
+                    return v.Annotations;
+            }
+            return null;
+        }
+
+        internal void AddFilteredView(object filter, Direction dir, List<Annotation<TOffset>> annotations)
+        {
+            while (true)
+            {
+                FilteredView head = _filteredViews;
+                var entry = new FilteredView(filter, dir, annotations, head);
+                if (System.Threading.Interlocked.CompareExchange(ref _filteredViews, entry, head) == head)
+                    return;
+            }
+        }
+
         public AnnotationList()
             : base(new AnnotationComparer(), begin => new Annotation<TOffset>(Range<TOffset>.Null)) { }
 

src/SIL.Machine/Annotations/Shape.cs

@@ -258,6 +258,11 @@ public void Freeze()
             // than racing a lazy first build of the offset dictionaries. No extra work overall: a frozen
             // shape that is frozen is one that will be traversed (by itself or its COW clones).
             EnsureIntProjection();
+            // Freeze the (final) projection so the FST traversal can cache filtered views on it
+            // (AnnotationList.GetFilteredView gates on IsFrozen — for an unfrozen list, in-place
+            // FeatureStruct edits could silently invalidate a cached view). Also fail-fast hardens
+            // the COW invariant: any unexpected mutation of a shared projection now throws.
+            _intAnnotations.Freeze();
         }
 
         // Maps a ShapeNode annotation range to its int-offset range using the dense per-projection node

src/SIL.Machine/FiniteState/TraversalMethodBase.cs

@@ -18,7 +18,12 @@ internal abstract class TraversalMethodBase<TData, TOffset, TInst> : ITraversalM
         private bool _startAnchor;
         private bool _endAnchor;
         private bool _useDefaults;
-        private readonly List<Annotation<TOffset>> _annotations;
+
+        // Either this method's own scratch list (built by Reset) or a shared filtered view cached on
+        // a frozen AnnotationList (see Reset). When shared (_annotationsShared), it must never be
+        // mutated — traversal only reads it after Reset, so the only guarded site is Reset's Clear().
+        private List<Annotation<TOffset>> _annotations;
+        private bool _annotationsShared;
 
         // Instance free-list, kept across Reset() calls so a traversal method pooled for the
         // duration of one word (see Fst.Transduce + Morpher per-word reset) reuses instances across
@@ -34,7 +39,8 @@ internal abstract class TraversalMethodBase<TData, TOffset, TInst> : ITraversalM
         protected TraversalMethodBase(Fst<TData, TOffset> fst)
         {
             _fst = fst;
-            _annotations = new List<Annotation<TOffset>>();
+            // _annotations is created lazily in Reset: on the (common) cached-view hit path this
+            // method never needs a scratch list of its own.
             _cachedInstances = new Queue<TInst>();
             _insertAnnotation = InsertAnnotation;
         }
@@ -50,11 +56,49 @@ public void Reset(TData data, VariableBindings varBindings, bool startAnchor, bo
             _startAnchor = startAnchor;
             _endAnchor = endAnchor;
             _useDefaults = useDefaults;
-            _annotations.Clear();
+
+            // The filtered+sorted list built below depends only on (annotation list, filter,
+            // direction) — NOT on which FST asks — and on the sena grammar ~89% of Transduce calls
+            // re-derive a view that was already built for the same frozen list (COW clones share the
+            // frozen source's projection, and rule filters are a handful of compiler-cached lambdas).
+            // Frozen lists are immutable, so a cached view is final; unfrozen lists never cache
+            // (their annotations' FeatureStructs can be edited in place, silently invalidating a
+            // cached view).
+            AnnotationList<TOffset> annList = _data.Annotations;
+            bool cacheable = annList.IsFrozen;
+            if (cacheable)
+            {
+                List<Annotation<TOffset>> cached = annList.GetFilteredView(_fst.Filter, _fst.Direction);
+                if (cached != null)
+                {
+                    _annotations = cached;
+                    _annotationsShared = true;
+                    return;
+                }
+            }
+
+            if (_annotations == null || _annotationsShared)
+            {
+                _annotations = new List<Annotation<TOffset>>();
+                _annotationsShared = false;
+            }
+            else
+            {
+                _annotations.Clear();
+            }
             // insertion sort (PreorderTraverse with a cached delegate — same depth-first order as
             // GetNodesDepthFirst but no per-call yield-iterator allocation; see _insertAnnotation).
-            foreach (Annotation<TOffset> topAnn in _data.Annotations.GetNodes(_fst.Direction))
+            foreach (Annotation<TOffset> topAnn in annList.GetNodes(_fst.Direction))
                 topAnn.PreorderTraverse(_insertAnnotation, _fst.Direction);
+
+            if (cacheable)
+            {
+                // Publish for the next Transduce against the same frozen list. This method keeps
+                // using the (now-shared) list read-only; mark it shared so a hypothetical re-Reset
+                // of this method starts a fresh scratch list instead of clearing the published one.
+                annList.AddFilteredView(_fst.Filter, _fst.Direction, _annotations);
+                _annotationsShared = true;
+            }
         }
 
         private void InsertAnnotation(Annotation<TOffset> ann)