chore: dead-API sweep — TextMessage, SdCardBusyException, abandoned simulator docs

[tylerkron]

Summary

Closes #463 — three vestigial items found in a repo sweep, each resolved differently:

1. TextMessage (Communication/Messages/TextMessage.cs) — a public IInboundMessage<string> referenced nowhere in Core src/tests/docs, nowhere in daqifi-desktop (origin/main), and nowhere in daqifi-core-example-app (origin/main). Removed.

2. SdCardBusyException — declared but never thrown. Rather than delete it (and coordinate a desktop PR to drop its now-dead SdCardFailureClassifier match arm), I found the exception actually has a real, already-detected condition to describe: SdCardOperations already tracks _isLoggingToSdCard and refuses GetSdCardStorageAsync, DeleteSdCardFileAsync, FormatSdCardAsync, and DownloadSdCardFileAsync while a logging session is active — it was just throwing a generic InvalidOperationException for that instead of the typed exception that exists for exactly this. Switched all four call sites to throw SdCardBusyException, which makes desktop's existing classifier arm (SdCardFailureClassifier.cs:180, "The device is still using the SD card. Stop logging, wait a moment, and try again.") live instead of dead — no desktop changes required.

3. docs/archive/simulator/ — five planning docs for a device simulator that was never built, no corresponding code anywhere. Deleted.

Breaking changes (for release notes)

• TextMessage public type removed.
• GetSdCardStorageAsync, DeleteSdCardFileAsync, FormatSdCardAsync, and DownloadSdCardFileAsync now throw SdCardBusyException (derives from SdCardOperationException, not InvalidOperationException) when called while an SD logging session is active. Callers catching InvalidOperationException for that case need to catch SdCardBusyException instead.

Verification

• dotnet build — 0 warnings, 0 errors
• dotnet test src/Daqifi.Core.Tests — 2826 passed, 0 failed (net9.0 and net10.0), 2 skipped (real-hardware-only transport tests)
• No hardware/wire-format behavior changed (the SD-busy check is purely client-side state), so no bench test was needed
• Verified against daqifi-desktop origin/main and daqifi-core-example-app origin/main that TextMessage has zero references, and that desktop's SdCardBusyException match arm is exactly the dead code the issue describes

🤖 Generated with Claude Code

[qodo-code-review]

PR Summary by Qodo

Dead-API sweep: remove TextMessage, throw SdCardBusyException, drop simulator docs

🐞 Bug fix 📝 Documentation 🧪 Tests 🕐 20-40 Minutes

AI Description

• Remove unused public TextMessage inbound message type.
• Throw SdCardBusyException for SD operations while an SD logging session is active.
• Delete abandoned simulator planning docs from docs/archive.

Diagram

graph TD
  A["Caller (app/SDK)"] --> B["SdCardOperations"] --> C{{"Logging active?"}} -->|"Yes"| D(("SdCardBusyException"))
  C -->|"No"| E["Transport / SCPI"] --> F["Device firmware"]
  T["SdCardOperationsTests"] --> B

  subgraph Legend
    direction LR
    _proc["Process"] ~~~ _dec{{"Decision"}} ~~~ _exc(("Exception"))
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Keep InvalidOperationException for compatibility

• ➕ Non-breaking for callers currently catching InvalidOperationException
• ➕ No behavior change in exception hierarchy
• ➖ Desktop/app-side typed classification remains dead or requires string/message parsing
• ➖ Harder for callers to distinguish SD-busy vs other invalid-state cases reliably

2. Throw SdCardOperationException with a Busy error code (instead of a distinct type)

• ➕ Still typed within SD-card error domain; fewer public exception types
• ➕ Easier to handle as a single catch with branching on reason
• ➖ Requires adding/standardizing an error-code mechanism and updating consumers
• ➖ Less idiomatic than a dedicated exception when consumers already match on SdCardBusyException

3. Throw SdCardBusyException with a clearer message/context payload

• ➕ Improves diagnostics without changing the chosen typed-exception approach
• ➕ Can preserve existing UX strings in downstream apps via exception message
• ➖ May require adjusting SdCardBusyException constructors/serialization to carry context consistently

Recommendation: The PR’s approach (throw the already-defined SdCardBusyException) is the best fit because downstream code can reliably classify the condition without fragile message matching, and it activates an existing desktop classifier path. If additional improvement is desired, consider enriching SdCardBusyException with a standard message or context (e.g., operation name) to keep diagnostics strong while retaining the typed contract.

