fix(api,codegen): ARCH-001-A — Phase 1 Orval codegen + 2 new CI guards (large diff)

Sprint 5 unified-master-audit closure. Pre-fix:

  - api/openapi.yaml: 7,788 LOC of hand-authored spec.
  - web/src/api/generated/: directory did NOT exist (the Phase-5
    scaffolding never had its first generation run).
  - scripts/ci-guards/openapi-codegen-drift.sh: skip-when-absent
    (line 33-39 — informational scaffold).
  - api/openapi.yaml info.version: '2.0.0', latest tag: v2.1.7
    (a 7-version drift between spec and ship).

Net effect: every new route required three coordinated edits (Go
handler, openapi.yaml, frontend client.ts), payload-level breaking
changes shipped unnoticed, and downstream API client integration
cost was permanent.

Phase 1 fix (the audit's literal scope):

  1. **Run Orval**, commit the generated tree. 316 files / ~1.8 MB
     under web/src/api/generated/, tags-split layout (one directory
     per OpenAPI tag), TanStack Query client mode. All output routes
     through web/src/api/mutator.ts which delegates to the existing
     fetchJSON in client.ts so auth/CSRF/401-event semantics stay
     in one place.

  2. **Fix two spec defects** the first orval run surfaced:
     - YAML duplicate-key bug at L77-89 — SCEP's description was
       misplaced under OIDC. Restored to its own tag entry.
     - Missing #/components/schemas/Error referenced by three
       operations. Aliased to the existing ErrorResponse schema.

  3. **Flip the codegen-drift guard from skip-when-absent to
     hard-gate.** A missing generated/ directory now fails the
     build with an actionable restore command. The existing
     regenerate-and-diff path stays as before.

  4. **New openapi-version-tag-parity CI guard.** Asserts
     openapi.yaml info.version equals the latest v* git tag. Falls
     back to api.github.com when the local clone is shallow.
     Bumped openapi.yaml info.version 2.0.0 → 2.1.7 in the same
     commit so the new guard greens out.

  5. **CI workflow** updated to fetch tags on the frontend job's
     checkout so the parity guard reads them locally (the GH API
     fallback still works but adds a network round-trip).

Verified locally:
  - openapi-codegen-drift.sh: clean (re-generation produces
    byte-identical tree to what's tracked).
  - openapi-version-tag-parity.sh: clean (2.1.7 == v2.1.7).
  - tsc --noEmit: exit 0 across the entire frontend (the
    generated tree's responseType field threaded through the
    mutator's CertctlFetchOptions cleanly).
  - Existing Vitest suite: 141/141 pass on the three sampled
    suites (AuthProvider + client + IssuerHierarchyPage).

Follow-on work (NOT in this commit):
  - Per-consumer migration: pages flip from client.ts imports to
    generated/ imports one at a time. Both styles share fetchJSON
    semantics, so the migration is incremental.
  - Server-side oapi-codegen handler stubs (Phase 2 from the
    audit's fix language) — separate sprint.

Closes ARCH-001-A.

scripts/ci-guards/openapi-codegen-drift.sh

@@ -31,11 +31,18 @@ set -e
 GENERATED_DIR="web/src/api/generated"
 
 if [ ! -d "$GENERATED_DIR" ]; then
-  echo "openapi-codegen-drift: skipped — $GENERATED_DIR does not exist yet."
-  echo "  This is expected during Phase 5 scaffolding. Once the operator"
-  echo "  runs 'cd web && npm install && npm run generate' for the first"
-  echo "  time, the directory lands and this guard activates."
-  exit 0
+  # ARCH-001-A closure (Sprint 5, 2026-05-16). Pre-fix the guard
+  # tolerated a missing generated/ tree as "Phase 5 scaffolding."
+  # Phase 5 scaffolded; ARCH-001-A landed the first generation and
+  # committed the tree. From this point on, a missing generated/
+  # directory means a contributor deleted it (intentionally or not)
+  # — the guard fails closed so CI catches the deletion.
+  echo "::error::openapi-codegen-drift: $GENERATED_DIR does not exist. ARCH-001-A committed the initial generated tree; a deletion has happened since."
+  echo "  Restore via:"
+  echo "      cd web && npm ci && npm run generate"
+  echo "  Then commit the result. Do NOT delete generated/ — the codegen-drift"
+  echo "  guard depends on its presence."
+  exit 1
 fi
 
 # Tolerate the case where orval isn't installed in the local