Config

Remarks

This is an internal provider seam, not a consumer-facing configuration API. DefaultConfigManager uses it after direct provider resolution so hierarchical override sources can update only the supplied child values instead of replacing an entire options object.

Remarks

Providers that store text, such as local secret stores and remote secret managers, should use this helper so scalar, enum, Guid, and JSON object conversion stay consistent. The helper intentionally returns a boolean instead of exposing raw parse exception messages because provider diagnostics must not leak secret payloads.

Remarks

Reporters inspect known configuration keys, provider provenance, validation diagnostics, and redacted display values. Implementations should return a report with diagnostics for recoverable provider and wrapper failures rather than throwing after argument validation succeeds.

Remarks

This internal reporter treats IEnvironmentConfigProvider as the override provider, excludes manager/internal provider registrations from the displayed provider list, and favors wrapper-discovered audit entries when duplicate keys are registered manually. Manual audit option assignments override wrapper-discovered options per property so callers can intentionally reset a wrapper default for one key. Provider failures are converted into diagnostics so one broken provider does not prevent operators from seeing the rest of the report.

Remarks

The reporter uses this internal contract to keep value state, provenance, and diagnostics together while it walks providers in precedence order. Missing values should be represented with Missing(string).

Remarks

Implementations should avoid throwing for expected parse or source errors and return diagnostics instead. The reporter catches unexpected exceptions and converts them into provider diagnostics.

Remarks

This contract is internal in v1 so provider-specific enumeration semantics can settle before AppSurface exposes a public extension API. Implementations should enumerate the provider's effective view for the requested environment and return diagnostics instead of throwing for expected source problems.

Remarks

This helper keeps the formatted value, redaction flag, and ConfigAuditDiscoveredValueDisplayState synchronized before they enter ConfigAuditDiscoveredKey. DisplayValue may be null for omitted states, so callers must branch on DisplayState instead of inferring intent from nullability. Pitfall: a null display value is not an error, and renderers or logs must preserve the redaction and display-state decision ordering rather than recomputing value visibility.

Remarks

The environment provider uses this to explain mixed provenance for object values without mutating the provider instance that supplied the base value.

Remarks

Implementations receive the raw provider value and should return structured diagnostics rather than throwing for validation failures. Unexpected exceptions are caught by the wrapper implementations.

Remarks

The renderer only renders sanitized diff evidence. By default it summarizes file paths to reduce support-bundle exposure; set ConfigAuditDiffOptions.SourceDetail to ConfigAuditDiffSourceDetail.Full before comparing when operators need the full source details already present in the audit reports.

Remarks

Matching is fragment based and case-insensitive across keys, config paths, applied paths, and environment variable names. Sensitive values are replaced with a fixed placeholder before rendering. Non-sensitive complex values, including collections, may produce a null display value so callers can rely on source records and supported child entries instead of an unsafe dump. Formatting failures are swallowed intentionally to keep audit generation best-effort.

Remarks

Options affect evidence wording, renderer detail, and whether unchanged items are retained. They do not cause provider resolution, host startup, or command execution.

Remarks

The report contains only evidence already present in the input audit reports plus comparison diagnostics. It is safe to serialize as a support artifact subject to the same sensitivity rules as ConfigAuditReport: source paths, provider names, environment names, and correlation identifiers may still be support-sensitive.

Remarks

Diagnostics explain uncertainty, duplicate evidence, default/manual enum values, and evidence-mode warnings. They are intended for rendering and support triage, not for leaking raw provider exception messages.

Remarks

Items keep baseline and target evidence separate so renderers can explain uncertainty without implying raw equality. Empty source and diagnostic lists mean the original report did not provide that evidence for the item.

Remarks

Failures intentionally omit raw exception messages because provider, parser, and renderer exceptions can contain attempted values, file paths, or environment-specific details. Command wrappers should display these fields instead of printing the original exception.

Remarks

A successful result means the diff report was produced and written. It does not mean the environments are equivalent: changed, added, removed, uncomparable, and warning items remain part of a successful inspection run. Command wrappers should use ExitCode only for process success or failure of the workflow itself.

Remarks

Apply this attribute to a concrete Config{T} or ConfigStruct{T} wrapper when startup should fail if provider/default resolution leaves the wrapper without a value. A Config{T}.DefaultValue or ConfigStruct{T}.DefaultValue satisfies the requirement because the requirement is resolved presence, not provider-source auditing.

This attribute is intentionally separate from scalar value validation attributes such as ConfigValueNotEmptyAttribute. Use ConfigKeyRequiredAttribute when absence should fail, and use value validation when a resolved value must satisfy shape or range rules.