Files changed (2) +16 / -16

Bug fix (1) +8 / -7

SdCardOperations.csThrow SdCardBusyException when SD operations run during active logging +8/-7

Throw SdCardBusyException when SD operations run during active logging

• Replaces InvalidOperationException with SdCardBusyException when _isLoggingToSdCard is true for GetSdCardStorageAsync, DeleteSdCardFileAsync, FormatSdCardAsync, and DownloadSdCardFileAsync. Updates XML documentation to reflect the new exception contract for these APIs.

src/Daqifi.Core/Device/SdCard/SdCardOperations.cs

Tests (1) +8 / -9

SdCardOperationsTests.csUpdate SD-card busy tests to expect SdCardBusyException +8/-9

Update SD-card busy tests to expect SdCardBusyException

• Renames the affected tests and updates assertions to expect SdCardBusyException instead of InvalidOperationException. Removes the message-content assertion that was specific to the previous generic exception.

src/Daqifi.Core.Tests/Device/SdCard/SdCardOperationsTests.cs

[tylerkron]

/agentic_review

[tylerkron]

/agentic_review

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. SD API docs mismatch ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

SdCardOperations now throws SdCardBusyException when SD logging is active, but the public
ISdCardOperations XML docs still declare InvalidOperationException (and the download overloads don’t
mention the busy exception). This makes the public exception contract and generated docs incorrect,
and CheckSdCardSpaceAsync now also throws SdCardBusyException via GetSdCardStorageAsync.

Code

src/Daqifi.Core/Device/SdCard/SdCardOperations.cs[R423-426]

            if (_isLoggingToSdCard)
            {
-                throw new InvalidOperationException("Cannot query SD card storage while logging to SD card.");
+                throw new SdCardBusyException(Array.Empty<string>());
            }

Relevance

●●● Strong

Team often accepts fixing XML docs to match actual behavior/exception surface; avoids incorrect
public contract.

PR-#321
PR-#357
PR-#435

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The implementation now throws SdCardBusyException when _isLoggingToSdCard is true, but the public
interface still documents InvalidOperationException for the same scenarios and doesn’t list the busy
exception on download. Additionally, CheckSdCardSpaceAsync delegates to GetSdCardStorageAsync, so it
now also throws SdCardBusyException even though the interface docs still claim
InvalidOperationException.

src/Daqifi.Core/Device/SdCard/SdCardOperations.cs[399-426]
src/Daqifi.Core/Device/SdCard/SdCardOperations.cs[516-535]
src/Daqifi.Core/Device/SdCard/ISdCardOperations.cs[50-86]
src/Daqifi.Core/Device/SdCard/ISdCardOperations.cs[160-179]
src/Daqifi.Core/Device/SdCard/ISdCardOperations.cs[180-233]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`SdCardOperations` switched the “called while SD logging is active” guard from `InvalidOperationException` to `SdCardBusyException`, but `ISdCardOperations` still documents the old exception type and omits the new exception on the download overloads. This leaves public IntelliSense/generated docs wrong and hides that `CheckSdCardSpaceAsync` now also throws `SdCardBusyException` because it calls `GetSdCardStorageAsync`.

### Issue Context
- The runtime behavior already changed to throw `SdCardBusyException`.
- `DaqifiStreamingDevice` uses `<inheritdoc />`, so the interface documentation is what most consumers will see.

### Fix Focus Areas
- src/Daqifi.Core/Device/SdCard/ISdCardOperations.cs[50-86]
- src/Daqifi.Core/Device/SdCard/ISdCardOperations.cs[160-179]
- src/Daqifi.Core/Device/SdCard/ISdCardOperations.cs[180-233]

### What to change
- Replace `System.InvalidOperationException` with `SdCardBusyException` in the `<exception>` tags for:
 - `GetSdCardStorageAsync`
 - `CheckSdCardSpaceAsync`
 - `DeleteSdCardFileAsync`
 - `FormatSdCardAsync`
- Add `<exception cref="SdCardBusyException">…</exception>` to both `DownloadSdCardFileAsync` overload docs.
- (Optional) If you maintain release notes in-repo, ensure `CheckSdCardSpaceAsync` is included as a behavior change too (it now propagates `SdCardBusyException`).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

_{To customize comments, go to the Qodo configuration screen, or learn more in the docs.}

[tylerkron]

/agentic_review

[qodo-code-review]

Code review by qodo was updated up to the latest commit 30394a9