Docs: record content-based CloudKit subscription uniqueness finding (#387)

[leogdion]

Documentation-only. Captures the empirical finding that CloudKit enforces subscription uniqueness on (recordType, firesOn), not subscriptionID; duplicates surface as a misleading INTERNAL_ERROR ("could not find subscription we just created") with no formal CONFLICT/EXISTS code.

Added a subsection to the HandlingErrors.md docc article documenting the behavior and how MistKit infers it via the hedged isLikelyDuplicate hint / subscriptionLikelyDuplicate error (the API itself already landed); batch modifySubscriptions still returns raw failures via SubscriptionResult.failure.

Closes #387.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 104c1f45-0d3a-48d5-8434-66edfa16c903

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/subscription-uniqueness-findings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[claude]

Review: Docs — subscription-uniqueness findings (#416)

This PR adds a documentation subsection describing CloudKit's undocumented subscription-uniqueness behavior ((recordType, firesOn) collision → INTERNAL_ERROR) and the subscriptionLikelyDuplicate / isLikelyDuplicate hints MistKit uses to surface it. The prose is clear and the hedged framing matches the code's naming philosophy. Three issues surfaced that a maintainer should act on before merging.

---

1. Wrong error surface described — httpErrorWithDetails vs. in-body per-item failure [CONFIRMED bug, highest severity]

File: Sources/MistKit/Documentation.docc/HandlingErrors.md

The new section says:

…the rejection arrives as a generic CloudKitError/httpErrorWithDetails(statusCode:serverErrorCode:reason:) carrying serverErrorCode INTERNAL_ERROR…

This is factually incorrect. CloudKit returns a 200 OK for subscriptions/modify, with per-item failures embedded in the response body (SubscriptionsModifyResponse.subscriptions). CloudKitResponseProcessor.processModifySubscriptionsResponse processes the .ok branch — the .badRequest/.unauthorized/.undocumented branch (which produces httpErrorWithDetails) is never hit for duplicates.

The actual path is:

1. modifySubscriptions → 200 OK → SubscriptionResult.failure(OperationFailure{serverErrorCode: .internalError, reason: "could not find…"})
2. createSubscription checks failure.isLikelyDuplicate → throws CloudKitError.subscriptionLikelyDuplicate

httpErrorWithDetails is reserved for HTTP-level rejections (non-2xx). A developer reading this section and trying to catch or understand the error flow will be looking in the wrong place.

Suggested fix: Replace the sentence with something like:

…the rejection arrives as an inline per-item failure inside an otherwise-successful HTTP 200 response body. createSubscription surfaces it as CloudKitError/subscriptionLikelyDuplicate(_:) (carrying the raw INTERNAL_ERROR code and the marker reason string); modifySubscriptions surfaces it as SubscriptionResult/failure(_:).

---

2. Uniqueness key narrowed from "query" to "recordType" [CONFIRMED]

File: Sources/MistKit/Documentation.docc/HandlingErrors.md

The section (and the empirical Note below it) says the uniqueness key is (recordType, firesOn). The authoritative doc comment in CloudKitError.swift (line 75) says:

same query + firesOn, regardless of subscriptionID

query in CloudKit means the full CKQuery-equivalent: record type plus any filter predicates. Documenting only recordType is misleading — two subscriptions with the same recordType but different filter predicates might not collide, while the current wording implies they would. Both occurrences should use "query" (or "query + firesOn") consistently with the rest of the codebase.

---

3. subscriptionOperationFailed and subscriptionLikelyDuplicate missing from the CloudKitError cases table [CONFIRMED]

File: Sources/MistKit/Documentation.docc/HandlingErrors.md (around line 80)

The PR adds a standalone subsection for the subscription-duplicate pattern but leaves the main CloudKitError cases table unchanged. That table is the canonical discovery surface for users who don't yet know what error to expect. Both subscriptionOperationFailed and subscriptionLikelyDuplicate should have rows there — otherwise a developer scanning the table during error-handling design won't find them.

Suggested additions:

| ``CloudKitError/subscriptionOperationFailed(_:)`` | No | A per-subscription failure in a batch `modifySubscriptions` |
| ``CloudKitError/subscriptionLikelyDuplicate(_:)`` | No | Inferred duplicate from `createSubscription`; see subsection below |

---

Minor / non-blocking

• The ### Per-operation failures Topics group at the bottom is a reasonable addition, but SubscriptionOperationFailure and SubscriptionResult might sit more naturally adjacent to the existing ### Error types group (they are error-surface types, not a third category).
• failure.reason ?? "" in the code example will log an empty string when reason is nil; failure.reason ?? "<no reason>" or failure.reason.map { "Subscription likely duplicate: \($0)" } ?? "Subscription likely duplicate" would be more informative, though this is style-level.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 11.52%. Comparing base (9894d48) to head (843fd18).
⚠️ Report is 4 commits behind head on v1.0.0-beta.3.

❗ There is a different number of reports uploaded between BASE (9894d48) and HEAD (843fd18). Click for more details.

HEAD has 9 uploads less than BASE

Flag	BASE (9894d48)	HEAD (843fd18)
spm	3	0
swift-6.3-noble	1	0
swift-6.1-noble	1	0
swift-6.2-noble	1	0
swift-6.2-jammy	1	0
swift-6.1-jammy	1	0
swift-6.3-jammy	1	0

Additional details and impacted files

@@                Coverage Diff                 @@
##           v1.0.0-beta.3     #416       +/-   ##
==================================================
- Coverage          71.82%   11.52%   -60.31%     
==================================================
  Files                168      168               
  Lines               3844     3844               
==================================================
- Hits                2761      443     -2318     
- Misses              1083     3401     +2318     

Flag	Coverage Δ
mistdemo-spm-macos	11.42% <ø> (ø)
mistdemo-swift-6.2-jammy	11.42% <ø> (ø)
mistdemo-swift-6.2-noble	11.42% <ø> (ø)
mistdemo-swift-6.3-jammy	11.42% <ø> (ø)
mistdemo-swift-6.3-noble	11.52% <ø> (+0.10%)	⬆️
spm	?
swift-6.1-jammy	?
swift-6.1-noble	?
swift-6.2-jammy	?
swift-6.2-noble	?
swift-6.3-jammy	?
swift-6.3-noble	?

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.