feat(sdk): expose snapshot criteria relaxation as a resolve option (NVIDIA#2247)

Signed-off-by: Mark Chmarny <mark@chmarny.com>

Author: mchmarny

docs/contributor/cli.md

@@ -138,6 +138,7 @@ packages (`pkg/recipe`, `pkg/bundler`, `pkg/snapshotter`,
 | `ResolveRecipe(ctx, RecipeRequest)` | `recipe`, `query` (request can hold criteria, file path, or snapshot input) |
 | `ResolveRecipeFromCriteria(ctx, *Criteria)` | criteria-only fast path |
 | `ResolveRecipeFromSnapshot(ctx, *Criteria, *Snapshot)` | `validate`, `recipe --snapshot` |
+| `ResolveRecipeFromSnapshotWithOptions(ctx, *Criteria, *Snapshot, opts...)` | `recipe --snapshot`, `query --snapshot` — with `WithSnapshotCriteriaRelaxation(stated...)` for the derived-criteria retry |
 | `LoadRecipe(ctx, path, kubeconfig)` | `bundle`, `validate`, `diff` (read a previously emitted recipe file) |
 | `BundleComponents(ctx, *RecipeResult)` | `bundle` |
 | `LoadSnapshot(ctx, path, kubeconfig)` | `validate`, `query`, `diff` (read a previously captured snapshot; file, URL, or `cm://` ConfigMap) |
@@ -155,6 +156,14 @@ rendering, validator orchestration, OCI pushes — is a boundary
 violation. If the facade is missing the surface you need, add it to
 `pkg/client/v1` first.
 
+**What `--snapshot` still owns.** `buildRecipeFromCmdWithConfig` in
+`query.go` derives criteria from the snapshot fingerprint, layers config and
+flags on top, and records which of the five coverage dimensions were
+explicitly stated in a `touched` map. That map becomes the argument to
+`aicr.WithSnapshotCriteriaRelaxation` — the relax-and-retry itself lives in
+the facade (issue #2027). Only this layer can know a flag was set, so
+declaring the stated set is the CLI's job; acting on it is not.
+
 ## Output Writers
 
 User-facing output goes through `cmd.Root().Writer`, never

docs/contributor/recipe.md

@@ -499,21 +499,53 @@ non-`NotFound` error through `aicrerrors.PropagateOrWrap(..., ErrCodeInternal,
 ...)` before returning it — an evaluator that hasn't adopted `pkg/errors`
 still surfaces a coded error instead of an uncoded 500 at the server layer.
 
-**The engine stays strict; the CLI's snapshot path relaxes derived-only
+**The engine stays strict; the SDK's snapshot path can relax derived-only
 failures.** Everything above describes `pkg/recipe`'s behavior, which never
 relaxes the post-condition — a coverage failure there is always terminal.
-The CLI's `--snapshot` flow (`pkg/cli/query.go`) layers a caller-side
-retry on top: `service`, `accelerator`, and `os` can be derived from the
-snapshot fingerprint rather than stated by the user (`intent` and
-`platform` are always user-stated — the fingerprint never derives them).
-If a coverage error's uncovered dimensions are *all* fingerprint-derived
-(none came from `--config` or a CLI flag), the CLI clears those dimensions
-to unstated and retries resolution once, logging a warning per relaxed
-dimension; if any uncovered dimension was user-stated, the error still
-propagates unchanged. This lets an overlay tree that is deliberately
-agnostic to a dimension (e.g. Kind's OS-agnostic overlays) tolerate a
-snapshot that still reports a concrete value for it, without weakening the
-post-condition for anyone who asked for that dimension explicitly.
+The relax-and-retry lives one layer up, in `pkg/client/v1`
+(`relax.go`), behind an opt-in resolve option:
+
+```go
+result, err := client.ResolveRecipeFromSnapshotWithOptions(ctx, criteria, snap,
+    aicr.WithSnapshotCriteriaRelaxation(aicr.DimensionIntent))
+```
+
+`service`, `accelerator`, and `os` can be derived from the snapshot
+fingerprint rather than stated by the user (`intent` and `platform` are
+always user-stated — the fingerprint never derives them). The option's
+arguments name the dimensions the *caller* stated; everything else is
+treated as derived. If a coverage error's uncovered dimensions are *all*
+safely relaxable, the facade clears them to unstated and retries resolution
+once, logging a warning per relaxed dimension and reporting them in
+`pkg/client/v1.RecipeResult.RelaxedDimensions` — the facade's result type,
+not the resolver's `RecipeResult` documented under
+[Observable RecipeResult Surfaces](#observable-reciperesult-surfaces) below.
+
+**Not every uncovered dimension is relaxable**, and the distinction is why
+`verifyCriteriaCoverage` records `constraintExcluded` per entry. A dimension
+no overlay states at all is safe to clear — nothing in the recipe
+distinguishes the detected value. A dimension whose only provider was
+removed by constraint evaluation is not: clearing it converts a real
+incompatibility (the cluster failed that overlay's constraints) into a
+broader recipe that resolves at exit 0. The facade refuses in that case, and
+refuses again if clearing would leave no stated *coverage* dimension, which
+would match every overlay and resolve the generic fallback — the same
+fail-open as issue #1888. That check counts only the five coverage
+dimensions, not `Specificity()`, because `nodes` scores a specificity point
+while participating in no overlay match (#1781). A stated dimension is never
+relaxed either way.
+
+This lets an overlay tree that is deliberately agnostic to a dimension
+(e.g. Kind's OS-agnostic overlays) tolerate a snapshot that still reports a
+concrete value for it, without weakening the post-condition for anyone who
+asked for that dimension explicitly.
+
+Omitting the option keeps the strict behavior, so the coverage
+post-condition is unchanged for every caller that does not opt in — the
+REST recipe endpoint among them. `pkg/cli/query.go` passes the option and
+supplies the stated set from its `touched` map; declaring which dimensions
+a user typed is the one part of the policy that has to stay in the CLI,
+since only that layer knows a flag was set (issue #2027).
 
 ## Determinism
 

docs/integrator/go-library.md

@@ -398,12 +398,104 @@ For a per-resolution Slurm accounting mode, use
 `aicr.WithAccountingMode("customer-managed")`. The original criteria and
 snapshot method signatures remain unchanged for source compatibility.
 
+### Criteria relaxation on the snapshot path
+
+A snapshot resolve is strict by default — every criteria dimension you state
+must be honored by an applied overlay, or resolution fails with
+`ErrCodeInvalidRequest` and a `details.uncovered` payload.
+
+That is right for criteria a user typed, but wrong for criteria you *derived*
+from the snapshot fingerprint. An overlay tree can be deliberately agnostic to
+a dimension (Kind's overlays state no `os`) while the fingerprint still detects
+a concrete value on the node — nothing in the recipe distinguishes it, so
+failing there rejects a legitimate query.
+
+Pass `aicr.WithSnapshotCriteriaRelaxation` and name the dimensions **you
+received explicitly**. Anything else is treated as derived, and a coverage
+failure limited to derived dimensions is retried once with those cleared:
+
+```go
+import (
+    aicr "github.com/NVIDIA/aicr/pkg/client/v1"
+
+    // Deriving criteria from a snapshot has no facade-owned helper yet, so
+    // this step reaches past the stable surface — see the caveat below.
+    "github.com/NVIDIA/aicr/pkg/fingerprint" // Internal
+    "github.com/NVIDIA/aicr/pkg/recipe"      // Public (evolving)
+)
+
+criteria := fingerprint.FromMeasurements(snap.Unwrap().Measurements).
+    ToCriteria(client.CriteriaRegistry())
+criteria.Intent = recipe.CriteriaIntentTraining // the user asked for this one
+
+result, err := client.ResolveRecipeFromSnapshotWithOptions(
+    ctx, aicr.WrapCriteria(criteria), snap,
+    aicr.WithSnapshotCriteriaRelaxation(aicr.DimensionIntent))
+if err != nil {
+    log.Fatalf("resolve: %v", err)
+}
+for _, dim := range result.RelaxedDimensions {
+    log.Printf("resolved recipe is broader than requested: %s was relaxed", dim)
+}
+```
+
+> **The fingerprint step is an escape hatch, not stable API.** `pkg/fingerprint`
+> is [Internal](public-api.md#stability-tiers) and may change without notice;
+> `pkg/recipe` is Public (evolving) and may change in a minor bump. Only the
+> `aicr.*` calls above carry the facade's compatibility guarantee. Pin the AICR
+> version and re-audit this block on upgrade, or derive criteria yourself and
+> hand the facade an `*aicr.Criteria`. If you need this without the coupling,
+> say so on [#2016](https://github.com/NVIDIA/aicr/issues/2016) — a facade-owned
+> snapshot-to-criteria helper is the obvious gap it exposes.
+
+Relaxation is deliberately narrow. Three cases propagate the original coverage
+error rather than retrying:
+
+- **A dimension you named.** Relaxing a value the caller asked for would
+  silently resolve a different recipe than requested.
+- **A constraint-excluded dimension.** An overlay carrying it exists, but the
+  observed cluster failed its constraints — a Kubernetes version below the
+  overlay's floor, say. Relaxing there converts "your cluster does not meet
+  this overlay's requirements" into a broader recipe that resolves cleanly,
+  discarding the finding you most need.
+- **A relaxation that would leave no stated coverage dimension.** Such criteria
+  match every overlay and resolve the generic fallback recipe at exit 0 — the
+  fail-open the pre-resolution specificity guard exists to prevent (#1888).
+  Note this is not the same as "criteria is empty": a fingerprint-derived
+  `nodes` value survives the clear, but no overlay gates on `nodes`, so it
+  selects nothing.
+
+The distinction in the second case is *why* the dimension is uncovered: no
+overlay states it at all (safe to relax — nothing in the recipe distinguishes
+the value) versus an overlay states it but was constraint-excluded (not safe).
+The resolver reports which, per dimension, in the coverage error's
+`details.uncovered[].constraintExcluded`.
+
+Two more properties:
+
+- **Passing no dimensions is meaningful,** not a no-op: it means every
+  dimension was derived and all are relaxable. That is the common case for a
+  pure fingerprint query. Presence of the option is what enables the policy, so
+  omitting it entirely is how you keep strict behavior.
+- **It is snapshot-only.** On `ResolveRecipeFromCriteria` there is no
+  fingerprint, so the option is rejected with `ErrCodeInvalidRequest` rather
+  than ignored.
+
+Both attempts share the call's timeout budget, and relaxation happens at most
+once.
+
 The returned `*RecipeResult` carries:
 
 - `Name`, `Version`, `TranslatedAt` — stable identity
 - `Components` — `[]ComponentRef` (Name, Kind, Version, Source, Chart, Namespace)
 - `SelectedProfile` — selected name/value and declaration-wide `OwnedPaths`;
   nil for legacy recipes
+- `RelaxedDimensions` — criteria dimensions cleared by
+  `WithSnapshotCriteriaRelaxation`. Non-empty only when the first attempt failed
+  coverage on derived dimensions **and** the retry succeeded. Every other
+  outcome — option not passed, first attempt succeeded, relaxation refused, or
+  the retry itself failed — yields either an empty slice or `nil, error` with no
+  `RecipeResult` at all, so this field is never the way to detect a failure
 - `Resolved()` — the upstream `*pkg/recipe.RecipeResult` for callers that
   need constraints, deployment order, validation config, or metadata
   (e.g., evidence emission). Do not mutate; do not retain past the

docs/integrator/public-api.md

@@ -70,7 +70,7 @@ unrelated exports in their evolving packages remain free to change.
 | `aicr.Phase`, `aicr.PhaseDeployment` / `PhasePerformance` / `PhaseConformance` | string consts | **Facade-owned**. Values match `pkg/validator/v1` constants verbatim for byte-identical wire round-trip. |
 | `aicr.ReportSummary` | `pkg/validator/ctrf.Summary` | **Facade-owned struct** with the CTRF count fields. |
 | `aicr.ValidateOption` | `pkg/validator.Option` | **Facade-owned** functional-option type that captures into an internal struct and translates at call time. |
-| `aicr.RecipeResult` | `pkg/recipe.RecipeResult` | **Facade-owned struct** exposing `Name`, `Version`, `TranslatedAt`, `SelectedProfile` (the recorded ADR-015 selection, nil for unprofiled recipes), and `Components` (enabled/deployable components only — disabled refs remain visible via `Resolved().ComponentRefs`). Call `Resolved()` for the full upstream `*pkg/recipe.RecipeResult` (constraints, deployment order, validation config, metadata). The previous `aicr.Recipe` alias was removed in #1115; `ResolveRecipeFromCriteria` and `ResolveRecipeFromSnapshot` now return `*RecipeResult`. |
+| `aicr.RecipeResult` | `pkg/recipe.RecipeResult` | **Facade-owned struct** exposing `Name`, `Version`, `TranslatedAt`, `SelectedProfile` (the recorded ADR-015 selection, nil for unprofiled recipes), `Components` (enabled/deployable components only — disabled refs remain visible via `Resolved().ComponentRefs`), and `RelaxedDimensions` (criteria dimensions cleared by `WithSnapshotCriteriaRelaxation`; non-empty only when that option was passed, the first attempt failed the coverage post-condition on derived dimensions, **and** the retry succeeded — a refused or failed retry returns `nil, error` with no `RecipeResult`, so this field never signals failure). Call `Resolved()` for the full upstream `*pkg/recipe.RecipeResult` (constraints, deployment order, validation config, metadata). The previous `aicr.Recipe` alias was removed in #1115; `ResolveRecipeFromCriteria` and `ResolveRecipeFromSnapshot` now return `*RecipeResult`. |
 | `aicr.AllowLists` | `pkg/recipe.AllowLists` | **Facade-owned struct** with `[]string` fields (Accelerators / Services / Intents / OSTypes). Use `aicr.WrapAllowLists` to lift a `*pkg/recipe.AllowLists`. |
 | `aicr.Criteria` | `pkg/recipe.Criteria` | **Facade-owned struct** whose enum-typed fields (Service / Accelerator / Intent / OS / Platform) project to plain strings; Nodes stays an `int` per the facade's string/int contract. Use `aicr.WrapCriteria` to lift a `*pkg/recipe.Criteria`. |
 | `aicr.BundleConfig` | `pkg/bundler/config.Config` | Deliberate transparent alias. It keeps the facade compatible with `config.NewConfig` and its functional options instead of duplicating the bundler's configuration builder. |

pkg/cli/consts.go

@@ -43,20 +43,6 @@ const (
 // criteriaAny is the wildcard value for any criteria dimension.
 const criteriaAny = "any"
 
-// Coverage dimension names, matching pkg/recipe's coverageDimensions (see
-// pkg/recipe/coverage.go) name-for-name. Used to track which of the 5
-// dimensions subject to the criteria-coverage post-condition (issue #1542)
-// were explicitly user-stated (config or CLI flag) vs snapshot-derived, so a
-// coverage failure limited to snapshot-derived dimensions can be relaxed and
-// retried once (see relaxSnapshotDerivedCoverage in query.go).
-const (
-	coverageDimService     = "service"
-	coverageDimAccelerator = "accelerator"
-	coverageDimIntent      = "intent"
-	coverageDimOS          = "os"
-	coverageDimPlatform    = "platform"
-)
-
 // Keyless-signing / OCI-push flag names shared by `validate`, `bundle`,
 // and `evidence publish`. Extracted so the same literal is declared once
 // (goconst flags a string repeated ≥3 times across the package) and the