feat(world-local): support Hook minimum retention - #2866
Conversation
🦋 Changeset detectedLatest commit: f204f71 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✅ All tests passed E2E Test SummarySummary
Details by Category✅ ▲ Vercel Production
✅ 💻 Local Development
✅ 📦 Local Production
✅ 🐘 Local Postgres
✅ 🪟 Windows
✅ 📋 Other
✅ vercel-multi-region
|
697002e to
d6a289a
Compare
…local # Conflicts: # docs/content/docs/v5/api-reference/workflow/create-hook.mdx # docs/content/docs/v5/foundations/idempotency.mdx # packages/core/src/workflow/hook.test.ts # packages/world-local/src/storage.test.ts # packages/world-local/src/storage/events-storage.ts # packages/world-local/src/storage/helpers.ts # packages/world-vercel/src/events.ts
Signed-off-by: Nathan Colosimo <110621881+NathanColosimo@users.noreply.github.com>
Signed-off-by: Nathan Colosimo <110621881+NathanColosimo@users.noreply.github.com>
📊 Workflow Benchmarkscommit Backend:
📈 STSO distribution vs main (inline / queue-hop histograms)1020 steps (inline) Cumulative STSO time: main 145277ms → this run 416203ms (Δ +270926ms, +186%) 1020 steps (queue-hop) Cumulative STSO time: main 3471ms → this run 8832ms (Δ +5361ms, +154%) 📜 Previous results (6)d3bf2a3Mon, 03 Aug 2026 21:47:28 GMT · run logs
6f1e4c2Mon, 03 Aug 2026 19:16:57 GMT · run logs
28d27f5Sun, 02 Aug 2026 01:36:38 GMT · run logs
5fad298Sat, 01 Aug 2026 21:46:55 GMT · run logs
737a7b1Mon, 27 Jul 2026 22:59:55 GMT · run logs
0057b6cMon, 27 Jul 2026 22:09:41 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 |
Signed-off-by: Nathan Colosimo <110621881+NathanColosimo@users.noreply.github.com>
…local # Conflicts: # packages/world-local/src/storage/events-storage.ts
…local # Conflicts: # packages/world-local/src/index.ts # packages/world-local/src/storage/events-storage.ts
VaguelySerious
left a comment
VaguelySerious
left a comment
There was a problem hiding this comment.
AI review: blocking issues found
VaguelySerious
left a comment
VaguelySerious
left a comment
There was a problem hiding this comment.
AI review: approved.
AI Review: Note
Before merge, both Worlds should enforce a default maximum retention of 30d, overridable by environment variable.
experimental_minRetention is unbounded today. createHook() validates the webhook combination and the World capability, then hands whatever the caller passed to parseDurationToDate with no ceiling, so '10y' or a Date in 2099 is honored verbatim by both backends. Two reasons that matters more here than it looks:
- Neither World reaps an expired retained Hook on its own. world-postgres never deletes the row unless someone creates a Hook with the same token again; world-local only reaps lazily when a read happens to touch it. An unbounded deadline is therefore effectively a permanent row, and the token stays reserved for as long as it says.
- The deadline is pinned once at
createHook()and re-pinned from the persistedhook_createdon replay. That is the right design, but it also means a mistake is durable: there is no later opportunity to correct an over-long value for runs already in flight.
A few things worth settling while wiring the cap:
- Clamp, don't reject. Silently truncating 90d to 30d is surprising, so the clamp should be visible in a log at minimum.
- Clamp before the value reaches the event log, so the persisted deadline is the effective one and replay stays deterministic. A consequence to state explicitly: raising or lowering the env var later will not retroactively move deadlines already persisted, which I think is the behavior you want.
- Use one env var name shared by both Worlds rather than a
WORKFLOW_LOCAL_*/WORKFLOW_POSTGRES_*pair, so the two cannot drift, and document it per the repo rule that every user-configurable environment variable is documented. - The
create-hookdocs page should state the default ceiling next to the existing retention section, since"30d"is the example value there and would sit exactly at the limit.
My agent misunderstood - I think it's fine to have separate variables |
|
Review the following changes in direct dependencies. Learn more about Socket for GitHub.
|
2 participants
Summary
experimental_minRetentionin the Local WorldhookRetentionWorld capabilityWorkflowWorldErrorWORKFLOW_LOCAL_HOOK_RETENTION_LIMIT_DAYSdispose()is calledThe core API and event contract are already on
main. This PR implements that contract for the Local World; it does not add an external token-release API.Behavior
experimental_minRetentionis measured from Hook creation. It is a minimum:hook.dispose()removes the Hook and releases its token immediatelyWORKFLOW_LOCAL_HOOK_RETENTION_LIMIT_DAYScan change that limit so development matches productionImplementation
The absolute
tokenRetentionUntildeadline is stored on thehook_createdevent, the Hook entity, and the existing token claim. The Hook entity is authoritative during terminal cleanup; the event and claim preserve crash recovery without introducing a retained-only data type.The Local World resolves its retention limit when storage is created.
events.create()rejects an oversizedhook_createdrequest before acquiring Hook locks or writing an event, Hook, or token claim. The error is aWorkflowWorldErrorwith status 400, so the runtime treats it as deterministic and does not retry it as an infrastructure failure.Hook claim replacement and release use a bounded per-token filesystem lock because separate Local World processes can share one data directory. The critical section covers only claim recovery and the read-delete-create handoff. A compromised lock fails the current operation instead of throwing from a timer and crashing the process.
When a run completes, fails, or is cancelled, terminal cleanup keeps the Hook and token claim only while retention remains. Hook reads are pure: after the deadline they hide the terminal Hook without deleting storage. The next creator lazily removes the expired claim and claims the token.
The existing per-Hook lifecycle lock still serializes creation, resume, and disposal for one Hook. Independent Hooks in the same run are not serialized.
Postgres explicitly excludes the new Hook field from its schema assertion until its separate retention implementation adds a column and behavior.
Verification
@workflow/world-localTypeScript check passedDocs Preview
createHook()minimum retention