Design Principles

Reader question: Why does Calor represent contracts, effects, IDs, and expressions this way?

Calor compiles structured source to C#. Its design makes selected intent available to compiler checks and editing tools. That is a mechanism, not evidence that agents write better programs.

Declared effects expose an interface constraint

An effect declaration lists effects a function permits. The compiler checks the effects it can resolve against that declaration. Callers can inspect the declared interface without rediscovering it from each implementation.

Illustrative function-header fragment, not a complete program:

§F{f001:SaveUser:pub} (User:user) -> bool
  §E{db:rw,net:rw}

The declaration permits database and network access; it does not promise that either happens or specify its ordering, destinations, or business behavior. External libraries need coverage through known effects or manifests. Unresolved calls, interop, and waivers limit enforcement. Use the canonical effect reference for codes and policies.

Contracts state checkable obligations

§Q states a precondition; §S states a postcondition on normal returns. Runtime checking and optional static proof are separate operations with documented limits.

Illustrative function fragment:

§F{f001:Divide:pub} (i32:a, i32:b) -> i32
  §Q (>= a 0)
  §Q (> b 0)
  §S (>= result 0)
  §R (/ a b)

The positive divisor matters: merely excluding zero would allow a negative result for a negative divisor. These predicates describe selected properties, not a complete behavioral specification. Neither contracts nor effect rows prove arbitrary implementation correctness.

See contract syntax and verification guarantees for runtime modes, proof statuses, and unsupported cases.

Stable IDs are optional editing targets

A structural element can carry an explicit ID. A tool can use it instead of a line number when the element moves or is renamed. This works only if edits preserve the ID and avoid duplicates; not every element must have one.

For example, f001 in §F{f001:Divide:pub} identifies the function independently of its display name. Short IDs in documentation are examples, not a production ID policy. See stable identifiers for generation, uniqueness checks, and limitations.

Indentation carries block structure

An opening tag introduces a body indented farther than its parent. Dedenting ends the block. Structural closer tags are rejected; call argument lists and block lambdas have their own delimiters.

This avoids maintaining a separate closing tag for each structural block. It also makes whitespace significant: an edit that moves indentation can change scope. Use formatting and compilation to check changes rather than assuming the visual layout is correct.

Prefix notation makes grouping explicit

Calor expressions place the operator first:

(+ (* a b) (- c d))

This expression fragment groups the same arithmetic as (a * b) + (c - d) in C#. C# also has defined precedence; it is not ambiguous. Calor chooses uniform prefix grouping rather than requiring an infix-precedence table.

Both representations still need parsing into an AST. Symbolic transformation also needs type and runtime semantics: integer overflow, overloaded operators, and floating-point values can invalidate an algebraic rewrite. See expressions for the grammar and Tradeoffs for adoption decisions.