oxmux: Add streaming robustness controls

[nodnarbnitram]

🔗 Linked Issue

Closes #20

✅ Type of Change

• ✨ New Project/Feature
• 🐞 Bug Fix
• 📚 Documentation Update
• 🔨 Refactor or Other

📝 Summary

• Adds deterministic oxmux streaming robustness policy, reserved control metadata, and structured pre-stream failure outcomes.
• Extends strict [streaming] TOML configuration, management snapshots, and mock provider attempt plans for retry, timeout, cancellation, and provider stream failure visibility.
• Adds networkless tests for streaming metadata spoofing, config validation, mock retry semantics, management latest-outcome replacement, and proxy-facing stable error codes.

📐 OpenSpec Evidence

• OpenSpec change/spec: openspec/changes/streaming-robustness-controls
• No OpenSpec required: N/A
• Vision/boundary impact: Preserves oxmux as the shared headless owner for stream policy, provider execution, configuration, and management semantics. No oxidemux app-shell, GPUI, provider SDK, OAuth, credential storage, or live transport dependencies were added.

📖 Documentation Checklist

• I updated README.md, CONTRIBUTING.md, or OpenSpec docs when needed.
• I updated CHANGELOG.md for notable user-facing, compatibility, security, or workflow changes, or explained why it was not applicable. Not applicable: pre-release core semantics tracked by OpenSpec change artifacts.

✔️ Contributor Checklist

• My code follows the project's coding standards.
• I have added a .env.example file if environment variables are needed and ensured no secrets are committed. Not applicable: no environment variables added.
• My pull request is focused on a single project or change.
• I preserved the oxmux shared-core and oxidemux platform-shell boundary, or documented the OpenSpec-approved reason for changing it.
• I ran mise run ci locally, or explained why it was not applicable.
• I ran mise run security locally for dependency policy and vulnerability changes, or explained why it was not applicable. Not applicable: no dependency or security policy changes.
• I ran relevant hk checks with mise run hk-check, or explained why they were not applicable. Commit hooks ran the relevant hk checks.

💬 Additional Comments

Verification:

• openspec validate streaming-robustness-controls --strict
• cargo fmt --all --check
• cargo test -p oxmux
• mise run ci

Release Notes:

• N/A

---

^{Need help on this PR? Tag @codesmith with what you need.}

• Let Codesmith autofix CI failures and bot reviews

[greptile-apps]

Greptile Summary

This PR adds a deterministic streaming robustness layer to oxmux: a validated StreamingRobustnessPolicy (keepalive, bootstrap retry, timeout, cancellation), reserved oxmux.* metadata key enforcement, structured pre-stream failure variants (RetryExhausted, PreStreamTimeout, PreStreamCancellation, ProviderStreamFailure), management snapshot outcome tracking with last-writer-wins semantics, and TOML-backed configuration with layered-merge support. All new behaviour is covered by networkless tests, including the short-plan retry case that ensures total_attempts reports only executed attempts rather than policy capacity.

Confidence Score: 5/5

Safe to merge; no logic or correctness issues found, only minor style observations.

All findings are P2 (style/clarity only). Core logic — retry counting, cross-field validation, error mapping, fingerprint stability, and reserved-key enforcement — is correct and thoroughly exercised by the new tests. The previously flagged ProviderStreamFailure→PreStreamFailure mapping is resolved by the new StreamingFailure::ProviderStreamFailure variant, and the double-error concern for the timeout cross-field guard is handled correctly by checking Some(None) rather than None.

No files require special attention.

Important Files Changed

