feat(world-postgres): event-first start-hook admission

Adds the workflow_hook_claims table (single-owner token constraint;
lifecycle state derived from hookId/expiresAt). run_created claims the
token in the same transaction as the run and event inserts, createHook
materializes the claim, disposal and run completion retain TTL-carrying
claims with set-based statements, cancellation releases unmaterialized
claims, and terminal-run cleanup GCs expired claim debris. Also lifts
the postgres-lane skip from the start-hook e2e test.

Author: NathanColosimo

.changeset/start-hook-world-postgres.md

@@ -0,0 +1,5 @@
+---
+"@workflow/world-postgres": minor
+---
+
+Support experimental start-hook admission (event-first): a new `workflow_hook_claims` table backs single-owner hook tokens; `run_created` claims the token in the same transaction as run and event creation, claims are retained for their TTL after hook disposal or run completion, and cancellation releases claims the workflow never materialized.

packages/core/e2e/e2e.test.ts

@@ -1863,12 +1863,7 @@ describe('e2e', () => {
     }
   );
 
-  // Postgres world support lands in the next PR of this stack; drop the
-  // WORKFLOW_TARGET_WORLD clause there.
-  test.skipIf(
-    !!process.env.WORKFLOW_VERCEL_ENV ||
-      process.env.WORKFLOW_TARGET_WORLD === '@workflow/world-postgres'
-  )(
+  test.skipIf(!!process.env.WORKFLOW_VERCEL_ENV)(
     'experimentalStartHook rejects duplicate starts before hook materialization',
     { timeout: 60_000 },
     async () => {

packages/world-postgres/src/drizzle/migrations/0016_add_hook_claims.sql

@@ -0,0 +1,12 @@
+CREATE TABLE IF NOT EXISTS "workflow"."workflow_hook_claims" (
+	"token" varchar PRIMARY KEY NOT NULL,
+	"run_id" varchar NOT NULL,
+	"hook_id" varchar,
+	"ttl_seconds" integer NOT NULL,
+	"expires_at" timestamp,
+	"created_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "workflow_hook_claims_run_id_index" ON "workflow"."workflow_hook_claims" USING btree ("run_id");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "workflow_hook_claims_expires_at_index" ON "workflow"."workflow_hook_claims" USING btree ("expires_at");

packages/world-postgres/src/drizzle/migrations/meta/_journal.json

@@ -113,6 +113,13 @@
       "when": 1782691200000,
       "tag": "0015_move_enums_to_workflow_schema",
       "breakpoints": true
+    },
+    {
+      "idx": 16,
+      "version": "7",
+      "when": 1782777600000,
+      "tag": "0016_add_hook_claims",
+      "breakpoints": true
     }
   ]
 }

packages/world-postgres/src/drizzle/schema.ts

@@ -218,6 +218,33 @@ export const hooks = schema.table(
   (tb) => [index().on(tb.runId), index().on(tb.token)]
 );
 
+/**
+ * Hook-token claims: the single-owner constraint behind hook tokens.
+ *
+ * A claim's lifecycle state is derived, not stored:
+ * - unmaterialized start claim: `hookId IS NULL` (reserved by `start()`,
+ *   no hook entity yet)
+ * - materialized: `hookId` set, `expiresAt IS NULL` (live hook entity)
+ * - retained: `expiresAt` set (hook disposed / run finished; the token
+ *   stays fenced until `expiresAt`)
+ *
+ * `ttlSeconds <= 0` marks a plain `createHook` token guard with no
+ * retention window — it is released when the hook is disposed or the run
+ * reaches a terminal state.
+ */
+export const hookClaims = schema.table(
+  'workflow_hook_claims',
+  {
+    token: varchar('token').primaryKey(),
+    runId: varchar('run_id').notNull(),
+    hookId: varchar('hook_id'),
+    ttlSeconds: integer('ttl_seconds').notNull(),
+    expiresAt: timestamp('expires_at'),
+    createdAt: timestamp('created_at').defaultNow().notNull(),
+  },
+  (tb) => [index().on(tb.runId), index().on(tb.expiresAt)]
+);
+
 export const waits = schema.table(
   'workflow_waits',
   {

packages/world-postgres/src/index.ts

@@ -58,6 +58,7 @@ export function createWorld(
 
   return {
     specVersion: SPEC_VERSION_CURRENT,
+    experimentalStartHookAdmission: { mode: 'event-first' },
     ...storage,
     ...streamer,
     ...queue,