feat(events): phase 4.4 — SDK DLQ config per event

Add `dlq` option to `event()` allowing per-event DLQ configuration.
When `dlq.enabled` is false, failed event-triggered runs are silently
discarded instead of being stored in the dead letter queue.

- Add EventDLQConfig type to SDK and EventDLQManifest schema to core
- Add dlqConfig JSON column to EventDefinition model
- Wire config through deploy (createBackgroundWorker) and resource catalog
- DeadLetterService checks config before creating DLQ entries

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: giovaborgogno

apps/webapp/app/v3/services/createBackgroundWorker.server.ts

@@ -353,12 +353,14 @@ async function syncWorkerEvents(
           description: event.description,
           schema: event.schema as any ?? undefined,
           rateLimit: event.rateLimit as any ?? undefined,
+          dlqConfig: event.dlq as any ?? undefined,
           projectId: worker.projectId,
         },
         update: {
           description: event.description,
           schema: event.schema as any ?? undefined,
           rateLimit: event.rateLimit as any ?? undefined,
+          dlqConfig: event.dlq as any ?? undefined,
         },
       });
 

apps/webapp/app/v3/services/events/deadLetterService.server.ts

@@ -21,6 +21,16 @@ export class DeadLetterService extends BaseService {
       return; // Not an event-triggered run
     }
 
+    // Check if DLQ is disabled for this event type
+    const dlqEnabled = await this.isDLQEnabled(eventContext.eventType, run.projectId);
+    if (!dlqEnabled) {
+      logger.debug("DLQ disabled for event type, skipping", {
+        runId: run.id,
+        eventType: eventContext.eventType,
+      });
+      return;
+    }
+
     try {
       await this._prisma.deadLetterEvent.create({
         data: {
@@ -52,6 +62,24 @@ export class DeadLetterService extends BaseService {
     }
   }
 
+  private async isDLQEnabled(eventType: string, projectId: string): Promise<boolean> {
+    try {
+      const eventDef = await this._prisma.eventDefinition.findFirst({
+        where: { slug: eventType, projectId },
+        select: { dlqConfig: true },
+      });
+
+      if (!eventDef?.dlqConfig) {
+        return true; // Default: DLQ enabled
+      }
+
+      const config = eventDef.dlqConfig as Record<string, unknown>;
+      return config.enabled !== false;
+    } catch {
+      return true; // On error, default to enabled
+    }
+  }
+
   private extractEventContext(run: TaskRun): EventContext | null {
     if (!run.metadata) return null;
 

internal-packages/database/prisma/migrations/20260304064319_add_dlq_config_to_event_definition/migration.sql

@@ -0,0 +1,2 @@
+-- AlterTable
+ALTER TABLE "public"."EventDefinition" ADD COLUMN     "dlqConfig" JSONB;

internal-packages/database/prisma/schema.prisma

@@ -604,6 +604,9 @@ model EventDefinition {
   // Rate limiting (Phase 7) — JSON config e.g. { "limit": 100, "window": "1m" }
   rateLimit Json?
 
+  // DLQ configuration (Phase 4.4) — JSON config e.g. { "enabled": false }
+  dlqConfig Json?
+
   project   Project @relation(fields: [projectId], references: [id], onDelete: Cascade, onUpdate: Cascade)
   projectId String
 

packages/core/src/v3/resource-catalog/catalog.ts

@@ -11,6 +11,8 @@ export interface EventMetadata {
   rateLimit?: { limit: number; window: string };
   /** Ordering configuration — enables per-key serialization with global concurrency limit */
   ordering?: { concurrencyLimit?: number };
+  /** Dead letter queue configuration */
+  dlq?: { enabled?: boolean };
 }
 
 export interface ResourceCatalog {

packages/core/src/v3/resource-catalog/standardResourceCatalog.ts

@@ -192,6 +192,7 @@ export class StandardResourceCatalog implements ResourceCatalog {
       description: event.description,
       rateLimit: event.rateLimit,
       ordering: event.ordering,
+      dlq: event.dlq,
     }));
   }
 

packages/core/src/v3/schemas/schemas.ts

@@ -190,6 +190,13 @@ export const EventOrderingManifest = z.object({
 
 export type EventOrderingManifest = z.infer<typeof EventOrderingManifest>;
 
+export const EventDLQManifest = z.object({
+  /** Whether to store failed event-triggered runs in the DLQ (default: true) */
+  enabled: z.boolean().optional(),
+});
+
+export type EventDLQManifest = z.infer<typeof EventDLQManifest>;
+
 export const EventManifest = z.object({
   /** Unique event identifier (e.g. "order.created") */
   id: z.string(),
@@ -203,6 +210,8 @@ export const EventManifest = z.object({
   rateLimit: EventRateLimitManifest.optional(),
   /** Ordering configuration — creates a dedicated queue with per-key serialization */
   ordering: EventOrderingManifest.optional(),
+  /** Dead letter queue configuration */
+  dlq: EventDLQManifest.optional(),
 });
 
 export type EventManifest = z.infer<typeof EventManifest>;

packages/trigger-sdk/src/v3/events.ts

@@ -51,6 +51,19 @@ export interface EventOptions<TId extends string, TSchema extends Schema | undef
    * ```
    */
   ordering?: EventOrdering;
+  /**
+   * Dead letter queue configuration. Controls what happens when event-triggered runs fail.
+   * By default, all failed runs are stored in the DLQ for inspection and retry.
+   *
+   * @example
+   * ```ts
+   * event({
+   *   id: "order.created",
+   *   dlq: { enabled: false }, // Don't store failures in DLQ
+   * });
+   * ```
+   */
+  dlq?: EventDLQConfig;
 }
 
 /** Ordering configuration for an event */
@@ -59,6 +72,16 @@ export interface EventOrdering {
   concurrencyLimit?: number;
 }
 
+/** Dead letter queue configuration for an event */
+export interface EventDLQConfig {
+  /**
+   * Whether to store failed event-triggered runs in the DLQ.
+   * When false, failed runs are discarded silently.
+   * @default true
+   */
+  enabled?: boolean;
+}
+
 /** Options for publishing an event */
 export interface PublishEventOptions {
   /** Idempotency key to prevent duplicate publications */
@@ -189,7 +212,7 @@ export function createEvent<TId extends string>(
 export function createEvent<TId extends string, TSchema extends Schema | undefined = undefined>(
   options: EventOptions<TId, TSchema>
 ): EventDefinition<TId, any> {
-  const { id, schema, description, version = "1.0", rateLimit, ordering } = options;
+  const { id, schema, description, version = "1.0", rateLimit, ordering, dlq } = options;
 
   // Build the parse function if a schema is provided
   let parseFn: SchemaParseFn<any> | undefined;
@@ -318,6 +341,7 @@ export function createEvent<TId extends string, TSchema extends Schema | undefin
     rawSchema: schema,
     rateLimit,
     ordering,
+    dlq,
   });
 
   // Mark as event for runtime detection