Remarks

This public shape is intentionally smaller than Config's internal audit resolution. It gives external providers a safe way to report value state, source records, and diagnostics without coupling packages to internal traversal or patching details. Value is still redacted by the audit reporter before display.

Remarks

IConfigProvider.GetValue{T} uses null for both missing values and failed lookups. Providers that own fail-closed sources, such as local secret stores, implement this interface so IConfigManager can distinguish true absence from terminal conditions like locked stores, unsupported platforms, invalid identities, or posture-disabled environments.

When to implement: implement this interface when a provider wraps a fail-closed source that can distinguish "not found" from access denied, locked, unavailable, unsupported platform, invalid identity, or other claimed-key states that must not be masked by file defaults. Prefer a plain IConfigProvider when missing and unavailable values should both fall through.

Usage pattern: IConfigProvider.GetValue{T} returns null for the lookup, then IConfigManager calls TryGetTerminalDiagnostic with the same environment and key. Return true only when that last lookup produced a terminal diagnostic.

Pitfall: cache diagnostics by environment and key for the most recent lookup because TryGetTerminalDiagnostic is called after IConfigProvider.GetValue{T} has already returned. A common mistake is treating every null as terminal; only claimed-key failures should stop resolution, while true missing values must return false.

Remarks

Scalar validation runs after provider/default resolution and only when the resolved value is non-null. These attributes validate the value itself; they do not make a missing configuration key required. Use a default value or an application startup presence check when absence should fail.

Validation is intentionally strict about value types. Built-in scalar attributes return validation failures for unsupported runtime types instead of converting values. Use an options object with DataAnnotations when validation spans multiple members, needs nested object traversal, or should model required presence separately from value shape.

The validation context object is the concrete config wrapper and does not provide application dependency injection services. Override Config{T}.ValidateValue or ConfigStruct{T}.ValidateValue for scalar rules that cannot be expressed as reusable attributes.

Remarks

A null value is treated as successful validation so optional or missing scalar values remain optional. Non-null strings must contain non-whitespace characters, and non-null Guid values must not be Guid.Empty.

Runtime type matching is strict: only string and Guid are supported. Applying this attribute to a different scalar value type returns a validation failure rather than attempting a conversion. Use an options object with member-level DataAnnotations when required presence, cross-field rules, or richer object validation is part of the contract.

Remarks

A null value is treated as successful validation so optional or missing scalar values remain optional. Non-null values are compared against the inclusive minimum and maximum supplied to the constructor.

Range validation accepts resolved int and double values. Integer bounds are widened when validating a double value, so attribute arguments such as [ConfigValueRange(1, 5)] work for ConfigStruct<double> wrappers. Unsupported runtime types return validation failures instead of being converted. Use an options object when validation needs multiple numeric fields, required presence, or object-level DataAnnotations.

Remarks

A null value is treated as successful validation so optional or missing scalar values remain optional. Non-null strings must have a length greater than or equal to Length.

Runtime type matching is strict: only string values are supported. Applying this attribute to another scalar value type returns a validation failure rather than converting the value. Use an options object with DataAnnotations when string length is only one part of a larger model contract or when required presence should be represented separately.

Remarks

These options are only used by entries whose ConfigAuditEntryOptions.DictionaryKeyCorrelationMode is ConfigAuditDictionaryKeyCorrelationMode.ScopedHmac. The secret key is never copied into reports. Reports may include KeyId, ApplicationScope, and derived correlation identifiers, which are still sensitive support metadata because they reveal key equality, churn, and absence across reports.

Remarks

This internal helper is used only when at least one audit entry requests ConfigAuditDictionaryKeyCorrelationMode.ScopedHmac. A context is available only when the configured secret is at least MinimumSecretBytes UTF-8 bytes, the key id is display-safe, and the application scope is present. Unavailable contexts preserve report generation and later emit config-audit-key-correlation-unavailable diagnostics at requested dictionary paths.

Remarks

The context is internal because callers should configure correlation through ConfigAuditDictionaryKeyCorrelationOptions and per-entry ConfigAuditEntryOptions.DictionaryKeyCorrelationMode. Available contexts derive opaque ids for raw dictionary keys; unavailable contexts never throw during traversal and instead let consumers emit a warning diagnostic.

Remarks

Failures intentionally omit raw exception messages because provider and reporter exceptions can contain attempted configuration values, file paths, or other support-sensitive details. Command wrappers should display these fields instead of printing the original exception.

Remarks

