Documentation menu

Commit Outcomes and Frame Events

Maintain the correct client baseline by treating acceptance, GPU submission, and display activation as distinct milestones.

A scene update passes through retained publication, GPU submission, and display activation before its result is visible. Each stage answers a different question for the client, so Hera reports them through separate messages. Maintaining the correct scene baseline depends on handling the retained outcome independently of later frame progress.

CommitAccepted

CommitAccepted { surface_id, commit_id } means that the atomic diff has been published in retained state. A reconciler can promote that candidate to its accepted baseline and publish the corresponding callbacks and ownership changes.

Once acceptance arrives, the server may still have rendering work ahead of it. Several accepted commits can contribute to the same frame, so a client can advance its baseline without expecting every intermediate scene to appear as a separate image.

CommitRejected

If validation fails before retained publication, CommitRejected identifies the surface and commit and supplies an error code and message. The rejected update will not receive CommitAck, while previously accepted updates remain valid. This gives the client a definite outcome against which to preserve its earlier baseline.

Keep the previous accepted tree as the reconciliation baseline. Application model writes that occurred before the attempt are separate from retained publication; rejecting a scene does not automatically undo those writes.

CommitAck

After renderer submission succeeds, the server claims the pending commit records covered by that submission and reports them through CommitAck. The acknowledgment therefore establishes GPU submission, while GPU completion, scanout activation, and imported-buffer retirement still require their own evidence.

A blocked or failed renderer attempt must leave submission responsibility available for a later successful frame.

FrameScheduled and FramePresented

Clients that coordinate work with the frame clock can use FrameScheduled to obtain a frame ID, estimated presentation timestamp, and render deadline in microseconds. These values are advisory: under output pressure, the server can coalesce pending hints or omit them without changing the retained outcome of a commit.

When an identified frame activates on the display, FramePresented reports its ID and presentation timestamp. The event concerns the composed frame, which may include several client updates, so it cannot be interpreted as a separate result for each commit.

A Practical Client State Machine

Keep an accepted scene and at most one pending candidate when using the Hera Kit hosting model. Send a nonempty candidate, continue processing ordered server events, and wait for its matching accepted or rejected outcome before publishing another candidate.

A matching acceptance lets the host promote its candidate and evaluate later changes against it. A rejection instead leaves the accepted tree in place and discards the candidate baseline. If transport failure or an uncorrelated generic error makes publication ambiguous, the host ends the session because it can no longer safely choose a baseline.

This one-candidate policy is Hera Kit's hosting discipline. It is not a claim that the wire contract requires every independently implemented client to use the identical scheduling strategy.

Source Reference

The following files in the Hera checkout define the behavior described on this page.

  • crates/protocol/src/messages.rs
  • crates/server/src/client/commits.rs
  • crates/server/src/frame/mod.rs
  • crates/kit/src/threading/mod.rs