Skip to content

feat(state): pass the step's context to callbacks; skip CI on drafts - #245

Merged
reka18 merged 9 commits into
mainfrom
feat/state-callback-context
Nov 11, 2026
Merged

reka18 merged 9 commits into
mainfrom
feat/state-callback-context

Conversation

@reka18

@reka18 reka18 commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

What this change does

Guards, actions and reducers now get the context of the step running them, so a host can tell when one of them calls back into it.

  • GuardCtx, ActionCtx and AssignCtx have a new Ctx field: the context the Fire was given. Outside a Fire, such as during PlanPath, it's context.Background(), never nil. A Fire nested inside a callback on the same instance restores the outer context when it returns.
  • The in-process bindings pass the context they're given (EvalGuard, EvalAction, EvalAssign) through to the function they wrap.
  • WithContext sets the context Cast gives the guards, actions and reducers that settle the initial state.
  • ActorSystem.RegisterContext registers a ContextActorBehavior, an actor factory that gets the context of the step spawning or restoring the actor, so it can Cast its child WithContext. A child's own callbacks already get the context its delivery carries. Register is unchanged.
  • A guard registered with BindGuard gets the Fire's context through EvalGuard, where it used to get a background one, and callbacks see the context as the middleware chain passes it down.

It's additive: no existing signature changes.

CI on drafts. This PR also stops CI and CodeQL running on draft PRs. A draft runs only the required gate check, which fails in a few seconds with "Draft PR: CI runs when it's marked ready for review". Marking a PR ready runs the full CI and CodeQL, as does every later push to it. The gate fails rather than skips on a draft: a skipped required check counts as passing for that commit, so a PR could otherwise be marked ready and merged before its CI ran. CONTRIBUTING says so.

Why

#243 makes a durable Handle hold a lock for each step. Code that runs under that lock and calls back into the same Handle would wait forever. A service gets the step's context, so #243 can recognize a call carrying it and return ErrReentrantStep instead. Guards, actions, reducers and actor factories had no context to pass back, so the same mistake there still deadlocked. With this change, a callback that passes in.Ctx back into its Handle gets ErrReentrantStep too. Once both land, #243's docs will say so.

It also lets work under review stay a draft without spending CI time, as agreed with the maintainers.

Relates to: #214, #243

Evidence

On GOTOOLCHAIN=go1.27.3:

Check Result
go test -race ./state/... ./durable/... ./cluster/... Pass
go test ./... in examples/dispatch and e2e Pass
go vet ./... in every workspace module Clean
Pinned golangci-lint on state 0 issues
actionlint on ci.yml and codeql.yml Clean
This PR as a draft, after the CI change Only gate ran (3 s, failed with the draft message); CodeQL skipped

The new tests in state/callback_context_test.go cover a guard, an action and a reducer seeing the Fire's context, an entry reducer on a later Fire, Cast with and without WithContext, PlanPath, a nested Fire, and RegisterContext through spawn, Cast and delivery, a BindGuard binding, middleware, an eventless transition settling during Cast, and a parallel region. Each fails when the code it covers is removed.

Checklist

  • Commits are signed off (git commit -s) per the DCO
  • Conventional commit messages (type: subject)
  • mage check passes locally (lint + race tests + govulncheck): not run as a whole; the parts above were run individually
  • Tests added/updated for the change
  • Public API changes documented (godoc) and, if applicable, noted for the changelog

A guard, action or reducer had no context, so a host couldn't tell a call
it made back into the host from a call on another goroutine. GuardCtx,
ActionCtx and AssignCtx now carry Ctx: the context the Fire was given, or
context.Background() outside a Fire. The in-process bindings pass their
own context through.

WithContext sets the context Cast gives the reducers that settle the
initial state. ActorSystem.RegisterContext registers a factory that gets
the spawning step's context, so it can Cast its child with it. A child's
own callbacks already get the context its delivery carries.

The change is additive.

Signed-off-by: Ray Karnes <ray.karnes@stablekernel.com>
@reka18 reka18 added not-ready On every new PR until all review dimensions are confirmed wait:correctness ACR pending: correctness wait:regression-safety ACR pending: regression-safety wait:concurrency-discipline ACR pending: concurrency-discipline wait:api-compatibility ACR pending: api-compatibility wait:missed-context ACR pending: missed-context wait:human-readability ACR pending: human-readability labels Nov 10, 2026
A draft PR now runs only the gate, which fails with a note that CI runs
once the PR is marked ready. Marking it ready (ready_for_review) runs the
full CI and CodeQL, as does every later push to a ready PR.