Enumeration should describe the provider's effective view for the requested environment. Providers that cannot enumerate safely, such as remote secret stores where inventory access is broader than value access, should not implement this interface.

Remarks

A successful result means the audit report was generated and written. It does not mean every audited entry resolved successfully: entries with ConfigAuditEntryState.Missing or ConfigAuditEntryState.Invalid are still part of a successful inspection run. Command wrappers should treat ExitCode as the process result for this v1 inspect-only surface.

Remarks

The exception message is built from Diagnostic and intentionally omits raw provider exception messages and configuration values. Catch this exception at command or host boundaries when the app should render provider posture guidance instead of falling through to lower-priority configuration sources.

Remarks

AppSurfaceConfigModule registers core configuration services immediately, including audit reporting, diagnostics, sanitized diff comparison, diff rendering, and command-runner helpers, then defers typed IConfig discovery through StartupContext.CustomRegistrations so all module dependencies are known first. The deferred scan inspects dependency module assemblies, the entry assembly, and the root module assembly. Pitfall: config dependencies should be registered before the custom registration callback runs; otherwise discovered config objects may activate before their supporting services are available.

Remarks

IEnvironmentConfigProvider composes IConfigProvider with IEnvironmentProvider for implementations that need to resolve configuration and the active environment from the same source. Prefer the composite when environment-aware config lookup should be atomic or co-located in one implementation; use the separate interfaces when configuration and environment ownership differ. Implementations should be safe for repeated reads, define any caching or refresh behavior, and avoid assuming that all configuration is environment-exclusive. Disposal and lifetime follow the concrete provider registration.

Remarks

The differ is intentionally pure: it does not start hosts, read files, call providers, or depend on any command framework. Reports should already be sanitized by IConfigAuditReporter or by a trusted captured-report workflow. Redacted and omitted values remain uncertain; the diff exposes that uncertainty through ConfigAuditDiffItem.ValueEvidence instead of implying raw equality.

Remarks

The map is advisory and intentionally narrower than JSON parsing: it records object property-name token locations, suppresses ambiguous case-insensitive paths, and omits array descendants so callers never receive a coordinate that is more specific than the file provider's merge/origin model.

Remarks

Implement this interface when a provider can resolve a known audit key with richer provenance or diagnostics than the generic IConfigProvider.GetValue{T} fallback can provide, or when calling the generic path would lose provider-specific source records. Providers with ordinary scalar values and no custom diagnostics should rely on the generic audit path instead. Return display-safe diagnostics only: messages, source records, and metadata must not include raw configuration values, secret payloads, credentials, or raw provider exception messages. Expected provider failures, such as missing remote secrets or access-denied responses, should be returned as failed ConfigProviderAuditResolution instances so the reporter can preserve provider ownership. Throw only for unexpected programming or infrastructure failures that cannot be represented safely. The reporter invokes providers in priority order while building a point-in-time audit report, so implementations should avoid writes and other order-sensitive side effects.

Remarks

Implementations should return a stable absolute path that exists and is readable by the process. The default implementation returns AppContext.BaseDirectory. Callers should validate Directory before opening files and report a configuration error when it is null, empty, missing, unreadable, or unsuitable for the current platform. Paths should not depend on the current working directory; symlinks and platform separators are implementation details callers should normalize before comparison.

Remarks

This runner belongs to the config package and intentionally has no dependency on CliFx, AppSurface Console, or any command-specific abstractions. Console applications should expose their own app-local command, pass that command's output writer to Run(TextWriter), and translate unsuccessful results into their command framework's failure type. V1 audits only IEnvironmentProvider.Environment from the already-built app host. It does not provide a command-level environment override, does not enumerate raw unknown environment variables, and cannot rescue apps that fail before the host and command service can run.

Remarks

DefaultConfigFileLocationProvider returns AppContext.BaseDirectory from Directory. This is appropriate for simple apps that keep configuration beside application binaries. Use a custom IConfigFileLocationProvider for environment-specific, user-scoped, container-mounted, or service-hosted configuration. Pitfall: AppContext.BaseDirectory is not necessarily System.IO.Directory.GetCurrentDirectory and can vary by deployment model, test runner, or host.

Remarks

Reports are immutable snapshots from the caller's perspective: provider order, entries, diagnostics, and redaction policy describe one audit run and should not be treated as live configuration. Use Entries for machine inspection and DiscoveredKeys for effective provider-discovered configuration keys that are not necessarily represented by known entries. Use ConfigAuditTextRenderer when operators need a deterministic text dump.

Remarks

