Effects

Effects declare the side effects a function may have. This is unique to Calor - traditional languages leave side effects implicit.

Why Declare Effects?

In traditional languages, you must read the entire implementation to know if a function:

Writes to console
Reads files
Makes network calls
Modifies a database

Calor requires explicit effect declarations:

Plain Text

§F{f001:SaveUser:pub}
  §I{User:user}
  §O{bool}
  §E{db:rw,net:rw}        // Declares: database and network operations
  // ...

Now an agent knows immediately what side effects to expect.

Effect Syntax

Plain Text

§E{code1,code2,...}
§E{}                      // No effects (pure function)

Place the effect declaration after the output type:

Plain Text

§F{id:name:vis}
  §I{...}
  §O{...}
  §E{effects}             // Here
  §Q ...
  §S ...
  // body

Effect Codes

Code	Effect	Description	C# Examples
`cw`	Console write	Output to console	`Console.WriteLine()`
`cr`	Console read	Input from console	`Console.ReadLine()`
`fs:r`	Filesystem read	Read from filesystem	`File.ReadAllText()`
`fs:w`	Filesystem write	Write to filesystem	`File.WriteAllText()`
`fs:rw`	Filesystem read/write	Read and write filesystem	`File.Copy()`
`net:r`	Network read	HTTP GET, etc.	`HttpClient.GetStringAsync()`
`net:w`	Network write	HTTP POST, etc.	`HttpClient.PostAsync()`
`net:rw`	Network read/write	HTTP operations	`HttpClient.SendAsync()`
`db:r`	Database read	Database queries	`SELECT` queries
`db:w`	Database write	Database mutations	`INSERT/UPDATE/DELETE`
`db:rw`	Database read/write	Database operations	ORM calls

Examples

Pure Function (No Effects)

Plain Text

§F{f001:Add:pub}
  §I{i32:a}
  §I{i32:b}
  §O{i32}
  // No §E means pure - no side effects
  §R (+ a b)

Or explicitly:

Plain Text

§F{f001:Add:pub}
  §I{i32:a}
  §I{i32:b}
  §O{i32}
  §E{}                    // Explicitly no effects
  §R (+ a b)

Console Output

Plain Text

§F{f001:Greet:pub}
  §I{str:name}
  §O{void}
  §E{cw}                  // Console write
  §P name

File Operations

Plain Text

§F{f001:CopyFile:pub}
  §I{str:source}
  §I{str:dest}
  §O{bool}
  §E{fs:rw}               // Filesystem read and write
  // ...

Network Call

Plain Text

§F{f001:FetchData:pub}
  §I{str:url}
  §O{str!str}
  §E{net:rw}              // Network operations
  // ...

Database with Logging

Plain Text

§F{f001:CreateUser:pub}
  §I{User:user}
  §O{i32}
  §E{db:rw,cw}            // Database and console (for logging)
  // ...

Multiple Effects

Plain Text

§F{f001:ProcessOrder:pub}
  §I{Order:order}
  §O{bool}
  §E{db:rw,net:rw,fs:w,cw} // Database, network, filesystem write, console write
  // ...

Effect Patterns

Read-Only vs Read-Write

Plain Text

// Read-only file operation
§F{f001:LoadConfig:pub}
  §I{str:path}
  §O{Config}
  §E{fs:r}                // Only filesystem read
  // ...

// Read-write file operation
§F{f002:UpdateConfig:pub}
  §I{str:path}
  §I{Config:config}
  §O{void}
  §E{fs:rw}               // Filesystem read and write
  // ...

Interactive Console

Plain Text

§F{f001:Prompt:pub}
  §I{str:question}
  §O{str}
  §E{cw,cr}               // Console write and read
  §P question
  §R §C{Console.ReadLine} §/C

Benefits for Agents

1. Filtering by Effect

"Find all functions that access the database":

Plain Text

// Agent searches for §E{..db..}

2. Refactoring Safety

"This function should be pure, but it has effects":

Plain Text

§F{f001:Calculate:pub}
  §O{i32}
  §E{cw}                  // Wait, why is Calculate logging?

3. Testing Strategy

Functions with no effects: Unit test directly
Functions with cw/cr: Mock console
Functions with fs:r/fs:w/fs:rw: Mock filesystem
Functions with net:r/net:w/net:rw: Mock HTTP
Functions with db:r/db:w/db:rw: Mock database

4. Composition Analysis

Plain Text

// If f1 calls f2, f1's effects must include f2's effects
§F{f001:ProcessAndSave:pub}
  §E{db:rw,cw}            // Must include f002's effects
  §C{f002:Process} ... §/C

§F{f002:Process:pri}
  §E{cw}                  // Has console write effect
  // ...

Effect Checking

Effect enforcement is on by default for compile, build, and watch workflows. The compiler reports:

Missing effect: a function uses an effect it did not declare
Propagation: a caller does not include a callee's effects
Unknown calls: interop and unmodeled calls become Assumed and propagate (Calor0419) instead of silently becoming pure
Delegate calls: invoking a delegate stored in a parameter, binding, or field is an error (Calor0418) unless permissive mode is explicitly chosen
Variance: overrides and interface implementations may not declare more effects than their base contracts (Calor0420 and Calor0421)

Collection mutators such as Add, Remove, Clear, Insert, Sort, and CopyTo are not on the known-pure list. Use --no-enforce-effects only as an explicit migration waiver. --permissive-effects assumes unknown calls are pure and voids the effect guarantee; review packets disclose that waiver on their first line.

Effect manifests and package import - External call coverage
Adoption Playbook - Applying effects in an existing solution