Document prompt requirement inspection

requirements.go

@@ -10,43 +10,74 @@ import (
 // RequirementInspectionRequest selects a prompt and supplies caller context
 // for requirement discovery. It requires no artifact bindings or credentials.
 type RequirementInspectionRequest struct {
-	PromptID      string
+	// PromptID is the exact, case-sensitive configured prompt ID.
+	PromptID string
+	// PromptVersion selects an exact version. An empty value uses the prompt
+	// selection rule that requires exactly one configured version.
 	PromptVersion string
-	ProfileID     string
-	Vars          map[string]string
-	SessionID     string
+	// ProfileID selects the exact effective profile identity. If empty, the
+	// prompt's default profile is used; the profile need not be ready for
+	// execution.
+	ProfileID string
+	// Vars supplies string values for caller-variable lookups and simple
+	// conditions. Presence is determined by exact map key, including an empty
+	// value; values are not returned in the inspection.
+	Vars map[string]string
+	// SessionID, when nonblank after the normal session-ID normalization,
+	// bypasses the prompt's session template during discovery.
+	SessionID string
 }
 
 // RequirementKind describes how a selected prompt may depend on an input or
-// caller variable for the supplied context.
+// caller variable for the supplied context. It is independent of whether a
+// caller-variable value is present.
 type RequirementKind string
 
 const (
-	// RequirementRequired identifies a declaration or definite access.
+	// RequirementRequired identifies an input declared required or a dependency
+	// reached by a recognized definite access.
 	RequirementRequired RequirementKind = "required"
-	// RequirementConditional identifies a dependency whose reachability is
-	// unresolved for the supplied context.
+	// RequirementConditional identifies a dependency whose reachability or
+	// identity remains unresolved for the supplied context.
 	RequirementConditional RequirementKind = "conditional"
 	// RequirementOptional identifies a dependency known not to be required,
-	// including a reference used only on a known skipped path.
+	// including a nonrequired declaration, optional lookup, or reference used
+	// only on a known skipped path.
 	RequirementOptional RequirementKind = "optional"
 )
 
 // InputRequirement describes a declared or template-referenced prompt input.
 type InputRequirement struct {
-	Name        string
-	Kind        RequirementKind
-	Declared    bool
+	// Name is the exact input identifier.
+	Name string
+	// Kind is the strongest classification established for this name.
+	Kind RequirementKind
+	// Declared reports whether the name appears in the effective input
+	// declarations; helper-only references have Declared false.
+	Declared bool
+	// ContentType preserves effective metadata presence: nil means absent or
+	// null, while a non-nil pointer may refer to an empty string.
 	ContentType *string
+	// Description preserves effective metadata presence independently of
+	// Explanation, including an explicitly empty string.
 	Description *string
+	// Explanation is safe human-readable context, such as why a reference is
+	// optional because it occurs only on a known skipped path. It is not a
+	// machine-readable contract.
 	Explanation string
 }
 
 // VariableRequirement describes a caller-map key referenced by a prompt.
 type VariableRequirement struct {
-	Name        string
-	Kind        RequirementKind
-	Supplied    bool
+	// Name is the exact caller-map key, not a template-local name.
+	Name string
+	// Kind is the strongest classification established for this key.
+	Kind RequirementKind
+	// Supplied reports exact-key presence in the request Vars map. An empty
+	// string is supplied; the value itself is not returned.
+	Supplied bool
+	// Explanation is safe human-readable context and is not a machine-readable
+	// contract.
 	Explanation string
 }
 
@@ -54,31 +85,67 @@ type VariableRequirement struct {
 type RequirementIssueCode string
 
 const (
-	RequirementIssueMissingVariable      RequirementIssueCode = "missing_variable"
-	RequirementIssueInputContent         RequirementIssueCode = "input_content"
-	RequirementIssueDynamicInputName     RequirementIssueCode = "dynamic_input_name"
+	// RequirementIssueMissingVariable means an absent caller value prevents
+	// resolving a dependency decision or input name.
+	RequirementIssueMissingVariable RequirementIssueCode = "missing_variable"
+	// RequirementIssueInputContent means unavailable input content affects
+	// dependency discovery.
+	RequirementIssueInputContent RequirementIssueCode = "input_content"
+	// RequirementIssueDynamicInputName means a referenced input name cannot be
+	// determined for the supplied context.
+	RequirementIssueDynamicInputName RequirementIssueCode = "dynamic_input_name"
+	// RequirementIssueUnsupportedConstruct means a dependency-relevant
+	// expression or scope is outside the supported discovery analysis.
 	RequirementIssueUnsupportedConstruct RequirementIssueCode = "unsupported_construct"
 )
 
 // RequirementIssue describes one discovery limitation using safe summary
 // text. Descriptions are not intended as machine-readable details.
 type RequirementIssue struct {
-	Code         RequirementIssueCode
-	InputName    string
+	// Code is the machine-readable limitation category.
+	Code RequirementIssueCode
+	// InputName identifies an affected input when one is known; empty means no
+	// particular input was identified.
+	InputName string
+	// VariableName identifies an affected caller key when one is known; empty
+	// means no particular key was identified.
 	VariableName string
-	Description  string
+	// Description is a safe human-readable summary, not a string to parse.
+	Description string
 }
 
 // RequirementInspection contains discovered dependencies for one selected
-// prompt context. Complete describes discovery, not renderability or readiness.
+// prompt context. Input and variable entries are sorted by exact name. Issues
+// are deduplicated by code and associated names, then sorted by that tuple.
+// Their descriptions and entry explanations are safe summaries, not
+// machine-readable details.
+//
+// Complete describes the supported analysis's discovery coverage, not whether
+// requirements are supplied, templates will render, artifacts or schemas are
+// valid, or execution is ready. A complete result can still contain required
+// inputs or missing required variables. Valid templates using dependency-
+// relevant constructs outside the deliberately small recognition scope may
+// produce useful partial inventories with Complete false; this is not a
+// template-definition error or an authoring prohibition.
 type RequirementInspection struct {
-	PromptID      string
+	// PromptID is the selected exact prompt ID.
+	PromptID string
+	// PromptVersion is the selected exact prompt version.
 	PromptVersion string
-	ProfileID     string
-	Inputs        []InputRequirement
-	Variables     []VariableRequirement
-	Complete      bool
-	Issues        []RequirementIssue
+	// ProfileID is the selected profile identity; it does not indicate
+	// execution readiness.
+	ProfileID string
+	// Inputs contains declared inputs and recognizable template references,
+	// including entries known to be optional.
+	Inputs []InputRequirement
+	// Variables contains recognizable caller-map keys, including keys used
+	// only on known skipped paths.
+	Variables []VariableRequirement
+	// Complete reports discovery coverage, not requirement satisfaction or
+	// execution readiness.
+	Complete bool
+	// Issues contains deduplicated, structured discovery limitations.
+	Issues []RequirementIssue
 }
 
 // InspectRequirements discovers inputs and caller variables for one selected
@@ -89,6 +156,14 @@ type RequirementInspection struct {
 // captured session template. Vars are copied before analysis, and returned
 // slices and metadata pointers belong to the caller.
 //
+// Discovery recognizes literal input names, direct caller-map keys, literal-
+// key root-map lookups, simple caller-derived input names, and if/with
+// conditions based on direct values, literals, negation, or two-string
+// equality/inequality. It classifies recognizable references on known skipped
+// paths as optional. Other dependency-relevant expressions or scopes may leave
+// a useful partial result with Complete false. The returned inventories do
+// not reject otherwise valid templates or prohibit their use.
+//
 // This method does not perform artifact, schema, credential, rendering,
 // validation, capacity, observation, provider, or execution work. Complete
 // describes dependency discovery, not whether every dependency is supplied or
@@ -98,7 +173,9 @@ type RequirementInspection struct {
 // selection match ErrInvalidRequest; an absent profile selection also matches
 // ErrProfileRequired. Missing prompt/profile IDs match ErrPromptNotFound or
 // ErrProfileNotFound. Other selection/snapshot failures match ErrPromptLoad or
-// ErrProfileLoad. A nil Engine matches ErrInvalidConfig.
+// ErrProfileLoad. When cancellation prevents lookup or analysis, no inspection
+// is returned and the context error remains discoverable with errors.Is. A nil
+// Engine matches ErrInvalidConfig.
 func (e *Engine) InspectRequirements(
 	ctx context.Context,
 	req RequirementInspectionRequest,