Error Handling

This chapter specifies error handling semantics in Clef, including the relationship between compile-time error propagation through tooling and runtime error handling in compiled applications.

Overview

Clef takes a fundamentally different approach to error handling than managed F#:

Design Principle: Errors are values, not control flow. The type system encodes fallibility explicitly, making error handling visible and verifiable at compile time.

The Dual Nature of Error Handling

Clef error handling operates at two distinct levels:

1. Application Runtime: How compiled Fidelity framework applications handle errors during execution
2. Tooling Integration: How Clef Compiler Service (CCS) propagates errors through the Language Server Protocol to editors like Lattice

These two domains have different requirements and constraints, but must remain coherent.

Application Runtime Error Handling

The Result Type

The Result<'T, 'E> type is the primary mechanism for representing operations that may fail:

type Result<'T, 'E> =
    | Ok of 'T
    | Error of 'E

Operations that can fail return Result values rather than raising exceptions:

// Managed F# style (NOT used in Clef applications)
let divide x y =
    if y = 0 then raise (DivideByZeroException())
    else x / y

// Clef style
let divide x y : Result<int, DivisionError> =
    if y = 0 then Error DivisionByZero
    else Ok (x / y)

Native Result Operations

The operations below use the canonical Result<'a, 'e> identity and independently quantified NTU payload types:

