Cohesive.Infra

Authority Model

Infra keeps desired semantics, target evidence, physical realization, and observed state separate. Each artifact answers a different question and carries an exact fingerprint or reference to the inputs it interprets.

This is the infrastructure form of system language and realization: stable intent stays distinct from the tools that construct or observe it.

Canonical Definition

The canonical graph has two node families:

Bindings and readiness dependencies connect those nodes. Requirements attach provider-neutral capability identities to the node that demands them.

InfrastructureCapabilityId https = new("network/https");
InfrastructureCapabilityId documentAuthority = new("storage/document-authority");
InfrastructureCapabilityId changeFeed = new("storage/change-feed");
InfrastructureBindingContractId repositoryReadWrite = new("storage/repository-read-write");
 
var document = Infrastructure.Define(
    id: new("shipping"),
    revision: new("1"),
    configure: infra =>
    {
        var api = infra.Workload(new("workload/api"))
            .Requires(https);
 
        var state = infra.Resource(new("resource/state"))
            .Persistent()
            .Requires(documentAuthority)
            .Requires(changeFeed);
 
        api.RequiresReady(state);
 
        infra.Bind(new("binding/api-state"), api)
            .To(state)
            .As(repositoryReadWrite);
    });

Infrastructure.Define returns an immutable, normalized, serializable, fingerprinted InfrastructureDefinitionDocument. Collection order and builder objects are not semantic. Equivalent direct IR, generated manifests, imports, and fluent authoring normalize to the same document.

Bindings and Readiness

A resource declaration says that a role exists. A binding says how one node may rely on another and names the provider-neutral contract that must survive realization.

Binding elaboration profiles map exact contract identities to capability and assurance obligations. Those obligations may cover service discovery, configuration injection, identity grants, network policy, secret transport, telemetry, replacement order, or other properties of the path. Zero matching rules is unavailable; several matching rules are ambiguous. The compiler does not guess.

RequiresReady(...) carries a different meaning. It declares that one canonical node cannot be admitted as ready until another is ready. The realization compiler later lowers that semantic edge through exact workload placements and resource lifecycle bindings into a physical readiness obligation.

This prevents an application host, Compose file, or deployment program from becoming a second application topology.

Target Facilities

A target adapter declares its selectable physical construction families with InfrastructureTargetFacilities.Define. A facility owns exact leaf capability evidence; the capability profile remains the authority for composition rules and operating boundaries.

var facilities = InfrastructureTargetFacilities.Define(
    id: new("azure-pulumi/facilities/v1"),
    profileId: new("azure-pulumi/capabilities/v1"),
    target: new("pulumi-azure-native/3.16.0"),
    variant: new("development"),
    supportedDefinitionSchemaVersions:
        [InfrastructureDefinitionDocument.CurrentSchemaVersion],
    configure: target =>
    {
        target.Workload(new("azure/app-service"))
            .Provides(AppServiceEvidence.Https);
 
        target.Resource(new("azure/blob-storage"))
            .Provides(BlobEvidence.ObjectStorage);
    });
 
var plan = InfrastructureTargetCompiler.Compile(
    document,
    facilities,
    ShippingBindings.Profile);

The shared compiler selects one facility per logical node, resolves attributable conventions, elaborates binding obligations, and proves capability closure. A convention can choose among semantically valid alternatives or supply stable naming policy; it cannot invent requirements or weaken a guarantee.

Target variants such as local-aspire, azure-pulumi, or another adapter-defined environment are coherent alternatives. Compilation cannot cherry-pick individually convenient evidence from mutually incompatible variants.

Capability Proof

Requirements and supplied capabilities use the same identity vocabulary. Every demand receives one inspectable disposition:

Composed proofs retain every intermediate and auxiliary evidence identity. Equally preferred valid proofs are ambiguous until policy selects one. Constrained evidence remains residual until an exact, demand-scoped boundary-acceptance policy supplies a rationale and attributable sources.

The result is capability closure, not a lowest-common-denominator feature check. The proof records why this exact target preserves this exact requirement.

Physical Deployment

Facility planning chooses construction families. InfrastructureTargetDeploymentManifest supplies the exact physical identities and environment participation needed to turn that plan into a realization.

InfrastructureLifecycleAuthorityId pulumiState =
    new("pulumi/shipping/development");
 
var targetEvidence = InfrastructureSourceReferences.Target(
    facilities.Profile.Target);
 
var deployment = InfrastructureTargetDeployments.Define(
    id: new("shipping/azure-pulumi/development/v1"),
    definition: document,
    targetFacilities: facilities,
    configure: physical =>
    {
        physical.Workload(
            ShippingNodes.Api,
            AzureFacilities.AppService,
            AzureResources.AppService("shipping-api"),
            [targetEvidence]);
 
        physical.Resource(
            ShippingNodes.State,
            AzureFacilities.BlobStorage,
            AzureResources.Container("shipping", "state"),
            pulumiState,
            [InfrastructureSourceReferences.LifecycleAuthority(pulumiState)]);
    });
 
var deploymentPlan = InfrastructureTargetDeploymentCompiler.Compile(
    ShippingInfrastructure.Current,
    deployment);
 
var realization = deploymentPlan.Realization;

Every canonical workload must be placed or explicitly declared non-participating with a rationale and sources. Silent omission fails. A binding or readiness edge from a participating node into a non-participating workload also fails because the declared physical environment cannot preserve the canonical path.

Placements do more than assign names. They construct demand-scoped capability witnesses, associate logical nodes with exact physical resources, and fence the realization to the definition, facility manifest, capability profile, binding profile, target, and variant that produced it.

Lifecycle Ownership

Canonical resources declare one of three lifecycle intents:

