inngest 4.3.0 → 4.4.0

package/components/execution/engine.d.cts

@@ -4,6 +4,7 @@ import { MetadataUpdate } from "../InngestMetadata.cjs";
 import { BasicFoundStep, InngestExecutionFactory, MemoizedOp } from "./InngestExecution.cjs";
 import { OutgoingOp } from "../../types.cjs";
 import { StepError } from "../StepError.cjs";
+import { LazyOps } from "./lazyOps.cjs";
 
 //#region src/components/execution/engine.d.ts
 declare namespace engine_d_exports {
@@ -46,6 +47,13 @@ interface ExecutionState {
    * with state from the executor.
    */
   stepState: Record<string, MemoizedOp>;
+  /**
+   * Hashed defer step IDs the backend has already received. Used to skip
+   * re-emitting `DeferAdd` ops on replay. Defer ops aren't memoized like
+   * normal steps (they have no result), so this lives separately from
+   * `stepState`.
+   */
+  priorDefers: Record<string, unknown>;
   /**
    * The number of steps we expect to fulfil based on the state passed from the
    * Executor.
@@ -122,6 +130,12 @@ interface ExecutionState {
    * A buffer of steps that are currently queued to be checkpointed.
    */
   checkpointingStepBuffer: OutgoingOp[];
+  /**
+   * Buffer for opcode-only sync ops (e.g. `DeferAdd`) awaiting shipment
+   * on the next outbound wire message. See `ARCHITECTURE.md` and
+   * `lazyOps.ts` for the rationale.
+   */
+  lazyOps: LazyOps;
   /**
    * Metadata collected during execution to be sent with outgoing ops.
    */

package/components/execution/engine.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.cts","names":[],"sources":["../../../src/components/execution/engine.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;cAwHa,uBAAuB;;;;UAq6EnB,WAAA;;YACU,cAAc;;;IAt6E5B,KAAA,EAAA,OAAA;EAq6EI,CAAA;EAAW,mBAAA,EAAA;IACD,IAAA,EAAA,OAAA;;kBAIjB,EAAA;IACM,IAAA,EADN,UACM;IAAc,UAAA,EAAd,cAAc,EAAA;IAOzB,eAAU,EAAA,MAAA;EAAA,CAAA;iCACD,EAAA,CAAA,CAAA;yCAA+B,EAAA,CAAA,CAAA;;KADxC,UAAA,GAC0D,QAAnC,MAAd,WAAc,GAAA,QAAA,CAAA;EACpB,IAAA,EADqC,CACrC;AAAW,CAAA,GADgC,WAChC,CAD4C,CAC5C,CAAA,CAAA,EA+BnB,CAAA,MA/BQ,WA+BS,CAAA;AAAc,UAAd,cAAA,CAAc;;;;;;eAwBV,CAAA,EAlBH,QAkBG,CAlBM,IAkBN,CAlBW,UAkBX,EAAA,IAAA,CAAA,CAAA;;;;;WAoCK,EAhDb,MAgDa,CAAA,MAAA,EAhDE,UAgDF,CAAA;;;;;gBA6Cb,EAAA,MAAA;EAAG;AACf;AAgBkC;;OA4BjC,EA9HO,GA8HP,CAAA,MAAA,EA9HmB,SA8HnB,CAAA;;;;;;UAOE,EAAA,OAAA;EAAyB;AAoC7B;;;MAjFiC,EA3EzB,cA2EyB,CA3EV,UA2EU,EAAA,IAAA,EAAA,IAAA,CAAA;;;;wBAtET;;;;;;;;;;;;;;;0BAkBE;;;;;;;;;;;;;;;8BAgBI;;;;;;;;;;;;;;;;;;;;;2BAwBH;;;;aAKd,YAAY,MAAM;;;;;UAiBrB,yBAAA;;;;;;;;;;;;;;;iBA2BD,sBAAA;;;;;;mBAMU;YACP,YAAY;IACpB;;;;cAoCS;eAjFO,eAAa"}
+{"version":3,"file":"engine.d.cts","names":[],"sources":["../../../src/components/execution/engine.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;cA2Ha,uBAAuB;;;;UAmuFnB,WAAA;;YACU,cAAc;;;IApuF5B,KAAA,EAAA,OAAA;EAmuFI,CAAA;EAAW,mBAAA,EAAA;IACD,IAAA,EAAA,OAAA;;kBAIjB,EAAA;IACM,IAAA,EADN,UACM;IAAc,UAAA,EAAd,cAAc,EAAA;IAOzB,eAAU,EAAA,MAAA;EAAA,CAAA;iCACD,EAAA,CAAA,CAAA;yCAA+B,EAAA,CAAA,CAAA;;KADxC,UAAA,GAC0D,QAAnC,MAAd,WAAc,GAAA,QAAA,CAAA;EACpB,IAAA,EADqC,CACrC;AAAW,CAAA,GADgC,WAChC,CAD4C,CAC5C,CAAA,CAAA,EA+BnB,CAAA,MA/BQ,WA+BS,CAAA;AAAc,UAAd,cAAA,CAAc;;;;;;eAoBhB,CAAA,EAdG,QAcH,CAdY,IAcZ,CAdiB,UAcjB,EAAA,IAAA,CAAA,CAAA;;;;;WA8BS,EAtCX,MAsCW,CAAA,MAAA,EAtCI,UAsCJ,CAAA;;;;;;;aAsEX,EApGE,MAoGF,CAAA,MAAA,EAAA,OAAA,CAAA;EAAG;AACf;AAgBkC;;gBA4BjC,EAAA,MAAA;;;;;OAMU,EA3IH,GA2IG,CAAA,MAAA,EA3IS,SA2IT,CAAA;;;AAqCZ;;;UAjFiC,EAAA,OAAA;;;;;QAlFzB,eAAe;;;;wBAKC;;;;;;;;;;;;;;;0BAkBE;;;;;;;;;;;;;;;8BAgBI;;;;;;;;;;;;;;;;;;;;;2BAwBH;;;;;;WAOhB;;;;aAKE,YAAY,MAAM;;;;;UAiBrB,yBAAA;;;;;;;;;;;;;;;iBA2BD,sBAAA;;;;;;mBAMU;YACP,YAAY;IACpB;;;;cAoCS;eAjFO,eAAa"}

package/components/execution/engine.d.ts

@@ -4,6 +4,7 @@ import { MetadataUpdate } from "../InngestMetadata.js";
 import { BasicFoundStep, InngestExecutionFactory, MemoizedOp } from "./InngestExecution.js";
 import { OutgoingOp } from "../../types.js";
 import { StepError } from "../StepError.js";
+import { LazyOps } from "./lazyOps.js";
 
 //#region src/components/execution/engine.d.ts
 declare namespace engine_d_exports {
@@ -46,6 +47,13 @@ interface ExecutionState {
    * with state from the executor.
    */
   stepState: Record<string, MemoizedOp>;
+  /**
+   * Hashed defer step IDs the backend has already received. Used to skip
+   * re-emitting `DeferAdd` ops on replay. Defer ops aren't memoized like
+   * normal steps (they have no result), so this lives separately from
+   * `stepState`.
+   */
+  priorDefers: Record<string, unknown>;
   /**
    * The number of steps we expect to fulfil based on the state passed from the
    * Executor.
@@ -122,6 +130,12 @@ interface ExecutionState {
    * A buffer of steps that are currently queued to be checkpointed.
    */
   checkpointingStepBuffer: OutgoingOp[];
+  /**
+   * Buffer for opcode-only sync ops (e.g. `DeferAdd`) awaiting shipment
+   * on the next outbound wire message. See `ARCHITECTURE.md` and
+   * `lazyOps.ts` for the rationale.
+   */
+  lazyOps: LazyOps;
   /**
    * Metadata collected during execution to be sent with outgoing ops.
    */

package/components/execution/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","names":[],"sources":["../../../src/components/execution/engine.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;cAwHa,uBAAuB;;;;UAq6EnB,WAAA;;YACU,cAAc;;;IAt6E5B,KAAA,EAAA,OAAA;EAq6EI,CAAA;EAAW,mBAAA,EAAA;IACD,IAAA,EAAA,OAAA;;kBAIjB,EAAA;IACM,IAAA,EADN,UACM;IAAc,UAAA,EAAd,cAAc,EAAA;IAOzB,eAAU,EAAA,MAAA;EAAA,CAAA;iCACD,EAAA,CAAA,CAAA;yCAA+B,EAAA,CAAA,CAAA;;KADxC,UAAA,GAC0D,QAAnC,MAAd,WAAc,GAAA,QAAA,CAAA;EACpB,IAAA,EADqC,CACrC;AAAW,CAAA,GADgC,WAChC,CAD4C,CAC5C,CAAA,CAAA,EA+BnB,CAAA,MA/BQ,WA+BS,CAAA;AAAc,UAAd,cAAA,CAAc;;;;;;eAwBV,CAAA,EAlBH,QAkBG,CAlBM,IAkBN,CAlBW,UAkBX,EAAA,IAAA,CAAA,CAAA;;;;;WAoCK,EAhDb,MAgDa,CAAA,MAAA,EAhDE,UAgDF,CAAA;;;;;gBA6Cb,EAAA,MAAA;EAAG;AACf;AAgBkC;;OA4BjC,EA9HO,GA8HP,CAAA,MAAA,EA9HmB,SA8HnB,CAAA;;;;;;UAOE,EAAA,OAAA;EAAyB;AAoC7B;;;MAjFiC,EA3EzB,cA2EyB,CA3EV,UA2EU,EAAA,IAAA,EAAA,IAAA,CAAA;;;;wBAtET;;;;;;;;;;;;;;;0BAkBE;;;;;;;;;;;;;;;8BAgBI;;;;;;;;;;;;;;;;;;;;;2BAwBH;;;;aAKd,YAAY,MAAM;;;;;UAiBrB,yBAAA;;;;;;;;;;;;;;;iBA2BD,sBAAA;;;;;;mBAMU;YACP,YAAY;IACpB;;;;cAoCS;eAjFO,eAAa"}
+{"version":3,"file":"engine.d.ts","names":[],"sources":["../../../src/components/execution/engine.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;cA2Ha,uBAAuB;;;;UAmuFnB,WAAA;;YACU,cAAc;;;IApuF5B,KAAA,EAAA,OAAA;EAmuFI,CAAA;EAAW,mBAAA,EAAA;IACD,IAAA,EAAA,OAAA;;kBAIjB,EAAA;IACM,IAAA,EADN,UACM;IAAc,UAAA,EAAd,cAAc,EAAA;IAOzB,eAAU,EAAA,MAAA;EAAA,CAAA;iCACD,EAAA,CAAA,CAAA;yCAA+B,EAAA,CAAA,CAAA;;KADxC,UAAA,GAC0D,QAAnC,MAAd,WAAc,GAAA,QAAA,CAAA;EACpB,IAAA,EADqC,CACrC;AAAW,CAAA,GADgC,WAChC,CAD4C,CAC5C,CAAA,CAAA,EA+BnB,CAAA,MA/BQ,WA+BS,CAAA;AAAc,UAAd,cAAA,CAAc;;;;;;eAoBhB,CAAA,EAdG,QAcH,CAdY,IAcZ,CAdiB,UAcjB,EAAA,IAAA,CAAA,CAAA;;;;;WA8BS,EAtCX,MAsCW,CAAA,MAAA,EAtCI,UAsCJ,CAAA;;;;;;;aAsEX,EApGE,MAoGF,CAAA,MAAA,EAAA,OAAA,CAAA;EAAG;AACf;AAgBkC;;gBA4BjC,EAAA,MAAA;;;;;OAMU,EA3IH,GA2IG,CAAA,MAAA,EA3IS,SA2IT,CAAA;;;AAqCZ;;;UAjFiC,EAAA,OAAA;;;;;QAlFzB,eAAe;;;;wBAKC;;;;;;;;;;;;;;;0BAkBE;;;;;;;;;;;;;;;8BAgBI;;;;;;;;;;;;;;;;;;;;;2BAwBH;;;;;;WAOhB;;;;aAKE,YAAY,MAAM;;;;;UAiBrB,yBAAA;;;;;;;;;;;;;;;iBA2BD,sBAAA;;;;;;mBAMU;YACP,YAAY;IACpB;;;;cAoCS;eAjFO,eAAa"}

package/components/execution/engine.js

@@ -7,6 +7,7 @@ import { StepMode, StepOpCode, jsonErrorSchema } from "../../types.js";
 import { InngestExecution } from "./InngestExecution.js";
 import { isRecord } from "../../helpers/types.js";
 import { undefinedToNull } from "../../helpers/functions.js";
+import { isDeferredFunction } from "../../helpers/marker.js";
 import { isTemporalDuration } from "../../helpers/temporal.js";
 import { createDeferredPromise, createDeferredPromiseWithStack, createTimeoutPromise, goIntervalTiming, resolveAfterPending, resolveNextTick, retryWithBackoff, runAsPromise } from "../../helpers/promises.js";
 import { getAsyncCtx, getAsyncLocalStorage } from "./als.js";
@@ -20,6 +21,7 @@ import { StepError } from "../StepError.js";
 import { buildSseMetadataEvent, prependToStream } from "./streaming.js";
 import { Stream } from "../StreamTools.js";
 import { validateEvents } from "../triggers/utils.js";
+import { LazyOps, isLazyOp } from "./lazyOps.js";
 import { clientProcessorMap } from "./otel/access.js";
 import { z } from "zod/v3";
 import hashjs from "hash.js";
@@ -258,6 +260,8 @@ var InngestExecutionEngine = class extends InngestExecution {
 		throw new Error("Core loop finished without returning a value");
 	}
 	async checkpoint(steps) {
+		const lazyOps = this.state.lazyOps.drain();
+		if (lazyOps.length > 0) steps = [...steps, ...lazyOps];
 		if (this.options.stepMode === StepMode.Sync) if (!this.state.checkpointedRun) {
 			const res = await retryWithBackoff(() => this.options.client["inngestApi"].checkpointNewRun({
 				runId: this.fnArg.runId,
@@ -515,12 +519,13 @@ var InngestExecutionEngine = class extends InngestExecution {
 			return transformResult;
 		};
 		const maybeReturnNewSteps = async () => {
-			const newSteps = await this.filterNewSteps(Array.from(this.state.steps.values()));
-			if (newSteps) return {
+			const allSteps = [...await this.filterNewSteps(Array.from(this.state.steps.values())) ?? [], ...this.state.lazyOps.drain()];
+			if (allSteps.length === 0) return;
+			return {
 				type: "steps-found",
 				ctx: this.fnArg,
 				ops: this.ops,
-				steps: newSteps
+				steps: allSteps
 			};
 		};
 		const attemptCheckpointAndResume = async (stepResult, resume = true, force = false) => {
@@ -666,23 +671,36 @@ var InngestExecutionEngine = class extends InngestExecution {
 					sseResponse = extractSseResponse(data, body);
 					resultData = body;
 				} else sseResponse = defaultSseResponse(resultData);
-				const newStepsResult = await maybeReturnNewSteps();
-				if (newStepsResult) return newStepsResult;
+				const newSteps = await this.filterNewSteps(Array.from(this.state.steps.values()));
+				if (newSteps?.length) return this.attachLazyOps({
+					type: "steps-found",
+					ctx: this.fnArg,
+					ops: this.ops,
+					steps: newSteps
+				});
 				await this.streamCloseSucceeded(sseResponse);
 				if (!this.streamTools.activated) this.postCheckpointStream();
 				if (this.options.createResponse) data = await this.options.createResponse(jsonResponse(resultData));
-				return this.transformOutput({ data });
+				return this.attachLazyOps(this.transformOutput({ data }));
 			},
 			"function-rejected": async (checkpoint) => {
 				if (!this.retriability(checkpoint.error)) await this.streamCloseFailed(errorMessage(checkpoint.error));
 				else await this.streamEnd();
 				if (!this.streamTools.activated) this.postCheckpointStream();
-				return this.transformOutput({ error: checkpoint.error });
+				return this.attachLazyOps(this.transformOutput({ error: checkpoint.error }));
 			},
 			"steps-found": async ({ steps }) => {
 				const stepResult = await this.tryExecuteStep(steps);
-				if (stepResult) return stepRanHandler(stepResult);
-				return maybeReturnNewSteps();
+				if (!stepResult) return maybeReturnNewSteps();
+				if (this.state.lazyOps.length === 0) return stepRanHandler(stepResult);
+				const transformed = await stepRanHandler(stepResult);
+				if (transformed.type !== "step-ran") return transformed;
+				return this.attachLazyOps({
+					type: "steps-found",
+					ctx: transformed.ctx,
+					ops: transformed.ops,
+					steps: [transformed.step]
+				});
 			},
 			"step-not-found": ({ step }) => {
 				const { foundSteps, totalFoundSteps } = this.getStepNotFoundDetails();
@@ -705,13 +723,18 @@ var InngestExecutionEngine = class extends InngestExecution {
 		const asyncCheckpointingHandlers = {
 			"": commonCheckpointHandler,
 			"function-resolved": async (checkpoint, i) => {
+				const lazyOps = this.state.lazyOps.drain();
 				const output = await asyncHandlers["function-resolved"](checkpoint, i);
 				if (output?.type === "function-resolved") {
-					const steps = this.state.checkpointingStepBuffer.concat({
-						op: StepOpCode.RunComplete,
-						id: hashId(RUN_COMPLETE_STEP_ID),
-						data: output.data
-					});
+					const steps = [
+						...this.state.checkpointingStepBuffer,
+						...lazyOps,
+						{
+							op: StepOpCode.RunComplete,
+							id: hashId(RUN_COMPLETE_STEP_ID),
+							data: output.data
+						}
+					];
 					if (isNonEmpty(steps)) return {
 						type: "steps-found",
 						ctx: output.ctx,
@@ -719,9 +742,14 @@ var InngestExecutionEngine = class extends InngestExecution {
 						steps
 					};
 				}
+				if (output?.type === "steps-found" && lazyOps.length) return {
+					...output,
+					steps: [...output.steps, ...lazyOps]
+				};
+				return output;
 			},
 			"function-rejected": async (checkpoint) => {
-				if (this.state.checkpointingStepBuffer.length) {
+				if (this.state.checkpointingStepBuffer.length || this.state.lazyOps.length > 0) {
 					const fallback = await attemptCheckpointAndResume(void 0, false, true);
 					if (fallback) return fallback;
 				}
@@ -966,7 +994,11 @@ var InngestExecutionEngine = class extends InngestExecution {
 	* Validate event data against schemas defined in function triggers.
 	*/
 	async validateEventSchemas() {
-		if (this.options.isFailureHandler) return;
+		if (this.options.handlerKind === "failure") return;
+		if (this.options.handlerKind === "defer") {
+			await this.validateDeferEventSchema();
+			return;
+		}
 		const triggers = this.options.fn.opts.triggers;
 		if (!triggers || triggers.length === 0) return;
 		const fnArgEvents = this.fnArg.events;
@@ -977,6 +1009,17 @@ var InngestExecutionEngine = class extends InngestExecution {
 		})), triggers);
 	}
 	/**
+	* Validate the deferred event's data against the defer function's own
+	* schema (set via `createDefer`'s `opts.schema`).
+	*/
+	async validateDeferEventSchema() {
+		const fn = this.options.fn;
+		if (!isDeferredFunction(fn) || !fn.schema) return;
+		const eventData = this.fnArg.event?.data;
+		const result = await fn.schema["~standard"].validate(eventData);
+		if (result.issues) throw new NonRetriableError(`defer handler "${fn.id(this.options.client.id)}" schema validation failed: ${JSON.stringify(result.issues)}`);
+	}
+	/**
 	* Using middleware, transform output before returning.
 	*/
 	transformOutput(dataOrError) {
@@ -999,6 +1042,64 @@ var InngestExecutionEngine = class extends InngestExecution {
 			data: undefinedToNull(data)
 		};
 	}
+	/**
+	* Drain buffered lazy ops (e.g. `DeferAdd` from `defer()`) and merge them
+	* into `result` so they ship in the same outbound message. Lazy ops are
+	* fire-and-forget and have no natural shipping moment, so each terminal code
+	* path must ship them or they're silently dropped.
+	*/
+	attachLazyOps(result, extras = []) {
+		const lazyOps = this.state.lazyOps.drain();
+		if (lazyOps.length === 0 && extras.length === 0) return result;
+		switch (result.type) {
+			case "function-resolved": {
+				const steps = [
+					...extras,
+					...lazyOps,
+					{
+						op: StepOpCode.RunComplete,
+						id: hashId(RUN_COMPLETE_STEP_ID),
+						data: undefinedToNull(result.data)
+					}
+				];
+				return {
+					type: "steps-found",
+					ctx: result.ctx,
+					ops: result.ops,
+					steps
+				};
+			}
+			case "function-rejected": {
+				const isFinal = result.retriable === false;
+				const steps = [
+					...extras,
+					...lazyOps,
+					{
+						op: isFinal ? StepOpCode.StepFailed : StepOpCode.StepError,
+						id: hashId(RUN_COMPLETE_STEP_ID),
+						error: result.error
+					}
+				];
+				return {
+					type: "steps-found",
+					ctx: result.ctx,
+					ops: result.ops,
+					steps
+				};
+			}
+			case "steps-found": return {
+				...result,
+				steps: [
+					...result.steps,
+					...extras,
+					...lazyOps
+				]
+			};
+			default:
+				for (const op of lazyOps) this.state.lazyOps.push(op);
+				return result;
+		}
+	}
 	createExecutionState() {
 		const d = createDeferredPromiseWithStack();
 		let checkpointResolve = d.deferred.resolve;
@@ -1021,6 +1122,7 @@ var InngestExecutionEngine = class extends InngestExecution {
 		const stepsToFulfill = Object.keys(this.options.stepState).length;
 		return {
 			stepState: this.options.stepState,
+			priorDefers: this.options.priorDefers ?? {},
 			stepsToFulfill,
 			steps: /* @__PURE__ */ new Map(),
 			loop,
@@ -1035,6 +1137,7 @@ var InngestExecutionEngine = class extends InngestExecution {
 				return this.state.remainingStepsToBeSeen.size === 0;
 			},
 			checkpointingStepBuffer: [],
+			lazyOps: new LazyOps(),
 			metadata: /* @__PURE__ */ new Map()
 		};
 	}
@@ -1042,17 +1145,22 @@ var InngestExecutionEngine = class extends InngestExecution {
 		return Object.fromEntries(this.state.steps);
 	}
 	createFnArg() {
-		const step = this.createStepTools();
+		const { step, defer } = this.createStepTools();
 		const experimentStepRun = step[experimentStepRunSymbol];
 		let fnArg = {
 			...this.options.data,
 			step,
-			group: createGroupTools({ experimentStepRun })
+			group: createGroupTools({ experimentStepRun }),
+			defer
 		};
+		if (this.options.handlerKind === "defer") {
+			delete fnArg.event.data._inngest;
+			for (const event of fnArg.events) delete event.data._inngest;
+		}
 		/**
 		* Handle use of the `onFailure` option by deserializing the error.
 		*/
-		if (this.options.isFailureHandler) {
+		if (this.options.handlerKind === "failure") {
 			const eventData = z.object({ error: jsonErrorSchema }).parse(fnArg.event?.data);
 			fnArg = {
 				...fnArg,
@@ -1181,6 +1289,30 @@ var InngestExecutionEngine = class extends InngestExecution {
 		};
 		const stepHandler = async ({ args, matchOp, opts }) => {
 			const opId = matchOp(getStepOptions(args[0]), ...args.slice(1));
+			if (isLazyOp(opts, opId)) {
+				const hashedId$1 = _internals.hashId(opId.id);
+				if (this.state.lazyOps.hasId(hashedId$1)) {
+					this.options.client[internalLoggerSymbol].warn({
+						runId: this.fnArg.runId,
+						id: opId.userland?.id ?? opId.id
+					}, "defer skipped: duplicate ID within run");
+					return;
+				}
+				if (this.state.priorDefers[hashedId$1]) {
+					this.state.lazyOps.markSeen(hashedId$1);
+					return;
+				}
+				this.state.lazyOps.push({
+					id: hashedId$1,
+					op: opId.op,
+					name: opId.name,
+					displayName: opId.displayName ?? opId.id,
+					opts: opId.opts,
+					userland: opId.userland,
+					data: null
+				});
+				return;
+			}
 			if (this.state.executingStep)
  /**
 			* If a step is found after asynchronous actions during another step's
@@ -1302,7 +1434,75 @@ var InngestExecutionEngine = class extends InngestExecution {
 			} else pushStepToReport(step);
 			return promise;
 		};
-		return createStepTools(this.options.client, this, stepHandler);
+		return {
+			step: createStepTools(this.options.client, this, stepHandler),
+			defer: this.buildDefer(stepHandler)
+		};
+	}
+	/**
+	* Build the `defer(idOrOptions, { function, data })` method exposed on
+	* every handler context. Validates `data` against the target function's
+	* schema (if any) and emits a `DeferAdd` opcode that routes to the
+	* target's companion function slug.
+	*
+	* `defer()` is fire-and-forget: a misuse should not derail the user's
+	* handler. Validation failures (wrong function, async schema validator,
+	* schema mismatch) are logged and the call is silently skipped.
+	*/
+	buildDefer(stepHandler) {
+		return (idOrOptions, { function: deferFn, data }) => {
+			const log = this.options.client[internalLoggerSymbol];
+			const runId = this.fnArg.runId;
+			try {
+				if (!isDeferredFunction(deferFn)) {
+					log.error({ runId }, "defer skipped: function not created via createDefer");
+					return;
+				}
+				const { schema } = deferFn;
+				const deferFnSlug = deferFn.id(this.options.client.id);
+				let input = data;
+				if (schema) {
+					const result = schema["~standard"].validate(data);
+					if (result instanceof Promise) {
+						log.error({ runId }, "defer() requires a synchronous schema validator. The defer call was skipped.");
+						return;
+					}
+					if (result.issues) {
+						log.error({
+							runId,
+							issues: result.issues
+						}, "defer skipped: schema validation failed");
+						return;
+					}
+					input = result.value ?? data;
+				}
+				stepHandler({
+					args: [idOrOptions, input],
+					matchOp: (stepOptions, inputArg) => ({
+						id: stepOptions.id,
+						mode: StepMode.Sync,
+						op: StepOpCode.DeferAdd,
+						name: stepOptions.name ?? stepOptions.id,
+						displayName: stepOptions.name ?? stepOptions.id,
+						opts: {
+							fn_slug: deferFnSlug,
+							input: inputArg
+						},
+						userland: { id: stepOptions.id }
+					})
+				}).catch((err) => {
+					log.error({
+						runId,
+						err
+					}, "defer skipped: unexpected error");
+				});
+			} catch (err) {
+				log.error({
+					runId,
+					err
+				}, "defer skipped: unexpected error");
+			}
+		};
 	}
 	/**
 	* Applies middleware transformations to a step, resolves ID collisions,
@@ -1384,14 +1584,19 @@ var InngestExecutionEngine = class extends InngestExecution {
 		return userlandStep;
 	}
 	getUserFnToRun() {
-		if (!this.options.isFailureHandler) return this.options.fn["fn"];
-		if (!this.options.fn["onFailureFn"])
+		switch (this.options.handlerKind) {
+			case "defer": return this.options.fn["fn"];
+			case "failure":
+				if (!this.options.fn["onFailureFn"])
  /**
-		* Somehow, we've ended up detecting that this is a failure handler but
-		* doesn't have an `onFailure` function. This should never happen.
-		*/
-		throw new Error("Cannot find function `onFailure` handler");
-		return this.options.fn["onFailureFn"];
+				* Somehow, we've ended up detecting that this is a failure handler
+				* but doesn't have an `onFailure` function. This should never
+				* happen.
+				*/
+				throw new Error("Cannot find function `onFailure` handler");
+				return this.options.fn["onFailureFn"];
+			default: return this.options.fn["fn"];
+		}
 	}
 	initializeTimer(state) {
 		if (!this.options.requestedRunStep) return;