@walkeros/core 2.0.1 → 2.1.1

package/dist/index.d.mts

@@ -1,3 +1,30 @@
+/**
+ * Options for responding to an HTTP request.
+ * Same interface for web and server — sources implement the handler.
+ */
+interface RespondOptions {
+    /** Response body. Objects are JSON-serialized by source. */
+    body?: unknown;
+    /** HTTP status code (default: 200). Server-only, ignored by web sources. */
+    status?: number;
+    /** HTTP response headers. Server-only, ignored by web sources. */
+    headers?: Record<string, string>;
+}
+/**
+ * Standardized response function available on env for every step.
+ * Idempotent: first call wins, subsequent calls are no-ops.
+ * Created by sources via createRespond(), consumed by any step.
+ */
+type RespondFn = (options?: RespondOptions) => void;
+/**
+ * Creates an idempotent respond function.
+ * The sender callback is source-specific (Express wraps res, Fetch wraps Response, etc.).
+ *
+ * @param sender - Platform-specific function that actually sends the response
+ * @returns Idempotent respond function (first call wins)
+ */
+declare function createRespond(sender: (options: RespondOptions) => void): RespondFn;
+
 /**
  * Core collector configuration interface
  */
@@ -80,6 +107,7 @@ type CommandType = 'action' | 'config' | 'consent' | 'context' | 'destination' |
 interface PushOptions {
     id?: string;
     ingest?: unknown;
+    respond?: RespondFn;
     mapping?: Config$3;
     preChain?: string[];
 }
