Section 10: Error Handling and Failure Guarantees¶
TECHSPEC-10 — Section 10 · Version 0.1 · Status: Initial Draft
Status: draft. This section is an Initial Draft (Section 57 is a Working Register). It describes intended or proposed behavior, not a finalized, implemented language rule. Do not treat examples here as normative.
1. Failure Philosophy¶
Failures must be explicit, typed, and observable.
The language must not silently ignore errors, convert failures into success values, or assume that an operation succeeded because no error was reported.
2. Result Type¶
Operations that can fail must return a Result type.
A Result contains exactly one of two outcomes:
SUCCESS: The operation completed successfully.ERROR: The operation failed with a declared error value.
Example:
FUNCTION divide(
numerator: Decimal,
denominator: Decimal
) -> Result<Decimal, DivisionError>
IMPLEMENTATION:
IF denominator == 0:
RETURN ERROR(DivisionError.DivideByZero)
END IF
RETURN SUCCESS(numerator / denominator)
END FUNCTION
Rules: - A Result must always contain either success or failure. - Callers must explicitly handle or propagate the Result. - Errors cannot be silently discarded. - A function must not return SUCCESS when its declared operation failed. - Error types must be declared in the function's return type.
3. Error Types¶
Errors must have defined types and meanings.
Example:
Rules: - Expected failures must use declared error types. - Error values may contain structured diagnostic information. - Error causes must be preserved when errors are propagated. - Error messages must not be used as substitutes for typed error values. - Sensitive information must not be exposed through error messages.
4. Failure Propagation¶
Failures must remain visible as they move through function calls.
Rules: - Callers must handle a Result or explicitly propagate its error. - Propagated errors must remain identifiable. - Converting one error type into another requires an explicit mapping. - Unknown failures must not be silently converted into ordinary errors. - A caller cannot claim success while an unhandled failure remains.
5. Recovery¶
Recovery must establish a valid program state before execution continues.
Rules: - Recovery behavior must be explicit. - Failed operations must not leave partially modified state unless that state is permitted by the contract. - Recovery must preserve required invariants. - Retrying an operation must account for whether the original operation may already have taken effect. - Operations with external side effects must not be assumed safe to retry. - Recovery failure must also be reported.
6. Unexpected Failures¶
Not every failure can be predicted in advance.
The language must distinguish between:
- Declared errors: Expected failure conditions defined by the function.
- Runtime faults: Failures detected by the runtime environment.
- External failures: Failures originating from systems outside the program.
- Internal faults: Unexpected failures indicating a violated runtime or language guarantee.
Rules: - Unexpected failures must not be silently swallowed. - Runtime faults must produce diagnostic information where possible. - Internal faults must not be represented as successful results. - Programs must define their permitted response to unrecoverable failures.
7. Compiler and Runtime Responsibilities¶
The compiler and runtime must: - Enforce explicit Result handling. - Verify declared error types. - Detect discarded or unhandled errors. - Preserve error causes during propagation. - Validate recovery paths against function contracts. - Report unexpected failures distinctly from declared errors.
8. Design Goal¶
AI agents must never be able to mistake an attempted operation for a successful one.
Every failure must remain visible, traceable, and distinguishable from successful execution.
Source and related sections¶
Source file: TECHSPEC-10.md (preserved in source-original/LANG/). See the specification index, the glossary, and the cross-reference index.