One physical resource has one lifecycle authority. Another interpreter may consume that resource by declaring ReferencedResource(...) and naming both the manager and authority. The shared compiler then retains a managed binding for the owner and a referenced binding for the consumer.

physical.ReferencedResource(
    ShippingNodes.State,
    AspireFacilities.Postgres,
    LocalResources.Postgres("shipping"),
    dockerComposeTarget,
    dockerComposeAuthority,
    [InfrastructureSourceReferences.LifecycleAuthority(dockerComposeAuthority)]);

Conflicting managers, ownership claims on canonical external resources, or aliases that disagree about lifecycle authority are structured errors. This makes ownership explicit across infrastructure interpreters instead of leaving it in deployment convention.

Readiness Assessment

A successful realization proves semantic coverage and compiles exact readiness obligations. It does not prove that anything was deployed or is healthy.

Adapters normalize current backend evidence into InfrastructureResourceObservation values. The pure evaluator compares those attributable observations with one exact realization:

var assessment = InfrastructureReadinessEvaluator.Assess(
    realization,
    observations);

The assessment returns one fingerprinted decision per physicalized logical node. Missing or unknown evidence fails closed. An unhealthy dependency blocks its subject even when that subject exposes an endpoint, and favorable runtime health cannot repair an incomplete capability realization.

Observation collection remains adapter work. The evaluator performs no I/O and does not deploy, mutate, restart, or reconcile resources.

Local Realization

InfrastructureLocalRealizationDocument is the shared input boundary for local lifecycle adapters. It combines an exact infrastructure realization with a versioned environment policy, resolved conventions, and a target-neutral construction topology.

The local topology can describe:

• Workload services backed by repository-relative .NET projects.
• Workload or resource services backed by pinned container images.
• Referenced services whose lifecycle belongs to another interpreter.
• Typed endpoints, host exposure, and endpoint-derived configuration values.
• External secret references and generated non-secret configuration files.
• Volumes, health probes, graceful termination, and exact readiness dependencies.
• Application-owned harness operations with explicit execution placement and mutation authority.

var topology = InfrastructureLocal.Define(local => local
    .ProjectService(
        ShippingNodes.Api,
        LocalResources.Api,
        new InfrastructureLocalProjectSource(
            new("shipping-api"),
            new("src/Shipping.Api/Shipping.Api.csproj")),
        api => api
            .Endpoint(
                ShippingEndpoints.Http,
                "http",
                8080,
                InfrastructureLocalEndpointExposure.HostLoopback,
                InfrastructureLocalEndpointRole.Data,
                ShippingConfiguration.ApiPort))
    .ContainerService(
        ShippingNodes.State,
        LocalResources.Postgres,
        "postgres:18.0@sha256:...",
        postgres => postgres
            .CommandHealth("pg_isready")
            .HealthTiming(
                TimeSpan.FromSeconds(2),
                TimeSpan.FromSeconds(1),
                retries: 30)));
 
var localRealization = InfrastructureLocalRealizationCompiler.Compile(
    realization,
    ShippingEnvironments.Local,
    topology,
    [ShippingConventions.Local]);

The compiler checks that local services agree with physical placements and lifecycle bindings, project sources attach only to workloads, images are pinned, referenced values exist, ports are valid, secrets remain external, health policies are complete, and destructive operations stay inside their named lifecycle authority.

Interactive and isolated-test profiles make data retention, project naming, maximum lifetime, and destructive authority visible. A local startup preference may remain an explicit compatibility override, but it is diagnosed when it has no matching canonical readiness dependency.

Adapter Boundary

Cohesive.Infra is a zero-third-party-dependency semantic core. It does not reference Terraform, Pulumi, Aspire, Azure, AWS, GCP, Kubernetes, Docker, or their SDKs.

Dedicated adapters may:

• Declare target facility and capability manifests.
• Translate a successful realization into provider resources or deployment artifacts.
• Run deployment, preview, apply, destroy, or reconciliation operations.
• Import backend identities, receipts, drift, diagnostics, and observations.
• Project local construction into Docker Compose or Aspire orchestration.

They do not reimplement facility selection, capability closure, binding elaboration, lifecycle ownership, or readiness meaning. Current adapter packages include Docker Compose and Aspire projections, Aspire deployment integration for Pulumi, and an Azure Pulumi facility adapter.

Compiler Pipeline

Diagnostics are part of the programming model. Capability gaps, ambiguous proofs, unaccepted boundaries, binding gaps, participation conflicts, convention conflicts, lifecycle conflicts, missing witnesses, and unknown observations return stable diagnostic codes with semantic locations, source references, expected and observed states, and repair options.

Those structured artifacts can feed CLI text, JSON, SARIF, CI annotations, editors, tests, dashboards, or agent explanations without parsing rendered log messages.

Design Rules

• Keep application meaning in the canonical definition; keep provider naming and deployment mechanics in adapters.
• Use bindings as primary semantics for paths between workloads and resources.
• Select evidence from one coherent target variant instead of synthesizing a target from incompatible claims.
• Treat constrained support as residual until exact policy accepts every operating boundary for the exact demand.
• Retain source provenance, fingerprints, and physical identities across compilation boundaries.
• Give each physical resource one lifecycle authority and represent every other interpreter as a reference.
• Lower canonical readiness through the realization; do not maintain a second dependency graph in deployment code.
• Fail closed on missing, unknown, stale, ambiguous, or incorrectly scoped evidence.
• Keep deployment receipts and time-indexed observations distinct from semantic and capability proof.
• Make fluent builders produce canonical IR; do not retain callbacks, provider objects, service providers, clocks, or ambient environment state.

Together these rules preserve the boundary between a portable semantic system graph and the compute, network, and storage systems chosen to realize it.