feat: Speculative CFG discovery

Author: kevinferrare

SPECULATIVE_CFG_EXPLORATION.md

@@ -357,4 +357,17 @@ public sealed class Configuration : CommandSettings {
     [CommandOption("--AllowIvtAddress0")]
     public bool AllowIvtAddress0 { get; init; }
 
+    /// <summary>
+    /// When true (default), the speculative CFG explorer is enabled: after each newly-observed
+    /// instruction is parsed, the explorer performs a recursive-descent static decode of all
+    /// statically-reachable successors that have not yet been observed, marking the resulting nodes
+    /// as speculative. This allows the C# code generator to emit real branches for unobserved
+    /// conditional arms instead of always falling back to <c>FailAsUntested</c>.
+    /// When false, no speculative nodes, edges, or index entries are created; the graph content is
+    /// byte-identical to the pre-feature baseline.
+    /// </summary>
+    [CommandOption("--EnableSpeculativeCfgExploration <ENABLESPECULATIVECFGEXPLORATION>")]
+    [DefaultValue(true)]
+    public bool EnableSpeculativeCfgExploration { get; init; } = true;
+
 }

SPECULATIVE_CFG_IMPLEMENTATION_PLAN.md

@@ -34,14 +34,14 @@ public CfgCpu(IMemory memory, State state, IOPortDispatcher ioPortDispatcher, Ca
         DualPic dualPic, EmulatorBreakpointsManager emulatorBreakpointsManager,
         IPauseHandler pauseHandler,
         FunctionCatalogue functionCatalogue,
-        bool useCodeOverride, bool failOnInvalidOpcode, bool allowIvtAddress0, ILoggerService loggerService, CfgNodeExecutionCompiler executionCompiler, SequentialIdAllocator idAllocator, CpuHeavyLogger? cpuHeavyLogger = null) {
+        bool useCodeOverride, bool failOnInvalidOpcode, bool allowIvtAddress0, bool enableSpeculativeExploration, ILoggerService loggerService, CfgNodeExecutionCompiler executionCompiler, SequentialIdAllocator idAllocator, CpuHeavyLogger? cpuHeavyLogger = null) {
         _loggerService = loggerService;
         _state = state;
         _dualPic = dualPic;
         _cpuHeavyLogger = cpuHeavyLogger;
         _emulatorBreakpointsManager = emulatorBreakpointsManager;
         _pauseHandler = pauseHandler;
-        CfgNodeFeeder = new(memory, state, emulatorBreakpointsManager, _replacerRegistry, executionCompiler, idAllocator);
+        CfgNodeFeeder = new(memory, state, emulatorBreakpointsManager, _replacerRegistry, executionCompiler, idAllocator, enableSpeculativeExploration);
         _executionContextManager = new(memory, state, CfgNodeFeeder, _replacerRegistry, functionCatalogue, useCodeOverride, loggerService, cpuHeavyLogger);
         _instructionExecutionHelper = new(state, memory, ioPortDispatcher, callbackHandler, emulatorBreakpointsManager, _executionContextManager, failOnInvalidOpcode, allowIvtAddress0, loggerService);
     }

src/Spice86.Core/CLI/Configuration.cs

