Merge pull request #1007 from muhdusama/medfix/apple-health-scheduled-mirror

fix: allow scheduled Apple Health medication mirrors

docs/api/openapi.yaml

@@ -5827,12 +5827,10 @@ paths:
       tags:
         - Medications
       summary: Batched adherence read for every medication of the caller
-      description: Returns one compact adherence row per medication the caller owns (active + paused), ordered by `createdAt
-        DESC` — the single round trip the medication cards consume instead of fanning out one
-        `/api/medications/{id}/compliance` request per card. Each row carries the 7-/30-day summaries and the
-        cadence-scaled display block; the per-day grid stays on the per-medication endpoint. Pure computation — no
-        writes. Served through the same per-medication server cache as the per-id read, so the two endpoints warm each
-        other.
+      description: Returns one compact row per non-PRN medication. A scheduled medication with no local schedule remains in
+        the array with applicable=false and reason NO_LOCAL_SCHEDULE. compliance7/compliance30 stay non-null as all-zero
+        compatibility placeholders for released clients; aware clients must ignore those percentages when
+        applicable=false. complianceDisplay is null.
       responses:
         "200":
           description: One adherence row per medication.
@@ -5849,11 +5847,11 @@ paths:
       tags:
         - Medications
       summary: Adherence read for a medication
-      description: Returns the 7- and 30-day adherence summaries, the per-day compliance grid for the history glyph track, and
-        the two-row display block. Pure computation — no writes. Day boundaries are resolved in the user's IANA
-        timezone, and the expected-dose denominator is cadence-aware (RRULE / rolling / one-shot / PRN / cyclic) and
-        clamped to the medication's `createdAt`. Read `compliance30` for the headline 30-day taken-vs-expected
-        percentage; build the per-day glyph track from `dailyCompliance` (draw a cell only where `due === true`).
+      description: Returns the cadence-aware adherence payload. A scheduled medication with no local schedule returns
+        applicable=false, reason NO_LOCAL_SCHEDULE, non-null all-zero compliance7/compliance30 compatibility
+        placeholders, a null display block, and an empty daily grid. Aware clients must not render the placeholder
+        percentages. Medications with a local schedule preserve the existing arithmetic, including windows in which no
+        dose is due.
       parameters:
         - in: path
           name: id
@@ -42937,21 +42935,35 @@ components:
       properties:
         medicationId:
           type: string
+        applicable:
+          type: boolean
+          description: Whether this medication has a local expected-dose grid and therefore a displayable adherence percentage.
+        notApplicableReason:
+          anyOf:
+            - type: string
+              const: NO_LOCAL_SCHEDULE
+            - type: "null"
         compliance7:
+          description: Seven-day adherence summary, or an all-zero compatibility placeholder when applicable is false.
           $ref: "#/components/schemas/ComplianceResult"
         compliance30:
+          description: Thirty-day adherence summary, or an all-zero compatibility placeholder when applicable is false.
           $ref: "#/components/schemas/ComplianceResult"
         complianceDisplay:
-          $ref: "#/components/schemas/ComplianceDisplay"
+          anyOf:
+            - $ref: "#/components/schemas/ComplianceDisplay"
+            - type: "null"
       required:
         - medicationId
+        - applicable
+        - notApplicableReason
         - compliance7
         - compliance30
         - complianceDisplay
       additionalProperties: false
-      description: "Compact per-medication adherence row for the batched card read: the 7-/30-day summaries plus the
-        cadence-scaled display block. The per-day `dailyCompliance` grid is NOT on this shape — read the per-medication
-        `/compliance` endpoint for the history glyph track."
+      description: Compact per-medication adherence row for the batched card read. Zero-local-schedule scheduled medications
+        remain present with applicable=false so clients render a settled not-applicable state instead of a loading
+        skeleton.
     ComplianceResult:
       type: object
       properties:
@@ -43181,9 +43193,23 @@ components:
     MedicationComplianceResponse:
       type: object
       properties:
+        applicable:
+          type: boolean
+          description: Whether a local adherence percentage applies to this medication.
+        notApplicableReason:
+          anyOf:
+            - type: string
+              const: NO_LOCAL_SCHEDULE
+            - type: "null"
+          description: Reason adherence is not applicable. NO_LOCAL_SCHEDULE means the medication has no HealthLog-owned
+            expected-dose grid.
         compliance7:
+          description: Seven-day adherence summary. When applicable is false, this remains a non-null all-zero compatibility
+            placeholder for released clients and must not be rendered as a percentage.
           $ref: "#/components/schemas/ComplianceResult"
         compliance30:
+          description: Thirty-day adherence summary. When applicable is false, this remains a non-null all-zero compatibility
+            placeholder for released clients and must not be rendered as a percentage.
           $ref: "#/components/schemas/ComplianceResult"
         dailyCompliance:
           type: object
@@ -43191,20 +43217,24 @@ components:
             type: string
           additionalProperties:
             $ref: "#/components/schemas/DailyComplianceEntry"
-          description: Flat per-day map keyed `YYYY-MM-DD` in the user timezone, one entry per day for up to 90 days back, clamped
-            to the medication's `createdAt` (so a recently-created med has fewer entries). No weekly/monthly collapse —
-            this is the raw daily grid.
+          description: Flat per-day map keyed YYYY-MM-DD in the user timezone. Empty when adherence is not applicable.
         complianceDisplay:
-          $ref: "#/components/schemas/ComplianceDisplay"
+          anyOf:
+            - $ref: "#/components/schemas/ComplianceDisplay"
+            - type: "null"
+          description: Cadence-scaled display block, or null when adherence is not applicable.
       required:
+        - applicable
+        - notApplicableReason
         - compliance7
         - compliance30
         - dailyCompliance
         - complianceDisplay
       additionalProperties: false
-      description: Adherence read for a single medication. `compliance30` is the authoritative 30-day taken-vs-expected
-        summary; `dailyCompliance` is the per-day grid for the history glyph track. The graded raw→week→month→year
-        series used elsewhere for AI prompts does NOT apply here — this response is never downsampled.
+      description: Adherence read for a single medication. A scheduled medication with no local schedule returns
+        applicable=false and NO_LOCAL_SCHEDULE rather than a vacuous 100 percent. Scheduled medications that have a
+        local schedule keep the existing cadence-aware arithmetic, including windows with no doses due. PRN behaviour is
+        unchanged.
     DailyComplianceEntry:
       type: object
       properties: