feat(caching): ServiceRef.ObservationOnly variant so ILogger doesn't uncacheable steps

The smart-caching planner's prior invariant — "any service dep makes
a step uncacheable, cascade to downstream consumers" — was correct
for domain services whose state can change a step's output
(IRemoteTimeService, ICustomerRepository) but wrong for pure
observation surfaces. Once we landed Create(ILogger logger) on
~half the example step library, every Flow that touched a
logger-declaring step became uncacheable end-to-end via the
cascade rule — a regression of the smart-caching system, not the
intended outcome of plumbing a logger through.

This change adds a third sealed variant to the ServiceRef closed
sum — ObservationOnly(Type ServiceType) — that DI-resolves
identically to CSharp but is skipped by CachePlanBuilder when
counting cache-affecting dependencies. The [FlowthruStep] source
generator recognises Microsoft.Extensions.Logging.ILogger by FQN
and emits the new variant for it; everything else still emits
CSharp. The "1 service dependency(ies)" message in the host log
now reflects only cache-affecting refs, so a step that declares
both a logger and a real service is still uncacheable but the
count is honest (e.g., SimpleEffectsExample's 2 → 1).

Three new CachePlanBuilder tests pin the contract:
  - ObservationOnly-only step stays fresh-eligible
  - ObservationOnly + regular dep still uncacheable, count excludes
    the observation ref
  - ObservationOnly parent doesn't cascade uncacheability to children

The existing StepLoggerInjectionTests.SourceGenerator_ExtractsILogger
test was renamed and the assertion updated to look for the
ObservationOnly variant.

ADR-0010 documents the design; src/core/CONTRIBUTING.md gets one
paragraph cross-linking it from the Engine Logging section.

User-side opt-in (an [ObservationOnly] attribute on Create() params
for arbitrary observability services) is the planned follow-up
when a second observation-only service surfaces — premature to
design without a real use case.

Author: Spelkington

.claude/docs/adr/0010-observation-only-service-refs.md

@@ -0,0 +1,3 @@
+# Observation-only service refs are a distinct case in the `ServiceRef` closed sum
+
+`ServiceRef` now has a third sealed nested variant — `ObservationOnly(Type ServiceType)` — alongside `CSharp` and `External`. The cache planner ([CachePlanBuilder.cs:119](/src/core/Flowthru.Core/Caching/CachePlanBuilder.cs#L119)) skips refs of this variant when counting cache-affecting dependencies, so steps that declare only observation-only services (the canonical case is `ILogger` per [ADR-0005](./0005-step-logging-via-shared-ilogger.md)) remain cache-eligible and don't cascade uncacheability through their downstream consumers. DI resolution is identical to `CSharp` — the `ServiceType` is the lookup key against the host's `IServiceProvider` — but the planner treats the dep as cache-neutral because observation surfaces can't change the step's output values, only the IO timeline. Recognition happens at source-generation time: the `[FlowthruStep]` generator emits `ServiceRef.ObservationOnly(...)` when a `Create()` parameter's fully-qualified type matches a hardcoded set (currently just `Microsoft.Extensions.Logging.ILogger`); a future per-parameter `[ObservationOnly]` attribute is the planned opt-in for user-defined observability services. The variant exists because the smart-caching planner's prior invariant — "any service dep makes a step uncacheable" — is correct for domain services whose state can change the step's output (e.g., `IRemoteTimeService`) but wrong for pure observation surfaces, and without the carve-out declaring a logger uncacheabilises every Flow in the workspace via the cascade rule.

src/core/CONTRIBUTING.md

@@ -53,6 +53,8 @@ Engine components (`FlowthruService`, `ParallelFlowScheduler`, future schedulers
 
 `FlowthruActivitySource` still emits trace spans (`flowthru.run`, `flowthru.preflight`, `flowthru.step`) for OpenTelemetry and other distributed-tracing consumers — that was always activities' real job. The CLI-side `FlowthruActivityLogger` bridge that translated those activities into log lines has been retired; see [.claude/docs/adr/0006-engine-logs-directly-retire-activity-bridge.md](/.claude/docs/adr/0006-engine-logs-directly-retire-activity-bridge.md). The step-side convention (`Create(ILogger)`) lives in [/examples/CONTRIBUTING.md](/examples/CONTRIBUTING.md) and [.claude/docs/adr/0005-step-logging-via-shared-ilogger.md](/.claude/docs/adr/0005-step-logging-via-shared-ilogger.md).
 
+The smart-caching planner treats `ILogger` as **cache-neutral** — the source generator emits it as `ServiceRef.ObservationOnly` rather than `ServiceRef.CSharp`, so a step that declares only a logger remains cache-eligible (and its downstream consumers don't inherit uncacheability via the cascade rule). See [.claude/docs/adr/0010-observation-only-service-refs.md](/.claude/docs/adr/0010-observation-only-service-refs.md). Steps that declare both a regular service and a logger still cascade through the regular dep — `ObservationOnly` doesn't change *what* gets resolved, only *whether* the planner counts the dep when deciding cacheability.
+
 ## Prelude
 
 `Flowthru.Prelude` houses the FP primitives the rest of Core builds on — `FlowIO<T>`, `EffResult<A>`, `Validated<TError, TValue>`, `FlowUnit`, `FlowResource`, plus the `IFlowResource` interface.
@@ -90,3 +92,12 @@ _Avoid_: helper method, fluent API
 
 **Applicative vs monadic composition**: Two ways to chain operations on a closed sum. *Applicative* (`Zip`, `ZipAll`) accumulates errors from all branches — for pre-flight validation where every problem should surface at once. *Monadic* (`Bind`, LINQ `from`/`in`/`select`) short-circuits on the first error — for operations that genuinely depend on earlier success. Choose by asking: are these checks independent (applicative) or dependent (monadic)?
 _Avoid_: parallel vs sequential
+
+**Anchor**: A structured property in a Flowthru analyzer's emitted `Diagnostic` that ties the diagnostic to a specific [[DAG]] element — a Step, Item, Edge, Flow, or Schema. Read by Tool renderers (notably the planned VSCode Editor Frontend's F2 surface) to project the diagnostic onto a DAG canvas in addition to the source-positional squiggly. Composite by design: a diagnostic may carry multiple Anchors of mixed kinds (Step + Item + Edge for a "no producer" diagnostic), and the renderer prioritizes label-keyed Anchors over type-symbol fallbacks. See [ADR-0009](/.claude/docs/adr/0009-diagnostic-anchor-contract.md) for the contract.
+_Avoid_: "tag" (Roslyn already uses `DiagnosticTag` for orthogonal concerns), "location" (Roslyn's `Location` is source-positional; an Anchor is semantic — it identifies a DAG element, not a span).
+
+**Anchor block**: The complete set of `Flowthru.Anchor.*` property keys carried by a single diagnostic. Always uses numbered keys (`.0`, `.1`, …) even for single-anchor diagnostics — symmetry over special cases. A diagnostic's Anchor block is built via `FlowthruAnchor.Builder()` and attached at `CreateFlowthruDiagnostic` time; the extension-method pattern follows the Roslyn idiom (see `Roslyn.Diagnostics.Analyzers/Core/DiagnosticExtensions.cs`) rather than introducing a `FlowthruAnalyzer` base class.
+_Avoid_: "anchor set" (suggests unordered; the numbered indices are ordered for renderer stability), "property bag" (too generic — every Roslyn diagnostic has properties; the Anchor block is the specifically-keyed subset).
+
+**`Anchor.None` sentinel**: Explicit "this diagnostic has no DAG meaning" marker, carried as `Flowthru.Anchor.None = "true"` in lieu of any kind-keyed Anchor. Used by diagnostics about authoring shape that don't correspond to any node or edge in a Flow Dev's DAG — extension-capability mismatches, analyzer-test scaffolding, source-generator preconditions. The sentinel disambiguates *intentional* unanchorability from *forgotten* anchoring; the test convention treats a missing Anchor block (no kind-keyed entries and no sentinel) as a failure.
+_Avoid_: omitting the block entirely (silent omission is ambiguous between "unanchorable" and "the analyzer author forgot"; the sentinel makes intent explicit).

src/core/Flowthru.Core.SourceGenerators/Step/StepMetadataGenerator.cs

@@ -57,6 +57,22 @@ public sealed class StepMetadataGenerator : IIncrementalGenerator
   /// </summary>
   private const int CodeVersionHexLength = 16;
 
+  /// <summary>
+  /// Fully-qualified type names of framework-recognised observation-
+  /// only services. When a <c>Create()</c> parameter's FQN matches an
+  /// entry here, the generator emits a <c>ServiceRef.ObservationOnly</c>
+  /// instead of the default <c>ServiceRef.CSharp</c> — the cache
+  /// planner skips observation-only refs when deciding step
+  /// cacheability (ADR-0010). Keep this set tiny; an
+  /// <c>[ObservationOnly]</c> per-parameter attribute is the planned
+  /// opt-in mechanism for user-defined observability services.
+  /// </summary>
+  private static readonly System.Collections.Generic.HashSet<string> _observationOnlyFqns =
+    new(System.StringComparer.Ordinal)
+    {
+      "global::Microsoft.Extensions.Logging.ILogger",
+    };
+
   /// <inheritdoc/>
   public void Initialize(IncrementalGeneratorInitializationContext context)
   {
@@ -240,7 +256,8 @@ private static void Emit(SourceProductionContext ctx, StepInfo info)
     sb.AppendLine("  {");
     foreach (var fqn in info.ServiceTypeFqns)
     {
-      sb.AppendLine($"    new global::Flowthru.Validation.Runtime.ServiceRef.CSharp(typeof({fqn})),");
+      var variant = _observationOnlyFqns.Contains(fqn) ? "ObservationOnly" : "CSharp";
+      sb.AppendLine($"    new global::Flowthru.Validation.Runtime.ServiceRef.{variant}(typeof({fqn})),");
     }
     sb.AppendLine("  };");
     sb.AppendLine("}");

src/core/Flowthru.Core/Caching/CachePlanBuilder.cs

@@ -116,11 +116,20 @@ public static async Task<CachePlan> BuildAsync(
         uncacheableReasons[step.Label] = new StepUncacheableReason.NoCodeVersion();
         continue;
       }
-      if (step.ServiceDependencies.Count > 0)
+      // Cache-affecting deps only. ServiceRef.ObservationOnly variants
+      // (e.g., ILogger) are skipped — per ADR-0010, observation surfaces
+      // can't change a step's output values, so their presence or
+      // identity doesn't invalidate a cached result. Without this
+      // filter, declaring a logger on a Create() factory would
+      // uncacheabilise the step and cascade through every downstream
+      // consumer.
+      var cacheAffectingDeps = step.ServiceDependencies
+        .Count(r => r is not ServiceRef.ObservationOnly);
+      if (cacheAffectingDeps > 0)
       {
         uncacheable.Add(step.Label);
         uncacheableReasons[step.Label] = new StepUncacheableReason.HasServiceDependencies(
-          step.ServiceDependencies.Count);
+          cacheAffectingDeps);
         continue;
       }
 

src/core/Flowthru.Core/Validation/Runtime/ServiceRef.cs

@@ -59,6 +59,40 @@ public sealed record External(IExtensionServiceRef Cause) : ServiceRef
     public override string DisplayName => Cause.DisplayName;
   }
 
+  /// <summary>
+  /// A C# service identified by an interface or class type, classified
+  /// as <em>observation-only</em>: its calls don't affect the step's
+  /// output values, only the IO timeline. DI resolution is identical
+  /// to <see cref="CSharp"/> — the <see cref="ServiceType"/> is the
+  /// lookup key used against the host's
+  /// <see cref="System.IServiceProvider"/> at runtime — but the cache
+  /// planner skips refs of this variant when deciding step
+  /// cacheability. The canonical (and currently only) recognised case
+  /// is <c>Microsoft.Extensions.Logging.ILogger</c>; the
+  /// <c>[FlowthruStep]</c> source generator emits this variant when a
+  /// <c>Create()</c> parameter's fully-qualified type matches a
+  /// hardcoded set.
+  /// </summary>
+  /// <remarks>
+  /// <para>
+  /// Per ADR-0010, this variant exists because the smart-caching
+  /// planner's invariant is "any service dep makes a step
+  /// uncacheable" (and cascades downstream) — true for domain
+  /// services whose state can change the step's output (e.g.,
+  /// <c>IRemoteTimeService</c>) but wrong for pure observation
+  /// surfaces. Without this carve-out, declaring a logger
+  /// uncacheabilises every Flow in the workspace.
+  /// </para>
+  /// </remarks>
+  public sealed record ObservationOnly(Type ServiceType) : ServiceRef
+  {
+    /// <inheritdoc/>
+    public override string DagId => ServiceType.FullName ?? ServiceType.Name;
+
+    /// <inheritdoc/>
+    public override string DisplayName => ServiceType.Name;
+  }
+
   /// <summary>Build a <see cref="CSharp"/> ref from a generic type parameter.</summary>
   public static ServiceRef Of<TService>() where TService : class =>
     new CSharp(typeof(TService));

tests/core/Flowthru.Core.Tests/Caching/CachePlanBuilderTests.cs

@@ -350,6 +350,102 @@ public async Task UncacheableReason_ServiceDependencies_CarriesCount()
     Assert.That(((StepUncacheableReason.HasServiceDependencies)reason).Count, Is.EqualTo(2));
   }
 
+  // ── ObservationOnly carve-out (ADR-0010) ────────────────────────────
+
+  [Test]
+  public async Task ObservationOnlyDeps_DoNotMarkStepUncacheable()
+  {
+    // ADR-0010: ServiceRef.ObservationOnly variants (e.g., ILogger)
+    // are skipped when computing cache eligibility — observation
+    // surfaces don't affect step output values, so their presence
+    // can't invalidate a cached result.
+    var input = new FakeFingerprintItem<int>("in", fingerprint: "fp-in", exists: true);
+    var output = new FakeFingerprintItem<int>("out", fingerprint: "fp-out", exists: true);
+    var step = MakeStep(
+      label: "transform", codeVersion: "code-v1",
+      input: input, output: output,
+      serviceDependencies: new ServiceRef[]
+      {
+        new ServiceRef.ObservationOnly(typeof(Microsoft.Extensions.Logging.ILogger)),
+      });
+
+    var composite = CachePlanBuilder.ComposeStepFingerprint(
+      "code-v1", new[] { ("in", "fp-in") });
+    var manifest = Manifest(
+      steps: new[] { ("transform", composite) },
+      items: new[] { ("in", "fp-in") });
+
+    var plan = await CachePlanBuilder.BuildAsync(BuildFlow(step), manifest);
+
+    Assert.That(plan.FreshStepLabels, Is.EquivalentTo(new[] { "transform" }),
+      "A step with only observation-only deps must remain eligible for caching when "
+      + "its inputs and code version match the manifest.");
+    Assert.That(plan.UncacheableStepLabels, Is.Empty,
+      "Observation-only deps must not push the step into the uncacheable bucket.");
+  }
+
+  [Test]
+  public async Task ObservationOnlyPlusRegularDep_StillUncacheable_CountExcludesObservation()
+  {
+    // The carve-out is for observation-only refs specifically; a step
+    // that also declares a regular service dep is still uncacheable.
+    // The reason's Count surfaces only the cache-affecting deps so
+    // the developer-facing message stays meaningful.
+    var input = new FakeFingerprintItem<int>("in", fingerprint: "fp-in", exists: true);
+    var output = new FakeFingerprintItem<int>("out", fingerprint: "fp-out", exists: true);
+    var step = MakeStep(
+      label: "transform", codeVersion: "code-v1",
+      input: input, output: output,
+      serviceDependencies: new ServiceRef[]
+      {
+        new ServiceRef.ObservationOnly(typeof(Microsoft.Extensions.Logging.ILogger)),
+        ServiceRef.Of<object>(),
+      });
+
+    var plan = await CachePlanBuilder.BuildAsync(BuildFlow(step), CacheManifest.Empty);
+
+    Assert.That(plan.UncacheableStepLabels, Is.EquivalentTo(new[] { "transform" }));
+    var reason = plan.UncacheableReasons["transform"];
+    Assert.That(reason, Is.TypeOf<StepUncacheableReason.HasServiceDependencies>());
+    Assert.That(((StepUncacheableReason.HasServiceDependencies)reason).Count, Is.EqualTo(1),
+      "Count surfaces cache-affecting deps only — the ObservationOnly logger is excluded.");
+  }
+
+  [Test]
+  public async Task ObservationOnlyParent_DoesNotCascadeUncacheabilityToChildren()
+  {
+    // The original motivation for ADR-0010 was the cascade: an
+    // ILogger-declaring parent step uncacheabilised every downstream
+    // consumer too. With the carve-out the parent is cache-eligible,
+    // so the cascade rule has nothing to propagate.
+    var seedInput = new FakeFingerprintItem<int>("seed", fingerprint: "fp-seed", exists: true);
+    var mid = new FakeFingerprintItem<int>("mid", fingerprint: "fp-mid", exists: true);
+    var output = new FakeFingerprintItem<int>("out", fingerprint: "fp-out", exists: true);
+    var stepA = MakeStep(
+      label: "A", codeVersion: "code-A-v1",
+      input: seedInput, output: mid,
+      serviceDependencies: new ServiceRef[]
+      {
+        new ServiceRef.ObservationOnly(typeof(Microsoft.Extensions.Logging.ILogger)),
+      });
+    var stepB = MakeStep("B", "code-B-v1", mid, output);
+
+    var compositeA = CachePlanBuilder.ComposeStepFingerprint(
+      "code-A-v1", new[] { ("seed", "fp-seed") });
+    var compositeB = CachePlanBuilder.ComposeStepFingerprint(
+      "code-B-v1", new[] { ("mid", "fp-mid") });
+    var manifest = Manifest(
+      steps: new[] { ("A", compositeA), ("B", compositeB) },
+      items: new[] { ("seed", "fp-seed"), ("mid", "fp-mid") });
+
+    var plan = await CachePlanBuilder.BuildAsync(BuildFlow(stepA, stepB), manifest);
+
+    Assert.That(plan.UncacheableStepLabels, Is.Empty,
+      "Observation-only deps on the parent must not cascade into the child.");
+    Assert.That(plan.FreshStepLabels, Is.EquivalentTo(new[] { "A", "B" }),
+      "Both steps eligible and matching the manifest → both fresh.");
+  }
+
   [Test]
   public async Task UncacheableReason_UnfingerprintableInput_NamesItemLabel()
   {

tests/core/Flowthru.Core.Tests/Step/StepLoggerInjectionTests.cs

@@ -46,8 +46,9 @@ public static Func<IEnumerable<int>, IEnumerable<int>> Create(ILogger logger)
 /// (ADR-0005): a <c>[FlowthruStep]</c> class declares
 /// <see cref="ILogger"/> as a parameter on its <c>Create()</c>
 /// factory; the source generator extracts it as a
-/// <see cref="ServiceRef.CSharp"/>; the host resolves it through DI;
-/// the step's logged lines hit the captured provider.
+/// <see cref="ServiceRef.ObservationOnly"/> (ADR-0010); the host
+/// resolves it through DI; the step's logged lines hit the captured
+/// provider.
 /// </summary>
 [TestFixture]
 public class StepLoggerInjectionTests
@@ -62,22 +63,25 @@ public sealed class TestCatalog : CatalogAbstract
   }
 
   [Test]
-  public void SourceGenerator_ExtractsILoggerParameter_AsServiceRef()
+  public void SourceGenerator_ExtractsILoggerParameter_AsObservationOnlyServiceRef()
   {
     // The [FlowthruStep] generator inspects Create() parameter types
-    // and registers interface-typed params as ServiceRef.CSharp on the
+    // and registers interface-typed params as ServiceRefs on the
     // step's metadata. ILogger (non-generic) must round-trip through
     // this path so the engine's shared "Flowthru"-category logger is
-    // resolvable at flow-construction time.
+    // resolvable at flow-construction time — AND it must be emitted
+    // as the ObservationOnly variant (ADR-0010) so the cache planner
+    // doesn't cascade uncacheability from steps that only declare a
+    // logger.
     var entry = StepMetadataRegistry.TryGetEntry(typeof(FixtureLoggingStep));
     Assert.That(entry, Is.Not.Null,
       "ModuleInitializer should have registered the fixture step before any test runs.");
     Assert.That(
-      entry!.Services.OfType<ServiceRef.CSharp>()
+      entry!.Services.OfType<ServiceRef.ObservationOnly>()
         .Any(r => r.ServiceType == typeof(ILogger)),
       Is.True,
-      "Step metadata must record ILogger as a CSharp ServiceRef. Found: "
-        + string.Join(", ", entry.Services.Select(s => s.DisplayName))
+      "Step metadata must record ILogger as an ObservationOnly ServiceRef. Found: "
+        + string.Join(", ", entry.Services.Select(s => $"{s.GetType().Name}({s.DisplayName})"))
     );
   }