The gate fails rather than skips on a draft: a skipped required check
counts as passing for that commit, so a PR could otherwise be marked
ready and merged before its CI had run.

Signed-off-by: Ray Karnes <ray.karnes@stablekernel.com>
Review found that a guard registered with BindGuard was adapted with a
background context, dropping the Fire's context the kernel now passes.
Its EvalGuard now gets the Fire's context.

Callbacks also see the context as the middleware chain passes it down,
not only the one Fire was called with.

Docs: WithContext reaches the guards and actions that settle the initial
state as well as its reducers, and Cast settles to completion even if
that context has ended. The ActorSystem doc says the parent Instance
still needs one goroutine at a time. The site docs mention Ctx.

Signed-off-by: Ray Karnes <ray.karnes@stablekernel.com>
…in regions

Review follow-ups:
- Cast clears the callbacks' context with defer, as Fire does.
- Tests: an eventless transition settling during Cast, and a transition
  inside a parallel region, see the expected context.
- Ctx's doc no longer suggests PlanPath runs actions or reducers.
- The guards and actors pages mention Ctx and RegisterContext, the
  deferred-surface notes record Cast's WithContext, and CONTRIBUTING says
  CI runs on ready PRs.

Signed-off-by: Ray Karnes <ray.karnes@stablekernel.com>
@reka18 reka18 changed the title feat(state): pass the step's context to guards, actions and reducers feat(state): pass the step's context to callbacks; skip CI on drafts Nov 10, 2026
@reka18 reka18 added ready All ACR dimensions confirmed - clear to merge confirmed:correctness ACR clean: correctness confirmed:api-compatibility ACR clean: api-compatibility and removed not-ready On every new PR until all review dimensions are confirmed wait:correctness ACR pending: correctness wait:regression-safety ACR pending: regression-safety wait:concurrency-discipline ACR pending: concurrency-discipline wait:api-compatibility ACR pending: api-compatibility wait:missed-context ACR pending: missed-context wait:human-readability ACR pending: human-readability labels Nov 10, 2026
@reka18 reka18 added not-ready On every new PR until all review dimensions are confirmed wait:correctness ACR pending: correctness wait:regression-safety ACR pending: regression-safety wait:human-readability ACR pending: human-readability wait:replay-determinism ACR pending: replay-determinism labels Nov 10, 2026
…rds alike

Review follow-ups:
- Cast gives its callbacks WithContext's values without its cancellation
  or deadline. A bound guard that honored an ended context could fail
  there and quietly send the settle down another transition, because
  Cast settles to completion and has no error to report.
- A guard stopped by an ended context no longer reports a guard panic or
  failure in the Trace on any path: named guards, guard expressions,
  parallel regions and the parallel state itself.
- The Fire's error names the bound guard and keeps its own error, while
  still matching the context's.
- Tests pin each of these, and a Fire whose eventless guard was canceled
  with nothing chosen.
- Docs: ContextActorBehavior covers restore; the site pages say not to
  branch on Ctx.

Signed-off-by: Ray Karnes <ray.karnes@stablekernel.com>
An eventless transition's guard stopped by an ended context was read as
not passing, so the Fire reported a bare context error, without the
guard's name or the binding's own error. Eventless selection now stops
with the guard's error, as event-driven evaluation does. A test covers
both.

Docs: a nested Fire clears the outer Fire's raised events; a bound
guard's cancellation check reads the context it got, as middleware
passed it down; at Cast, Ctx carries the values of WithContext's
context.

Signed-off-by: Ray Karnes <ray.karnes@stablekernel.com>
The Fire's error embedded the binding's error as text only, so a host couldn't match its sentinel with errors.Is, though the CHANGELOG said it was wrapped. It now wraps both the context's error and the binding's. The test checks errors.Is for each.

Signed-off-by: Ray Karnes <ray.karnes@stablekernel.com>
… error

A guard that panicked with a value wrapping context.Canceled was taken for a guard stopped by its ended context. Canceled guards now carry the kernel's own marker, so only those skip the guard-panic outcome. Tests: that case, a region's eventless transition settling during Cast, and a note that a nil Ctx fails the context tests.

