fix-codex round-1: address PR #707 reviewer comments (cluster-026)

Applied 5 fixes (FIX_DONE:707:round-1:applied-5:rejected-0:blocked-0):
- (A) architect: add method-level Refactor (iter15/cluster-026) markers
  on VoicePresenceModule actor-turn provider event normalization, response
  identity normalization, provider response mapping, retirement
- (A) architect: add method-level Refactor marker on OpenAI provider
  MapSessionEvent (emits provider-native response ids)
- (A) architect: add method-level Refactor markers on MiniCPM provider
  CancelResponseAsync + ReadCompletionStreamAsync
- (A) quality: add why-comment for intentional remote audio input no-op
  until raw host-origin transport path exists
- (A) tests: add source-regression test asserting provider adapters no
  longer own response epoch/counter state; module owns provider response
  mapping

Build pass; VoicePresence.Tests 120/120; OpenAI.Tests 24/24; MiniCPM.Tests
12/12; test_stability_guards pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: loning

src/Aevatar.Foundation.VoicePresence.MiniCPM/MiniCPMRealtimeProvider.cs

@@ -137,6 +137,9 @@ public Task InjectEventAsync(VoiceConversationEventInjection injection, Cancella
             "MiniCPM-o demo protocol does not support structured external event injection.");
     }
 
+    // Refactor (iter15/cluster-026-voice-provider-background-state):
+    //   Old pattern: cancel mutated active/suppressed response epoch state and emitted synthetic cancel events.
+    //   New principle: cancel only sends provider stop; VoicePresenceModule owns actor cancellation state.
     public async Task CancelResponseAsync(CancellationToken ct)
     {
         using var message = new HttpRequestMessage(HttpMethod.Post, BuildUri(_options.StopPath));
@@ -251,6 +254,9 @@ private async Task RunCompletionsLoopAsync(ChannelWriter<VoiceProviderEvent> wri
         }
     }
 
+    // Refactor (iter15/cluster-026-voice-provider-background-state):
+    //   Old pattern: completion stream allocated actor response ids and suppressed stale audio in provider state.
+    //   New principle: stream parsing emits provider-native response ids; module actor turn maps and suppresses.
     private async Task ReadCompletionStreamAsync(
         Stream stream,
         ChannelWriter<VoiceProviderEvent> writer,

src/Aevatar.Foundation.VoicePresence.OpenAI/OpenAIRealtimeProvider.cs

@@ -214,6 +214,9 @@ private async Task RunDispatchLoopAsync(ChannelReader<VoiceProviderEvent> reader
         }
     }
 