Result.map : ('a -> 'b) -> Result<'a, 'e> -> Result<'b, 'e>
Result.mapError : ('e -> 'f) -> Result<'a, 'e> -> Result<'a, 'f>
Result.bind : ('a -> Result<'b, 'e>) -> Result<'a, 'e> -> Result<'b, 'e>
Result.defaultValue : 'a -> Result<'a, 'e> -> 'a
Result.defaultWith : ('e -> 'a) -> Result<'a, 'e> -> 'a
Result.iter : ('a -> unit) -> Result<'a, 'e> -> unit
Result.isOk : Result<'a, 'e> -> bool
Result.isError : Result<'a, 'e> -> bool

Explicit type arguments are ordered Result.map<'a, 'b, 'e>, Result.mapError<'a, 'e, 'f>, Result.bind<'a, 'b, 'e>, Result.defaultValue<'a, 'e>, Result.defaultWith<'a, 'e>, Result.iter<'a, 'e>, Result.isOk<'a, 'e> and Result.isError<'a, 'e>.

Their case behavior is:

let map mapper input =
    match input with
    | Ok value -> Ok (mapper value)
    | Error error -> Error error

let mapError mapper input =
    match input with
    | Ok value -> Ok value
    | Error error -> Error (mapper error)

let bind binder input =
    match input with
    | Ok value -> binder value
    | Error error -> Error error

let defaultValue fallback input =
    match input with
    | Ok value -> value
    | Error _ -> fallback

let defaultWith fallback input =
    match input with
    | Ok value -> value
    | Error error -> fallback error

let iter action input =
    match input with
    | Ok value -> action value
    | Error _ -> ()

let isOk input =
    match input with
    | Ok _ -> true
    | Error _ -> false

let isError input =
    match input with
    | Ok _ -> false
    | Error _ -> true

Supplied operands SHALL be evaluated eagerly in source evaluation order. The callback SHALL be invoked once only for the indicated case. An untouched payload SHALL retain its value, dimensional type and resource identity; changing the other case’s type does not authorize a conversion of that payload. The enclosing Result may require a different realized layout and is not required to retain the same allocation identity. A bind callback’s Result is returned with its case unchanged.

For defaultValue, the fallback expression is evaluated even when the input is Ok. For defaultWith, the fallback function expression is evaluated on both cases, but the function is invoked only on Error, with that error payload as one logical argument. This is an error handler, not the unit thunk used by Option.defaultWith. For iter, the action expression is evaluated on both cases; only Ok invokes it, with the success payload as one logical argument. The action and the operation return unit. Unit-valued and callable payloads retain these logical argument boundaries.

The mapping, binding, defaulting and iteration operations have two operands. Direct applications and backward pipes evaluate the fallback or callback expression before the Result expression; forward pipes evaluate the Result expression first. When the result type 'a of defaultValue or defaultWith is itself a function, later arguments apply that selected or produced function after the two-operand operation boundary. All supplied source arguments, including those later arguments, SHALL evaluate before case selection or fallback invocation. Extra application of the unit result of iter is a type error.

isOk and isError each evaluate their single Result operand eagerly and once, including when applied through a pipe. They SHALL observe only the case tag; neither operation extracts a payload or invokes a callable payload. Constructing the supplied Result still evaluates its payload expression according to ordinary source evaluation order. Each predicate returns bool, so extra application is a type error. Bare aliases of either predicate SHALL instantiate both payload types independently at each admitted use.

Partial applications SHALL retain the supplied fallback or callback value at formation while preserving the identities and obligations of its captured storage. Bare aliases SHALL instantiate the quantified types independently at each admitted use. Binder input and output share the same error type; changing it requires an explicit operation such as mapError.

Baker SHALL elaborate these operations into typed case discrimination and, where required by the operation, case-specific payload extraction, callback application and Result construction before Alex witnesses the graph. Payload reads SHALL occur only within their established case. Joint dimensional, lifetime and resource constraints remain attached to the actual participating values. The operations introduce no new allocation rule: placement follows the settled DU lifetime contract.

Standard Error Types

Clef defines standard error types for common failure modes:

type ArithmeticError =
    | DivisionByZero
    | Overflow
    | Underflow

type IndexError =
    | OutOfBounds of index: int * length: int

type ParseError =
    | InvalidFormat of input: string * expected: string
    | UnexpectedEnd

type IOError =
    | NotFound of path: string
    | PermissionDenied of path: string
    | DeviceError of code: int

Note: The exact set of standard error types is subject to further specification as the standard library matures.

The voption Type

For optional values where absence is not an error, voption<'T> (ValueOption) provides a null-free representation:

type voption<'T> =
    | ValueSome of 'T
    | ValueNone

The voption<'T> type has an explicit discriminator with no null representation.

// Looking up a value that may not exist
let tryFind key (map: Map<'K, 'V>) : voption<'V> =
    match Map.tryFind key map with
    | ValueSome v -> ValueSome v
    | ValueNone -> ValueNone

Result Propagation

Clef provides computation expression syntax for Result propagation:

let result {
    let! x = tryParseInt "42"
    let! y = tryParseInt "17"
    return x + y
}

This is equivalent to explicit binding:

match tryParseInt "42" with
| Error e -> Error e
| Ok x ->
    match tryParseInt "17" with
    | Error e -> Error e
    | Ok y -> Ok (x + y)

Try/With Syntax Compatibility

Clef preserves try/with/finally syntax for compatibility with standard F# tooling:

try
    riskyOperation()
with
| :? SomeException as e -> handleError e

However, the semantics differ:

• In Clef, try/with may be used for effect handling (delimited continuations) rather than exception catching
• The exact semantics depend on the effect system specification
• Code using try/with for exception handling must be migrated to Result-based patterns for native compilation

Tooling Note: Lattice and other editors will parse try/with expressions normally. CCS may emit warnings when exception-style patterns are detected, guiding migration to Result-based alternatives.

Null-Freedom

Clef is null-free by construction. The following are compile-time errors:

let x : string = null           // ERROR: null literal not available
let y = Unchecked.defaultof<_>  // ERROR for reference types in most contexts
 

This eliminates entire classes of runtime errors:

Tooling Integration

CCS Error Propagation

Clef Compiler Service (CCS) must propagate errors through the tooling stack in a format compatible with existing F# tooling infrastructure.

Diagnostic Format

CCS diagnostics follow the F# compiler diagnostic format:

filepath(line,col)-(line,col): severity code: message

For example:

src/Main.clef(12,5)-(12,15): error CCS8010: 'null' is not permitted in Clef; use 'ValueNone' for an absent value

Error Codes

CCS uses error codes in the CCS8xxx range to distinguish native-specific diagnostics:

The CCS code table

Decision D3 of the dimensional hardening (2026-09-04): every diagnostic the compiler service reports carries a code in the CCS series; the FS prefix is retired. Codes are allocated inside the blocks above and never reassigned. Inherited lexer and parser diagnostics keep their F# number under the CCS prefix (FS0058 becomes CCS0058); the block CCS0000–CCS0999 is reserved for that family.

LSP Compatibility

CCS implements the Language Server Protocol for editor integration. Key considerations:

1. Diagnostic Publishing: Errors are published via textDocument/publishDiagnostics in standard LSP format
2. Code Actions: Quick fixes (e.g., “Insert the explicit conversion”, “Add the measure annotation”) are provided via textDocument/codeAction
3. Hover Information: Type information displays native types

Lattice Integration Model

The multi-target editor model is well established in the F# ecosystem: Ionide routes a single editing experience across several F# compilation backends.

Lattice, the Clef editor tooling, follows this model:

Lattice ←→ LSP ←→ CCS ←→ Composer Compiler ←→ MLIR/LLVM

Extension Points

CCS provides extension points for Lattice integration:

1. Project Recognition: .fidproj files identify Clef projects
2. Target Selection: Lattice can route to CCS when native compilation is detected
3. Shared Parsing: Syntax parsing uses standard F# lexer/parser for compatibility
4. Semantic Divergence: Type checking and code generation use native semantics

Compatibility Considerations

To maintain compatibility with the broader F# ecosystem:

1. Syntax Compatibility: Clef code parses as valid F# syntax
2. Type Notation: Types are expressed using standard F# type notation
3. Error Format: Diagnostics follow F# compiler conventions
4. Incremental Adoption: Projects can mix managed and native targets during migration

Editor Experience

The design-time experience for Clef should be consistent with managed F#:

Error Handling Patterns

Railway-Oriented Programming

Clef encourages railway-oriented programming with Result:

let processOrder orderId =
    orderId
    |> validateOrderId
    |> Result.bind fetchOrder
    |> Result.bind validateInventory
    |> Result.bind processPayment
    |> Result.bind shipOrder

Error Aggregation

For operations that may produce multiple errors:

type ValidationErrors = ValidationErrors of ValidationError list

let validateAll validators input =
    validators
    |> List.map (fun v -> v input)
    |> List.fold aggregateErrors (Ok input)

Partial Success

For operations where partial results are meaningful:

type PartialResult<'T, 'E> =
    | Complete of 'T
    | Partial of 'T * 'E list
    | Failed of 'E list

Grammar

result-type := Result < type , type >

voption-type := voption < type >

result-expr :=
    Ok expr
    Error expr

voption-expr :=
    ValueSome expr
    ValueNone

result-bind := let! pattern = expr in expr

result-return := return expr

Diagnostics

Null-freedom is by construction and has exactly one diagnostic, CCS8010 (the null keyword is not permitted, Types and Type Constraints). There is no second null diagnostic: no type “supports null”, no value is uninitialised, and Unchecked.defaultof is BCL surface rejected as such. The codes this chapter contributes:

A warning is promoted to an error under the --warnaserror policy, the rule every warning in the framework follows (the FPGA timing budget’s CCS0100 is the reference case).

Areas Requiring Further Specification

The following areas require additional design work:

1. Effect System Integration: How Result interacts with algebraic effects and delimited continuations
2. Async/Concurrent Errors: Error propagation in concurrent and asynchronous contexts
3. Interop Boundaries: Error translation at FFI boundaries with C libraries
4. Panic vs. Error: Distinction between recoverable errors (Result) and unrecoverable panics
5. Stack Traces: Diagnostic information for debugging without managed exception infrastructure
6. Tooling PR Strategy: Concrete changes needed for Lattice/FSAC to support CCS