Slot event identity (SDK 1/4): per-kind correlation ids and run-scoped idempotency keys - #3228
Slot event identity (SDK 1/4): per-kind correlation ids and run-scoped idempotency keys#3228VaguelySerious wants to merge 5 commits into
Conversation
… keys Adds the client half of slot-based event identity, dormant until a run is stamped at spec version 6. - `@workflow/world` gains `slot-identity.ts` (26-char zero-padded decimal bodies, so a slot is a valid ULID body everywhere a ULID is accepted), `SPEC_VERSION_SLOT_IDENTITY` and `usesSlotIdentity()`. - `nextCorrelationId(kind)` on the orchestrator context is now the only place step and wait correlation ids are minted. In slot mode each kind counts independently from 1; otherwise it delegates to the same seeded ULID generator as before, so existing runs are byte-identical. - Every queue idempotency key is scoped to the run. Queues dedupe per queue, which is per workflow, so slot-numbered correlation ids would otherwise collide across concurrent runs of one workflow — silently, because a deduped send is answered normally and never dispatched. A source-scan test asserts no site builds a key any other way. - `packages/world` had test files but no `test` script, so 10 files never ran in CI. Added one.
🦋 Changeset detectedLatest commit: c55dc1e The changes in this PR will be included in the next version bump. This PR includes changesets to release 20 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
🧪 E2E Test Results❌ Some tests failed ❌ Failed E2E Tests▲ Vercel Production (1 failed)example (1 failed):
E2E Test SummarySummary
Details by Category❌ ▲ Vercel Production
✅ 💻 Local Development
✅ 📦 Local Production
✅ 🐘 Local Postgres
✅ 🪟 Windows
✅ 📋 Other
✅ vercel-multi-region
|
📊 Workflow Benchmarkscommit Backend:
📈 STSO distribution vs main (inline / queue-hop histograms)1020 steps (inline) Cumulative STSO time: main 437759ms → this run 425313ms (Δ -12446ms, -3%) 1020 steps (queue-hop) Cumulative STSO time: main 8262ms → this run 6341ms (Δ -1921ms, -23%) 📜 Previous results (1)3ae14e7Thu, 30 Jul 2026 21:39:47 GMT · run logs
ℹ️ Metric definitions & methodologyThe collapsed STSO distribution section above buckets every step gap of the sequential-steps run (not a sampled window), split by whether the step ending the gap ran inline — in the same warm process as the step before it, so the gap is pure framework overhead — or after a queue-hop — the first step of a fresh process, which pays queue dispatch, client reinit and event-log replay. Bars overlay the two runs: Best/P75/P90/P99 deltas compare against the most recent benchmark run on Metrics — TTFS: time to first step body (in-deployment start() → first step body, deployment clocks) · STSO: step-to-step overhead (gap between consecutive step bodies) · WO: workflow overhead (whole-run time outside step bodies, in-deployment anchored) · SL: stream latency (in-deployment write → read propagation, readAt - writtenAt) · SO: stream overhead (end-to-end write+consume time beyond the modelled generation window) Scenarios — step: one trivial no-op step, no stream; no hooks, so the run stays in turbo mode (in-process fast path) · stream: one streaming step; no hooks, so the run stays in turbo mode (in-process fast path) · hook + stream: registers a hook before one step, which exits turbo mode (dispatch path) · 1020 steps: 1020 trivial sequential steps; STSO is measured between consecutive steps in the given step ranges, and WO is the whole-run overhead outside step bodies · stream latency: parallel reader/writer steps on a dedicated stream; SL is the in-deployment write->read propagation (readAt - writtenAt) · stream overhead (text): writer streams 300 variable-length text token deltas paced at 100/s for 3s (a haiku-size LLM's token throughput) while a parallel reader drains the whole stream; SO is the end-to-end write+consume time beyond the 3s generation window (overhead/backpressure) · stream overhead (structured): same workload as stream overhead (text), but each delta is an AI-SDK-style structured object ({ type: 'text-delta', id, text }) instead of a raw string, so the SO gap vs the text scenario is the added serialization cost 🔴 marks a percentile over its target (within target is left unmarked). Targets (p75/p90/p99, ms) — TTFS 200/300/600 · SL 50/60/125 · SO 250/500/1000 All metrics are measured from deployment-side timestamps only. Runs are triggered by an in-deployment route that stamps the anchor ( Cold starts are kept in the numbers on purpose — they are part of real bursty-workload latency. The workbench deployment cold-starts the |
VaguelySerious
changed the title
|
(AI) Superseded by #3305, which combines this stack into a single PR. The correlation-id renumbering that this stack carried is dropped: it was separable from slot event identity, and it dragged in prerequisites of its own (run-scoped queue idempotency keys, run-scoped step keys). Correlation ids stay ULIDs. |
1 participant
First of four SDK PRs for slot-based event identity. Client half of the groundwork; dormant — nothing stamps spec version 6 yet, so every run still takes the ULID path byte-for-byte.
What
@workflow/worldslot-identity.ts:slotIdBody(slot)/slotFromId(id)/isSlotId(id),FIRST_SLOT = 1,SLOT_ID_WIDTH = 26. A slot body is a 26-char zero-padded decimal, which is a valid Crockford base32 (ULID) body — so every existing schema, sort key, range fence andeid:cursor keeps working unchanged. Slots start at 1 because slot 0 is the inclusive lower fence for range queries.SPEC_VERSION_SLOT_IDENTITY = 6andusesSlotIdentity(). Deliberately notSPEC_VERSION_CURRENT:requiresNewerWorld()is what makes a world reject runs it can't read, so bumping current before the worlds can allocate slots would have them reject their own new runs. That bump lands last.testscript, so none of them ran in CI. Added one.@workflow/corenextCorrelationId(kind)on the orchestrator context is now the only place step and wait correlation ids are minted (step.ts,workflow/sleep.ts). In slot mode each kind counts independently from 1; otherwise it delegates to the same seeded ULID generator, in the same call order, as today.specVersion, never from the build. A run whose log holdsstep_01K…must keep proposing ULIDs however new the code replaying it is, or it would proposestep_…001and match no existing entity.Run-scoped queue idempotency keys —
runScopedKey(runId, …parts), threaded throughbackstopIdempotencyKey,getWaitContinuationDispatch, and the step-dispatch and delayed-retry sends.Queues dedupe on
(queue, idempotencyKey), and a queue is per workflow, not per run. Once correlation ids are slot-numbered, the first step of every run of a workflow isstep_…001, so two concurrent runs would submit the same key. The failure is total and silent: the send is answered normally with a fresh message id, the duplicate is excluded from notifications, no callback is ever dispatched, the orchestrator acks — and the inline-ownership backstop can't recover it because it needs astep_startedthat never happened. There is no error to find afterwards, so a source-scan test asserts that no site inpackages/corebuilds anidempotencyKeyany other way.This is a prerequisite, not a live bug fix: the VM's ULID seed already includes the run id, so today's correlation ids are run-unique.
Tests
world: slot bodies pad to ULID width and parse as ULIDs, order lexicographically by slot, reject 0/-1/1.5;slotFromIdround-trips prefixed and bare bodies and reads nothing out of a ULID, the all-zero fence, or a wrong-width body.core: dense per-kind numbering; two fresh invocations issue identical sequences; interleaved allocations of other kinds don't renumber steps or waits; ULID mode still draws one shared sequence across kinds.core: the idempotency-key source scan (verified to fail when an unscoped site is introduced), plus per-run isolation tests for the backstop and wait-continuation keys.Full
packages/core(1666),packages/world(87) andpackages/world-vercel(309) unit suites pass;turbo typecheckgreen across 41 tasks.Note for review
WORKFLOW_SERVER_URL_OVERRIDEis set in its own commit (bb04d1c) and points at the top of the paired backend stack, so e2e runs against a backend that can accept and allocate slots. Reverting that one commit is all that's needed before merge. The follow-up commit making the last three v4 mock tests honor the override is a permanent fix and should stay.Stack: #3228 → #3234 → #3246 → #3247
Paired backend stack (world-vercel side): 6 PRs, all rebased on main and stacked;
WORKFLOW_SERVER_URL_OVERRIDEpoints at the top of it and must be reverted before merge.