+    // Refactor (iter15/cluster-026-voice-provider-background-state):
+    //   Old pattern: MapSessionEvent allocated actor response epochs and mutated provider-owned response dictionaries.
+    //   New principle: OpenAI events carry provider-native response ids; VoicePresenceModule maps them in actor turn.
     private VoiceProviderEvent? MapSessionEvent(OpenAIRealtimeSessionEvent sessionEvent) =>
         sessionEvent switch
         {

src/Aevatar.Foundation.VoicePresence/Modules/VoicePresenceModule.cs

@@ -151,6 +151,7 @@ private async Task HandleModuleSignalAsync(
                 await HandleRemoteSessionCloseRequestedAsync(signal.RemoteSessionCloseRequested, ctx, ct);
                 break;
             case VoiceModuleSignal.SignalOneofCase.RemoteAudioInputReceived:
+                // Remote PCM stays off EventEnvelope until a raw transport path exists for host-origin audio.
                 break;
             case VoiceModuleSignal.SignalOneofCase.RemoteControlInputReceived:
                 await HandleRemoteControlInputReceivedAsync(signal.RemoteControlInputReceived, ct);
@@ -334,6 +335,9 @@ private async Task StopRelayAsync()
 
     // ── State machine dispatch (used by both event pipeline and relay) ──
 
+    // Refactor (iter15/cluster-026-voice-provider-background-state):
+    //   Old pattern: provider callbacks arrived with actor response epochs already assigned in background loops.
+    //   New principle: provider events are normalized to actor response ids inside this actor turn.
     internal async Task HandleProviderEventAsync(
         VoiceProviderEvent providerEvent,
         IEventHandlerContext ctx,
@@ -402,6 +406,9 @@ internal async Task HandleProviderEventAsync(
         }
     }
 
+    // Refactor (iter15/cluster-026-voice-provider-background-state):
+    //   Old pattern: provider-specific receive loops suppressed and completed response epochs directly.
+    //   New principle: this actor-turn normalizer owns cancellation suppression and response-id materialization.
     private bool TryNormalizeProviderEvent(
         VoiceProviderEvent providerEvent,
         out VoiceProviderEvent normalizedEvent)
@@ -482,6 +489,9 @@ private bool TryNormalizeProviderEvent(
         }
     }
 
+    // Refactor (iter15/cluster-026-voice-provider-background-state):
+    //   Old pattern: providers allocated fallback response epochs when provider ids were missing.
+    //   New principle: fallback actor response ids are allocated only by the module state machine turn.
     private bool TryNormalizeResponseIdentity(string providerResponseId, int suppliedResponseId, out int responseId)
     {
         if (!string.IsNullOrWhiteSpace(providerResponseId))
@@ -506,6 +516,9 @@ private bool TryNormalizeResponseIdentity(string providerResponseId, int supplie
         return true;
     }
 
+    // Refactor (iter15/cluster-026-voice-provider-background-state):
+    //   Old pattern: OpenAI/MiniCPM adapters owned provider-id to actor-epoch dictionaries and counters.
+    //   New principle: provider-id to actor response-id mapping is actor runtime state owned by this module.
     private int GetOrCreateProviderResponse(string providerResponseId, int suppliedResponseId)
     {
         if (_providerResponseIds.TryGetValue(providerResponseId, out var existing))
@@ -520,6 +533,9 @@ private int GetOrCreateProviderResponse(string providerResponseId, int suppliedR
     private bool TryGetProviderResponse(string providerResponseId, out int responseId) =>
         _providerResponseIds.TryGetValue(providerResponseId, out responseId);
 
+    // Refactor (iter15/cluster-026-voice-provider-background-state):
+    //   Old pattern: providers retired response epochs from background completion/cancel callbacks.
+    //   New principle: the actor turn retires provider response mappings when committed lifecycle events arrive.
     private void RetireProviderResponse(string providerResponseId)
     {
         if (string.IsNullOrWhiteSpace(providerResponseId))

test/Aevatar.Foundation.VoicePresence.Tests/VoicePresenceModuleTests.cs

@@ -391,6 +391,37 @@ await module.HandleAsync(CreateEnvelope(new VoiceProviderEvent
         module.StateMachine.State.ShouldBe(VoicePresenceState.UserSpeaking);
     }
 
+    [Fact]
+    public void Provider_adapters_should_not_own_response_epoch_state()
+    {
+        var repoRoot = FindRepositoryRoot();
+        var providerSources = new[]
+        {
+            Path.Combine(repoRoot, "src/Aevatar.Foundation.VoicePresence.OpenAI/OpenAIRealtimeProvider.cs"),
+            Path.Combine(repoRoot, "src/Aevatar.Foundation.VoicePresence.MiniCPM/MiniCPMRealtimeProvider.cs"),
+        };
+        var forbiddenTokens = new[]
+        {
+            "_responseEpochs",
+            "_nextResponseId",
+            "_activeResponseId",
+            "_suppressedResponseId",
+            "Interlocked.Increment",
+        };
+
+        foreach (var sourcePath in providerSources)
+        {
+            File.Exists(sourcePath).ShouldBeTrue(sourcePath);
+            var source = StripLineComments(File.ReadAllLines(sourcePath));
+            foreach (var token in forbiddenTokens)
+                source.ShouldNotContain(token, Case.Sensitive, $"{Path.GetFileName(sourcePath)} must emit provider-native ids only");
+        }
+
+        var moduleSourcePath = Path.Combine(repoRoot, "src/Aevatar.Foundation.VoicePresence/Modules/VoicePresenceModule.cs");
+        var moduleSource = File.ReadAllText(moduleSourcePath);
+        moduleSource.ShouldContain("_providerResponseIds");
+    }
+
     [Fact]
     public async Task Remote_session_signals_should_not_forward_audio_or_publish_audio_outputs()
     {
@@ -899,6 +930,23 @@ private static EventEnvelope CreateEnvelope(IMessage payload)
         };
     }
 
+    private static string FindRepositoryRoot()
+    {
+        var current = new DirectoryInfo(AppContext.BaseDirectory);
+        while (current != null)
+        {
+            if (File.Exists(Path.Combine(current.FullName, "aevatar.slnx")))
+                return current.FullName;
+
+            current = current.Parent;
+        }
+
+        throw new DirectoryNotFoundException("Could not find repository root containing aevatar.slnx.");
+    }
+
+    private static string StripLineComments(IEnumerable<string> lines) =>
+        string.Join(Environment.NewLine, lines.Where(static line => !line.TrimStart().StartsWith("//", StringComparison.Ordinal)));
+
     private sealed class RecordingVoiceProvider : IRealtimeVoiceProvider
     {
         public int ConnectCalls { get; private set; }