Skip to content

feat(workflow-world): implement the Workflow SDK 5 World contract (spec 8) - #5880

Open
VaguelySerious wants to merge 1 commit into
rivet-dev:mainfrom
VaguelySerious:peter/workflow-v5-spec-8
Open

VaguelySerious wants to merge 1 commit into
rivet-dev:mainfrom
VaguelySerious:peter/workflow-v5-spec-8

Conversation

@VaguelySerious

Copy link
Copy Markdown

(AI) Brings @rivet-dev/workflow-world up to the Workflow SDK 5 World contract. Today it pins @workflow/world@5.0.0-beta.21, whose SPEC_VERSION_CURRENT is 5, so workflow@5.2.2 refuses it at startup ("supports Worlds with spec version 6 through 8").

  • Event ids are now positions in the run's log (slotToEventId, evnt_…0001 first). Each run's actor allocates the next slot inside the same transaction that appends the event, with event_id as the primary key, so the log stays dense and never has holes. No noop events are ever written.
  • Bump-and-report: a write whose eventCount is behind the log still commits at the next slot, and returns the events in the slots it skipped (events / cursor / hasMore).
  • Declares specVersion with mintedSpecVersion() (8 by default, 6 under WORKFLOW_SEALED_LOG=0). Hook token takeover (capabilities.hookForceClaim) is not implemented, so it stays unadvertised and createHook({ experimental_force: true }) fails closed.
  • A finished run refuses run_started and step_started with RunExpiredError, and still accepts step_completed / step_failed / step_retrying for a step that was running when the run finished.
  • A lazy step_started for a step that already exists now throws EntityConflictError. Before, the loser of a concurrent lazy start got the winner's step back, and could run the step body a second time. A start for a completed step is refused too.
  • steps.get and events.listByCorrelationId take the run id and go straight to the run actor, so they no longer look anything up through the coordinator.
  • All queue messages go to the flow route. v5 removed the step queue kind.
  • runs.list accepts an array of statuses.
  • CreateEventParams carries a function (replayEventObserver) that can't be serialized across the actor RPC, so only the params the actor reads are forwarded. Without this every run_started failed with Value of type "function" is not CBOR serializable.
  • Bumps @workflow/world and @workflow/errors to 5.0.4 and @workflow/world-testing to 5.0.5, adds @workflow/utils for a process-wide id factory, and moves examples/workflow-sdk to workflow@5.2.2 (workflow@5.0.0-beta.35 would refuse a spec 8 World).
  • Adds integration tests: dense slots under 12 concurrent appends, bump-and-report, and the terminal-run rules.

Rollout: runs written by earlier releases have ULID event ids, and the v5 runtime cannot replay them. All runs are served by the deployment at WORKFLOW_RUNTIME_URL, so in-flight runs need to finish on the previous release before upgrading. The README now says this.

Verification (macOS, Node 24, published rivetkit / @rivetkit/engine-cli 2.3.27 instead of the workspace builds):

  • tsc --noEmit and tsc -p tsconfig.build.json: clean.
  • @workflow/world-testing@5.0.5 conformance: 14 passed, 2 skipped (the in-band fence tests, which are optional), including numbers events by position. retriable and fatal errors passed on its one retry.
  • scripts/integration/run.ts: all checks passed.
  • vitest tests/unit tests/integration: 70/73 passed. The 3 failures all assert on an error message, and that message reaches the client as An internal error occurred. One of them (a duplicate hook id cannot confirm a different token) fails the same way on main in this setup. With the message match dropped, the two new ones pass.
  • The 2.3.27 engine needs auth.admin_token in its config before it will start. I added it locally to run the conformance and integration scripts. It isn't in this diff.

Not done: the coordinator's correlation index is still written for every step, hook and wait, though nothing reads it anymore. Optional v5 surface that isn't implemented: events.createBatch, queueBatch, runs.waitForTerminalStatus, getRuntimeDeadline, and the sinceCursor delta.

@NathanFlurry

Copy link
Copy Markdown
Member

👀

@eersnington

Copy link
Copy Markdown
Member

will take a look!

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants