refactor: iter2 minor — Normalizer/Polling/Idempotent via PatternKit (incl. dedup-on-failure bug fix)

.gitignore

@@ -30,6 +30,8 @@ bld/
 *.nupkg
 *.snupkg
 **/artifacts/
+# Exception: pre-release packages committed for CI bootstrap (removed once upstream publishes)
+!eng/local-feed/*.nupkg
 
 # Test Results
 [Tt]est[Rr]esult*/
@@ -50,7 +52,9 @@ docs/api/
 *.db-shm
 *.db-wal
 
-# Aspire AppHost and UITests use RestorePackagesWithLockFile=false; exclude their
-# ephemeral lock files that --use-lock-file can create at restore time.
+# These projects use RestorePackagesWithLockFile=false; exclude their ephemeral
+# lock files that --use-lock-file can create at restore time.
 src/WorkflowFramework.Dashboard.AppHost/packages.lock.json
 tests/WorkflowFramework.Dashboard.UITests/packages.lock.json
+tests/WorkflowFramework.Extensions.Approvals.Acceptance/packages.lock.json
+tests/WorkflowFramework.Extensions.Approvals.Integration.Tests/packages.lock.json

Directory.Packages.props

@@ -89,7 +89,7 @@
     <PackageVersion Include="Reqnroll.xUnit" Version="3.0.0" />
 
     <!-- PatternKit -->
-    <PackageVersion Include="PatternKit.Core" Version="0.112.0" />
+    <PackageVersion Include="PatternKit.Core" Version="0.113.0" />
 
     <!-- TinyBDD -->
     <PackageVersion Include="TinyBDD" Version="0.19.16" />

benchmarks/WorkflowFramework.Benchmarks/packages.lock.json

@@ -174,7 +174,8 @@
         "type": "Project",
         "dependencies": {
           "Microsoft.Extensions.DependencyInjection.Abstractions": "[10.0.5, )",
-          "Microsoft.Extensions.Hosting.Abstractions": "[10.0.5, )"
+          "Microsoft.Extensions.Hosting.Abstractions": "[10.0.5, )",
+          "PatternKit.Core": "[0.113.0, )"
         }
       },
       "workflowframework.extensions.diagnostics": {
@@ -246,6 +247,12 @@
           "Microsoft.Extensions.DependencyInjection.Abstractions": "10.0.5",
           "Microsoft.Extensions.Primitives": "10.0.5"
         }
+      },
+      "PatternKit.Core": {
+        "type": "CentralTransitive",
+        "requested": "[0.113.0, )",
+        "resolved": "0.113.0",
+        "contentHash": "gnHABPF+MK6UmTm3Q0q6UjN1ZLx+A260nDHdk8nq6BTL9m3oZXACmDDiBaYJV4lQjQj5Bg1uEUGqlzSLCBrX0Q=="
       }
     },
     "net8.0": {
@@ -431,7 +438,8 @@
         "type": "Project",
         "dependencies": {
           "Microsoft.Extensions.DependencyInjection.Abstractions": "[10.0.5, )",
-          "Microsoft.Extensions.Hosting.Abstractions": "[10.0.5, )"
+          "Microsoft.Extensions.Hosting.Abstractions": "[10.0.5, )",
+          "PatternKit.Core": "[0.113.0, )"
         }
       },
       "workflowframework.extensions.diagnostics": {
@@ -508,6 +516,12 @@
           "Microsoft.Extensions.Primitives": "10.0.5"
         }
       },
+      "PatternKit.Core": {
+        "type": "CentralTransitive",
+        "requested": "[0.113.0, )",
+        "resolved": "0.113.0",
+        "contentHash": "gnHABPF+MK6UmTm3Q0q6UjN1ZLx+A260nDHdk8nq6BTL9m3oZXACmDDiBaYJV4lQjQj5Bg1uEUGqlzSLCBrX0Q=="
+      },
       "System.Diagnostics.DiagnosticSource": {
         "type": "CentralTransitive",
         "requested": "[10.0.5, )",
@@ -683,7 +697,8 @@
         "type": "Project",
         "dependencies": {
           "Microsoft.Extensions.DependencyInjection.Abstractions": "[10.0.5, )",
-          "Microsoft.Extensions.Hosting.Abstractions": "[10.0.5, )"
+          "Microsoft.Extensions.Hosting.Abstractions": "[10.0.5, )",
+          "PatternKit.Core": "[0.113.0, )"
         }
       },
       "workflowframework.extensions.diagnostics": {
@@ -758,6 +773,12 @@
           "Microsoft.Extensions.Primitives": "10.0.5"
         }
       },
