feat(cliniko): patient search + appointment picker (#9)

[CloudbrokerAz]

Summary

Patient search + appointment picker UI for Clinical Notes Mode export. Rides on ClinikoClient from #8 — adds two thin actor wrappers (ClinikoPatientService, ClinikoAppointmentService), an @Observable @MainActor view-model with debounced search, and the SwiftUI picker view itself. Selections flow through to SessionStore.active.selected{Patient,Appointment}ID so #14's export flow can consume them.

Closes #9.

Files

Models (Sources/Models/)

• Patient.swift — Decodable DTO; id: Int (Cliniko wire shape), dateOfBirth: String? (Cliniko returns YYYY-MM-DD which collides with the client's .iso8601 strategy — see file comment).
• Appointment.swift — Decodable DTO; startsAt/endsAt decode natively under .iso8601.
• ClinikoPagination.swift — PatientSearchResponse / AppointmentListResponse envelopes + ClinikoPaginationLinks { next: URL? }.

Services (Sources/Services/Cliniko/)

• ClinikoPatientService.swift — actor + protocol ClinikoPatientSearching: Actor. One method.
• ClinikoAppointmentService.swift — actor + protocol ClinikoAppointmentLoading: Actor. Window: [reference − 7d, reference + 1d] (UTC).

View layer (Sources/Views/ClinicalNotes/)

• PatientPickerViewModel.swift — @Observable @MainActor. Phase machines SearchPhase / AppointmentPhase. Debounce via Task.sleep(_:) + post-sleep cancellation re-check. Service refs @ObservationIgnored per concurrency.md §1. .cancelled swallowed on the search path (typing race), conditional on Task.isCancelled for the appointment path. Non-ClinikoError catch-all crashes in DEBUG (assertionFailure) and degrades to .transport(.unknown) + structural log in RELEASE — type names only, no PHI.
• PatientPickerView.swift — Warm Minimalism (.ultraThinMaterial, Color.amberLight/.amberBright, spring(0.5, 0.7)). Two panes: search (with all five SearchPhase states) and appointment list (with .idle/.loading/.loaded/.error). "No appointment / general note" is the first row of the appointment pane.

Tests (33 new tests, all green)

• Tests/.../Services/Cliniko/ClinikoPatientServiceTests.swift — 8 XCTest cases (decoding, query-item shape, 401/403/404/503 mapping, .cancelled).
• Tests/.../Services/Cliniko/ClinikoAppointmentServiceTests.swift — 5 XCTest cases (decoding, window edges, path encoding, 401/404).
• Tests/.../Views/PatientPickerViewModelTests.swift — 12 Swift Testing tests (debounce-no-call, debounce-collapse, all phase transitions, selection writes, clearSelection).
• Tests/.../Views/PatientPickerViewRenderTests.swift — 8 ViewInspector + crash-detection tests covering all phase combinations.

Why XCTest for the service tests: URLProtocolStub keeps a single process-wide responder. XCTest serialises tests within a class; Swift Testing parallelises them and they trample each other. Refactor tracked in #30. VM tests stay Swift Testing because they go through the actor protocols and don't touch URLProtocolStub.

Fixtures (Tests/.../Fixtures/cliniko/responses/)

• patients_search.json (3 synthetic results: Sample/Test/Fixture), patients_search_empty.json, patient_appointments.json (3 synthetic timeslots). All @example.test.

Acceptance criteria mapping

#9 acceptance	Coverage
First keystroke → no network call	debounce_firstKeystroke_noNetworkCall (asserts callCount == 0 after one keystroke + Task.yield())
Empty / loading / error states rendered	PatientPickerViewRenderTests.test_picker_*Phase_rendersWithoutCrash
Crash-detection (ViewInspector) instantiates picker with mock service	test_picker_instantiatesWithoutCrash, test_picker_bodyAccessDoesNotCrash
No patient data cached to disk	Services hold no state across calls; VM is @MainActor in-memory; no UserDefaults / FileManager writes; logs are structural-only (type names + path templates per phi-handling.md)

Pre-PR review

Three Opus reviewers ran in parallel — pr-review-toolkit:code-reviewer + silent-failure-hunter + type-design-analyzer. Findings folded in:

• Catch-all silent failure (silent-failure-hunter B1): now assertionFailure in DEBUG + structural log + degrade in RELEASE.
• .forbidden copy misroute (B2): now mentions API-key scopes explicitly.
• .cancelled race on appointment path (S1): only swallow when Task.isCancelled; otherwise surface as error.
• Stuck .searching / .loading after cancel (S2): cancel-guards now reset to .idle.
• .decoding copy (S3): now suggests "report it" so users have an action.
• .notFound resource discriminator (silent-failure-hunter N3): copy is now per-resource, e.g. "No matching patient" / "No matching appointment".
• reference: Date = Date() default on actor witness (type-design-analyzer): default removed — protocol existentials don't surface witness defaults, so leaving it would have misled callers.
• DateFormatter per-row (code-reviewer nit): hoisted to a static.

Type-design-analyzer flagged that selectedAppointmentID: Int? overloads "no choice yet" with "explicit no appointment / general note" — I've left it as-is for #9 because both states map to SessionStore.setSelectedAppointment(id: nil) and there's no consumer that distinguishes them today, but it should become a tri-state enum before #14's "Confirm export" flow lands.

Test plan

• CI green: PR-scoped pre-commit, swift test --parallel --enable-code-coverage against the documented skip list, codecov/patch.
• Gemini Code Assist: address inline comments.
• Local: swift test --parallel --skip <CI list> → all suites passing locally.

🤖 Generated with Claude Code

[CloudbrokerAz]

Re-opening against the correct base repo (CloudbrokerAz).

[gemini-code-assist]

Code Review

This pull request establishes the foundational architecture for the 'Clinical Notes Mode', introducing models and services for Cliniko API integration, local LLM prompt construction, and session management. It also overhauls the project's documentation and operating rules while addressing concurrency safety issues in Core Audio and SwiftUI components. Feedback highlights the need to resolve remaining Swift 6 strict concurrency violations involving non-Sendable formatters, specifically suggesting the use of the modern FormatStyle API or proper actor isolation for static and instance-level DateFormatters.

[gemini-code-assist]

The static iso8601Formatter is a stored property of a Sendable enum. Since ISO8601DateFormatter is not Sendable, this will trigger a data race warning or error in Swift 6 strict concurrency mode. Given the project baseline is macOS 14, you can replace the manual formatter with the more efficient and thread-safe FormatStyle API.

    static func iso8601(_ date: Date) -> String {
        date.formatted(.iso8601)
    }

[gemini-code-assist]

This static DateFormatter is a global stored property. Since DateFormatter is not Sendable, accessing it from multiple threads is a data race. In Swift 6, this should be isolated to the @MainActor to ensure safe access from the UI layer.

Suggested change

	private static let appointmentTimeFormatter: DateFormatter = {
	let formatter = DateFormatter()
	formatter.dateStyle = .medium
	formatter.timeStyle = .short
	return formatter
	}()
	@MainActor
	private static let appointmentTimeFormatter: DateFormatter = {
	let formatter = DateFormatter()
	formatter.dateStyle = .medium
	formatter.timeStyle = .short
	return formatter
	}()

[gemini-code-assist]

Storing a non-Sendable DateFormatter as actor state will trigger a compiler error in Swift 6 strict concurrency mode. While actor isolation protects it from concurrent access, the type itself must still be Sendable or the property must be marked nonisolated(unsafe). A safer alternative that avoids unsafe is to create the formatter on demand within the method, as it is only used on the 429 error path.