feat: data provenance, clinic-tz appts, slot-conflict recovery, import validation (#1012)

- medicationService: expose interaction-warning provenance (source/version/
  publish date), an update policy, an unavailable state and a freshness-aware
  disclaimer so stale warnings are not shown as clinically authoritative.
- appointmentTime util: resolve/validate appointment slots in the clinic's IANA
  timezone, transporting UTC + clinic zone; DST-safe, and flags when the device
  timezone would shift the displayed slot.
- appointmentService: bookAppointmentWithConflictHandling() refreshes alternative
  slots on HTTP 409, preserves safe form inputs (never the dead slot), and sends
  an Idempotency-Key so a retry cannot double-book.
- medicalFileValidation util + ImportRecordScreen: enforce type/size limits and
  reject malformed or password-protected PDFs with safe, non-leaking errors
  before any parsing happens.

Each change is covered by focused unit tests (synthetic data only).

closes #959
closes #960
closes #961
closes #962

Author: orsar-rita

src/screens/ImportRecordScreen.tsx

@@ -18,6 +18,7 @@ import type {
   Treatment,
   VaccinationRecord,
 } from '../models/MedicalRecord';
+import { validateMedicalImportFile } from '../utils/medicalFileValidation';
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
@@ -111,6 +112,20 @@ const ImportRecordScreen: React.FC<Props> = ({ petId, petName, onBack, onImporte
       return;
     }
 
+    // Validate the document before it reaches the parser: enforce type/size
+    // limits and reject encrypted or malformed PDFs with a safe error. (#962)
+    const approxBytes = Math.floor((pdfBase64.replace(/\s/g, '').length * 3) / 4);
+    const validation = validateMedicalImportFile({
+      name: 'import.pdf',
+      size: approxBytes,
+      mimeType: 'application/pdf',
+      base64: pdfBase64,
+    });
+    if (!validation.ok) {
+      Alert.alert('Cannot import file', validation.message);
+      return;
+    }
+
     setLoading(true);
     try {
       const response = await fetch('/api/import/medical-records/parse-pdf', {

src/services/__tests__/appointmentSlotConflict.test.ts

@@ -0,0 +1,112 @@
+import {
+  bookAppointmentWithConflictHandling,
+  type BookAppointmentRequest,
+} from '../appointmentService';
+import { upsertAppointment } from '../localDB';
+import apiClient from '../apiClient';
+
+jest.mock('../apiClient', () => ({
+  __esModule: true,
+  default: { get: jest.fn(), post: jest.fn(), put: jest.fn(), delete: jest.fn() },
+}));
+
+jest.mock('../localDB', () => ({
+  getAllLocalAppointments: jest.fn(),
+  getAllAppointmentsByPetId: jest.fn(),
+  getAppointmentsInWindow: jest.fn(),
+  upsertAppointment: jest.fn(),
+  deleteAppointmentById: jest.fn(),
+}));
+
+jest.mock('expo-notifications', () => ({
+  scheduleNotificationAsync: jest.fn(),
+  cancelScheduledNotificationAsync: jest.fn(),
+  SchedulableTriggerInputTypes: { DATE: 'date' },
+}));
+
+const mockPost = jest.mocked(apiClient).post as jest.Mock;
+const mockGet = jest.mocked(apiClient).get as jest.Mock;
+const mockUpsert = upsertAppointment as jest.Mock;
+
+const baseReq: BookAppointmentRequest = {
+  petId: 'pet-1',
+  vetId: 'vet-1',
+  date: '2026-09-01',
+  time: '10:00',
+  title: 'Dental cleaning',
+  location: 'Downtown Clinic',
+  vetName: 'Dr. Synthetic',
+  notes: 'Nervous around strangers',
+  durationMinutes: 30,
+  idempotencyKey: 'attempt-abc-123',
+};
+
+const conflict409 = Object.assign(new Error('Conflict'), { response: { status: 409 } });
+
+beforeEach(() => jest.clearAllMocks());
+
+describe('bookAppointmentWithConflictHandling (#961)', () => {
+  it('books normally and persists locally when the slot is free', async () => {
+    mockPost.mockResolvedValueOnce({ data: { data: { id: 'a1', ...baseReq } } });
+
+    const result = await bookAppointmentWithConflictHandling(baseReq);
+
+    expect(result.status).toBe('booked');
+    expect(mockUpsert).toHaveBeenCalledWith(expect.objectContaining({ id: 'a1' }));
+  });
+
+  it('sends the idempotency key as a header so retries cannot double-book', async () => {
+    mockPost.mockResolvedValueOnce({ data: { data: { id: 'a1' } } });
+
+    await bookAppointmentWithConflictHandling(baseReq);
+
+    expect(mockPost).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.any(Object),
+      expect.objectContaining({ headers: { 'Idempotency-Key': 'attempt-abc-123' } }),
+    );
+  });
+
+  it('on 409 refreshes alternative slots and preserves safe form inputs', async () => {
+    mockPost.mockRejectedValueOnce(conflict409);
+    mockGet.mockResolvedValueOnce({
+      data: {
+        data: { vetId: 'vet-1', date: '2026-09-01', availableSlots: ['10:00', '10:30', '11:00'] },
+      },
+    });
+
+    const result = await bookAppointmentWithConflictHandling(baseReq);
+
+    if (result.status !== 'conflict') throw new Error('expected conflict');
+    expect(result.alternatives).toEqual(['10:30', '11:00']); // conflicted 10:00 removed
+    expect(result.preservedInput).toMatchObject({
+      petId: 'pet-1',
+      title: 'Dental cleaning',
+      location: 'Downtown Clinic',
+      vetName: 'Dr. Synthetic',
+      notes: 'Nervous around strangers',
+      date: '2026-09-01',
+    });
+    // The dead time is not carried back into the form.
+    expect((result.preservedInput as Record<string, unknown>).time).toBeUndefined();
+    expect(mockUpsert).not.toHaveBeenCalled();
+  });
+
+  it('still returns a usable conflict result when availability lookup fails', async () => {
+    mockPost.mockRejectedValueOnce(conflict409);
+    mockGet.mockRejectedValueOnce(new Error('offline'));
+
+    const result = await bookAppointmentWithConflictHandling(baseReq);
+
+    expect(result.status).toBe('conflict');
+    if (result.status === 'conflict') expect(result.alternatives).toEqual([]);
+  });
+
+  it('rethrows non-409 errors so existing handling applies', async () => {
+    mockPost.mockRejectedValueOnce(
+      Object.assign(new Error('Server error'), { response: { status: 500 } }),
+    );
+
+    await expect(bookAppointmentWithConflictHandling(baseReq)).rejects.toThrow('Server error');
+  });
+});

src/services/__tests__/medicationInteractionProvenance.test.ts

@@ -0,0 +1,90 @@
+import {
+  INTERACTION_DATA_PROVENANCE,
+  INTERACTION_DATA_STALE_AFTER_DAYS,
+  INTERACTION_DATA_UNAVAILABLE_AFTER_DAYS,
+  assessInteractionDataFreshness,
+  presentInteractionWarning,
+} from '../medicationService';
+
+jest.mock('@react-native-async-storage/async-storage', () => ({
+  getItem: jest.fn(),
+  setItem: jest.fn(),
+  removeItem: jest.fn(),
+}));
+
+jest.mock('expo-notifications', () => ({
+  scheduleNotificationAsync: jest.fn(),
+  cancelScheduledNotificationAsync: jest.fn(),
+  SchedulableTriggerInputTypes: { DATE: 'date' },
+}));
+
+const published = new Date(INTERACTION_DATA_PROVENANCE.publishedAt).getTime();
+const daysAfterPublish = (n: number) => new Date(published + n * 24 * 60 * 60 * 1000);
+
+describe('medication interaction data provenance & freshness (#959)', () => {
+  // Characterises the current/target behaviour before the UI consumes it.
+  it('exposes source, version and publish date as provenance', () => {
+    expect(INTERACTION_DATA_PROVENANCE.source).toEqual(expect.any(String));
+    expect(INTERACTION_DATA_PROVENANCE.version).toEqual(expect.any(String));
+    expect(() => new Date(INTERACTION_DATA_PROVENANCE.publishedAt).toISOString()).not.toThrow();
+  });
+
+  it('treats recent data as fresh and authoritative', () => {
+    const status = assessInteractionDataFreshness(daysAfterPublish(10));
+    expect(status.freshness).toBe('fresh');
+    expect(status.authoritative).toBe(true);
+    expect(status.unavailable).toBe(false);
+    expect(status.ageDays).toBe(10);
+    expect(status.disclaimer).toMatch(/veterinar/i);
+  });
+
+  it('flags data past the stale threshold as non-authoritative but still shown', () => {
+    const status = assessInteractionDataFreshness(
+      daysAfterPublish(INTERACTION_DATA_STALE_AFTER_DAYS + 1),
+    );
+    expect(status.freshness).toBe('stale');
+    expect(status.authoritative).toBe(false);
+    expect(status.unavailable).toBe(false);
+    expect(status.disclaimer).toMatch(/out of date|old/i);
+  });
+
+  it('marks data past the unavailable threshold as expired and withheld', () => {
+    const status = assessInteractionDataFreshness(
+      daysAfterPublish(INTERACTION_DATA_UNAVAILABLE_AFTER_DAYS + 1),
+    );
+    expect(status.freshness).toBe('expired');
+    expect(status.authoritative).toBe(false);
+    expect(status.unavailable).toBe(true);
+    expect(status.updatePolicy).toMatch(/withheld|stale/i);
+  });
+
+  it('handles a malformed publish date as expired rather than crashing', () => {
+    const status = assessInteractionDataFreshness(new Date(), {
+      ...INTERACTION_DATA_PROVENANCE,
+      publishedAt: 'not-a-date',
+    });
+    expect(status.unavailable).toBe(true);
+    expect(status.ageDays).toBe(Number.POSITIVE_INFINITY);
+  });
+
+  describe('presentInteractionWarning', () => {
+    it('attaches an attribution line and keeps the message when fresh', () => {
+      const p = presentInteractionWarning('Do not combine drug A and drug B.', daysAfterPublish(5));
+      expect(p.message).toContain('drug A');
+      expect(p.attribution).toContain(INTERACTION_DATA_PROVENANCE.source);
+      expect(p.attribution).toContain('5 days old');
+      expect(p.authoritative).toBe(true);
+      expect(p.suppressed).toBe(false);
+    });
+
+    it('suppresses the warning body once the data is expired', () => {
+      const p = presentInteractionWarning(
+        'Do not combine drug A and drug B.',
+        daysAfterPublish(INTERACTION_DATA_UNAVAILABLE_AFTER_DAYS + 5),
+      );
+      expect(p.message).toBe('');
+      expect(p.suppressed).toBe(true);
+      expect(p.disclaimer).toMatch(/unavailable/i);
+    });
+  });
+});

src/services/appointmentService.ts

@@ -422,3 +422,101 @@ export async function checkConflicts(
     };
   }
 }
+
+// ─── Slot-conflict-safe booking (issue #961) ─────────────────────────────────
+
+/**
+ * Fields the user typed that are safe to carry back into the form after a slot
+ * conflict — never the (now-invalid) date/time, never anything server-assigned.
+ */
+export type PreservableBookingInput = Pick<
+  Appointment,
+  'petId' | 'title' | 'location' | 'vetName' | 'notes' | 'durationMinutes'
+> & { vetId?: string };
+
+export interface BookAppointmentRequest extends PreservableBookingInput {
+  /** Requested slot, `YYYY-MM-DD`. */
+  date: string;
+  /** Requested slot, `HH:mm`. */
+  time: string;
+  vetId: string;
+  /**
+   * Stable key identifying this booking attempt. Re-sent verbatim on retry so
+   * the server can dedupe and never create two appointments for one intent.
+   */
+  idempotencyKey: string;
+}
+
+export type BookAppointmentResult =
+  | { status: 'booked'; appointment: Appointment }
+  | {
+      status: 'conflict';
+      /** Fresh alternative slots (`HH:mm`) for the same vet/date, if any. */
+      alternatives: string[];
+      /** The user's inputs minus the conflicted slot, ready to re-seed the form. */
+      preservedInput: PreservableBookingInput & { date: string };
+      message: string;
+    };
+
+function pickPreservable(req: BookAppointmentRequest): PreservableBookingInput {
+  const { petId, title, location, vetName, notes, durationMinutes, vetId } = req;
+  return { petId, title, location, vetName, notes, durationMinutes, vetId };
+}
+
+function httpStatusOf(error: unknown): number | undefined {
+  const resp = (error as { response?: { status?: number } })?.response;
+  return typeof resp?.status === 'number' ? resp.status : undefined;
+}
+
+/**
+ * Book an appointment, tolerating the slot being taken between selection and
+ * submit:
+ *  - On HTTP 409 the form state is preserved (minus the dead slot) and a fresh
+ *    list of alternative slots is fetched so the user can re-pick in place.
+ *  - The caller-supplied `idempotencyKey` is sent as a header so a retry of the
+ *    same intent can never double-book.
+ *
+ * Throws for non-409 errors so existing error handling still applies.
+ */
+export async function bookAppointmentWithConflictHandling(
+  req: BookAppointmentRequest,
+): Promise<BookAppointmentResult> {
+  try {
+    const response = await apiClient.post<{ data: Appointment }>(
+      BASE_URL,
+      {
+        petId: req.petId,
+        vetId: req.vetId,
+        date: req.date,
+        time: req.time,
+        durationMinutes: req.durationMinutes,
+        title: req.title,
+        location: req.location,
+        vetName: req.vetName,
+        notes: req.notes,
+      },
+      { headers: { 'Idempotency-Key': req.idempotencyKey } },
+    );
+    const appointment = response.data.data;
+    await upsertAppointment(appointment);
+    return { status: 'booked', appointment };
+  } catch (error) {
+    if (httpStatusOf(error) !== 409) throw error;
+
+    let alternatives: string[] = [];
+    try {
+      const availability = await getAvailability(req.vetId, req.date);
+      alternatives = (availability.availableSlots ?? []).filter((slot) => slot !== req.time);
+    } catch {
+      alternatives = [];
+    }
+
+    return {
+      status: 'conflict',
+      alternatives,
+      preservedInput: { ...pickPreservable(req), date: req.date },
+      message:
+        'That time was just booked by someone else. Your details are saved — pick another slot below.',
+    };
+  }
+}