feat(s41): offline Azure/Foundry preflight CLI (env-contract + placeholder refusal)

src/portfolio_optimiser/preflight.py

@@ -0,0 +1,123 @@
+"""S4.1 — Azure/Foundry offline preflight (D2/D6): validate everything checkable WITHOUT a model
+call before the operator pays for one.
+
+Runs ``python -m portfolio_optimiser.preflight --profile azure``. It checks, purely offline
+(config/string/env only — NO client construction, NO network, NO auto-login): (1) the endpoint env
+``PORTFOLIO_FOUNDRY_PROJECT_ENDPOINT`` is set and shaped like a Foundry project endpoint
+(``https://`` + host ``*.services.ai.azure.com``); (2) the effective model-map (honoring
+``PORTFOLIO_MODEL_MAP``) is structurally valid (``ModelMapContract``); (3) no azure deployment is
+still a ``REPLACE-WITH-*`` placeholder (via ``resolve_model`` — the SAME seam the run path uses, so
+preflight and run never validate different maps).
+
+**Necessary-but-not-sufficient (honesty):** a green preflight rules out the offline-detectable
+misconfig class; it does NOT prove the paid live call will succeed. RBAC (403), token/tenant/consent
+(401), a well-formed-but-nonexistent deployment (404), and api-version skew surface only at the live
+call. The verified auth recipe (``az login`` / ``AzureCliCredential``; the ``Foundry User`` RBAC
+role; endpoint form) lives in ``docs/2026-07-15-foundry-auth-recipe.md`` — deliberately NOT in this
+docstring, so the no-network/no-auto-login AST guard in ``tests/test_preflight_loadbearing.py`` stays
+clean. Load-bearing: that guard + the refusal/placeholder teeth.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass
+
+from pydantic import ValidationError
+
+from portfolio_optimiser.backends import Profile, _load_effective_map, resolve_model
+from portfolio_optimiser.contracts import ModelMapContract
+
+_ENDPOINT_ENV = "PORTFOLIO_FOUNDRY_PROJECT_ENDPOINT"
+_FOUNDRY_HOST_SUFFIX = ".services.ai.azure.com"
+_ROLES = ("default", "proposer", "checker")
+# Exact operator-facing disclaimer marker (Norwegian, per docs-language convention). The docs note
+# carries the English "necessary-but-not-sufficient" marker; each guard pins its own document.
+_DISCLAIMER = "ikke tilstrekkelig: RBAC/token/tenant/deployment sjekkes først ved live-kall"
+
+
+@dataclass(frozen=True)
+class PreflightOK:
+    """Every offline-checkable Azure/Foundry precondition holds. Distinct type from a refusal."""
+
+    profile: Profile
+
+
+@dataclass(frozen=True)
+class PreflightRefusal:
+    """A blocked precondition, carrying the actionable reason. Cannot be consumed as a
+    ``PreflightOK`` (mirror ``validator.Rejection``)."""
+
+    reason: str
+
+
+def _endpoint_error() -> str | None:
+    """Return an actionable reason if the endpoint env is missing/misshapen, else ``None``. Pure
+    string work — no ``urllib`` (both the NFR and the offline grep-guard forbid it)."""
+    endpoint = os.environ.get(_ENDPOINT_ENV)
+    if not endpoint:
+        return f"{_ENDPOINT_ENV} er ikke satt (påkrevd for azure-profilen)"
+    if not endpoint.startswith("https://"):
+        return f"{_ENDPOINT_ENV} må være en https://-URL, fikk: {endpoint!r}"
+    # Host = between the scheme and the first '/', minus any port; lowercased. Do NOT require the
+    # '/api/projects/<project>' path (official samples omit it — research §3); accept the bare host.
+    host = endpoint[len("https://") :].split("/", 1)[0].split(":", 1)[0].lower()
+    if not host.endswith(_FOUNDRY_HOST_SUFFIX):
+        return (
+            f"{_ENDPOINT_ENV} host {host!r} er ikke en Foundry-project-endpoint "
+            f"(*{_FOUNDRY_HOST_SUFFIX}); *.openai.azure.com / *.cognitiveservices.azure.com er feil "
+            "klient-flate (bruk OpenAIChatClient, ikke FoundryChatClient)"
+        )
+    return None
+
+
+def check_azure_preflight(profile: Profile | str = Profile.AZURE) -> PreflightOK | PreflightRefusal:
+    """Offline Azure/Foundry preflight: endpoint env-contract + model-map consistency + placeholder
+    refusal. Pure config/string/env — NO client construction, NO network. Every config error becomes
+    a structured ``PreflightRefusal`` (never a traceback), so a bad ``PORTFOLIO_MODEL_MAP`` refuses
+    cleanly."""
+    try:
+        prof = Profile(profile)
+        if prof is not Profile.AZURE:
+            return PreflightRefusal(
+                f"preflight --profile {prof.value}: kun 'azure' støttes "
+                "(S4.1 offline Foundry-preflight; local-profilen trenger ingen preflight)"
+            )
+        endpoint_err = _endpoint_error()
+        if endpoint_err:
+            return PreflightRefusal(endpoint_err)
+        # Model-map consistency — the SAME effective map resolve_model uses (no divergence).
+        ModelMapContract(**_load_effective_map())
+        # Placeholder refusal: resolving each role raises ValueError on a REPLACE-WITH-* id.
+        for role in _ROLES:
+            resolve_model(prof, role)
+    except (FileNotFoundError, ValidationError, ValueError) as exc:
+        return PreflightRefusal(str(exc))
+    return PreflightOK(prof)
+
+
+def main(argv: list[str] | None = None) -> int:
+    """CLI entry: ``python -m portfolio_optimiser.preflight --profile azure`` — offline Azure/Foundry
+    config preflight. rc 0 = OK (with the necessary-but-not-sufficient disclaimer to stdout), rc 1 =
+    structured refusal to stderr. No network, no auto-login."""
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        prog="portfolio_optimiser.preflight",
+        description="Offline Azure/Foundry-preflight (S4.1) — validerer endpoint, model-map og "
+        "deployment-navn UTEN modellkall/nettverk før operatøren betaler for en live-kjøring.",
+    )
+    parser.add_argument("--profile", default="azure", help="backend-profil (azure)")
+    args = parser.parse_args(argv)
+
+    result = check_azure_preflight(args.profile)
+    if isinstance(result, PreflightRefusal):
+        print(f"preflight: {result.reason}", file=sys.stderr)
+        return 1
+    print(f"preflight OK ({result.profile.value}) — men {_DISCLAIMER}")
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover - console entry
+    raise SystemExit(main())