cove v0.1.0 - Contextual stepping for kont suspensions

Introduction

• cove is the context layer of the nonblocking I/O stack. Around a kont computation that is advanced one suspension at a time, cove keeps ambient state — dispatch budget, ring capabilities, protocol phase, buffer-group validity, and similar runtime facts — as typed, composable data instead of hidden globals or ad-hoc side maps.
• The package is policy-free by design: it carries context, checks requirements, and exposes the current suspension boundary, but it never schedules, retries, classifies outcomes, or talks to the kernel. Those responsibilities stay with takt, iox, and uring.
• The public surface of cove package: View as the ambient carrier, SuspensionView as the contextual observation boundary over kont.Suspension, Cmd for contextual commands, Req / ReqExpr for context predicates in closure and data form, Rule / RuleExpr plus Report for named diagnostics, and requirement-gated value carriers Checked and Guarded.

Usage

type Runtime struct {
    Budget int
}

_, sv := cove.StepExprWith(Runtime{Budget: 8}, computation)
for sv.Suspension != nil {
    result := dispatch(sv.Ask(), sv.Op())
    _, sv = sv.ResumeWith(result, func(r Runtime) Runtime {
        r.Budget--
        return r
    })
}

// Completion clears the suspension; the carried context is preserved.
_ = sv.Ask()

Highlights

cove ships an explicit context algebra for kont suspensions without becoming a runtime. The surface covers contextual stepping, contextual commands, composable requirements (closure and data forms), named rule diagnostics with reports, requirement- and rule-gated value carriers, and bridge helpers between the closure and expression worlds.

Features

Public Surface

• Ambient carrier. View[C, A] with Observe, Extract, Ask, Map, MapContext, Replace, WithContext, Duplicate, and Extend.
• Contextual commands. Cmd[C, A, B] with Run, ExtractCmd, LiftCmd, and Compose for command composition through Extend.
• Contextual stepping. SuspensionView[C, A], ObserveSuspension, StepWith, StepExprWith, Step, StepExpr, Op, Resume, ResumeWith, and Discard for stepping kont computations under ambient context; MapContextSuspension and WithContextSuspension for explicit context transport on already-observed suspensions.
• Requirements. Req[C] with Need, Pullback, All, Any, Not, True, False; ReqExpr[C] with NeedExpr, ExprAtom, ExprPullback, ExprAll, ExprAny, ExprNot, ExprTrue, ExprFalse as a defunctionalized Boolean algebra over predicates.
• Diagnostics. Rule[C], RuleExpr[C], Report, RuleError, Require, RequireExpr, PullbackRule, CheckRule, CheckRules, CheckRuleExpr, and CheckRulesExpr for named, ordered diagnostic checks.
• Gated values. Checked[C, A], CheckedExpr[C, A], Guarded[C, A], and GuardedExpr[C, A] as requirement-gated and rule-gated value carriers, with Guard, GuardExpr, GuardRule, GuardRuleExpr, IntoView, MustView, MapChecked, MapGuarded, PullbackChecked, and PullbackGuarded.
• Bridges. Reify, Reflect, ReifyReq, and ReflectReq between the closure and expression worlds.
• Gated suspensions. CheckSuspension and CheckSuspensionExpr gate contextualization of a raw kont.Suspension on a requirement.

Behavioural contracts

• SuspensionView is affine: each suspension is consumed exactly once via Resume, ResumeWith, or Discard.
• Completion preserves carried context: when stepping reaches the terminal boundary, sv.Suspension becomes nil while sv.Ask() still returns the ambient context.
• cove performs no scheduling, retry, or outcome classification; semantic outcome branching belongs to iox, kernel mechanics belong to uring, and proactor advancement belongs to takt.

Laws

• Duplicate(v).Extract() == v
• Extend(v, func(w View[C, A]) A { return w.Extract() }) == v
• Compose(g, f)(v) == g(Extend(v, f))
• Compose(ExtractCmd, f) == f and Compose(g, ExtractCmd) == g

Compatibility

• Go: 1.26+