package solve

Import Path
	go.pact.im/x/plumb/internal/solve (on go.dev)

Dependency Relation
	imports 11 packages, and imported by 2 packages


Involved Source Files

	    checks.go
	    finalize.go
	    instance.go
	    joint.go
	    lift.go
	    order.go
	    revision.go
	
		Package solve is plumb's second phase: it turns the providers of one set into a
		fully resolved Plan, instantiating generics by demand, inferring the injector
		signature, ordering by dependency, and enforcing reachability and naming rules.
		It is a deterministic function of its providers; it reads no files and consults
		no clock.
		
		# Pipeline
		
		Set resolves one set by running run on a solver:
		
		  - classify: split providers into concrete / anchor / result-generic and
		    validate each result shape.
		  - seed: register the concrete providers and instantiate the anchors (lifting
		    their free parameters); registering an instance seeds demand from its inputs.
		  - solveDemands: the demand fixpoint. Each pass first works the worklist (a
		    demand a single result pins completely), then, if that made no progress, the
		    joint step (demands clustered across a template's results, lifting the
		    parameters no demand pins), until a whole pass adds nothing.
		  - checkUnusedTemplates / resolveFlexReceivers / finalize: reject a template no
		    consumer used, choose value-vs-pointer form for flexible struct receivers,
		    then resolve inputs, order instances by dependency, and build the Plan.
		
		# Pinning-revision restart
		
		A template whose pins arrive across different fixpoint rounds must be served by
		one instantiation at the union of those pins, not split into half-pinned calls.
		When a late pin would extend an existing instance's pinning, reviseOrSplit
		commits the union and the solve restarts: it signals with the errRestart
		sentinel, which rides the *diag.Error return channel up through
		instantiateTemplate → viableSingle/tryWorklist/tryJoint → solveDemands → run,
		compared by identity at each layer, until Set replays run on a fresh solver
		with the accumulated commitments in force. Resolution is therefore a pure
		function of (providers, commitments). A replay is the ordinary fixpoint, not a
		mutation of the aborted attempt, and maxRestarts bounds the loop. See
		revision.go.
		
		# Solver memo state
		
		Every memo table on solver is rebuilt fresh each attempt EXCEPT commitments and
		refusedUnions, which persist across restarts (a committed union must stay in
		force; a union already found non-viable must not re-trigger). The per-field roles
		are documented on the solver struct.


Package-Level Type Names (total 13, in which 9 are exported)


	/* sort exporteds by:  |  */
	
		ArgRef records how one provider input is satisfied.

		
			Coerce Coerce
			
				// the type whose local holds the value

			


	
		Coerce describes a value/pointer bridge applied to an argument.

		
			
		
			
		
			const CoerceNone
			const CoerceToPtr
			const CoerceToVal


	
		DestInfo describes the destination package as far as solve's collision checks
		and emit's qualification decisions need it. gen builds it; solve and emit
		(which imports solve) consume it.

		
			
				Imports maps each import qualifier used in the destination's existing files
				to the base name of a file using it. A generated function name (package
				block) cannot coexist with an import qualifier (file block) of the same
				name in any one file, so this feeds the set-name collision check.

			
				// top-level identifier → base filename declaring it

			
				// the destination's package name

			
				// the destination is one of the scanned packages

		
			
				ReservedNames returns the base set of identifiers a name generated for this
				destination must avoid: every predeclared universe name and every destination
				top-level identifier (so, in same-package mode, a generated name never shadows
				a builtin the body emits or a provider the body calls unqualified). The
				receiver may be nil. Callers that reserve further categories (lifted-parameter
				names, import aliases, set names) add them to the returned map.

		
			
		
			func Set(name string, provs []*discover.Provider, destPath, outputBase string, dest *DestInfo, ctxt *types.Context) (*Plan, *diag.Error)
			func go.pact.im/x/plumb/internal/emit.File(importPath, packageName string, pkgs []*discover.Package, plans []*Plan, dest *DestInfo) *emit.Result
			


	
		Input is one resolved injector parameter: its type and the source-name hint
		(the earliest consumer's parameter or field name, or "") used to name the
		generated parameter.

		
			Name string
			Type types.Type


	
		InputSlot is one consumed type, in call order.

		
			
				Name is the source parameter/field name, a hint for naming an injector
				input. For a struct-type provider it is the exported field name, which emit
				renders into the composite literal.

			


	
		Instance is a concrete (fully instantiated) provider ready for wiring: pure
		data describing what to call with what. emit turns it into Go source. For a
		non-generic provider there is exactly one; for a template there is one per
		pinning.

		
			
				// consumed types, in call order

			
				// the source provider this instantiates

			
				// classified results, in result order

			
				// type arguments, aligned with Prov.Tparams; nil if concrete

			
		
			
				InputTypes returns the instance's input types, in call order (for the report).

			
		
			
		
			


	
		Plan is the fully resolved wiring for one set, ready for emission.

		
			
				// some provider yields a cleanup, so the injector returns an aggregated cleanup func

			
				// each instance's inputs, one ArgRef per input in order

			
				// some cleanup can itself fail, so the aggregated cleanup returns an error

			
				// some provider returns an error, so the injector returns a trailing error

			
				// injector parameters, in signature order

			
				// free type parameters carried onto the generic injector header

			
				// the set name; the generated injector func is named this

			
				// instances to emit, in dependency (topological) order

			
				// value outputs, in signature order

			
				// source providers in the set, for the -v report; not len(Order), the instantiation count

			
		
			
				InputTypes returns the injector parameter types in signature order.

		
			func Set(name string, provs []*discover.Provider, destPath, outputBase string, dest *DestInfo, ctxt *types.Context) (*Plan, *diag.Error)
		
			func go.pact.im/x/plumb/internal/emit.File(importPath, packageName string, pkgs []*discover.Package, plans []*Plan, dest *DestInfo) *emit.Result
			


	
		ResultKind classifies one entry of a provider's result tuple.

		
			const ResultKindCleanup
			const ResultKindError
			const ResultKindValue


	
		ResultSlot is one classified entry of a provider's result tuple.

		
			
				// ResultKindCleanup: true if func() error

			Kind ResultKind
			
				// ResultKindValue: the value type; otherwise nil



	


Package-Level Functions (total 21, in which 1 is exported)


	
		Set resolves one set into a plan. destPath is the destination import path
		(what is referenced unqualified) and outputBase is the base name of the file
		being overwritten, used by the set-name collision check (empty for stdout).


	


Package-Level Variables (total 2, neither is exported)

	


Package-Level Constants (total 9, in which 6 are exported)


	
		Coercion directions for the value/pointer bridge.


	
		Coercion directions for the value/pointer bridge.


	
		Coercion directions for the value/pointer bridge.


	
		The result kinds for classifying entries of a provider’s result tuple.


	
		The result kinds for classifying entries of a provider’s result tuple.


	
		The result kinds for classifying entries of a provider’s result tuple.