Enables safe collection element traversal for a discovered configuration wrapper in audit reports.
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.
ConfigAuditEntryOptions ToOptions()
Converts the attribute values into immutable audit entry options.
The returned options enable collection traversal, copy attribute values as-is, and mark every traversal option plus dictionary key correlation as assigned. The traversal attribute never assigns entry sensitivity; use manual audit-key options when a discovered wrapper should be classified as sensitive.
int MaxCollectionDepth { get; set; }
Source
Gets or sets the maximum nested collection depth traversed for the attributed wrapper.
The default is ConfigAuditEntryOptions.DefaultMaxCollectionDepth
. Values must be greater than or equal to 0
; invalid values are reported by audit diagnostics and replaced with the safe default for traversal.
int MaxCollectionElements { get; set; }
Source
Gets or sets the maximum number of elements reported from any one traversed collection.
The default is ConfigAuditEntryOptions.DefaultMaxCollectionElements
. Values must be greater than or equal to 0
; invalid values are reported by audit diagnostics and replaced with the safe default for traversal.
int MaxReportNodes { get; set; }
Source
Gets or sets the maximum number of child nodes created for the attributed entry before traversal stops.
The default is ConfigAuditEntryOptions.DefaultMaxReportNodes
. Values must be greater than or equal to 1
; invalid values are reported by audit diagnostics and replaced with the safe default for traversal.
bool DisplayDictionaryKeys { get; set; }
Source
Gets or sets a value indicating whether non-sensitive dictionary keys may appear as element labels.
The default is true
. Sensitive-looking dictionary keys are redacted even when this property allows key labels to be displayed.
ConfigAuditDictionaryKeyCorrelationMode DictionaryKeyCorrelationMode { get; set; }
Source
Gets or sets the opt-in dictionary key correlation mode for the attributed wrapper.
The default is ConfigAuditDictionaryKeyCorrelationMode.None
, which keeps redacted dictionary key labels report-local. ConfigAuditDictionaryKeyCorrelationMode.ScopedHmac
adds opaque correlation ids when ConfigAuditDictionaryKeyCorrelationOptions
supplies valid key material.
Base class for AppSurface scalar configuration value validation attributes. Apply derived attributes to concrete Config{T}
or ConfigStruct{T}
wrapper types to validate resolved scalar values during configuration initialization.
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.
Validates that a resolved scalar configuration value is not empty. Supported value types are string
and Guid
.
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.
Validates that a resolved scalar numeric configuration value is inside an inclusive range. Supported value types are int
and double
.
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.
object Minimum { get; }
Source
Gets the inclusive minimum allowed value as a boxed int
or double
, matching the constructor overload used to create the attribute.
The integer constructor stores a boxed int
, and the double constructor stores a boxed double
. Callers should unbox this value according to the constructor overload they used. The attribute treats the bound as inclusive and may widen integer bounds when validating double values.
object Maximum { get; }
Source
Gets the inclusive maximum allowed value as a boxed int
or double
, matching the constructor overload used to create the attribute.
The integer constructor stores a boxed int
, and the double constructor stores a boxed double
. Callers should unbox this value according to the constructor overload they used. The attribute treats the bound as inclusive and may widen integer bounds when validating double values.
Validates that a resolved scalar string configuration value has at least the configured length.
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.
int Length { get; }
Source
Gets the minimum allowed string length.
The single composition authority for runtime, effective audit, and local-only startup validation.
bool ContainsSecrets(Type type)
Detects the explicit typed opt-in without resolving any provider.
IReadOnlyList<string> GetSecretPaths(string key, Type type)
Gets declared secret paths for structural audit redaction, even when execution fails.
ConfigCompositionExecutionResult Execute(string environment, string key, Type type)
Executes one observation. Runtime and audit receive identical semantics for identical inputs.
void ValidatePlan(string environment, string key, Type type)
Compiles known roots at startup without enabled secret reads or activating application wrappers.
ConfigSecretProviderRegistry Registry { get; }
Source
The immutable registration snapshot shared by all entry points.
Owns raw payloads, source observations and opaque binding slots for one execution only.
ConfigCompositionExecutionResult? TryDirect(string environmentName, string key, Type type, out IReadOnlyList<ConfigAuditDiagnostic> conversionDiagnostics)
Probes every legacy direct-root candidate before compiling file policy or resolving providers.
ConfigCompositionExecutionResult Execute(ConfigCompositionPlan plan)
Resolves one validated plan, with providerless uniqueness, exact rescue, and one final bind.
bool IsFatalProviderException(Exception exception)
Identifies process-level failures that must escape the provider redaction boundary.
bool TryConvertScalarText(string raw, Type type, out object? value)
Converts provider, environment, and file scalar text without exposing failed payloads.
Mutable JSON operations confined to the current invocation; never operate on a cached snapshot.
bool TryGet(JsonObject root, IReadOnlyList<string> path, out JsonNode? node)
Finds a relative path case-insensitively while preserving explicit null presence.
void Set(JsonObject root, IReadOnlyList<string> path, JsonNode? value)
Replaces a relative path, creating object ancestors and removing case-only spellings.
A value-free observed provider outcome.
Opaque slot provenance. It never contains a payload, reference key or version.
One invocation's result; only the explicit internal Value accessor carries the transient application value.
ConfigCompositionRootState State { get; }
Source
The root outcome.
object? Value { get; }
Source
The transient bound root; consumers must never format it for diagnostics.
IReadOnlyList<ConfigCompositionFailure> Failures { get; }
Source
Every unresolved ordered failure.
IReadOnlyList<ConfigSecretSlotTrace> Slots { get; }
Source
The value-free slot trace.
IReadOnlyList<ConfigAuditSourceRecord> Sources { get; }
Source
The observed root source contributions.
IReadOnlyList<ConfigAuditDiagnostic> Diagnostics { get; }
Source
Safe conversion warnings.
bool DirectRoot { get; }
Source
Whether a direct environment root bypassed plan compilation.
A module that registers configuration management services and automatically discovers and registers configuration objects.
AppSurfaceConfigModule
registers core configuration services immediately, including audit reporting, diagnostics, sanitized diff comparison, diff rendering, and command-runner helpers. It also registers IEnvironmentConfigCandidateInspector
for metadata-only name planning, sharing the first-resolution frozen mapping options with the built-in environment provider. It 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. Discovery records lazy singletons without activating wrappers. Register singleton-safe constructor dependencies before building the final provider; they resolve when a wrapper is first requested.
void ConfigureServices(StartupContext context, IServiceCollection services)
Registers AppSurface config services and schedules typed config discovery after module registration.
context
services
ConfigureServices(StartupContext, IServiceCollection)
adds the default manager, providers, audit reporter, audit redactor, text renderer, diagnostics runner, file-location provider, and sanitized diff services, then appends a StartupContext.CustomRegistrations
callback. The diff registrations include ConfigAuditReportDiffer
for pure typed snapshot comparison, ConfigAuditDiffTextRenderer
for deterministic operator output, and ConfigAuditDiffCommandRunner
for command-framework-agnostic same-host and captured-snapshot workflows. The custom callback scans dependency, entry, and root-module assemblies for concrete IConfig
implementations through the same registrar as AppSurfaceConfigServiceCollectionExtensions.AddAppSurfaceConfig{TConfig}
. Each lazy singleton initializes from IConfigManager
and IEnvironmentProvider
. Wrappers decorated with ConfigAuditCollectionTraversalAttribute
also contribute audit traversal options for their key. Each assembly is checked against the package compatibility contract
before reflecting over its types, including when callers invoke custom registration directly.
Configures scoped dictionary-key correlation identifiers for configuration audit reports.
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.
string? SecretKey { get; set; }
Source
Gets or sets the deployment-local HMAC secret used to derive correlation identifiers.
The value is interpreted as UTF-8 bytes and must contain at least 32 bytes. Store it in a secret manager or equivalent protected configuration source. Rotating this value intentionally breaks historical correlation.
string? KeyId { get; set; }
Source
Gets or sets the display-safe identifier for the active correlation key.
The key id appears in reports so operators can tell which secret produced a correlation identifier. It must be non-empty and can contain only ASCII letters, digits, .
, _
, and -
.
string? ApplicationScope { get; set; }
Source
Gets or sets the application or product scope included in correlation derivation.
Use a stable public identifier for the app or product, not a secret. Changing this value intentionally breaks historical correlation and prevents ids from matching across unrelated apps that share a key.
Creates per-entry dictionary-key correlation contexts from deployment-level options.
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.
ConfigAuditDictionaryKeyCorrelationContext CreateContext(string environment, string rootKey)
Creates an immutable context for one report environment and root audit key.
environment
rootKey
An available context when all correlation options are valid; otherwise an unavailable context carrying the reason reported by config-audit-key-correlation-unavailable
.
Available contexts derive ids in the form v1:{keyId}:{24-hex-chars}
. The suffix is the first TruncatedBytes
bytes (96 bits) of an HMAC-SHA256 digest over AlgorithmVersion
, application scope, environment, root key, and raw dictionary key. Diff comparison ids derive a separate v1c:{keyId}:{24-hex-chars}
value that omits the environment by design so captured reports from different environments can match the same redacted dictionary key.
string? NormalizeKeyId(string? keyId)
Trims the configured key id before validation and report metadata rendering.
keyId
The trimmed key id, or null
when no value was configured.
string? NormalizeApplicationScope(string? applicationScope)
Trims the configured application scope before validation and HMAC input construction.
applicationScope
The trimmed application scope, or null
when no value was configured.
bool IsDisplaySafeKeyId(string keyId)
Determines whether a key id is safe to render in report metadata and text output.
keyId
true
when the key id contains only ASCII letters, digits, .
, _
, or -
; otherwise false
.
string ComputeCorrelationId(byte[] secretKey, string keyId, string applicationScope, string environment, string rootKey, string rawDictionaryKey)
Computes the stable opaque id for a raw dictionary key within a fully scoped report context.
secretKey
keyId
applicationScope
environment
rootKey
rawDictionaryKey
A v1:{keyId}:{24-hex-chars}
correlation id with a 96-bit truncated HMAC-SHA256 suffix.
string ComputeComparisonCorrelationId(byte[] secretKey, string keyId, string applicationScope, string rootKey, string rawDictionaryKey)
Computes the stable opaque id for comparing a raw dictionary key across report environments.
secretKey
keyId
applicationScope
rootKey
rawDictionaryKey
A v1c:{keyId}:{24-hex-chars}
comparison id with a 96-bit truncated HMAC-SHA256 suffix.
Carries the correlation state used while traversing one configured audit entry.
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.
ConfigAuditDictionaryKeyCorrelationContext Available(byte[] secretKey, string keyId, string applicationScope, string environment, string rootKey)
Creates a context that can derive scoped HMAC ids for dictionary keys in one report entry.
secretKey
keyId
applicationScope
environment
rootKey
An available correlation context.
string? CreateCorrelationId(string rawDictionaryKey)
Derives the opaque correlation id for a raw dictionary key when this context is available.
rawDictionaryKey
A v1:{keyId}:{24-hex-chars}
id containing a 96-bit truncated HMAC-SHA256 digest, or null
when this context is unavailable.
string? CreateComparisonCorrelationId(string rawDictionaryKey)
Derives the opaque comparison id for a raw dictionary key when this context is available.
rawDictionaryKey
A v1c:{keyId}:{24-hex-chars}
id containing a 96-bit truncated HMAC-SHA256 digest, or null
when this context is unavailable.
bool IsAvailable { get; }
Source
Gets a value indicating whether this context can derive correlation identifiers.
A context is unavailable when the secret key is absent or shorter than MinimumSecretBytes
UTF-8 bytes, the key id is missing or not display-safe, or the application scope is missing.
Resolves a parsed logical key through one provider-native source projection.
Providers must be safe for concurrent requests. Missing permits fallback; Terminal suppresses lower providers. Do not normalize logical identity or store a follow-up diagnostic cache. See the provider-author contract
.
ConfigProviderValueResult<T> Resolve<T>(ConfigProviderRequest request)
Returns exactly one missing, found, or terminal outcome for the request.
T
request
A non-null structured result; expected provider failures are terminal diagnostics.
int Priority { get; }
Source
Gets priority; larger values are queried first after the environment provider.
string Name { get; }
Source
Gets the value-safe provider name used in provenance.
Provides the environment-variable candidate names used by configuration lookup and patching.
IReadOnlyList<string> GetDirectCandidates(string environment, string key)
Gets the ordered direct candidates for a logical configuration key.
environment
key
The distinct candidates in scoped flat, unscoped flat, scoped hierarchical, and unscoped hierarchical order.
ImmutableArray<EnvironmentCompositionPathCandidate> GetDirectMetadataCandidates(string environment, string key)
Materializes direct legacy producers and their scope/shape before ordinal de-duplication.
IReadOnlyList<string> GetPathCandidates(string environment, IReadOnlyList<string> segments)
Gets the ordered direct candidates for canonical path segments.
environment
segments
The distinct candidates in the same order as GetDirectCandidates
, with the segments projected through the existing dotted-key spelling rules.
ImmutableArray<EnvironmentCompositionPathCandidate> GetPathMetadataCandidates(string environment, IReadOnlyList<string> segments)
Projects literal path segments through the existing dotted composition spelling.
This projection is intentionally not an injective logical-key encoding.
string NormalizeSegment(string value)
Normalizes one environment or legacy key segment to uppercase flat spelling.
value
The uppercase segment with periods and hyphens replaced by underscores.
string NormalizeHierarchicalKey(string value)
Normalizes a logical key to uppercase hierarchical environment-variable spelling.
value
The key split on periods and hyphens, with empty segments removed and segments joined by double underscores.
IReadOnlyList<string> BuildDirectCandidates(string envPrefix, string legacyKey, string hierarchicalKey)
Builds and ordinal-deduplicates the legacy direct candidate sequence.
envPrefix
legacyKey
hierarchicalKey
The candidates in legacy precedence order.
ImmutableArray<EnvironmentCompositionPathCandidate> BuildMetadataCandidates(string envPrefix, string legacyKey, string hierarchicalKey)
Attaches producer metadata and retains the first ordinal name in legacy precedence order.
Bounds structural discovery and synchronous providerless work for opted-in configuration roots.
All values must be positive. Configuration is captured once per host; rebuild the host to change it. The providerless deadline is cooperative and shared by all unconstrained references in one root invocation.
TimeSpan ProviderlessResolutionBudget { get; set; }
Source
Total providerless resolution budget per root; defaults to 30 seconds.
int MaxCompositionGraphDepth { get; set; }
Source
Maximum member depth beneath a root; defaults to 32.
int MaxCompositionGraphNodes { get; set; }
Source
Maximum discovered graph nodes including the root; defaults to 4096.
int MaxSecretDestinationsPerRoot { get; set; }
Source
Maximum scalar secret destinations in one root; defaults to 256.
Rejects nonpositive discovery/deadline limits before a host reports ready.
Validates resolved Config{T}
and ConfigStruct{T}
values with DataAnnotations. The validator returns immediately for null values and scalar primitives, validates object and field annotations before initialization completes, and traverses nested members only when callers opt in with ValidateObjectMembersAttribute
or ValidateEnumeratedItemsAttribute
. Recursive traversal tracks the active object path by reference so cycles terminate while shared objects can still be reported at each reachable path. AppSurface owns this traversal and the ConfigurationValidationException
shape; the custom validator type overloads on the Microsoft Options marker attributes are reported as unsupported failures rather than invoked.
void Validate(AppSurfaceConfigKey key, Type configType, Type valueType, object? value)
Validates a resolved configuration value and throws ConfigurationValidationException
when DataAnnotations failures are found. Call this after provider/default resolution and before config initialization is considered complete. Null and scalar values short-circuit, recursive validation is marker-gated, and callers should catch ConfigurationValidationException
to inspect the structured failures.
key
configType
valueType
value
ConfigurationValidationException
Provides the base directory used to resolve AppSurface configuration files.
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.
string Directory { get; }
Source
Gets the absolute directory path containing configuration files.
The value should be an absolute path without a required trailing slash. The provider does not own the directory lifetime and should not create, delete, or lock it. A typical consumer checks System.IO.Directory.Exists(provider.Directory)
before resolving known config file names below that path and returns a clear validation failure when the directory is unavailable.
Attaches stable, safe remediation metadata to framework-owned exceptions.
T Enrich<T>(T exception, string code, string operation, string fix, string recovery, string helpUri)
Enriches the original known exception in place and returns that same object.
T
exception
code
operation
fix
recovery
helpUri
The same exception instance.
Call only at a known framework validation boundary; arbitrary host callbacks are not certified.
T Require<T>(T? value, string parameter, string operation)
Validates immutable public DTO inputs before storing or copying them.
ArgumentException NullEntry(string parameter, string operation)
Reports a null candidate element with safe, parameter-only remediation metadata.
Specifies the configuration key or path for a type.
string? ExtractKey(object obj)
Extracts the configuration key from an object's type attribute.
obj
The configuration key, or null if not specified.
string? ExtractKey(Type type)
Extracts the configuration key from a type's attribute.
type
The configuration key, or null if not specified.
AppSurfaceConfigKey GetLogicalKey(Type type)
Computes the full configuration key path for a type, recursively including declaring types unless Root
is true.
type
The computed configuration key path.
This public helper always uses strict colon grammar: literal dots remain inside segments. Host discovery uses the finalized input parser instead, as described by the logical-key contract
.
AppSurfaceConfigKey GetLogicalKey(Type type, IConfigKeyInputParser parser)
Computes a logical key using the finalized application input parser for compatibility declarations.
type
parser
The parsed logical key, including immutable input provenance.
Each attribute fragment is parsed exactly once. If any fragment is translated, the composed key retains translated origin and the original dot-joined declaring-type spelling for provider aliases and diagnostics.
string GetKeyPath(Type type)
Returns the colon-delimited compatibility rendering of GetLogicalKey(Type)
.
type
The rendered logical key.
string Key { get; }
Source
Gets the configuration key or path for this type.
bool Root { get; }
Source
Gets a value indicating whether this key should be treated as a root key, ignoring the declaring type hierarchy.
An immutable segment path; logical identity is ordinal case-insensitive, never a raw prefix.
ConfigLogicalPath Parse(string path)
Parses either supported separator without changing external provider keys.
ConfigLogicalPath FromKey(AppSurfaceConfigKey key)
Creates a path from an already parsed key, preserving literal dots in each segment.
ConfigLogicalPath Append(string member)
Appends one literal serialized member name; dots remain part of that segment.
bool IsAncestorOrEqual(ConfigLogicalPath other)
Tests equality or a complete-segment ancestor relationship.
bool Overlaps(ConfigLogicalPath other)
Tests intersecting paths, excluding siblings.
IReadOnlyList<string> Segments { get; }
Source
Gets the original segment spellings.
string Canonical { get; }
Source
Gets colon-delimited logical spelling.
string Dotted { get; }
Source
Gets dotted spelling for legacy file origins and environment normalization.
A source entry before any case-insensitive insertion can discard collision evidence.
T
Retains every origin, the declared precedence winner, and any terminal identity condition.
bool IsTerminal { get; }
Source
Gets whether the collision domain must fail closed before selecting a value.
ConfigSourceEntry<T>? Winner { get; }
Source
Gets the last declared layer's entry only when identity is unambiguous.
Builds an immutable typed index after retaining and validating all native source occurrences.
bool TryGet(AppSurfaceConfigKey key, out ConfigSourceProjectionResult<T>? result)
Finds one logical identity without selecting a value from a terminal collision domain.
IEnumerable<ConfigSourceProjectionResult<T>> Entries { get; }
Source
Gets deterministic projected entries, retaining their exact native locators.
Selects individual configuration wrappers, including wrappers outside module discovery.
Use this API with the normal Config host composition when a shared contract assembly is outside the module, root, and entry assembly scan. See the logical-key and registration contract
.
IServiceCollection AddAppSurfaceConfig<TConfig>(this IServiceCollection services)
Registers one wrapper's lazy singleton and attributed audit declaration.
TConfig
services
The same collection for chaining.
ArgumentNullException
ArgumentException
Core.AppSurfacePackageCompatibilityException
InvalidOperationException
Repeated selection and module discovery share registration rules. One existing exact unkeyed singleton is preserved unchanged; its caller owns initialization, validation, and agreement with the attributed key. Keyed descriptors coexist independently. Later singleton Replace is supported on a valid collection; arbitrary later duplicate appends are unsupported and rejected on the next registration call. This method does not build a provider, parse keys, construct wrappers, call Init, or read providers or secrets. It ensures declaration/parser/options infrastructure; the host supplies IConfigManager, Core.IEnvironmentProvider, providers, and singleton-safe constructor dependencies. Finalized host options determine the logical key. At resolution, ActivatorUtilities selects the constructor and the framework initializes its own wrapper once per successful singleton activation per provider. Dependency, value, validation, factory, and cancellation failures retain their normal exception behavior. Audit constructs a separate inspection wrapper and may read providers; it does not initialize or inspect arbitrary state on a caller-owned singleton.
Provides the canonical scalar-type classification shared by configuration validation paths.
bool IsScalar(Type type)
Returns whether type
is treated as a scalar configuration value. Nullable wrappers are unwrapped before inspection. Supported scalar types are primitives, enums, string
, decimal
, DateTime
, DateTimeOffset
, TimeSpan
, Guid
, and Uri
.
type
true
when type
is a supported scalar type.
Allows external configuration providers to expose source-aware audit details without depending on Config internals.
Implement this interface when a provider can resolve a known audit key with richer provenance or diagnostics than the generic IConfigProvider.Resolve{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.
ConfigProviderAuditResolution ResolveForAudit(ConfigProviderRequest request, Type valueType, ConfigAuditSourceRole role)
Resolves a known audit key with source metadata for a configuration audit report.
request
valueType
role
The provider audit resolution.
Return a ConfigProviderAuditResolution
whose logical key matches request.Key
. Failed claimed-key lookups should use ConfigAuditEntryState.Invalid
with display-safe diagnostics instead of throwing when the failure is an expected provider outcome. Do not include raw secret values in diagnostics or source metadata.
IReadOnlyList<ConfigAuditDiagnostic> GetReportDiagnostics(string environment)
Gets report-level diagnostics for environment
.
environment
Display-safe diagnostics that are not tied to one key.
Use this for provider-wide warnings or failures that are not tied to one key. The returned diagnostics may be rendered before or after key-level diagnostics, so consumers must not depend on ordering for correctness.
Describes a display-safe failure from ConfigDiagnosticsCommandRunner
.
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.
string ToDisplayString()
Formats this failure for command-line display.
A display-safe multiline failure message.
string Problem { get; }
Source
Gets the operator-facing problem summary.
string Cause { get; }
Source
Gets the display-safe cause summary.
string Fix { get; }
Source
Gets the suggested next action.
string? ExceptionType { get; }
Source
Gets the exception type that caused the failure, when available.
The type name is retained for support triage while the raw exception message is intentionally omitted.
Builds safe child audit entries from object and opt-in collection values.
ConfigAuditTraversalResult BuildChildren(ConfigAuditPath path, object? value, IReadOnlyList<ConfigAuditSourceRecord> sources, ConfigAuditFactContext factContext, ConfigAuditEntryOptions options, HashSet<object> visited, ConfigAuditDictionaryLabelSet labels, ConfigAuditDictionaryKeyCorrelationContext correlation, ConfigAuditReportTraversalContext? reportTraversalContext = null)
Builds child audit entries for value
.
path
value
sources
factContext
ConfigAuditFactContext.Empty
when resolution produced no facts or when child diagnostics must not infer collection element creation from patch evidence. Non-empty contexts can add diagnostics to the returned ConfigAuditTraversalResult
without changing labels, correlations, traversal limits, or the child value shape. options
visited
labels
correlation
reportTraversalContext
The traversed child entries and traversal diagnostics.
ConfigAuditTraversalResult BuildChildren(ConfigAuditPath path, object? value, IReadOnlyList<ConfigAuditSourceRecord> sources, ConfigAuditFactContext factContext, ConfigAuditEntryOptions options, HashSet<object> visited, ConfigAuditDictionaryLabelSet labels, ConfigAuditDictionaryKeyCorrelationContext correlation, ref int budget, ConfigAuditReportTraversalContext? reportTraversalContext)
Builds child audit entries for value
while sharing the caller-owned traversal budget.
path
value
sources
factContext
ConfigAuditFactContext.Empty
when there are no facts; non-empty contexts can mark environment-created or unknown-base collection elements in the returned ConfigAuditTraversalResult
. options
visited
labels
correlation
budget
reportTraversalContext
The traversed child entries and traversal diagnostics.
ConfigAuditTraversalResult BuildComposedObjectChildren(ConfigAuditPath path, object value, IReadOnlyList<ConfigAuditSourceRecord> sources, ConfigAuditFactContext facts, ConfigAuditEntryOptions options, HashSet<object> visited, ConfigAuditDictionaryLabelSet labels, ConfigAuditDictionaryKeyCorrelationContext correlation, ref int budget, ConfigAuditReportTraversalContext? reportContext)
Uses the same default serialized member names as composition, never reading a secret member getter.
ConfigAuditTraversalResult BuildUnresolvedSecretChildren(ConfigAuditPath path, ref int budget, ConfigAuditReportTraversalContext? reportContext)
Retains only declared slot topology when a root or parent has no safe bound value to inspect.
ConfigAuditEntry BuildSecretChild(ConfigSecretSlotTrace slot, string? declaredType = null)
Renders engine state without accessing a wrapper, descriptor, or payload.
Describes an external provider's audit resolution for one known configuration key.
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.
ConfigProviderAuditResolution Missing(AppSurfaceConfigKey key)
Creates a missing resolution for key
.
key
A missing audit resolution.
AppSurfaceConfigKey LogicalKey { get; }
Source
Gets the logical AppSurface configuration key.
string Key { get; }
Source
Gets the colon-delimited display rendering of LogicalKey
.
ConfigAuditEntryState State { get; }
Source
Gets the audit state.
object? Value { get; }
Source
Gets the resolved value, if any.
IReadOnlyList<ConfigAuditSourceRecord> Sources { get; }
Source
Gets the source records that contributed to the value.
IReadOnlyList<ConfigAuditDiagnostic> Diagnostics { get; }
Source
Gets display-safe diagnostics for this key.
Configures a config audit report comparison.
Options affect evidence wording, renderer detail, and whether unchanged items are retained. They do not cause provider resolution, host startup, or command execution.
ConfigAuditDiffEvidenceMode EvidenceMode { get; set; }
Source
Gets or sets the evidence mode for this comparison.
bool IncludeUnchangedItems { get; set; }
Source
Gets or sets a value indicating whether unchanged items should be included in ConfigAuditDiffReport.Items
.
ConfigAuditDiffSourceDetail SourceDetail { get; set; }
Source
Gets or sets the source-detail level used by the text renderer.
Describes the result of comparing two sanitized config audit reports.
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.
string BaselineEnvironment { get; init; }
Source
Gets the baseline report environment.
string TargetEnvironment { get; init; }
Source
Gets the target report environment.
DateTimeOffset GeneratedAt { get; init; }
Source
Gets the time when the diff report was generated.
ConfigAuditDiffEvidenceMode EvidenceMode { get; init; }
Source
Gets the evidence mode used for this comparison.
ConfigAuditDiffSourceDetail SourceDetail { get; init; }
Source
Gets the source-detail level requested for renderer output.
ConfigAuditDiffSummary Summary { get; init; }
Source
Gets aggregate item counts for this diff.
IReadOnlyList<ConfigAuditComparisonDiagnostic> Diagnostics { get; init; }
Source
Gets comparison diagnostics that apply to the whole diff.
IReadOnlyList<ConfigAuditDiffItem> Items { get; init; }
Source
Gets deterministic diff items retained for rendering or programmatic inspection.
Summarizes item counts for a config audit diff.
int Changed { get; init; }
Source
Gets the number of changed items.
int Added { get; init; }
Source
Gets the number of added items.
int Removed { get; init; }
Source
Gets the number of removed items.
int Unchanged { get; init; }
Source
Gets the number of unchanged items, even when unchanged items are not retained.
int Uncomparable { get; init; }
Source
Gets the number of uncomparable items.
int Diagnostics { get; init; }
Source
Gets the number of comparison diagnostics.
Describes one display-safe config audit comparison diagnostic.
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.
ConfigAuditDiagnosticSeverity Severity { get; init; }
Source
Gets the diagnostic severity.
string Code { get; init; }
Source
Gets the stable diagnostic code.
string Message { get; init; }
Source
Gets the display-safe diagnostic message.
string? Key { get; init; }
Source
Gets the affected item path or key, when available.
Describes one item in a config audit diff.
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.
ConfigAuditDiffItemKind Kind { get; init; }
Source
Gets the kind of audit evidence represented by this item.
ConfigAuditDiffItemStatus Status { get; init; }
Source
Gets the comparison status.
ConfigAuditDiffSignificance Significance { get; init; }
Source
Gets the review significance.
string Key { get; init; }
Source
Gets the deterministic item key or path.
string Description { get; init; }
Source
Gets an operator-facing display-safe description.
string? BaselineDisplayValue { get; init; }
Source
Gets the baseline display value, when the audit report rendered one.
string? TargetDisplayValue { get; init; }
Source
Gets the target display value, when the audit report rendered one.
ConfigAuditDiffValueEvidence ValueEvidence { get; init; }
Source
Gets the value-evidence classification.
IReadOnlyList<ConfigAuditSourceRecord> BaselineSources { get; init; }
Source
Gets baseline source records attached to this item.
IReadOnlyList<ConfigAuditSourceRecord> TargetSources { get; init; }
Source
Gets target source records attached to this item.
IReadOnlyList<ConfigAuditComparisonDiagnostic> Diagnostics { get; init; }
Source
Gets item-level comparison diagnostics.
One parsed logical-key request within a top-level resolution or audit scope.
Providers consume requests from the manager; they never translate application input or create a second scope. Environment spelling is independent of logical-key identity.
string Environment { get; }
Source
Gets the exact active environment name.
AppSurfaceConfigKey Key { get; }
Source
Gets the parsed logical identity, preserving its chosen spelling.
ConfigResolutionScope Scope { get; }
Source
Gets the operation-owned snapshot and notice collector.
ConfigKeyInputOrigin InputOrigin { get; }
Source
Gets the application parser origin, which does not affect key equality.
string? OriginalInput { get; }
Source
Gets the original input only for train-1 native alias generation.
Owns one environment snapshot, notice collector, and optional aggregate audit budget.
The lazy snapshot caches success and failure. Dispose an audit scope after every remote waiter finishes.
bool TryAcquireRemoteLookup(out IDisposable? lease, out ConfigProviderTerminalDiagnostic? diagnostic)
Reserves one uncached remote lookup and a concurrency slot within the operation deadline. Dispose the lease after the caller stops waiting; this never cancels a shared fetch. Cached reads need no reservation. A rejected reservation must not start a remote operation. Successful lease acquisition while the shared token is live is the admission boundary: a worker admitted before cancellation may be queued or enter its synchronous client call after the deadline. A new request arriving after cancellation cannot acquire a lease or start a worker.
bool ConfirmRemoteLookupAdmission(ref IDisposable? lease, out ConfigProviderTerminalDiagnostic? diagnostic)
Confirms a newly granted audit lease while the shared deadline is still live. A grant racing with cancellation is disposed and reported as incomplete audit evidence. This internal boundary is also used to verify that post-grant cancellation releases the slot.
ConfigProviderTerminalDiagnostic MarkAuditDeadline()
Records a deadline without converting explicit caller cancellation to an audit failure.
ConfigEnvironmentSnapshot GetEnvironmentSnapshot(IEnvironmentProvider provider, ConfigResourceOptions options)
Gets the same captured snapshot or failure for every request in this scope.
void AddNotice(string provider, AppSurfaceConfigKey key, ConfigProviderNotice notice, int capacity)
Collects bounded value-free notices; saturation marks audit evidence incomplete.
void Dispose()
Releases audit timer and semaphore resources after all report work and leases finish.
CancellationToken CancellationToken { get; }
Source
Gets cancellation for the caller's wait, never ownership of a shared remote fetch.
bool IsAudit { get; }
Source
Gets whether this operation owns an aggregate audit budget.
ConfigProviderTerminalDiagnostic? IncompleteAuditDiagnostic { get; }
Source
Gets the first budget failure so a report cannot claim complete resolution or notice evidence.
IReadOnlyList<ConfigResolutionNotice> Notices { get; }
Source
Returns a point-in-time view of collected notices.
int NoticeCount { get; }
Source
Gets the current notice count without allocating a snapshot before a patch transaction.
Releases a remote concurrency slot at most once.
A value-free notice with the provider and logical identity that produced it.
An immutable exact-name, folded-name, and prefix index over one environment capture.
ConfigEnvironmentSnapshot Capture(IEnvironmentProvider provider, ConfigResourceOptions options)
Captures all entries once, rejecting an oversized snapshot before index publication.
IReadOnlyList<string> GetMatchingNames(string expectedName)
Finds every exact native spelling equal to the expected name under ordinal ignore-case comparison.
IEnumerable<string> GetDescendantNames(string prefix)
Enumerates only present names below a native prefix, using binary search instead of speculative probes.
FrozenDictionary<string, string> Entries { get; }
Source
Gets exact native names and sensitive values; never serialize or log this dictionary.
Signals a bounded-input failure without carrying values or raw external exception text.
string Code { get; }
Source
Gets the stable value-safe resource diagnostic code.
Keeps report display paths separate from provider source paths while child entries are built.
DisplayPath
SourcePath
Element
CollectionDepth
RequiresInheritedSource
ConfigAuditPath Root(string key)
Starts a traversal from a strict colon-delimited source path.
ConfigAuditPath Root(AppSurfaceConfigKey key)
Starts traversal with the original typed identity; presentation is never reparsed as hierarchy.
ConfigAuditPath AppendMember(string name)
Appends one member segment while retaining dotted display and inherited privacy state.
ConfigAuditPath AppendIndex(int index, ConfigAuditElementKind kind)
Appends an invariant numeric source segment and a bracketed display index.
ConfigAuditPath AppendDictionaryKey(object? key, ConfigAuditEntryOptions options, ConfigAuditDictionaryLabelSet labels, ConfigAuditDictionaryKeyCorrelationContext correlation)
Builds a bounded display label and retains exact provenance only for a visible valid segment.
Literal dots, slashes, and brackets remain part of one segment. Hidden or invalid keys never enter public source paths.
The application boundary for environment-first, ordered configuration resolution.
Terminal failures suppress fallback but allow one transactional environment-child rescue.
T? GetValue<T>(string environment, AppSurfaceConfigKey key)
Resolves a strict typed key without applying legacy aliases.
T
environment
key
The value, or default only when all providers and patches are missing.
ConfigurationResolutionException
T? GetValue<T>(string environment, string key)
Parses application input once using the configured compatibility mode, then resolves.
T
environment
key
The value, or default when absent.
ArgumentException
ConfigurationResolutionException
Validates the coordinated configuration SPI before activating external provider or wrapper types.
void ValidateAssemblies(IEnumerable<Assembly> assemblies)
Checks assembly references without invoking provider code or enumerating implementation types.
assemblies
AppSurfacePackageCompatibilityException
Call before GetTypes, DI scans, or plugin activation. This guard performs no compatibility adaptation.
Supplies an isolated object transaction from present child values in the request's snapshot.
ConfigPatchResult<T> Patch<T>(ConfigProviderRequest request, T? currentValue)
Validates every present candidate before publishing one or more successfully bound children.
Never mutate currentValue. A failed child makes the entire patch terminal.
Validates registrations and known opted-in plans before readiness without resolving secret payloads.
This is an IHostedLifecycleService
so local validation runs in StartingAsync
, before any ordinary IHostedService.StartAsync
method can stop a fast host. Validation remains local and creates no wrappers or remote-resolution state.
Task StartingAsync(CancellationToken cancellationToken)
Compiles known roots locally before ordinary hosted-service startup begins.
Task StartAsync(CancellationToken cancellationToken)
Completes the ordinary hosted-service phase because validation ran in StartingAsync
.
Task StartedAsync(CancellationToken cancellationToken)
Completes the post-start lifecycle phase without activating wrappers or resolving payloads.
Task StoppedAsync(CancellationToken cancellationToken)
Completes the post-stop lifecycle phase because validation owns no shutdown work.
Task StoppingAsync(CancellationToken cancellationToken)
Completes the pre-stop lifecycle phase because validation owns no shutdown work.
Task StopAsync(CancellationToken cancellationToken)
No background work or payload state survives startup validation.
Creates ConfigurationValidationFailure
instances from DataAnnotations results while preserving AppSurface's member-path formatting contract.
ConfigurationValidationFailure FromValidationResult(AppSurfaceConfigKey key, Type configType, Type valueType, string? path, ValidationResult result, string? defaultMemberName = null)
Converts a ValidationResult
into a configuration-validation failure payload.
key
configType
valueType
path
result
defaultMemberName
result
has no member names, such as field-level validation where DataAnnotations did not bind the member name itself.
A normalized ConfigurationValidationFailure
.
Converts textual configuration provider values into AppSurface configuration value types.
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.
bool TryConvert<T>(string raw, out T? value)
Attempts to convert raw
into T
.
T
raw
value
true
when conversion succeeds.
bool TryConvert(string raw, Type targetType, out object? value)
Attempts to convert raw
into targetType
.
raw
targetType
value
true
when conversion succeeds.
Reviewed value-free diagnostic templates shared by built-in provider boundaries.
ConfigProviderTerminalDiagnostic Terminal(string code, params string[] safeIdentifiers)
Builds complete guidance using only known templates and classified source identifiers.
string SafeCode(string code, string fallback)
Returns a bounded catalogued automatic-log code, never arbitrary external-provider text.
ConfigProviderNotice LegacyDot(AppSurfaceConfigKey key)
Explains one automatic train-1 translation without including any configuration value.
ConfigProviderNotice LegacyAlias(string source, string replacement)
Explains the single historical native identifier that supplied a successful value.
Escapes and bounds untrusted identifiers independently of logical equality and native storage identity.
string Identifier(string? value, int limit = 256)
Renders at most limit characters plus a stable digest, escaping controls before display.
string Prose(string? value, int limit = 4096)
Escapes and caps explicit diagnostic prose without creating a fingerprint of untrusted text.
string Digest(string value)
Creates an identifier-only digest; callers must never pass configuration values.
Bounded process-level notice suppression. Saturation drops new identities rather than evicting old ones.
bool TryRemember(string code, string provider, string environment, AppSurfaceConfigKey key, string? source, int capacity)
Records a stable value-free identity once; never retains unbounded caller text.
Owns one bounded notice history. The manager shares the process instance; isolated instances let tests verify capacity and concurrency without resetting or saturating another host's diagnostic history.
bool TryRemember(string code, string provider, string environment, AppSurfaceConfigKey key, string? source, int capacity)
Admits a previously unseen identity while capacity remains; saturation retains existing identities.
string CreateIdentity(string code, string provider, string environment, AppSurfaceConfigKey key, string? source)
Hashes framed value-free components; logical casing folds while exact source spelling remains distinct.
Tracks the child-node budget shared by one expanded report.
Each context belongs to exactly one report traversal. Do not share an instance across concurrent traversals: the caller owns ordering child reads and consumption so failed member reads do not consume report capacity.
bool TryConsumeNode()
Consumes one report-wide child node when capacity remains.
true
when one child node was consumed; otherwise false
after setting WasTruncated
because the shared report-wide capacity is exhausted.
bool WasTruncated { get; set; }
Source
Gets a value indicating whether the global budget stopped a child from being created.
bool HasRemainingCapacity { get; }
Source
Gets a value indicating whether a member read may still produce a child node.
When capacity is exhausted, this property returns false
and sets WasTruncated
so the report can explain why traversal stopped. It does not consume capacity.
Produces structured configuration audit reports.
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.
ConfigAuditReport GetReport(string environment)
Builds a configuration audit report for environment
.
environment
The completed audit report.
For roots containing Secret{T}
, this is an effective audit: it executes the shared composition engine and therefore may perform the same file, network, IAM, provider, and latency-affecting reads as runtime composition. No public compile-only preflight is exposed; callers requiring zero provider I/O should not use effective audit.
ConfigAuditReport GetReport(ConfigAuditReportRequest request)
Builds a configuration audit report using an explicit request.
request
The completed audit report.
ArgumentNullException
request
is null
.NotSupportedException
The default implementation preserves source and runtime compatibility for existing reporters: default mode delegates to GetReport(string)
, while expansion fails closed until the reporter chooses how to preserve its own redaction and traversal contract.
Default implementation that mirrors configuration resolution while preserving source and diagnostic metadata.
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.
ConfigAuditDiagnostic CreateNoticeDiagnostic(ConfigProviderNotice notice, string key, string provider)
Renders explicit notices without retaining the resolved value or hashing provider prose.
Captures a provider's value resolution result before wrapper inspection and redaction.
Key
State
Value
null
when missing or invalid.Sources
Diagnostics
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 ConfigValueResolution.Missing(AppSurfaceConfigKey)
.
ConfigValueResolution Missing(AppSurfaceConfigKey key)
Creates a missing resolution with a synthetic missing source record for key
.
key
A missing resolution that can still be rendered with provenance.
IReadOnlyList<ConfigAuditSourceRecord> AuditSources { get; init; }
Source
Gets the sources used for child-entry source selection.
ConfigAuditFactContext AuditFacts { get; init; }
Source
Gets internal provenance facts used to attach proof-limited diagnostics while traversing child entries.
ConfigCompositionRootState? CompositionState { get; init; }
Source
Gets the composition outcome when this entry was executed by the shared engine.
IReadOnlyList<ConfigSecretSlotTrace> SecretSlots { get; init; }
Source
Gets the value-free secret slot trace produced by the shared engine.
Describes the result of tracing environment patches onto an existing provider value.
Patched
Value
Sources
Diagnostics
IReadOnlyList<ConfigPatchProvenanceFact> Facts { get; init; }
Source
Gets internal patch-time provenance facts for child audit diagnostics.
Describes one environment patch fact before it is converted into public audit diagnostics.
ConfigPath
Source
Action
PriorPresence
Indexes internal audit provenance facts by source-style config path for traversal.
IReadOnlyList<ConfigPatchProvenanceFact> GetFacts(AppSurfaceConfigKey configPath)
Gets all facts associated with configPath
.
configPath
Facts for the path, or an empty list when none are known.
ConfigAuditFactContext Empty { get; }
Source
Gets the shared immutable empty fact context for callers that have no provenance facts to report.
Use this instance to avoid allocations when traversal should emit no fact-derived child diagnostics. The context contains no path entries and is never modified after construction.
Describes wrapper inspection after provider resolution.
Value
State
null
to keep provider state.DefaultSource
Diagnostics
Allows providers to expose audit-specific resolution details and report-level diagnostics.
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.
ConfigValueResolution Resolve(ConfigProviderRequest request, Type valueType, ConfigAuditSourceRole role)
Resolves the request's logical key for audit reporting without losing source metadata.
request
valueType
role
The provider-specific resolution result.
IReadOnlyList<ConfigAuditDiagnostic> GetReportDiagnostics(string environment)
Gets diagnostics that apply to the whole report rather than one key.
environment
Report-level diagnostics. Return an empty list when there are none.
Allows providers to expose their effective keys for audit reporting.
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.
IReadOnlyList<ConfigAuditProviderDiscoveredKey> EnumerateKeys(string environment)
Enumerates effective provider-discovered configuration keys for environment
.
environment
Discovered provider keys with redaction-ready scalar values and source metadata.
Describes one provider-discovered key before public classification and redaction.
LogicalKey
RawValue
null
for object/array parents. ValueKind
Sources
Diagnostics
Carries the discovered-value display decision used while projecting provider-discovered keys.
DisplayValue
null
when the value is omitted.IsRedacted
DisplayState
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.
Allows an override provider to trace member-level patches onto a base provider value.
The environment provider uses this to explain mixed provenance for object values without mutating the provider instance that supplied the base value.
ConfigPatchDiagnosticResult TracePatch(ConfigProviderRequest request, object? currentValue, Type valueType)
Traces patch candidates for request
and returns a cloned patched value when possible.
request
currentValue
valueType
The patch result, including successful patch sources and diagnostics.
Allows config wrappers to add defaults and validation diagnostics to an audit entry.
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.
ConfigWrapperInspection Inspect(AppSurfaceConfigKey key, object? rawValue, ConfigAuditEntryState resolutionState)
Inspects a resolved value for defaults and validation.
key
rawValue
null
when missing.resolutionState
The wrapper inspection result.
One validated occurrence with its copy-owned document bytes and original token coordinates.
Key
SourceSpelling
Shape
Bytes
ValueStart
ValueLength
Location
ScalarValue
Projects one JSON document directly from its UTF-8 token stream.
ConfigFileTokenProjection Parse(ReadOnlySpan<byte> input)
Captures and projects one document without discarding duplicate evidence in a DOM parser.
input
The complete projection, including invalid subtrees that poison valid ancestors.
JsonException
bool RecordEntry(IReadOnlyList<string> path, byte[] bytes, int[] starts, int start, int end, int locator, ConfigFileValueShape shape, object? scalar, Dictionary<AppSurfaceConfigKey, ConfigFileProjectedEntry> entries, List<ConfigFileProjectedEntry> occurrences, HashSet<AppSurfaceConfigKey> terminals, HashSet<AppSurfaceConfigKey> invalidKeys, Dictionary<string, ConfigAuditSourceLocation?> locations)
Retains duplicate occurrences before lookup can erase them; only unique valid nodes enter the bound tree.
IReadOnlyDictionary<AppSurfaceConfigKey, ConfigFileProjectedEntry> Entries { get; }
Source
Gets the first occurrence per identity; callers must check terminal domains before selecting values.
IReadOnlyList<ConfigFileProjectedEntry> Occurrences { get; }
Source
Gets every valid occurrence, including duplicates needed for cross-layer collision validation.
IReadOnlySet<AppSurfaceConfigKey> TerminalKeys { get; }
Source
Gets ambiguous or unrepresentable keys and their affected aggregate ancestors.
IReadOnlySet<AppSurfaceConfigKey> InvalidKeys { get; }
Source
Gets terminal domains caused specifically by an invalid source segment.
ConfigFileSourceLocationMap Locations { get; }
Source
Gets exact token coordinates, with terminal locations suppressed.
JsonObject MaterializedRoot { get; }
Source
Gets the tree materialized from these same tokens; terminal paths are never safe lookup results.
bool HasInvalidRootProperties { get; }
Source
Gets whether one or more root properties could not be represented as logical keys.
Shared typed ancestry for poisoning a file key and each containing aggregate.
IEnumerable<AppSurfaceConfigKey> AncestorsAndSelf(this AppSurfaceConfigKey key)
Enumerates ancestors from the root segment through the complete key.
key
Case-preserving typed ancestors, including the key itself.
Renders ConfigAuditDiffReport
instances as deterministic, human-readable text.
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.
string Render(ConfigAuditDiffReport report)
Renders a config audit diff report.
report
A deterministic text report.
Requires a strongly typed configuration wrapper to resolve a value during initialization.
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.
Runs command-framework-agnostic config audit diff workflows.
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.
ConfigAuditDiffCommandResult Run(string baselineEnvironment, string targetEnvironment, TextWriter output, ConfigAuditDiffOptions? options = null)
Compares two named environments by asking the current host's reporter for both reports.
baselineEnvironment
targetEnvironment
output
options
A command-runner result describing success or display-safe failure details.
This workflow is convenient for operator triage, but it reuses the already-built host and should not be treated as proof that two deployed hosts have identical provider inputs. Prefer RunCapturedSnapshots
for support evidence collected from each environment.
ConfigAuditDiffCommandResult RunCapturedSnapshots(string baselineSnapshotJson, string targetSnapshotJson, TextWriter output, ConfigAuditDiffOptions? options = null, JsonSerializerOptions? jsonOptions = null)
Compares two captured JSON audit report snapshots.
baselineSnapshotJson
targetSnapshotJson
output
options
null
.jsonOptions
A command-runner result describing success or display-safe failure details.
Captured snapshots are a consumer-owned v1 workflow. Capture each sanitized ConfigAuditReport
from the host it describes, store it according to your support-bundle policy, and pass the JSON snapshots here when a command wrapper wants stronger evidence than same-host named-environment comparison.
A value-safe failure at one canonical destination or at the root plan.
Instances come from the framework diagnostic catalog. They cannot retain a payload, resource key, version, provider exception, or serialized application object.
string Path { get; }
Source
The canonical colon-delimited destination.
string Code { get; }
Source
A stable framework code.
string? ProviderId { get; }
Source
A validated provider id, when relevant.
bool Retryable { get; }
Source
Whether a later attempt may repair a transient failure.
ConfigAuditSourceRecord? Source { get; }
Source
A safe declaration location, never the descriptor or resource identity.
string? RelatedPath { get; }
Source
The other canonical destination in a path or environment-alias conflict.
string? EnvironmentVariableName { get; }
Source
The colliding environment variable name; never its value.
string Problem { get; }
Source
The operator-facing problem.
string Cause { get; }
Source
The framework-classified cause.
string Fix { get; }
Source
The suggested corrective action.
string Docs { get; }
Source
The canonical diagnostic reference.
Reports every unresolved failure in an opted-in root, without changing legacy resolution exceptions.
Failures are ordered by canonical path, code and provider id. No provider exception is retained as an inner exception. Exact valid environment values can rescue runtime slot failures, but cannot rescue plan errors.
string EnvironmentName { get; }
Source
The requested environment.
string RootKey { get; }
Source
The requested root key.
IReadOnlyList<ConfigCompositionFailure> Failures { get; }
Source
The immutable ordered failure snapshot.
One safe problem/cause/fix catalog used by runtime, audit and documentation checks.
(string Problem, string Cause, string Fix, string Anchor) Describe(string code)
Returns framework text and the canonical guide anchor for a stable code.
Copies public values into normally constructed objects while isolating every mutable member.
Getter-only aggregates are populated through their existing public members and collection methods. A getter must not expose the source's mutable storage; readonly state must survive public construction unchanged. Cycles, excessive depth, and aggregates that cannot be isolated fail the whole transaction. No compiler-generated fields or private accessors are inspected or rewritten.
object Copy(object source, Type type)
Copies a root using its runtime type and public construction/serialization contracts.
Signals an isolation failure without retaining the input value or a raw exception.
Resolves environment values and isolated child patches from one operation snapshot.
Canonical and compatibility candidates use the same source projection for values and audit evidence. Native claims are checked before reading values. Getter-only aggregates are copied through their public members into isolated constructor-created objects. If public construction cannot retain read-only state, the entire patch is terminal; private fields and serialization are never used to silently discard that state. Getter-only structs cannot publish child writes. Missing effective descendants do not trigger construction or getter invocation.
T? GetValue<T>(string environment, string key)
Strict compatibility helper; typed requests have no historical aliases.
IReadOnlyList<ConfigProviderAuditDiscoveredKey> EnumerateKeys(string environment)
Inventories only declared and explicitly mapped keys, never arbitrary process variables.
IReadOnlyList<ConfigProviderAuditDiscoveredKey> EnumerateKeys(string environment, ConfigResolutionScope scope)
Inventories forward declarations using the audit report's existing immutable snapshot.
IEnumerable<string> PresentChildren(ConfigProviderRequest request, ConfigEnvironmentSnapshot snapshot, NativeCandidate[] candidates, AppSurfaceConfigKey key)
Finds present child segments through native prefixes and the frozen forward mapping index.
Mapped descendants can live outside every parent native prefix; their exact suffix still replaces all child conventions.
Encodes logical keys and generates the bounded train-1 environment aliases.
string Encode(AppSurfaceConfigKey key)
Encodes portable ASCII segments with double underscores only at logical boundaries.
bool TryEncode(AppSurfaceConfigKey key, out string encoded)
Reports convention representability without rewriting literal separators or Unicode.
string EncodeSegment(string segment)
Encodes one literal segment, rejecting edge/double underscores and unsupported characters.
IEnumerable<(string Layer, string Name, bool Legacy)> Candidates(ConfigProviderRequest request, IReadOnlyDictionary<AppSurfaceConfigKey, string> mappings)
Returns exact unique native candidates and their scope domains using the approved train-1 table.
Typed requests have no aliases. Explicit mappings replace all convention candidates.
ImmutableArray<EnvironmentNativeCandidate> GetCandidates(string environment, AppSurfaceConfigKey key, ConfigKeyInputOrigin inputOrigin, string? originalInput, IReadOnlyDictionary<AppSurfaceConfigKey, string> mappings)
Materializes native names with producer metadata without resolving values or claims.
environment
key
inputOrigin
originalInput
mappings
Immutable scoped/unscoped canonical or mapped names, followed by distinct aliases.
InvalidOperationException
Mapping replacement and strict/translated compatibility aliases retain resolver precedence.
string EncodeEnvironment(string environment)
Retains the existing environment-name normalization independently of logical-key grammar.
Represents a display-safe terminal configuration resolution failure.
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. The public constructor uses the compatible 256-character identifier limit. Managers use their snapshotted ConfigResourceOptions.MaxRenderedIdentifierCharacters
value for both Exception.Message
and Exception.ToString()
; the structured identity properties retain their full values.
string EnvironmentName { get; }
Source
Gets the environment being resolved.
string Key { get; }
Source
Gets the configuration key being resolved.
AppSurfaceConfigKey LogicalKey { get; }
Source
Gets the parsed identity that failed resolution.
string ProviderName { get; }
Source
Gets the provider that stopped lower-priority resolution.
ConfigProviderTerminalDiagnostic Diagnostic { get; }
Source
Gets the display-safe terminal diagnostic.
Allows external providers to expose effective keys for configuration audit inventory.
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.
IReadOnlyList<ConfigProviderAuditDiscoveredKey> EnumerateKeys(string environment)
Enumerates effective provider keys for environment
.
environment
Discovered keys with typed logical identity, redaction-ready values, and source metadata.
Orchestrates one parsed identity and one environment snapshot through ordered sources and patching.
ConfigPatchResult<T> Patch<T>(IConfigValuePatcher patcher, ConfigProviderRequest request, T? value)
Contains unexpected patch failures without retaining raw exception text or publishing a partial value.
void EmitNotice(ConfigProviderRequest request, string provider, ConfigProviderNotice notice)
Logs a committed notice once without recollecting notices already published by an environment patch.
Shares descriptor ownership and attributed metadata rules between explicit selection and discovery.
Registration inspects the current collection without mutable selection markers or provider probes. Expected shape, compatibility, conflict, and metadata failures precede helper additions. This is not transactional rollback for a custom collection's Add failure or a catastrophic allocation failure.
void Register(IServiceCollection services, Type configType)
Prepares and registers a selected wrapper without activation or logical-key parsing.
services
configType
ArgumentNullException
ArgumentException
AppSurfacePackageCompatibilityException
InvalidOperationException
The compatibility guard precedes constructor and traversal reflection; discovery also guards before DefinedTypes. CLR type loading before this call is outside that guard. One caller singleton is preserved without framework Init. Known unkeyed attributed instance declarations deduplicate by wrapper type and declaration kind; manual declarations and opaque factories remain independent. Invalid traversal limits are copied for the existing audit diagnostic/fallback boundary. No public enclosing-type visibility is required.
Describes the environment and explicit mode for one configuration audit report.
The default mode preserves the canonical report returned by IConfigAuditReporter.GetReport(string)
. ConfigAuditReportMode.ExpandKnownEntryCollections
is an opt-in diagnostic mode: built-in reporting expands only already-known entry collections and retains the normal redaction and traversal limits. Custom reporters can continue to support only the default mode until they explicitly implement the request overload.
string Environment { get; }
Source
Gets the environment to audit.
ConfigAuditReportMode Mode { get; }
Source
Gets the explicit report mode.
Describes the resolved configuration state for an AppSurface environment.
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.
string Environment { get; init; }
Source
Gets the environment this report describes.
DateTimeOffset GeneratedAt { get; init; }
Source
Gets the time when this report was generated.
ConfigAuditReportMode? Mode { get; init; }
Source
Gets the explicit mode used to produce this report, when it differs from the canonical default.
Canonical reports leave this property null
so existing JSON contracts do not gain a member. Expanded reports identify ConfigAuditReportMode.ExpandKnownEntryCollections
so copied support artifacts remain distinguishable from the default report.
IReadOnlyList<ConfigAuditProvider> Providers { get; init; }
Source
Gets the provider precedence used while producing this report.
IReadOnlyList<ConfigAuditEntry> Entries { get; init; }
Source
Gets the known configuration entries resolved for this environment.
IReadOnlyList<ConfigAuditDiscoveredKey> DiscoveredKeys { get; init; }
Source
Gets effective configuration keys discovered directly from enumerable providers.
Discovered keys describe the effective merged configuration visible to AppSurface providers that implement audit enumeration. They are not a complete raw inventory: providers that cannot enumerate keys are omitted, shadowed lower-priority file keys are not included, and environment variables or secret providers are not enumerated by the built-in v1 surface. ConfigAuditDiscoveredKey.DisplayValue
is redacted or omitted before it enters the public report, but source metadata such as file paths, provider names, and config paths may still be support-sensitive.
IReadOnlyList<ConfigAuditDiagnostic> Diagnostics { get; init; }
Source
Gets report-level diagnostics that are not tied to a single entry.
ConfigAuditRedaction Redaction { get; init; }
Source
Gets the redaction policy applied before this report was returned.
Describes one effective provider-discovered configuration key in an audit report.
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.
string Key { get; init; }
Source
Gets the discovered configuration key path.
ConfigAuditDiscoveredKeyClassification Classification { get; init; }
Source
Gets the key's relationship to the AppSurface audit registry.
string? DisplayValue { get; init; }
Source
Gets the display-safe value, or null
when a non-sensitive value is omitted.
Exact registered scalar keys can include a display value. Non-sensitive object and array parent values are omitted instead of serialized, and non-sensitive provider-discovered inventory values that are not exact audit entries are omitted by default. Use ValueDisplayState
instead of testing this property for null
when consuming structured reports.
bool IsRedacted { get; init; }
Source
Gets a value indicating whether DisplayValue
was replaced by the redaction placeholder.
ConfigAuditDiscoveredValueDisplayState ValueDisplayState { get; init; }
Source
Gets the display decision applied to DisplayValue
for this discovered key.
This state explains how the public report rendered the discovered value. It is not a sensitivity label and does not prove whether a value is secret or safe outside the current report context. The default ConfigAuditDiscoveredValueDisplayState.Unspecified
preserves compatibility for reports manually constructed before this property existed; reporter-produced instances always set an explicit state.
IReadOnlyList<ConfigAuditSourceRecord> Sources { get; init; }
Source
Gets source records associated with this effective discovered key.
IReadOnlyList<ConfigAuditDiagnostic> Diagnostics { get; init; }
Source
Gets diagnostics specific to this discovered key.
Describes one provider in the audit report precedence list.
Precedence
is the display order used by audit reports. Environment providers are marked as overrides because they are checked before normal priority-ordered providers.
string Name { get; init; }
Source
Gets the provider name.
int Priority { get; init; }
Source
Gets the provider priority.
int Precedence { get; init; }
Source
Gets the precedence rank used by the configuration manager. Lower ranks are checked first.
bool IsOverride { get; init; }
Source
Gets a value indicating whether the manager treats this provider as an override outside normal priority order.
Describes one known configuration entry and its source records.
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.
string Key { get; init; }
Source
Gets the configuration key.
string? ConfigPath { get; init; }
Source
Gets the colon-delimited logical source path when it can be disclosed independently of the display label.
The reporter sets this from typed logical segments. Diff consumers parse it with strict AppSurfaceConfigKey
grammar instead of interpreting dots or brackets in Key
. It is null for paths containing redacted dictionary identifiers and may be absent from older captured reports. Dictionary comparison uses the safe correlation metadata in Element
when available.
string? DeclaredType { get; init; }
Source
Gets the declared value type name when known.
ConfigAuditEntryState State { get; init; }
Source
Gets the resolved entry state.
string? DisplayValue { get; init; }
Source
Gets the display-safe value. Sensitive values are already redacted, and collection parent values may be omitted so nested element data cannot leak through a serialized dump.
bool IsRedacted { get; init; }
Source
Gets a value indicating whether DisplayValue
was redacted.
ConfigAuditElementIdentity? Element { get; init; }
Source
Gets collection element identity when this entry represents an array/list item or dictionary item.
Element labels are already display-safe. Sensitive dictionary keys are replaced before the report object is created, so callers must not expect ConfigAuditElementIdentity.KeyLabel
to be reversible.
IReadOnlyList<ConfigAuditSourceRecord> Sources { get; init; }
Source
Gets the source records that contributed to this entry.
IReadOnlyList<ConfigAuditEntry> Children { get; init; }
Source
Gets child entries for object-valued configuration.
IReadOnlyList<ConfigAuditDiagnostic> Diagnostics { get; init; }
Source
Gets diagnostics specific to this entry.
Describes a source coordinate inside a configuration file.
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.
int LineNumber { get; }
Source
Gets the one-based physical line number containing the source token.
int ByteColumnNumber { get; }
Source
Gets the one-based UTF-8 byte column containing the source token.
This is a byte coordinate over the UTF-8 file content, not a Unicode scalar, text element, or editor display column. A non-ASCII character earlier on the same line can increase this value by more than one.
Describes the collection element represented by a child audit entry.
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.
ConfigAuditElementKind Kind { get; init; }
Source
Gets the collection element kind.
int? Index { get; init; }
Source
Gets the zero-based array or list index, when applicable.
string? KeyLabel { get; init; }
Source
Gets the display-safe dictionary key label, when applicable.
bool IsKeyRedacted { get; init; }
Source
Gets a value indicating whether the original dictionary key was redacted or intentionally hidden.
string? KeyCorrelationId { get; init; }
Source
Gets the opt-in opaque identifier for correlating the same dictionary key across reports.
This value is populated only when entry options enable dictionary key correlation and global correlation key material is valid. It includes the report environment in its derivation, is not reversible, is not part of the display path, and should still be treated as sensitive support metadata because it reveals equality and churn across reports from the same environment.
string? ComparisonKeyCorrelationId { get; init; }
Source
Gets the opt-in opaque identifier for matching the same dictionary key across compared environments.
This value is populated only when entry options enable dictionary key correlation and global correlation key material is valid. Unlike KeyCorrelationId
, the environment name is deliberately omitted from the derivation so ConfigAuditReportDiffer
can match captured staging and production reports without trusting report-local redacted labels. It is not reversible and should still be treated as support-sensitive equality metadata.
Describes one source that contributed to a configuration entry.
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.
ConfigAuditSourceKind Kind { get; init; }
Source
Gets the source kind.
string? ProviderName { get; init; }
Source
Gets the provider name when applicable.
int? ProviderPriority { get; init; }
Source
Gets the provider priority when applicable.
string? FilePath { get; init; }
Source
Gets the file path for file-sourced values.
string? EnvironmentVariableName { get; init; }
Source
Gets the environment variable name for environment-sourced values.
string? ConfigPath { get; init; }
Source
Gets the source config path.
string? AppliedToPath { get; init; }
Source
Gets the target config path affected by this source.
ConfigAuditSourceLocation? Location { get; init; }
Source
Gets the exact file coordinate for this source when the provider can prove one.
A null
value means the source is still known but no truthful coordinate is available, such as for non-file sources, ambiguous case-insensitive file paths, unsupported paths, parser mismatches, or collection element descendants.
ConfigAuditSourceRole Role { get; init; }
Source
Gets the role this source played in resolution.
ConfigAuditSensitivity Sensitivity { get; init; }
Source
Gets the sensitivity classification supplied by the source.
Describes a diagnostic emitted while building a configuration audit report.
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.
ConfigAuditDiagnosticSeverity Severity { get; init; }
Source
Gets the diagnostic severity.
string Code { get; init; }
Source
Gets a stable diagnostic code.
string Message { get; init; }
Source
Gets the display-safe diagnostic message.
string? Key { get; init; }
Source
Gets the configuration key associated with the diagnostic, when any.
string? ConfigPath { get; init; }
Source
Gets the member/config path associated with the diagnostic, when any.
ConfigAuditSourceRecord? Source { get; init; }
Source
Gets the source associated with the diagnostic, when any.
Describes the redaction policy applied to a configuration audit report.
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.
bool Enabled { get; init; }
Source
Gets a value indicating whether redaction was enabled.
IReadOnlyList<string> MatchedFragments { get; init; }
Source
Gets the sensitive fragments matched by the built-in redactor.
string Placeholder { get; init; }
Source
Gets the display placeholder used for redacted values.
ConfigAuditDictionaryKeyCorrelationMode DictionaryKeyCorrelationMode { get; init; }
Source
Gets the configured dictionary key correlation mode for the report.
string? DictionaryKeyCorrelationKeyId { get; init; }
Source
Gets the display-safe correlation key id when configured.
string? DictionaryKeyCorrelationApplicationScope { get; init; }
Source
Gets the configured application or product scope when configured.
Bounds untrusted configuration inputs and retained diagnostic identities.
All limits must be positive. Exceeding a limit is terminal; no partial source is published.
ConfigResourceOptions Snapshot()
Validates and snapshots limits before any provider publishes its indexes.
long MaxFileBytes { get; set; }
Source
Gets or sets maximum bytes per JSON file layer; defaults to 16 MiB.
int MaxFilesPerEnvironment { get; set; }
Source
Gets or sets maximum files per environment; defaults to 256.
int MaxEnvironmentEntries { get; set; }
Source
Gets or sets maximum captured environment entries; defaults to 65,536.
long MaxEnvironmentBytes { get; set; }
Source
Gets or sets maximum UTF-8 bytes in environment names and values; defaults to 64 MiB.
int MaxNoticeIdentities { get; set; }
Source
Gets or sets maximum distinct notice identities per operation and in process log suppression; defaults to 4,096.
Operation overflow marks audit notice evidence incomplete; duplicate identities do not consume capacity.
int MaxRenderedIdentifierCharacters { get; set; }
Source
Gets or sets maximum rendered identifier characters before a digest; defaults to 256.
int MaxBindingDepth { get; set; }
Source
Gets or sets the maximum object binding depth; defaults to 32.
TimeSpan AuditTimeout { get; set; }
Source
Gets or sets the aggregate remote-audit deadline; defaults to 30 seconds and is capped at uint.MaxValue - 1 milliseconds.
The upper bound keeps the deadline representable by the timer APIs used for cancellation.
int MaxAuditRemoteLookups { get; set; }
Source
Gets or sets the maximum uncached remote lookups in one audit; defaults to 256.
int MaxAuditConcurrency { get; set; }
Source
Gets or sets the maximum concurrent remote lookups in one audit; defaults to four.
A whole-root provider capability that returns text before application-object binding.
Alias this interface to the same singleton as IConfigProvider
. Whole roots remain priority-ordered alternatives, never deep-merged peers. See provider compatibility
.
ConfigCompositionValueResolution ResolveRaw(string environment, string logicalKey)
Resolves one raw root with provenance, preserving missing and terminal behavior.
Lets a typed-only legacy provider locally prove an opted-in root is unrelated.
ConfigProviderClaim InspectClaim(string environment, string logicalKey)
Inspects ownership without I/O. Unclaimed providers can be safely excluded from composition.
Value-safe raw resolution. Found JSON null is a resolved contribution, not absence.
string? ReadRaw()
Reads transient raw text only inside core composition.
ConfigCompositionValueResolution Unclaimed(string providerName, int priority, bool isSensitive = false)
Returns an unclaimed root without payload storage.
ConfigCompositionValueResolution Missing(string providerName, int priority, bool isSensitive = false)
Returns a missing root without payload storage.
ConfigCompositionValueResolution Resolved(string raw, string providerName, int priority, bool isSensitive)
Returns found raw text; pass "null" to represent a found JSON null.
ConfigCompositionValueResolution TerminalFailure(string providerName, int priority, bool isSensitive = true, bool retryable = false)
Stops lower-root fallback without retaining arbitrary provider text.
ConfigCompositionValueResolutionStatus Status { get; }
Source
The whole-root outcome.
string ProviderName { get; }
Source
The existing provider name, not an external resource identifier.
int Priority { get; }
Source
The existing whole-root priority.
bool IsSensitive { get; }
Source
Whether scalars from this source may supply secret destinations.
bool Retryable { get; }
Source
Whether a terminal failure may be transient.
Freezes native mappings and claim capacity once for a service container.
Read finalized IOptions.Value before calling this constructor. Host callbacks remain outside framework validation handling. Direct provider construction creates an isolated snapshot through this same path.
FrozenDictionary<AppSurfaceConfigKey, string> Mappings { get; }
Source
Gets the immutable exact-key suffix replacements.
int MaxAdHocClaims { get; }
Source
Gets the validated native provider claim capacity captured with the mappings.
Caches value-free default JSON metadata and creates separate invocation-owned binding options.
bool ContainsSecrets(Type type)
Detects opt-in even when a custom converter hides the graph from JSON metadata.
bool IsSecret(Type type)
Tests the exact wrapper definition without inspecting its payload.
ConfigCompositionShape GetShape(Type type)
Gets cached structural destinations. The shape contains neither source declarations nor payloads.
object? Bind(Type type, JsonObject buffer, IReadOnlyList<IConfigSecretValue> slots)
Binds opaque slot ids once with a context that is cleared on both success and failure.
IConfigSecretValue CreateSecret(Type innerType, bool enabled, object? value, string? provider)
Constructs a typed wrapper without exposing a public value-bearing factory.
Creates only execution-local converters; never enters structural caches.
Reads an already-classified wrapper by opaque id and never accepts a descriptor or payload.
A cached value-free root shape.
A scalar secret's relative serialized path and types.
An ordinary bindable member used for final environment composition.
A structural no-I/O failure, relative to its requested root.
Runs the app-owned configuration diagnostics command workflow for the active AppSurface environment.
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. Effective audits of roots containing Secret{T}
execute the shared composition engine and can therefore perform the same file, network, IAM, provider, and latency- affecting reads as runtime composition. No public compile-only preflight is exposed; callers requiring zero provider I/O should not run effective diagnostics.
ConfigDiagnosticsCommandResult Run(TextWriter output)
Writes the active environment's configuration audit report to output
.
output
A result whose ConfigDiagnosticsCommandResult.ExitCode
is zero when the report was generated. Missing or invalid configuration entries remain successful inspection results.
Non-fatal runtime failures are converted to display-safe failure details. Raw exception messages are not exposed because provider and validation exceptions can contain attempted secret values or environment-specific paths.
ConfigDiagnosticsCommandResult Run(TextWriter output, ConfigAuditReportMode mode)
Writes the active environment's configuration audit report to output
.
output
mode
A result whose ConfigDiagnosticsCommandResult.ExitCode
is zero when the report was generated.
Default mode intentionally preserves the pre-existing IConfigAuditReporter.GetReport(string)
flow so existing custom reporters still function unchanged. Expanded report modes use explicit request-based reporting.
Configures explicit native environment names for logical configuration keys.
Mappings are exact suffix replacements in both scoped and unscoped layers. The suffix is deliberately narrower than a logical segment so the environment codec remains injective and collision checks remain deterministic. Configure these options before building or resolving the host. The first built-in provider or IEnvironmentConfigCandidateInspector
resolution freezes one snapshot shared by both in that container; subsequent mutations do not change either consumer. Direct provider construction uses an isolated snapshot. Canonical and historical aliases are both replaced by a mapping. The replacement also applies when resolving a member through its aggregate: MapKey("App:Name", "CUSTOM_NAME") binds App.Name from CUSTOM_NAME or its scoped form, even when no APP__ prefix is present. APP__NAME is ignored.
AppSurfaceEnvironmentConfigOptions MapKey(AppSurfaceConfigKey logicalKey, string nativeSuffix)
Maps a typed logical key to an exact native suffix.
logicalKey
nativeSuffix
This builder, for chained registrations.
For example, Payments_ApiKey produces Production's scoped name PRODUCTION__Payments_ApiKey and the unscoped name Payments_ApiKey. Casing is preserved and required at lookup. Duplicates and reverse claims are validated when options and finalized declarations are frozen; equal values never make a collision valid.
AppSurfaceEnvironmentConfigOptions MapKey(string logicalKey, string nativeSuffix)
Maps a strict logical key string to an exact native suffix.
logicalKey
nativeSuffix
This builder, for chained registrations.
FrozenDictionary<AppSurfaceConfigKey, string> Snapshot()
Validates the complete registration set and returns an immutable forward mapping.
void ValidateSuffix(string suffix)
Rejects suffixes that could collapse a native hierarchy or require lossy spelling conversion.
int MaxAdHocClaims { get; set; }
Source
Gets or sets the maximum distinct environment/key reverse claims retained by one provider; defaults to 4,096.
Must be positive. A new claim beyond this capacity fails closed; existing claims remain usable.
Describes one validation failure found while initializing a strongly typed configuration value.
string Key { get; }
Source
Gets the configuration key being initialized.
Type ConfigType { get; }
Source
Gets the concrete configuration wrapper type being initialized.
Type ValueType { get; }
Source
Gets the resolved value type that was validated.
IReadOnlyList<string> MemberNames { get; }
Source
Gets the member names or paths associated with the failure. Object-level failures use an empty list rather than null; consumers should treat that empty collection as a valid failure payload. The returned list is an immutable snapshot owned by this instance.
string Message { get; }
Source
Gets the validation message.
Represents a scalar secret destination with independent activation and availability.
T
ConfigValueConverter
.
Declare this type on a configuration member to opt its containing root into file secret composition. The public constructor creates an empty destination. Only configuration resolution supplies values or disables references. A required wrapper does not imply a value exists; check HasValue
in application validation. See the secret reference guide
. Default JSON serialization and formatting omit the payload. Application access, third-party serializers and inspection of private process memory are outside that guarantee.
bool TryGetValue(out T value)
Reads the sensitive value without throwing when the destination is empty.
value
Whether a non-null effective value exists.
string ToString()
Formats activation, availability and source only; never formats the payload.
bool Enabled { get; }
Source
Whether the declared reference is active; this does not activate an application feature.
bool HasValue { get; }
Source
Whether a non-null effective value exists, including an empty string when accepted.
T Value { get; }
Source
Gets the sensitive value. Never log or serialize the returned value.
InvalidOperationException
string? ResolvedProvider { get; }
Source
Gets the canonical secret-provider id or the name of the effective base/environment provider.
Exposes only opaque state to framework traversal without a payload getter.
bool Enabled { get; }
Source
Whether the reference is active.
bool HasValue { get; }
Source
Whether a value is present.
string? ResolvedProvider { get; }
Source
The effective source identity.
Renders ConfigAuditReport
instances as deterministic, human-readable text.
string Render(ConfigAuditReport report)
Renders report
as text.
report
A human-readable report.
Defines a configuration provider that also provides environment information.
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.
Describes a display-safe failure from ConfigAuditDiffCommandRunner
.
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.
string ToDisplayString()
Formats this failure for command-line display.
A display-safe multiline failure message.
ConfigAuditDiffFailureStage Stage { get; }
Source
Gets the failure stage.
string Problem { get; }
Source
Gets the operator-facing problem summary.
string Cause { get; }
Source
Gets the display-safe cause summary.
string Fix { get; }
Source
Gets the suggested next action.
string DocsLink { get; }
Source
Gets the documentation link for this workflow.
string? ExceptionType { get; }
Source
Gets the exception type that caused the failure, when available.
A base class for strongly-typed configuration objects where the value is a struct. Values are resolved during IConfig.Init
, then object-valued configuration models are validated with DataAnnotations and scalar values can be validated with AppSurface scalar attributes or ValidateValue
. Invalid provider values and invalid defaults fail fast by throwing ConfigurationValidationException
, so callers that activate config wrappers can catch that exception and surface its structured failures. Ensure defaults satisfy the same validation rules as configured values; an invalid default prevents initialization when no provider value exists. Apply ConfigKeyRequiredAttribute
to require resolved provider/default presence.
T
void IConfig.Init(IConfigManager configManager, IEnvironmentProvider environmentProvider, AppSurfaceConfigKey key)
Resolves the configured value for key
and validates the resolved provider value or DefaultValue
before initialization completes.
configManager
environmentProvider
key
ConfigurationValidationException
IEnumerable<ValidationResult>? ValidateValue(T value, ValidationContext validationContext)
Validates a resolved non-null scalar configuration value. Override this method when a scalar rule is too specific for the built-in AppSurface scalar attributes.
value
validationContext
The validation results for value
. Return null
, an empty sequence, ValidationResult.Success
, or null entries when validation succeeds.
ConfigWrapperInspection Inspect(AppSurfaceConfigKey key, object? rawValue, ConfigAuditEntryState resolutionState)
Inspects a resolved value using its typed logical key.
bool HasValue { get; set; }
Source
Gets a value indicating whether the configuration has a value.
bool IsDefaultValue { get; set; }
Source
Gets a value indicating whether the current value is the default value.
T? Value { get; set; }
Source
Gets the configuration value.
T? DefaultValue { get; }
Source
Gets the default value for the configuration if none is found in the source.
Describes one native environment variable name.
Name
Scope
IsLegacyAlias
IsExplicitMapping
Immutable ordered native environment-name candidates for a logical key.
Key
Candidates
Constructor and with
assignments copy the candidate collection. Plain record copies share only immutable state. Names do not prove variable presence, native ownership, provider acceptance, or successful resolution.
var copy = plan with { Candidates = suppliedCandidates };AppSurfaceConfigKey Key { get; init; }
Source
Gets the inspected logical key.
IReadOnlyList<EnvironmentNativeCandidate> Candidates { get; init; }
Source
Gets an immutable, independently copied candidate list.
Describes one direct composition-path environment name.
Name
Scope
IsHierarchical
Immutable ordered direct composition-path environment-name candidates.
Path
Candidates
Constructor and with
assignments copy the candidate collection. The legacy dotted projection may collapse distinct literal paths to the same names. This plan does not enumerate all descendants or certify source ownership.
var (path, candidates) = plan with { };AppSurfaceConfigKey Path { get; init; }
Source
Gets the inspected literal path.
IReadOnlyList<EnvironmentCompositionPathCandidate> Candidates { get; init; }
Source
Gets an immutable, independently copied candidate list.
Inspects possible environment names without reading or resolving values.
Registered as a singleton by AppSurfaceConfigModule
. Configure mapping options before container construction; the first built-in provider or inspector resolution freezes the shared mappings in that container. Every call materializes immutable results and retains no per-key cache or native claims. Callers own the inventory, comparer, relevant roots/ancestors/member paths and policy; generated names alone certify none of those choices.
var key = AppSurfaceConfigKey.FromSegments("Service", "Api-Key");
var typed = inspector.InspectNativeKey("Production", key);
var strict = inspector.InspectNativeKey("Production", "Service:Api-Key");
var composition = inspector.InspectCompositionPath("Production", key);EnvironmentNativeKeyPlan InspectNativeKey(string environment, AppSurfaceConfigKey key)
Plans native names with typed semantics, ignoring any parser provenance on the key.
environment
key
A materialized scoped-then-unscoped plan with ordinal first-producer metadata.
ArgumentNullException
InvalidOperationException
EnvironmentNativeKeyPlan InspectNativeKey(string environment, string strictInput)
Plans native names using strict parsing and the existing compatibility aliases.
environment
strictInput
Canonical scoped/unscoped names followed by distinct strict aliases, or only the exact mapped pair.
ArgumentNullException
FormatException
InvalidOperationException
EnvironmentCompositionPathPlan InspectCompositionPath(string environment, AppSurfaceConfigKey path)
Plans direct composition names using the legacy dotted projection of literal segments.
environment
path
Distinct scoped flat, unscoped flat, scoped hierarchical, then unscoped hierarchical names.
ArgumentNullException
Defines a configuration object that can be initialized using a configuration manager.
void Init(IConfigManager configManager, IEnvironmentProvider environmentProvider, AppSurfaceConfigKey key)
Initializes the configuration object, resolving its provider or default value and failing fast with ConfigurationValidationException
when required presence is not satisfied or when the resolved value violates object DataAnnotations rules or scalar value validation rules. Exceptions thrown by scalar Config{T}.ValidateValue
or ConfigStruct{T}.ValidateValue
overrides are not wrapped, so callers that activate config wrappers during startup should let unexpected programming errors fail the startup path.
configManager
environmentProvider
key
ConfigurationValidationException
Exception
Describes one external provider-discovered configuration key before public classification and redaction.
Key
RawValue
null
for object or array parents.ValueKind
Sources
Diagnostics
AppSurfaceConfigKey Key { get; init; }
Source
Gets the typed logical configuration key, including its input-origin metadata.
IReadOnlyList<ConfigAuditSourceRecord> Sources { get; init; }
Source
Gets source records associated with the key.
IReadOnlyList<ConfigAuditDiagnostic> Diagnostics { get; init; }
Source
Gets display-safe diagnostics specific to this key.
Validates required resolved presence for strongly typed configuration wrappers.
void Validate(AppSurfaceConfigKey key, Type configType, Type valueType, bool hasValue)
Throws ConfigurationValidationException
when a wrapper marked with ConfigKeyRequiredAttribute
has no resolved provider or default value.
key
configType
valueType
hasValue
One immutable host-local index of all declared configuration identities.
Raw declarations are resolved only after the final service provider exists, so parser options are finalized and wrapper activation is never used to discover keys. Exact canonical duplicates merge metadata. Case-only and legacy/canonical conflicts fail before a wrapper can be activated. The registry remains internal; provider packages share it through friend-assembly access. Public logical identity is the immutable AppSurfaceConfigKey
documented by the logical-key contract
.
ConfigAuditKnownEntry GetForConfigType(Type configType)
Finds the merged entry for each wrapper type, including multiple wrappers sharing one exact key.
configType
The immutable merged entry shared with providers and audit reporting.
InvalidOperationException
IReadOnlyList<ConfigAuditKnownEntry> Entries { get; }
Source
Gets merged immutable entries in deterministic order.
IReadOnlyList<AppSurfaceConfigKey> Keys { get; }
Source
Gets the corresponding immutable typed keys in deterministic order.
Empty options marker that forces the finalized declaration registry to be validated at host startup.
Its validator depends on the immutable registry. The options validation pipeline therefore resolves all deferred declarations before provider traversal or wrapper activation.
Forces the environment provider's finalized declaration and native-mapping validation at startup.
This marker is separate from environment options because the provider consumes those options in its constructor. Depending on the provider while validating its own options would create a circular dependency.
Validates that the finalized host declaration registry can be constructed.
Immutable declaration captured before DI finalization.
RawKey
ConfigType
ValueType
Options
IsAttributeDeclaration
TypedKey
ConfigAuditKnownEntry Resolve(IConfigKeyInputParser parser)
Resolves captured fragments once, or preserves an already typed key and its input provenance.
Validates the default host key policy without depending on the declaration registry.
Its implementation descriptor identifies the framework's startup-validation installation bundle. Other caller validators remain independent. Keeping this validator free of registry dependencies prevents a parser/options cycle.
Immutable per-type public binding metadata; contains no environment state or values.
EnvironmentBindingPlan For(Type type)
Gets one immutable plan, safely shared by concurrent operations.
Type? CollectionElementType(Type type)
Gets the supported sequence element type; dictionaries bind as complete JSON values.
bool IsComplex(Type type)
Gets whether a type supports recursive public-member patching.
object? Create(Type type)
Constructs an ordinary public instance, or reports an unsupported construction path.
object? MaterializeCollection(Type type, Type elementType, IList list)
Builds a supported array or assignable list without invoking private setters.
bool IsMutableList(object? value)
Checks whether public list operations can replace a getter-only collection.
void ReplaceList(IList target, IEnumerable values)
Replaces an isolated mutable list through its public collection contract.
int? CollectionCount(object? value)
Obtains prior collection presence without assuming a concrete implementation.
IReadOnlyList<EnvironmentBindingMember> Members { get; }
Source
Gets non-indexed public properties and fields, including readable aggregates without setters.
One public patchable field/property and its exact native segment.
object? Read(object target)
Reads the member value; returns null when a property has no public getter.
target
The member value, or null when a public property getter is unavailable.
void Write(object target, object? value)
Writes a value through the public field or property setter.
target
value
bool CanWrite { get; }
Source
Gets whether the member can be assigned through its public setter or mutable field.
string NativeName { get; }
Source
Gets the member name normalized to the environment provider's uppercase native form.
Describes the outcome of a configuration diagnostics command runner invocation.
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.
string? Environment { get; }
Source
Gets the active AppSurface environment that was audited, when it was available.
ConfigDiagnosticsCommandFailure? Failure { get; }
Source
Gets the display-safe failure details when diagnostics could not run.
bool Succeeded { get; }
Source
Gets a value indicating whether the report was generated and written.
int ExitCode { get; }
Source
Gets the recommended process exit code for a command wrapper.
An immutable, case-insensitive logical configuration path. Only a colon separates segments.
Equality and hashing use ordinal ignore-case comparison without Unicode normalization. Value
preserves spelling; dots, hyphens, underscores, and slashes are literal. See the logical-key reference
.
AppSurfaceConfigKey Parse(string value)
Parses strict colon syntax; dots always remain literal in this API.
value
A key preserving the supplied spelling.
FormatException
bool TryParse(string? value, out AppSurfaceConfigKey? key)
Attempts strict parsing without trimming, rewriting, or returning partial output.
value
key
Whether every segment satisfies the logical grammar.
AppSurfaceConfigKey FromSegments(params string[] segments)
Constructs a strict key by copying and joining literal segments with colons.
segments
A key independent of later changes to the supplied array.
ArgumentNullException
ArgumentException
bool IsSameOrDescendantOf(AppSurfaceConfigKey prefix)
Tests equality or ancestry using complete segments and ordinal ignore-case comparison.
prefix
True for the prefix itself and its descendants, but not text-prefix siblings.
ArgumentNullException
AppSurfaceConfigKey WithInput(ConfigKeyInputOrigin origin, string? originalInput)
Copies input provenance without changing segments, rendering, equality, or hashing.
bool IsValidSegment(string? segment)
Validates one literal segment without applying boundary encoding or normalization.
string Value { get; }
Source
Gets the colon-delimited path with its original segment spelling.
ImmutableArray<string> Segments { get; }
Source
Gets the immutable literal segments; no caller-owned array is retained.
ConfigKeyInputOrigin InputOrigin { get; }
Source
Gets parser provenance, excluded from logical identity and public serialization.
string? OriginalInput { get; }
Source
Gets the original application spelling used only for compatibility aliases.
A display-safe, non-terminal explanation attached to a successfully resolved value.
Automatic logging treats third-party prose as untrusted and emits only bounded identifiers and codes.
string Code { get; }
Source
Gets the stable diagnostic code.
string Problem { get; }
Source
Gets the safe problem summary.
string Cause { get; }
Source
Gets the safe cause summary.
string Fix { get; }
Source
Gets the repair action.
string Docs { get; }
Source
Gets the required documentation destination.
bool Retryable { get; }
Source
Gets whether retrying later can help.
string? SafeSourceIdentifier { get; init; }
Source
Gets an approved native locator for built-in notice deduplication, never a value.
A provider value or terminal diagnostic carried atomically in a single immutable result.
T
Missing is distinct from a found default value such as zero or false. Values must never be logged.
ConfigProviderValueResult<T> Missing()
Creates an absent result without diagnostics, notices, or a value.
A missing outcome.
ConfigProviderValueResult<T> Found(T value, params ConfigProviderNotice[] notices)
Creates a successful result with an immutable notice collection.
value
notices
A found outcome.
ArgumentNullException
ConfigProviderValueResult<T> Terminal(ConfigProviderTerminalDiagnostic diagnostic)
Creates a terminal outcome with no value or notices.
diagnostic
A terminal outcome.
ArgumentNullException
ConfigProviderValueStatus Status { get; }
Source
Gets the exclusive outcome.
T? Value { get; }
Source
Gets the value for Found; otherwise the default value.
ConfigProviderTerminalDiagnostic? Diagnostic { get; }
Source
Gets the diagnostic only for Terminal.
IReadOnlyList<ConfigProviderNotice> Notices { get; }
Source
Gets the defensively copied notices only for Found.
Configures application string parsing through the normal options registration pipeline.
Typed keys always use strict grammar. Configure options before building the host.
LegacyDotPathBehavior LegacyDotPathBehavior { get; set; }
Source
Gets or sets the string migration behavior; train 1 defaults to dot-only translation.
The sole translation boundary for application strings and deferred declaration fragments.
AppSurfaceConfigKey Parse(string key)
Parses once and retains immutable input origin for aliases and audit notices.
Snapshots finalized options; provider internals never invoke this application adapter.
A synchronous, provider-neutral resolver for scalar file-declared references.
Register one singleton through DI. Validation is local-only; resolution must cap its native synchronous timeout to ConfigSecretResolutionContext.Remaining
and must not block on asynchronous work. Providers unable to honor that contract must reject local validation. See provider compatibility
.
ConfigSecretReferenceValidation ValidateReference(ConfigSecretReference reference)
Validates ownership and syntax without secret-store I/O, including disabled references.
ConfigSecretProviderResolution Resolve(ConfigSecretReference reference, ConfigSecretResolutionContext context)
Resolves one enabled reference without formatting payloads or arbitrary exception text.
string Id { get; }
Source
A unique lower-case kebab-case id, compared case-insensitively.
Inspects existing code-configured mappings locally without broadening convention discovery.
IReadOnlyList<ConfigSecretConfiguredClaim> InspectClaims(string rootLogicalPath, IReadOnlyList<string> secretDestinationPaths)
Reports mappings intersecting the root and a convention only if it already claims that root.
Ordinary inspection failures become value-free composition failures; process-fatal exceptions escape.
A local mapping claim. Resource identity is excluded from default formatting and JSON.
Kind
LogicalPath
ProviderId
Key
Version
An immutable reference passed to local validation and runtime resolution.
Environment
LogicalPath
Key
Version
A cooperative monotonic deadline. Synchronous providers cannot be forcibly preempted.
TimeSpan Remaining { get; }
Source
Gets the nonnegative time remaining. Explicitly constrained providers receive an effectively unbounded TimeSpan.MaxValue
budget. Use the lesser of a finite provider timeout and this value for native calls.
A local-only validation result. It carries no resource identity or arbitrary provider message.
ConfigSecretReferenceValidation Supported()
Accepts this shape without reading a secret.
ConfigSecretReferenceValidation Unclaimed()
Declines ownership of this shape.
ConfigSecretReferenceValidation Invalid()
Rejects a recognized reference without retaining raw error text.
ConfigSecretReferenceValidationStatus Status { get; }
Source
Gets the ownership/syntax outcome.
string Code { get; }
Source
A stable framework-owned code safe for diagnostics.
Allowlisted source metadata; resource keys and requested versions are intentionally absent.
ConfigSecretSourceMetadata Create(string providerId, string sourceKind = "custom")
Creates source metadata without any external identity.
ConfigSecretSourceMetadata WithSafeCorrelationToken(string providerId, string sourceKind, string token)
Creates metadata with a provider-approved, 8–64 character alphanumeric/underscore/hyphen token.
The provider is responsible for ensuring the opaque token reveals no key, version or payload.
string ProviderId { get; }
Source
The canonical registered provider id.
string SourceKind { get; }
Source
The allowlisted source kind: remote, local, or custom.
string? CorrelationToken { get; }
Source
An explicitly approved opaque correlation token, never a resource name or version.
A sealed provider result whose success payload is accessible only to the composition core.
string? ReadSensitiveValue()
Reads transient payload storage without exposing a public serializable getter.
ConfigSecretProviderResolution Resolved(string sensitiveValue, ConfigSecretSourceMetadata source)
Creates a success; empty strings are valid, null is rejected.
ConfigSecretProviderResolution Unclaimed(string providerId)
Declines runtime ownership.
ConfigSecretProviderResolution Missing(string providerId)
Reports a missing claimed resource.
ConfigSecretProviderResolution AccessDenied(string providerId)
Reports denied access without exception text.
ConfigSecretProviderResolution InvalidReference(string providerId)
Reports runtime reference rejection.
ConfigSecretProviderResolution ProviderFailed(string providerId, bool retryable = false)
Reports an unexpected failure without retaining an exception.
ConfigSecretProviderResolutionStatus Status { get; }
Source
The response classification.
ConfigSecretSourceMetadata Source { get; }
Source
Allowlisted source metadata.
string ProviderId { get; }
Source
The canonical provider identity.
bool Retryable { get; }
Source
Whether retrying may repair a transient failure.
Validates bounded identifiers before including trusted registration metadata in output.
string ProviderId(string id)
Validates and returns a canonical id without echoing invalid input in an exception.
Describes a display-safe configuration provider condition that must stop lower-priority resolution.
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.
string ToDisplayString()
Formats this diagnostic for display without exposing raw configuration values.
A multiline display-safe diagnostic string.
Identifier fields are escaped and bounded to 256 characters plus a stable digest when truncated.
string ToDisplayString(int maxRenderedIdentifierCharacters)
Formats this diagnostic for display with a caller-selected identifier limit.
maxRenderedIdentifierCharacters
A multiline display-safe diagnostic string.
ArgumentOutOfRangeException
maxRenderedIdentifierCharacters
is not positive.Only identifier fields are bounded; problem, cause, and fix prose retain their existing display cap.
string Code { get; }
Source
Gets the stable machine-readable diagnostic code.
string Problem { get; }
Source
Gets the operator-facing problem summary.
string Cause { get; }
Source
Gets the display-safe cause summary.
string Fix { get; }
Source
Gets the suggested next action.
string? Docs { get; }
Source
Gets the optional documentation hint or URL.
bool Retryable { get; }
Source
Gets a value indicating whether retrying the same lookup later may resolve the condition.
Describes a configuration entry known to AppSurface's audit system.
AppSurfaceConfigKey LogicalKey { get; }
Source
Gets the typed logical identity represented by this entry.
string Key { get; }
Source
Gets the configuration key.
Type? ConfigType { get; }
Source
Gets the config wrapper type, when this entry came from a wrapper.
Type ValueType { get; }
Source
Gets the declared value type.
ConfigAuditEntryOptions Options { get; }
Source
Gets a copy of the audit entry options captured for this known entry.
The returned options object is immutable. Configure options during registration by using ConfigAuditServiceCollectionExtensions.AddConfigAuditKey{T}(IServiceCollection,string,Action{ConfigAuditEntryOptionsBuilder})
or the constructor overload that accepts ConfigAuditEntryOptions
.
Controls optional expansion behavior for one configuration audit entry.
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.
ConfigAuditEntryOptions Normalize()
Returns options with invalid traversal limits replaced by safe defaults.
Normalization preserves TraverseCollectionElements
, DisplayDictionaryKeys
, and AssignedOptions
. Invalid Sensitivity
values fail closed as ConfigAuditSensitivity.Sensitive
after diagnostics have captured the bad value. It is intended for report generation after diagnostics have captured invalid inputs; it should not be used as a signal that an option was unassigned.
ConfigAuditEntryOptions ApplyAssignedOverrides(ConfigAuditEntryOptions overrides)
Applies explicitly assigned option values from a later registration over this options snapshot.
overrides
A new options snapshot containing merged values and the union of assignment flags.
Merging happens per property. A property in overrides
wins only when its assignment flag is present, and it wins even when the overriding value equals the default. This preserves duplicate-registration precedence where wrapper-discovered options provide a complete policy, while manual provider options can intentionally reset any individual setting back to a default value.
ConfigAuditSensitivity MergeSensitivity(ConfigAuditSensitivity current, ConfigAuditSensitivity candidate)
Merges two assigned entry sensitivity values using the most restrictive valid classification.
current
candidate
The merged sensitivity value.
ConfigAuditSensitivity.Sensitive
wins over ConfigAuditSensitivity.NonSensitive
, and ConfigAuditSensitivity.NonSensitive
wins over ConfigAuditSensitivity.Unknown
. If either value is outside the known enum members, that invalid value is preserved so validation can emit an actionable diagnostic before normalization fails closed. This helper is pure and does not throw for invalid enum values.
ConfigAuditSensitivity NormalizeSensitivity(ConfigAuditSensitivity sensitivity)
Returns a report-generation-safe sensitivity value.
sensitivity
sensitivity
when it is valid; otherwise ConfigAuditSensitivity.Sensitive
.
Valid values are returned unchanged. Invalid enum values normalize to ConfigAuditSensitivity.Sensitive
so redaction fails closed after validation has captured the original value. This helper is pure and does not throw.
bool IsValidSensitivity(ConfigAuditSensitivity sensitivity)
Determines whether a sensitivity value is one of the supported enum members.
sensitivity
true
when sensitivity
is a supported enum member.
ConfigAuditSensitivity.Unknown
, ConfigAuditSensitivity.NonSensitive
, and ConfigAuditSensitivity.Sensitive
are valid. All other numeric values are invalid and should be reported before being normalized. This helper is pure and does not throw.
bool TraverseCollectionElements { get; init; }
Source
Gets a value indicating whether arrays, lists, and dictionaries should emit child element entries.
int MaxCollectionDepth { get; init; }
Source
Gets the maximum nested collection depth traversed when collection traversal is enabled.
int MaxCollectionElements { get; init; }
Source
Gets the maximum number of elements reported from any one traversed collection.
int MaxReportNodes { get; init; }
Source
Gets the maximum number of child nodes created for this entry before traversal stops.
bool DisplayDictionaryKeys { get; init; }
Source
Gets a value indicating whether non-sensitive dictionary keys may appear as element labels.
ConfigAuditSensitivity Sensitivity { get; init; }
Source
Gets the entry-level sensitivity classification used by audit redaction.
The default is ConfigAuditSensitivity.Unknown
. ConfigAuditSensitivity.Sensitive
redacts the root value, traversed child values, and value-derived dictionary labels before report models are returned. ConfigAuditSensitivity.NonSensitive
is a classification hint only: it never disables redaction from sensitive key fragments, source metadata, provider metadata, or another registration that marks the same entry sensitive. Invalid enum values emit a config-audit-options-invalid
diagnostic and fail closed as sensitive during report generation.
ConfigAuditDictionaryKeyCorrelationMode DictionaryKeyCorrelationMode { get; init; }
Source
Gets the opt-in persistent dictionary key correlation mode for this entry.
The default is ConfigAuditDictionaryKeyCorrelationMode.None
, which keeps redacted dictionary key labels report-local. ConfigAuditDictionaryKeyCorrelationMode.ScopedHmac
adds a separate ConfigAuditElementIdentity.KeyCorrelationId
to dictionary element entries when global correlation key material is configured.
ConfigAuditEntryOptionAssignments AssignedOptions { get; init; }
Source
Gets the option properties that were intentionally assigned by the source registration.
Assignment tracking is independent from value comparison. For example, manually assigning MaxCollectionDepth
to its default value still sets the corresponding flag and therefore overrides a wrapper attribute's custom depth during duplicate-registration merging.
Mutable builder used by registration callbacks to create immutable ConfigAuditEntryOptions
.
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.
ConfigAuditEntryOptions ToOptions()
Creates an immutable options snapshot from the current builder state.
The returned options copy current values and assignment flags. Later builder mutations do not affect the returned options, which is important because registrations are snapshotted before reports are built or serialized.
bool TraverseCollectionElements { get; set; }
Source
Gets or sets a value indicating whether arrays, lists, and dictionaries should emit child element entries.
int MaxCollectionDepth { get; set; }
Source
Gets or sets the maximum nested collection depth traversed when collection traversal is enabled.
int MaxCollectionElements { get; set; }
Source
Gets or sets the maximum number of elements reported from any one traversed collection.
int MaxReportNodes { get; set; }
Source
Gets or sets the maximum number of child nodes created for this entry before traversal stops.
bool DisplayDictionaryKeys { get; set; }
Source
Gets or sets a value indicating whether non-sensitive dictionary keys may appear as element labels.
ConfigAuditSensitivity Sensitivity { get; set; }
Source
Gets or sets the entry-level sensitivity classification used by audit redaction.
Use ConfigAuditSensitivity.Sensitive
when the key's domain-specific value should redact even if the key name does not contain a built-in sensitive fragment. ConfigAuditSensitivity.NonSensitive
documents intent but is not an opt-out from conservative redaction and never downgrades another sensitive signal.
ConfigAuditDictionaryKeyCorrelationMode DictionaryKeyCorrelationMode { get; set; }
Source
Gets or sets the opt-in persistent dictionary key correlation mode for this entry.
The default keeps redacted dictionary key labels report-local. Use ConfigAuditDictionaryKeyCorrelationMode.ScopedHmac
only when operators need stable opaque dictionary key identifiers and global ConfigAuditDictionaryKeyCorrelationOptions
are configured.
ConfigAuditEntryOptionAssignments AssignedOptions { get; set; }
Source
Gets the option properties that were assigned through this builder.
The builder tracks setter calls rather than non-default values so duplicate-registration merging can distinguish "caller left the wrapper value alone" from "caller explicitly reset this option to its default."
Extension methods for registering additional configuration audit keys.
IServiceCollection AddConfigAuditKey<T>(this IServiceCollection services, string key)
Registers an additional configuration key for audit reports.
T
services
key
The original services
instance.
Use this method for values that should appear in audit reports but are not backed by an IConfig
or Config{T}
wrapper discovered by assembly scanning. Prefer wrapper discovery when a typed wrapper already exists, because the wrapper can contribute defaults and validation diagnostics. Manual registration creates a ConfigAuditKnownEntry
with ConfigAuditKnownEntry.ConfigType
set to null
and T
as the expected value type; for example, AddConfigAuditKey<Uri>("Billing:Endpoint")
includes a provider-only key in reports. String keys use the finalized input parser; see the logical-key contract
for canonical colon-separated identity and compatibility parsing rules.
IServiceCollection AddConfigAuditKey<T>(this IServiceCollection services, AppSurfaceConfigKey key, Action<ConfigAuditEntryOptionsBuilder>? configure = null)
Registers a typed logical key for audit reports.
T
services
key
configure
The original service collection.
This is the primary manual declaration API. It preserves the supplied immutable key and snapshots callback options immediately. The final registry merges exact canonical duplicates and validates collisions at host startup, including when this extension is used without AppSurfaceConfigModule
. Configure host options before building the service provider. See the logical-key contract
.
IServiceCollection AddConfigAuditKey<T>(this IServiceCollection services, string key, Action<ConfigAuditEntryOptionsBuilder>? configure)
Registers an additional configuration key for audit reports with entry-specific options.
T
services
key
configure
The original services
instance.
Use configure
to opt into collection element traversal for this key only or to classify a domain-specific value with ConfigAuditEntryOptionsBuilder.Sensitivity
. Options are snapshotted when the registration is created; collection traversal remains disabled by default so existing reports keep their previous shape unless callers explicitly enable it. If this key is also discovered from a config wrapper, the wrapper supplies metadata and validation while explicitly assigned manual options override wrapper audit options per property. Sensitivity merges monotonically, so ConfigAuditSensitivity.NonSensitive
never downgrades an effective sensitive entry. String grammar is resolved only after host options are finalized; the train-1 default translates dot-only strings with provenance. Prefer the typed overload for strict identity. Startup validation is registered even without the config module, so malformed deferred declarations and ambiguous spellings fail before traversal.
void EnsureDeclarationInfrastructure(IServiceCollection services)
Ensures one parser/registry and each framework startup-validation bundle per collection.
services
Each named framework validator's exact implementation descriptor identifies its own installation bundle. Other caller validators do not suppress framework validation. Repeated explicit selection, discovery, and manual audit registration keep infrastructure descriptors stable; intentional manual declarations remain additive. Key-policy validation is independent of the registry to avoid a parser/options dependency cycle. Parser and registry TryAdd calls always run, preserving caller replacements. Manual tampering with private installation bundle descriptors is outside this idempotency contract.
Default implementation of IConfigFileLocationProvider
that uses the application's base directory.
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.
Provides shared state predicates for configuration audit entries.
bool IsPartiallyResolved(ConfigAuditEntry entry)
Determines whether an entry or any descendant represents a partial provider patch.
entry
true
when the entry is explicitly partial, has a patch source, or contains a partial child.
Emits diagnostic counters without key, environment, source, value, or exception tags.
The meter is process-owned. Unknown providers and codes collapse to reviewed fallback tags. Listener failures cannot change resolution. Notice counts include repeated use before log suppression.
void Terminal(string code, string provider)
Records one terminal outcome using reviewed category tags.
void Notice(string code, string provider)
Records a compatibility or provider notice using reviewed category tags.
Publishes a candidate only after all present patch inputs have passed conversion and validation.
ConfigPatchResult<T> NotApplied()
Creates a result with no applicable children.
ConfigPatchResult<T> Applied(T value)
Publishes a non-null isolated candidate after successful validation.
ConfigPatchResult<T> Terminal(ConfigProviderTerminalDiagnostic diagnostic)
Rejects the entire transaction without exposing a partially mutated value.
ConfigPatchStatus Status { get; }
Source
Gets the transaction outcome.
T? Value { get; }
Source
Gets the isolated value only when Applied.
ConfigProviderTerminalDiagnostic? Diagnostic { get; }
Source
Gets the diagnostic only when Terminal.
A base class for strongly-typed configuration objects. Values are resolved during IConfig.Init
, then object-valued configuration models are validated with DataAnnotations and scalar values can be validated with AppSurface scalar attributes or ValidateValue
. Invalid provider values and invalid defaults fail fast by throwing ConfigurationValidationException
, so callers that activate config wrappers can catch that exception and surface its structured failures. Ensure defaults satisfy the same validation rules as configured values; an invalid default prevents initialization when no provider value exists. Apply ConfigKeyRequiredAttribute
to require resolved provider/default presence.
T
void Init(IConfigManager configManager, IEnvironmentProvider environmentProvider, AppSurfaceConfigKey key)
Resolves the configured value for key
and validates the resolved provider value or DefaultValue
before initialization completes.
configManager
environmentProvider
key
ConfigurationValidationException
IEnumerable<ValidationResult>? ValidateValue(T value, ValidationContext validationContext)
Validates a resolved non-null scalar configuration value. Override this method when a scalar rule is too specific for the built-in AppSurface scalar attributes.
value
validationContext
The validation results for value
. Return null
, an empty sequence, ValidationResult.Success
, or null entries when validation succeeds.
ConfigWrapperInspection Inspect(AppSurfaceConfigKey key, object? rawValue, ConfigAuditEntryState resolutionState)
Inspects a resolved value using its typed logical key.
bool HasValue { get; set; }
Source
Gets a value indicating whether the configuration has a value (either from source or default).
bool IsDefaultValue { get; set; }
Source
Gets a value indicating whether the current value is the default value.
T? Value { get; set; }
Source
Gets the configuration value.
T? DefaultValue { get; }
Source
Gets the default value for the configuration if none is found in the source.
The exception thrown when a strongly typed configuration value fails validation during initialization.
string Key { get; }
Source
Gets the configuration key being initialized.
Type ConfigType { get; }
Source
Gets the concrete configuration wrapper type being initialized.
Type ValueType { get; }
Source
Gets the resolved value type that was validated.
IReadOnlyList<ConfigurationValidationFailure> Failures { get; }
Source
Gets the validation failures returned for the configuration value.
Projects the frozen native rules and separate direct-composition rules without source dependencies.
Compares two existing ConfigAuditReport
instances without resolving providers.
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.
ConfigAuditDiffReport Compare(ConfigAuditReport baseline, ConfigAuditReport target)
Compares two audit reports using default options.
baseline
target
A typed diff report.
ConfigAuditDiffReport Compare(ConfigAuditReport baseline, ConfigAuditReport target, ConfigAuditDiffOptions? options)
Compares two audit reports using the supplied options.
baseline
target
options
null
.A typed diff report whose item ordering is deterministic.
IEnumerable<ConfigAuditEntry> LogicalChildren(ConfigAuditEntry root)
Finds children that require logical metadata, including object members inside visible dictionaries.
Dictionary items have their own label/correlation identity and need not carry ConfigPath. Visible items without HMAC still contain ordinary children that need logical identity. Redacted and HMAC subtrees use their separate comparison protocol, so their deliberately absent paths do not mark a root as mixed-generation evidence.
A configuration provider that reads settings from JSON files.
Array indices use the token projection's invariant, unpadded decimal spelling. Incoming layers are validated before replacing values or source histories. Rejected branches retain lower-layer state; valid object siblings can still merge, while collisions remain visible to resolution and audit discovery across later layers. File declarations are retained as ordered layers for type-aware Secret{T}
composition. See the logical-key contract
for file identity and layer semantics.
bool HasProjectedRootCollision(string environment, ConfigLogicalPath root)
Reports whether a file identity collision poisons this whole composition root.
ConfigProviderValueResult<T> Resolve<T>(ConfigProviderRequest request)
Resolves a typed value using the request's environment and logical key.
request
A found, missing, or terminal result. Null values are reported as missing.
ConfigCompositionValueResolution IConfigCompositionValueProvider.ResolveRaw(string environment, string logicalKey)
Resolves a legacy file root as raw JSON for type-aware composition.
environment
logicalKey
A value-safe raw resolution with the provider's existing priority and identity.
The returned payload is the composition canonical view built from the immutable file layers. It is deliberately marked non-sensitive because file configuration is not a secret-capable source. A present JSON null
in the injected no-layer snapshot seam is serialized as the raw JSON token null
and remains resolved; only an absent path is missing.
ConfigCompositionValueResolution ResolveRaw(string environment, ConfigLogicalPath root)
Resolves a composition root using its original literal segment boundaries.
IReadOnlyDictionary<string, JsonNode> BuildCompositionEnvironments(ConfigFileProviderSnapshot snapshot)
Builds the immutable host-scoped raw view used only by typed composition.
This view preserves legacy null-skipping semantics and merges logical JSON members case-insensitively so a higher layer can override a lower layer whose member casing differs. The type-aware compiler remains the authority for secret declaration precedence and complete descriptor replacement. The legacy InitializeSnapshot
merge remains unchanged for ordinary file reads and audit enumeration.
byte[] ReadBounded(Stream stream, long limit)
Bounds the bytes retained even if a file grows after its initial length check.
stream
limit
A copy of the complete input, only when it fits the limit.
ConfigResourceLimitException
bool TryGetNodeIncludingNull(JsonNode node, string key, out JsonNode? currentNode)
Finds the first legacy string-root match, preserving a present JSON null as a contribution.
Requested dots and colons are compatibility separators; serialized file members remain literal segments. Empty keys retain the whole-document behavior. This lookup does not merge competing matches.
bool TryGetLogicalNode(JsonNode? node, ConfigLogicalPath requestedPath, ConfigLogicalPath? parentPath, out JsonNode? currentNode)
Traverses matching object ancestors in insertion order while retaining literal member names.
Arrays and scalar nodes cannot be traversed. Invalid member paths are skipped here; the compiler reports their diagnostics before execution. A complete match returns its original subtree without rewriting names.
FileLayerValidation ValidateLayer(ConfigFileTokenProjection projection, Dictionary<AppSurfaceConfigKey, string> earlierSpellings)
Validates every raw occurrence before merging a layer. Exact duplicates reject their whole branch; case differences also reject the incoming branch against all earlier spellings, including rejected sources. Terminal ancestors prevent aggregate replacement but permit independent valid object members to merge.
void RecordOrigin(Dictionary<string, ConfigAuditSourceRecord> origins, Dictionary<AppSurfaceConfigKey, List<ConfigAuditSourceRecord>> history, string file, string path)
Preserves ordered same-path overrides while replacement removes obsolete descendant histories.
ConfigFileProviderSnapshot Snapshot { get; }
Source
Gets the provider snapshot for the type-aware composition compiler.
Existing merged members remain authoritative for ordinary reads and audit enumeration. Composition code uses ConfigFileProviderSnapshot.Layers
and ConfigFileProviderSnapshot.LoadEvents
to inspect file declarations.
Separates rejected source branches from their terminal aggregate ancestors during one layer merge.
Maps JSON object member paths to conservative file source locations for audit provenance.
The map is the location view of the file token projection, so it shares the provider's exact logical-key walk.
ConfigFileSourceLocationMap Create(ReadOnlySpan<byte> fileBytes)
Creates a map from the same token projection used by the file provider.
ConfigAuditSourceLocation? GetLocation(string path)
Gets the location for a logical path written with either supported separator.
ConfigFileSourceLocationMap Empty { get; }
Source
Gets an empty map used when source coordinates are unavailable.
The immutable ordered JSON layer captured from one successfully parsed configuration file.
JsonObject Document { get; }
Source
Gets an isolated copy of the parsed JSON document for compiler traversal.
The layer owns its captured document. Returning a copy keeps compiler and test mutations from changing the snapshot, while retaining the existing layer.Document
access used by the compiler.
An immutable, value-free record of a file that could not contribute a JSON layer.
Code
Environment
DisplayPath
Order
Classification
Base type for the ordered file load history consumed by the type-aware compiler.
IReadOnlyDictionary<string, Dictionary<AppSurfaceConfigKey, List<ConfigAuditSourceRecord>>> OriginHistory { get; init; }
Source
Ordered source origins for effective paths; values are never retained in provenance.
Validates complete native names and atomically publishes bounded ad-hoc reverse claims.
Each environment has its own collision domain. All names for one request are checked before any are added.
void Validate(string environment)
Checks frozen mappings against canonical and explicit full names for all finalized declarations.
string? Claim(ConfigProviderRequest request, IEnumerable<string>? nativeNames = null)
Checks representability even for supplied child names, then atomically claims every candidate.
Only an exact mapping exempts a key from convention grammar and environment-prefix restrictions.
Applies the built-in audit redaction and value formatting policy.
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.
ConfigAuditRedaction CreatePolicy(ConfigAuditDictionaryKeyCorrelationOptions? correlationOptions = null, bool dictionaryKeyCorrelationRequested = false)
Creates a snapshot of the redaction policy applied to reports.
correlationOptions
dictionaryKeyCorrelationRequested
A policy snapshot with a copy of the sensitive fragments and the placeholder text.
RedactedValue FormatValue(string key, object? value, IReadOnlyList<ConfigAuditSourceRecord> sources, ConfigAuditSensitivity entrySensitivity = ConfigAuditSensitivity.Unknown)
Formats value
for display and redacts it when the key or sources look sensitive.
key
value
sources
entrySensitivity
The display value and whether it was replaced by the redaction placeholder.
Describes a formatted value after applying the redaction policy.
DisplayValue
null
for non-scalar objects.IsRedacted
A host-scoped immutable registration snapshot, shared by runtime, startup and audit.
IReadOnlyList<ConfigSecretRegistration> Providers { get; }
Source
The registered providers in canonical id order.
IReadOnlyList<string> Errors { get; }
Source
Value-free registration errors detected before local reference validation or I/O.
Captures one trusted provider instance and its validated identity.
Compiles value-free plans from host-owned immutable inputs. Payloads and invocation options are never cached.
ConfigCompositionPlan Compile(string environment, string key, Type type)
Gets a cached plan. New source/registration/options generations belong to a new host compiler.
ConfigCompositionPlan Compile(string environment, AppSurfaceConfigKey key, Type type)
Compiles a plan from a typed root whose segments may contain literal dots.
bool IsFatalInspectionException(Exception exception)
Identifies process-level failures that provider callbacks must not turn into plan diagnostics.
ConfigLogicalPath Join(ConfigLogicalPath root, IReadOnlyList<string> members)
Appends serialized member segments to the requested root.
A parsed policy declaration. It is never used as an effective value.
An immutable value-free execution plan scoped to one host and source generation.
One compiled scalar destination and its locally validated reference policy.
Describes the outcome of a config audit diff command runner invocation.
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.
string? BaselineEnvironment { get; }
Source
Gets the baseline environment when available.
string? TargetEnvironment { get; }
Source
Gets the target environment when available.
ConfigAuditDiffCommandFailure? Failure { get; }
Source
Gets the display-safe failure details when the diff workflow could not run.
bool Succeeded { get; }
Source
Gets a value indicating whether the diff was generated and written.
int ExitCode { get; }
Source
Gets the recommended process exit code for a command wrapper.
The root result classification shared by runtime and audit.
The identity outcome for an entire collision domain.
Selects how much trust the diff should attach to the two audit reports being compared.
Evidence mode changes diagnostics and wording only. ConfigAuditReportDiffer
still compares two already-built ConfigAuditReport
objects and never re-resolves configuration providers.
Identifies the comparison status for one diff item.
Values are explicit and append-only so serialized diff reports remain stable across releases.
Classifies how urgently an item should be reviewed.
Identifies the kind of audit evidence represented by a diff item.
Selects how source paths should be rendered by ConfigAuditDiffTextRenderer
.
Explains how much value-level evidence is available for one compared item.
Identifies how an environment source changed the final audited value.
Describes whether lower-priority provider evidence proved a path existed before the environment override.
Identifies the provider value shape used while building discovered-key reports.
Values are explicit and append-only so external provider audit enumerators can report inventory shape without exposing provider-private parser details.
Distinguishes present aggregates from scalars and null members skipped during layering.
Selects the shape of a configuration audit report.
Identifies how dictionary keys should receive cross-report correlation identifiers.
Values are explicit and append-only so serialized reports remain stable across releases.
Identifies the resolution state for an audited configuration entry.
Values are explicit and append-only so serialized reports remain stable across releases.
Identifies how a provider-discovered key relates to the AppSurface audit registry.
Values are explicit and append-only so serialized reports remain stable across releases. These classifications are registry-relative: Unknown
does not mean globally unused, and KnownDescendant
is based on colon-delimited segment matching rather than schema validation of a wrapper type.
Identifies how a provider-discovered value appears in the public audit report.
Values are explicit and append-only so serialized reports remain stable across releases. This enum describes report display state only: it is not a sensitivity or secrecy classification, and source metadata may remain support-sensitive even when a value is omitted.
Identifies the kind of collection element represented by an audit child entry.
Values are explicit and append-only so serialized reports remain stable across releases.
Identifies the kind of configuration source.
Values are explicit and append-only so serialized reports remain stable across releases.
Identifies how a source contributed to the final value.
Values are explicit and append-only so serialized reports remain stable across releases.
Classifies source or value sensitivity.
Values are explicit and append-only so serialized reports remain stable across releases. For entry options, NonSensitive
is a classification hint, not a redaction bypass; sensitive fragments, provider source sensitivity, and another registration's Sensitive
classification still win.
Identifies diagnostic severity.
Values are explicit and append-only so serialized reports remain stable across releases.
A local whole-root ownership classification.
Classifies raw root resolution without deserializing an application object.
Identifies the stage where ConfigAuditDiffCommandRunner
could not complete.
Identifies whether an environment candidate is scoped to an environment prefix.
Distinguishes strict construction from train-1 application input for native alias selection.
The three mutually exclusive outcomes of one provider request.
Controls the bounded migration of historical dot-delimited application strings.
Classifies an existing code-configured claim.
Local ownership and reference syntax classification.
Classifies a single provider response. Only missing and unclaimed can fall through.
Tracks which audit entry options were intentionally assigned by a wrapper attribute or manual registration.
These flags control duplicate-registration precedence. They are not a serialization format and should not be inferred from option values, because default-valued assignments are meaningful overrides.
The result of an isolated, all-present-children-validated patch transaction.
Classifies a file load failure without retaining exception text or configuration values.