+      "PatternKit.Core": {
+        "type": "CentralTransitive",
+        "requested": "[0.113.0, )",
+        "resolved": "0.113.0",
+        "contentHash": "gnHABPF+MK6UmTm3Q0q6UjN1ZLx+A260nDHdk8nq6BTL9m3oZXACmDDiBaYJV4lQjQj5Bg1uEUGqlzSLCBrX0Q=="
+      },
       "System.Diagnostics.DiagnosticSource": {
         "type": "CentralTransitive",
         "requested": "[10.0.5, )",

docs/patternkit-adoption.md

@@ -1,7 +1,7 @@
 # PatternKit Adoption Inventory
 
-**PatternKit version:** 0.112.0  
-**Last updated:** 2026-05-22 (feat/consume-patternkit-0.112 — WireTapStep adopted)
+**PatternKit version:** 0.113.0  
+**Last updated:** 2026-05-22 (feat/iter2-minor-refactors — NormalizerStep / PollingConsumerStep / IdempotentReceiverStep adopted)
 
 This document lists every point in the WorkflowFramework codebase where a PatternKit primitive is used, and every point where a step is intentionally kept bespoke with the rationale for that decision. This is the canonical reference for Phase I and future phases.
 
@@ -57,6 +57,46 @@ This document lists every point in the WorkflowFramework codebase where a Patter
 | **Public API change** | None — swap is internal-only. |
 | **Net delta** | −15 lines of bespoke logic (try/catch error-swallowing replaced by `TapErrorPolicy`). |
 
+### 5. `NormalizerStep` — Keyed normalizer pattern
+
+| Item | Detail |
+|------|--------|
+| **File** | `src/WorkflowFramework.Extensions.Integration/Transformation/NormalizerStep.cs` |
+| **PatternKit namespace** | `PatternKit.Messaging.Transformation` |
+| **Primitive** | `KeyedNormalizer<string, IWorkflowContext, IWorkflowContext>` (new in 0.113.0) |
+| **Purpose** | Delegates O(1) key-based dispatch to `KeyedNormalizer`. Each `IStep` translator is wrapped as an async handler. The original `InvalidOperationException` contract is preserved by catching `KeyNotFoundException` from the PatternKit miss path and wrapping it with the bespoke message. |
+| **Phase introduced** | feat/iter2-minor-refactors |
+| **Test coverage** | `tests/WorkflowFramework.Tests.TinyBDD/Integration/Transformation/NormalizerStepScenarios.cs` — all 9 scenarios pass without modification. |
+| **Public API change** | None — swap is internal-only. |
+| **Net delta** | −10 lines of bespoke dict-lookup logic (absorbed into KeyedNormalizer). |
+
+### 6. `PollingConsumerStep` — Async polling consumer pattern
+
+| Item | Detail |
+|------|--------|
+| **File** | `src/WorkflowFramework.Extensions.Integration/Endpoint/PollingConsumerStep.cs` |
+| **PatternKit namespace** | `PatternKit.Messaging.Consumers` |
+| **Primitive** | `AsyncPollingConsumer<IReadOnlyList<T>>.PollOnceAsync` (new in 0.113.0) |
+| **Purpose** | Bridges `IPollingSource<T>` (which returns `IReadOnlyList<T>`) to `AsyncPollingConsumer`'s `AsyncPollSource` delegate via `WithSource`. Calls `PollOnceAsync` for a single-shot poll without entering the consumer's run loop. The `ResultKey` write contract and `IReadOnlyList<T>` output type are unchanged. |
+| **Phase introduced** | feat/iter2-minor-refactors |
+| **Test coverage** | `tests/WorkflowFramework.Tests.TinyBDD/Integration/Endpoint/PollingConsumerStepScenarios.cs` — all 8 scenarios pass without modification. |
+| **Public API change** | None — swap is internal-only. |
+| **Net delta** | −4 lines (bespoke poll call replaced by consumer delegation). |
+
+### 7. `IdempotentReceiverStep` — Idempotent receiver pattern
+
+| Item | Detail |
+|------|--------|
+| **File** | `src/WorkflowFramework.Extensions.Integration/Endpoint/IdempotentReceiverStep.cs` |
+| **PatternKit namespace** | `PatternKit.Messaging.Reliability` |
+| **Primitive** | `IIdempotencyStore` (in 0.112.0+) with `TryClaimAsync` / `MarkCompletedAsync` / `MarkFailedAsync` |
+| **Purpose** | Replaces the bespoke `HashSet<string>` with claim/complete/fail semantics. The default store (`RetryAfterFailureIdempotencyStore`) resets Failed keys to Processing on re-claim, allowing retry after transient failure. Completed keys are still suppressed, preserving the successful-dedup contract. |
+| **Phase introduced** | feat/iter2-minor-refactors |
+| **Behavior change** | **BUG FIX:** Previously, a step failure permanently locked the idempotency key, preventing retries. A transient inner-step failure should not lock future attempts. The new semantics: `Failed` → retry allowed; `Completed` → deduplicated. |
+| **Test coverage** | `tests/WorkflowFramework.Tests.TinyBDD/Integration/Endpoint/IdempotentReceiverStepScenarios.cs` — 9 scenarios; `ReAttemptAfterExceptionIsSkipped` renamed to `ReAttemptAfterExceptionIsAllowed` with assertion flipped. |
+| **Public API change** | Added optional `IIdempotencyStore` overload in the constructor. Default two-arg constructor preserved. |
+| **Net delta** | +83 lines net (bespoke `HashSet` replaced by `IIdempotencyStore` + internal default impl). |
+
 ---
 
 ## Intentionally Bespoke
@@ -197,16 +237,15 @@ When evaluating a bespoke component for PatternKit adoption, the following crite
 
 The following components are candidates for PatternKit adoption in later phases if suitable primitives become available or interface alignment is achieved:
 
-| Component | Potential Primitive | Blocking Reason (assessed against 0.112.0) |
+| Component | Potential Primitive | Blocking Reason (assessed against 0.113.0) |
 |-----------|--------------------|-----------------------|
-| `NormalizerStep` | `Normalizer<TRaw,TCanonical>` (now in 0.112.0) | Behavioral mismatch: PatternKit uses content predicates (first match wins); bespoke uses O(1) dictionary keyed dispatch. Error message format differs — test pins format name in exception text. See `docs/patternkit-followup.md`. |
-| `ContentEnricherStep` | `AsyncContentEnricher<TPayload>` (now in 0.112.0) | Semantic mismatch: PatternKit returns an enriched payload copy; bespoke mutates `IWorkflowContext` in place via a `Func<IWorkflowContext, Task>`. Wrapping adds indirection for zero functional benefit. |
-| `IdempotentReceiverStep` | `IdempotentReceiver<TPayload,TResult>` (now in 0.112.0) | Behavioral breaking change: PatternKit marks failed attempts as `Failed` in the store (allowing retry); bespoke registers the ID in a `HashSet` before calling inner, so a failed first attempt DOES suppress the second. Test `ReAttemptAfterExceptionIsSkipped` pins this behavior. |
-| `ClaimCheckStep` / `ClaimRetrieveStep` | `ClaimCheck<TPayload>` (now in 0.112.0) | Interface mismatch: bespoke `IClaimCheckStore` is untyped (`object`); PatternKit `IClaimCheckStore<TPayload>` is typed. Bridging requires an adapter class, adding indirection without deleting complexity. |
-| `PollingConsumerStep` | `AsyncPollingConsumer<TPayload>` (now in 0.112.0) | Semantic mismatch: PatternKit is a continuous polling loop (run until cancelled); bespoke is a single-shot poll (`PollAsync` → store results → return). Incompatible lifecycle models. |
-| `ScatterGatherStep` | `AsyncScatterGather<TRequest,TResponse,TResult>` (now in 0.112.0) | Integration complexity: handlers mutate a shared `IWorkflowContext` and write results to named context keys; PatternKit's per-recipient isolation model returns typed `TResponse` values. Adapting while preserving the `__Result_{handler.Name}` and `ResultsKey` contract would re-implement the existing complexity via a wrapper, defeating the purpose. |
-| `TransactionalOutboxStep` | `IOutboxStore<TPayload>` (now in 0.112.0) | Interface mismatch: bespoke `IOutboxStore` uses `SaveAsync(object) → string`; PatternKit `IOutboxStore<TPayload>` uses `EnqueueAsync(Message<TPayload>) → OutboxMessage<TPayload>`. Different return types and message wrapper model. |
-| `AggregatorStep` | PatternKit Aggregator (future) | No Aggregator primitive in 0.112.0 |
+| `ContentEnricherStep` | `AsyncContentEnricher<TPayload>` (now in 0.113.0) | Path C — intentionally bespoke. PatternKit returns an enriched payload copy; bespoke mutates `IWorkflowContext` in place via a `Func<IWorkflowContext, Task>`. Wrapping adds indirection for zero functional benefit. See `.plan/patternkit-iteration-2.md` §2. |
+| `ClaimCheckStep` / `ClaimRetrieveStep` | `ClaimCheck<TPayload>` (now in 0.113.0) | Interface mismatch: bespoke `IClaimCheckStore` is untyped (`object`); PatternKit `IClaimCheckStore<TPayload>` is typed. Deferred to Iteration 2 Phase 3 — requires adapter + interface migration. |
+| `ScatterGatherStep` | `AsyncScatterGather<TRequest,TResponse,TResult>` (now in 0.113.0) | Integration complexity: handlers mutate a shared `IWorkflowContext` and write results to named context keys; PatternKit's per-recipient isolation model returns typed `TResponse` values. Deferred to Iteration 2 Phase 3. |
+| `TransactionalOutboxStep` | `IOutboxStore<TPayload>` (now in 0.113.0) | Interface mismatch: bespoke `IOutboxStore` uses `SaveAsync(object) → string`; PatternKit `IOutboxStore<TPayload>` uses `EnqueueAsync(Message<TPayload>) → OutboxMessage<TPayload>`. Deferred to Iteration 2 Phase 3. |
+| `AggregatorStep` | PatternKit Aggregator (future) | No Aggregator primitive in 0.113.0 |
 | `PluginManager` | `Strategy` + `AbstractFactory` | Phase H.8 — not yet started |
 | `AgentLoopStep` / `AgentDecisionStep` | TypeDispatcher | Phase H.7 — not yet started |
 | `ResilienceMiddleware` (Polly) | `RetryPolicy` | Phase F pilot option B — deferred |
+
+**Adopted in feat/iter2-minor-refactors (Iteration 2 Phase 2):** `NormalizerStep` (→ `KeyedNormalizer`), `PollingConsumerStep` (→ `PollOnceAsync`), `IdempotentReceiverStep` (→ `IIdempotencyStore` claim/complete/fail — includes bug fix).

samples/WorkflowFramework.Samples.DataPipeline/packages.lock.json

@@ -56,7 +56,8 @@
         "type": "Project",
         "dependencies": {
           "Microsoft.Extensions.DependencyInjection.Abstractions": "[10.0.5, )",
-          "Microsoft.Extensions.Hosting.Abstractions": "[10.0.5, )"
+          "Microsoft.Extensions.Hosting.Abstractions": "[10.0.5, )",
+          "PatternKit.Core": "[0.113.0, )"
         }
       },
       "Microsoft.Extensions.DependencyInjection.Abstractions": {
@@ -96,6 +97,12 @@
           "Microsoft.Extensions.DependencyInjection.Abstractions": "10.0.5",
           "Microsoft.Extensions.Primitives": "10.0.5"
         }
