Remove deprecated API, model server error codes, refactor FieldValue conversion, add cloud toolchain

[leogdion]

Summary

Four milestone v1.0.0-beta.4 issues, developed on separate worktrees and merged onto this branch: #421, #378, #358, and #295.

Warning

This PR contains breaking public API removals (#421). Four deprecated declarations are gone: CloudKitService.queryRecords(recordType:), CloudKitService.queryAllRecords(recordType:), CloudKitService.fetchCurrentUser(), and RecordManaging.queryRecords(recordType:). Callers must move to the paginating queryRecords(recordType:filters:sortBy:limit:desiredKeys:continuationMarker:database:) and to fetchCaller(). No @available(*, deprecated) declarations remain in Sources/MistKit.

What's in here

#421 — Remove deprecated public API before v1.0.0

Removes the four declarations above. RecordManaging itself is retained — it is not deprecated and still has conforming users.

#358 — Model every documented serverErrorCode

Gives 14 documented CloudKit server error codes their own CloudKitError case, replacing string-matching against a generic catch-all. Unknown codes map to .unknownServerError(code:statusCode:reason:). Adds ServerErrorCodeDetail and a CloudKitServiceTests.ServerErrorCodes suite; HandlingErrors.md now shows pattern-matching instead of string comparison.

httpErrorWithDetails(statusCode:reason:) is now used exclusively for failures that carried no server code.

#378 — Refactor FieldValue ↔ Components conversion

Replaces large switch/if-else chains with exhaustive dispatch, removing 5 default: branches that were silently swallowing unhandled cases. Adds FieldValue.ResponseTypeTag and a private ScalarPayload enum consolidating the scalar conversions.

#295 — Cloud toolchain setup

Two-tier setup adopted from ConfigKeyKit#7: Scripts/cloud-setup.sh runs once per cloud environment (snapshotted), and .claude/hooks/session-start.sh falls back to installing via swiftly and re-exports PATH into CLAUDE_ENV_FILE. Pins .swift-version to 6.3.2, matching MistDemo-Integration.yml.

Also adds Scripts/OpenAPITools/, a standalone manifest pinning the same generator version as mise.toml, so openapi.yaml can be regenerated in environments where mise cannot reach api.github.com. Verified: regeneration reproduces the committed Sources/MistKitOpenAPI output byte-identically.

Scripts/lint.sh now gates SwiftLint and periphery on CLAUDE_CODE_REMOTE, so web sessions run swift-format, the header check and --build-tests rather than failing on tooling they cannot install.

Verification

Run locally on Linux x86-64 / Swift 6.2 against the fully merged tree:

Check	Result
MistKit core	552 tests / 176 suites passing
MistDemo	970 tests / 289 suites passing
MistDemo / CelestraCloud / BushelCloud	all build against modified MistKit
swift-format lint + header check + --build-tests	clean (formatting produced no changes)

Not verified locally — relying on CI: wasm32 / wasm-embedded, Windows, Android, and all Apple platforms. SwiftLint and periphery did not run (no Linux binaries for periphery; mise cannot reach api.github.com from a web session) — they need a local ./Scripts/lint.sh.

Follow-ups (not blocking)

• Refactor FieldValue ↔ Components conversion to drop large switch/if-else chains #378 introduced and fixed an Int64→Int narrowing that would trap on 32-bit WASI for large timestamps. There is no 32-bit coverage, so the fix is unverified — a green wasm CI lane proves it compiles, not that the path is safe. Worth a review.
• MistDemoApp fails to build: NoteEditView/RecordDetailView have no accessible initializers (Swift 6.3) #419 is already fixed. The initializers it proposes for NoteEditView and RecordDetailView shipped in 5a58120 (v1.0.0 beta.3). The issue looks closable pending a swift build --target MistDemoApp on macOS with Swift 6.3.2, which Linux cannot run (no SwiftUI).
• openapi.yaml declares serverErrorCode as a closed enum, so unrecognized codes fail to decode before .unknownServerError is ever reached. Deferred to the openapi.yaml workstream.

Manual step required

.claude/settings.json is not in this branch and must be added for the SessionStart hook to run at all:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/session-start.sh\""
          }
        ]
      }
    ]
  }
}

Closes #421
Closes #378
Closes #358
Closes #295

[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 Plus

Run ID: 74e2c088-0e6a-430d-bc63-87306aed3fc2

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

---

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.}

[codecov]

Codecov Report

❌ Patch coverage is 95.38462% with 12 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (v1.0.0-beta.4@d295c30). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
...els/FieldValues/FieldValue+Components+Scalar.swift	91.93%	5 Missing ⚠️
...t/Models/Queries/FilterBuilder/FilterBuilder.swift	76.92%	3 Missing ⚠️
...oudKitService/CloudKitError+ErrorDescription.swift	86.66%	2 Missing ⚠️
...istKit/CloudKitService/ServerErrorCodeDetail.swift	92.85%	1 Missing ⚠️
Sources/MistKit/Models/OperationFailure.swift	50.00%	1 Missing ⚠️

Additional details and impacted files

