Core API

Freer monad kernel: `send`/`bind`/`map`/`seq`/`pipe`/`kleisli` over the `Computation` ADT with FTCQueue continuations for O(1) bind.

Computation ADT: `pure`/`impure` constructors plus `match`/`isComp`/`isPure` eliminators — the freer-monad value representation other modules build on.

Idiomatic Nix bind helpers: `bindAttrs`/`bindComp`/`bindFn` lift attrset/function shapes into effect chains; `optionalArg` marks attrs as handler-conditional.

Trampolined interpreter: `run`/`handle`/`rotate` drive computations via `builtins.genericClosure` at O(1) stack depth and Kyo-style rotation.

FTCQueue (catenable queue, Kiselyov & Ishii 2015): `leaf`/`node`/`singleton`/`snoc`/`append`/`viewl`/`qApp` — O(1) bind on linearly nested computation chains.

Handler context transformation: `adapt`/`adaptHandlers` reposition handlers onto larger state via lenses — contravariant on context, covariant on continuat...

Typed pipeline: `mkStage`/`compose`/`run` build composable stages over reader/error/acc handlers, collecting errors, warnings, and type errors.

fx.state: deepSeq-safe carrier for arbitrary values in handler state — `mkThunk`/`forceThunk` shield Nix closures from the trampoline per-step deepSeq.

Thunk: deepSeq-safe carrier for transporting values through trampoline-threaded handler state via a closure that hides the value from `builtins.deepSeq`.

fx.sugar: opt-in syntax layer for the effect substrate — do, /, steps, letM, with, wrap — that compiles down to plain bind/pure/send.

fx.build: eval-time build pipeline — `plan` validates BuildStep records via fx.pipeline, `materialize` lowers a plan to a runCommand derivation.

Build types: `BuildStep`/`BuildPlan` open-record schemas that validate build pipelines at eval time before materialisation into derivations.

fx.experimental: unstable surfaces under active development — currently the description-side `desc-interp` substrate where FreeFx lives as a μ-tree.

fx.experimental.desc-interp: FreeFx as a μ-tree on HOAS descriptions — `kernel` provides pure/send/bind, `trampoline` runs programs via genericClosure.

fx.experimental.desc-interp.compose: universal handler-result type UniRet and its smart constructors. Every kernel-resident handler can be re-shaped into a U...

fx.experimental.desc-interp.compose-laws: kernel-checked one-shot meta-theorem for composeHandlers. Two clauses (inl/inr); both discharge by H.refl.

fx.experimental.desc-interp.composed-shortcut: closes per-effect UShortHand shortcuts under `composeHandlers`. `composedHandlerShortcut` mirrors `eval (compo...

fx.experimental.desc-interp.composed-shortcut-laws: six H.refl lemmas — state's three canonical ops on inl and error's three strategies on inr — anchorin...

fx.experimental.desc-interp.desc: freer monad encoded as a levitated Desc (freeFx = pure + impure plus continuation queue); the substrate descInterp runs.

fx.experimental.desc-interp.descind-laws: kernel-level laws derived via `descInd kontQueueApp` at the indexed slice. Hosts qAppKernel (kernel-resident transp...

fx.experimental.desc-interp.effects: error and state effects over the description-side kernel — `error` raises, `EffState` is kernel-resident with handle_S...

error effect over descInterp's FreeFx kernel — EffError datatype + three kernel-term handlers (strict/collecting/result) with paired dispatch interpreters.

fx.experimental.desc-interp.effects.error-shortcut-laws: kernel-checked one-shot lemmas for each `handle_*` on the canonical EffError raise. Each lemma disch...

fx.experimental.desc-interp.effects.error-uniform-shortcut-laws: kernel-checked H.refl lemmas certifying that each `uniformOf_*` on the canonical EffError ra...

state effect over descInterp's FreeFx kernel — EffState kernel datatype + kernel-term handle_State; smart constructors + `{ handler; dispatch }` bridge rec...

fx.experimental.desc-interp.effects.state-shortcut-laws: kernel-checked one-shot lemmas for handle_State on each canonical EffState op (get/put/modify). Each...

fx.experimental.desc-interp.extract: partial-evaluation emitter for kernel-resident handler shortcuts. ResidualForm algebra + `extract : RF → Val` mirrorin...

fx.experimental.desc-interp.kernel: pure/send/bind constructors producing FreeFx Desc values directly as `μ freeFxApp` data, not Nix-host computations.

fx.experimental.desc-interp.trampoline: qApp/run/handle interpreters trampolining FreeFx Desc values via genericClosure for O(1) stack depth on long chains.