Conditional Evaluation & Fluent Predicate Chains Subsystem Architectural & Operational Guide
1. Executive Architectural Summary
The Conditional Expression & Fluent Predicate Chain Subsystem (pkg/when) provides a functional, fluent control flow and monadic error-handling DSL across the ZQK Knowledge Kernel.
In idiomatic Go systems, the absence of ternary operators and monadic containers frequently produces repetitive branching cascades, deeply nested if err != nil boilerplate, and high risk of swallowed error contexts. Governed by core system policy POL-DEFAULT-a5e2f78b19c36d0e, pkg/when establishes a deterministic, expressive, and type-safe abstraction layer that unifies:
- Fluent Conditional Branching: Lazy condition evaluation, short-circuit execution, and declarative fallback resolution via
When,OrElseWhen, andOrElse. - Explicit Flow Signals: Fine-grained execution signals (
FlowReturn,FlowContinue,FlowBreak,FlowNone) enabling clean iteration and early loop control in state-machine handlers. - Generic Value Resolution: Monadic type-parameterized chains (
ChainT[T]) providing compile-time type safety without runtime casting or interface boxing. - Non-Swallowing Monadic Error Handling: The
Try[T]andIfTruecontainers preserve accumulated error contexts through transformations, allowing optional annotations viaUnlessErr, deterministic fallbacks viaOrElse, and intentional recovery viaClearErr. - Memory-Safe Pointer & Nil Predicates: Deep reflection-aware nil guards (
IsNilValue,IsNilOrEmpty) and fallback dereference helpers (PtrOr,PtrOrElse) ensuring nil-safety across disparate data types. - Concurrency Safety: Stateless, immutable execution pipelines engineered for high-throughput concurrency across swarms managed by
pkg/goroutinelabels.
2. Component Topology & Subsystem Architecture
The subsystem is organized into five complementary functional units designed for zero global state and minimal allocation overhead:
flowchart TD
subgraph Client["Consumer Systems (CLI, Kernel, Schedulers, Watchdogs)"]
Consumer["Callsite Invocation"]
end
subgraph WhenSubsystem["Conditional Evaluation Subsystem (pkg/when)"]
Consumer --> Router{"Execution Style"}
Router -->|"Branch Action"| FluentChain["Fluent Action Chain (chain.go)"]
Router -->|"Value Resolution"| GenericChain["Generic Value Chain (chain_generic.go)"]
Router -->|"Value + Error Carrier"| TryMonad["Monadic Error Carrier (try.go)"]
Router -->|"Boolean Branch"| ErrBranch["Error-Aware Branch (try.go)"]
Router -->|"Type / Nil Probing"| Predicates["Predicates & Pointers (predicates.go, pointers.go)"]
FluentChain --> Clauses["Clauses Evaluator (Short-Circuit)"]
GenericChain --> ClausesT["Generic Clauses Evaluator"]
TryMonad --> MonadOps["Then / UnlessErr / OrElse / ClearErr"]
ErrBranch --> ErrOps["Then / UnlessErr / OrElse"]
Predicates --> ReflectionGuard["Deep Type & Reflection Inspector"]
end
Clauses --> FlowOut["FlowSignal / Terminal Execution"]
ClausesT --> ValOut["Resolved Typed Value (T)"]
MonadOps --> PairOut["(T, error)"]
ErrOps --> ErrOut["error"]
ReflectionGuard --> BoolOut["bool / *T"]
Core Components
| Component | Source File | Core Responsibility |
|---|---|---|
| Fluent Chain Builder | chain.go |
Builds and evaluates conditional action branches with short-circuit execution and loop flow signals. |
| Generic Chain Carrier | chain_generic.go |
Type-parameterized (ChainT[T]) conditional value builder resolving typed expressions with default fallbacks. |
| Monadic Try/Catch Carrier | try.go |
Carries (value, error) pairs through fluent transformation pipelines while guaranteeing error preservation. |
| Error-Aware Brancher | try.go |
Implements conditional execution (IfTrue) with error interception, wrapping, and alternate error paths. |
| Predicate Evaluator | predicates.go |
Inspects strings, runes, and typed interface values for nil, emptiness, whitespace, and rune classification. |
| Pointer Utilities | pointers.go |
Provides nil-safe dereferencing with static or dynamic lazy fallback evaluation. |
3. Execution Lifecycle & Short-Circuit Mechanics
The subsystem enforces strict lazy evaluation: conditions and branch actions are closures evaluated sequentially at invocation time (Run() or Execute()). As soon as a condition evaluates to true, its corresponding action is dispatched and all subsequent conditions and actions are short-circuited.
sequenceDiagram
autonumber
actor Caller as Kernel Subsystem / Swarm Worker
participant Chain as pkg/when.Chain
participant Cond1 as Condition 1 (Closure)
participant Act1 as Action 1 (Closure)
participant Cond2 as Condition 2 (Closure)
participant Act2 as Action 2 (Closure)
participant Fallback as OrElse Fallback (Closure)
Caller->>Chain: When(Cond1).Then(Act1).OrElseWhen(Cond2).Then(Act2).OrElse(Fallback).Run()
Note over Chain: Sequential Evaluation Begins
Chain->>Cond1: Evaluate Cond1()
Cond1-->>Chain: true
Chain->>Act1: Execute Act1()
Act1-->>Chain: Completed
Note over Chain: Short-Circuit Triggered
Note over Chain,Cond2: Cond2() is NEVER evaluated
Note over Chain,Act2: Act2() is NEVER executed
Note over Chain,Fallback: Fallback() is NEVER executed
Chain-->>Caller: Returns
Control Flow Signal Dispatch
When operating inside loops, iteration switches, or state machines, calling Execute() returns a FlowSignal rather than returning void:
for _, item := range queue {
sig := when.When(item.IsCorrupt).Then(func() { quarantine(item) }).AndContinue().
OrElseWhen(item.IsComplete).Then(func() { finalize(item) }).AndBreak().
OrElse(func() { process(item) }).
Execute()
switch sig {
case when.FlowContinue:
continue
case when.FlowBreak:
break
case when.FlowReturn:
return nil
case when.FlowNone:
// default execution path
}
}
4. Error Preservation & Monadic Try Strategies
A common failure mode in functional Go wrappers is the silent dropping or swallowing of error states. pkg/when eliminates this anti-pattern through explicit error preservation invariants:
Then(fn)executes only on success: If an error is already present inTryResult[T],Thenis a no-op that preserves the incoming value and error.UnlessErr(fn)annotates errors: When an error is present,UnlessErrallows callers to wrap or contextualize the error without dropping it.OrElse(fn)sets fallbacks without clearing errors: Supplying a fallback value for degraded operational states preserves the original or annotated error.ClearErr()explicit recovery: An error is dropped only when the caller explicitly transitions the pipeline into a recovered state viaClearErr().
stateDiagram-v2
[*] --> Initialized: Try(val, err)
state Initialized {
[*] --> CheckError
CheckError --> ErrorNil: err == nil
CheckError --> ErrorSet: err != nil
}
state ErrorNil {
[*] --> ThenAction: .Then(transform)
ThenAction --> ErrorNil: transform success
ThenAction --> SkipUnlessErr: .UnlessErr(...) [Skipped]
SkipUnlessErr --> SkipOrElse: .OrElse(...) [Skipped]
SkipOrElse --> ValidResult: .Get() -> (newVal, nil)
}
state ErrorSet {
[*] --> SkipThen: .Then(...) [Skipped]
SkipThen --> AnnotateErr: .UnlessErr(wrapFn)
AnnotateErr --> FallbackVal: .OrElse(fallbackFn)
FallbackVal --> PreservedErr: Error remains bound
PreservedErr --> Recovered: .ClearErr() [Intentional Recovery]
PreservedErr --> ErrorResult: .Get() -> (fallbackVal, annotatedErr)
Recovered --> RecoveredResult: .Get() -> (fallbackVal, nil)
}
Error-Aware Branching (IfTrue)
For conditional operations returning standalone errors:
err := when.IfTrue(requiresSync).
Then(func() error { return syncWithPeer(peerID) }).
UnlessErr(func(e error) error { return fmt.Errorf("peer sync failure: %w", e) }).
OrElse(func() error { return recordSkippedSync(peerID) }).
Err()
if err != nil {
return err
}
5. Predicates, Reflection Guards & Pointer Utilities
The subsystem provides reflection-aware inspections to guard against typed nil interface hazards (where val != nil evaluates to true despite the underlying pointer or slice being nil).
Deep Nil & Emptiness Detection
| Helper Function | Type Domain | Evaluates True When |
|---|---|---|
IsEmpty(s) |
string |
String length is exactly 0. |
IsBlank(s) |
string |
String is empty or composed exclusively of whitespace. |
IsNil(ptr) |
*T |
Pointer reference is nil. |
IsNotNil(ptr) |
*T |
Pointer reference is non-nil. |
IsNilValue(v) |
any |
Untyped nil or typed nil channel, func, interface, map, pointer, or slice. |
IsNilOrEmpty(v) |
any |
IsNilValue(v) holds, or length is 0 across strings, string pointers, arrays, slices, or maps. |
Rune Classification
Low-latency rune classifiers accelerate internal lexical tokenization and AST parsing pipelines without regex engine allocations:
IsNewLine(r): Detects\nand\r.IsComma(r),IsColon(r),IsDash(r),IsHyphen(r),IsTilde(r): Structural syntax separators.IsFwdSlash(r),IsBackSlash(r): Path and escape delimiters.IsLeftCurly(r),IsRightCurly(r): Block scope indicators.IsDecimal(r): Numeric fraction markers.IsChar(r)/IsNum(r): Unicode character and digit predicates.
Pointer Ergonomics
Ptr[T](v): Returns an allocated pointer to literal valuev.PtrOr[T](ptr, def): Returns*ptrif non-nil; otherwise returns literaldef.PtrOrElse[T](ptr, fn): Returns*ptrif non-nil; otherwise lazily evaluatesfn().
6. Concurrency & Thread-Safety Invariants
The pkg/when subsystem is architected for zero-contention concurrent execution across parallel agent swarms and kernel daemons:
- Zero Global Mutable State: All builders (
Builder,BuilderT,ErrChain,TryResult) and execution clauses are strictly stack-allocated or local-reference scoped. - Stateless Functional Predicates: Predicates and rune evaluators are pure functions with zero memory mutations.
- Goroutine Worker Coordination: Verified under high-concurrency workloads using
pkg/goroutinelabelswith zero race conditions, shared memory locks, or goroutine leaks.
7. Verification & Quality Gates
The pkg/when package conforms to mandatory quality standards:
- Static Floor Invariant: Statement test coverage must strictly remain \(\ge 85.0\%\) (achieving 100.0% statement coverage under core verification).
- Deterministic Execution: Dynamic proof verification guarantees short-circuit sequencing, monadic error wrapping, and flow signal propagation behave predictably across all execution paths.
- Zero Swallowed Errors: All error-returning branches must be explicitly asserted, verified, or returned (
_ = ...is strictly banned). - Cognitive Clarity: All functional routines and test cases maintain \(<100\) lines per block.
- Public Release Invariant: Verified via
scripts/open-core/check-public-release-payload.shto ensure zero internal nanosecond process IDs.