Cohesive Configuration

Cohesive.Configuration extends the standard .NET configuration and dependency-injection model with semantic configuration profiles and rule-based dependency selection.

It is built for systems where "configuration" means more than key/value binding. A Cohesive runtime often needs to select backends, activate adapters, compose runtime profiles, bind CLI/environment/application settings, and choose concrete infrastructure based on semantic requests. Cohesive.Configuration gives those decisions a declarative surface while continuing to use IConfiguration and IServiceProvider as the host integration points.

Why It Exists
Configuration Profiles
Two-Phase Bootstrap
Typed Parameter Parsing
Runtime Profiles
Dependency Selection
IServiceProvider-Backed Activation
Configuration Projection
What It Extends
Integration With Cohesive
The Configuration Role In Cohesive

Why It Exists

Modern systems rarely have one configuration file and one dependency graph.

The same product may run as:

a local development runtime;
an in-memory test harness;
a cloud-backed staging environment;
a production runtime with remote storage, Durable Task, search, identity, and blob adapters;
a CLI that needs the same settings as an ASP.NET host;
a process worker that needs a subset of the same services.

Without a stronger model, those modes tend to become scattered if statements, duplicated appsettings files, hand-rolled environment parsing, and service-registration branches.

Cohesive.Configuration keeps the normal .NET hosting model, but adds:

configuration profiles with inheritance and overlays;
typed parameter parsing from IConfiguration, environment variables, and CLI arguments;
runtime profile catalogs;
configuration projections between setting models;
prioritized dependency selection catalogs;
service-provider-backed activation patterns for adapters and runtime dependencies.

Configuration Profiles

Configuration profiles are named overlays inside an IConfiguration tree. A profile can extend one or more base profiles, and the resolved chain is applied from base to most specific.

{
  "ActiveProfile": "cloud-dev",
  "Profiles": {
    "default": {
      "Runtime": {
        "Backend": "InMemory"
      }
    },
    "cloud": {
      "Extends": "default",
      "Runtime": {
        "Backend": "Remote"
      },
      "Storage": {
        "Provider": "Cosmos"
      }
    },
    "cloud-dev": {
      "Extends": "cloud",
      "Storage": {
        "Database": "cohesive-dev"
      }
    }
  }
}

The profile can be resolved without mutating the live configuration.

var resolution = configuration.ResolveConfigurationProfile(new()
{
    ProfilesSectionPath = "Profiles",
    ActiveProfileKey = "ActiveProfile",
    DefaultActiveProfile = "default"
});

var profiled = configuration.CreateProfiledConfiguration(resolution);

For host applications, the profile overlay can be applied to the live IConfigurationManager.

var profileContext = builder.Configuration.AddConfigurationProfile(
    builder.Environment,
    new ConfigurationProfileOptions(),
    configureBootstrap: bootstrap =>
    {
        var appConfigEndpoint = bootstrap.Configuration["AzureAppConfiguration:Endpoint"];
        if (!string.IsNullOrWhiteSpace(appConfigEndpoint))
        {
            builder.Configuration.AddAzureAppConfiguration(appConfigEndpoint);
        }
    });

The returned ConfigurationProfileContext records the host environment, active profile, and applied profile chain. That context can be registered in DI and passed through CLI commands, process workers, API hosts, and test harnesses.

Two-Phase Bootstrap

Some configuration providers are themselves configured by the active profile. For example, a profile may specify whether Azure App Configuration is enabled and which endpoint to use.

Cohesive.Configuration supports a two-phase flow:

Resolve a bootstrap profile view from the current configuration.
Use that view to register additional providers.
Resolve the final profile after those providers are attached.
Apply the final overlay to the live configuration manager.

This lets profile-derived settings participate in provider registration without losing the normal last-provider-wins behavior of IConfiguration.

Typed Parameter Parsing

Cohesive.Configuration includes a typed parameter parser for CLIs, tools, and hosts that need strict setting validation.