Classifications are relative to the AppSurface audit registry, not to all application code. An ConfigAuditDiscoveredKeyClassification.Unknown key can be a typo, stale setting, or a value consumed outside AppSurface's known-entry registry; it is not proof that no code uses the key. Use ValueDisplayState to distinguish shown, redacted, complex-omitted, and inventory-omitted values. The display state describes this report's rendering decision only; it is not a sensitivity or secrecy classification.

Remarks

Precedence is the display order used by audit reports. Environment providers are marked as overrides because they are checked before normal priority-ordered providers.

Remarks

State summarizes the entry as a whole. Object entries can contain Children with more specific provenance, including nested ConfigAuditEntryState.PartiallyResolved states when descendants are patched. DisplayValue is already redacted and can be null for complex values, including collections whose elements are not dumped into parent display strings. Callers should inspect source records and available children instead of assuming a full object dump is available.

Remarks

Both values are one-based. ByteColumnNumber counts UTF-8 bytes from the start of the physical line, so it can differ from an editor's character column when a line contains non-ASCII characters before the source token.

Remarks

Array and list entries use zero-based Index values. Dictionary entries use KeyLabel, which is either the non-sensitive key label, a display-suppressed placeholder, or an in-report redaction label such as [redacted-key-1]. Labels are intended for display and comparison within one report only. When configured, KeyCorrelationId is the separate environment-scoped opaque value for comparing dictionary keys inside one named environment's report history. Use ComparisonKeyCorrelationId for explicit cross-environment config diff matching.

Remarks

Source records identify where a value came from and how it was applied. File paths, environment variable names, and config paths are optional because not every provider exposes the same provenance. File sources can also include Location when the provider can truthfully map the parsed value back to an exact file coordinate. The source role is especially important for mixed values: a base source can be combined with patch sources from higher-priority providers.

Remarks

Diagnostic messages are intended to be display-safe and stable enough for operators. Use Code for programmatic handling, and use Source when a diagnostic can be tied to one provider, file, or environment variable.

Remarks

The built-in policy is always enabled and uses fragment matching before values are exposed through ConfigAuditEntry.DisplayValue. MatchedFragments is a snapshot for explanation, not a mutable policy hook. Dictionary key correlation metadata describes the configured report policy without exposing the secret key used for scoped HMAC derivation.

Remarks

IConfigProvider.GetValue{T} preserves ordinary provider fallback for missing values, but it also honors fail-closed provider diagnostics. When a provider reports that resolution must stop, the manager throws ConfigurationResolutionException instead of querying lower-priority providers.

Remarks

Defaults preserve the original audit behavior: object members are reported, collection parent values remain opaque, and collection elements are not traversed unless TraverseCollectionElements is enabled. Instances are copied by ConfigAuditKnownEntry, so registration captures a stable snapshot. Use ConfigAuditEntryOptionsBuilder with the service-collection registration callback when mutable callback configuration is more convenient than an object initializer. When entries with the same key are merged, explicitly assigned manual options override wrapper-discovered options one property at a time.

Remarks

The builder exists only for configuration ergonomics. AppSurface snapshots it into immutable options when registering the audit key, so later builder mutations cannot affect reports. Property setters are also tracked as explicit assignments, allowing manual registrations to override wrapper attribute options even when the assigned value is the option's default.

Remarks

Providers use terminal diagnostics when returning null would be ambiguous. For example, a provider can distinguish a true missing key, which may fall through, from an unavailable secret store, which should not allow lower-priority files to mask the failure. Diagnostic text must not contain raw configuration values.

Remarks

The runner belongs to the config package and intentionally has no dependency on CliFx, AppSurface Console, or any command-specific abstractions. Apps can expose a command that either compares two named environments from the already-built host or compares consumer-owned captured JSON snapshots. Non-fatal workflow failures are converted to display-safe ConfigAuditDiffCommandFailure objects with problem, cause, fix, and documentation fields.

Remarks

Apply this attribute to a Config{T} or ConfigStruct{T} wrapper when operators need element-level visibility for that key. Attribute presence enables traversal; there is no separate enabled flag. The limit properties mirror ConfigAuditEntryOptions and are validated when reports are built. Invalid limits emit a config-audit-options-invalid diagnostic and fall back to safe bounded defaults. Non-sensitive dictionary keys may be displayed by default, but sensitive-looking keys are always redacted before structured reports or text output are returned. The attribute is inherited by derived wrappers; place a new attribute on the derived wrapper when it needs different traversal limits. Dictionary key correlation stays disabled unless DictionaryKeyCorrelationMode is set and global correlation key material is configured.