Runtime contract guard kernel
This commit is contained in:
328
notes/contract-design.md
Normal file
328
notes/contract-design.md
Normal file
@@ -0,0 +1,328 @@
|
||||
# Contract Kernel Design
|
||||
|
||||
## Status
|
||||
|
||||
Implemented. The contract system uses a configurable kernel defined in
|
||||
`lib/base.tri`. All contract logic lives in pure tree calculus.
|
||||
|
||||
## Goals
|
||||
|
||||
1. **User code stays ergonomic.** `@`/`=@` syntax remains. Calling a guarded
|
||||
function looks the same as calling an unguarded one.
|
||||
2. **No stringly-dynamic failures.** A contract boundary returns a structured
|
||||
`Result`. The kernel decides whether to abort, resume with a replacement,
|
||||
log, or otherwise transform the result.
|
||||
3. **All evaluation logic in pure tree calculus.** The evaluator does not treat
|
||||
contracts specially; contracts are ordinary functions and the desugarer
|
||||
emits ordinary tricu code.
|
||||
4. **Optional contract enforcement.** A CLI/REPL flag can disable contract
|
||||
syntax entirely by stripping annotations at desugar time.
|
||||
5. **Configurable failure semantics.** A global kernel, supplied by the user
|
||||
via CLI/REPL, determines how contract failures are handled for the
|
||||
session.
|
||||
|
||||
## Core idea
|
||||
|
||||
A contract annotation on a definition desugars into a runtime guard. The
|
||||
runtime guard applies a contract predicate to a value and passes the resulting
|
||||
`Result` to the current `kernel`. The `kernel` returns another `Result`, which
|
||||
the wrapper inspects:
|
||||
|
||||
- `ok value` means the guard succeeded; continue with `value`.
|
||||
- `err msg` means the guard failed; abort and propagate the error.
|
||||
|
||||
The default kernel is the identity on the contract `Result`. A custom kernel
|
||||
can transform failures into successes, wrap diagnostics, or log failures before
|
||||
aborting.
|
||||
|
||||
## Kernel
|
||||
|
||||
### Signature
|
||||
|
||||
```tricu
|
||||
kernel contract value result -> Result
|
||||
```
|
||||
|
||||
- `contract`: the contract predicate being checked.
|
||||
- `value`: the unevaluated original value passed to the contract.
|
||||
- `result`: the `Result` produced by evaluating `contract value t`.
|
||||
|
||||
### Default kernel
|
||||
|
||||
`lib/base.tri` defines both `defaultKernel` and the active `kernel`:
|
||||
|
||||
```tricu
|
||||
defaultKernel = (contract value result :
|
||||
matchResult
|
||||
(msg rest : err msg rest)
|
||||
(v rest : ok v rest)
|
||||
result)
|
||||
|
||||
kernel = defaultKernel
|
||||
```
|
||||
|
||||
The runner may rebind `kernel` to a different value before evaluating user
|
||||
code (e.g. via `--contract-kernel`). Because `withContract` looks up `kernel`
|
||||
dynamically at application time, rebinding it changes the behaviour of every
|
||||
contract boundary.
|
||||
|
||||
### Skip kernel
|
||||
|
||||
Resume with the original value whenever a contract fails:
|
||||
|
||||
```tricu
|
||||
skipKernel = (contract value result :
|
||||
matchResult
|
||||
(msg rest : ok value rest)
|
||||
(v rest : ok v rest)
|
||||
result)
|
||||
```
|
||||
|
||||
### Logging kernel
|
||||
|
||||
Abort but also emit a log entry:
|
||||
|
||||
```tricu
|
||||
loggingKernel = (contract value result :
|
||||
matchResult
|
||||
(msg rest : pair (logMsg msg) (err msg rest))
|
||||
(v rest : ok v rest)
|
||||
result)
|
||||
```
|
||||
|
||||
### Resume-with-default kernel
|
||||
|
||||
```tricu
|
||||
resumeWithZero = (contract value result :
|
||||
matchResult
|
||||
(msg rest : ok 0 rest)
|
||||
(v rest : ok v rest)
|
||||
result)
|
||||
```
|
||||
|
||||
## Runtime guard primitive
|
||||
|
||||
`withContract` is the primitive emitted by the desugarer:
|
||||
|
||||
```tricu
|
||||
withContract = (contract value :
|
||||
kernel contract value (contract value t))
|
||||
```
|
||||
|
||||
`check` is a convenience wrapper that extracts the value or the diagnostic
|
||||
message:
|
||||
|
||||
```tricu
|
||||
check contract value =
|
||||
matchResult
|
||||
(msg _ : msg)
|
||||
(v _ : v)
|
||||
(withContract contract value)
|
||||
```
|
||||
|
||||
## Desugaring
|
||||
|
||||
Desugaring runs **before** import selection so that names introduced by the
|
||||
desugarer (`withContract`, `matchResult`, `err`, `ok`, etc.) are included in
|
||||
the selected exports of imported modules. This ensures that a module using
|
||||
contract annotations imports everything it needs from `base`/`prelude`.
|
||||
|
||||
### Phantom annotations
|
||||
|
||||
```tricu
|
||||
add @nat? @nat? =@nat? addRaw
|
||||
```
|
||||
|
||||
desugars to:
|
||||
|
||||
```tricu
|
||||
add = (x y :
|
||||
matchResult
|
||||
(msg _ : \_ : err msg t)
|
||||
(x' _ :
|
||||
matchResult
|
||||
(msg _ : err msg t)
|
||||
(y' _ :
|
||||
matchResult
|
||||
(msg _ : err msg t)
|
||||
(r _ : r)
|
||||
(withContract nat? (addRaw x' y')))
|
||||
(withContract nat? y))
|
||||
(withContract nat? x))
|
||||
```
|
||||
|
||||
The first failure continuation is absorbing (`\_ : err msg t`) because `add`
|
||||
is curried and a failure on the first argument should consume the second
|
||||
argument without producing garbage.
|
||||
|
||||
`addRaw` is the locally-let-bound raw helper, as in the current phantom
|
||||
implementation.
|
||||
|
||||
### Named-binder annotations
|
||||
|
||||
```tricu
|
||||
safeDiv a@nat? b@(andC nat? nonZero?) =@nat? div a b
|
||||
```
|
||||
|
||||
desugars to:
|
||||
|
||||
```tricu
|
||||
safeDiv = (a b :
|
||||
matchResult
|
||||
(msg _ : \_ : err msg t)
|
||||
(a' _ :
|
||||
matchResult
|
||||
(msg _ : err msg t)
|
||||
(b' _ :
|
||||
matchResult
|
||||
(msg _ : err msg t)
|
||||
(r _ : r)
|
||||
(withContract nat? (div a' b')))
|
||||
(withContract (andC nat? nonZero?) b))
|
||||
(withContract nat? a))
|
||||
```
|
||||
|
||||
### No return contract
|
||||
|
||||
```tricu
|
||||
head xs@(nonEmptyListOf anyC) =@anyC headRaw
|
||||
```
|
||||
|
||||
desugars to:
|
||||
|
||||
```tricu
|
||||
head = (xs :
|
||||
matchResult
|
||||
(msg _ : err msg t)
|
||||
(xs' _ :
|
||||
matchResult
|
||||
(msg _ : err msg t)
|
||||
(r _ : r)
|
||||
(withContract anyC (headRaw xs')))
|
||||
(withContract (nonEmptyListOf anyC) xs))
|
||||
```
|
||||
|
||||
### No annotations
|
||||
|
||||
Definitions without `@`/`=@` are emitted unchanged.
|
||||
|
||||
## Failure propagation
|
||||
|
||||
When a non-final argument contract fails, the wrapper returns a function that
|
||||
absorbs the next argument and then returns the failed `Result`. This prevents
|
||||
partial-application accidents like `gt? "the" 3` reducing to a garbage number.
|
||||
|
||||
When the final argument or result contract fails, the wrapper returns
|
||||
`\msg -> err msg t`, which is the failure constructor awaiting its `rest`
|
||||
slot.
|
||||
|
||||
## Skip-contracts flag
|
||||
|
||||
When the `--skip-contracts` flag is set, the desugarer strips all `@`/`=@`
|
||||
annotations and emits the raw function body. This is faster than running the
|
||||
skip kernel because no contract code is generated at all.
|
||||
|
||||
### CLI
|
||||
|
||||
```bash
|
||||
tricu eval --skip-contracts program.tri
|
||||
tricu repl --skip-contracts
|
||||
```
|
||||
|
||||
### REPL
|
||||
|
||||
```tricu
|
||||
> :set skip-contracts
|
||||
> add 1 2
|
||||
3
|
||||
> :unset skip-contracts
|
||||
> add "bad" 2
|
||||
[t, "not a natural number"]
|
||||
```
|
||||
|
||||
## Kernel selection
|
||||
|
||||
### CLI
|
||||
|
||||
```bash
|
||||
tricu eval --contract-kernel resumeWithZero program.tri
|
||||
```
|
||||
|
||||
### REPL
|
||||
|
||||
```tricu
|
||||
> :set contract-kernel resumeWithZero
|
||||
> add "bad" 2
|
||||
2
|
||||
```
|
||||
|
||||
### Resolution
|
||||
|
||||
The kernel name is resolved like any other top-level binding in the program or
|
||||
its imports. The runner prepends `kernel = <name>` to the program AST (or
|
||||
inserts it into the environment) after imports are resolved. If the name is
|
||||
not found, evaluation fails with an undefined-variable error.
|
||||
|
||||
## Base library changes
|
||||
|
||||
1. `withContract` becomes the runtime guard primitive shown above.
|
||||
2. `check` extracts the checked value or diagnostic message from the kernel
|
||||
`Result`.
|
||||
3. Contract predicates (`nat?`, `nonZero?`, `bool?`, etc.) remain pure
|
||||
functions returning `Result`.
|
||||
4. Guarded base functions (`add`, `sub`, `head`, `div`, etc.) use the new
|
||||
desugaring.
|
||||
5. Raw helpers (`addRaw`, `subRaw`, etc.) remain for internal use and recursion.
|
||||
|
||||
## Custom contracts
|
||||
|
||||
Users write ordinary predicates returning `Result`:
|
||||
|
||||
```tricu
|
||||
positive? = (n rest :
|
||||
ifThenElse (gte? n 1)
|
||||
(ok n rest)
|
||||
(err "expected positive integer" rest))
|
||||
```
|
||||
|
||||
and use them with the same syntax:
|
||||
|
||||
```tricu
|
||||
fact n@positive? =@nat? y (self n : ...)
|
||||
```
|
||||
|
||||
Contract combinators (`andC`, `orC`, `guardC`) compose in the obvious way.
|
||||
|
||||
## Limitations
|
||||
|
||||
1. **Global kernel only.** There is no local kernel override. A module or
|
||||
function cannot install a different kernel for part of the program.
|
||||
Workarounds: split into separate evaluation sessions, or use explicit
|
||||
`withContract` calls with a local handler function.
|
||||
2. **Kernel must return `Result`.** A kernel that returns a plain value is a
|
||||
bug. The `defaultKernel`/`skipKernel` templates show the required shape.
|
||||
3. **Failures are first-class `Result` values.** A caller that ignores a
|
||||
returned `err msg` and treats it as data will operate on the `Result` tree.
|
||||
This is inherent to any value-level error mechanism.
|
||||
4. **Function contracts are advanced.** Contracts on function arguments
|
||||
(e.g. `f @ (nat? -> nat?)`) require intensional/quantified contracts. The
|
||||
simple predicate model covers most use cases.
|
||||
|
||||
## Implementation notes
|
||||
|
||||
- `Frontend.ContractDesugar` emits `matchResult`/`withContract`/`err`/`ok`
|
||||
instead of continuation-passing `withContract`.
|
||||
- `FileEval.loadFile'` desugars before computing selected exports, so
|
||||
imported modules bring in the runtime helpers needed by annotations.
|
||||
- `Eval.injectKernel` is a fallback that binds `kernel` to `defaultKernel`
|
||||
when `kernel` is missing from the environment.
|
||||
|
||||
## Open questions
|
||||
|
||||
1. **Should `--skip-contracts` strip annotations or just bind the skip
|
||||
kernel?** Currently stripping is the intended design; not yet implemented.
|
||||
2. **Should we provide a small set of built-in kernel names?** `default`,
|
||||
`skip`, `strict`, `log` would cover common cases without requiring the user
|
||||
to define them.
|
||||
3. **How do we expose the current kernel to introspection?** A top-level
|
||||
`currentContractKernel` binding might be useful for debugging.
|
||||
Reference in New Issue
Block a user