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: c5482019-a920-4939-83da-d2101d98aa3d

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@4fabb07). 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.44% ================================================
Files ? 159 Lines ? 3818 Branches ? 0 ================================================
Hits ? 2995 Misses ? 823 Partials ? 0 

Flag	Coverage Δ
mistdemo-spm-macos	12.41% <25.76%> (?)
mistdemo-swift-6.2-jammy	12.44% <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%> (?)
mistdemo-swift-6.4-jammy	12.41% <25.76%> (?)
mistdemo-swift-6.4-noble	12.41% <25.76%> (?)
spm	76.55% <95.38%> (?)
swift-6.1-jammy	76.55% <95.38%> (?)
swift-6.1-noble	76.73% <95.00%> (?)
swift-6.2-jammy	76.55% <95.38%> (?)
swift-6.2-noble	76.52% <95.38%> (?)
swift-6.3-jammy	76.68% <95.38%> (?)
swift-6.3-noble	76.84% <95.38%> (?)
swift-6.4-jammy	76.73% <95.38%> (?)
swift-6.4-noble	76.84% <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.

[claude]

Review

Reviewed the merged diff (base cedc784 → head 6a98a56, ~70 files / +1932 −686). This bundles four issues (#421, #378, #358, #295); feedback organized by workstream.

#421 — Remove deprecated API

Clean removal. RecordManaging.queryRecords(recordType:) and its default queryAllRecords shim are gone along with the CloudKitService conformance; queryAllRecords(recordType:) now does real pagination as the sole requirement. Nice catch fixing the stale doc comment on CloudKitService+RecordManaging.swift — it said .requires(.serverToServer) while the code (both before and after) actually used .prefers(.serverToServer); the wording now matches reality. Example call sites (MistDemo, CelestraCloud) were migrated to the Query-value overload correctly.

#358 — Per-serverErrorCodeCloudKitError cases

The design is solid: CloudKitServerErrorCode.knownCatalog is now the single source of truth for wire string / HTTP status / summary (nice simplification from the old linear-scan knownPairs to a Dictionary-backed byRawValue/byCode), and ServerErrorCodeDetail + serverErrorDetail centralize the case → detail mapping used by both errorDescription and httpStatusCode. The exhaustive switch in serverErrorDetail and Self.make(from:...) means a future case addition to CloudKitError won't silently fall through.

A genuine bug fix rides along in CelestraError.isCloudKitErrorRetriable: it now checks error.httpStatusCode directly instead of only matching the old three raw-HTTP cases, so .throttled/.tryAgainLater/.internalServerError correctly participate in retry logic. Good catch and the updated comment explains it well.

One thing worth double-checking before merge: this is called out as "a deliberate breaking API change" in the commit message, and the .httpErrorWithDetails payload shrank from 3 fields to 2 (dropped serverErrorCode). Any downstream consumer pattern-matching the old 3-arg case (outside this repo) will fail to compile — worth confirming the version bump / changelog reflects this appropriately, since MistKit is pre-1.0 but still.

#378 — FieldValue conversion refactor

Good mechanical refactor — ScalarPayload and ResponseTypeTag collapse the four default-having switches into total ones, and FieldValueRequest.init(from:) / cloudKitListType(for:) becoming fully exhaustive switches (removing the unreachable Self(value: .ListValue([])) fallback and the "nested lists" default) is a real improvement — the compiler now enforces that a new FieldValue case gets handled everywhere.

The PR body already flags the Int64 -> Int narrowing in ScalarPayload.inferred (.int64(let intVal): return .int64(Int(intVal))) as an unverified 32-bit-WASI risk. Worth noting this narrowing isn't new — it's carried over unchanged from the pre-refactor makeInferredScalar, just relocated — so it's pre-existing behavior, not a regression from this PR. Still agree it's worth a follow-up issue with 32-bit WASI test coverage before v1.0 rather than blocking here.

#295 — Cloud toolchain setup

Scripts/cloud-setup.sh and .claude/hooks/session-start.sh are well-guarded: CLAUDE_CODE_REMOTE gates all the install logic so local sessions are untouched, cloud-setup.sh avoids set -e deliberately (documented) so it always exits 0, and both scripts fetch swiftly over HTTPS from download.swift.org rather than a curl-pipe-to-bash pattern. Scripts/lint.sh/Scripts/generate-openapi.sh degrading gracefully when mise can't reach api.github.com (falling back to Scripts/OpenAPITools) is a nice touch, and the PR verified byte-identical regeneration output.

Per the PR description, .claude/settings.json needs to be added manually (not committed here) for the SessionStart hook to actually fire — make sure that doesn't get lost after merge.

Test coverage

The new ServerErrorCodes suite is thorough — parameterized roundtrip across all 14 codes, plus explicit forward-compatibility coverage for .unknownServerError, a codeless body, and the documented current gap where an unmodelled code fails at .decodingError (since serverErrorCode is a closed enum in openapi.yaml) rather than reaching .unknownServerError. That gap is called out in the PR's non-blocking follow-ups, consistent with the fail-loud philosophy documented in CLAUDE.md.

Nit

CloudKitError+ServerErrorCode.swift's serverErrorDetail and Self.make(from:...) both carry // swiftlint:disable:next cyclomatic_complexity — expected given 15+ cases in a single exhaustive switch, and preferable to a lossy default, so no change requested, just flagging for awareness.

Overall this looks well-scoped despite touching four issues at once — each sub-change is independently reasonable, the breaking changes are called out explicitly, and the verification section is detailed about what was and wasn't run locally. No blocking issues found.

[leogdion]

Review/merge order note

Proposed order for the v1.0.0-beta.4 queue: #425 → #424 → #427 → #426 → #429 → #428

This PR should go second, right after #425 — it's the destructive/foundational one, and everything else should be rebased onto post-removal state rather than the reverse.

Why early:

• It deletes CloudKitService+Operations+Deprecated.swift (−159) and rewrites CloudKitError.swift (+52/−14) and the FieldValue ↔ Components conversion. Landing it late means re-resolving those against four other branches.
• It touches none of openapi.yaml / Sources/MistKitOpenAPI/Types.swift, so it doesn't compete with the generated-code cluster (Add confirmed zone metadata (syncToken, atomic) to zone schemas #427/Add records/resolve and records/accept share operations (#41, #42) #428/Add changes/database and changes/zone endpoints; deprecate zones/changes (#401, #47, #46) #429) at all.
• Scripts/OpenAPITools/ (from Add SessionStart hook to install Swift toolchain for Claude Code on the web #295) is exactly what the other three need to regenerate cheaply after each merge. Getting it in first pays for itself three times.

Two conflicts this PR creates downstream

1. Add custom/shared zone support to the query path (#146) #426 adds +6 lines to CloudKitService+Operations+Deprecated.swift — the file this PR deletes outright. That hunk has to move (presumably into CloudKitService+Operations.swift) when Add custom/shared zone support to the query path (#146) #426 rebases. Both PRs also touch CloudKitService+Classification.swift, QueryRecordsPhase.swift, and CloudKitService+WebBackend.swift.

2. Deprecation policy vs Add changes/database and changes/zone endpoints; deprecate zones/changes (#401, #47, #46) #429. This PR's summary states "No @available(*, deprecated) declarations remain in Sources/MistKit."Add changes/database and changes/zone endpoints; deprecate zones/changes (#401, #47, #46) #429 adds two new ones (fetchZoneChanges / fetchAllZoneChanges, deprecating zones/changes in favor of changes/database). Those can't both be true at 1.0. Worth deciding here rather than letting whichever merges last settle it silently:

   • (a) pre-1.0 rule is remove-don't-deprecate → zones/changes goes away outright in Add changes/database and changes/zone endpoints; deprecate zones/changes (#401, #47, #46) #429, no new @available; or
   • (b) narrow this PR's claim to "no deprecations carried over from before beta.4," which leaves room for Add changes/database and changes/zone endpoints; deprecate zones/changes (#401, #47, #46) #429 to ship the deprecation as written.