fix: efcore forward look at query shapes

Author: Spelkington

src/core/Flowthru.Core/Flows/Flow.cs

@@ -7,6 +7,7 @@
 using Flowthru.Core.Graph.Meta.Models;
 using Flowthru.Core.Graph.Scheduling;
 using Flowthru.Core.Graph.Validation;
+using Flowthru.Core.Results;
 using Microsoft.Extensions.Logging;
 
 namespace Flowthru.Core.Flows;
@@ -772,12 +773,37 @@ CancellationToken cancellationToken
 
       return FlowResult.CreateSuccess(stopwatch.Elapsed, stepResults, Name);
     }
-    catch (OperationCanceledException)
+    catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
     {
-      // Re-throw — cancellation is not a failure but a requested abort.
+      // Caller-initiated abort — re-throw cleanly so hosts can distinguish a
+      // requested cancellation from a runtime failure.
       stopwatch.Stop();
       throw;
     }
+    catch (OperationCanceledException ex)
+    {
+      // Cancellation propagated past the executor without the caller asking
+      // for it — i.e., an internal stop-on-first-error cascade leaked the
+      // cancel out instead of cleanly returning partial results. By the
+      // FlowResult contract this is an unexpected escape, so wrap it in
+      // FlowExecutionEscapedException so the runtime-error classifier reports
+      // it as a possible framework bug instead of an external cancellation.
+      stopwatch.Stop();
+      var wrapped = new FlowExecutionEscapedException(
+        "Flow execution aborted by an unexpected cancellation that was not "
+          + "caller-initiated. This indicates a possible bug in Flowthru's "
+          + "execution path — the original cancellation is preserved as the "
+          + "inner exception.",
+        ex
+      );
+      Logger?.LogError(wrapped, "Flow execution aborted unexpectedly: {ErrorMessage}", ex.Message);
+      return FlowResult.CreateFailure(
+        stopwatch.Elapsed,
+        wrapped,
+        new Dictionary<string, StepResult>(),
+        Name
+      );
+    }
     catch (Exception ex)
     {
       stopwatch.Stop();

src/core/Flowthru.Core/Results/FlowExecutionEscapedException.cs

@@ -0,0 +1,37 @@
+namespace Flowthru.Core.Results;
+
+/// <summary>
+/// Marker exception that wraps any failure which escapes the normal
+/// <see cref="Flows.FlowResult"/> contract — i.e., a runtime failure that
+/// surfaced as a thrown exception rather than a structured step failure.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Flowthru's design invariant (see <c>CONTRIBUTING.md</c>) is that a flow which
+/// passes pre-flight checks should always complete successfully, with any
+/// step failure captured in <see cref="Flows.FlowResult"/>. When something
+/// throws past that boundary — for example, an internal cancellation cascade
+/// that leaks out of the executor before partial step results can be
+/// gathered — that's an unexpected escape of the contract and almost always
+/// indicates a Flowthru framework bug.
+/// </para>
+/// <para>
+/// Wrapping such a failure in <c>FlowExecutionEscapedException</c> lets the
+/// runtime-error reporting pipeline classify it correctly as
+/// <see cref="ErrorClassification.PossibleFrameworkBug"/> regardless of the
+/// inner exception's type — including allowlisted types like
+/// <see cref="OperationCanceledException"/> that would otherwise be mistaken
+/// for environmental failures.
+/// </para>
+/// </remarks>
+public sealed class FlowExecutionEscapedException : Exception
+{
+  /// <summary>
+  /// Creates a new <see cref="FlowExecutionEscapedException"/> wrapping an
+  /// underlying failure that escaped the FlowResult contract.
+  /// </summary>
+  /// <param name="message">Human-readable description of the escape.</param>
+  /// <param name="innerException">The original failure being wrapped.</param>
+  public FlowExecutionEscapedException(string message, Exception innerException)
+    : base(message, innerException) { }
+}

src/core/Flowthru.Core/Results/RuntimeErrorClassifier.cs

@@ -26,10 +26,20 @@ public static class RuntimeErrorClassifier
   /// <remarks>
   /// Walks the exception type's inheritance chain and checks inner exceptions.
   /// Any match against known external/environmental exception types produces
-  /// <see cref="ErrorClassification.ExternalError"/>.
+  /// <see cref="ErrorClassification.ExternalError"/>. A
+  /// <see cref="FlowExecutionEscapedException"/> short-circuits the inner-walk
+  /// and is always classified as <see cref="ErrorClassification.PossibleFrameworkBug"/>,
+  /// since by definition it represents a failure that escaped the FlowResult
+  /// contract — even if its inner exception happens to be allowlisted.
   /// </remarks>
   public static ErrorClassification Classify(Exception exception)
   {
+    // Explicit framework-bug marker takes precedence over any inner-exception
+    // heuristic. Without this short-circuit a leaked OperationCanceledException
+    // wrapped here would still classify as ExternalError via the inner walk.
+    if (exception is FlowExecutionEscapedException)
+      return ErrorClassification.PossibleFrameworkBug;
+
     if (IsExternal(exception))
       return ErrorClassification.ExternalError;
 

src/core/Flowthru.Core/Services/FlowthruService.cs

@@ -7,6 +7,7 @@
 using Flowthru.Core.Graph.Validation;
 using Flowthru.Core.Meta;
 using Flowthru.Core.Meta.Providers;
+using Flowthru.Core.Results;
 using Flowthru.Core.Services.Models;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Logging;
@@ -223,8 +224,43 @@ public async Task<FlowResult> ExecuteFlowAsync(
     _logger.LogInformation("════════════════════════════════════════");
     _logger.LogInformation("");
 
-    // Execute merged pipeline
-    var result = await mergedPipeline.RunAsync(options, cancellationToken);
+    // Execute merged pipeline.
+    //
+    // Service-level safety net: anything that escapes Flow.RunAsync past the
+    // FlowResult contract is, by definition, an unexpected runtime escape. The
+    // wrap below ensures the user-facing formatter still gets a chance to fire
+    // (with the "please file an issue" framing) before the exception reaches
+    // the host. Caller-initiated cancellation propagates clean — that's a
+    // user-requested abort, not a Flowthru failure.
+    FlowResult result;
+    try
+    {
+      result = await mergedPipeline.RunAsync(options, cancellationToken);
+    }
+    catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
+    {
+      throw;
+    }
+    catch (Exception ex)
+    {
+      var wrapped =
+        ex as FlowExecutionEscapedException
+        ?? new FlowExecutionEscapedException(
+          "Flow execution failed with an exception that escaped the FlowResult "
+            + "contract. This is unexpected — pre-flight should have caught the "
+            + "underlying issue before runtime. The original exception is "
+            + "preserved as the inner exception.",
+          ex
+        );
+      var synthetic = FlowResult.CreateFailure(
+        executionTime: totalStopwatch.Elapsed,
+        exception: wrapped,
+        stepResults: new Dictionary<string, StepResult>(),
+        flowName: "Pipeline"
+      );
+      options.GetFormatter().Format(synthetic, _logger);
+      throw;
+    }
 
     // Export post-run metadata — fires only after real executions (dry run returns above)
     if (_metadataBuilder != null)