Effect Manifests: .NET Ecosystem Coverage

How Calor knows the effects of .NET framework and ecosystem library calls

When Calor code calls into .NET libraries, the compiler needs to know what side effects those calls have. Effect manifests provide this information — JSON files that map types and methods to their effects.

The Problem

Calor enforces that every function declares its effects:

§F{f001:SaveUser:pub}
  §O{void}
  §E{db:w,cw}
  §C{DbContext.SaveChanges} §/C
  §C{ILogger.LogInformation} §A STR:"User saved" §/C
§/F{f001}

But how does the compiler know that DbContext.SaveChanges has effect db:w and ILogger.LogInformation has effect cw? Without this knowledge, every external call would be flagged as Unknown.

What's Covered

Calor ships with 14 embedded manifest files covering ~170 types across three tiers:

BCL Types (10 manifests)

Core .NET types the compiler has always known about, plus recent additions:

Framework Interfaces (Tier B)

The most commonly used .NET framework types — these are the calls AI agents generate most often:

Ecosystem Libraries (4 manifests)

Popular NuGet packages that AI agents commonly generate code for:

How Resolution Works

When the compiler encounters §C{DbContext.SaveChanges}, it:

1. Parses the target: type = DbContext, method = SaveChanges
2. Maps the short name: DbContext → Microsoft.EntityFrameworkCore.DbContext
3. Looks up the manifest: finds bcl-framework-interfaces.calor-effects.json
4. Returns the effect: db:w

For instance calls like §C{client.GetAsync} (from converted C# code), the compiler also checks variable declarations — if §B{client} §NEW{HttpClient}, it resolves client → System.Net.Http.HttpClient → net:rw.

Resolution Priority

Manifests are loaded in priority order (higher overrides lower):

Adding Custom Manifests

For types not covered by the built-in manifests, create a .calor-effects.json file in your project root:

{
  "version": "1.0",
  "description": "Effects for MyApp types",
  "mappings": [
    {
      "type": "MyApp.Services.EmailService",
      "methods": {
        "SendAsync": ["net:w"],
        "ValidateAddress": []
      }
    },
    {
      "type": "MyApp.Data.CacheService",
      "methods": {
        "Get": ["db:r"],
        "Set": ["db:w"],
        "Remove": ["db:w"]
      }
    }
  ]
}

Manifest Schema

Each manifest supports:

• methods — Per-method effects (or "*" wildcard for all methods)
• getters / setters — Property accessor effects
• constructors — Constructor effects (keyed by parameter signature)
• defaultEffects — Fallback for any method not explicitly listed
• namespaceDefaults — Default effects for entire namespaces

Effect Code Reference

Broader effects encompass narrower ones: fs:rw covers both fs:r and fs:w.

CLI Tools

Resolve effects for a method

calor effects resolve Console.WriteLine    # → cw
calor effects resolve DbContext.SaveChanges # → db:w
calor effects resolve ILogger.Log          # → cw
calor effects resolve JsonSerializer.Serialize # → [pure]

Validate manifests

calor effects validate
calor effects validate --project ./src

List all covered types

calor effects list
calor effects list --type ILogger

Reducing Manifest Burden with IL Analysis

For methods in your own assemblies (repositories, services, handlers), you can enable cross-assembly IL analysis instead of writing manifests. The compiler traces through the IL of your referenced DLLs and discovers effects automatically.

<PropertyGroup>
  <CalorEnableILAnalysis>true</CalorEnableILAnalysis>
</PropertyGroup>

With IL analysis enabled, the compiler can trace UserRepository.Save() → DbCommand.ExecuteNonQuery() → db:w without a custom manifest for UserRepository. Manifests still provide the seeds (DbCommand.ExecuteNonQuery → db:w), and IL analysis propagates them through your code.

When to use each:

See the IL analysis guide for details.

Architecture: Why Manifests?

Calor is designed for AI agents as primary code authors. When an agent generates Calor code that calls DbContext.SaveChanges(), the compiler needs to verify the function declares §E{db:w}. Without manifests, every external call would be Unknown — defeating the purpose of effect enforcement.

Manifests are the primary resolution mechanism because they're curated, precise, and cover the interface-heavy patterns (ILogger, IConfiguration) where IL analysis has a 0% resolution rate. IL analysis complements manifests by handling concrete call chains in user code — the gap between "framework types covered by manifests" and "Unknown."