@@               Coverage Diff                @@
##             v1.0.0-beta.4     #424   +/-   ##
================================================
  Coverage                 ?   78.60%           
================================================
  Files                    ?      159           
  Lines                    ?     3818           
  Branches                 ?        0           
================================================
  Hits                     ?     3001           
  Misses                   ?      817           
  Partials                 ?        0           

Flag	Coverage Δ
mistdemo-spm-macos	12.41% <25.76%> (?)
mistdemo-swift-6.2-jammy	12.41% <25.76%> (?)
mistdemo-swift-6.2-noble	12.41% <25.76%> (?)
mistdemo-swift-6.3-jammy	12.41% <25.76%> (?)
mistdemo-swift-6.3-noble	12.41% <25.76%> (?)
spm	76.82% <95.38%> (?)
swift-6.1-jammy	76.86% <95.38%> (?)
swift-6.1-noble	76.63% <95.38%> (?)
swift-6.2-jammy	76.57% <95.38%> (?)
swift-6.2-noble	76.70% <95.38%> (?)
swift-6.3-jammy	76.84% <95.38%> (?)
swift-6.3-noble	76.55% <95.38%> (?)

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.

[claude]

Review of #424 (milestone v1.0.0-beta.4)

This is a large, well-organized rollup of four issues (#421, #378, #358, #295). Overall the changes are consistent with the codebase conventions in CLAUDE.md — good exhaustive-dispatch cleanup in FieldValue+Components+Scalar.swift/FieldValue+ResponseTypeTag.swift, and the new CloudKitError.ServerErrorCode modeling is a solid improvement over string-matching. A few concrete issues surfaced during review:

Bugs — stale docs referencing the removed API (breaking, since #421 deletes it in this same PR)

queryRecords(recordType:database:) is deleted by this PR (the only surviving overload takes a Query struct: queryRecords(_ query: Query, ..., database:)), but four DocC pages still show the old, now-nonexistent call shape as a copy-pasteable example:

• Sources/MistKit/Documentation.docc/Documentation.md:33 — quick-start sample
• Sources/MistKit/Documentation.docc/HandlingErrors.md:97 — error-handling sample (ironic, since this file was otherwise heavily rewritten for the new error cases in this very PR)
• Sources/MistKit/Documentation.docc/AbstractionLayerArchitecture.md:199 — QueryFilter/QuerySort sample, just 3 lines below a correctly updated reference to the new signature in the same file
• Sources/MistKit/Documentation.docc/AuthenticationAndDatabases.md:109 — database-scope sample

Any reader who copies these snippets gets a compile error. Worth a follow-up pass to wrap these in Query(recordType:filters:sortBy:) per the new signature before merge, since the PR explicitly calls out that "no @available(*, deprecated) declarations remain" — the docs should match.

Minor — mapConflict in MistDemo isn't exhaustive over the new .unknownServerError case

Two conflict-mapping helpers touched by this PR don't account for CloudKitError.unknownServerError(code:statusCode:reason:):

• Examples/MistDemo/Sources/MistDemoKit/Commands/UpdateCommand.swift:76-92 (mapConflict) — switches structurally on .httpError/.httpErrorWithDetails/.httpErrorWithRawResponse. A 409 that arrives as .unknownServerError (e.g. a currently-unmodeled CloudKit server error code) matches none of those and falls through to default: return nil — so UpdateError.conflict is silently not raised for a case that used to map correctly pre-refactor (as a generic .httpErrorWithDetails).
• Examples/MistDemo/Sources/MistDemoKit/Commands/DeleteCommand.swift:70-80 (mapConflict) — same gap, but here the default: return .conflict(reason: nil) catch-all does still produce a conflict, just silently drops the reason string that .unknownServerError carries.

Both are currently dead paths in practice, since openapi.yaml declares serverErrorCode as a closed enum (unrecognized codes fail to decode before .unknownServerError is ever constructed) — and the PR description already flags that as a known, deferred gap. So this isn't launch-blocking, but it's worth a one-line follow-up (case .unknownServerError(_, let statusCode, let reason) where statusCode == 409: return .conflict(reason: reason)) so MistDemo's error mapping stays exhaustive once that enum opens up, rather than silently regressing conflict detection.

Other notes

• The Int64→Int narrowing follow-up flagged for Refactor FieldValue ↔ Components conversion to drop large switch/if-else chains #378 (32-bit WASI) is a reasonable call to defer — no 32-bit coverage exists to verify it either way, and it's clearly documented as unverified rather than silently shipped.
• RecordManaging retention (not deprecated, still has conformers) makes sense given queryRecords(recordType:) itself was removed from CloudKitService but the protocol's other members remain in use.
• Test coverage for the new ServerErrorCode modeling (ServerErrorCodes*.swift, 4 files) looks thorough — dedicated forward-compatibility and roundtrip suites are a nice touch for a closed-enum-adjacent feature.

Nothing above blocks the merge in my view, but I'd fix the four doc snippets before shipping since they're now actively wrong (not just outdated), and log a quick follow-up issue for the mapConflict exhaustiveness gap.