@@ -180,15 +208,15 @@ interface Contexts {
 interface Entities$1 {
     [name: string]: Entity$1;
 }
-interface Properties$2 {
-    [name: string]: Property$2;
+interface Properties$1 {
+    [name: string]: Property$1;
 }
-interface Global extends Property$2 {
+interface Global extends Property$1 {
 }
-interface Context$5 extends Property$2 {
+interface Context$5 extends Property$1 {
 }
 interface Entity$1 {
-    data: Properties$2;
+    data: Properties$1;
     actions: Actions;
 }
 interface Actions {
@@ -198,7 +226,7 @@ interface Action {
     trigger?: Trigger;
 }
 type Trigger = string;
-interface Property$2 {
+interface Property$1 {
     type?: PropertyType$1;
     required?: boolean;
     values?: PropertyValues;
@@ -214,7 +242,38 @@ type data_Globals = Globals;
 type data_PropertyValues = PropertyValues;
 type data_Trigger = Trigger;
 declare namespace data {
-  export type { data_Action as Action, data_Actions as Actions, Context$5 as Context, data_Contexts as Contexts, Contract$1 as Contract, Entities$1 as Entities, Entity$1 as Entity, data_Global as Global, data_Globals as Globals, Properties$2 as Properties, Property$2 as Property, PropertyType$1 as PropertyType, data_PropertyValues as PropertyValues, data_Trigger as Trigger };
+  export type { data_Action as Action, data_Actions as Actions, Context$5 as Context, data_Contexts as Contexts, Contract$1 as Contract, Entities$1 as Entities, Entity$1 as Entity, data_Global as Global, data_Globals as Globals, Properties$1 as Properties, Property$1 as Property, PropertyType$1 as PropertyType, data_PropertyValues as PropertyValues, data_Trigger as Trigger };
+}
+
+/**
+ * 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.
+ */
+interface DestroyContext<C = unknown, E = unknown> {
+    /** Step instance ID. */
+    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$2;
+}
+/**
+ * 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 lifecycle_DestroyContext<C = unknown, E = unknown> = DestroyContext<C, E>;
+type lifecycle_DestroyFn<C = unknown, E = unknown> = DestroyFn<C, E>;
+declare namespace lifecycle {
+  export type { lifecycle_DestroyContext as DestroyContext, lifecycle_DestroyFn as DestroyFn };
 }
 
 /**
@@ -276,6 +335,7 @@ interface Instance$3<T extends TypesGeneric$2 = Types$3> {
     push: PushFn<T>;
     pushBatch?: PushBatchFn<T>;
     on?: OnFn;
+    destroy?: DestroyFn<Config$6<T>, Env$2<T>>;
 }
 interface Config$6<T extends TypesGeneric$2 = Types$3> {
     /** Required consent states to push events; queues events when not granted. */
@@ -439,9 +499,54 @@ declare namespace elb {
  * (web_prod, web_stage, server_prod, etc.) with shared configuration,
  * variables, and reusable definitions.
  *
+ * ## Connection Rules
+ *
+ * Sources use `next` to connect to transformers (pre-collector chain).
+ * Sources cannot have `before`.
+ *
+ * Destinations use `before` to connect to transformers (post-collector chain).
+ * Destinations cannot have `next`.
+ *
+ * Transformers use `next` to chain to other transformers. The same transformer
+ * pool is shared by both pre-collector and post-collector chains.
+ *
+ * The collector is implicit — it is never referenced directly in connections.
+ * It sits between the source chain and the destination chain automatically.
+ *
+ * Circular `next` references are safely handled at runtime by `walkChain()`
+ * in the collector module (visited-set detection).
+ *
+ * ```
+ * Source → [next → Transformer chain] → Collector → [before → Transformer chain] → Destination
+ * ```
+ *
  * @packageDocumentation
  */
 
+/**
+ * JSON Schema object for contract entry validation.
+ * Standard JSON Schema with description/examples annotations.
+ * Compatible with AJV for runtime validation.
+ */
+type ContractSchema = Record<string, unknown>;
+/**
+ * Contract action entries keyed by action name.
+ * Each value is a JSON Schema describing the expected WalkerOS.Event shape.
+ * Use "*" as wildcard for all actions of an entity.
+ */
+type ContractActions = Record<string, ContractSchema>;
+/**
+ * Data contract definition.
+ * Entity → action keyed JSON Schema with additive inheritance.
+ *
+ * Special keys:
+ * - "$tagging": Contract version number (syncs to event.version.tagging)
+ * - "*": Wildcard entity/action (matches all)
+ */
+interface Contract {
+    $tagging?: number;
+    [entity: string]: ContractActions | number | undefined;
+}
 /**
  * Primitive value types for variables
  */
@@ -526,7 +631,7 @@ interface Setup {
     /**
      * Configuration schema version.
      */
-    version: 1;
+    version: 1 | 2;
     /**
      * JSON Schema reference for IDE validation.
      * @example "https://walkeros.io/schema/flow/v1.json"
@@ -550,6 +655,11 @@ interface Setup {
      * ```
      */
     include?: string[];
+    /**
+     * Data contract definition (version 2+).
+     * Entity → action keyed JSON Schema with additive inheritance.
+     */
+    contract?: Contract;
     /**
      * Shared variables for interpolation.
      * Resolution: destination/source > Config > Setup level
@@ -590,6 +700,11 @@ interface Config$5 {
      * Mutually exclusive with `web`.
      */
     server?: Server;
+    /**
+     * Data contract definition for this flow.
+     * Merges on top of Setup-level contract (additive).
+     */
+    contract?: Contract;
     /**
      * Source configurations (data capture).
      *
@@ -726,6 +841,20 @@ interface Config$5 {
      */
     definitions?: Definitions;
 }
+/**
+ * Named example pair for a step.
+ * `in` is the input to the step, `out` is the expected output.
+ * `out: false` indicates the step filters/drops this event.
+ */
+interface StepExample {
+    in?: unknown;
+    mapping?: unknown;
+    out?: unknown;
+}
+/**
+ * Named step examples keyed by scenario name.
+ */
+type StepExamples = Record<string, StepExample>;
 /**
  * Source reference with inline package syntax.
  *
@@ -825,14 +954,20 @@ interface SourceReference {
      */
     definitions?: Definitions;
     /**
-     * First transformer in post-source chain.
+     * First transformer in pre-collector chain.
      *
      * @remarks
      * Name of the transformer to execute after this source captures an event.
+     * Creates a pre-collector transformer chain. Chain ends at the collector.
      * If omitted, events route directly to the collector.
      * Can be an array for explicit chain control (bypasses transformer.next resolution).
      */
     next?: string | string[];
+    /**
+     * Named examples for testing and documentation.
+     * Stripped during flow resolution (not included in bundles).
+     */
+    examples?: StepExamples;
 }
 /**
  * Transformer reference with inline package syntax.
@@ -893,10 +1028,11 @@ interface TransformerReference {
      *
      * @remarks
      * Name of the next transformer to execute after this one.
-     * If omitted:
-     * - Pre-collector: routes to collector
-     * - Post-collector: routes to destination
-     * Can be an array for explicit chain control (terminates chain walking).
+     * When used in a pre-collector chain (source.next), terminates at the collector.
+     * When used in a post-collector chain (destination.before), terminates at the destination.
+     * If omitted, the chain ends and control passes to the next pipeline stage.
+     * Array values define an explicit chain (no walking). Circular references
+     * are safely detected at runtime by `walkChain()`.
      */
     next?: string | string[];
     /**
@@ -909,6 +1045,11 @@ interface TransformerReference {
      * Overrides flow and setup definitions.
      */
     definitions?: Definitions;
+    /**
+     * Named examples for testing and documentation.
+     * Stripped during flow resolution (not included in bundles).
+     */
+    examples?: StepExamples;
 }
 /**
  * Destination reference with inline package syntax.
@@ -999,16 +1140,25 @@ interface DestinationReference {
      */
     definitions?: Definitions;
     /**
-     * First transformer in pre-destination chain.
+     * First transformer in post-collector chain.
      *
      * @remarks
      * Name of the transformer to execute before sending events to this destination.
+     * Creates a post-collector transformer chain. Chain ends at this destination.
      * If omitted, events are sent directly from the collector.
      * Can be an array for explicit chain control (bypasses transformer.next resolution).
      */
     before?: string | string[];
+    /**
+     * Named examples for testing and documentation.
+     * Stripped during flow resolution (not included in bundles).
+     */
+    examples?: StepExamples;
 }
 
+type flow_Contract = Contract;
+type flow_ContractActions = ContractActions;
+type flow_ContractSchema = ContractSchema;
 type flow_Definitions = Definitions;
 type flow_DestinationReference = DestinationReference;
 type flow_InlineCode = InlineCode;
@@ -1017,11 +1167,13 @@ type flow_Primitive = Primitive;
 type flow_Server = Server;
 type flow_Setup = Setup;
 type flow_SourceReference = SourceReference;
+type flow_StepExample = StepExample;
+type flow_StepExamples = StepExamples;
 type flow_TransformerReference = TransformerReference;
 type flow_Variables = Variables;
 type flow_Web = Web;
 declare namespace flow {
-  export type { Config$5 as Config, flow_Definitions as Definitions, flow_DestinationReference as DestinationReference, flow_InlineCode as InlineCode, flow_Packages as Packages, flow_Primitive as Primitive, flow_Server as Server, flow_Setup as Setup, flow_SourceReference as SourceReference, flow_TransformerReference as TransformerReference, flow_Variables as Variables, flow_Web as Web };
+  export type { Config$5 as Config, flow_Contract as Contract, flow_ContractActions as ContractActions, flow_ContractSchema as ContractSchema, flow_Definitions as Definitions, flow_DestinationReference as DestinationReference, flow_InlineCode as InlineCode, flow_Packages as Packages, flow_Primitive as Primitive, flow_Server as Server, flow_Setup as Setup, flow_SourceReference as SourceReference, flow_StepExample as StepExample, flow_StepExamples as StepExamples, flow_TransformerReference as TransformerReference, flow_Variables as Variables, flow_Web as Web };
 }
 
 type AnyFunction$1<P extends unknown[] = never[], R = unknown> = (...args: P) => R;
@@ -1045,8 +1197,9 @@ declare namespace hooks {
  */
 declare enum Level {
     ERROR = 0,
-    INFO = 1,
-    DEBUG = 2
+    WARN = 1,
+    INFO = 2,
+    DEBUG = 3
 }
 /**
  * Normalized error context extracted from Error objects
@@ -1093,6 +1246,10 @@ interface Instance$2 {
      * Log an error message (always visible unless silenced)
      */
     error: LogFn;
+    /**
+     * Log a warning (degraded state, config issues, transient failures)
+     */
+    warn: LogFn;
     /**
      * Log an informational message
      */
@@ -1106,6 +1263,10 @@ interface Instance$2 {
      * Combines logging and throwing in one call
      */
     throw: ThrowFn;
+    /**
+     * Output structured JSON data
+     */
+    json: (data: unknown) => void;
     /**
      * Create a scoped child logger with automatic trace path
      * @param name - Scope name (e.g., destination type, destination key)
@@ -1127,6 +1288,8 @@ interface Config$4 {
      * Receives originalHandler to preserve default behavior
      */
     handler?: Handler;
+    /** Custom handler for json() output. Default: console.log(JSON.stringify(data, null, 2)) */
+    jsonHandler?: (data: unknown) => void;
 }
 /**
  * Internal config with resolved values and scope
@@ -1134,6 +1297,7 @@ interface Config$4 {
 interface InternalConfig {
     level: Level;
     handler?: Handler;
+    jsonHandler?: (data: unknown) => void;
     scope: string[];
 }
 /**
@@ -1183,7 +1347,7 @@ interface Rule<Settings = unknown> {
     name?: string;
     policy?: Policy;
 }
-interface Result {
+interface Result$2 {
     eventMapping?: Rule;
     mappingKey?: string;
 }
@@ -1220,7 +1384,6 @@ type mapping_Data = Data;
 type mapping_Loop = Loop;
 type mapping_Map = Map;
 type mapping_Policy = Policy;
-type mapping_Result = Result;
 type mapping_Rule<Settings = unknown> = Rule<Settings>;
 type mapping_Rules<T = Rule> = Rules<T>;
 type mapping_Validate = Validate;
@@ -1229,7 +1392,7 @@ type mapping_ValueConfig = ValueConfig;
 type mapping_ValueType = ValueType;
 type mapping_Values = Values;
 declare namespace mapping {
-  export type { mapping_Condition as Condition, Config$3 as Config, mapping_Data as Data, Fn$1 as Fn, mapping_Loop as Loop, mapping_Map as Map, Options$1 as Options, mapping_Policy as Policy, mapping_Result as Result, mapping_Rule as Rule, mapping_Rules as Rules, mapping_Validate as Validate, mapping_Value as Value, mapping_ValueConfig as ValueConfig, mapping_ValueType as ValueType, mapping_Values as Values };
+  export type { mapping_Condition as Condition, Config$3 as Config, mapping_Data as Data, Fn$1 as Fn, mapping_Loop as Loop, mapping_Map as Map, Options$1 as Options, mapping_Policy as Policy, Result$2 as Result, mapping_Rule as Rule, mapping_Rules as Rules, mapping_Validate as Validate, mapping_Value as Value, mapping_ValueConfig as ValueConfig, mapping_ValueType as ValueType, mapping_Values as Values };
 }
 
 type Config$2 = {
@@ -1373,18 +1536,17 @@ interface Context$2<T extends TypesGeneric$1 = Types$1> extends Base<Config$1<T>
     ingest?: unknown;
 }
 /**
- * Branch result for dynamic chain routing.
- * Returned by transformers (e.g., router) to redirect the chain.
- * The chain runner resolves `next` via walkChain() — same semantics
- * as source.next or transformer.config.next.
+ * Unified result type for transformer functions.
+ * Replaces the old union return type with a structured object.
  *
- * IMPORTANT: Always use the `branch()` factory function to create BranchResult.
- * The `__branch` discriminant is required for reliable type detection.
+ * @field event - Modified event to continue with
+ * @field respond - Wrapped respond function for downstream transformers
+ * @field next - Branch to a different chain (replaces BranchResult)
  */
-interface BranchResult {
-    readonly __branch: true;
-    event: DeepPartialEvent;
-    next: Next;
+interface Result$1 {
+    event?: DeepPartialEvent;
+    respond?: RespondFn;
+    next?: Next;
 }
 /**
  * The main transformer function.
@@ -1392,11 +1554,11 @@ interface BranchResult {
  *
  * @param event - The event to process
  * @param context - Transformer context with collector, config, env, logger
- * @returns event - continue with modified event
+ * @returns Result - structured result with event, respond, next
  * @returns void - continue with current event unchanged (passthrough)
  * @returns false - stop chain, cancel further processing
  */
-type Fn<T extends TypesGeneric$1 = Types$1> = (event: DeepPartialEvent, context: Context$2<T>) => PromiseOrValue<DeepPartialEvent | false | void | BranchResult>;
+type Fn<T extends TypesGeneric$1 = Types$1> = (event: DeepPartialEvent, context: Context$2<T>) => PromiseOrValue<Result$1 | false | void>;
 /**
  * Optional initialization function.
  * Called once before first push.
@@ -1415,7 +1577,7 @@ interface Instance$1<T extends TypesGeneric$1 = Types$1> {
     config: Config$1<T>;
     push: Fn<T>;
     init?: InitFn<T>;
-    destroy?: () => void | Promise<void>;
+    destroy?: DestroyFn<Config$1<T>, Env$1<T>>;
 }
 /**
  * Transformer initialization function.
@@ -1446,7 +1608,6 @@ interface Transformers {
     [transformerId: string]: Instance$1;
 }
 
-type transformer_BranchResult = BranchResult;
 type transformer_Fn<T extends TypesGeneric$1 = Types$1> = Fn<T>;
 type transformer_InitFn<T extends TypesGeneric$1 = Types$1> = InitFn<T>;
 type transformer_InitTransformer<T extends TypesGeneric$1 = Types$1> = InitTransformer<T>;
@@ -1454,7 +1615,7 @@ type transformer_InitTransformers = InitTransformers;
 type transformer_Next = Next;
 type transformer_Transformers = Transformers;
 declare namespace transformer {
-  export type { BaseEnv$1 as BaseEnv, transformer_BranchResult as BranchResult, Config$1 as Config, Context$2 as Context, Env$1 as Env, transformer_Fn as Fn, Init$1 as Init, transformer_InitFn as InitFn, InitSettings$1 as InitSettings, transformer_InitTransformer as InitTransformer, transformer_InitTransformers as InitTransformers, Instance$1 as Instance, transformer_Next as Next, Settings$1 as Settings, transformer_Transformers as Transformers, Types$1 as Types, TypesGeneric$1 as TypesGeneric, TypesOf$1 as TypesOf };
+  export type { BaseEnv$1 as BaseEnv, Config$1 as Config, Context$2 as Context, Env$1 as Env, transformer_Fn as Fn, Init$1 as Init, transformer_InitFn as InitFn, InitSettings$1 as InitSettings, transformer_InitTransformer as InitTransformer, transformer_InitTransformers as InitTransformers, Instance$1 as Instance, transformer_Next as Next, Result$1 as Result, Settings$1 as Settings, transformer_Transformers as Transformers, Types$1 as Types, TypesGeneric$1 as TypesGeneric, TypesOf$1 as TypesOf };
 }
 
 interface Context$1 {
@@ -1474,34 +1635,6 @@ declare namespace request {
   export type { Context$1 as Context };
 }
 
-type Contracts = Array<Contract>;
-type Contract = {
-    [entity: string]: {
-        [action: string]: Properties$1;
-    };
-};
-type Properties$1 = {
-    [key: string]: Property$1 | undefined;
-};
-type Property$1 = {
-    allowedKeys?: string[];
-    allowedValues?: unknown[];
-    maxLength?: number;
-    max?: number;
-    min?: number;
-    required?: boolean;
-    schema?: Properties$1;
-    strict?: boolean;
-    type?: string;
-    validate?: (value: unknown, key: string, event: AnyObject) => Property;
-};
-
-type schema_Contract = Contract;
-type schema_Contracts = Contracts;
-declare namespace schema {
-  export type { schema_Contract as Contract, schema_Contracts as Contracts, Properties$1 as Properties, Property$1 as Property };
-}
-
 /**
  * Base Env interface for dependency injection into sources.
  *
@@ -1587,7 +1720,7 @@ interface Instance<T extends TypesGeneric = Types> {
     type: string;
     config: Config<T>;
     push: Push<T>;
-    destroy?(): void | Promise<void>;
+    destroy?: DestroyFn<Config<T>, Env<T>>;
     on?(event: Types$2, context?: unknown): void | boolean | Promise<void | boolean>;
 }
 /**
@@ -1604,6 +1737,8 @@ interface Context<T extends TypesGeneric = Types> extends Base<Partial<Config<T>
      * @param value - Raw request object (Express req, Lambda event, etc.)
      */
     setIngest: (value: unknown) => Promise<void>;
+    /** Sets respond function for the current request. Called by source per-request. */
+    setRespond: (fn: RespondFn | undefined) => void;
 }
 type Init<T extends TypesGeneric = Types> = (context: Context<T>) => Instance<T> | Promise<Instance<T>>;
 type InitSource<T extends TypesGeneric = Types> = {
@@ -1620,6 +1755,32 @@ type InitSource<T extends TypesGeneric = Types> = {
 interface InitSources {
     [sourceId: string]: InitSource<any>;
 }
+/**
+ * Renderer hint for source simulation UI.
+ * - 'browser': Source needs a real DOM (iframe with live preview)
+ * - 'codebox': Source uses a JSON/code editor (default)
+ */
+type Renderer = 'browser' | 'codebox';
+/**
+ * Minimal environment contract for source simulation.
+ * Both JSDOM and iframe satisfy this interface.
+ */
+interface SimulationEnv {
+    window: Window & typeof globalThis;
+    document: Document;
+    localStorage: Storage;
+    [key: string]: unknown;
+}
+/**
+ * Setup function for source simulation.
+ * Runs BEFORE startFlow() to prepare the environment
+ * (dataLayer arrays, localStorage, window globals).
+ *
+ * Return void for sources that need no post-init action.
+ * Return a () => void trigger for sources that dispatch
+ * events AFTER startFlow() (e.g., usercentrics CustomEvent).
+ */
+type SetupFn = (input: unknown, env: SimulationEnv) => void | (() => void);
 
 type source_BaseEnv = BaseEnv;
 type source_Config<T extends TypesGeneric = Types> = Config<T>;
@@ -1633,12 +1794,15 @@ type source_Instance<T extends TypesGeneric = Types> = Instance<T>;
 type source_Mapping<T extends TypesGeneric = Types> = Mapping<T>;
 type source_PartialConfig<T extends TypesGeneric = Types> = PartialConfig<T>;
 type source_Push<T extends TypesGeneric = Types> = Push<T>;
+type source_Renderer = Renderer;
 type source_Settings<T extends TypesGeneric = Types> = Settings<T>;
+type source_SetupFn = SetupFn;
+type source_SimulationEnv = SimulationEnv;
 type source_Types<S = unknown, M = unknown, P = Fn$2, E = BaseEnv, I = S> = Types<S, M, P, E, I>;
 type source_TypesGeneric = TypesGeneric;
 type source_TypesOf<I> = TypesOf<I>;
 declare namespace source {
-  export type { source_BaseEnv as BaseEnv, source_Config as Config, source_Context as Context, source_Env as Env, source_Init as Init, source_InitSettings as InitSettings, source_InitSource as InitSource, source_InitSources as InitSources, source_Instance as Instance, source_Mapping as Mapping, source_PartialConfig as PartialConfig, source_Push as Push, source_Settings as Settings, source_Types as Types, source_TypesGeneric as TypesGeneric, source_TypesOf as TypesOf };
+  export type { source_BaseEnv as BaseEnv, source_Config as Config, source_Context as Context, source_Env as Env, source_Init as Init, source_InitSettings as InitSettings, source_InitSource as InitSource, source_InitSources as InitSources, source_Instance as Instance, source_Mapping as Mapping, source_PartialConfig as PartialConfig, source_Push as Push, source_Renderer as Renderer, source_Settings as Settings, source_SetupFn as SetupFn, source_SimulationEnv as SimulationEnv, source_Types as Types, source_TypesGeneric as TypesGeneric, source_TypesOf as TypesOf };
 }
 
 type AnyObject<T = unknown> = Record<string, T>;
@@ -1756,6 +1920,48 @@ declare namespace walkeros {
   export type { walkeros_ActionHandler as ActionHandler, walkeros_AnyFunction as AnyFunction, walkeros_AnyObject as AnyObject, walkeros_Consent as Consent, walkeros_ConsentHandler as ConsentHandler, walkeros_DeepPartial as DeepPartial, walkeros_DeepPartialEvent as DeepPartialEvent, walkeros_Elb as Elb, walkeros_Entities as Entities, walkeros_Entity as Entity, walkeros_Event as Event, walkeros_Events as Events, walkeros_OrderedProperties as OrderedProperties, walkeros_PartialEvent as PartialEvent, walkeros_PromiseOrValue as PromiseOrValue, walkeros_Properties as Properties, walkeros_Property as Property, walkeros_PropertyType as PropertyType, walkeros_SingleOrArray as SingleOrArray, walkeros_Source as Source, walkeros_SourceType as SourceType, walkeros_User as User, walkeros_Version as Version };
 }
 
+/**
+ * A recorded function call made during simulation.
+ * Captures what a destination called on its env (e.g., window.gtag).
+ */
+interface Call {
+    /** Dot-path of the function called: "window.gtag", "dataLayer.push" */
+    fn: string;
+    /** Arguments passed to the function */
+    args: unknown[];
+    /** Unix timestamp in ms */
+    ts: number;
+}
+/**
+ * Result of simulating a single step.
+ * Same shape for source, transformer, and destination.
+ */
+interface Result {
+    /** Which step type was simulated */
+    step: 'source' | 'transformer' | 'destination';
+    /** Step name, e.g. "gtag", "dataLayer", "enricher" */
+    name: string;
+    /**
+     * Output events:
+     * - source: captured pre-collector events
+     * - transformer: [transformed event] or [] if filtered
+     * - destination: [] (destinations don't produce events)
+     */
+    events: DeepPartialEvent[];
+    /** Intercepted env calls. Populated for destinations, empty [] for others. */
+    calls: Call[];
+    /** Execution time in ms */
+    duration: number;
+    /** Error if the step threw */
+    error?: Error;
+}
+
+type simulation_Call = Call;
+type simulation_Result = Result;
+declare namespace simulation {
+  export type { simulation_Call as Call, simulation_Result as Result };
+}
+
 type StorageType = 'local' | 'session' | 'cookie';
 declare const Const: {
     readonly Utils: {
@@ -1778,10 +1984,10 @@ interface SendResponse {
 }
 
 /**
- * Creates a BranchResult for dynamic chain routing.
+ * Creates a TransformerResult for dynamic chain routing.
  * Use this in transformer push functions to redirect the chain.
  */
-declare function branch(event: DeepPartialEvent, next: Next): BranchResult;
+declare function branch(event: DeepPartialEvent, next: Next): Result$1;
 
 /**
  * Anonymizes an IPv4 address by setting the last octet to 0.
@@ -1799,6 +2005,11 @@ declare function anonymizeIP(ip: string): string;
  * @packageDocumentation
  */
 
+/** Sentinel prefix for deferred $env resolution. Shared with CLI bundler. */
+declare const ENV_MARKER_PREFIX = "__WALKEROS_ENV:";
+interface ResolveOptions {
+    deferred?: boolean;
+}
 /**
  * Convert package name to valid JavaScript variable name.
  * Used for deterministic default import naming.
@@ -1828,7 +2039,7 @@ declare function packageNameToVariable(packageName: string): string;
  * const prodConfig = getFlowConfig(setup, 'production');
  * ```
  */
-declare function getFlowConfig(setup: Setup, flowName?: string): Config$5;
+declare function getFlowConfig(setup: Setup, flowName?: string, options?: ResolveOptions): Config$5;
 /**
  * Get platform from config (web or server).
  *
@@ -2111,7 +2322,7 @@ declare function createLogger(config?: Config$4): Instance$2;
  * @param mapping The mapping rules.
  * @returns The mapping result.
  */
-declare function getMappingEvent(event: DeepPartialEvent | PartialEvent | Event, mapping?: Rules): Promise<Result>;
+declare function getMappingEvent(event: DeepPartialEvent | PartialEvent | Event, mapping?: Rules): Promise<Result$2>;
 /**
  * Gets a value from a mapping.
  *
@@ -2221,9 +2432,11 @@ declare function traverseEnv<T extends object>(env: T, replacer: (value: unknown
  */
 interface MockLogger extends Instance$2 {
     error: jest.Mock;
+    warn: jest.Mock;
     info: jest.Mock;
     debug: jest.Mock;
     throw: jest.Mock<never, [string | Error, unknown?]>;
+    json: jest.Mock;
     scope: jest.Mock<MockLogger, [string]>;
     /**
      * Array of all scoped loggers created by this logger
@@ -2396,25 +2609,6 @@ declare function getOSVersion(userAgent: string): string | undefined;
  */
 declare function getDeviceType(userAgent: string): string | undefined;
 
-/**
- * Validates an event against a set of contracts.
- *
- * @param obj The event to validate.
- * @param customContracts The custom contracts to use.
- * @returns The validated event.
- */
-declare function validateEvent(obj: unknown, customContracts?: Contracts): Event | never;
-/**
- * Validates a property against a schema.
- *
- * @param obj The object to validate.
- * @param key The key of the property to validate.
- * @param value The value of the property to validate.
- * @param schema The schema to validate against.
- * @returns The validated property.
- */
-declare function validateProperty(obj: AnyObject, key: string, value: unknown, schema: Property$1): Property | never;
-
 /**
  * Inline Code Wrapping Utilities
  *
@@ -2498,6 +2692,13 @@ declare function wrapFn(code: string): Fn$1;
  */
 declare function wrapValidate(code: string): Validate;
 
+interface WalkerOSPackageMeta {
+    packageName: string;
+    version: string;
+    description?: string;
+    type?: string;
+    platform?: string;
+}
 interface WalkerOSPackageInfo {
     packageName: string;
     version: string;
@@ -2510,5 +2711,42 @@ declare function fetchPackageSchema(packageName: string, options?: {
     version?: string;
     timeout?: number;
 }): Promise<WalkerOSPackageInfo>;
+declare function fetchPackageMeta(packageName: string, options?: {
+    version?: string;
+    timeout?: number;
+}): Promise<WalkerOSPackageMeta>;
+
+/**
+ * Deep merge two JSON Schema objects with additive semantics.
+ * - `required` arrays: union (deduplicated)
+ * - `properties`: deep merge (child wins on conflict for scalars)
+ * - Scalars: child overrides parent
+ */
+declare function mergeContractSchemas(parent: Record<string, unknown>, child: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Resolve a contract for a specific entity-action pair.
+ * Merges matching levels additively:
+ * 1. setup["*"]["*"]
+ * 2. setup["*"][action]
+ * 3. setup[entity]["*"]
+ * 4. setup[entity][action]
+ * 5-8. Same for config-level contract
+ */
+declare function resolveContract(setup: Contract, entity: string, action: string, config?: Contract): Record<string, unknown>;
+
+declare function mcpResult(result: unknown): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: Record<string, unknown>;
+};
+declare function mcpError(error: unknown): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: true;
+};
 
-export { collector as Collector, Const, context as Context, data as Data, destination as Destination, elb as Elb, flow as Flow, hooks as Hooks, Level, logger as Logger, mapping as Mapping, type MarketingParameters, type MockLogger, on as On, request as Request, schema as Schema, type SendDataValue, type SendHeaders, type SendResponse, source as Source, type StorageType, transformer as Transformer, walkeros as WalkerOS, type WalkerOSPackageInfo, anonymizeIP, assign, branch, castToProperty, castValue, clone, createDestination, createEvent, createLogger, createMockLogger, debounce, fetchPackageSchema, filterValues, getBrowser, getBrowserVersion, getByPath, getDeviceType, getEvent, getFlowConfig, getGrantedConsent, getHeaders, getId, getMappingEvent, getMappingValue, getMarketingParameters, getOS, getOSVersion, getPlatform, isArguments, isArray, isBoolean, isCommand, isDefined, isElementOrDocument, isFunction, isNumber, isObject, isPropertyType, isSameType, isString, mockEnv, packageNameToVariable, parseUserAgent, processEventMapping, requestToData, requestToParameter, setByPath, throttle, throwError, transformData, traverseEnv, trim, tryCatch, tryCatchAsync, useHooks, validateEvent, validateProperty, wrapCondition, wrapFn, wrapValidate };
+export { collector as Collector, Const, context as Context, data as Data, destination as Destination, ENV_MARKER_PREFIX, elb as Elb, flow as Flow, hooks as Hooks, Level, lifecycle as Lifecycle, logger as Logger, mapping as Mapping, type MarketingParameters, type MockLogger, on as On, request as Request, type ResolveOptions, type RespondFn, type RespondOptions, type SendDataValue, type SendHeaders, type SendResponse, simulation as Simulation, source as Source, type StorageType, transformer as Transformer, walkeros as WalkerOS, type WalkerOSPackageInfo, type WalkerOSPackageMeta, anonymizeIP, assign, branch, castToProperty, castValue, clone, createDestination, createEvent, createLogger, createMockLogger, createRespond, debounce, fetchPackageMeta, fetchPackageSchema, filterValues, getBrowser, getBrowserVersion, getByPath, getDeviceType, getEvent, getFlowConfig, getGrantedConsent, getHeaders, getId, getMappingEvent, getMappingValue, getMarketingParameters, getOS, getOSVersion, getPlatform, isArguments, isArray, isBoolean, isCommand, isDefined, isElementOrDocument, isFunction, isNumber, isObject, isPropertyType, isSameType, isString, mcpError, mcpResult, mergeContractSchemas, mockEnv, packageNameToVariable, parseUserAgent, processEventMapping, requestToData, requestToParameter, resolveContract, setByPath, throttle, throwError, transformData, traverseEnv, trim, tryCatch, tryCatchAsync, useHooks, wrapCondition, wrapFn, wrapValidate };