cove v0.1.1 — clarify source-level contract docs

[hayabusa-cloud]

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 covers a comonadic View, a SuspensionView boundary over kont.Suspension, contextual Cmd composition, closure and defunctionalized requirement algebras Req / ReqExpr, named diagnostics Rule / RuleExpr with Report, and requirement- and rule-gated value carriers Checked and Guarded.
v0.1.1 is a documentation-only patch on top of v0.1.0; the public API and runtime behavior are unchanged, but the exported Go-surface comments now state the existing contracts more explicitly.

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

This release turns three source-level contracts from implied knowledge into explicit exported documentation. The stepping APIs now state their inherited nil-completion rule directly, the command surface states its identity/composition law, and the Req bridge docs now make the lossy quotation/evaluation direction explicit.

What's Changed

Documentation

• Document the inherited nil-completion convention directly on Step, StepExpr, StepWith, StepExprWith, Resume, and ResumeWith in step.go.
• Document Cmd as the contextual command / coKleisli surface in cmd.go, including the identity and composition laws already enforced by the implementation.
• Document ReifyReq / ReflectReq in bridge.go as lossy quotation/evaluation helpers rather than structural inverses, including the ReifyReq(nil) invalid-input hazard.

Behavioural Contracts

• SuspensionView remains affine: each suspension is consumed exactly once via Resume, ResumeWith, or Discard.
• Completion still preserves carried context: when stepping reaches the terminal boundary, sv.Suspension becomes nil while sv.Ask() still returns the ambient context.
• Step, StepExpr, StepWith, StepExprWith, Resume, and ResumeWith still inherit kont's nil-completion convention: a nil completed payload denotes completion with the zero value of A.
• Cmd composition still follows Compose(g, f)(v) == g(Extend(v, f)), with ExtractCmd as the identity command on View.
• ReifyReq still quotes a closure predicate into an Expr atom without preserving original Expr structure on the round trip back through ReflectReq.

Compatibility

• Go: 1.26+

---

This discussion was created from the release cove v0.1.1 — clarify source-level contract docs.