@@ -23,6 +23,12 @@ public sealed class CfgBlock : CfgNode {
     /// </summary>
     private int _nonLiveCounter;
 
+    /// <summary>
+    /// Number of contained nodes whose <see cref="ICfgNode.IsSpeculative"/> is currently <c>true</c>.
+    /// <see cref="IsSpeculative"/> is <c>(_speculativeCounter &gt; 0)</c>.
+    /// </summary>
+    private int _speculativeCounter;
+
     private BlockNode? _cachedDisplayAst;
     private bool _isDisplayAstStale = true;
 
@@ -50,6 +56,13 @@ public CfgBlock(int id, ICfgNode entry)
     /// </remarks>
     public override bool IsLive => _nonLiveCounter == 0;
 
+    /// <inheritdoc />
+    /// <remarks>
+    /// O(1). The block is speculative iff at least one contained instruction is speculative;
+    /// computed from the maintained <see cref="_speculativeCounter"/> without iterating.
+    /// </remarks>
+    public override bool IsSpeculative => _speculativeCounter > 0;
+
     /// <inheritdoc />
     /// <remarks>
     /// Always <c>null</c>: a <see cref="CfgBlock"/> is itself the container, not contained in one.
@@ -140,19 +153,22 @@ public override IVisitableAstNode DisplayAst {
 
     /// <summary>
     /// Appends <paramref name="node"/> to the end of the block, making it the new
-    /// <see cref="Terminator"/>. Updates the non-live counter from the node's live state.
+    /// <see cref="Terminator"/>. Updates the non-live and speculative counters from the node's state.
     /// </summary>
     internal void Append(ICfgNode node) {
         _instructions.Add(node);
         if (!node.IsLive) {
             _nonLiveCounter++;
         }
+        if (node.IsSpeculative) {
+            _speculativeCounter++;
+        }
         _isDisplayAstStale = true;
     }
 
     /// <summary>
     /// Replaces the node at <paramref name="index"/> with <paramref name="newNode"/>, preserving
-    /// order. Adjusts the non-live counter to reflect the new node's live state.
+    /// order. Adjusts the non-live and speculative counters to reflect the new node's state.
     /// </summary>
     internal void ReplaceInPlace(int index, ICfgNode newNode) {
         ICfgNode old = _instructions[index];
@@ -163,18 +179,25 @@ internal void ReplaceInPlace(int index, ICfgNode newNode) {
         if (!newNode.IsLive) {
             _nonLiveCounter++;
         }
+        if (old.IsSpeculative) {
+            _speculativeCounter--;
+        }
+        if (newNode.IsSpeculative) {
+            _speculativeCounter++;
+        }
         _isDisplayAstStale = true;
     }
 
     /// <summary>
     /// Removes nodes from <paramref name="splitIndex"/> through the end and returns them as a
-    /// new list. The non-live counter is recomputed for the surviving prefix.
+    /// new list. The non-live and speculative counters are recomputed for the surviving prefix.
     /// </summary>
     internal List<ICfgNode> SliceFrom(int splitIndex) {
         int tailLength = _instructions.Count - splitIndex;
         List<ICfgNode> tail = _instructions.GetRange(splitIndex, tailLength);
         _instructions.RemoveRange(splitIndex, tailLength);
         RecountNonLiveFromInstructions();
+        RecountSpeculativeFromInstructions();
         _isDisplayAstStale = true;
         return tail;
     }
@@ -191,6 +214,18 @@ internal void OnContainedInstructionLiveChanged(bool nowLive) {
         }
     }
 
+    /// <summary>
+    /// Counter choke-point invoked by <see cref="CfgInstruction.SetSpeculative"/> exactly once per
+    /// actual <see cref="ICfgNode.IsSpeculative"/> transition of a contained instruction.
+    /// </summary>
+    internal void OnContainedInstructionSpeculativeChanged(bool nowSpeculative) {
+        if (nowSpeculative) {
+            _speculativeCounter++;
+        } else {
+            _speculativeCounter--;
+        }
+    }
+
     /// <summary>
     /// Recomputes the non-live counter from scratch by iterating the contained instructions.
     /// Used after a split to re-base the counter on the new instruction set.
@@ -199,6 +234,14 @@ internal void RecountNonLiveFromInstructions() {
         _nonLiveCounter = _instructions.Count(node => !node.IsLive);
     }
 
+    /// <summary>
+    /// Recomputes the speculative counter from scratch by iterating the contained instructions.
+    /// Used after a split to re-base the counter on the new instruction set.
+    /// </summary>
+    internal void RecountSpeculativeFromInstructions() {
+        _speculativeCounter = _instructions.Count(node => node.IsSpeculative);
+    }
+
     /// <summary>
     /// Returns the index of <paramref name="node"/> in the contained list, or <c>-1</c> if
     /// the node is not part of this block.

src/Spice86.Core/Emulator/CPU/CfgCpu/CfgCpu.cs

@@ -43,6 +43,21 @@ public CfgNodeExecutionAction<InstructionExecutionHelper> CompiledExecution {
     }
 
     public abstract bool IsLive { get; }
+
+    /// <summary>
+    /// Default is <c>false</c>. <see cref="ParsedInstruction.CfgInstruction"/> overrides this to
+    /// expose its stored speculative flag, maintained by <see cref="SetSpeculative"/> calls.
+    /// <see cref="SelectorNode"/> and <see cref="CfgBlock"/> keep the default <c>false</c>.
+    /// </summary>
+    public virtual bool IsSpeculative => false;
+
+    /// <summary>
+    /// No-op default: <see cref="SelectorNode"/> and <see cref="CfgBlock"/> have no speculative
+    /// state. <see cref="ParsedInstruction.CfgInstruction"/> overrides this to maintain its stored
+    /// flag and notify its containing block.
+    /// </summary>
+    public virtual void SetSpeculative(bool isSpeculative) {
+    }
 
     public abstract void UpdateSuccessorCache();
     public abstract ICfgNode? GetNextSuccessor(InstructionExecutionHelper helper);

src/Spice86.Core/Emulator/CPU/CfgCpu/ControlFlowGraph/CfgBlock.cs

@@ -37,6 +37,24 @@ public interface ICfgNode : IEquatable<ICfgNode> {
     /// </summary>
     bool IsLive { get; }
 
+    /// <summary>
+    /// Returns whether the node is speculative.
+    /// A speculative node was decoded by the static explorer from memory bytes but has never been
+    /// executed and confirmed. It is a separate axis from <see cref="IsLive"/>: a speculative node
+    /// is always non-live, but a non-live observed node (e.g. SMC-evicted) is not speculative.
+    /// Speculative nodes never enter <see cref="Feeder.CurrentInstructions"/>,
+    /// <see cref="Feeder.PreviousInstructions"/>, or a <see cref="ParsedInstruction.SelfModifying.SelectorNode"/>.
+    /// </summary>
+    bool IsSpeculative { get; }
+
+    /// <summary>
+    /// Updates the speculative provenance of this node. On an actual transition, keeps the
+    /// containing <see cref="CfgBlock"/>'s speculative counter in sync. Setting speculative also
+    /// forces the node non-live. No-op for node kinds that have no speculative state
+    /// (<see cref="ParsedInstruction.SelfModifying.SelectorNode"/>, <see cref="CfgBlock"/>).
+    /// </summary>
+    void SetSpeculative(bool isSpeculative);
+
     /// <summary>
     /// True when the node execution can lead to going back to previous execution context if the next to execute is the correct address
     /// </summary>

src/Spice86.Core/Emulator/CPU/CfgCpu/ControlFlowGraph/CfgNode.cs

@@ -121,6 +121,22 @@ private void RegisterCurrentInstructionAsEntryPoint(SegmentedAddress entryAddres
         nodes.Add(toExecute);
     }
 
+    /// <summary>
+    /// Registers <paramref name="node"/> as a CFG entry point so it is treated as a generation root by
+    /// the graph exporter and the function partitioner. Used to seed emulator-installed hardware
+    /// interrupt handlers: these fire on external events with nondeterministic timing and may never be
+    /// reached from the program's observed entry points during discovery, yet must still become
+    /// generated overrides so generated code can service the interrupt.
+    /// </summary>
+    /// <param name="node">The handler entry instruction to register.</param>
+    public void RegisterEntryPoint(CfgInstruction node) {
+        if (!ExecutionContextEntryPoints.TryGetValue(node.Address, out ISet<CfgInstruction>? nodes)) {
+            nodes = new HashSet<CfgInstruction>();
+            ExecutionContextEntryPoints.Add(node.Address, nodes);
+        }
+        nodes.Add(node);
+    }
+
     public override void ReplaceInstruction(CfgInstruction oldInstruction, CfgInstruction newInstruction) {
         if (ExecutionContextEntryPoints.TryGetValue(newInstruction.Address, out ISet<CfgInstruction>? entriesAtAddress)
             && entriesAtAddress.Remove(oldInstruction)) {

src/Spice86.Core/Emulator/CPU/CfgCpu/ControlFlowGraph/ICfgNode.cs

@@ -21,16 +21,27 @@ namespace Spice86.Core.Emulator.CPU.CfgCpu.Feeder;
 public class CfgNodeFeeder {
     private readonly State _state;
     private readonly NodeLinker _nodeLinker;
+    private readonly SpeculativeReachabilityPruner? _speculativePruner;
 
     public CfgNodeFeeder(IMemory memory, State state, EmulatorBreakpointsManager emulatorBreakpointsManager,
-        InstructionReplacerRegistry replacerRegistry, CfgNodeExecutionCompiler executionCompiler, SequentialIdAllocator idAllocator) {
+        InstructionReplacerRegistry replacerRegistry, CfgNodeExecutionCompiler executionCompiler, SequentialIdAllocator idAllocator,
+        bool enableSpeculativeExploration) {
         _state = state;
-        InstructionsFeeder = new(emulatorBreakpointsManager, memory, state, replacerRegistry, executionCompiler, idAllocator);
         _nodeLinker = new(replacerRegistry, executionCompiler, idAllocator);
+        InstructionsFeeder = new(emulatorBreakpointsManager, memory, state, replacerRegistry, executionCompiler, idAllocator,
+            enableSpeculativeExploration, enableSpeculativeExploration ? _nodeLinker : null);
+        if (enableSpeculativeExploration) {
+            SpeculativeReachabilityPruner pruner = new(_nodeLinker, InstructionsFeeder.NodeIndex);
+            _speculativePruner = pruner;
+            InstructionsFeeder.SetSpeculativePruner(pruner);
+        }
     }
 
     public InstructionsFeeder InstructionsFeeder { get; }
 
+    /// <summary>Persistent graph index spanning all nodes (observed + speculative).</summary>
+    public CfgNodeIndex NodeIndex => InstructionsFeeder.NodeIndex;
+
     /// <summary>
     /// Parses or retrieves from cache the instruction at the current IP from memory.
     /// May trigger SignatureReducer and InstructionReplacerRegistry side effects.
@@ -92,6 +103,19 @@ private ICfgNode ReconcileGraphWithMemory(ExecutionContext executionContext, ICf
                 $"From graph: {graphNodeAfterReconciliation}");
         }
 
+        // Provenance-gated path (Phase 5): when the stale graph node is speculative,
+        // either promote it (memory match) or discard-and-replace (mismatch).
+        // This must run BEFORE the generic SelectorNode path so that speculative nodes
+        // never enter a SelectorNode (Core Invariant 4).
+        if (graphNodeAfterReconciliation is CfgInstruction speculativeInGraph && speculativeInGraph.IsSpeculative) {
+            SpeculativePromoter? promoter = InstructionsFeeder.SpeculativePromoter;
+            if (speculativeInGraph.Signature.ListEquivalent(fromMemory.Signature.SignatureValue) && promoter is not null) {
+                return promoter.Promote(speculativeInGraph);
+            }
+            _speculativePruner?.Sweep(speculativeInGraph);
+            return fromMemory;
+        }
+
         // Genuinely different instructions at the same address. Inject a SelectorNode
         return _nodeLinker.CreateSelectorNodeBetween(fromMemory, (CfgInstruction)graphNodeAfterReconciliation);
     }

src/Spice86.Core/Emulator/CPU/CfgCpu/ExecutionContextManager.cs

@@ -0,0 +1,97 @@
+namespace Spice86.Core.Emulator.CPU.CfgCpu.Feeder;
+
+using Spice86.Core.Emulator.CPU.CfgCpu.ControlFlowGraph;
+using Spice86.Core.Emulator.CPU.CfgCpu.ParsedInstruction;
+using Spice86.Shared.Emulator.Memory;
+
+/// <summary>
+/// Persistent graph index keyed by <c>(address, signature)</c>, spanning all nodes (observed and
+/// speculative). Unlike the hot memory caches <see cref="CurrentInstructions"/> /
+/// <see cref="PreviousInstructions"/>, this index has no memory-state semantics and no eviction on
+/// write: it is a durable lookup table for the CFG explorer and the cold-path promotion logic.
+///
+/// <para>Implements <see cref="IInstructionReplacer"/> so that signature-reducer fan-out via
+/// <see cref="InstructionReplacerRegistry"/> keeps the index coherent: when two instructions are
+/// merged the old key is replaced by the new key.</para>
+/// </summary>
+public class CfgNodeIndex : InstructionReplacer {
+    private readonly Dictionary<SegmentedAddress, Dictionary<Signature, CfgInstruction>> _index = new();
+
+    /// <summary>
+    /// Set of addresses proven byte-unstable between explore-time and execution-time.
+    /// Speculation stops permanently at poisoned addresses.
+    /// </summary>
+    public HashSet<SegmentedAddress> PoisonSet { get; } = new();
+
+    public CfgNodeIndex(InstructionReplacerRegistry replacerRegistry) : base(replacerRegistry) {
+    }
+
+    /// <summary>
+    /// Inserts <paramref name="node"/> into the index.
+    /// Idempotent: a second insertion with the same <c>(address, signature)</c> key is a no-op.
+    /// </summary>
+    public void Insert(CfgInstruction node) {
+        Signature signature = node.Signature;
+        if (!_index.TryGetValue(node.Address, out Dictionary<Signature, CfgInstruction>? atAddress)) {
+            atAddress = new Dictionary<Signature, CfgInstruction>();
+            _index[node.Address] = atAddress;
+        }
+        atAddress.TryAdd(signature, node);
+    }
+
+    /// <summary>
+    /// Removes the single <c>(address, signature)</c> entry for <paramref name="node"/>.
+    /// Used only by the discard sweep; does not touch graph edges.
+    /// </summary>
+    public void Remove(CfgInstruction node) {
+        if (!_index.TryGetValue(node.Address, out Dictionary<Signature, CfgInstruction>? atAddress)) {
+            return;
+        }
+        atAddress.Remove(node.Signature);
+        if (atAddress.Count == 0) {
+            _index.Remove(node.Address);
+        }
+    }
+
+    /// <summary>
+    /// Returns the node at <c>(address, signature)</c>, or <c>null</c> if not present.
+    /// </summary>
+    public CfgInstruction? TryGet(SegmentedAddress address, Signature signature) {
+        if (!_index.TryGetValue(address, out Dictionary<Signature, CfgInstruction>? atAddress)) {
+            return null;
+        }
+        atAddress.TryGetValue(signature, out CfgInstruction? node);
+        return node;
+    }
+
+    /// <summary>
+    /// Returns all nodes indexed at <paramref name="address"/>, or an empty enumerable if none.
+    /// </summary>
+    public IEnumerable<CfgInstruction> GetAtAddress(SegmentedAddress address) {
+        if (!_index.TryGetValue(address, out Dictionary<Signature, CfgInstruction>? atAddress)) {
+            return [];
+        }
+        return atAddress.Values;
+    }
+
+    /// <summary>
+    /// Returns whether the index has any entry at <paramref name="address"/>.
+    /// </summary>
+    public bool HasAddress(SegmentedAddress address) => _index.ContainsKey(address);
+
+    /// <summary>
+    /// Handles signature-reducer fan-out: replaces the index entry for
+    /// <paramref name="oldInstruction"/> with <paramref name="newInstruction"/>.
+    /// </summary>
+    public override void ReplaceInstruction(CfgInstruction oldInstruction, CfgInstruction newInstruction) {
+        if (!_index.TryGetValue(oldInstruction.Address, out Dictionary<Signature, CfgInstruction>? atAddress)) {
+            return;
+        }
+        Signature oldSignature = oldInstruction.Signature;
+        if (!atAddress.TryGetValue(oldSignature, out CfgInstruction? incumbent) || !incumbent.Equals(oldInstruction)) {
+            return;
+        }
+        atAddress.Remove(oldSignature);
+        atAddress.TryAdd(newInstruction.Signature, newInstruction);
+    }
+}