ConfigurationParameterParser reads hierarchical configuration, validates required values and allowed values, converts raw values into binder-friendly values, and delegates final object creation to the Microsoft configuration binder.

public sealed record TrainCommandOptions
{
    [ConfigurationParameter(
        keyOverride: "training:profile",
        CliKey = "--profile",
        CliShortKey = "-p",
        Description = "Training profile to run.",
        Required = true)]
    public string Profile { get; init; } = "";

    [ConfigurationParameter(
        keyOverride: "training:timeout",
        CliKey = "--timeout",
        TimeUnit = ConfigurationTimeUnit.Seconds)]
    public TimeSpan Timeout { get; init; } = TimeSpan.FromMinutes(10);
}

var options = ConfigurationParameterParser.Parse<TrainCommandOptions>(
    args,
    configure: builder => builder.AddJsonFile("appsettings.json", optional: true),
    environmentVariablePrefix: "COHESIVE_");

Attributes are not the only way to define metadata. Expression-based overrides can map property paths, CLI names, allowed values, required flags, and enum mappings without putting all metadata directly on the settings type.

var parserOptions = new ConfigurationParameterOptions<TrainCommandOptions>();

parserOptions
    .Map(x => x.Profile)
    .WithNameOverride("training:profile")
    .WithCliName("--profile")
    .WithCliShortName("-p")
    .IsRequired();

parserOptions
    .Map(x => x.Timeout)
    .WithNameOverride("training:timeout")
    .WithCliName("--timeout")
    .WithTimeUnit(ConfigurationTimeUnit.Seconds);

var options = ConfigurationParameterParser.Parse(args, options: parserOptions);

The parser can also describe the effective parameter model, which is useful for generated help output, command documentation, or runtime diagnostics.

var parameters = ConfigurationParameterParser
    .Describe<TrainCommandOptions>(parserOptions);

Runtime Profiles

Configuration profiles operate over IConfiguration. Runtime profiles operate over typed settings.

A runtime profile catalog defines named typed transformations. Like configuration profiles, runtime profiles can extend base profiles. This is useful when a runtime mode is more than a collection of string keys and needs to activate a coherent typed setting graph.

var catalog = new RuntimeProfileCatalogBuilder<TrainingRuntimeSettings>()
    .Add(new(
        Name: "local",
        Extends: [],
        Apply: settings => settings with
        {
            Backend = ResourceBackendMode.Local
        }))
    .Add(new(
        Name: "cloud",
        Extends: ["local"],
        Apply: settings => settings with
        {
            Backend = ResourceBackendMode.Remote
        }))
    .Build();

var runtime = catalog.Resolve(
    context: profileContext,
    defaultProfile: "local",
    settingsFactory: environmentName => TrainingRuntimeSettings.ForEnvironment(environmentName));

This keeps environment and profile resolution explicit while allowing strongly typed settings to evolve without duplicating environment-specific object construction.

Dependency Selection

Cohesive.Configuration provides a prioritized dependency selection catalog.

Instead of encoding dependency selection with nested conditionals, a catalog declares named rules. Each rule decides whether it matches a semantic request, creates the dependency, and has a priority. Higher-priority rules win. Equal-priority matches fail as ambiguous.

public sealed record RepositoryRequest(
    EntityDefinition Entity,
    ConfigurationProfileContext Profile);

var catalog = new DependencySelectionCatalogBuilder<RepositoryRequest, IEntityRepository>()
    .Add(
        name: "cosmos-tenant-partitioned",
        matches: request =>
            request.Profile.ActiveProfile == "cloud"
            && UsesTenantPartitioning(request.Entity),
        create: request => CreateCosmosRepository(request.Entity),
        priority: 100)
    .Add(
        name: "in-memory-local",
        matches: request => request.Profile.ActiveProfile == "local",
        create: request => CreateInMemoryRepository(request.Entity),
        priority: 10)
    .AddFallback(
        name: "default-in-memory",
        create: request => CreateInMemoryRepository(request.Entity))
    .Build();

