Skip to content

Compatibility Model

Target Architecture — Final-State Design

TemplateCompatibilityService, CompatibilityMatrixService, and DependencyAnalyzerService, together with the TemplateCompatibilityRule, CompatibilityMatrix, and DependencyGraph aggregates, are the planned ConnectSoft.Factory.Templates.* decomposition. They operate over the real ConnectSoft.Template.* and ConnectSoft.Extensions.* assets.

The Compatibility Model is the platform's safety system. Before any generation, it answers: can these templates, at these versions, with this set of libraries, on this runtime, actually work together? It turns the implicit knowledge that usually lives in senior engineers' heads — "the NHibernate persistence flavor needs this Saas package, this template requires .NET 10, these two libraries conflict" — into explicit, machine-evaluable rules. This is what lets agents compose solutions autonomously without producing broken combinations.

The three aggregates

erDiagram
    TemplateCompatibilityRule }o--|| CompatibilityMatrix : "rolls up into"
    DependencyGraph }o--|| CompatibilityMatrix : "feeds"
    TemplateCompatibilityRule {
        string ruleId
        string subjectRef
        string constraintKind
        string expression
    }
    CompatibilityMatrix {
        string matrixId
        string scope
        string computedAt
    }
    DependencyGraph {
        string graphId
        int nodeCount
        int conflictCount
    }
Hold "Alt" / "Option" to enable pan & zoom

TemplateCompatibilityRule

A TemplateCompatibilityRule is a single declarative constraint owned by a template or library version. Each rule has a subject (the template/library version it belongs to), a constraint kind, and an expression. Constraint kinds include:

  • RuntimeRequires — minimum/maximum runtime (e.g. >= net10.0).
  • LibraryRequires — a required library capability or version range (e.g. requires ConnectSoft.Extensions.Saas.Abstractions >= 2.0).
  • LibraryConflictsWith — an incompatible package/version (e.g. cannot combine MessagingModel.MassTransit and MessagingModel.NServiceBus).
  • TemplateConflictsWith — a template that cannot be composed in the same solution.
  • ParameterConstraint — cross-parameter rules surfaced from the parameter schema.

Rules are versioned with their subject so compatibility for a pinned version is reproducible. See Aggregate Roots.

CompatibilityMatrix

The CompatibilityMatrix is the rolled-up, queryable answer for a given scope (a template version, a library version, or a candidate solution composition). CompatibilityMatrixService computes it by evaluating all applicable TemplateCompatibilityRules against the DependencyGraph, caching the result in Redis for fast pre-generation checks and persisting the authoritative copy in the registry store. See Aggregate Roots.

DependencyGraph

The DependencyGraph (owned by the Library Registry and maintained by DependencyAnalyzerService) is the directed graph of library-to-library dependencies with resolved version ranges. It is the substrate the matrix is computed over — transitive closures, conflict detection, and impact analysis all run on it. See Aggregate Roots.

Compatibility evaluation

Evaluation is exposed through POST /templates/{templateId}/compatibility/evaluate and POST /libraries/compatibility/evaluate (see APIs), and is also invoked internally by the Scaffold Engine before every execution.

flowchart TB
    Request["Evaluate request<br/>(templates + libraries + runtime)"] --> Resolve["DependencyAnalyzerService<br/>resolve transitive closure"]
    Resolve --> Graph["DependencyGraph"]
    Graph --> Conflict["Detect version conflicts"]
    Request --> Rules["Collect TemplateCompatibilityRules"]
    Rules --> Eval["CompatibilityMatrixService evaluate"]
    Conflict --> Eval
    Eval --> Matrix["CompatibilityMatrix"]
    Matrix --> Decision{"Compatible?"}
    Decision -->|yes| Pass["Proceed to generation"]
    Decision -->|no| Report["Structured incompatibility report"]
    Report --> Advisor["PackageUpgradeAdvisorService<br/>suggest resolutions"]
Hold "Alt" / "Option" to enable pan & zoom

The evaluation:

  1. Resolves the requested template and library versions to their transitive dependency closure via the DependencyGraph.
  2. Detects conflicts — duplicate packages at incompatible versions, diamond conflicts, or banned combinations.
  3. Collects and evaluates rules — every TemplateCompatibilityRule in scope is checked (runtime, required capabilities, conflicts).
  4. Produces a CompatibilityMatrix — a pass/fail with, on failure, a structured report listing each violated rule and the offending versions.
  5. Suggests resolutions — on failure, PackageUpgradeAdvisorService proposes version bumps or substitutions that would satisfy the constraints.

A failed evaluation emits CompatibilityEvaluated with the failure detail so agents can self-correct (pick a different library version, switch the persistence flavor) and the Observability & Feedback platform can track compatibility friction over time.

Worked example

An agent plans a multi-tenant booking service and requests:

  • MicroserviceTemplate 3.2.0 (requires >= net10.0)
  • ConnectSoft.Extensions.PersistenceModel.PostgreSQL 4.1.0
  • ConnectSoft.Extensions.MessagingModel.MassTransit 5.0.0
  • ConnectSoft.Extensions.Saas.AspNetCore 2.3.0

Evaluation finds that Saas.AspNetCore 2.3.0 requires Saas.Abstractions >= 2.0, pulls it into the closure, confirms PostgreSQL persistence satisfies the template's LibraryRequires for relational persistence, and verifies no LibraryConflictsWith rule fires (no second messaging stack present). The matrix returns compatible, and the Scaffold Engine proceeds. Had the agent also requested MessagingModel.NServiceBus, the LibraryConflictsWith rule would fail the evaluation and the advisor would recommend removing one messaging stack.

Upgrade and impact analysis

The same model powers upgrades. When a new TemplateVersion or LibraryVersion is published, TemplateCompatibilityWorker recomputes affected matrices. TemplateUpgradeService and PackageUpgradeAdvisorService use the dependency graph to find every dependent product and produce a TemplateUpgradePlan describing what must change. This makes platform-wide upgrades — for example moving a library to a new major version — a governed, analyzable operation rather than a risky guess.

Why it matters

  • Autonomy — agents compose solutions safely without a human verifying every combination.
  • Governance — banned combinations and runtime floors are enforced declaratively and auditable.
  • Reusability — capability-based requirements let agents satisfy a need with any compatible library.
  • Traceability — each CompatibilityEvaluated event records exactly what was checked and why it passed or failed, in the canonical event envelope.