@walkeros/core 4.0.0 → 4.1.0-next-1778155282668

package/dist/index.d.mts

@@ -312,7 +312,6 @@ interface Instance$6 {
     timing: number;
     user: User;
     pending: {
-        sources: InitSources;
         destinations: InitDestinations;
     };
 }
@@ -347,34 +346,36 @@ declare namespace context {
 }
 
 /**
- * Context provided to the destroy() lifecycle method.
- *
- * A subset of the init context — config, env, logger, and id.
- * Does NOT include collector or event data. Destroy should only
- * clean up resources, not interact with the event pipeline.
+ * Shared context for one-shot lifecycle hooks (setup, destroy).
+ * No event pipeline machinery — just config, env, logger, and id.
  */
-interface DestroyContext<C = unknown, E = unknown> {
-    /** Step instance ID. */
+interface LifecycleContext<C = unknown, E = unknown> {
     id: string;
-    /** Step configuration (contains settings with SDK clients, etc.). */
     config: C;
-    /** Runtime environment/dependencies (DB clients, auth clients, etc.). */
     env: E;
-    /** Scoped logger for this step instance. */
     logger: Instance$4;
 }
+/**
+ * Setup function signature. Called once via `walkeros setup <kind>.<name>`.
+ * Packages own idempotency and error semantics. Return value (if any) is
+ * JSON-stringified to stdout by the CLI for scripting use.
+ */
+type SetupFn<C = unknown, E = unknown> = (context: LifecycleContext<C, E>) => PromiseOrValue<unknown>;
 /**
  * Destroy function signature for step lifecycle cleanup.
- *
- * Implementations should be idempotent — calling destroy() twice must not throw.
- * Used for closing connections, clearing timers, releasing SDK clients.
  */
-type DestroyFn<C = unknown, E = unknown> = (context: DestroyContext<C, E>) => PromiseOrValue<void>;
+type DestroyFn<C = unknown, E = unknown> = (context: LifecycleContext<C, E>) => PromiseOrValue<void>;
+/**
+ * @deprecated Use `LifecycleContext` instead. Kept as alias for one minor cycle.
+ */
+type DestroyContext<C = unknown, E = unknown> = LifecycleContext<C, E>;
 
 type lifecycle_DestroyContext<C = unknown, E = unknown> = DestroyContext<C, E>;
 type lifecycle_DestroyFn<C = unknown, E = unknown> = DestroyFn<C, E>;
+type lifecycle_LifecycleContext<C = unknown, E = unknown> = LifecycleContext<C, E>;
+type lifecycle_SetupFn<C = unknown, E = unknown> = SetupFn<C, E>;
 declare namespace lifecycle {
-  export type { lifecycle_DestroyContext as DestroyContext, lifecycle_DestroyFn as DestroyFn };
+  export type { lifecycle_DestroyContext as DestroyContext, lifecycle_DestroyFn as DestroyFn, lifecycle_LifecycleContext as LifecycleContext, lifecycle_SetupFn as SetupFn };
 }
 
 /**
@@ -393,13 +394,14 @@ interface BaseEnv$3 {
 }
 /**
  * Type bundle for destination generics.
- * Groups Settings, InitSettings, Mapping, and Env into a single type parameter.
+ * Groups Settings, InitSettings, Mapping, Env, and Setup into a single type parameter.
  */
-interface Types$4<S = unknown, M = unknown, E = BaseEnv$3, I = S> {
+interface Types$4<S = unknown, M = unknown, E = BaseEnv$3, I = S, U = unknown> {
     settings: S;
     initSettings: I;
     mapping: M;
     env: E;
+    setup: U;
 }
 /**
  * Generic constraint for Types - ensures T has required properties for indexed access
@@ -409,6 +411,7 @@ type TypesGeneric$3 = {
     initSettings: any;
     mapping: any;
     env: any;
+    setup: any;
 };
 /**
  * Type extractors for consistent usage with Types bundle
@@ -417,6 +420,7 @@ type Settings$3<T extends TypesGeneric$3 = Types$4> = T['settings'];
 type InitSettings$3<T extends TypesGeneric$3 = Types$4> = T['initSettings'];
 type Mapping$1<T extends TypesGeneric$3 = Types$4> = T['mapping'];
 type Env$3<T extends TypesGeneric$3 = Types$4> = T['env'];
+type SetupOptions$2<T extends TypesGeneric$3 = Types$4> = T['setup'];
 /**
  * Inference helper: Extract Types from Instance
  */
@@ -432,6 +436,7 @@ interface Instance$5<T extends TypesGeneric$3 = Types$4> {
     batches?: BatchRegistry<Mapping$1<T>>;
     type?: string;
     env?: Env$3<T>;
+    setup?: SetupFn<Config$5<T>, Env$3<T>>;
     init?: InitFn$2<T>;
     push: PushFn<T>;
     pushBatch?: PushBatchFn<T>;
@@ -465,6 +470,11 @@ interface Config$5<T extends TypesGeneric$3 = Types$4> {
     queue?: boolean;
     /** Defer destination initialization until these collector events fire (e.g., `['consent']`). */
     require?: string[];
+    /**
+     * Provisioning options for `walker setup`. `boolean | object`.
+     * Triggered only by explicit CLI invocation; never automatic.
+     */
+    setup?: boolean | SetupOptions$2<T>;
     /** Transformer chain to run after collector processing but before this destination. */
     before?: Next;
     /** Transformer chain to run after destination push completes. Push response available at ingest._response. */
@@ -476,7 +486,7 @@ interface Config$5<T extends TypesGeneric$3 = Types$4> {
     /** Return this value instead of calling push(). Uses !== undefined check to support falsy values. */
     mock?: unknown;
 }
-type PartialConfig$1<T extends TypesGeneric$3 = Types$4> = Config$5<Types$4<Partial<Settings$3<T>> | Settings$3<T>, Partial<Mapping$1<T>> | Mapping$1<T>, Env$3<T>>>;
+type PartialConfig$2<T extends TypesGeneric$3 = Types$4> = Config$5<Types$4<Partial<Settings$3<T>> | Settings$3<T>, Partial<Mapping$1<T>> | Mapping$1<T>, Env$3<T>, InitSettings$3<T>, SetupOptions$2<T>>>;
 interface Policy {
     [key: string]: Value;
 }
@@ -558,7 +568,7 @@ type destination_PushEvents<Mapping = unknown> = PushEvents<Mapping>;
 type destination_PushFn<T extends TypesGeneric$3 = Types$4> = PushFn<T>;
 type destination_Ref = Ref;
 declare namespace destination {
-  export type { BaseEnv$3 as BaseEnv, destination_Batch as Batch, destination_BatchRegistry as BatchRegistry, Code$1 as Code, Config$5 as Config, Context$5 as Context, destination_DLQ as DLQ, destination_Data as Data, destination_Destinations as Destinations, Env$3 as Env, Init$3 as Init, destination_InitDestinations as InitDestinations, InitFn$2 as InitFn, InitSettings$3 as InitSettings, Instance$5 as Instance, Mapping$1 as Mapping, PartialConfig$1 as PartialConfig, destination_Policy as Policy, Push$1 as Push, destination_PushBatchContext as PushBatchContext, destination_PushBatchFn as PushBatchFn, destination_PushContext as PushContext, destination_PushEvent as PushEvent, destination_PushEvents as PushEvents, destination_PushFn as PushFn, destination_Ref as Ref, Settings$3 as Settings, Types$4 as Types, TypesGeneric$3 as TypesGeneric, TypesOf$3 as TypesOf };
+  export type { BaseEnv$3 as BaseEnv, destination_Batch as Batch, destination_BatchRegistry as BatchRegistry, Code$1 as Code, Config$5 as Config, Context$5 as Context, destination_DLQ as DLQ, destination_Data as Data, destination_Destinations as Destinations, Env$3 as Env, Init$3 as Init, destination_InitDestinations as InitDestinations, InitFn$2 as InitFn, InitSettings$3 as InitSettings, Instance$5 as Instance, Mapping$1 as Mapping, PartialConfig$2 as PartialConfig, destination_Policy as Policy, Push$1 as Push, destination_PushBatchContext as PushBatchContext, destination_PushBatchFn as PushBatchFn, destination_PushContext as PushContext, destination_PushEvent as PushEvent, destination_PushEvents as PushEvents, destination_PushFn as PushFn, destination_Ref as Ref, Settings$3 as Settings, SetupOptions$2 as SetupOptions, Types$4 as Types, TypesGeneric$3 as TypesGeneric, TypesOf$3 as TypesOf };
 }
 
 interface EventFn<R = Promise<PushResult>> {
@@ -608,7 +618,8 @@ declare namespace elb {
  * Represents one deployment target (e.g., web_prod, server_stage).
  * Platform is determined by `config.platform` ('web' | 'server').
  *
- * Variables/definitions cascade: source/destination > flow > root config.
+ * Variables cascade (resolveFlowSettings): step > flow > root config.
+ * "step" applies uniformly to source, destination, transformer, and store.
  */
 interface Flow {
     /** Per-flow configuration: platform, url, settings, bundle. */
@@ -672,11 +683,6 @@ interface Flow {
      * Override root variables; overridden by source/destination variables.
      */
     variables?: Flow.Variables;
-    /**
-     * Flow-level definitions.
-     * Extend root definitions; overridden by source/destination definitions.
-     */
-    definitions?: Flow.Definitions;
 }
 declare namespace Flow {
     /**
@@ -721,11 +727,6 @@ declare namespace Flow {
          * Syntax: $var.name
          */
         variables?: Variables;
-        /**
-         * Reusable configuration definitions.
-         * Syntax: $def.name
-         */
-        definitions?: Definitions;
         /**
          * Data contract definition.
          * Entity → action keyed JSON Schema with additive inheritance.
@@ -765,23 +766,17 @@ declare namespace Flow {
          */
         settings?: Settings;
         /**
-         * Bundle configuration: NPM packages to include, transitive dependency overrides.
+         * Bundle configuration: NPM packages to include, transitive dependency
+         * overrides, and extra trace includes for server bundles.
          * Consumed by the CLI bundler at build time.
          */
         bundle?: Bundle;
     }
-    /** Primitive value types for variables. */
-    type Primitive = string | number | boolean;
     /**
-     * Variables record type for interpolation.
-     * Used at root, flow, source, destination, transformer, and store levels.
+     * Reusable values referenced via `$var.name` (with optional deep paths).
+     * Whole-string references preserve native type; inline interpolation requires scalars.
      */
-    type Variables = Record<string, Primitive>;
-    /**
-     * Definitions record type for reusable configurations.
-     * Used at root, flow, source, destination, transformer, and store levels.
-     */
-    type Definitions = Record<string, unknown>;
+    type Variables = Record<string, unknown>;
     /**
      * Free-form settings bag inside `Flow.Config.settings`.
      * Mirrors the package settings convention (arbitrary keys).
@@ -790,8 +785,12 @@ declare namespace Flow {
     /**
      * Bundle configuration for a flow.
      *
-     * Groups all build-time bundling concerns: NPM packages to include and
-     * transitive dependency overrides. Consumed by the CLI bundler.
+     * Groups all build-time bundling concerns: NPM packages to include,
+     * transitive dependency overrides, and extra trace includes (server only).
+     * Consumed by the CLI bundler.
+     *
+     * The `flow.config.bundle.external` sub-field is no longer supported
+     * (replaced by nft tracing in @walkeros/cli@4.x).
      */
     interface Bundle {
         /** NPM packages to bundle, keyed by package name. */
@@ -799,7 +798,7 @@ declare namespace Flow {
         /**
          * Transitive dependency version pins.
          *
-         * Maps package name → version spec. Applied during bundle package install
+         * Maps package name to version spec. Applied during bundle package install
          * to force transitive dependencies to a specific version. Useful for
          * resolving conflicts between packages that depend on incompatible
          * versions of a shared dependency.
@@ -812,6 +811,17 @@ declare namespace Flow {
          * ```
          */
         overrides?: Record<string, string>;
+        /**
+         * Extra paths the bundler must include in the trace output.
+         *
+         * Each entry is either a literal path or a glob (matched via picomatch),
+         * resolved against the bundler's install root. Use as an escape hatch
+         * when the file tracer cannot statically discover an asset (e.g.,
+         * dynamic require, runtime configuration files).
+         *
+         * Server flows only.
+         */
+        traceInclude?: string[];
     }
     /**
      * Single bundle package entry.
@@ -907,11 +917,6 @@ declare namespace Flow {
          * Overrides flow and root variables.
          */
         variables?: Variables;
-        /**
-         * Source-level definitions (highest priority in cascade).
-         * Overrides flow and root definitions.
-         */
-        definitions?: Definitions;
         /**
          * Named examples for testing and documentation.
          * Stripped during flow resolution (not included in bundles).
@@ -959,8 +964,6 @@ declare namespace Flow {
         cache?: Cache;
         /** Destination-level variables (highest priority in cascade). */
         variables?: Variables;
-        /** Destination-level definitions (highest priority in cascade). */
-        definitions?: Definitions;
         /**
          * Named examples for testing and documentation.
          * Stripped during flow resolution.
@@ -1005,8 +1008,6 @@ declare namespace Flow {
         cache?: Cache;
         /** Transformer-level variables (highest priority in cascade). */
         variables?: Variables;
-        /** Transformer-level definitions (highest priority in cascade). */
-        definitions?: Definitions;
         /**
          * Named examples for testing and documentation.
          * Stripped during flow resolution.
@@ -1031,8 +1032,6 @@ declare namespace Flow {
         env?: unknown;
         /** Store-level variables (highest priority in cascade). */
         variables?: Variables;
-        /** Store-level definitions (highest priority in cascade). */
-        definitions?: Definitions;
         /**
          * Named examples for testing and documentation.
          * Stripped during flow resolution.
@@ -1595,20 +1594,22 @@ interface BaseEnv$1 {
 }
 /**
  * Type bundle for source generics.
- * Groups Settings, Mapping, Push, Env, and InitSettings into a single type parameter.
+ * Groups Settings, Mapping, Push, Env, InitSettings, and Setup into a single type parameter.
  *
  * @template S - Settings configuration type
  * @template M - Mapping configuration type
  * @template P - Push function signature (flexible to support HTTP handlers, etc.)
  * @template E - Environment dependencies type
  * @template I - InitSettings configuration type (user input)
+ * @template U - Setup options type (provisioning options for `walker setup`)
  */
-interface Types$1<S = unknown, M = unknown, P = Fn$3, E = BaseEnv$1, I = S> {
+interface Types$1<S = unknown, M = unknown, P = Fn$3, E = BaseEnv$1, I = S, U = unknown> {
     settings: S;
     initSettings: I;
     mapping: M;
     push: P;
     env: E;
+    setup: U;
 }
 /**
  * Generic constraint for Types - ensures T has required properties for indexed access
@@ -1619,6 +1620,7 @@ type TypesGeneric$1 = {
     mapping: any;
     push: any;
     env: any;
+    setup: any;
 };
 /**
  * Type extractors for consistent usage with Types bundle
@@ -1628,6 +1630,7 @@ type InitSettings$1<T extends TypesGeneric$1 = Types$1> = T['initSettings'];
 type Mapping<T extends TypesGeneric$1 = Types$1> = T['mapping'];
 type Push<T extends TypesGeneric$1 = Types$1> = T['push'];
 type Env$1<T extends TypesGeneric$1 = Types$1> = T['env'];
+type SetupOptions$1<T extends TypesGeneric$1 = Types$1> = T['setup'];
 /**
  * Inference helper: Extract Types from Instance
  */
@@ -1645,6 +1648,11 @@ interface Config$1<T extends TypesGeneric$1 = Types$1> extends Config$7<Mapping<
     primary?: boolean;
     /** Defer source initialization until these collector events fire (e.g., `['consent']`). */
     require?: string[];
+    /**
+     * Provisioning options for `walker setup`. `boolean | object`.
+     * Triggered only by explicit CLI invocation; never automatic.
+     */
+    setup?: boolean | SetupOptions$1<T>;
     /**
      * Ingest metadata extraction mapping.
      * Extracts values from raw request objects (Express req, Lambda event, etc.)
@@ -1660,14 +1668,39 @@ interface Config$1<T extends TypesGeneric$1 = Types$1> extends Config$7<Mapping<
     ingest?: Data$1;
     /** Completely skip this source — no init, no event capture. */
     disabled?: boolean;
+    /**
+     * Init lifecycle flag. Set by the collector to `true` after `Instance.init()`
+     * has been called. Used together with `require` to gate `on()` delivery:
+     * lifecycle events are queued in `Instance.queueOn` until both
+     * `config.init === true` and `config.require` is empty/absent, then replayed.
+     */
+    init?: boolean;
 }
-type PartialConfig<T extends TypesGeneric$1 = Types$1> = Config$1<Types$1<Partial<Settings$1<T>> | Settings$1<T>, Partial<Mapping<T>> | Mapping<T>, Push<T>, Env$1<T>>>;
+type PartialConfig$1<T extends TypesGeneric$1 = Types$1> = Config$1<Types$1<Partial<Settings$1<T>> | Settings$1<T>, Partial<Mapping<T>> | Mapping<T>, Push<T>, Env$1<T>, InitSettings$1<T>, SetupOptions$1<T>>>;
 interface Instance$2<T extends TypesGeneric$1 = Types$1> {
     type: string;
     config: Config$1<T>;
+    setup?: SetupFn<Config$1<T>, Env$1<T>>;
     push: Push<T>;
     destroy?: DestroyFn<Config$1<T>, Env$1<T>>;
     on?(event: Types$3, context?: unknown): void | boolean | Promise<void | boolean>;
+    /**
+     * Optional setup hook. Called by the collector eagerly after all source
+     * factories have run, regardless of `config.require`. Use for prep work
+     * such as draining a pre-init window queue or attaching DOM listeners.
+     * The collector still gates `on()` delivery, and `Collector.push`
+     * enforces `allowed`/consent at the destination layer.
+     */
+    init?: () => void | Promise<void>;
+    /**
+     * Lifecycle event queue. Populated by `onApply` when the source is not
+     * yet started (`config.init !== true` or `config.require` non-empty).
+     * Flushed by the collector when the source becomes started.
+     */
+    queueOn?: Array<{
+        type: Types$3;
+        data: unknown;
+    }>;
 }
 /**
  * Context provided to source init function.
@@ -1713,36 +1746,44 @@ type Renderer = 'browser' | 'codebox';
 type source_InitSource<T extends TypesGeneric$1 = Types$1> = InitSource<T>;
 type source_InitSources = InitSources;
 type source_Mapping<T extends TypesGeneric$1 = Types$1> = Mapping<T>;
-type source_PartialConfig<T extends TypesGeneric$1 = Types$1> = PartialConfig<T>;
 type source_Push<T extends TypesGeneric$1 = Types$1> = Push<T>;
 type source_Renderer = Renderer;
 declare namespace source {
-  export type { BaseEnv$1 as BaseEnv, Config$1 as Config, Context$1 as Context, Env$1 as Env, Init$1 as Init, InitSettings$1 as InitSettings, source_InitSource as InitSource, source_InitSources as InitSources, Instance$2 as Instance, source_Mapping as Mapping, source_PartialConfig as PartialConfig, source_Push as Push, source_Renderer as Renderer, Settings$1 as Settings, Types$1 as Types, TypesGeneric$1 as TypesGeneric, TypesOf$1 as TypesOf };
+  export type { BaseEnv$1 as BaseEnv, Config$1 as Config, Context$1 as Context, Env$1 as Env, Init$1 as Init, InitSettings$1 as InitSettings, source_InitSource as InitSource, source_InitSources as InitSources, Instance$2 as Instance, source_Mapping as Mapping, PartialConfig$1 as PartialConfig, source_Push as Push, source_Renderer as Renderer, Settings$1 as Settings, SetupOptions$1 as SetupOptions, Types$1 as Types, TypesGeneric$1 as TypesGeneric, TypesOf$1 as TypesOf };
 }
 
 interface BaseEnv {
     [key: string]: unknown;
 }
-interface Types<S = unknown, E = BaseEnv, I = S> {
+interface Types<S = unknown, E = BaseEnv, I = S, U = unknown> {
     settings: S;
     initSettings: I;
     env: E;
+    setup: U;
 }
 type TypesGeneric = {
     settings: any;
     initSettings: any;
     env: any;
+    setup: any;
 };
 type Settings<T extends TypesGeneric = Types> = T['settings'];
 type InitSettings<T extends TypesGeneric = Types> = T['initSettings'];
 type Env<T extends TypesGeneric = Types> = T['env'];
+type SetupOptions<T extends TypesGeneric = Types> = T['setup'];
 type TypesOf<I> = I extends Instance$1<infer T> ? T : never;
 interface Config<T extends TypesGeneric = Types> {
     settings?: InitSettings<T>;
     env?: Env<T>;
     id?: string;
     logger?: Config$4;
+    /**
+     * Provisioning options for `walker setup`. `boolean | object`.
+     * Triggered only by explicit CLI invocation; never automatic.
+     */
+    setup?: boolean | SetupOptions<T>;
 }
+type PartialConfig<T extends TypesGeneric = Types> = Config<Types<Partial<Settings<T>> | Settings<T>, Env<T>, InitSettings<T>, SetupOptions<T>>>;
 interface Context<T extends TypesGeneric = Types> extends Base<Config<T>, Env<T>> {
     id: string;
 }
@@ -1755,6 +1796,7 @@ interface Instance$1<T extends TypesGeneric = Types> {
     get: GetFn;
     set: SetFn;
     delete: DeleteFn;
+    setup?: SetupFn<Config<T>, Env<T>>;
     destroy?: DestroyFn<Config<T>, Env<T>>;
 }
 type Init<T extends TypesGeneric = Types> = (context: Context<Types<Partial<Settings<T>>, Env<T>, InitSettings<T>>>) => Instance$1<T> | Promise<Instance$1<T>>;
@@ -1782,14 +1824,16 @@ type store_InitFn<T extends TypesGeneric = Types> = InitFn<T>;
 type store_InitSettings<T extends TypesGeneric = Types> = InitSettings<T>;
 type store_InitStore<T extends TypesGeneric = Types> = InitStore<T>;
 type store_InitStores = InitStores;
+type store_PartialConfig<T extends TypesGeneric = Types> = PartialConfig<T>;
 type store_SetFn<T = unknown> = SetFn<T>;
 type store_Settings<T extends TypesGeneric = Types> = Settings<T>;
+type store_SetupOptions<T extends TypesGeneric = Types> = SetupOptions<T>;
 type store_Stores = Stores;
-type store_Types<S = unknown, E = BaseEnv, I = S> = Types<S, E, I>;
+type store_Types<S = unknown, E = BaseEnv, I = S, U = unknown> = Types<S, E, I, U>;
 type store_TypesGeneric = TypesGeneric;
 type store_TypesOf<I> = TypesOf<I>;
 declare namespace store {
-  export type { store_BaseEnv as BaseEnv, store_Config as Config, store_Context as Context, store_DeleteFn as DeleteFn, store_Env as Env, store_GetFn as GetFn, store_Init as Init, store_InitFn as InitFn, store_InitSettings as InitSettings, store_InitStore as InitStore, store_InitStores as InitStores, Instance$1 as Instance, store_SetFn as SetFn, store_Settings as Settings, store_Stores as Stores, store_Types as Types, store_TypesGeneric as TypesGeneric, store_TypesOf as TypesOf };
+  export type { store_BaseEnv as BaseEnv, store_Config as Config, store_Context as Context, store_DeleteFn as DeleteFn, store_Env as Env, store_GetFn as GetFn, store_Init as Init, store_InitFn as InitFn, store_InitSettings as InitSettings, store_InitStore as InitStore, store_InitStores as InitStores, Instance$1 as Instance, store_PartialConfig as PartialConfig, store_SetFn as SetFn, store_Settings as Settings, store_SetupOptions as SetupOptions, store_Stores as Stores, store_Types as Types, store_TypesGeneric as TypesGeneric, store_TypesOf as TypesOf };
 }
 
 /**
@@ -2133,9 +2177,9 @@ declare function walkPath(value: unknown, path: string, refPrefix: string): unkn
  * Resolver callback for `$flow.X.Y` references.
  *
  * Given a sibling flow name, returns its fully resolved `Flow.Config` block
- * (with `$env`/`$var`/`$def`/`$contract` already resolved) as `unknown` so
- * that {@link walkPath} can traverse it. Returns `undefined` if the flow
- * does not exist. Implementations are responsible for cycle detection across
+ * (with `$env`/`$var`/`$contract` already resolved) as `unknown` so that
+ * {@link walkPath} can traverse it. Returns `undefined` if the flow does
+ * not exist. Implementations are responsible for cycle detection across
  * recursive calls.
  */
 type FlowConfigResolver = (flowName: string) => unknown;
@@ -2152,20 +2196,22 @@ declare function packageNameToVariable(packageName: string): string;
  *
  * Resolution pass order:
  * 1. `$env` / `$var` resolve per-flow in isolation (no cross-flow context).
+ *    `$var` resolves recursively (variables may reference other variables,
+ *    `$env`, `$contract`, or `$flow`); cycles are detected via a visiting set.
  * 2. `$flow.X.Y` resolves against pass-1 outputs of sibling flows (so `$env`/`$var`
  *    inside the referenced flow are already resolved when `$flow` reads it).
- * 3. `$def` / `$contract` resolve last (with `$flow` results available).
+ * 3. `$contract` resolves last (with `$flow` results available).
  *
  * In practice these passes are interleaved by the resolver: when `$flow.X.Y`
  * is encountered, the sibling flow X's `Flow.Config` block is recursively
- * resolved on demand (with all its own `$env`/`$var`/`$def`/`$contract`
- * references resolved first), then the deep path is walked. Cycles are
- * detected via a visiting set.
+ * resolved on demand (with all its own `$env`/`$var`/`$contract` references
+ * resolved first), then the deep path is walked. Cycles are detected via a
+ * visiting set.
  *
  * @param config - The complete Flow.Json (root multi-flow config)
  * @param flowName - Flow name (auto-selected if only one exists)
  * @param options - Resolution options
- * @returns Resolved {@link Flow} with $var, $env, $def, $contract, and $flow patterns resolved
+ * @returns Resolved {@link Flow} with $var, $env, $contract, and $flow patterns resolved
  * @throws Error if flow selection is required but not specified, or flow not found
  * @throws Error if a `$flow.X.Y` reference forms a cycle
  *
@@ -2736,6 +2782,15 @@ declare function transformData(data?: SendDataValue): string | undefined;
  */
 declare function getHeaders(headers?: SendHeaders): SendHeaders;
 
+/**
+ * Normalize `config.setup` into a concrete options object, or null when disabled.
+ *
+ * - `false` / `undefined` → null (no setup)
+ * - `true` → `defaults` as-is
+ * - object → shallow merge of defaults and overrides (overrides win)
+ */
+declare function resolveSetup<T extends object>(value: boolean | T | undefined, defaults: T): T | null;
+
 /**
  * Throws an error.
  *
@@ -3046,8 +3101,8 @@ declare function formatOut(out: StepOut): string;
  * app secrets service, explorer IntelliSense) imports these — no
  * inline regexes elsewhere.
  */
-declare const REF_VAR: RegExp;
-declare const REF_DEF: RegExp;
+declare const REF_VAR_FULL: RegExp;
+declare const REF_VAR_INLINE: RegExp;
 declare const REF_ENV: RegExp;
 declare const REF_CONTRACT: RegExp;
 /** Whole-string `$flow.<name>(.<path>)?`: cross-flow value reference. */
@@ -3056,4 +3111,4 @@ declare const REF_STORE: RegExp;
 declare const REF_SECRET: RegExp;
 declare const REF_CODE_PREFIX = "$code:";
 
-export { cache as Cache, type CacheResult, type ClickIdEntry, collector as Collector, type CompiledCache, type CompiledNext, type CompiledRoute, Const, context as Context, destination as Destination, ENV_MARKER_PREFIX, elb as Elb, type ExampleSummary, Flow, type FlowConfigResolver, hint as Hint, hooks as Hooks, type Ingest, type IngestMeta, Level, lifecycle as Lifecycle, logger as Logger, mapping as Mapping, type MarketingParameters, matcher as Matcher, type MockLogger, on as On, REF_CODE_PREFIX, REF_CONTRACT, REF_DEF, REF_ENV, REF_FLOW, REF_SECRET, REF_STORE, REF_VAR, request as Request, type ResolveOptions, type RespondFn, type RespondOptions, type SendDataValue, type SendHeaders, type SendResponse, simulation as Simulation, source as Source, type StorageType, store as Store, transformer as Transformer, trigger as Trigger, walkeros as WalkerOS, type WalkerOSPackage, type WalkerOSPackageInfo, type WalkerOSPackageMeta, anonymizeIP, applyUpdate, assign, branch, buildCacheContext, castToProperty, castValue, checkCache, clone, compileCache, compileMatcher, compileNext, createDestination, createEvent, createIngest, createLogger, createMockContext, createMockLogger, createRespond, debounce, deepMerge, defaultClickIds, fetchPackage, fetchPackageSchema, filterValues, flattenIncludeSections, formatOut, getBrowser, getBrowserVersion, getByPath, getDeviceType, getEvent, getFlowSettings, getGrantedConsent, getHeaders, getId, getMappingEvent, getMappingValue, getMarketingParameters, getOS, getOSVersion, getPlatform, getSpanId, isArguments, isArray, isBoolean, isCommand, isDefined, isElementOrDocument, isFunction, isNumber, isObject, isPropertyType, isRouteArray, isSameType, isString, mcpError, mcpResult, mergeContractSchemas, mockEnv, packageNameToVariable, parseUserAgent, processEventMapping, requestToData, requestToParameter, resolveContracts, resolveNext, setByPath, storeCache, throttle, throwError, transformData, traverseEnv, trim, tryCatch, tryCatchAsync, useHooks, walkPath, wrapCondition, wrapFn, wrapValidate };
+export { cache as Cache, type CacheResult, type ClickIdEntry, collector as Collector, type CompiledCache, type CompiledNext, type CompiledRoute, Const, context as Context, destination as Destination, type DestroyContext, type DestroyFn, ENV_MARKER_PREFIX, elb as Elb, type ExampleSummary, Flow, type FlowConfigResolver, hint as Hint, hooks as Hooks, type Ingest, type IngestMeta, Level, lifecycle as Lifecycle, type LifecycleContext, logger as Logger, mapping as Mapping, type MarketingParameters, matcher as Matcher, type MockLogger, on as On, REF_CODE_PREFIX, REF_CONTRACT, REF_ENV, REF_FLOW, REF_SECRET, REF_STORE, REF_VAR_FULL, REF_VAR_INLINE, request as Request, type ResolveOptions, type RespondFn, type RespondOptions, type SendDataValue, type SendHeaders, type SendResponse, type SetupFn, simulation as Simulation, source as Source, type StorageType, store as Store, transformer as Transformer, trigger as Trigger, walkeros as WalkerOS, type WalkerOSPackage, type WalkerOSPackageInfo, type WalkerOSPackageMeta, anonymizeIP, applyUpdate, assign, branch, buildCacheContext, castToProperty, castValue, checkCache, clone, compileCache, compileMatcher, compileNext, createDestination, createEvent, createIngest, createLogger, createMockContext, createMockLogger, createRespond, debounce, deepMerge, defaultClickIds, fetchPackage, fetchPackageSchema, filterValues, flattenIncludeSections, formatOut, getBrowser, getBrowserVersion, getByPath, getDeviceType, getEvent, getFlowSettings, getGrantedConsent, getHeaders, getId, getMappingEvent, getMappingValue, getMarketingParameters, getOS, getOSVersion, getPlatform, getSpanId, isArguments, isArray, isBoolean, isCommand, isDefined, isElementOrDocument, isFunction, isNumber, isObject, isPropertyType, isRouteArray, isSameType, isString, mcpError, mcpResult, mergeContractSchemas, mockEnv, packageNameToVariable, parseUserAgent, processEventMapping, requestToData, requestToParameter, resolveContracts, resolveNext, resolveSetup, setByPath, storeCache, throttle, throwError, transformData, traverseEnv, trim, tryCatch, tryCatchAsync, useHooks, walkPath, wrapCondition, wrapFn, wrapValidate };