feat(world-vercel): support Hook minimum retention

.changeset/local-hook-min-retention.md

@@ -0,0 +1,8 @@
+---
+'@workflow/world': minor
+'@workflow/world-local': minor
+'@workflow/web-shared': patch
+'@workflow/world-postgres': patch
+---
+
+Keep Hook tokens reserved through their configured minimum retention.

.changeset/postgres-hook-min-retention.md

@@ -0,0 +1,5 @@
+---
+'@workflow/world-postgres': minor
+---
+
+Keep Hook tokens reserved through their configured minimum retention.

.changeset/vercel-hook-min-retention.md

@@ -0,0 +1,5 @@
+---
+'@workflow/world-vercel': minor
+---
+
+Support Hook minimum retention on Vercel.

docs/content/docs/v5/api-reference/workflow/create-hook.mdx

@@ -187,7 +187,7 @@ After the workflow ends, [`getHookByToken()`](/docs/api-reference/workflow-api/g
 </Callout>
 
 <Callout type="warn">
-This option is experimental. If the configured World does not support it, the workflow fails when registering the Hook. `createWebhook()` does not accept this option.
+This option is experimental. Worlds can limit how long tokens are retained; see [World configuration](/docs/configuration/worlds) for each World's limit. If the configured World does not support minimum retention, the workflow fails when registering the Hook. `createWebhook()` does not accept this option.
 </Callout>
 
 ### Waiting for Multiple Payloads

docs/content/docs/v5/configuration/worlds.mdx

@@ -104,6 +104,13 @@ The Local World is the default outside Vercel and is intended for development.
 - Default: `true`
 - Re-enqueues pending and running local runs when the World starts. Set the environment variable to `0` or `false` to skip recovery; the factory option wins when both are set.
 
+### `WORKFLOW_LOCAL_HOOK_RETENTION_LIMIT_DAYS`
+
+- Factory option: none
+- Default: `30`
+- Maximum [`experimental_minRetention`](/docs/api-reference/workflow/create-hook#keep-a-token-unavailable-after-the-run-ends) accepted by the Local World, in days.
+- Set this to the same limit as your production World so oversized values fail during local development.
+
 ### `tag`
 
 - Environment variable: none
@@ -160,6 +167,13 @@ The Postgres World is a self-hosted durable backend for long-running server proc
 - Default: `pg` default
 - Maximum size of the internal `pg.Pool` when the World creates the pool.
 
+### `WORKFLOW_POSTGRES_HOOK_RETENTION_LIMIT_DAYS`
+
+- Factory option: none
+- Default: `30`
+- Maximum [`experimental_minRetention`](/docs/api-reference/workflow/create-hook#keep-a-token-unavailable-after-the-run-ends) accepted by the Postgres World, in days.
+- Set this to the same limit as your production World so oversized values fail during development.
+
 ### `namespace`
 
 - Environment variable fallback: `WORKFLOW_QUEUE_NAMESPACE`

docs/content/worlds/v5/local.mdx

@@ -74,6 +74,10 @@ Maximum gap in milliseconds between response body chunks from a local queue hand
 
 Whether pending and running runs found in the data directory are re-enqueued when the world starts. Set to `0` or `false` to skip recovery and leave stale runs untouched. Default: `true`
 
+### `WORKFLOW_LOCAL_HOOK_RETENTION_LIMIT_DAYS`
+
+Maximum [`experimental_minRetention`](/docs/api-reference/workflow/create-hook#keep-a-token-unavailable-after-the-run-ends) accepted by the Local World, in days. Default: `30`. Set this to the same limit as your production World so oversized values fail during local development.
+
 ### `WORKFLOW_STREAM_FLUSH_INTERVAL_MS`
 
 Group-commit window, in milliseconds, for the leading chunk of an idle stream. Default: `0` (dispatch immediately). A positive value holds the first chunk up to that long to collect a group — trading first-chunk latency for fewer requests. Chunks arriving while a request is in flight always coalesce into the next group regardless.

docs/content/worlds/v5/postgres.mdx

@@ -218,6 +218,10 @@ For higher worker concurrency, Graphile Worker recommends setting `maxPoolSize`
 
 Set to `1` when the application or framework coordinates shutdown and awaits `world.close()` before closing its workflow HTTP server and any caller-owned pool. Default: unset (`false`).
 
+### `WORKFLOW_POSTGRES_HOOK_RETENTION_LIMIT_DAYS`
+
+Maximum [`experimental_minRetention`](/docs/api-reference/workflow/create-hook#keep-a-token-unavailable-after-the-run-ends) accepted by the Postgres World, in days. Default: `30`. Set this to the same limit as your production World so oversized values fail during development.
+
 ### `WORKFLOW_QUEUE_NAMESPACE`
 
 Queue topic namespace shared by build output and the Postgres World. Default: unset.

docs/content/worlds/v5/vercel.mdx

@@ -91,6 +91,7 @@ const run = await start(myWorkflow, [input], { region: "sfo1" });
 ## Limitations
 
 - **No run migration** - A run's region is fixed at creation. Existing runs cannot be moved to a different region.
+- **Hook minimum retention** - [`experimental_minRetention`](/docs/api-reference/workflow/create-hook#keep-a-token-unavailable-after-the-run-ends) cannot exceed 30 days.
 
 ## Observability
 

packages/core/e2e/e2e.test.ts

@@ -1,3 +1,3 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { setTimeout as sleep } from 'node:timers/promises';
@@ -2047,6 +2047,36 @@
     }
   );
 
+  test(
+    'hookMinRetentionWorkflow - terminal Hook cannot resume and its token stays unavailable',
+    { timeout: 60_000 },
+    async () => {
+      const token = `retained-${Math.random().toString(36).slice(2)}`;
+      const owner = await start(await e2e('hookMinRetentionWorkflow'), [
+        token,
+        60_000,
+      ]);
+
+      expect(await owner.returnValue).toEqual({ role: 'owner' });
+
+      const hook = await getHookByToken(token);
+      expect(hook.runId).toBe(owner.runId);
+      await expect(resumeHook(hook, { duplicate: true })).rejects.toSatisfy(
+        (error: unknown) => HookNotFoundError.is(error)
+      );
+
+      const duplicate = await start(await e2e('hookMinRetentionWorkflow'), [
+        token,
+        60_000,
+      ]);
+      expect(await duplicate.returnValue).toEqual({
+        role: 'duplicate',
+        conflictRunId: owner.runId,
+        conflictStatus: 'completed',
+      });
+    }
+  );
+
   test(
     'hookAdoptOwnerResultWorkflow - duplicate adopts the owner result via conflict.returnValue',
     { timeout: 120_000 },

packages/web-shared/src/components/sidebar/attribute-panel.tsx

@@ -263,6 +263,7 @@ const attributeOrder: AttributeKey[] = [
   'runId',
   'attempt',
   'token',
+  'tokenRetentionUntil',
   'isWebhook',
   'isSystem',
   'receivedCount',
@@ -322,6 +323,7 @@ const attributeDisplayNames: Partial<Record<AttributeKey, string>> = {
   eventId: 'Event ID',
   runId: 'Run ID',
   token: 'Token',
+  tokenRetentionUntil: 'Minimum Retention Until',
   eventType: 'Event Type',
   errorCode: 'Error Code',
   correlationId: 'Correlation ID',
@@ -441,6 +443,7 @@ const attributeToDisplayFn: Record<
   attempt: (value: unknown) => String(value),
   // Hook details
   token: (value: unknown) => String(value),
+  tokenRetentionUntil: timestampWithTooltipOrNull,
   isWebhook: (value: unknown) => String(value),
   isSystem: (value: unknown) => String(value),
   receivedCount: (value: unknown) => String(value),

packages/world-local/package.json

@@ -35,6 +35,7 @@
     "@workflow/utils": "workspace:*",
     "@workflow/world": "workspace:*",
     "async-sema": "3.1.1",
+    "proper-lockfile": "4.1.2",
     "ulid": "catalog:",
     "undici": "catalog:",
     "zod": "catalog:"
@@ -43,6 +44,7 @@
     "@opentelemetry/api": "1.9.0",
     "@types/ms": "0.7.34",
     "@types/node": "catalog:",
+    "@types/proper-lockfile": "4.1.4",
     "@workflow/tsconfig": "workspace:*",
     "ms": "2.1.3",
     "typescript": "catalog:",

packages/world-local/src/fs.ts

@@ -573,7 +573,8 @@ interface PaginatedFileSystemQueryConfig<T> {
   cachedItems?: ReadonlyMap<string, T>;
   filePrefix?: string;
   fileIdFilter?: (fileId: string) => boolean;
-  filter?: (item: T) => boolean;
+  /** Runs concurrently for each read batch and must not mutate storage. */
+  filter?: (item: T) => boolean | Promise<boolean>;
   sortOrder?: 'asc' | 'desc';
   limit?: number;
   cursor?: string;
@@ -689,11 +690,13 @@ export async function paginatedFileSystemQuery<T extends { createdAt: Date }>(
     const loadedBatch = await Promise.all(
       batch.map(async (fileId): Promise<T | null> => {
         const filePath = path.join(resolvedDirectory, `${fileId}.json`);
+        let item: T | null;
         try {
           const cachedItem = cachedItems?.get(filePath);
-          return cachedItem === undefined
-            ? await readJSON(filePath, schema)
-            : structuredClone(cachedItem);
+          item =
+            cachedItem === undefined
+              ? await readJSON(filePath, schema)
+              : structuredClone(cachedItem);
         } catch (error: unknown) {
           // We don't expect zod errors to happen, but if the JSON does get malformed,
           // we skip the item. Preferably, we'd have a way to mark items as malformed,
@@ -707,13 +710,12 @@ export async function paginatedFileSystemQuery<T extends { createdAt: Date }>(
           }
           throw error;
         }
+        return item && filter && !(await filter(item)) ? null : item;
       })
     );
 
     for (const item of loadedBatch) {
       if (!item) continue;
-      // Apply custom filter early if provided
-      if (filter && !filter(item)) continue;
 
       // Double-check cursor filtering with actual createdAt from JSON
       // (in case ULID timestamp differs from stored createdAt)

packages/world-local/src/index.ts

@@ -74,6 +74,7 @@ export function createWorld(args?: Partial<Config>): LocalWorld {
   return {
     specVersion: SPEC_VERSION_CURRENT,
     capabilities: {
+      hookRetention: { active: true },
       // world-local deduplicates concurrent `hook_received` writes sharing a
       // `(runId, resumeId)` via a filesystem sidecar claim (see
       // events-storage.ts `claimHookResume`), so resumeHook()'s parallel fast