feat(profiles): promote descriptor/registry/auth machinery from mountainash-data — Phase 1

[discreteds]

Summary

Phase 1 of the profiles-promotion initiative: lifts the descriptor/registry/auth machinery from mountainash-data (commit 2ec5079 on feat/settings-registry) into mountainash-settings so other settings-heavy packages (utils-files, utils-secrets, acrds-core) can reuse the pattern rather than reinvent it.

This PR is purely additive library work — no consumers yet. Consumer migration is Phase 2 (plan already written at mountainash-data/docs/superpowers/plans/2026-04-16-profiles-migration-data.md, depends on this PR merging + a mountainash-settings release).

What shipped

Two new sub-packages under src/mountainash_settings/:

profiles/ (Pattern A + B mechanism):

• ProfileDescriptor — frozen dataclass (renamed from BackendDescriptor, generalised with open metadata: dict)
• ParameterSpec — with new template: str | None field enabling declarative Pattern B template wiring
• DescriptorProfile — pure-mechanism base class. Installs descriptor params as pydantic fields via __pydantic_init_subclass__, composes auth discriminated union, wires AfterValidator for ParameterSpec.validator, and resolves template fields in post_init. Strips domain-specific outputs (to_driver_kwargs, to_connection_string) — those stay in domain subclasses.
• Registry — per-domain registry class (Registry("databases"), Registry("storage")) with bound decorator(), get_descriptor(), get_settings_class(), test seams (_snapshot_for_tests/_reset_for_tests). Error messages include registry name.
• descriptor_invariants_for(registry) — pytest helper that produces a parametric test class pinning 10 descriptor invariants over every registered descriptor. Consumers drop it into their test suite and get free coverage for new registrations.

auth/ (cross-cutting auth):

• AuthSpec base + 10 subclasses (NoAuth, PasswordAuth, TokenAuth, JWTAuth, OAuth2Auth, ServiceAccountAuth, IAMAuth, AzureADAuth, KerberosAuth, CertificateAuth, WindowsAuth) — pydantic v2 discriminated union via kind literal
• AUTH_TO_DRIVER_KWARGS + auth_to_driver_kwargs() default dispatch — handles the common auth types; adapter-owned types (ServiceAccount, AzureAD, Kerberos, Certificate, Windows) raise KeyError so domain adapters must handle them.

Public re-exports from mountainash_settings.__init__ expose all profiles + auth symbols at package root.

Spec mapping

Implements docs/superpowers/specs/2026-04-16-profiles-promotion-design.md:

• Pattern A (descriptor registry) ✅ profiles/descriptor.py, profiles/profile.py, profiles/registry.py
• Pattern B (declarative templates) ✅ ParameterSpec.template + DescriptorProfile.post_init wiring
• All 11 AuthSpec subclasses promoted ✅ auth/
• Per-domain registries (not a global dict) ✅ Registry class
• Pure mechanism base — domain outputs stay in subclasses ✅ no to_driver_kwargs / to_connection_string on DescriptorProfile

Commits

1. ad50e8f feat(auth): add AuthSpec base class for discriminated unions
2. 19e30d6 feat(auth): port 11 AuthSpec subclasses from mountainash-data
3. 7c09066 feat(auth): add AUTH_TO_DRIVER_KWARGS default dispatch map
4. c9a0152 feat(profiles): add ProfileDescriptor + ParameterSpec with template support
5. 480e84d feat(profiles): add per-domain Registry class with bound decorator
6. 38b9e17 feat(profiles): add DescriptorProfile base (Pattern A mechanism) — also folds in Pattern B template wiring (planned as separate T7 commit but bundled for atomicity with the base class)
7. 66fc194 feat(profiles): add descriptor_invariants_for pytest helper
8. 37efeaa feat(settings): export profiles + auth from package root

Test plan

• hatch run test:test tests/unit/ — 73/73 passing
• Final code review approved
• Reviewer: verify domain-neutrality (no mountainash-data coupling)
• Reviewer: spot-check template wiring against mountainash-acrds-core's post_init usage as future consumer

What's next

After merge + release:

• Phase 2: migrate mountainash-data to consume the upstream primitives (plan ready at mountainash-data/docs/superpowers/plans/2026-04-16-profiles-migration-data.md, branches from feat/settings-registry)
• Phases 3-5 (utils-secrets, utils-files, acrds-core): drafted after Phase 2 lands

[sonarqubecloud]

Quality Gate failed

Failed conditions
C Security Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE

[codecov]

Codecov Report

❌ Patch coverage is 94.86607% with 23 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.67%. Comparing base (ce1466f) to head (37efeaa).
⚠️ Report is 87 commits behind head on develop.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/mountainash_settings/profiles/profile.py	80.00%	10 Missing and 7 partials ⚠️
src/mountainash_settings/profiles/registry.py	94.33%	2 Missing and 1 partial ⚠️
.../mountainash_settings/settings/app/app_settings.py	80.00%	1 Missing and 1 partial ⚠️
...sh_settings/settings/app/app_settings_templates.py	87.50%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop      #32      +/-   ##
===========================================
- Coverage    96.85%   96.67%   -0.19%     
===========================================
  Files           15       31      +16     
  Lines          573      841     +268     
  Branches        81      109      +28     
===========================================
+ Hits           555      813     +258     
- Misses          14       16       +2     
- Partials         4       12       +8     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.