Resolve configuration value precedence

This capability compares values supplied by an application default, a configuration file, an environment variable, and a command-line flag, then applies the precedence order you define. It returns both the effective value and the source that supplied it, making the decision easy to inspect, test, and document. Omitted sources remain distinct from deliberately supplied empty strings, so common override behavior is represented accurately.

Describe supplied values without losing absence semantics

Put source values in the values object using the canonical names default, config_file, environment_variable, and cli_flag. A property that is not present means that source did not provide the setting. This distinction matters because an empty string may be an intentional override: for example, a CLI option might deliberately clear a prefix that exists in a file. The resolver therefore treats a present empty string as a real value and does not silently skip it. Every supplied value must be a string, which mirrors the raw form commonly read from environment variables and command-line parsers and avoids surprising coercion between zero, false, and textual values. You may also provide a setting name. It does not change selection; it is echoed in the result so logs and test fixtures remain understandable when several settings are evaluated. Unknown source names are rejected rather than ignored, helping catch spelling errors that would otherwise look like missing configuration. If none of the four properties is present, resolution fails, including when the default property is absent. That explicit error prevents a missing setting from quietly becoming an invented value.

Define and apply precedence explicitly

The precedence array lists all four sources from highest priority to lowest priority. A conventional order is CLI flag, environment variable, configuration file, then default, but the resolver does not assume that convention because applications and deployment systems differ. It examines the ordered names and selects the first source whose property exists in the values object. The returned source explains why that value won, while the returned precedence array preserves the policy used for the decision. Requiring each supported source exactly once makes the policy complete and auditable. A duplicated name, an unknown name, a missing source, or an extra entry produces an input error instead of an ambiguous partial result. This is useful when precedence rules come from documentation, framework migration work, or a test matrix: the submitted order is the entire rule, not a hint combined with hidden platform defaults. Selection is deterministic and performs no type conversion, interpolation, file access, environment lookup, or command parsing. The capability evaluates only the values you submit, so the same input always produces the same output in a browser, CI job, or API call. That makes it suitable as a small reference oracle for testing larger configuration loaders.

Use the result in tests, diagnostics, and documentation

The response contains effective_value, source, and the precedence order that was evaluated. If you supplied a setting name, the response includes it as well. This compact structure works well in unit-test fixtures: assemble the raw values observed by your loader, submit the intended policy, and assert that both the winning value and its origin match expectations. It also helps with operational diagnostics. A support tool can show that a timeout came from an environment variable rather than a checked-in file without attempting to reproduce the entire application startup process. Documentation teams can turn examples of layered settings into executable demonstrations, especially when a framework uses an unconventional order. The resolver intentionally does not read the host process environment, open configuration files, or interpret CLI syntax. Callers remain responsible for collecting those inputs and for deciding whether secrets should be submitted; sensitive credentials should generally be represented with harmless placeholders when only precedence behavior is being tested. Each request resolves one setting and costs $0.002 through the API, while the tier-A browser path uses the same pure solving logic. Because the algorithm has no network, randomness, clock, or mutable state, repeated requests with identical JSON are stable and straightforward to cache or compare.