perf: optimize scheduler fast paths

- Keep dependency links across runs and clean stale links by tracking
  version instead of full clear/rebuild.
- Add per-run dependency cursors and fast paths for computed/effect
  tracking to reduce fallback scans.
- Improve propagation/flush behavior with queue-draining fixes,
  selective computed deferral, and ordering optimizations.
- Add low-overhead freshness/notify fast paths (global version stamp,
  direct-effect notify path, computed-subscriber metadata).

Author: brnrdog

packages/rescript-signals/src/signals/Core.res

@@ -6,74 +6,99 @@ let flag_dirty = 1
 let flag_pending = 2
 let flag_running = 4
 
-// Observer kind tag
+// Global tracking version
+let trackingVersion: ref<int> = ref(0)
+// Global mutation version (increments on real signal writes)
+let globalVersion: ref<int> = ref(0)
+
 type kind = [#Effect | #Computed]
 
-// Forward declare mutually recursive types
-type rec link = {
-  // Direct reference to signal's subscriber list (type-erased)
-  mutable subs: subs,
-  // Direct reference to observer
-  mutable observer: observer,
-  // Links in the observer's dependency chain
-  mutable nextDep: option<link>,
-  mutable prevDep: option<link>,
-  // Links in the signal's subscriber chain
-  mutable nextSub: option<link>,
-  mutable prevSub: option<link>,
-}
+module rec Link: {
+  type t = {
+    // Direct reference to signal's subscriber list (type-erased)
+    mutable subs: Subs.t,
+    // Direct reference to observer
+    mutable observer: Observer.t,
+    // Links in the observer's dependency chain
+    mutable nextDep: option<Link.t>,
+    mutable prevDep: option<Link.t>,
+    // Links in the signal's subscriber chain
+    mutable nextSub: option<Link.t>,
+    mutable prevSub: option<Link.t>,
+    // Version stamp for duplicate detection within a compute cycle
+    mutable lastTrackedVersion: int,
+  }
+} = Link
 
 // Signal subscriber list (head/tail of linked list)
 // For computeds, this same object also serves as the observer (combined structure)
-and subs = {
-  mutable first: option<link>,
-  mutable last: option<link>,
-  mutable version: int,
-  // === Observer fields (only used for computeds) ===
-  // If compute is Some, this subs is a computed signal
-  mutable compute: option<unit => unit>,
-  mutable firstDep: option<link>,
-  mutable lastDep: option<link>,
-  mutable flags: int,
-  mutable level: int,
-}
+and Subs: {
+  type t = {
+    mutable first: option<Link.t>,
+    mutable last: option<Link.t>,
+    mutable computedSubscriberCount: int,
+    mutable version: int,
+    // === Observer fields (only used for computeds) ===
+    // If compute is Some, this subs is a computed signal
+    mutable compute: option<unit => unit>,
+    mutable firstDep: option<Link.t>,
+    mutable lastDep: option<Link.t>,
+    mutable flags: int,
+    mutable level: int,
+    mutable deferEffectsUntilRecompute: bool,
+    mutable lastGlobalVersion: int,
+  }
+} = Subs
 
 // Observer for effects only (computeds use subs directly)
-and observer = {
-  id: int,
-  kind: kind,
-  run: unit => unit,
-  mutable firstDep: option<link>,
-  mutable lastDep: option<link>,
-  mutable flags: int,
-  mutable level: int,
-  name: option<string>,
-  // For computed observers: direct reference to backing subs (the combined object)
-  mutable backingSubs: option<subs>,
-}
+and Observer: {
+  type t = {
+    id: int,
+    kind: kind,
+    run: unit => unit,
+    mutable firstDep: option<Link.t>,
+    mutable lastDep: option<Link.t>,
+    mutable flags: int,
+    mutable level: int,
+    name: option<string>,
+    // For computed observers: direct reference to backing subs (the combined object)
+    mutable backingSubs: option<Subs.t>,
+  }
+} = Observer
+
+// Type aliases for convenience
+type link = Link.t
+type subs = Subs.t
+type observer = Observer.t
 
 // Create empty subscriber list (for plain signals)
 let makeSubs = (): subs => {
   first: None,
   last: None,
+  computedSubscriberCount: 0,
   version: 0,
   compute: None,
   firstDep: None,
   lastDep: None,
   flags: 0,
   level: 0,
+  deferEffectsUntilRecompute: false,
+  lastGlobalVersion: 0,
 }
 
 // Create subs for a computed (with compute function)
-let makeComputedSubs = (compute: unit => unit): subs => {
+let makeComputedSubs = (compute: unit => unit, ~deferEffectsUntilRecompute: bool=false): subs => {
   first: None,
   last: None,
+  computedSubscriberCount: 0,
   version: 0,
   compute: Some(compute),
   firstDep: None,
   lastDep: None,
   flags: flag_dirty, // start dirty
   level: 0,
+  deferEffectsUntilRecompute,
+  lastGlobalVersion: 0,
 }
 
 // Create observer
@@ -95,7 +120,7 @@ let makeObserver = (
   backingSubs,
 }
 
-// Flag operations for observer (using Int.Bitwise module)
+// Flag operations for observer
 let isDirty = (o: observer): bool => Int.bitwiseAnd(o.flags, flag_dirty) !== 0
 let setDirty = (o: observer): unit => o.flags = Int.bitwiseOr(o.flags, flag_dirty)
 let clearDirty = (o: observer): unit =>
@@ -105,7 +130,7 @@ let setPending = (o: observer): unit => o.flags = Int.bitwiseOr(o.flags, flag_pe
 let clearPending = (o: observer): unit =>
   o.flags = Int.bitwiseAnd(o.flags, Int.bitwiseNot(flag_pending))
 
-// Flag operations for subs (for computeds - subs IS the observer)
+// Flag operations for subs
 let isSubsDirty = (s: subs): bool => Int.bitwiseAnd(s.flags, flag_dirty) !== 0
 let setSubsDirty = (s: subs): unit => s.flags = Int.bitwiseOr(s.flags, flag_dirty)
 let clearSubsDirty = (s: subs): unit =>
@@ -115,17 +140,20 @@ let setSubsPending = (s: subs): unit => s.flags = Int.bitwiseOr(s.flags, flag_pe
 let clearSubsPending = (s: subs): unit =>
   s.flags = Int.bitwiseAnd(s.flags, Int.bitwiseNot(flag_pending))
 
-// Check if subs is a computed (has compute function)
+// Check if subs is a computed
 let isComputed = (s: subs): bool => s.compute !== None
 
 // Create a link node
-let makeLink = (subs: subs, observer: observer): link => {
-  subs,
-  observer,
-  nextDep: None,
-  prevDep: None,
-  nextSub: None,
-  prevSub: None,
+let makeLink = (sourceSubs: subs, linkedObserver: observer): link => {
+  {
+    subs: sourceSubs,
+    observer: linkedObserver,
+    nextDep: None,
+    prevDep: None,
+    nextSub: None,
+    prevSub: None,
+    lastTrackedVersion: 0,
+  }
 }
 
 // Add link to signal's subscriber list
@@ -137,6 +165,11 @@ let linkToSubs = (subs: subs, link: link): unit => {
   | None => subs.first = Some(link)
   }
   subs.last = Some(link)
+
+  let linkedSubs = (Obj.magic(link.observer): subs)
+  if isComputed(linkedSubs) {
+    subs.computedSubscriberCount = subs.computedSubscriberCount + 1
+  }
 }
 
 // Add link to observer's dependency list
@@ -163,6 +196,11 @@ let unlinkFromSubs = (link: link): unit => {
   }
   link.prevSub = None
   link.nextSub = None
+
+  let linkedSubs = (Obj.magic(link.observer): subs)
+  if isComputed(linkedSubs) && subs.computedSubscriberCount > 0 {
+    subs.computedSubscriberCount = subs.computedSubscriberCount - 1
+  }
 }
 
 // Remove link from dependency list
@@ -179,6 +217,20 @@ let unlinkFromDeps = (observer: observer, link: link): unit => {
   link.nextDep = None
 }
 
+// Remove link from subs's dependency list (for computeds - subs IS the observer)
+let unlinkFromSubsDeps = (s: subs, link: link): unit => {
+  switch link.prevDep {
+  | Some(prev) => prev.nextDep = link.nextDep
+  | None => s.firstDep = link.nextDep
+  }
+  switch link.nextDep {
+  | Some(next) => next.prevDep = link.prevDep
+  | None => s.lastDep = link.prevDep
+  }
+  link.prevDep = None
+  link.nextDep = None
+}
+
 // Clear all dependencies from observer (unlinks from all signals)
 let clearDeps = (observer: observer): unit => {
   let link = ref(observer.firstDep)