Filename	Overview
crates/oxmux/src/streaming.rs	Adds StreamingRobustnessPolicy, StreamingCancellationPolicy, StreamingRobustnessOutcome, reserved metadata key enforcement, and new StreamingFailure variants; well-validated with range checks and cross-field rules.
crates/oxmux/src/configuration/validation.rs	Adds validate_streaming with per-field and cross-field guards; the timeout+cancellation cross-field check correctly targets only the absent case (Some(None)), avoiding double errors when the field is present-but-invalid.
crates/oxmux/src/management.rs	Adds latest_streaming_outcome field and record_streaming_outcome with last-writer-wins semantics; ProviderStreamFailure correctly maps to StreamingFailure::ProviderStreamFailure (new variant, not PreStreamFailure).
crates/oxmux/src/provider.rs	Adds MockStreamingAttempt and execute_mock_streaming_attempts; total_attempts correctly reflects only executed attempts (no .max(policy.max_attempts()) inflation), validated by dedicated test.
crates/oxmux/src/configuration/file.rs	Propagates StreamingRobustnessPolicy through ConfigurationSnapshot, ValidatedFileConfiguration, and FileBackedManagementConfiguration; merge_streaming follows the same last-value-wins pattern as other merge helpers.
crates/oxmux/tests/provider_execution.rs	New tests cover retry-then-success, full exhaustion, short-plan exhaustion (reports only executed attempts), timeout, and cancellation; all key semantics exercised deterministically.
crates/oxmux/tests/file_configuration.rs	Covers full streaming TOML loading, partial defaults, out-of-range and type-mismatch errors, cross-field cancellation+timeout error, unknown field rejection, and layered-merge precedence.
crates/oxmux/tests/streaming_response.rs	Verifies reserved metadata key rejection, typed helper construction, StreamingRobustnessPolicy validation, and matchable failure variants for retry/timeout/cancellation.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[StreamingAttempts outcome] --> B[execute_mock_streaming_attempts]
    B --> C{Iterate attempt plan\nup to max_attempts}
    C --> D[Success]
    C --> E[FailBeforeEvent]
    C --> F[TimeoutBeforeEvent]
    C --> G[CancelBeforeEvent]
    D --> H[with_committed_retry_summary\nif any retries occurred]
    H --> I[ProviderExecutionResult::Success\nwith retry metadata prepended]
    E --> J[Increment failed_pre_event_attempts\nStore last_failure]
    J --> C
    F --> K[Err: PreStreamTimeout]
    G --> L[Err: PreStreamCancellation]
    C -- plan exhausted --> M[Err: RetryExhausted\ntotal_attempts = failed_pre_event_attempts]
    M --> N[ManagementSnapshot\nrecord_streaming_outcome]
    I --> N
    K --> N
    L --> N
    N --> O[Retain non-streaming warnings/errors\nAppend new outcome message\nUpdate latest_streaming_outcome]

Loading

Prompt To Fix All With AI

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
crates/oxmux/src/configuration/file.rs:969-972
**Formatting inconsistency in fingerprint field**

`bootstrap_retry_count` uses `{}` (Display) while the surrounding streaming fields all use `{:?}` (Debug). For `u8` both produce identical output, so there's no functional impact on fingerprint stability, but the inconsistency is worth aligning for readability.

```suggestion
    canonical.push_str(&format!(
        "streaming.bootstrap-retry-count={:?}\n",
        configuration.streaming.bootstrap_retry_count
    ));
```

### Issue 2 of 2
crates/oxmux/src/configuration/validation.rs:262-263
**`unwrap_or_default` is structurally unreachable after error check**

`validate_streaming` returns `None` only when a sub-validator pushed an error or the cross-field guard fired (both always push to `errors` first). The `if !errors.is_empty()` check above guarantees `validate_raw_configuration` has already returned before reaching this line, so `unwrap_or_default()` can never actually execute. It's harmless, but a comment or `expect` clarifying the invariant would make the relationship explicit and prevent future callers from accidentally adding a silent default path.

```rust
// SAFETY: validate_streaming returns None only after pushing to errors;
// the !errors.is_empty() guard above ensures we never reach here with None.
let streaming = streaming.expect("streaming validated without errors");
```

_{Reviews (3): Last reviewed commit: "Archive streaming robustness OpenSpec ch..." | Re-trigger Greptile}