Signed-off-by: Ray Karnes <ray.karnes@stablekernel.com>
@reka18 reka18 added ready All ACR dimensions confirmed - clear to merge confirmed:correctness ACR clean: correctness confirmed:regression-safety ACR clean: regression-safety confirmed:human-readability ACR clean: human-readability confirmed:replay-determinism ACR clean: replay-determinism and removed not-ready On every new PR until all review dimensions are confirmed wait:correctness ACR pending: correctness wait:regression-safety ACR pending: regression-safety wait:replay-determinism ACR pending: replay-determinism wait:human-readability ACR pending: human-readability labels Nov 11, 2026
@reka18

reka18 commented Nov 11, 2026

Copy link
Copy Markdown
Contributor Author

Thanks for the review. Addressed in 2f3c928 through f2eb64c.

Your must-fix: done. A BindGuard binding whose EvalGuard fails after the Fire's context ended now stops the Fire with the context's error, on event-driven and eventless transitions alike. The error names the guard and wraps both the context's error and the binding's own, so errors.Is matches either. The CHANGELOG entry is under Changed, and tests pin both kinds of transition. One correction: the divergence couldn't persist. The cancellation check after each microstep already rolled the Fire back, with nothing journaled. What the fix removes is the fallback's actions and reducers running under the ended context before that rollback.

Reviewing the fix also turned up a Cast case. Cast settles to completion and can't abort, so with an ended WithContext context, a bound guard that honoured cancellation sent the settle down another transition with no error. Cast's callbacks now get WithContext's values without its cancellation or deadline.

Your should-fix items: all done.

  • The Ctx docs say not to branch on it, because a replay runs the same callbacks under a different context. The guards, actions and assigns pages say so too.
  • There's now a RestoreActors test through RegisterContext.
  • The reserved WithContext note in the CHANGELOG is reworded.

Your nit: done. The comment at fire.go:69 says Fire's deferred restore puts callCtx back.

Also: a cancelled guard no longer shows as a guard panic or failure in the Trace on any path. The review summary below this comment has the details.

@reka18

reka18 commented Nov 11, 2026

Copy link
Copy Markdown
Contributor Author

Review after the maintainer's comments

The maintainer's review is addressed in 2f3c928 through f2eb64c. Each changed dimension was attacked again by an AI reviewer working from a clean context, until it had no blockers. The reviewers could only read code; I ran the tests and the mutation checks. All dimensions are confirmed.

Dimension Rounds since the maintainer's review Status
Correctness 2 rounds with blockers, then a verify-only round Confirmed
Replay determinism 2 rounds with blockers, then a verify-only round Confirmed
Regression safety 0 blockers Confirmed
Human readability 0 blockers Confirmed
Concurrency, API compatibility, missed context, CI gating Unchanged since their earlier confirmation Confirmed

Fixed

  • A bound guard on an ended context: a BindGuard binding whose EvalGuard fails after the Fire's context ended stops the Fire with the context's error, on event-driven and eventless transitions. The error names the guard and wraps both the context's error and the binding's own. The fallback transition's callbacks never run.
  • Cast with an ended context: Cast settles to completion, so a bound guard that honoured cancellation could quietly send the settle down another transition. Cast's callbacks now get WithContext's values without its cancellation or deadline.
  • Trace outcome: a cancelled guard is no longer reported as a guard panic or failure, whether it's a named guard, a guard expression, or in a parallel region or the parallel state. A guard that panics with a value wrapping a context error is still reported as a panic.
  • Docs: don't branch on Ctx, since a replay runs the same callbacks under a different context; a nested Fire clears the outer Fire's raised events; ContextActorBehavior covers restore.
  • Tests: each fix has a test that fails when the fix is removed, plus RestoreActors through RegisterContext and a region's eventless transition settling during Cast.

Not changed

  • A Fire stopped by a cancelled guard during eventless selection keeps the earlier outcome in its Trace instead of the cancellation outcome. The error is right; the outcome is a consistency follow-up.
  • A Fire rolled back at a cancellation check keeps a Trace that reads success. This predates this PR.
  • A plain guard that checks its context and returns false can still steer a transition until the rollback. That's covered by the rule against branching on Ctx.

@joshua-temple

joshua-temple commented Nov 11, 2026 •

Copy link
Copy Markdown
Collaborator
  • state/fire.go:286-299: Trace.Outcome keeps the earlier step's value (Success) when ctx ends during eventless selection
    • Fire returns Err and rolls back, but the trace reports Success
    • The boundary check at fire.go:255 has the same flaw, so it predates this PR
    • Fix: set res.Trace.Outcome on both new error returns (OutcomeInvalidTransition, as cancelled spine guards do)
    • Add a test: Outcome != Success when Err is set