+      },
+      "PatternKit.Core": {
+        "type": "CentralTransitive",
+        "requested": "[0.113.0, )",
+        "resolved": "0.113.0",
+        "contentHash": "gnHABPF+MK6UmTm3Q0q6UjN1ZLx+A260nDHdk8nq6BTL9m3oZXACmDDiBaYJV4lQjQj5Bg1uEUGqlzSLCBrX0Q=="
       }
     },
     "net8.0": {
@@ -154,7 +161,8 @@
         "type": "Project",
         "dependencies": {
           "Microsoft.Extensions.DependencyInjection.Abstractions": "[10.0.5, )",
-          "Microsoft.Extensions.Hosting.Abstractions": "[10.0.5, )"
+          "Microsoft.Extensions.Hosting.Abstractions": "[10.0.5, )",
+          "PatternKit.Core": "[0.113.0, )"
         }
       },
       "Microsoft.Extensions.DependencyInjection.Abstractions": {
@@ -196,6 +204,12 @@
           "Microsoft.Extensions.Primitives": "10.0.5"
         }
       },
+      "PatternKit.Core": {
+        "type": "CentralTransitive",
+        "requested": "[0.113.0, )",
+        "resolved": "0.113.0",
+        "contentHash": "gnHABPF+MK6UmTm3Q0q6UjN1ZLx+A260nDHdk8nq6BTL9m3oZXACmDDiBaYJV4lQjQj5Bg1uEUGqlzSLCBrX0Q=="
+      },
       "System.Diagnostics.DiagnosticSource": {
         "type": "CentralTransitive",
         "requested": "[10.0.5, )",
@@ -259,7 +273,8 @@
         "type": "Project",
         "dependencies": {
           "Microsoft.Extensions.DependencyInjection.Abstractions": "[10.0.5, )",
-          "Microsoft.Extensions.Hosting.Abstractions": "[10.0.5, )"
+          "Microsoft.Extensions.Hosting.Abstractions": "[10.0.5, )",
+          "PatternKit.Core": "[0.113.0, )"
         }
       },
       "Microsoft.Extensions.DependencyInjection.Abstractions": {
@@ -301,6 +316,12 @@
           "Microsoft.Extensions.Primitives": "10.0.5"
         }
       },
