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");