var selected = catalog.Resolve(new(entityDefinition, profileContext));
var repository = selected.Dependency;

The selected rule name is part of the result. That makes diagnostics more useful: a host can report not only which dependency was activated, but why it was activated.

IServiceProvider-Backed Activation

The dependency selection catalog is intentionally independent of IServiceProvider, but it composes naturally with it.

Rules can create dependencies directly, or they can use the service provider to activate richer objects with shared services, options, loggers, factories, and adapters.

services.AddSingleton(sp =>
{
    var profile = sp.GetRequiredService<ConfigurationProfileContext>();
    var settings = sp.GetRequiredService<TrainingRuntimeSettings>();

    return new DependencySelectionCatalogBuilder<EntityDefinition, EntityPartitionKeyPolicy>()
        .Add(
            name: "tenant-scope-placement",
            matches: entity => UsesTenantScopePlacement(entity, settings),
            create: entity => CreateTenantScopePartitionKeyPolicy(entity, sp),
            priority: 100)
        .AddFallback(
            name: "observation-id",
            create: _ => EntityPartitionKeyPolicy.ObservationId)
        .Build();
});

This pattern lets IServiceProvider stay responsible for activation while Cohesive.Configuration stays responsible for semantic selection. The result is a dependency system that can choose storage repositories, process runtimes, model trainers, code packagers, identity directories, or search adapters based on the requested semantic object and active runtime profile.

Configuration Projection

Some adapters need configuration values derived from another typed source. ConfigurationProjection<TSource, TTarget> projects values into hierarchical configuration overrides using expression-selected target paths or raw configuration paths.

var projection = new ConfigurationProjection<StorageProfile, CosmosSettings>()
    .Map(source => source.AccountName, target => target.AccountName)
    .Map(source => source.DatabaseName, target => target.Database)
    .When(
        source => source.UseLocalEmulator,
        local => local.Set("UseDevelopmentStorage=true", target => target.ConnectionString));

var overrides = projection.Build(storageProfile);

This is useful for adapter bridges where one semantic settings model needs to configure a backend-specific settings object without copying values by hand in every host.

What It Extends

Cohesive.Configuration extends IConfiguration by adding:

named profile overlays;
profile inheritance;
active-profile resolution;
profile-aware bootstrap provider registration;
typed parameter parsing;
CLI and environment-variable mapping;
expression-based parameter metadata;
configuration projections.

It extends IServiceProvider usage by adding:

semantic dependency selection requests;
named prioritized rules;
deterministic ambiguity handling;
fallback rules;
service-provider-backed dependency activation;
diagnostics that explain which rule produced a dependency.

The standard .NET abstractions remain the host boundary. Cohesive.Configuration adds semantic structure around them.

Integration With Cohesive

Cohesive.Configuration is used wherever the same semantic system must be activated in different runtime modes.

Cohesive.Storage

Storage repositories and partition policies can be selected by entity definition, storage annotations, identity scope, backend mode, or active profile.

Cohesive.Processes

Process engines can choose Durable Task, Temporal-style, or ephemeral execution backends through typed runtime settings and dependency selection.

Cohesive.Identity

Identity directories, bootstrap users, external provider options, and scope behavior can be selected by runtime profile.

Cohesive.Api

API hosts can load the same profile-aware settings as CLIs and workers, while generated endpoint metadata remains independent of host-specific configuration.

Cohesive.Presentation

Presentation projections and frontend development servers can consume generated configuration metadata without duplicating backend settings names.

The Configuration Role In Cohesive

Cohesive.Configuration keeps runtime choice declarative.

It provides:

profile overlays for IConfiguration;
typed settings parsing for hosts and CLIs;
runtime profile catalogs;
configuration projection helpers;
prioritized dependency selection;
service-provider-backed activation patterns;
explicit diagnostics for missing, cyclic, or ambiguous selections;
a bridge between semantic system definitions and concrete runtime infrastructure.

The result is a configuration layer that supports local development, testing, cloud deployments, CLIs, process workers, and API hosts from the same semantic runtime model.