+      "PatternKit.Core": {
+        "type": "CentralTransitive",
+        "requested": "[0.113.0, )",
+        "resolved": "0.113.0",
+        "contentHash": "gnHABPF+MK6UmTm3Q0q6UjN1ZLx+A260nDHdk8nq6BTL9m3oZXACmDDiBaYJV4lQjQj5Bg1uEUGqlzSLCBrX0Q=="
+      },
       "System.Diagnostics.DiagnosticSource": {
         "type": "CentralTransitive",
         "requested": "[10.0.5, )",

samples/WorkflowFramework.Samples.OrderProcessing/packages.lock.json

@@ -56,7 +56,8 @@
         "type": "Project",
         "dependencies": {
           "Microsoft.Extensions.DependencyInjection.Abstractions": "[10.0.5, )",
-          "Microsoft.Extensions.Hosting.Abstractions": "[10.0.5, )"
+          "Microsoft.Extensions.Hosting.Abstractions": "[10.0.5, )",
+          "PatternKit.Core": "[0.113.0, )"
         }
       },
       "workflowframework.extensions.visualization": {
@@ -102,6 +103,12 @@
           "Microsoft.Extensions.DependencyInjection.Abstractions": "10.0.5",
           "Microsoft.Extensions.Primitives": "10.0.5"
         }
+      },
+      "PatternKit.Core": {
+        "type": "CentralTransitive",
+        "requested": "[0.113.0, )",
+        "resolved": "0.113.0",
+        "contentHash": "gnHABPF+MK6UmTm3Q0q6UjN1ZLx+A260nDHdk8nq6BTL9m3oZXACmDDiBaYJV4lQjQj5Bg1uEUGqlzSLCBrX0Q=="
       }
     },
     "net8.0": {
@@ -160,7 +167,8 @@
         "type": "Project",
         "dependencies": {
           "Microsoft.Extensions.DependencyInjection.Abstractions": "[10.0.5, )",
-          "Microsoft.Extensions.Hosting.Abstractions": "[10.0.5, )"
+          "Microsoft.Extensions.Hosting.Abstractions": "[10.0.5, )",
+          "PatternKit.Core": "[0.113.0, )"
         }
       },
       "workflowframework.extensions.visualization": {
@@ -208,6 +216,12 @@
           "Microsoft.Extensions.Primitives": "10.0.5"
         }
       },
+      "PatternKit.Core": {
+        "type": "CentralTransitive",
+        "requested": "[0.113.0, )",
+        "resolved": "0.113.0",
+        "contentHash": "gnHABPF+MK6UmTm3Q0q6UjN1ZLx+A260nDHdk8nq6BTL9m3oZXACmDDiBaYJV4lQjQj5Bg1uEUGqlzSLCBrX0Q=="
+      },
       "System.Diagnostics.DiagnosticSource": {
         "type": "CentralTransitive",
         "requested": "[10.0.5, )",
@@ -271,7 +285,8 @@
         "type": "Project",
         "dependencies": {
           "Microsoft.Extensions.DependencyInjection.Abstractions": "[10.0.5, )",
-          "Microsoft.Extensions.Hosting.Abstractions": "[10.0.5, )"
+          "Microsoft.Extensions.Hosting.Abstractions": "[10.0.5, )",
+          "PatternKit.Core": "[0.113.0, )"
         }
       },
       "workflowframework.extensions.visualization": {
@@ -319,6 +334,12 @@
           "Microsoft.Extensions.Primitives": "10.0.5"
         }
       },
+      "PatternKit.Core": {
+        "type": "CentralTransitive",
+        "requested": "[0.113.0, )",
+        "resolved": "0.113.0",
+        "contentHash": "gnHABPF+MK6UmTm3Q0q6UjN1ZLx+A260nDHdk8nq6BTL9m3oZXACmDDiBaYJV4lQjQj5Bg1uEUGqlzSLCBrX0Q=="
+      },
       "System.Diagnostics.DiagnosticSource": {
         "type": "CentralTransitive",
         "requested": "[10.0.5, )",

samples/WorkflowFramework.Samples.TaskStream/packages.lock.json

@@ -248,7 +248,8 @@
         "type": "Project",
         "dependencies": {
           "Microsoft.Extensions.DependencyInjection.Abstractions": "[10.0.5, )",
-          "Microsoft.Extensions.Hosting.Abstractions": "[10.0.5, )"
+          "Microsoft.Extensions.Hosting.Abstractions": "[10.0.5, )",
+          "PatternKit.Core": "[0.113.0, )"
         }
       },
       "workflowframework.extensions.ai": {
@@ -300,6 +301,12 @@
           "Microsoft.SemanticKernel.Connectors.AzureOpenAI": "1.71.0",
           "Microsoft.SemanticKernel.Core": "1.71.0"
         }
+      },
+      "PatternKit.Core": {
+        "type": "CentralTransitive",
+        "requested": "[0.113.0, )",
+        "resolved": "0.113.0",
+        "contentHash": "gnHABPF+MK6UmTm3Q0q6UjN1ZLx+A260nDHdk8nq6BTL9m3oZXACmDDiBaYJV4lQjQj5Bg1uEUGqlzSLCBrX0Q=="
       }
     }
   }

samples/WorkflowFramework.Samples.VoiceWorkflows/packages.lock.json

@@ -248,7 +248,8 @@
         "type": "Project",
         "dependencies": {
           "Microsoft.Extensions.DependencyInjection.Abstractions": "[10.0.5, )",
-          "Microsoft.Extensions.Hosting.Abstractions": "[10.0.5, )"
+          "Microsoft.Extensions.Hosting.Abstractions": "[10.0.5, )",
+          "PatternKit.Core": "[0.113.0, )"
         }
       },
       "workflowframework.extensions.agents": {
@@ -313,6 +314,12 @@
           "Microsoft.SemanticKernel.Connectors.AzureOpenAI": "1.71.0",
           "Microsoft.SemanticKernel.Core": "1.71.0"
         }
+      },
+      "PatternKit.Core": {
+        "type": "CentralTransitive",
+        "requested": "[0.113.0, )",
+        "resolved": "0.113.0",
+        "contentHash": "gnHABPF+MK6UmTm3Q0q6UjN1ZLx+A260nDHdk8nq6BTL9m3oZXACmDDiBaYJV4lQjQj5Bg1uEUGqlzSLCBrX0Q=="
       }
     }
   }