Replay Outgoing Messages When Inbox Receives Duplicate

.agent_instructions/generated_tests.md

@@ -17,7 +17,8 @@ tools/Paramore.Brighter.Test.Generator/
 │   ├── IAmAMessageAssertion.cs.liquid      ← Message assertion interface
 │   ├── Outbox/
 │   │   ├── Sync/       ← 13 Liquid templates for sync outbox tests (12 tests + 1 interface)
-│   │   └── Async/      ← 13 Liquid templates for async outbox tests (12 tests + 1 interface)
+│   │   ├── Async/      ← 13 Liquid templates for async outbox tests (12 tests + 1 interface)
+│   │   └── Causation/  ← Liquid template for causation-tracking outbox tests (subclass of CausationTrackingOutboxBaseTests)
 │   └── MessagingGateway/
 │       ├── Reactor/    ← 13 Liquid templates for sync messaging gateway tests (12 tests + 1 interface)
 │       └── Proactor/   ← 13 Liquid templates for async messaging gateway tests (12 tests + 1 interface)
@@ -37,7 +38,8 @@ tests/Paramore.Brighter.*.Tests/
 ├── Outbox/
 │   └── [Prefix]/Generated/      ← Output directory (do not hand-edit)
 │       ├── Sync/*.cs
-│       └── Async/*.cs
+│       ├── Async/*.cs
+│       └── Causation/*.cs
 └── MessagingGateway/
     └── [Prefix]/Generated/      ← Output directory (do not hand-edit)
         ├── Reactor/*.cs

.gitignore

@@ -3,9 +3,6 @@
 ##
 ## Get latest from https://github.com/github/gitignore/blob/master/VisualStudio.gitignore
 
-# Claude Code session state
-PROMPT.md
-
 # User-specific files
 *.suo
 *.user

release_notes.md

@@ -295,6 +295,45 @@ While applying the value-type pattern we corrected a latent null-safety bug in n
 
 > Note: `Tenant` (in `Paramore.Brighter.Transformers.JustSaying`) is a `readonly record struct`, not a reference type — its receiver can never be null, so its `operator string` is intentionally left non-nullable.
 
+### Replay Outbox Messages on Inbox Duplicate (spec 0027)
+
+When an inbox detects a duplicate request, Brighter can now optionally **replay** the outbox messages that were produced under that request's causation, rather than silently dropping the duplicate. The feature is opt-in (`OnceOnlyAction.Replay` on the inbox attribute) and non-breaking: it requires a causation-tracking inbox and outbox (`IAmACausationTrackingInbox` / `IAmACausationTrackingOutbox`), and the relational stores gate the causation-aware write on a memoized column probe so un-migrated schemas keep depositing unchanged. Startup pipeline validation fails fast if a `Replay` pipeline is configured without causation tracking. See [ADR 0057](docs/adr/0057-replay-outbox-on-inbox-duplicate.md) and [spec 0027](specs/0027-replay-matching-outbox-events-when-inbox-has-already-seen/) for full details.
+
+#### Usage requirement: thread your `RequestContext` through `Post` / `DepositPost`
+
+Replay links a duplicate back to its original outbox messages through the **causation id**. `[UseInbox]` stamps that id into the pipeline's `RequestContext.Bag`, and the outbox `Add` reads it back from the bag — **but only if the handler that deposits the outbox message passes its own `Context` down**. If a handler calls the idiomatic `_commandProcessor.Post(evt)` (or `DepositPost`) *without* a request context, `CommandProcessor` creates a fresh context, the causation id is lost, the message is stored with a `null` `CausationId`, and a later `Replay` finds nothing to replay — a **silent no-op** with no error.
+
+To use Replay, every handler that produces outbox messages must forward its handler `Context`:
+
+```csharp
+// ❌ Silent no-op under Replay — fresh context, causation id lost
+public override MyCommand Handle(MyCommand command)
+{
+    _commandProcessor.Post(new DownstreamEvent(...));
+    return base.Handle(command);
+}
+
+// ✅ Threads the causation id so Replay can match
+public override MyCommand Handle(MyCommand command)
+{
+    _commandProcessor.Post(new DownstreamEvent(...), Context);
+    return base.Handle(command);
+}
+```
+
+This applies to the async equivalents (`PostAsync` / `DepositPostAsync`) as well.
+
+#### Source-breaking change: `IRequestContext.InstrumentationOptions`
+
+`IRequestContext` gains a new required `InstrumentationOptions InstrumentationOptions { get; set; }` member. It carries the instrumentation options configured for the pipeline that created the context, so middleware handlers can gate their own telemetry (for example on `InstrumentationOptions.Brighter`) without taking a dependency on how the processor was configured. `Paramore.Brighter` targets `netstandard2.0`, which does not support default interface members, so — as with the spec-0027/0029 box-provisioning interface additions — this is exposed as a plain abstract member.
+
+The change is **source-breaking** for any third-party or test type that implements `IRequestContext`: such types will fail to compile until they add the new member. It affects more consumers than just those adopting Replay, hence its call-out here. The shipped `RequestContext` already implements it and defaults to `InstrumentationOptions.All`, so call sites that use the shipped context require no change.
+
+```csharp
+// Custom IRequestContext implementations must add:
+public InstrumentationOptions InstrumentationOptions { get; set; } = InstrumentationOptions.All;
+```
+
 ## Release 10.0.0
 
 With V10 we have made a number of significant changes to Brighter. There are breaking changes that you will need to be aware of. However, most of the changes required are straightforward to make. A summary of the most important changes:

specs/.current-spec

@@ -1 +1 @@
-0035-pipeline-cache-type-key
+0027-replay-matching-outbox-events-when-inbox-has-already-seen

specs/0022-Defer-Message-Action-Backstop-Handler/review-tasks.md

@@ -0,0 +1,71 @@
+# Review: tasks — 0022-Defer-Message-Action-Backstop-Handler
+
+**Date**: 2026-04-17
+**Threshold**: 60
+**Verdict**: NEEDS WORK
+
+> **Note**: This phase is already approved. Findings are informational — consider whether any warrant re-opening the phase.
+
+1 finding at or above threshold 60. Address these before approving.
+
+## Findings
+
+### 1. Task 7 only tests Proactor path but implementation modifies both Reactor and Proactor (Score: 70)
+
+Task 7 specifies a single test file in `tests/Paramore.Brighter.Core.Tests/MessageDispatch/Proactor/` and says the implementation touches both `Proactor.cs` and `Reactor.cs`. However, the task only has one test file covering the Proactor (async) path. There is no corresponding test for the Reactor (sync) path with the delay override.
+
+**Evidence**: Task 7 says:
+> "In `Proactor.cs`: Change `catch (DeferMessageAction)` to `catch (DeferMessageAction deferAction)`, extract `deferAction.Delay`, pass to `RequeueMessage`"
+> "In `Reactor.cs`: Same change for the sync path"
+
+But only one test file is listed: `When_a_command_handler_throws_a_defer_message_with_delay_Then_message_is_requeued_with_delay.cs` in the `Proactor/` directory.
+
+**Recommendation**: Add a separate test task (or expand Task 7) to include a Reactor-path test: `tests/Paramore.Brighter.Core.Tests/MessageDispatch/Reactor/When_a_command_handler_throws_a_defer_message_with_delay_Then_message_is_requeued_with_delay.cs`.
+
+---
+
+### 2. Task 7 test verifies only the "with delay" case; the "null delay fallback" case is described but has no separate test file (Score: 55)
+
+Task 7 bullet says to verify two behaviors: (1) when `Delay` is set, pump uses it, and (2) when `Delay` is null, pump falls back to subscription `RequeueDelay`. Only one test file is specified, which presumably covers both cases in a single test class.
+
+**Evidence**: Task 7 lists:
+> "When handler throws `DeferMessageAction` with a `Delay` value, the pump passes that delay to `Channel.RequeueAsync`"
+> "When handler throws `DeferMessageAction` without a `Delay` (null), the pump falls back to subscription `RequeueDelay`"
+
+But only one test file is named.
+
+**Recommendation**: Consider splitting into two test files or at minimum ensure the single test file clearly has two separate test methods.
+
+---
+
+### 3. Task 1 describes work already completed in codebase (Score: 45)
+
+All tasks appear to be already implemented in the codebase (all four types exist, all test files exist, pump changes are in place), but all checkboxes remain unchecked.
+
+**Evidence**: `DeferMessageAction.cs` already has `TimeSpan? Delay`, all constructors, and all files referenced in Tasks 2-7 exist. All checkboxes are `- [ ]`.
+
+**Recommendation**: Mark completed tasks with `[x]` to reflect actual state.
+
+---
+
+### 4. Branch name in header is stale (Score: 30)
+
+The tasks.md header says `**Branch**: \`error_examples\` (or new feature branch)` but the current branch is `replay_on_seen`.
+
+**Evidence**: Line 6: `**Branch**: \`error_examples\` (or new feature branch)`
+
+**Recommendation**: Update the branch name or remove it.
+
+---
+
+## Summary
+
+| Score Range | Count |
+|-------------|-------|
+| 90-100 (Critical) | 0 |
+| 70-89 (High) | 1 |
+| 50-69 (Medium) | 1 |
+| 0-49 (Low) | 2 |
+
+**Total findings**: 4
+**Findings at or above threshold (60)**: 1

specs/0026-timed-outbox-archiver-sync-fallback/review-tasks.md

@@ -0,0 +1,81 @@
+# Review: tasks — 0026-timed-outbox-archiver-sync-fallback
+
+**Date**: 2026-04-15
+**Threshold**: 60
+**Verdict**: NEEDS WORK
+
+3 findings at or above threshold 60. Address these before approving.
+
+## Findings
+
+### 1. Implementation file path for TimedOutboxArchiver not specified (Score: 72)
+
+Task 2 describes implementing a three-way branch in `TimedOutboxArchiver.Archive()`, adding a `NoOutboxConfigured` log message, and removing a duplicate `OutboxSweeperSleeping` call. However, the task only specifies the file path for the TIDY step (`src/Paramore.Brighter/OutboxArchiver.cs`). The actual implementation changes are in a different project/file: `src/Paramore.Brighter.Outbox.Hosting/TimedOutboxArchiver.cs`.
+
+**Evidence**: Task 2 implementation bullet points reference `TimedOutboxArchiver.Archive()` and `Log` partial class changes but never state which file to edit. Task 1 explicitly lists `File: src/Paramore.Brighter/OutboxArchiver.cs` but no equivalent line appears for Tasks 2-4.
+
+**Recommendation**: Add `File: src/Paramore.Brighter.Outbox.Hosting/TimedOutboxArchiver.cs` to the implementation section of Task 2.
+
+---
+
+### 2. FR1 (async path unchanged) has no dedicated test task (Score: 65)
+
+FR1 states "When an async outbox is available, `TimedOutboxArchiver` calls `ArchiveAsync` (current behavior, unchanged)." Task 3 partially covers this with AC3 (prefers async when both are available), but there is no test for the scenario where ONLY an async outbox is registered (no sync). The three-way branch introduces a regression risk for async-only outboxes.
+
+**Evidence**: FR1 says "current behavior, unchanged." Task 3 tests "both sync and async" but not "async only via TimedOutboxArchiver."
+
+**Recommendation**: Either add a test task for async-only outbox through `TimedOutboxArchiver`, or explicitly document why existing coverage is sufficient.
+
+---
+
+### 3. NoOutboxConfigured log message location ambiguous (Score: 62)
+
+Task 2 says "Add `NoOutboxConfigured` log message to the `Log` partial class" but both `TimedOutboxArchiver` and `OutboxArchiver` have their own `Log` partial class. The call site is in `TimedOutboxArchiver` but this is not stated explicitly.
+
+**Evidence**: Task 2 implementation says `Log.NoOutboxConfigured(s_logger)` but `s_logger` exists in both classes.
+
+**Recommendation**: Specify: "Add `NoOutboxConfigured` log message to the `Log` partial class in `TimedOutboxArchiver.cs`."
+
+---
+
+### 4. OutboxArchiver is generic but test setup doesn't mention type parameters (Score: 55)
+
+`OutboxArchiver<TMessage, TTransaction>` requires two generic type parameters. The test descriptions don't mention what concrete types to use.
+
+**Evidence**: `public partial class OutboxArchiver<TMessage, TTransaction> where TMessage : Message` at line 40 of `OutboxArchiver.cs`.
+
+**Recommendation**: Specify the concrete generic types to use in tests based on existing archiving test patterns.
+
+---
+
+### 5. ADR decision to remove duplicate OutboxSweeperSleeping is bundled into behavioral task (Score: 45)
+
+The duplicate `OutboxSweeperSleeping` log removal is a structural/tidy change bundled into behavioral Task 2, contrary to tidy-first philosophy.
+
+**Evidence**: Task 2 implementation says "Remove duplicate `Log.OutboxSweeperSleeping` call (keep only the one in `finally`)."
+
+**Recommendation**: Move to Step 1 as a separate TIDY task.
+
+---
+
+### 6. Task numbering inconsistency in dependency chain (Score: 40)
+
+The dependency chain references "Task 1 → Task 2 → Task 3 → Task 4" but there are only 3 bullet-pointed tasks in Step 2.
+
+**Evidence**: `Task 1 (TIDY) → Task 2 (sync fallback) → Task 3 (async preference) → Task 4 (no outbox warning)` but document has Step 1 (1 task) + Step 2 (3 tasks).
+
+**Recommendation**: Number tasks explicitly or fix the dependency chain.
+
+---
+
+## Summary
+
+| Score Range | Count |
+|-------------|-------|
+| 90-100 (Critical) | 0 |
+| 70-89 (High) | 1 |
+| 50-69 (Medium) | 3 |
+| 0-49 (Low) | 2 |
+
+**Total findings**: 6
+**Findings at or above threshold (60)**: 3

specs/0027-replay-matching-outbox-events-when-inbox-has-already-seen/.adr-list

@@ -0,0 +1 @@
+0057-replay-outbox-on-inbox-duplicate.md

specs/0027-replay-matching-outbox-events-when-inbox-has-already-seen/.issue-number

@@ -0,0 +1 @@
+2541

specs/0027-replay-matching-outbox-events-when-inbox-has-already-seen/.requirements-approved

@@ -0,0 +1 @@
+Approved: 2026-04-16

specs/0027-replay-matching-outbox-events-when-inbox-has-already-seen/README.md

@@ -0,0 +1,11 @@
+# 0027 - Replay Matching Outbox Events When Inbox Has Already Seen
+
+**Created:** 2026-04-15
+
+## Status
+
+- [x] Requirements (`requirements.md`) - Approved 2026-04-16
+- [x] Design (`docs/adr/0057-replay-outbox-on-inbox-duplicate.md`) - Ready for review
+- [ ] Tasks (`tasks.md`)
+- [ ] Implementation
+- [ ] Review