migrating-world-v4-to-v5

Migrating a World from the v4 spec to v5

This skill is for a package that implements World from @workflow/world: a storage, queue and stream backend the Workflow runtime talks to. It is not for application code. If the task is bumping an app's workflow dependency, use the migrating-workflow-v4-to-v5 skill instead; if the app both uses Workflow and ships its own World, run that skill first and this one second.

An app on the Vercel, Local or Postgres World needs nothing from this skill. Those ship with the SDK and are already on the v5 spec.

One change dominates the work. Event ID allocation is required, is not visible from the type signatures, and a World that skips it type-checks, starts runs, and fails on the first replay. Do that part first, then the mechanical rewrites. Do not begin with the type errors: they are the small half, and finishing them produces a World that looks migrated and is not.

Intake

Before editing, establish and report each of these:

1. Where the World is. Grep for implements World, : World, World> and from '@workflow/world'. Read the factory it exports.
2. How event IDs are minted today. Grep for eventId, ulid, uuid, nanoid, nextval, AUTO_INCREMENT, IDENTITY. Find the exact line that produces the ID written to storage.
3. What settles a write race. Read the events.create implementation. Note whether the ID or ordering is decided in process (read-then-write, an in-memory counter, a Math.max over loaded events) or in the store (unique constraint, conditional write, INSERT ... ON CONFLICT, a transaction).
4. Which specVersion it declares. Grep for specVersion. Note whether it is a literal or an imported constant.
5. Which optional members exist. Grep for capabilities, analytics, getRuntimeDeadline, getEnvironment, createRunId, describeRun, getEncryptionKeyForRun, resolveLatestDeploymentId, cancelMany, experimentalSetAttributes.
6. Whether it provisions step topics. Grep for 'step', __wkf_step, stepQueue.
7. Whether it rejects stale writes. Grep for PreconditionFailedError, preconditionGuard, stateUpdatedAt, stateEventCount, stateCursor, 412.
8. Where its process-wide state lives. Grep the World's modules for top-level const/let holding a pool, client, socket, registry, cache, ULID factory, or a log-once boolean. Note every one: these are correct in a require()d package and wrong in a bundled one.
9. How it is tested. Grep for @workflow/world-testing and createTestSuite. A World without the conformance suite wired up gets it in this migration.
10. Where its runs live. Ask, or determine from the deployment model, whether a single deployment serves every run or a run is pinned to the deployment that created it. This decides the rollout in step 7 and cannot be read out of the code.