Cohesive.Infra 0.1.0-alpha.82

Cohesive.Infra

Cohesive.Infra describes portable infrastructure requirements, bindings, capability-qualified realizations, and lifecycle ownership without making a provider SDK or deployment tool authoritative for application meaning.

Install

dotnet add package Cohesive.Infra

Define requirements

The common authoring path declares workloads, logical resources, and the contracts that connect them. Resource and binding identities are durable topology boundaries; compiler-internal nodes are derived:

var document = Infrastructure.Define(
    id: new("shipping"),
    revision: new("1"),
    configure: infra =>
    {
        var api = infra.Workload(new("workload/api"));
        var state = infra.Resource(new("resource/state"))
            .Persistent()
            .Requires(ShippingCapabilities.DocumentAuthority)
            .Requires(ShippingCapabilities.ChangeFeed);

        api.RequiresReady(state);

        infra.Bind(new("binding/api-state"), api)
            .To(state)
            .As(ShippingContracts.RepositoryReadWrite);
    });

Infrastructure.Define returns an immutable, normalized, fingerprinted document. A target adapter declares its physical construction families as an InfrastructureTargetFacilityManifest: facilities group exact leaf capability evidence, while the capability profile remains the sole authority for guarantees, composition rules, and operating boundaries. InfrastructureTargetCompiler then selects one facility per logical node, resolves attributable conventions, elaborates binding obligations, and proves capability closure without an application-specific compiler.

var target = 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: facilities =>
    {
        facilities.Workload(new("azure/app-service")).Provides(AppServiceEvidence.Https);
        facilities.Resource(new("azure/blob-storage")).Provides(BlobEvidence.ObjectStorage);
    });

var plan = InfrastructureTargetCompiler.Compile(document, target, ShippingBindings.Profile);

The fluent builder is only an authoring projection. It materializes the same immutable, serializable, fingerprinted manifest that direct IR, imported documents, generated catalogs, and agent tooling can produce.

A lifecycle adapter can additionally declare the exact physical deployment without implementing an application-side compiler. InfrastructureTargetDeployments.Define materializes a portable deployment manifest; the shared compiler then selects facilities, derives lifecycle dispositions from canonical resource intent, places workloads, constructs demand-scoped capability witnesses, and reports mismatches:

InfrastructureLifecycleAuthorityId pulumiState = new("pulumi/shipping/development");
var targetEvidence = InfrastructureSourceReferences.Target(target.Profile.Target);
var deployment = InfrastructureTargetDeployments.Define(
    id: new("shipping/azure-pulumi/development/v1"),
    definition: document,
    targetFacilities: target,
    configure: physical =>
    {
        physical.Workload(
            ShippingNodes.Api,
            AzureFacilities.AppService,
            AzureResources.AppService("shipping-api"),
            [targetEvidence]);
        physical.NonParticipatingWorkload(
            ShippingNodes.Admin,
            "The API-only development environment does not host the administration workload.",
            [SourceReference.Create("environment-profile", "shipping/api-only-development")]);
        physical.Resource(
            ShippingNodes.State,
            AzureFacilities.BlobStorage,
            AzureResources.Container("shipping", "state"),
            pulumiState,
            [InfrastructureSourceReferences.LifecycleAuthority(pulumiState)]);
    });

var realization = InfrastructureTargetDeploymentCompiler.Compile(ShippingInfrastructure.Current, deployment);

Application declarations contain no requirement-discharge or witness-construction algorithm. Provider naming and artifact discovery belong to the adapter; all callbacks are discarded after materializing canonical IR. Every canonical workload must be either placed or explicitly declared non-participating with a rationale and sources; omission remains an error. Non-participation is physical environment policy, not a second semantic definition and not permission to weaken the target's capability closure. Requirements demanded solely by a non-participating workload do not need physical witnesses, while a participating binding or readiness edge into that workload fails closed. Constrained target evidence remains inadmissible until the deployment explicitly calls AcceptBoundary(...) with a rationale and attributable sources. That declaration accepts only the named target boundary; the shared compiler matches it to selected demands, materializes the exact fenced InfrastructureBoundaryAcceptancePolicy, and exposes that policy on the deployment plan. Applications do not compile provisionally or enumerate requirement identities. Fluent facility and deployment authoring also captures C# call sites in a portable source map. Source maps support diagnostics and inspection but are excluded from semantic fingerprints, so moving equivalent declarations between files does not change their canonical identity. Explicit source references remain semantic evidence and should be projected from typed target, facility, lifecycle, or artifact identities instead of handwritten repository paths.

When the selected interpreter consumes a non-external resource whose lifecycle belongs to another interpreter, use ReferencedResource(...) and name that manager explicitly. For example, an Aspire projection can consume emulators whose lifecycle remains owned by Docker Compose:

InfrastructureTargetId dockerCompose = new("docker-compose/2.30");
InfrastructureLifecycleAuthorityId localComposeProject = new("compose/ari/local");

physical.ReferencedResource(
    AriNodes.DomainState,
    AspireFacilities.Cosmos,
    LocalResources.Cosmos("ari"),
    dockerCompose,
    localComposeProject,
    [InfrastructureSourceReferences.LifecycleAuthority(localComposeProject)]);

The shared compiler derives both sides of that relationship: Docker Compose receives the sole Managed lifecycle binding and Aspire receives a Referenced binding to the same physical identity and authority. Resource(...) remains the concise default when canonical lifecycle intent makes the selected target the manager (or makes an external resource reference-only). Redundant selected-target managers, managers on canonical external resources, and aliases that disagree about a physical resource's manager, authority, or external status are structured errors.

When the target deployment and local construction topology describe the same services, use coordinated local deployment authoring so each logical-to-physical association is declared once. The producer emits the existing independently portable manifest and topology artifacts; it does not introduce another source of infrastructure truth:

var local = InfrastructureLocalDeployments.Define(
    id: new("shipping/aspire-local/v1"),
    definition: ShippingInfrastructure.Current.Definition,
    targetFacilities: AspireLocalFacilities.Current,
    configure: deployment => deployment
        .ProjectService(
            ShippingNodes.Api,
            AspireFacilities.Project,
            LocalResources.Api,
            ShippingProjects.Api)
        .ReferencedResourceService(
            ShippingNodes.State,
            AspireFacilities.Postgres,
            LocalResources.Postgres,
            DockerComposeTarget,
            DockerComposeAuthority,
            ShippingEndpoints.Postgres,
            [ShippingSources.LocalCompose],
            postgres => postgres
                .Endpoint(
                    ShippingEndpoints.Postgres,
                    "postgresql",
                    5432,
                    InfrastructureLocalEndpointExposure.HostLoopback,
                    InfrastructureLocalEndpointRole.Data,
                    ShippingConfiguration.PostgresPort)
                .CommandHealth("pg_isready")
                .HealthTiming(TimeSpan.FromSeconds(2), TimeSpan.FromSeconds(1), retries: 30))
        .NonParticipatingWorkloadsByDefault(
            "The local API profile excludes other workloads.",
            [ShippingSources.LocalProfile]));

var targetPlan = InfrastructureTargetDeploymentCompiler.Compile(
    ShippingInfrastructure.Current,
    local.TargetDeployment);
var localRealization = InfrastructureLocalRealizationCompiler.Compile(
    targetPlan.Realization!,
    ShippingEnvironments.Local,
    local.Topology,
    [ShippingConventions.Local]);

ProjectService, ContainerWorkload, ContainerResource, and ReferencedResourceService each produce the physical placement or lifecycle declaration together with its local service. Non-service resources may still be refined with Resource or ReferencedResource. NonParticipatingWorkloadsByDefault expands one attributable closed-world environment decision across canonical workloads not otherwise classified, avoiding an exhaustive parallel workload list while retaining explicit decisions in the fingerprinted deployment manifest.

Canonical RequiresReady(...) declarations are lowered by InfrastructureRealizationCompiler from logical nodes to their exact physical placements. Local compilation projects those obligations into the existing topology consumed by Docker Compose and Aspire, so application code does not repeat physical dependency strings. Aspire continues to own local orchestration and realizes the relationship as WaitFor plus adapter health checks.

Adoption note: topology-level DependsOn(...) and direct ReadyDependencies remain honored as explicit local compatibility overrides. When no matching canonical obligation exists, local compilation emits the warning infra.local.readiness.notCanonical without invalidating the local realization. Migrate an edge to semantic RequiresReady(...) only when the application's readiness actually depends on it. A local startup-order preference is not the same guarantee and should not be promoted into the canonical definition merely to silence the warning.

Adapters can normalize current backend evidence into InfrastructureResourceObservation values. The pure InfrastructureReadinessEvaluator compares those observations with the exact realization and returns a fingerprinted assessment with one decision per physicalized logical node. Missing and unknown evidence fail closed, an unhealthy dependency blocks its subject even when that subject exposes an endpoint, and an incomplete capability realization cannot be made ready by favorable runtime health.

What this package provides

• Portable workload, resource, binding, requirement, and lifecycle semantics.
• Declarative target-facility manifests and generic facility selection.
• Declarative target-deployment manifests and shared physical-realization compilation.
• Deterministic convention resolution with attributable effective configuration.
• Capability closure and boundary-acceptance diagnostics.
• Exact physical placement and evidence-witness documents.
• Exact physical readiness obligations and attributable observation assessment.
• Lifecycle ownership rules for managed, shared, and externally managed resources.
• Local construction realization used by Docker Compose and Aspire projections.

Current boundary

The package is a zero-third-party-dependency semantic core. It does not reference Terraform, Pulumi, Aspire, Azure, AWS, GCP, Kubernetes, or their SDKs. Provider emitters, deployment runners, observation importers, and drift readers belong in dedicated adapters.

A successful realization proves semantic coverage and compiles readiness obligations for the selected target. It is not by itself a deployment receipt, readiness signal, cost estimate, or observation of current backend state; an assessment requires separately attributable observations from an adapter.

Continue

• Internals covers authority boundaries, capability proofs, binding elaboration, local construction, lifecycle ownership, the ARI acceptance case, and planned adapters.
• Language-family architecture explains capability-driven compilation.
• Cohesive.Adapters.DockerCompose projects the local construction document to Compose.
• Cohesive.Adapters.Aspire consumes the same definition and realization for local orchestration.
• Cohesive.Adapters.Aspire.Pulumi contributes exact handoff, apply, and destroy steps to Aspire's deployment pipeline while delegating provider state and reconciliation to an existing Pulumi program.
• Cohesive.Adapters.Pulumi.Azure constructs an exact Azure Durable Task facility inside that program and derives canonical worker access-grant inputs.