@joshua-temple joshua-temple left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved pending outstanding bug

@reka18
reka18 merged commit 72b851d into main Nov 11, 2026
112 checks passed
@reka18
reka18 deleted the feat/state-callback-context branch November 11, 2026 14:57
reka18 added a commit that referenced this pull request Nov 11, 2026
…s Ctx [skip ci]

With #245, a guard, action or reducer gets the step's context as its
input's Ctx, so a call back into the Handle with it returns
ErrReentrantStep instead of deadlocking. Say so in the docs, and cover
it with a test.

Signed-off-by: Ray Karnes <ray.karnes@stablekernel.com>
reka18 added a commit that referenced this pull request Nov 11, 2026
…s Ctx [skip ci]

With #245, a guard, action or reducer gets the step's context as its
input's Ctx, so a call back into the Handle with it returns
ErrReentrantStep instead of deadlocking. Say so in the docs, and cover
it with a test.

Signed-off-by: Ray Karnes <ray.karnes@stablekernel.com>
reka18 added a commit that referenced this pull request Nov 11, 2026
…s Ctx

With #245, a guard, action or reducer gets the step's context as its
input's Ctx, so a call back into the Handle with it returns
ErrReentrantStep instead of deadlocking. Say so in the docs, including
that a call back without the step's context, or under middleware that
passed down an unrelated one, still deadlocks. Cover Fire, an eventless
transition, middleware, Tick, RunService and DeliverToActor in a test.

Signed-off-by: Ray Karnes <ray.karnes@stablekernel.com>
reka18 added a commit that referenced this pull request Nov 11, 2026
…243)

* fix(durable): lock the Handle and refuse steps after a failed Append

Fire, Tick, RunService and DeliverToActor now hold a lock for the whole step,
so a host's timer loop no longer loses acknowledged steps. A step that applied
to the kernel but wasn't appended leaves the instance ahead of the journal, so
the Handle refuses further steps with ErrHandleFailed until it's recovered.

Relates to #214.

Signed-off-by: Ray Karnes <ray.karnes@stablekernel.com>

* test(durable): cover the failed-Handle latch on RunService and DeliverToActor

RunService and DeliverToActor refuse steps after a failed Append and
return an ended context's error, but only Fire and Tick were tested.
New tests fail an Append under each and end the context before each,
and check nothing ran or was journaled. The Tick context test now also
checks that nothing was appended.

The RunService and DeliverToActor docs said a failed step returns
false; they return true with ErrHandleFailed once the service settled
or the actor received the event. The docs now say so, name a context
that ends during the Store write as a possible cause, and note that the
latch relies on the Append running inline.

Signed-off-by: Ray Karnes <ray.karnes@stablekernel.com>

* fix(durable): dispatch effects outside the step lock, and close review gaps

An effect handler that called back into its own Handle deadlocked, because
Fire held the step lock through dispatch. The lock now covers only the
kernel step and the Record append. Effects dispatch after it's released,
and a checkpoint waits until every step at or before it has dispatched, so
compaction never drops an effect still being sent. A failed dispatch fails
the Handle, so Recover sends the effect again.

Code that has to run under the lock gets a marked context: a service that
calls back in with it gets ErrReentrantStep instead of deadlocking. A step
waiting for the lock stops when its context ends. Handle.View reads the
instance under the lock.

Also:
- WithEventDataDecoder and DecodeAs decode a WithEventData payload as the
  caller's type, live and on replay. A payload that decodes as another
  type refuses the Fire.
- StepReporter lets Recover number past every recorded step after a
  checkpoint from before checkpoints carried the next step. MemStore and
  FileStore implement it.
- FileStore.Append encodes a Record once.

Signed-off-by: Ray Karnes <ray.karnes@stablekernel.com>

* fix(durable): release the lock on panic, and settle dispatch before failing

Review of the outbox change found gaps:
- Fire released the step lock without defer, so a panic in host code
  under the lock left it held. It now releases however the step ends.
- An effect handler that panicked left its step dispatching forever,
  which silently stopped every later checkpoint. A panic now fails the
  Handle with ErrEffectDispatch, like a returned error.
- A call that fails the Handle returns only once no effect is still
  being sent, so a host that recovers right away can't send one twice.
  A step that held the lock while another goroutine failed the Handle
  leaves its effects for Recover instead of sending them.
- refuse takes the context, so every step runs one check after taking
  the lock: the Handle hasn't failed, and the context hasn't ended.
