inngest 4.7.0 → 4.8.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # inngest
 
+## 4.8.0
+
+### Minor Changes
+
+- [#1595](https://github.com/inngest/inngest-js/pull/1595) [`aa315c7e`](https://github.com/inngest/inngest-js/commit/aa315c7ec9b99a69a7f85720e2805991b3e23841) Thanks [@amh4r](https://github.com/amh4r)! - Add opt-out for AI metadata extraction
+
+- [#1521](https://github.com/inngest/inngest-js/pull/1521) [`a69ec0e2`](https://github.com/inngest/inngest-js/commit/a69ec0e25acbf5c3a45b547ccf9d4d6819580a86) Thanks [@jakobevangelista](https://github.com/jakobevangelista)! - Add experimental createScorer function
+
+- [#1521](https://github.com/inngest/inngest-js/pull/1521) [`a69ec0e2`](https://github.com/inngest/inngest-js/commit/a69ec0e25acbf5c3a45b547ccf9d4d6819580a86) Thanks [@jakobevangelista](https://github.com/jakobevangelista)! - Add experimental scoring primitives for writing run- and step-scoped `inngest.score` metadata via `inngest.score()` and `scoreMiddleware()`-gated `step.score()`.
+
+### Patch Changes
+
+- [#1592](https://github.com/inngest/inngest-js/pull/1592) [`748c6cc4`](https://github.com/inngest/inngest-js/commit/748c6cc4fb167af9223c2b87d6c6543245d1428b) Thanks [@amh4r](https://github.com/amh4r)! - Deprecate Extended Traces provider creation. `behaviour: "createProvider"` and the `"auto"` fallback remain functional, but now direct users to preload `@inngest/otel/node` and extend that provider instead.
+
 ## 4.7.0
 
 ### Minor Changes

package/components/DeferredFunction.cjs

@@ -1,10 +1,39 @@
 const require_consts = require('../helpers/consts.cjs');
+const require_errors = require('../helpers/errors.cjs');
+const require_types = require('../helpers/types.cjs');
 const require_marker = require('../helpers/marker.cjs');
 const require_InngestFunction = require('./InngestFunction.cjs');
 
 //#region src/components/DeferredFunction.ts
 const idDenyRegex = /['\\\n\r]/;
 /**
+* Validates the reserved experiment-ref input key into an `ExperimentRef`, or
+* `undefined` when it's absent or malformed.
+*/
+function parseExperimentRef(value) {
+	if (require_types.isRecord(value) && typeof value.experimentName === "string" && typeof value.variant === "string") return {
+		experimentName: value.experimentName,
+		variant: value.variant
+	};
+}
+/**
+* Strips our `_inngest` metadata off an event's `data` in place and returns the
+* parent routing metadata extracted from it.
+*/
+function stripInngestMetadata(event) {
+	const { _inngest, [require_consts.deferExperimentKey]: experiment, ...input } = event.data ?? {};
+	if (!require_types.isRecord(_inngest)) throw new require_errors.UnreachableError("deferred event is missing _inngest metadata");
+	const { parent_fn_slug, parent_run_id } = _inngest;
+	if (typeof parent_fn_slug !== "string") throw new require_errors.UnreachableError("deferred event _inngest metadata is missing parent_fn_slug");
+	if (typeof parent_run_id !== "string") throw new require_errors.UnreachableError("deferred event _inngest metadata is missing parent_run_id");
+	event.data = input;
+	return {
+		fnSlug: parent_fn_slug,
+		runId: parent_run_id,
+		experiment: parseExperimentRef(experiment)
+	};
+}
+/**
 * EXPERIMENTAL: This API is not yet stable and may change in the future without
 * a major version bump.
 *
@@ -37,6 +66,29 @@ var DeferredFunction = class extends require_InngestFunction.InngestFunction {
 			expression: `event.data._inngest.fn_slug == '${fnId}'`
 		}];
 	}
+	/**
+	* Installs a `transformCtx` hook that runs before middleware and user code:
+	* - Strips our `_inngest` metadata off each event's `data`, ensuring it
+	*   matches what the user expects.
+	* - Collects the parent function's slug and run ID from that metadata into
+	*   `ctx.parents`, so the handler can correlate each event to its parent.
+	*/
+	createExecution(opts) {
+		return super.createExecution({
+			...opts,
+			partialOptions: {
+				...opts.partialOptions,
+				transformCtx: (ctx) => {
+					const parents = ctx.events.map(stripInngestMetadata);
+					stripInngestMetadata(ctx.event);
+					return {
+						...ctx,
+						parents
+					};
+				}
+			}
+		});
+	}
 };
 /**
 * EXPERIMENTAL: This API is not yet stable and may change in the future without

package/components/DeferredFunction.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"DeferredFunction.cjs","names":["InngestFunction","markerKey","internalEvents"],"sources":["../../src/components/DeferredFunction.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport { internalEvents } from \"../helpers/consts.ts\";\nimport { type Marker, markerKey } from \"../helpers/marker.ts\";\nimport type {\n  ApplyAllMiddlewareCtxExtensions,\n  ApplyAllMiddlewareStepExtensions,\n  BaseContext,\n  FunctionConfig,\n  Handler,\n} from \"../types.ts\";\nimport type {\n  builtInMiddleware,\n  ClientOptionsFromInngest,\n  Inngest,\n} from \"./Inngest.ts\";\nimport { InngestFunction } from \"./InngestFunction.ts\";\nimport type { createStepTools } from \"./InngestStepTools.ts\";\nimport type { Middleware } from \"./middleware/index.ts\";\n\nconst idDenyRegex = /['\\\\\\n\\r]/;\n\n/**\n * EXPERIMENTAL: This API is not yet stable and may change in the future without\n * a major version bump.\n *\n * A defer (companion) function created via `createDefer(...)`. Real\n * `InngestFunction` at runtime, but with the trigger pinned to\n * `inngest/deferred.schedule` (see `getConfigTriggers`), `triggers` and\n * `onFailure` disallowed, and the schema carried as a typed instance\n * property so callers of `defer(id, { function, data })` can extract it.\n *\n * Identify a defer function at runtime via `isDeferredFunction(value)` from\n * `helpers/marker.ts`. Prefer that over `instanceof`, which fails across\n * duplicate SDK copies in the same process.\n *\n * @public\n */\nexport class DeferredFunction<\n  TSchema extends\n    | StandardSchemaV1<Record<string, unknown>>\n    | undefined = undefined,\n> extends InngestFunction<\n  InngestFunction.Options<[], never>,\n  Handler.Any,\n  never,\n  Inngest.Any,\n  []\n> {\n  readonly schema: TSchema;\n  readonly [markerKey]: Marker = { kind: \"DeferredFunction\" };\n\n  constructor(\n    client: Inngest.Any,\n    opts: DeferredFunction.Options,\n    handler: Handler.Any,\n    schema: TSchema,\n  ) {\n    // The id is interpolated into a CEL trigger expression\n    // (`event.data._inngest.fn_slug == '${fnId}'`). Reject characters that\n    // would break the single-quoted string literal.\n    if (idDenyRegex.test(opts.id)) {\n      throw new Error(\n        `invalid id \"${opts.id}\"; must match ${idDenyRegex.source}`,\n      );\n    }\n    super(\n      client,\n      { ...opts, triggers: [] } as InngestFunction.Options<[], never>,\n      handler,\n    );\n    this.schema = schema;\n  }\n\n  protected override getConfigTriggers(\n    fnId: string,\n  ): FunctionConfig[\"triggers\"] {\n    return [\n      {\n        event: internalEvents.DeferredSchedule,\n        expression: `event.data._inngest.fn_slug == '${fnId}'`,\n      },\n    ];\n  }\n}\n\n/**\n * @public\n */\nexport namespace DeferredFunction {\n  /**\n   * Matches any `DeferredFunction` regardless of its schema. Use as the\n   * constraint for the `function` argument of `defer()`.\n   */\n  // biome-ignore lint/suspicious/noExplicitAny: widest schema constraint for inference\n  export type Any = DeferredFunction<StandardSchemaV1<any> | undefined>;\n\n  /**\n   * The user-facing options accepted by `createDefer(client, opts, handler)`.\n   * Mirrors `InngestFunction.Options` minus `triggers` (implicit), `onFailure`\n   * (not yet supported), and `batchEvents` (each `defer(...)` is its own run).\n   */\n  export type Options = Omit<\n    InngestFunction.Options<[], never>,\n    \"triggers\" | \"onFailure\" | \"batchEvents\"\n  >;\n}\n\n/**\n * The `event` shape a defer handler receives. With a schema, `data`\n * narrows to its inferred type; without one, it falls back to\n * `Record<string, any>`.\n */\ntype DeferEvent<TSchema> = {\n  name: internalEvents.DeferredSchedule;\n  data: TSchema extends StandardSchemaV1<\n    infer D extends Record<string, unknown>\n  >\n    ? D\n    : // biome-ignore lint/suspicious/noExplicitAny: no schema = any\n      Record<string, any>;\n};\n\n/**\n * Base ctx shape for a defer handler: the standard function context\n * (`runId`, `attempt`, `group`, `step` with middleware step extensions)\n * with `event`/`events` pinned to `inngest/deferred.schedule` and the\n * schema-typed payload.\n */\ntype BaseDeferCtx<\n  TClient extends Inngest.Any,\n  TFnMiddleware extends Middleware.Class[] | undefined,\n  TSchema extends StandardSchemaV1<Record<string, unknown>> | undefined,\n> = Omit<BaseContext<TClient>, \"event\" | \"events\" | \"step\"> & {\n  event: DeferEvent<TSchema>;\n  events: [DeferEvent<TSchema>];\n  step: ReturnType<typeof createStepTools<TClient, TFnMiddleware>> &\n    ApplyAllMiddlewareStepExtensions<\n      ClientOptionsFromInngest<TClient>[\"middleware\"]\n    > &\n    ApplyAllMiddlewareStepExtensions<TFnMiddleware>;\n};\n\n/**\n * Input type for `createDefer`. Same shape as `DeferredFunction.Options`\n * plus `schema` (the StandardSchema describing `event.data` that flows\n * to caller `defer(id, { function, data })` call sites) and `middleware`.\n */\nexport type CreateDeferInput<\n  TFnMiddleware extends Middleware.Class[] | undefined,\n  TSchema extends StandardSchemaV1<Record<string, unknown>> | undefined,\n> = DeferredFunction.Options & {\n  schema?: TSchema;\n  middleware?: TFnMiddleware;\n};\n\n/**\n * EXPERIMENTAL: This API is not yet stable and may change in the future without\n * a major version bump.\n *\n * Create a typed defer function. One `createDefer` call = one Inngest\n * function. Returns a `DeferredFunction<TSchema>` so callers of `defer(id,\n * { function, data })` get the data type inferred from the schema.\n *\n * Mirrors `inngest.createFunction(opts, handler)`, with three differences:\n * the client is the first positional arg, `triggers` is not accepted (the\n * SDK emits an implicit `inngest/deferred.schedule` trigger), and `schema`\n * describes the payload that callers will send via `defer(id, { function,\n * data })`.\n *\n * Pass the result to `serve()` alongside regular functions so the SDK\n * registers it.\n */\nexport function createDefer<\n  TClient extends Inngest.Any,\n  TSchema extends\n    | StandardSchemaV1<Record<string, unknown>>\n    | undefined = undefined,\n  const TFnMiddleware extends Middleware.Class[] | undefined = undefined,\n  THandler extends Handler.Any = (\n    ctx: BaseDeferCtx<TClient, TFnMiddleware, TSchema> &\n      ApplyAllMiddlewareCtxExtensions<\n        [...ReturnType<typeof builtInMiddleware>]\n      > &\n      ApplyAllMiddlewareCtxExtensions<\n        ClientOptionsFromInngest<TClient>[\"middleware\"]\n      > &\n      ApplyAllMiddlewareCtxExtensions<TFnMiddleware>,\n  ) => unknown,\n>(\n  client: TClient,\n  options: CreateDeferInput<TFnMiddleware, TSchema>,\n  handler: THandler,\n): DeferredFunction<TSchema> {\n  const { schema, ...rest } = options;\n  return new DeferredFunction<TSchema>(\n    client,\n    rest,\n    handler as Handler.Any,\n    schema as TSchema,\n  );\n}\n"],"mappings":";;;;;AAmBA,MAAM,cAAc;;;;;;;;;;;;;;;;;AAkBpB,IAAa,mBAAb,cAIUA,wCAMR;CACA,AAAS;CACT,CAAUC,4BAAqB,EAAE,MAAM,oBAAoB;CAE3D,YACE,QACA,MACA,SACA,QACA;AAIA,MAAI,YAAY,KAAK,KAAK,GAAG,CAC3B,OAAM,IAAI,MACR,eAAe,KAAK,GAAG,gBAAgB,YAAY,SACpD;AAEH,QACE,QACA;GAAE,GAAG;GAAM,UAAU,EAAE;GAAE,EACzB,QACD;AACD,OAAK,SAAS;;CAGhB,AAAmB,kBACjB,MAC4B;AAC5B,SAAO,CACL;GACE,OAAOC,8BAAe;GACtB,YAAY,mCAAmC,KAAK;GACrD,CACF;;;;;;;;;;;;;;;;;;;;AA2FL,SAAgB,YAiBd,QACA,SACA,SAC2B;CAC3B,MAAM,EAAE,QAAQ,GAAG,SAAS;AAC5B,QAAO,IAAI,iBACT,QACA,MACA,SACA,OACD"}
+{"version":3,"file":"DeferredFunction.cjs","names":["isRecord","deferExperimentKey","UnreachableError","InngestFunction","markerKey","internalEvents"],"sources":["../../src/components/DeferredFunction.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport { deferExperimentKey, internalEvents } from \"../helpers/consts.ts\";\nimport { UnreachableError } from \"../helpers/errors.ts\";\nimport { type Marker, markerKey } from \"../helpers/marker.ts\";\nimport { isRecord } from \"../helpers/types.ts\";\nimport type {\n  ApplyAllMiddlewareCtxExtensions,\n  ApplyAllMiddlewareStepExtensions,\n  BaseContext,\n  ExperimentRef,\n  FunctionConfig,\n  Handler,\n} from \"../types.ts\";\nimport type { IInngestExecution } from \"./execution/InngestExecution.ts\";\nimport type {\n  builtInMiddleware,\n  ClientOptionsFromInngest,\n  Inngest,\n} from \"./Inngest.ts\";\nimport {\n  type CreateExecutionOptions,\n  InngestFunction,\n} from \"./InngestFunction.ts\";\nimport type { createStepTools } from \"./InngestStepTools.ts\";\nimport type { Middleware } from \"./middleware/index.ts\";\n\nconst idDenyRegex = /['\\\\\\n\\r]/;\n\n/**\n * Validates the reserved experiment-ref input key into an `ExperimentRef`, or\n * `undefined` when it's absent or malformed.\n */\nfunction parseExperimentRef(value: unknown): ExperimentRef | undefined {\n  if (\n    isRecord(value) &&\n    typeof value.experimentName === \"string\" &&\n    typeof value.variant === \"string\"\n  ) {\n    return { experimentName: value.experimentName, variant: value.variant };\n  }\n  return undefined;\n}\n\n/**\n * Strips our `_inngest` metadata off an event's `data` in place and returns the\n * parent routing metadata extracted from it.\n */\nfunction stripInngestMetadata(event: {\n  data?: Record<string, unknown>;\n}): DeferredFunction.Parent {\n  const data = event.data ?? {};\n  const { _inngest, [deferExperimentKey]: experiment, ...input } = data;\n\n  if (!isRecord(_inngest)) {\n    throw new UnreachableError(\"deferred event is missing _inngest metadata\");\n  }\n  const { parent_fn_slug, parent_run_id } = _inngest;\n  if (typeof parent_fn_slug !== \"string\") {\n    throw new UnreachableError(\n      \"deferred event _inngest metadata is missing parent_fn_slug\",\n    );\n  }\n  if (typeof parent_run_id !== \"string\") {\n    throw new UnreachableError(\n      \"deferred event _inngest metadata is missing parent_run_id\",\n    );\n  }\n\n  // Mutate in place\n  event.data = input;\n\n  return {\n    fnSlug: parent_fn_slug,\n    runId: parent_run_id,\n    experiment: parseExperimentRef(experiment),\n  };\n}\n\n/**\n * EXPERIMENTAL: This API is not yet stable and may change in the future without\n * a major version bump.\n *\n * A defer (companion) function created via `createDefer(...)`. Real\n * `InngestFunction` at runtime, but with the trigger pinned to\n * `inngest/deferred.schedule` (see `getConfigTriggers`), `triggers` and\n * `onFailure` disallowed, and the schema carried as a typed instance\n * property so callers of `defer(id, { function, data })` can extract it.\n *\n * Identify a defer function at runtime via `isDeferredFunction(value)` from\n * `helpers/marker.ts`. Prefer that over `instanceof`, which fails across\n * duplicate SDK copies in the same process.\n *\n * @public\n */\nexport class DeferredFunction<\n  TSchema extends\n    | StandardSchemaV1<Record<string, unknown>>\n    | undefined = undefined,\n> extends InngestFunction<\n  InngestFunction.Options<[], never>,\n  Handler.Any,\n  never,\n  Inngest.Any,\n  []\n> {\n  readonly schema: TSchema;\n  readonly [markerKey]: Marker = { kind: \"DeferredFunction\" };\n\n  constructor(\n    client: Inngest.Any,\n    opts: DeferredFunction.Options,\n    handler: Handler.Any,\n    schema: TSchema,\n  ) {\n    // The id is interpolated into a CEL trigger expression\n    // (`event.data._inngest.fn_slug == '${fnId}'`). Reject characters that\n    // would break the single-quoted string literal.\n    if (idDenyRegex.test(opts.id)) {\n      throw new Error(\n        `invalid id \"${opts.id}\"; must match ${idDenyRegex.source}`,\n      );\n    }\n    super(\n      client,\n      { ...opts, triggers: [] } as InngestFunction.Options<[], never>,\n      handler,\n    );\n    this.schema = schema;\n  }\n\n  protected override getConfigTriggers(\n    fnId: string,\n  ): FunctionConfig[\"triggers\"] {\n    return [\n      {\n        event: internalEvents.DeferredSchedule,\n        expression: `event.data._inngest.fn_slug == '${fnId}'`,\n      },\n    ];\n  }\n\n  /**\n   * Installs a `transformCtx` hook that runs before middleware and user code:\n   * - Strips our `_inngest` metadata off each event's `data`, ensuring it\n   *   matches what the user expects.\n   * - Collects the parent function's slug and run ID from that metadata into\n   *   `ctx.parents`, so the handler can correlate each event to its parent.\n   */\n  protected override createExecution(\n    opts: CreateExecutionOptions,\n  ): IInngestExecution {\n    return super.createExecution({\n      ...opts,\n      partialOptions: {\n        ...opts.partialOptions,\n        transformCtx: (ctx) => {\n          // Get the parent info from each event. Also removes our internal\n          // metadata from each event (mutates in place).\n          const parents = ctx.events.map(stripInngestMetadata);\n\n          // Removes our internal metadata from the event (mutates in place).\n          stripInngestMetadata(ctx.event);\n\n          return {\n            ...ctx,\n            parents,\n          };\n        },\n      },\n    });\n  }\n}\n\n/**\n * @public\n */\nexport namespace DeferredFunction {\n  /**\n   * Matches any `DeferredFunction` regardless of its schema. Use as the\n   * constraint for the `function` argument of `defer()`.\n   */\n  // biome-ignore lint/suspicious/noExplicitAny: widest schema constraint for inference\n  export type Any = DeferredFunction<StandardSchemaV1<any> | undefined>;\n\n  /**\n   * The user-facing options accepted by `createDefer(client, opts, handler)`.\n   * Mirrors `InngestFunction.Options` minus `triggers` (implicit), `onFailure`\n   * (not yet supported), and `batchEvents` (each `defer(...)` is its own run).\n   */\n  export type Options = Omit<\n    InngestFunction.Options<[], never>,\n    \"triggers\" | \"onFailure\" | \"batchEvents\"\n  >;\n\n  /**\n   * Metadata describing the parent run that triggered the deferred run. Derived\n   * from `event.data._inngest` and surfaced on the handler ctx as `parents[i]`,\n   * aligned with `events[i]`.\n   */\n  export type Parent = {\n    fnSlug: string;\n    runId: string;\n    experiment?: ExperimentRef;\n  };\n}\n\n/**\n * The `event` shape a defer handler receives. `data` carries the user payload\n * directly, narrowed by the schema if one is set (otherwise\n * `Record<string, any>`). Parent metadata is exposed separately on\n * `ctx.parents` so events and parents can be matched by index.\n */\ntype DeferEvent<TSchema> = {\n  name: internalEvents.DeferredSchedule;\n  data: TSchema extends StandardSchemaV1<\n    infer D extends Record<string, unknown>\n  >\n    ? D\n    : // biome-ignore lint/suspicious/noExplicitAny: no schema = any\n      Record<string, any>;\n};\n\n/**\n * Base ctx shape for a defer handler: the standard function context\n * (`runId`, `attempt`, `group`, `step` with middleware step extensions)\n * with `event`/`events` pinned to `inngest/deferred.schedule` and the\n * schema-typed payload, plus `parents` aligned with `events` by index.\n */\ntype BaseDeferCtx<\n  TClient extends Inngest.Any,\n  TFnMiddleware extends Middleware.Class[] | undefined,\n  TSchema extends StandardSchemaV1<Record<string, unknown>> | undefined,\n> = Omit<BaseContext<TClient>, \"event\" | \"events\" | \"step\"> & {\n  event: DeferEvent<TSchema>;\n  events: [DeferEvent<TSchema>];\n  parents: [DeferredFunction.Parent];\n  step: ReturnType<typeof createStepTools<TClient, TFnMiddleware>> &\n    ApplyAllMiddlewareStepExtensions<\n      ClientOptionsFromInngest<TClient>[\"middleware\"]\n    > &\n    ApplyAllMiddlewareStepExtensions<TFnMiddleware>;\n};\n\n/**\n * Input type for `createDefer`. Same shape as `DeferredFunction.Options`\n * plus `schema` (the StandardSchema describing `event.data` that flows\n * to caller `defer(id, { function, data })` call sites) and `middleware`.\n */\nexport type CreateDeferInput<\n  TFnMiddleware extends Middleware.Class[] | undefined,\n  TSchema extends StandardSchemaV1<Record<string, unknown>> | undefined,\n> = DeferredFunction.Options & {\n  schema?: TSchema;\n  middleware?: TFnMiddleware;\n};\n\n/**\n * Full handler context for a defer function: `BaseDeferCtx` plus every\n * middleware ctx extension that applies (built-in, client, function-level).\n */\nexport type DeferContext<\n  TClient extends Inngest.Any,\n  TFnMiddleware extends Middleware.Class[] | undefined,\n  TSchema extends StandardSchemaV1<Record<string, unknown>> | undefined,\n> = BaseDeferCtx<TClient, TFnMiddleware, TSchema> &\n  ApplyAllMiddlewareCtxExtensions<[...ReturnType<typeof builtInMiddleware>]> &\n  ApplyAllMiddlewareCtxExtensions<\n    ClientOptionsFromInngest<TClient>[\"middleware\"]\n  > &\n  ApplyAllMiddlewareCtxExtensions<TFnMiddleware>;\n\n/**\n * EXPERIMENTAL: This API is not yet stable and may change in the future without\n * a major version bump.\n *\n * Create a typed defer function. One `createDefer` call = one Inngest\n * function. Returns a `DeferredFunction<TSchema>` so callers of `defer(id,\n * { function, data })` get the data type inferred from the schema.\n *\n * Mirrors `inngest.createFunction(opts, handler)`, with three differences:\n * the client is the first positional arg, `triggers` is not accepted (the\n * SDK emits an implicit `inngest/deferred.schedule` trigger), and `schema`\n * describes the payload that callers will send via `defer(id, { function,\n * data })`.\n *\n * Pass the result to `serve()` alongside regular functions so the SDK\n * registers it.\n */\nexport function createDefer<\n  TClient extends Inngest.Any,\n  TSchema extends\n    | StandardSchemaV1<Record<string, unknown>>\n    | undefined = undefined,\n  const TFnMiddleware extends Middleware.Class[] | undefined = undefined,\n  THandler extends Handler.Any = (\n    ctx: DeferContext<TClient, TFnMiddleware, TSchema>,\n  ) => unknown,\n>(\n  client: TClient,\n  options: CreateDeferInput<TFnMiddleware, TSchema>,\n  handler: THandler,\n): DeferredFunction<TSchema> {\n  const { schema, ...rest } = options;\n  return new DeferredFunction<TSchema>(\n    client,\n    rest,\n    handler as Handler.Any,\n    schema as TSchema,\n  );\n}\n"],"mappings":";;;;;;;AA0BA,MAAM,cAAc;;;;;AAMpB,SAAS,mBAAmB,OAA2C;AACrE,KACEA,uBAAS,MAAM,IACf,OAAO,MAAM,mBAAmB,YAChC,OAAO,MAAM,YAAY,SAEzB,QAAO;EAAE,gBAAgB,MAAM;EAAgB,SAAS,MAAM;EAAS;;;;;;AAS3E,SAAS,qBAAqB,OAEF;CAE1B,MAAM,EAAE,WAAWC,oCAAqB,YAAY,GAAG,UAD1C,MAAM,QAAQ,EAAE;AAG7B,KAAI,CAACD,uBAAS,SAAS,CACrB,OAAM,IAAIE,gCAAiB,8CAA8C;CAE3E,MAAM,EAAE,gBAAgB,kBAAkB;AAC1C,KAAI,OAAO,mBAAmB,SAC5B,OAAM,IAAIA,gCACR,6DACD;AAEH,KAAI,OAAO,kBAAkB,SAC3B,OAAM,IAAIA,gCACR,4DACD;AAIH,OAAM,OAAO;AAEb,QAAO;EACL,QAAQ;EACR,OAAO;EACP,YAAY,mBAAmB,WAAW;EAC3C;;;;;;;;;;;;;;;;;;AAmBH,IAAa,mBAAb,cAIUC,wCAMR;CACA,AAAS;CACT,CAAUC,4BAAqB,EAAE,MAAM,oBAAoB;CAE3D,YACE,QACA,MACA,SACA,QACA;AAIA,MAAI,YAAY,KAAK,KAAK,GAAG,CAC3B,OAAM,IAAI,MACR,eAAe,KAAK,GAAG,gBAAgB,YAAY,SACpD;AAEH,QACE,QACA;GAAE,GAAG;GAAM,UAAU,EAAE;GAAE,EACzB,QACD;AACD,OAAK,SAAS;;CAGhB,AAAmB,kBACjB,MAC4B;AAC5B,SAAO,CACL;GACE,OAAOC,8BAAe;GACtB,YAAY,mCAAmC,KAAK;GACrD,CACF;;;;;;;;;CAUH,AAAmB,gBACjB,MACmB;AACnB,SAAO,MAAM,gBAAgB;GAC3B,GAAG;GACH,gBAAgB;IACd,GAAG,KAAK;IACR,eAAe,QAAQ;KAGrB,MAAM,UAAU,IAAI,OAAO,IAAI,qBAAqB;AAGpD,0BAAqB,IAAI,MAAM;AAE/B,YAAO;MACL,GAAG;MACH;MACD;;IAEJ;GACF,CAAC;;;;;;;;;;;;;;;;;;;;AAuHN,SAAgB,YAUd,QACA,SACA,SAC2B;CAC3B,MAAM,EAAE,QAAQ,GAAG,SAAS;AAC5B,QAAO,IAAI,iBACT,QACA,MACA,SACA,OACD"}

package/components/DeferredFunction.d.cts

@@ -1,9 +1,10 @@
 import { internalEvents } from "../helpers/consts.cjs";
 import { Marker, markerKey } from "../helpers/marker.cjs";
-import { Middleware } from "./middleware/middleware.cjs";
 import { createStepTools } from "./InngestStepTools.cjs";
-import { InngestFunction } from "./InngestFunction.cjs";
-import { ApplyAllMiddlewareCtxExtensions, ApplyAllMiddlewareStepExtensions, BaseContext, FunctionConfig, Handler } from "../types.cjs";
+import { Middleware } from "./middleware/middleware.cjs";
+import { CreateExecutionOptions, InngestFunction } from "./InngestFunction.cjs";
+import { IInngestExecution } from "./execution/InngestExecution.cjs";
+import { ApplyAllMiddlewareCtxExtensions, ApplyAllMiddlewareStepExtensions, BaseContext, ExperimentRef, FunctionConfig, Handler } from "../types.cjs";
 import { ClientOptionsFromInngest, Inngest, builtInMiddleware } from "./Inngest.cjs";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 
@@ -30,6 +31,14 @@ declare class DeferredFunction<TSchema extends StandardSchemaV1<Record<string, u
   readonly [markerKey]: Marker;
   constructor(client: Inngest.Any, opts: DeferredFunction.Options, handler: Handler.Any, schema: TSchema);
   protected getConfigTriggers(fnId: string): FunctionConfig["triggers"];
+  /**
+   * Installs a `transformCtx` hook that runs before middleware and user code:
+   * - Strips our `_inngest` metadata off each event's `data`, ensuring it
+   *   matches what the user expects.
+   * - Collects the parent function's slug and run ID from that metadata into
+   *   `ctx.parents`, so the handler can correlate each event to its parent.
+   */
+  protected createExecution(opts: CreateExecutionOptions): IInngestExecution;
 }
 /**
  * @public
@@ -46,11 +55,22 @@ declare namespace DeferredFunction {
    * (not yet supported), and `batchEvents` (each `defer(...)` is its own run).
    */
   type Options = Omit<InngestFunction.Options<[], never>, "triggers" | "onFailure" | "batchEvents">;
+  /**
+   * Metadata describing the parent run that triggered the deferred run. Derived
+   * from `event.data._inngest` and surfaced on the handler ctx as `parents[i]`,
+   * aligned with `events[i]`.
+   */
+  type Parent = {
+    fnSlug: string;
+    runId: string;
+    experiment?: ExperimentRef;
+  };
 }
 /**
- * The `event` shape a defer handler receives. With a schema, `data`
- * narrows to its inferred type; without one, it falls back to
- * `Record<string, any>`.
+ * The `event` shape a defer handler receives. `data` carries the user payload
+ * directly, narrowed by the schema if one is set (otherwise
+ * `Record<string, any>`). Parent metadata is exposed separately on
+ * `ctx.parents` so events and parents can be matched by index.
  */
 type DeferEvent<TSchema> = {
   name: internalEvents.DeferredSchedule;
@@ -60,11 +80,12 @@ type DeferEvent<TSchema> = {
  * Base ctx shape for a defer handler: the standard function context
  * (`runId`, `attempt`, `group`, `step` with middleware step extensions)
  * with `event`/`events` pinned to `inngest/deferred.schedule` and the
- * schema-typed payload.
+ * schema-typed payload, plus `parents` aligned with `events` by index.
  */
 type BaseDeferCtx<TClient extends Inngest.Any, TFnMiddleware extends Middleware.Class[] | undefined, TSchema extends StandardSchemaV1<Record<string, unknown>> | undefined> = Omit<BaseContext<TClient>, "event" | "events" | "step"> & {
   event: DeferEvent<TSchema>;
   events: [DeferEvent<TSchema>];
+  parents: [DeferredFunction.Parent];
   step: ReturnType<typeof createStepTools<TClient, TFnMiddleware>> & ApplyAllMiddlewareStepExtensions<ClientOptionsFromInngest<TClient>["middleware"]> & ApplyAllMiddlewareStepExtensions<TFnMiddleware>;
 };
 /**
@@ -76,6 +97,11 @@ type CreateDeferInput<TFnMiddleware extends Middleware.Class[] | undefined, TSch
   schema?: TSchema;
   middleware?: TFnMiddleware;
 };
+/**
+ * Full handler context for a defer function: `BaseDeferCtx` plus every
+ * middleware ctx extension that applies (built-in, client, function-level).
+ */
+type DeferContext<TClient extends Inngest.Any, TFnMiddleware extends Middleware.Class[] | undefined, TSchema extends StandardSchemaV1<Record<string, unknown>> | undefined> = BaseDeferCtx<TClient, TFnMiddleware, TSchema> & ApplyAllMiddlewareCtxExtensions<[...ReturnType<typeof builtInMiddleware>]> & ApplyAllMiddlewareCtxExtensions<ClientOptionsFromInngest<TClient>["middleware"]> & ApplyAllMiddlewareCtxExtensions<TFnMiddleware>;
 /**
  * EXPERIMENTAL: This API is not yet stable and may change in the future without
  * a major version bump.
@@ -93,7 +119,7 @@ type CreateDeferInput<TFnMiddleware extends Middleware.Class[] | undefined, TSch
  * Pass the result to `serve()` alongside regular functions so the SDK
  * registers it.
  */
-declare function createDefer<TClient extends Inngest.Any, TSchema extends StandardSchemaV1<Record<string, unknown>> | undefined = undefined, const TFnMiddleware extends Middleware.Class[] | undefined = undefined, THandler extends Handler.Any = (ctx: BaseDeferCtx<TClient, TFnMiddleware, TSchema> & ApplyAllMiddlewareCtxExtensions<[...ReturnType<typeof builtInMiddleware>]> & ApplyAllMiddlewareCtxExtensions<ClientOptionsFromInngest<TClient>["middleware"]> & ApplyAllMiddlewareCtxExtensions<TFnMiddleware>) => unknown>(client: TClient, options: CreateDeferInput<TFnMiddleware, TSchema>, handler: THandler): DeferredFunction<TSchema>;
+declare function createDefer<TClient extends Inngest.Any, TSchema extends StandardSchemaV1<Record<string, unknown>> | undefined = undefined, const TFnMiddleware extends Middleware.Class[] | undefined = undefined, THandler extends Handler.Any = (ctx: DeferContext<TClient, TFnMiddleware, TSchema>) => unknown>(client: TClient, options: CreateDeferInput<TFnMiddleware, TSchema>, handler: THandler): DeferredFunction<TSchema>;
 //#endregion
-export { DeferredFunction, createDefer };
+export { CreateDeferInput, DeferContext, DeferredFunction, createDefer };
 //# sourceMappingURL=DeferredFunction.d.cts.map

package/components/DeferredFunction.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"DeferredFunction.d.cts","names":[],"sources":["../../src/components/DeferredFunction.ts"],"sourcesContent":[],"mappings":"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"}
+{"version":3,"file":"DeferredFunction.d.cts","names":[],"sources":["../../src/components/DeferredFunction.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;AA8FA;;;;;;;;;;;;;;AAsCK,cAtCQ,gBAsCR,CAAA,gBApCC,gBAoCD,CApCkB,MAoClB,CAAA,MAAA,EAAA,OAAA,CAAA,CAAA,GAAA,SAAA,GAAA,SAAA,CAAA,SAlCK,eAkCL,CAjCH,eAAA,CAAgB,OAiCb,CAAA,EAAA,EAAA,KAAA,CAAA,EAhCH,OAAA,CAAQ,GAgCL,EAAA,KAAA,EA9BH,OAAA,CAAQ,GA8BL,EAAA;WAkBA,MAAA,EA7Cc,OA6Cd;YA5CO,SAAA,CARF,EAQc,MARd;EAAe,WAAA,CAAA,MAAA,EAWb,OAAA,CAAQ,GAXK,EAAA,IAAA,EAYf,gBAAA,CAAiB,OAZF,EAAA,OAAA,EAaZ,OAAA,CAAQ,GAbI,EAAA,MAAA,EAcb,OAda;EA8ER,UAAA,iBAAgB,CAAA,IAAA,EAAA,MAAA,CAAA,EA5C5B,cA4C4B,CAAA,UAAA,CAAA;EAAA;;;;;;;EAoC5B,UAAA,eAAU,CAAA,IAAA,EA/DL,sBA+DK,CAAA,EA9DV,iBA8DU;;;;;AAES,kBAtCP,gBAAA,CAsCO;;;;AAKZ;EASK,KAAA,GAAA,GA9CG,gBA8CH,CA9CoB,gBA8CpB,CAAA,GAAA,CAAA,GAAA,SAAA,CAAA;;;;;;OAIR,OAAA,GA3Ce,IA2Cf,CA1CL,eAAA,CAAgB,OA0CX,CAAA,EAAA,EAAA,KAAA,CAAA,EAAA,UAAA,GAAA,WAAA,GAAA,aAAA,CAAA;;;;;;OAGG,MAAA,GAAA;IAC8B,MAAA,EAAA,MAAA;IAAS,KAAA,EAAA,MAAA;IAAzB,UAAA,CAAA,EAlCT,aAkCS;;;;;;;;AAY1B;KApCK,UAoCuB,CAAA,OAAA,CAAA,GAAA;MACJ,EApChB,cAAA,CAAe,gBAoCY;MACA,EApC3B,OAoC2B,SApCX,gBAoCW,CAAA,KAAA,WAnCf,MAmCe,CAAA,MAAA,EAAA,OAAA,CAAA,CAAA,GAjC7B,CAiC6B,GA/B7B,MA+B6B,CAAA,MAAA,EAAA,GAAA,CAAA;;;;;;AAUnC;;KAhCK,YAiCqB,CAAA,gBAhCR,OAAA,CAAQ,GAgCA,EAAA,sBA/BF,UAAA,CAAW,KA+BT,EAAA,GAAA,SAAA,EAAA,gBA9BR,gBA8BQ,CA9BS,MA8BT,CAAA,MAAA,EAAA,OAAA,CAAA,CAAA,GAAA,SAAA,CAAA,GA7BtB,IA6BsB,CA7BjB,WA6BiB,CA7BL,OA6BK,CAAA,EAAA,OAAA,GAAA,QAAA,GAAA,MAAA,CAAA,GAAA;OACF,EA7Bf,UA6B0B,CA7Bf,OA6Be,CAAA;QACA,EAAA,CA7BxB,UA6BwB,CA7Bb,OA6Ba,CAAA,CAAA;SAAjB,EAAA,CA5BN,gBAAA,CAAiB,MA4BX,CAAA;MACD,EA5BT,UA4BS,CAAA,OA5BS,eA4BT,CA5ByB,OA4BzB,EA5BkC,aA4BlC,CAAA,CAAA,GA3Bb,gCA2Ba,CA1BX,wBA0BW,CA1Bc,OA0Bd,CAAA,CAAA,YAAA,CAAA,CAAA,GAxBb,gCAwBa,CAxBoB,aAwBpB,CAAA;;;;;;;AAGY,KAnBjB,gBAmBiB,CAAA,sBAlBL,UAAA,CAAW,KAkBN,EAAA,GAAA,SAAA,EAAA,gBAjBX,gBAiBW,CAjBM,MAiBN,CAAA,MAAA,EAAA,OAAA,CAAA,CAAA,GAAA,SAAA,CAAA,GAhBzB,gBAAA,CAAiB,OAgBQ,GAAA;QAAzB,CAAA,EAfO,OAeP;YADF,CAAA,EAba,aAab;;;;AAsBF;;AACkB,KA7BN,YA6Bc,CAAA,gBA5BR,OAAA,CAAQ,GA4BA,EAAA,sBA3BF,UAAA,CAAW,KA2BT,EAAA,GAAA,SAAA,EAAA,gBA1BR,gBA0BQ,CA1BS,MA0BT,CAAA,MAAA,EAAA,OAAA,CAAA,CAAA,GAAA,SAAA,CAAA,GAzBtB,YAyBsB,CAzBT,OAyBS,EAzBA,aAyBA,EAzBe,OAyBf,CAAA,GAxBxB,+BAwBwB,CAAA,CAAA,GAxBY,UAwBZ,CAAA,OAxB8B,iBAwB9B,CAAA,CAAA,CAAA,GAvBxB,+BAuBwB,CAtBtB,wBAsBsB,CAtBG,OAsBH,CAAA,CAAA,YAAA,CAAA,CAAA,GApBxB,+BAoBwB,CApBQ,aAoBR,CAAA;;;;;;;;;;;;;;;;;;iBADV,4BACE,OAAA,CAAQ,qBAEpB,iBAAiB,8EAEO,UAAA,CAAW,kDACtB,OAAA,CAAQ,YAClB,aAAa,SAAS,eAAe,8BAGpC,kBACC,iBAAiB,eAAe,mBAChC,WACR,iBAAiB"}

package/components/DeferredFunction.d.ts

@@ -1,9 +1,10 @@
 import { internalEvents } from "../helpers/consts.js";
 import { Marker, markerKey } from "../helpers/marker.js";
-import { Middleware } from "./middleware/middleware.js";
 import { createStepTools } from "./InngestStepTools.js";
-import { InngestFunction } from "./InngestFunction.js";
-import { ApplyAllMiddlewareCtxExtensions, ApplyAllMiddlewareStepExtensions, BaseContext, FunctionConfig, Handler } from "../types.js";
+import { Middleware } from "./middleware/middleware.js";
+import { CreateExecutionOptions, InngestFunction } from "./InngestFunction.js";
+import { IInngestExecution } from "./execution/InngestExecution.js";
+import { ApplyAllMiddlewareCtxExtensions, ApplyAllMiddlewareStepExtensions, BaseContext, ExperimentRef, FunctionConfig, Handler } from "../types.js";
 import { ClientOptionsFromInngest, Inngest, builtInMiddleware } from "./Inngest.js";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 
@@ -30,6 +31,14 @@ declare class DeferredFunction<TSchema extends StandardSchemaV1<Record<string, u
   readonly [markerKey]: Marker;
   constructor(client: Inngest.Any, opts: DeferredFunction.Options, handler: Handler.Any, schema: TSchema);
   protected getConfigTriggers(fnId: string): FunctionConfig["triggers"];
+  /**
+   * Installs a `transformCtx` hook that runs before middleware and user code:
+   * - Strips our `_inngest` metadata off each event's `data`, ensuring it
+   *   matches what the user expects.
+   * - Collects the parent function's slug and run ID from that metadata into
+   *   `ctx.parents`, so the handler can correlate each event to its parent.
+   */
+  protected createExecution(opts: CreateExecutionOptions): IInngestExecution;
 }
 /**
  * @public
@@ -46,11 +55,22 @@ declare namespace DeferredFunction {
    * (not yet supported), and `batchEvents` (each `defer(...)` is its own run).
    */
   type Options = Omit<InngestFunction.Options<[], never>, "triggers" | "onFailure" | "batchEvents">;
+  /**
+   * Metadata describing the parent run that triggered the deferred run. Derived
+   * from `event.data._inngest` and surfaced on the handler ctx as `parents[i]`,
+   * aligned with `events[i]`.
+   */
+  type Parent = {
+    fnSlug: string;
+    runId: string;
+    experiment?: ExperimentRef;
+  };
 }
 /**
- * The `event` shape a defer handler receives. With a schema, `data`
- * narrows to its inferred type; without one, it falls back to
- * `Record<string, any>`.
+ * The `event` shape a defer handler receives. `data` carries the user payload
+ * directly, narrowed by the schema if one is set (otherwise
+ * `Record<string, any>`). Parent metadata is exposed separately on
+ * `ctx.parents` so events and parents can be matched by index.
  */
 type DeferEvent<TSchema> = {
   name: internalEvents.DeferredSchedule;
@@ -60,11 +80,12 @@ type DeferEvent<TSchema> = {
  * Base ctx shape for a defer handler: the standard function context
  * (`runId`, `attempt`, `group`, `step` with middleware step extensions)
  * with `event`/`events` pinned to `inngest/deferred.schedule` and the
- * schema-typed payload.
+ * schema-typed payload, plus `parents` aligned with `events` by index.
  */
 type BaseDeferCtx<TClient extends Inngest.Any, TFnMiddleware extends Middleware.Class[] | undefined, TSchema extends StandardSchemaV1<Record<string, unknown>> | undefined> = Omit<BaseContext<TClient>, "event" | "events" | "step"> & {
   event: DeferEvent<TSchema>;
   events: [DeferEvent<TSchema>];
+  parents: [DeferredFunction.Parent];
   step: ReturnType<typeof createStepTools<TClient, TFnMiddleware>> & ApplyAllMiddlewareStepExtensions<ClientOptionsFromInngest<TClient>["middleware"]> & ApplyAllMiddlewareStepExtensions<TFnMiddleware>;
 };
 /**
@@ -76,6 +97,11 @@ type CreateDeferInput<TFnMiddleware extends Middleware.Class[] | undefined, TSch
   schema?: TSchema;
   middleware?: TFnMiddleware;
 };
+/**
+ * Full handler context for a defer function: `BaseDeferCtx` plus every
+ * middleware ctx extension that applies (built-in, client, function-level).
+ */
+type DeferContext<TClient extends Inngest.Any, TFnMiddleware extends Middleware.Class[] | undefined, TSchema extends StandardSchemaV1<Record<string, unknown>> | undefined> = BaseDeferCtx<TClient, TFnMiddleware, TSchema> & ApplyAllMiddlewareCtxExtensions<[...ReturnType<typeof builtInMiddleware>]> & ApplyAllMiddlewareCtxExtensions<ClientOptionsFromInngest<TClient>["middleware"]> & ApplyAllMiddlewareCtxExtensions<TFnMiddleware>;
 /**
  * EXPERIMENTAL: This API is not yet stable and may change in the future without
  * a major version bump.
@@ -93,7 +119,7 @@ type CreateDeferInput<TFnMiddleware extends Middleware.Class[] | undefined, TSch
  * Pass the result to `serve()` alongside regular functions so the SDK
  * registers it.
  */
-declare function createDefer<TClient extends Inngest.Any, TSchema extends StandardSchemaV1<Record<string, unknown>> | undefined = undefined, const TFnMiddleware extends Middleware.Class[] | undefined = undefined, THandler extends Handler.Any = (ctx: BaseDeferCtx<TClient, TFnMiddleware, TSchema> & ApplyAllMiddlewareCtxExtensions<[...ReturnType<typeof builtInMiddleware>]> & ApplyAllMiddlewareCtxExtensions<ClientOptionsFromInngest<TClient>["middleware"]> & ApplyAllMiddlewareCtxExtensions<TFnMiddleware>) => unknown>(client: TClient, options: CreateDeferInput<TFnMiddleware, TSchema>, handler: THandler): DeferredFunction<TSchema>;
+declare function createDefer<TClient extends Inngest.Any, TSchema extends StandardSchemaV1<Record<string, unknown>> | undefined = undefined, const TFnMiddleware extends Middleware.Class[] | undefined = undefined, THandler extends Handler.Any = (ctx: DeferContext<TClient, TFnMiddleware, TSchema>) => unknown>(client: TClient, options: CreateDeferInput<TFnMiddleware, TSchema>, handler: THandler): DeferredFunction<TSchema>;
 //#endregion
-export { DeferredFunction, createDefer };
+export { CreateDeferInput, DeferContext, DeferredFunction, createDefer };
 //# sourceMappingURL=DeferredFunction.d.ts.map

package/components/DeferredFunction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DeferredFunction.d.ts","names":[],"sources":["../../src/components/DeferredFunction.ts"],"sourcesContent":[],"mappings":"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"}
+{"version":3,"file":"DeferredFunction.d.ts","names":[],"sources":["../../src/components/DeferredFunction.ts"],"sourcesContent":[],"mappings":"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"}

package/components/DeferredFunction.js

@@ -1,10 +1,39 @@
-import { internalEvents } from "../helpers/consts.js";
+import { deferExperimentKey, internalEvents } from "../helpers/consts.js";
+import { UnreachableError } from "../helpers/errors.js";
+import { isRecord } from "../helpers/types.js";
 import { markerKey } from "../helpers/marker.js";
 import { InngestFunction } from "./InngestFunction.js";
 
 //#region src/components/DeferredFunction.ts
 const idDenyRegex = /['\\\n\r]/;
 /**
+* Validates the reserved experiment-ref input key into an `ExperimentRef`, or
+* `undefined` when it's absent or malformed.
+*/
+function parseExperimentRef(value) {
+	if (isRecord(value) && typeof value.experimentName === "string" && typeof value.variant === "string") return {
+		experimentName: value.experimentName,
+		variant: value.variant
+	};
+}
+/**
+* Strips our `_inngest` metadata off an event's `data` in place and returns the
+* parent routing metadata extracted from it.
+*/
+function stripInngestMetadata(event) {
+	const { _inngest, [deferExperimentKey]: experiment, ...input } = event.data ?? {};
+	if (!isRecord(_inngest)) throw new UnreachableError("deferred event is missing _inngest metadata");
+	const { parent_fn_slug, parent_run_id } = _inngest;
+	if (typeof parent_fn_slug !== "string") throw new UnreachableError("deferred event _inngest metadata is missing parent_fn_slug");
+	if (typeof parent_run_id !== "string") throw new UnreachableError("deferred event _inngest metadata is missing parent_run_id");
+	event.data = input;
+	return {
+		fnSlug: parent_fn_slug,
+		runId: parent_run_id,
+		experiment: parseExperimentRef(experiment)
+	};
+}
+/**
 * EXPERIMENTAL: This API is not yet stable and may change in the future without
 * a major version bump.
 *
@@ -37,6 +66,29 @@ var DeferredFunction = class extends InngestFunction {
 			expression: `event.data._inngest.fn_slug == '${fnId}'`
 		}];
 	}
+	/**
+	* Installs a `transformCtx` hook that runs before middleware and user code:
+	* - Strips our `_inngest` metadata off each event's `data`, ensuring it
+	*   matches what the user expects.
+	* - Collects the parent function's slug and run ID from that metadata into
+	*   `ctx.parents`, so the handler can correlate each event to its parent.
+	*/
+	createExecution(opts) {
+		return super.createExecution({
+			...opts,
+			partialOptions: {
+				...opts.partialOptions,
+				transformCtx: (ctx) => {
+					const parents = ctx.events.map(stripInngestMetadata);
+					stripInngestMetadata(ctx.event);
+					return {
+						...ctx,
+						parents
+					};
+				}
+			}
+		});
+	}
 };
 /**
 * EXPERIMENTAL: This API is not yet stable and may change in the future without

package/components/DeferredFunction.js.map

@@ -1 +1 @@
-{"version":3,"file":"DeferredFunction.js","names":[],"sources":["../../src/components/DeferredFunction.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport { internalEvents } from \"../helpers/consts.ts\";\nimport { type Marker, markerKey } from \"../helpers/marker.ts\";\nimport type {\n  ApplyAllMiddlewareCtxExtensions,\n  ApplyAllMiddlewareStepExtensions,\n  BaseContext,\n  FunctionConfig,\n  Handler,\n} from \"../types.ts\";\nimport type {\n  builtInMiddleware,\n  ClientOptionsFromInngest,\n  Inngest,\n} from \"./Inngest.ts\";\nimport { InngestFunction } from \"./InngestFunction.ts\";\nimport type { createStepTools } from \"./InngestStepTools.ts\";\nimport type { Middleware } from \"./middleware/index.ts\";\n\nconst idDenyRegex = /['\\\\\\n\\r]/;\n\n/**\n * EXPERIMENTAL: This API is not yet stable and may change in the future without\n * a major version bump.\n *\n * A defer (companion) function created via `createDefer(...)`. Real\n * `InngestFunction` at runtime, but with the trigger pinned to\n * `inngest/deferred.schedule` (see `getConfigTriggers`), `triggers` and\n * `onFailure` disallowed, and the schema carried as a typed instance\n * property so callers of `defer(id, { function, data })` can extract it.\n *\n * Identify a defer function at runtime via `isDeferredFunction(value)` from\n * `helpers/marker.ts`. Prefer that over `instanceof`, which fails across\n * duplicate SDK copies in the same process.\n *\n * @public\n */\nexport class DeferredFunction<\n  TSchema extends\n    | StandardSchemaV1<Record<string, unknown>>\n    | undefined = undefined,\n> extends InngestFunction<\n  InngestFunction.Options<[], never>,\n  Handler.Any,\n  never,\n  Inngest.Any,\n  []\n> {\n  readonly schema: TSchema;\n  readonly [markerKey]: Marker = { kind: \"DeferredFunction\" };\n\n  constructor(\n    client: Inngest.Any,\n    opts: DeferredFunction.Options,\n    handler: Handler.Any,\n    schema: TSchema,\n  ) {\n    // The id is interpolated into a CEL trigger expression\n    // (`event.data._inngest.fn_slug == '${fnId}'`). Reject characters that\n    // would break the single-quoted string literal.\n    if (idDenyRegex.test(opts.id)) {\n      throw new Error(\n        `invalid id \"${opts.id}\"; must match ${idDenyRegex.source}`,\n      );\n    }\n    super(\n      client,\n      { ...opts, triggers: [] } as InngestFunction.Options<[], never>,\n      handler,\n    );\n    this.schema = schema;\n  }\n\n  protected override getConfigTriggers(\n    fnId: string,\n  ): FunctionConfig[\"triggers\"] {\n    return [\n      {\n        event: internalEvents.DeferredSchedule,\n        expression: `event.data._inngest.fn_slug == '${fnId}'`,\n      },\n    ];\n  }\n}\n\n/**\n * @public\n */\nexport namespace DeferredFunction {\n  /**\n   * Matches any `DeferredFunction` regardless of its schema. Use as the\n   * constraint for the `function` argument of `defer()`.\n   */\n  // biome-ignore lint/suspicious/noExplicitAny: widest schema constraint for inference\n  export type Any = DeferredFunction<StandardSchemaV1<any> | undefined>;\n\n  /**\n   * The user-facing options accepted by `createDefer(client, opts, handler)`.\n   * Mirrors `InngestFunction.Options` minus `triggers` (implicit), `onFailure`\n   * (not yet supported), and `batchEvents` (each `defer(...)` is its own run).\n   */\n  export type Options = Omit<\n    InngestFunction.Options<[], never>,\n    \"triggers\" | \"onFailure\" | \"batchEvents\"\n  >;\n}\n\n/**\n * The `event` shape a defer handler receives. With a schema, `data`\n * narrows to its inferred type; without one, it falls back to\n * `Record<string, any>`.\n */\ntype DeferEvent<TSchema> = {\n  name: internalEvents.DeferredSchedule;\n  data: TSchema extends StandardSchemaV1<\n    infer D extends Record<string, unknown>\n  >\n    ? D\n    : // biome-ignore lint/suspicious/noExplicitAny: no schema = any\n      Record<string, any>;\n};\n\n/**\n * Base ctx shape for a defer handler: the standard function context\n * (`runId`, `attempt`, `group`, `step` with middleware step extensions)\n * with `event`/`events` pinned to `inngest/deferred.schedule` and the\n * schema-typed payload.\n */\ntype BaseDeferCtx<\n  TClient extends Inngest.Any,\n  TFnMiddleware extends Middleware.Class[] | undefined,\n  TSchema extends StandardSchemaV1<Record<string, unknown>> | undefined,\n> = Omit<BaseContext<TClient>, \"event\" | \"events\" | \"step\"> & {\n  event: DeferEvent<TSchema>;\n  events: [DeferEvent<TSchema>];\n  step: ReturnType<typeof createStepTools<TClient, TFnMiddleware>> &\n    ApplyAllMiddlewareStepExtensions<\n      ClientOptionsFromInngest<TClient>[\"middleware\"]\n    > &\n    ApplyAllMiddlewareStepExtensions<TFnMiddleware>;\n};\n\n/**\n * Input type for `createDefer`. Same shape as `DeferredFunction.Options`\n * plus `schema` (the StandardSchema describing `event.data` that flows\n * to caller `defer(id, { function, data })` call sites) and `middleware`.\n */\nexport type CreateDeferInput<\n  TFnMiddleware extends Middleware.Class[] | undefined,\n  TSchema extends StandardSchemaV1<Record<string, unknown>> | undefined,\n> = DeferredFunction.Options & {\n  schema?: TSchema;\n  middleware?: TFnMiddleware;\n};\n\n/**\n * EXPERIMENTAL: This API is not yet stable and may change in the future without\n * a major version bump.\n *\n * Create a typed defer function. One `createDefer` call = one Inngest\n * function. Returns a `DeferredFunction<TSchema>` so callers of `defer(id,\n * { function, data })` get the data type inferred from the schema.\n *\n * Mirrors `inngest.createFunction(opts, handler)`, with three differences:\n * the client is the first positional arg, `triggers` is not accepted (the\n * SDK emits an implicit `inngest/deferred.schedule` trigger), and `schema`\n * describes the payload that callers will send via `defer(id, { function,\n * data })`.\n *\n * Pass the result to `serve()` alongside regular functions so the SDK\n * registers it.\n */\nexport function createDefer<\n  TClient extends Inngest.Any,\n  TSchema extends\n    | StandardSchemaV1<Record<string, unknown>>\n    | undefined = undefined,\n  const TFnMiddleware extends Middleware.Class[] | undefined = undefined,\n  THandler extends Handler.Any = (\n    ctx: BaseDeferCtx<TClient, TFnMiddleware, TSchema> &\n      ApplyAllMiddlewareCtxExtensions<\n        [...ReturnType<typeof builtInMiddleware>]\n      > &\n      ApplyAllMiddlewareCtxExtensions<\n        ClientOptionsFromInngest<TClient>[\"middleware\"]\n      > &\n      ApplyAllMiddlewareCtxExtensions<TFnMiddleware>,\n  ) => unknown,\n>(\n  client: TClient,\n  options: CreateDeferInput<TFnMiddleware, TSchema>,\n  handler: THandler,\n): DeferredFunction<TSchema> {\n  const { schema, ...rest } = options;\n  return new DeferredFunction<TSchema>(\n    client,\n    rest,\n    handler as Handler.Any,\n    schema as TSchema,\n  );\n}\n"],"mappings":";;;;;AAmBA,MAAM,cAAc;;;;;;;;;;;;;;;;;AAkBpB,IAAa,mBAAb,cAIU,gBAMR;CACA,AAAS;CACT,CAAU,aAAqB,EAAE,MAAM,oBAAoB;CAE3D,YACE,QACA,MACA,SACA,QACA;AAIA,MAAI,YAAY,KAAK,KAAK,GAAG,CAC3B,OAAM,IAAI,MACR,eAAe,KAAK,GAAG,gBAAgB,YAAY,SACpD;AAEH,QACE,QACA;GAAE,GAAG;GAAM,UAAU,EAAE;GAAE,EACzB,QACD;AACD,OAAK,SAAS;;CAGhB,AAAmB,kBACjB,MAC4B;AAC5B,SAAO,CACL;GACE,OAAO,eAAe;GACtB,YAAY,mCAAmC,KAAK;GACrD,CACF;;;;;;;;;;;;;;;;;;;;AA2FL,SAAgB,YAiBd,QACA,SACA,SAC2B;CAC3B,MAAM,EAAE,QAAQ,GAAG,SAAS;AAC5B,QAAO,IAAI,iBACT,QACA,MACA,SACA,OACD"}
+{"version":3,"file":"DeferredFunction.js","names":[],"sources":["../../src/components/DeferredFunction.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport { deferExperimentKey, internalEvents } from \"../helpers/consts.ts\";\nimport { UnreachableError } from \"../helpers/errors.ts\";\nimport { type Marker, markerKey } from \"../helpers/marker.ts\";\nimport { isRecord } from \"../helpers/types.ts\";\nimport type {\n  ApplyAllMiddlewareCtxExtensions,\n  ApplyAllMiddlewareStepExtensions,\n  BaseContext,\n  ExperimentRef,\n  FunctionConfig,\n  Handler,\n} from \"../types.ts\";\nimport type { IInngestExecution } from \"./execution/InngestExecution.ts\";\nimport type {\n  builtInMiddleware,\n  ClientOptionsFromInngest,\n  Inngest,\n} from \"./Inngest.ts\";\nimport {\n  type CreateExecutionOptions,\n  InngestFunction,\n} from \"./InngestFunction.ts\";\nimport type { createStepTools } from \"./InngestStepTools.ts\";\nimport type { Middleware } from \"./middleware/index.ts\";\n\nconst idDenyRegex = /['\\\\\\n\\r]/;\n\n/**\n * Validates the reserved experiment-ref input key into an `ExperimentRef`, or\n * `undefined` when it's absent or malformed.\n */\nfunction parseExperimentRef(value: unknown): ExperimentRef | undefined {\n  if (\n    isRecord(value) &&\n    typeof value.experimentName === \"string\" &&\n    typeof value.variant === \"string\"\n  ) {\n    return { experimentName: value.experimentName, variant: value.variant };\n  }\n  return undefined;\n}\n\n/**\n * Strips our `_inngest` metadata off an event's `data` in place and returns the\n * parent routing metadata extracted from it.\n */\nfunction stripInngestMetadata(event: {\n  data?: Record<string, unknown>;\n}): DeferredFunction.Parent {\n  const data = event.data ?? {};\n  const { _inngest, [deferExperimentKey]: experiment, ...input } = data;\n\n  if (!isRecord(_inngest)) {\n    throw new UnreachableError(\"deferred event is missing _inngest metadata\");\n  }\n  const { parent_fn_slug, parent_run_id } = _inngest;\n  if (typeof parent_fn_slug !== \"string\") {\n    throw new UnreachableError(\n      \"deferred event _inngest metadata is missing parent_fn_slug\",\n    );\n  }\n  if (typeof parent_run_id !== \"string\") {\n    throw new UnreachableError(\n      \"deferred event _inngest metadata is missing parent_run_id\",\n    );\n  }\n\n  // Mutate in place\n  event.data = input;\n\n  return {\n    fnSlug: parent_fn_slug,\n    runId: parent_run_id,\n    experiment: parseExperimentRef(experiment),\n  };\n}\n\n/**\n * EXPERIMENTAL: This API is not yet stable and may change in the future without\n * a major version bump.\n *\n * A defer (companion) function created via `createDefer(...)`. Real\n * `InngestFunction` at runtime, but with the trigger pinned to\n * `inngest/deferred.schedule` (see `getConfigTriggers`), `triggers` and\n * `onFailure` disallowed, and the schema carried as a typed instance\n * property so callers of `defer(id, { function, data })` can extract it.\n *\n * Identify a defer function at runtime via `isDeferredFunction(value)` from\n * `helpers/marker.ts`. Prefer that over `instanceof`, which fails across\n * duplicate SDK copies in the same process.\n *\n * @public\n */\nexport class DeferredFunction<\n  TSchema extends\n    | StandardSchemaV1<Record<string, unknown>>\n    | undefined = undefined,\n> extends InngestFunction<\n  InngestFunction.Options<[], never>,\n  Handler.Any,\n  never,\n  Inngest.Any,\n  []\n> {\n  readonly schema: TSchema;\n  readonly [markerKey]: Marker = { kind: \"DeferredFunction\" };\n\n  constructor(\n    client: Inngest.Any,\n    opts: DeferredFunction.Options,\n    handler: Handler.Any,\n    schema: TSchema,\n  ) {\n    // The id is interpolated into a CEL trigger expression\n    // (`event.data._inngest.fn_slug == '${fnId}'`). Reject characters that\n    // would break the single-quoted string literal.\n    if (idDenyRegex.test(opts.id)) {\n      throw new Error(\n        `invalid id \"${opts.id}\"; must match ${idDenyRegex.source}`,\n      );\n    }\n    super(\n      client,\n      { ...opts, triggers: [] } as InngestFunction.Options<[], never>,\n      handler,\n    );\n    this.schema = schema;\n  }\n\n  protected override getConfigTriggers(\n    fnId: string,\n  ): FunctionConfig[\"triggers\"] {\n    return [\n      {\n        event: internalEvents.DeferredSchedule,\n        expression: `event.data._inngest.fn_slug == '${fnId}'`,\n      },\n    ];\n  }\n\n  /**\n   * Installs a `transformCtx` hook that runs before middleware and user code:\n   * - Strips our `_inngest` metadata off each event's `data`, ensuring it\n   *   matches what the user expects.\n   * - Collects the parent function's slug and run ID from that metadata into\n   *   `ctx.parents`, so the handler can correlate each event to its parent.\n   */\n  protected override createExecution(\n    opts: CreateExecutionOptions,\n  ): IInngestExecution {\n    return super.createExecution({\n      ...opts,\n      partialOptions: {\n        ...opts.partialOptions,\n        transformCtx: (ctx) => {\n          // Get the parent info from each event. Also removes our internal\n          // metadata from each event (mutates in place).\n          const parents = ctx.events.map(stripInngestMetadata);\n\n          // Removes our internal metadata from the event (mutates in place).\n          stripInngestMetadata(ctx.event);\n\n          return {\n            ...ctx,\n            parents,\n          };\n        },\n      },\n    });\n  }\n}\n\n/**\n * @public\n */\nexport namespace DeferredFunction {\n  /**\n   * Matches any `DeferredFunction` regardless of its schema. Use as the\n   * constraint for the `function` argument of `defer()`.\n   */\n  // biome-ignore lint/suspicious/noExplicitAny: widest schema constraint for inference\n  export type Any = DeferredFunction<StandardSchemaV1<any> | undefined>;\n\n  /**\n   * The user-facing options accepted by `createDefer(client, opts, handler)`.\n   * Mirrors `InngestFunction.Options` minus `triggers` (implicit), `onFailure`\n   * (not yet supported), and `batchEvents` (each `defer(...)` is its own run).\n   */\n  export type Options = Omit<\n    InngestFunction.Options<[], never>,\n    \"triggers\" | \"onFailure\" | \"batchEvents\"\n  >;\n\n  /**\n   * Metadata describing the parent run that triggered the deferred run. Derived\n   * from `event.data._inngest` and surfaced on the handler ctx as `parents[i]`,\n   * aligned with `events[i]`.\n   */\n  export type Parent = {\n    fnSlug: string;\n    runId: string;\n    experiment?: ExperimentRef;\n  };\n}\n\n/**\n * The `event` shape a defer handler receives. `data` carries the user payload\n * directly, narrowed by the schema if one is set (otherwise\n * `Record<string, any>`). Parent metadata is exposed separately on\n * `ctx.parents` so events and parents can be matched by index.\n */\ntype DeferEvent<TSchema> = {\n  name: internalEvents.DeferredSchedule;\n  data: TSchema extends StandardSchemaV1<\n    infer D extends Record<string, unknown>\n  >\n    ? D\n    : // biome-ignore lint/suspicious/noExplicitAny: no schema = any\n      Record<string, any>;\n};\n\n/**\n * Base ctx shape for a defer handler: the standard function context\n * (`runId`, `attempt`, `group`, `step` with middleware step extensions)\n * with `event`/`events` pinned to `inngest/deferred.schedule` and the\n * schema-typed payload, plus `parents` aligned with `events` by index.\n */\ntype BaseDeferCtx<\n  TClient extends Inngest.Any,\n  TFnMiddleware extends Middleware.Class[] | undefined,\n  TSchema extends StandardSchemaV1<Record<string, unknown>> | undefined,\n> = Omit<BaseContext<TClient>, \"event\" | \"events\" | \"step\"> & {\n  event: DeferEvent<TSchema>;\n  events: [DeferEvent<TSchema>];\n  parents: [DeferredFunction.Parent];\n  step: ReturnType<typeof createStepTools<TClient, TFnMiddleware>> &\n    ApplyAllMiddlewareStepExtensions<\n      ClientOptionsFromInngest<TClient>[\"middleware\"]\n    > &\n    ApplyAllMiddlewareStepExtensions<TFnMiddleware>;\n};\n\n/**\n * Input type for `createDefer`. Same shape as `DeferredFunction.Options`\n * plus `schema` (the StandardSchema describing `event.data` that flows\n * to caller `defer(id, { function, data })` call sites) and `middleware`.\n */\nexport type CreateDeferInput<\n  TFnMiddleware extends Middleware.Class[] | undefined,\n  TSchema extends StandardSchemaV1<Record<string, unknown>> | undefined,\n> = DeferredFunction.Options & {\n  schema?: TSchema;\n  middleware?: TFnMiddleware;\n};\n\n/**\n * Full handler context for a defer function: `BaseDeferCtx` plus every\n * middleware ctx extension that applies (built-in, client, function-level).\n */\nexport type DeferContext<\n  TClient extends Inngest.Any,\n  TFnMiddleware extends Middleware.Class[] | undefined,\n  TSchema extends StandardSchemaV1<Record<string, unknown>> | undefined,\n> = BaseDeferCtx<TClient, TFnMiddleware, TSchema> &\n  ApplyAllMiddlewareCtxExtensions<[...ReturnType<typeof builtInMiddleware>]> &\n  ApplyAllMiddlewareCtxExtensions<\n    ClientOptionsFromInngest<TClient>[\"middleware\"]\n  > &\n  ApplyAllMiddlewareCtxExtensions<TFnMiddleware>;\n\n/**\n * EXPERIMENTAL: This API is not yet stable and may change in the future without\n * a major version bump.\n *\n * Create a typed defer function. One `createDefer` call = one Inngest\n * function. Returns a `DeferredFunction<TSchema>` so callers of `defer(id,\n * { function, data })` get the data type inferred from the schema.\n *\n * Mirrors `inngest.createFunction(opts, handler)`, with three differences:\n * the client is the first positional arg, `triggers` is not accepted (the\n * SDK emits an implicit `inngest/deferred.schedule` trigger), and `schema`\n * describes the payload that callers will send via `defer(id, { function,\n * data })`.\n *\n * Pass the result to `serve()` alongside regular functions so the SDK\n * registers it.\n */\nexport function createDefer<\n  TClient extends Inngest.Any,\n  TSchema extends\n    | StandardSchemaV1<Record<string, unknown>>\n    | undefined = undefined,\n  const TFnMiddleware extends Middleware.Class[] | undefined = undefined,\n  THandler extends Handler.Any = (\n    ctx: DeferContext<TClient, TFnMiddleware, TSchema>,\n  ) => unknown,\n>(\n  client: TClient,\n  options: CreateDeferInput<TFnMiddleware, TSchema>,\n  handler: THandler,\n): DeferredFunction<TSchema> {\n  const { schema, ...rest } = options;\n  return new DeferredFunction<TSchema>(\n    client,\n    rest,\n    handler as Handler.Any,\n    schema as TSchema,\n  );\n}\n"],"mappings":";;;;;;;AA0BA,MAAM,cAAc;;;;;AAMpB,SAAS,mBAAmB,OAA2C;AACrE,KACE,SAAS,MAAM,IACf,OAAO,MAAM,mBAAmB,YAChC,OAAO,MAAM,YAAY,SAEzB,QAAO;EAAE,gBAAgB,MAAM;EAAgB,SAAS,MAAM;EAAS;;;;;;AAS3E,SAAS,qBAAqB,OAEF;CAE1B,MAAM,EAAE,WAAW,qBAAqB,YAAY,GAAG,UAD1C,MAAM,QAAQ,EAAE;AAG7B,KAAI,CAAC,SAAS,SAAS,CACrB,OAAM,IAAI,iBAAiB,8CAA8C;CAE3E,MAAM,EAAE,gBAAgB,kBAAkB;AAC1C,KAAI,OAAO,mBAAmB,SAC5B,OAAM,IAAI,iBACR,6DACD;AAEH,KAAI,OAAO,kBAAkB,SAC3B,OAAM,IAAI,iBACR,4DACD;AAIH,OAAM,OAAO;AAEb,QAAO;EACL,QAAQ;EACR,OAAO;EACP,YAAY,mBAAmB,WAAW;EAC3C;;;;;;;;;;;;;;;;;;AAmBH,IAAa,mBAAb,cAIU,gBAMR;CACA,AAAS;CACT,CAAU,aAAqB,EAAE,MAAM,oBAAoB;CAE3D,YACE,QACA,MACA,SACA,QACA;AAIA,MAAI,YAAY,KAAK,KAAK,GAAG,CAC3B,OAAM,IAAI,MACR,eAAe,KAAK,GAAG,gBAAgB,YAAY,SACpD;AAEH,QACE,QACA;GAAE,GAAG;GAAM,UAAU,EAAE;GAAE,EACzB,QACD;AACD,OAAK,SAAS;;CAGhB,AAAmB,kBACjB,MAC4B;AAC5B,SAAO,CACL;GACE,OAAO,eAAe;GACtB,YAAY,mCAAmC,KAAK;GACrD,CACF;;;;;;;;;CAUH,AAAmB,gBACjB,MACmB;AACnB,SAAO,MAAM,gBAAgB;GAC3B,GAAG;GACH,gBAAgB;IACd,GAAG,KAAK;IACR,eAAe,QAAQ;KAGrB,MAAM,UAAU,IAAI,OAAO,IAAI,qBAAqB;AAGpD,0BAAqB,IAAI,MAAM;AAE/B,YAAO;MACL,GAAG;MACH;MACD;;IAEJ;GACF,CAAC;;;;;;;;;;;;;;;;;;;;AAuHN,SAAgB,YAUd,QACA,SACA,SAC2B;CAC3B,MAAM,EAAE,QAAQ,GAAG,SAAS;AAC5B,QAAO,IAAI,iBACT,QACA,MACA,SACA,OACD"}

package/components/Inngest.cjs

@@ -14,6 +14,7 @@ const require_metadataProcessor = require('./execution/otel/metadataProcessor.cj
 const require_InngestFunction = require('./InngestFunction.cjs');
 const require_middleware = require('./middleware/middleware.cjs');
 const require_InngestMetadata = require('./InngestMetadata.cjs');
+const require_InngestScore = require('./InngestScore.cjs');
 const require_InngestStepTools = require('./InngestStepTools.cjs');
 const require_utils = require('./middleware/utils.cjs');
 const require_index = require('./realtime/subscribe/index.cjs');
@@ -58,6 +59,12 @@ var Inngest = class Inngest {
 	_cachedFetch;
 	_logger;
 	/**
+	* Whether this client should collect AI metadata from OpenTelemetry spans.
+	*
+	* @internal
+	*/
+	aiMetadataEnabled;
+	/**
 	* Logger for SDK internal messages. Falls back to the user's `logger` if
 	* `internalLogger` is not provided in client options.
 	*
@@ -77,6 +84,11 @@ var Inngest = class Inngest {
 	*/
 	experimentalMetadataEnabled = false;
 	/**
+	* @internal
+	* Flag set by scoreMiddleware to enable step.score().
+	*/
+	experimentalScoreEnabled = false;
+	/**
 	* A dummy Inngest function used in Durable Endpoints. This is necessary
 	* because the vast majority of middleware hooks require the Inngest function.
 	* But for Durable Endpoints, there is no Inngest function. So we need some
@@ -173,6 +185,16 @@ var Inngest = class Inngest {
 		return new require_InngestMetadata.UnscopedMetadataBuilder(this);
 	}
 	/**
+	* Write scores. Call directly to write a live score for a run or step; use
+	* `inngest.score.experiment(...)` to attach a score to a `group.experiment()`
+	* variant.
+	*
+	* For standalone durable score writes, prefer `step.score()`.
+	*/
+	get score() {
+		return Object.assign((options) => require_InngestScore.sendScore(this, options), { experiment: (options) => require_InngestScore.sendScoreExperiment(this, options) });
+	}
+	/**
 	* A client used to interact with the Inngest API by sending or reacting to
 	* events.
 	*
@@ -185,6 +207,7 @@ var Inngest = class Inngest {
 		const { id, logger, middleware, appVersion } = this.options;
 		if (!id) throw new Error("An `id` must be passed to create an Inngest instance.");
 		this.id = id;
+		this.aiMetadataEnabled = this.options.aiMetadata !== false;
 		this._env = require_env.protectEnv({ ...require_env.getProcessEnv() });
 		this._userProvidedFetch = options.fetch;
 		this.inngestApi = new require_api.InngestApi({
@@ -201,7 +224,7 @@ var Inngest = class Inngest {
 			client: this,
 			fn: null
 		});
-		require_metadataProcessor.metadataSpanProcessor.attach();
+		if (this.aiMetadataEnabled) require_metadataProcessor.metadataSpanProcessor.attach();
 		this._appVersion = appVersion;
 	}
 	/**