Async

Task spawning, scheduling, partial results, and failure behavior across asynchronous boundaries.

7 items in this guidance cluster.

Tagged guidance

GuideBoundary CorrectnessValidation PolicyState TransitionsBoundary Correctnessboundary-correctnessBoundary-correctness guidance covers APIs and internal boundaries where uncertain input becomes trusted data, state changes, ambient inputs enter the system, or async work crosses an ownership boundary. It favors visible caller obligations, typed transitions, explicit policy, and provider behavior modeled as it really exists.

RuleBoundary CorrectnessFailure OutputErrorsDefine Hook Failure PolicyBOUNDARY-DEFINE-HOOK-FAILURE-POLICYSpecify whether each hook class blocks, retries, logs and continues, rolls back, or leaves partial state. This gives extension points predictable failure behavior without forcing one global answer onto every hook.RuleBoundary CorrectnessState TransitionsFailure OutputExpose Partial Stream OutputBOUNDARY-EXPOSE-PARTIAL-STREAM-OUTPUTSurface streaming tokens, chunks, or events as provisional output until completion promotes a final result. Callers get progress and diagnostics without corrupting authoritative state with partial provider data.

RuleRustDocumentationSide EffectsDocument Scheduling for Long Async WorkRUST-DOCUMENT-SCHEDULING-FOR-LONG-ASYNCExplain executor, cancellation, blocking, and fairness expectations for async work that can run long. Callers need those constraints to avoid starvation and runtime surprises.RuleRustBoundary CorrectnessPublic APIUse Send Static Across TasksRUST-USE-SEND-STATIC-ACROSS-TASKSRequire owned Send + static values, futures, errors, and handles when they cross spawn or thread boundaries. Avoid imposing those bounds on local synchronous APIs where they would reject valid use.

RuleTestingState TransitionsVerificationCover Async Routing Edge CasesTEST-COVER-ASYNC-ROUTING-EDGE-CASESTest late replies, unrelated input, timeouts, and unmatched async responses. These cases protect request correlation and cleanup without relying on wall-clock luck.

PatternBoundary CorrectnessSide EffectsTestingKeep Async Boundaries Explicitkeep-async-boundaries-explicitHidden async work obscures cancellation, ordering, resource ownership, and failure behavior. Make task spawning, awaiting, retries, and background ownership visible at the boundary where callers need to reason about them.