- A nil payload stays nil under a typed decoder, and ErrEffectDispatch
  wraps the handler's error.
- Docs: the wait after a failure, handler failures failing the Handle,
  dispatch order for a step fired from a handler, StepReporter errors.

Signed-off-by: Ray Karnes <ray.karnes@stablekernel.com>

* fix(durable): add Handle.Drain instead of waiting after a failure

A call that failed the Handle waited until no effect was still being
sent. An effect handler that called back with a context other than its
own, and failed the Handle, waited on its own dispatch forever, and so
did every later caller. Calls that fail the Handle now return at once.
Handle.Drain waits until no effect is still being sent; call it before
Recover. Called from inside a step or an effect handler, it returns
ErrReentrantStep instead of waiting.

Docs: an action reaches the Handle by returning an effect; a guard,
action, reducer or actor behavior that calls back without the step's
context deadlocks. Fire's doc covers a failed checkpoint. The payload
cap measures an error's JSON form, and a Store panic during dispatch is
reported as a dispatch panic, not a handler's.

Signed-off-by: Ray Karnes <ray.karnes@stablekernel.com>

* docs(durable): scope Drain to a failed Handle

Once a Handle has failed, no step can start sending effects, so Drain covers every one. On a healthy Handle a step still recording can start sending after Drain returns, so the docs say to stop calling it before moving its instance to a new Handle. Also: a typed-nil payload is refused as a type mismatch.

Signed-off-by: Ray Karnes <ray.karnes@stablekernel.com>

* docs(durable): refuse a guard, action or reducer calling back with its Ctx

With #245, a guard, action or reducer gets the step's context as its
input's Ctx, so a call back into the Handle with it returns
ErrReentrantStep instead of deadlocking. Say so in the docs, including
that a call back without the step's context, or under middleware that
passed down an unrelated one, still deadlocks. Cover Fire, an eventless
transition, middleware, Tick, RunService and DeliverToActor in a test.

Signed-off-by: Ray Karnes <ray.karnes@stablekernel.com>

* chore(ci): move to Go 1.27.4 across the repo

govulncheck now fails every PR on GO-2026-6859, an HTTP/1 server crash
in net/http that Go 1.27.4 fixes. It's reached through grpc's server in
transport. Every go.mod and go.work now declares Go 1.27.4; CI reads the
version from go.work. No dependency changes.

Signed-off-by: Ray Karnes <ray.karnes@stablekernel.com>

* fix(durable): drain a step still recording, and keep deferred checkpoints

Drain returned while a step that held the lock when the Handle failed was
still in its Append, so Recover could load a journal without that step
and the next step conflicted. Drain now waits for the step lock before
it waits for dispatch, and a step recorded as another goroutine failed
the Handle returns ErrHandleFailed saying it was recorded, on Fire, Tick,
RunService and DeliverToActor. The docs say to give Drain a context of
its own and not to Recover until it returns nil.

A checkpoint that waited on an earlier step's dispatch was written with
the context of whichever step finished last, so that caller's cancel
dropped it and the error went to that caller. Now that caller isn't told
and the next step writes the checkpoint. A retry the Store refuses as
not advancing counts as written. Any other checkpoint failure is still
returned, and only the next step the policy makes due tries again.

Signed-off-by: Ray Karnes <ray.karnes@stablekernel.com>

* fix(durable): fold in the review's notes on Drain and checkpoints

The README and overview gave a stale reason for stopping a healthy
Handle before handing its instance on: Drain now covers a step still
recording, and the reason is that a step can start after Drain returns.
The CHANGELOG now says a recorded step on a failed Handle returns
ErrHandleFailed, and that a retried deferred checkpoint's failure goes to
the step that tried it. Fire and Tick say how a checkpoint failure reaches
them. A deferred checkpoint is kept from its finishing caller for any
context error the Store reports, not only the one that ended that
caller's context.

Signed-off-by: Ray Karnes <ray.karnes@stablekernel.com>

---------

Signed-off-by: Ray Karnes <ray.karnes@stablekernel.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

confirmed:api-compatibility ACR clean: api-compatibility confirmed:concurrency-discipline ACR clean: concurrency-discipline confirmed:correctness ACR clean: correctness confirmed:human-readability ACR clean: human-readability confirmed:missed-context ACR clean: missed-context confirmed:regression-safety ACR clean: regression-safety confirmed:replay-determinism ACR clean: replay-determinism ready All ACR dimensions confirmed - clear to merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants