chore(openapi): resolve yaml emitter alias + register notifications/diagnostic

The yaml@2 emitter could not stringify .meta()-tagged sub-schemas
inside z.array(...) under sortMapEntries: true — alphabetic sorting
moved alias references ahead of their anchor definitions, tripping
verifyAliasOrder with "Unresolved alias: a1" during stringify. The
fix drops sortMapEntries from both generate-openapi and check-openapi
so anchors stay emitted before their aliases; output stability is
preserved by upstream determinism (Zod property declaration order +
single-object path table). The committed openapi.yaml is regenerated
in declaration order — large diff, functionally identical.

With the emitter stable, the v1.4.48 H-APNs-1 admin diagnostic
endpoint now appears in docs/api/openapi.yaml alongside its component
schemas: AdminDiagnosticDevice (APNs token masked to prefix +
suffix), AdminDiagnosticChannel (enabled + configPresent), and
AdminDiagnosticPushAttempt (reserved for the v1.4.48+ PushAttempt
table).

scripts/check-openapi.ts

@@ -16,8 +16,11 @@ const SPEC_PATH = resolve(__dirname, "..", "docs", "api", "openapi.yaml");
 
 function main(): void {
   const document = buildOpenApiDocument();
+  // Must match the options used by `scripts/generate-openapi.ts`.
+  // `sortMapEntries` stays off — see that file's header comment for the
+  // yaml@2 alias-ordering pitfall under sorted output.
   const generated = stringify(document, {
-    sortMapEntries: true,
+    sortMapEntries: false,
     lineWidth: 120,
   });
   const committed = readFileSync(SPEC_PATH, "utf8");

scripts/generate-openapi.ts

@@ -9,10 +9,20 @@
  * rest of the hand-maintained `docs/api/openapi.yaml` — once coverage is
  * complete, the gate flips to hard-fail in v1.4.24+.
  *
- * The output is stable across re-runs: `yaml@2` is configured with
- * `sortMapEntries: true` so map keys land in lexicographic order
- * regardless of Node version or the order in which schemas were
- * imported.
+ * The output is stable across re-runs because the upstream order is
+ * itself deterministic: Zod preserves schema property declaration
+ * order and the path table is a single object literal in
+ * `src/lib/openapi/routes.ts`. `yaml@2`'s `sortMapEntries` option is
+ * intentionally NOT set — when enabled, the emitter reorders keys
+ * alphabetically and can place an `*alias` reference before its
+ * `&anchor` definition, which triggers `verifyAliasOrder` and throws
+ * `Unresolved alias` during `stringify`. This started biting once
+ * `.meta()`-tagged sub-schemas were nested inside `z.array(...)` for
+ * the v1.4.48 admin diagnostic envelope: the array's element-schema
+ * anchor lives under `recentPushAttempts` (sorted to the bottom of
+ * the data object) while the alias from `notificationChannels`
+ * (sorted above it) refers to the same `$ref`. Leaving the source
+ * order intact keeps anchors emitted before their aliases.
  */
 import { writeFileSync } from "node:fs";
 import { resolve } from "node:path";
@@ -24,7 +34,7 @@ const SPEC_PATH = resolve(__dirname, "..", "docs", "api", "openapi.yaml");
 function main(): void {
   const document = buildOpenApiDocument();
   const yaml = stringify(document, {
-    sortMapEntries: true,
+    sortMapEntries: false,
     lineWidth: 120,
   });
   writeFileSync(SPEC_PATH, yaml, "utf8");

src/lib/openapi/routes.ts

@@ -422,6 +422,68 @@ const measurementResource = z
     description: "Server-shaped measurement row returned by GET endpoints.",
   });
 
+// v1.4.48 H-APNs-1 — admin diagnostic endpoint for the notification
+// subsystem. Mirrors the runtime types in
+// `src/app/api/admin/notifications/diagnostic/route.ts`: APNs tokens
+// are surfaced only as 8-char hex prefix + suffix (never the full
+// token), per-channel `enabled` + `configPresent` booleans, and a
+// `recentPushAttempts` array reserved for the v1.4.48+ follow-up that
+// adds the dedicated PushAttempt table (currently always `[]` so the
+// shape stays stable for iOS consumers).
+const adminDiagnosticDevice = z
+  .object({
+    id: z.string(),
+    platform: z.string(),
+    hasApnsToken: z.boolean(),
+    apnsTokenPrefix: z.string().nullable(),
+    apnsTokenSuffix: z.string().nullable(),
+    apnsEnvironment: z.string().nullable(),
+    lastSeenAt: z.iso.datetime({ offset: true }),
+  })
+  .meta({
+    id: "AdminDiagnosticDevice",
+    description:
+      "Per-device APNs registration snapshot. The APNs token is masked to its 8-char hex prefix + 8-char suffix so an operator can correlate with iOS-side logs without disclosing the delivery target.",
+  });
+
+const adminDiagnosticChannel = z
+  .object({
+    type: z.string(),
+    enabled: z.boolean(),
+    configPresent: z.boolean(),
+  })
+  .meta({
+    id: "AdminDiagnosticChannel",
+    description:
+      "Per-channel state. `configPresent` is true when the channel's encrypted-JSON config blob carries the field the corresponding sender will read (chatId+botToken for TELEGRAM, topic for NTFY); WEB_PUSH/APNS rely on sibling tables so the row's existence is the signal.",
+  });
+
+const adminDiagnosticPushAttempt = z
+  .object({
+    eventType: z.string(),
+    channel: z.string(),
+    result: z.string(),
+    reason: z.string().nullable(),
+    at: z.iso.datetime({ offset: true }),
+  })
+  .meta({
+    id: "AdminDiagnosticPushAttempt",
+    description:
+      "Single push delivery attempt. Reserved for the v1.4.48+ follow-up that adds the dedicated PushAttempt table — currently always returned as an empty array so the response shape stays stable for iOS consumers.",
+  });
+
+const adminDiagnosticData = z
+  .object({
+    devices: z.array(adminDiagnosticDevice),
+    notificationChannels: z.array(adminDiagnosticChannel),
+    recentPushAttempts: z.array(adminDiagnosticPushAttempt),
+  })
+  .meta({
+    id: "AdminDiagnosticData",
+    description:
+      "Admin notification diagnostic snapshot for the calling user — what the dispatcher would see when targeting this account. Surfaces device tokens (masked), channel state, and recent push attempts so an operator can debug an iOS / Web Push / Telegram / ntfy issue without DB shell access.",
+  });
+
 const insightsComprehensiveResponse = z
   .object({
     summary: z.string(),
@@ -923,6 +985,32 @@ export const openApiPaths: NonNullable<ZodOpenApiObject["paths"]> = {
       },
     },
   },
+  "/api/admin/notifications/diagnostic": {
+    get: {
+      tags: ["Admin"],
+      summary: "Admin notification diagnostic snapshot",
+      description:
+        "Admin-only. Returns what the dispatcher would see when targeting the calling admin's account: registered devices (APNs tokens masked to prefix + suffix), per-channel enabled + configPresent flags, and recent push attempts (currently always `[]` pending the v1.4.48+ PushAttempt table). Cookie auth only — never Bearer.",
+      responses: {
+        "200": {
+          description: "Diagnostic snapshot.",
+          content: {
+            "application/json": {
+              schema: dataEnvelope(
+                adminDiagnosticData,
+                "AdminDiagnosticResponse",
+              ),
+            },
+          },
+        },
+        "403": {
+          description: "Caller is not an admin.",
+          content: { "application/json": { schema: errorEnvelope } },
+        },
+        ...stdResponses,
+      },
+    },
+  },
   "/api/insights/comprehensive": {
     get: {
       tags: ["Insights"],