@walkeros/core 4.7.0-next-1790245733116 → 4.7.0

package/dist/index.d.mts

@@ -892,6 +892,13 @@ interface State {
      * validation requires it for get/set.
      */
     value?: Value;
+    /**
+     * Shapes the value read (get) or the resolved payload (set) with a full
+     * mapping value. Paths are relative to that value, not to { event, ingest }.
+     * The result merges into the target: get into the `value` path, set into
+     * the stored entry. Runs on a miss too, so declared fallbacks apply.
+     */
+    mapping?: Value;
 }
 
 /**
@@ -1078,6 +1085,9 @@ interface Config$5<T extends TypesGeneric$3 = Types$4> {
     /**
      * Per-destination delivery timeout in ms (default 10000); a delivery that
      * does not settle within this window is routed to the DLQ like a thrown push.
+     * Also bounds an `on()` handler: a state handler that does not settle within
+     * the window is logged, and the destination is held (its events stay queued)
+     * until a later state delivery to it settles.
      */
     timeout?: number;
     /** Return this value instead of calling push(). Uses !== undefined check to support falsy values. */
@@ -1887,7 +1897,8 @@ declare namespace Flow {
         /**
          * Arbitrary key-value settings consumed by the platform runtime.
          *
-         * For web: typical keys include `windowCollector`.
+         * For web: `windowCollector` names the global the collector instance is
+         * assigned to (default `walkerOS`); it must be a JavaScript identifier.
          * For server: reserved for future server-specific options.
          *
          * The `windowElb` key is deprecated: the browser source is the single writer
@@ -2643,6 +2654,9 @@ interface OnConfig {
 /**
  * Destination `on` handler: receives the action type and a destination context.
  * Already context-style; kept for compatibility with the destination interface.
+ * The collector awaits the returned promise and bounds the wait by
+ * `Destination.Config.timeout`; the handler's effects therefore land before
+ * the destination's next push.
  */
 type OnFn<T extends TypesGeneric$3 = Types$4> = (type: Types$2, context: Context$5<T>) => PromiseOrValue<void>;
 type OnFnRuntime = (type: Types$2, context: Context$5) => PromiseOrValue<void>;
@@ -3376,7 +3390,8 @@ declare namespace walkeros {
 
 /**
  * A recorded function call made during simulation.
- * Captures what a destination called on its env (e.g., window.gtag).
+ * Captures what a destination called on its env (e.g., window.gtag), or a
+ * walker command a source issued (`fn: 'elb'`, first argument verbatim).
  */
 interface Call {
     /** Dot-path of the function called: "window.gtag", "dataLayer.push" */
@@ -3386,6 +3401,22 @@ interface Call {
     /** Unix timestamp in ms */
     ts: number;
 }
+/**
+ * Why a simulated destination sent nothing, read from the collector's own
+ * records:
+ * - `consent`: the event was skipped at the consent gate (or queued, with
+ *   `queue: true`). `required` is the destination's `config.consent`,
+ *   `granted` the collector consent plus the event's own consent.
+ * - `pending`: the destination is still waiting for its `require` entries
+ *   (listed in `require`), so it never started.
+ */
+interface Skipped {
+    reason: 'consent' | 'pending';
+    required?: Consent;
+    granted?: Consent;
+    /** `pending` only: the `require` entries still unmet. */
+    require?: string[];
+}
 /**
  * Result of simulating a single step.
  * Same shape for source, transformer, collector, and destination.
@@ -3403,7 +3434,14 @@ interface Result {
      * - destination: [] (destinations don't produce events)
      */
     events: DeepPartialEvent[];
-    /** Intercepted env calls. Populated for destinations, empty [] for others. */
+    /**
+     * Recorded calls, in time order:
+     * - source: its own walker commands (`fn: 'elb'`, e.g. a CMP's
+     *   `['walker consent', {...}]` or the session's `['user', {...}]`) and
+     *   its mock-env calls
+     * - destination: its intercepted env calls
+     * - transformer, collector: []
+     */
     calls: Call[];
     /** Execution time in ms */
     duration: number;
@@ -3416,14 +3454,20 @@ interface Result {
      * available.
      */
     mappingKey?: string;
+    /**
+     * Destination simulations only: why nothing was sent, when the collector
+     * recorded a consent skip or the destination is still pending.
+     */
+    skipped?: Skipped;
     /** Error if the step threw */
     error?: Error;
 }
 
 type simulation_Call = Call;
 type simulation_Result = Result;
+type simulation_Skipped = Skipped;
 declare namespace simulation {
-  export type { simulation_Call as Call, simulation_Result as Result };
+  export type { simulation_Call as Call, simulation_Result as Result, simulation_Skipped as Skipped };
 }
 
 interface Code {
@@ -3786,6 +3830,18 @@ declare class FlowReferenceError extends Error {
     readonly reference: string;
     constructor(code: 'MISSING_ENV' | 'WEB_SECRET_REF', reference: string, message: string);
 }
+/**
+ * A reference cycle the resolver cannot break. Carries a code and the chain
+ * of names, so tooling can report it structurally instead of matching text.
+ * - `FLOW_CYCLE`: `$flow` references that reach a flow already being
+ *   resolved (the entry flow included, so a flow reading itself cycles).
+ * - `VAR_CYCLE`: `$var` values that reference each other.
+ */
+declare class FlowCycleError extends Error {
+    readonly code: 'FLOW_CYCLE' | 'VAR_CYCLE';
+    readonly chain: string[];
+    constructor(code: 'FLOW_CYCLE' | 'VAR_CYCLE', chain: string[]);
+}
 /** Sentinel prefix for deferred $env resolution. Shared with CLI bundler. */
 declare const ENV_MARKER_PREFIX = "__WALKEROS_ENV:";
 /** Sentinel prefix for deferred $secret resolution. Shared with CLI bundler. */
@@ -5060,6 +5116,25 @@ declare function getOSVersion(userAgent: string): string | undefined;
  */
 declare function getDeviceType(userAgent: string): string | undefined;
 
+/**
+ * Globals the collector must never replace: the page's own and walkerOS's.
+ */
+declare const RESERVED_WINDOW_GLOBALS: readonly string[];
+type WindowCollectorCheck = {
+    ok: true;
+    name: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Check a resolved `config.settings.windowCollector` value: the global a web
+ * bundle assigns the collector to. It must be a JavaScript identifier (it is
+ * interpolated into generated code) and must not replace a reserved global.
+ * The `reason` completes a sentence about the value ("is not ...").
+ */
+declare function checkWindowCollector(value: unknown): WindowCollectorCheck;
+
 /**
  * Inline Code Wrapping Utilities
  *
@@ -5160,6 +5235,19 @@ interface WalkerOSPackage extends WalkerOSPackageInfo {
     source?: string;
     hintKeys: string[];
     exampleSummaries: ExampleSummary[];
+    /**
+     * Examples per export, keyed by export name. Present only for packages
+     * that ship several exports; `examples` then holds the default export's.
+     */
+    exportExamples?: Record<string, unknown>;
+    /**
+     * Schemas per export, keyed by export name, each entry shaped like
+     * `schemas` of a single-export package (`settings`, `mapping`, `setup`).
+     * Present only for packages that ship several exports.
+     */
+    exportSchemas?: Record<string, Record<string, unknown>>;
+    /** Declared exports (name to description) from `$meta.exports`. */
+    exports?: Record<string, string>;
 }
 declare function fetchPackage(packageName: string, options?: {
     version?: string;
@@ -5228,6 +5316,39 @@ declare function isEnvObserve(value: unknown): value is EnvObserve;
  * consecutive dots) is unresolvable and yields `[]`.
  */
 declare function parseCallPath(raw: string): string[];
+interface ObservedEnv<T extends object = Record<string, unknown>> {
+    /** Proxy view of the env; declared paths record, everything else passes through. */
+    env: T;
+    /**
+     * Mutable array: each call on a declared path is pushed here once. Stays
+     * empty when a `record` callback is given, which then receives every call.
+     */
+    calls: Call[];
+    /**
+     * Declared paths whose object intermediates or leaf are absent at wrap time,
+     * as the post-`call:` dot-path. A path that continues through a function
+     * (constructor, factory, method result) resolves lazily and is not listed.
+     */
+    unresolved: string[];
+}
+/**
+ * Observe calls on declared dot-paths of an env without touching it.
+ *
+ * Returns a Proxy view of `env`. Declared paths use the `parseCallPath`
+ * grammar; the recorded `fn` is the full path without `call:` and `args` are
+ * the leaf call's arguments. After an object, a segment is a property of it.
+ * After a function, a segment is a static (see `hasStatic`) or else continues
+ * on the call result (or constructed instance); a Promise result is followed
+ * with `.then`. An object whose tracked properties a Proxy may not substitute
+ * (frozen, or non-writable and non-configurable) is viewed through a shadow
+ * target, so its calls still record and the object itself is never changed. Apply and construct traps call the originals through
+ * `Reflect`, with `this` bound to the real target, so `instanceof`, statics and
+ * `#private` fields keep working and a chain that returns `this` records once.
+ * Nothing on the caller's objects or prototypes is replaced. `record`, when
+ * given, receives every call instead of `calls` (a long-lived view must not
+ * grow an array); a throw there never stops the real call.
+ */
+declare function observeEnv<T extends object = Record<string, unknown>>(env: T, paths: string[], record?: EnvObserve['record']): ObservedEnv<T>;
 
 declare function mcpResult(result: unknown, hints?: {
     next?: string[];
@@ -5776,9 +5897,19 @@ declare function compileState(state: State | State[]): State[];
  * by every event in the scope, so at a fan-out it loses per-event
  * attribution. `set` writes the resolved value to the store.
  *
+ * `mapping` shapes the value read (get) or the payload (set) with paths
+ * relative to that value. It runs on a miss too, so declared fallbacks apply;
+ * an empty result writes nothing. An object result merges into an object
+ * target (get: the `value` path, set: the stored entry), anything else
+ * replaces it. The set merge reads then writes, it is not atomic. Consent
+ * gates on the event's consent, not on a stored `consent` key. Exception:
+ * a `loop` item is mapped like any loop item, so a `consent` key on the item
+ * itself gates that item's mapping.
+ *
  * Each entry is fail-open: a store or resolution error is logged and the
- * event is left unmutated, the chain continues. A key that does not resolve
- * warns; a store miss is silent. Only `FatalError` rethrows (via
+ * event is left unmutated, the chain continues. An unknown store logs an
+ * error and a `file: true` store is skipped with a warning. A key that does
+ * not resolve warns; a store miss is silent. Only `FatalError` rethrows (via
  * `getMappingValue`).
  */
 declare function applyState<E extends DeepPartialEvent>(states: State[], getStore: GetStore, event: E, collector: Instance$6, ingest: Record<string, unknown> | undefined): Promise<E>;
@@ -5910,4 +6041,4 @@ declare const REF_CODE_PREFIX = "$code:";
  */
 declare function scanFlowRefs(value: unknown, into?: Set<string>): Set<string>;
 
-export { type ActivationGrant, type AssembleJourneysOptions, type BatchResponse, type BatchedPosterOptions, type BreakerState, CLOCK_SKEW_MS, cache as Cache, type CacheEnvelope, type CacheResult, type ChainContinuation, type ChainFrame, type ChainStep, type ClickIdEntry, collector as Collector, type CompiledCache, Const, context as Context, type Credential, type Debounced, destination as Destination, type DestroyContext, type DestroyFn, type DroppedCounters, ENV_MARKER_PREFIX, elb as Elb, type EmitFn, type EventOutcome, type ExampleSummary, FatalError, Flow, type FlowConfigResolver, FlowReferenceError, type FlowState, type FlowStateBatch, type FlowStatePhase, type FlowStepType, type GetStore, hint as Hint, hooks as Hooks, type Ingest, type IngestEnvelope, type IngestMeta, InvalidEventError, type Journey, type JourneyAssembly, type JourneyBranch, type JourneyCorrelation, type JourneyEntry, type JourneyGap, type JourneyHop, type JourneyHopStatus, type JourneyPlatform, type JourneyStatus, type JourneyTopology, type JourneyTopologyNode, type JourneyUnattributed, type JsonSchema, Level, lifecycle as Lifecycle, type LifecycleContext, logger as Logger, MAX_SESSION_MS, mapping as Mapping, type MarketingParameters, matcher as Matcher, type MockLogger, type NextSteps, type NodeLikeRequest, OBSERVE_ENV_KEY, OBSERVE_STORAGE_KEY, type Observe, type ObserveCredential, type ObserveServer, type ObserveWeb, type ObserverFn, on as On, type ParsedGrant, type ParsedTraceparent, type PosterFetch, type PosterResponse, type PreviewCrypto, type PreviewFailure, type PreviewKey, type PreviewSubtle, REF_CODE_PREFIX, REF_CONTRACT, REF_ENV, REF_FLOW, REF_SECRET, REF_STORE, REF_VAR_FULL, REF_VAR_INLINE, request as Request, type ResolveContractsOptions, type ResolveOptions, type RespondFn, type RespondOptions, type RouteContinuation, type RouteDecision, type RouteGraphNode, type RouteLabel, SECRET_MARKER_PREFIX, SESSION_STORAGE_KEY, STEP_FIELD_ROLES, STEP_OPERATIVE_FIELDS, type ScheduleOptions, type SendDataValue, type SendHeaders, type SendResponse, type ServiceAccount, type SetupFn, simulation as Simulation, source as Source, type State, type StepEntryErrorCode, type StepEntryValidation, type StepField, type StepFieldRole, type StepKind, type StorageType, store as Store, StoreCodecError, type SwapActivatorConfig, type TelemetryLevel, type TelemetryOptions, type TelemetryOptionsSupplier, type Timer, transformer as Transformer, trigger as Trigger, URL_WINDOW_MS, type ValidateEvents, type VerifyParams, type VerifyResult, walkeros as WalkerOS, type WalkerOSPackage, type WalkerOSPackageInfo, type WalkerOSPackageMeta, advanceChain, anonymizeIP, applyState, applyUpdate, assembleJourneys, assign, batchResponse, branch, browserSwapActivator, buildScopeFromNodeRequest, castToProperty, castValue, checkCache, clone, compileCache, compileMatcher, compileState, createBatchedPoster, createDestination, createEvent, createIngest, createLogger, createMappingRoot, createMockContext, createMockLogger, createRespond, createTelemetryObserver, createTimer, debounce, deepMerge, defaultClickIds, deleteByPath, deriveSpanId, deserializeStoreValue, emitStep, fetchPackage, fetchPackageSchema, filterValues, flattenIncludeSections, formatOut, getBrowser, getBrowserVersion, getByPath, getDeviceType, getErrorMessage, getEvent, getFlowSettings, getGrantedConsent, getHeaders, getId, getMappingEvent, getMappingValue, getMarketingParameters, getNextSteps, getOS, getOSVersion, getPlatform, getRouteGraph, getSpanId, getStepFieldRole, getStepRuntimeProps, getTraceId, getTraceUntil, isArguments, isArray, isBatchBody, isBoolean, isChainContinuation, isCommand, isDefined, isElementOrDocument, isEnvObserve, isFunction, isNumber, isObject, isPathStepEntry, isPropertyType, isRouteArray, isRouteConfigEntry, isRouteContinuation, isSameType, isSampled, isScope, isStoreValue, isString, mcpError, mcpResult, mergeContractSchemas, mergeMappingRule, mockEnv, normalizeBody, normalizeHeaders, normalizeQuery, observeFromEnv, packageNameToVariable, parseCallPath, parseGrant, parseObserveCredential, parseTraceparent, parseUserAgent, processEventMapping, pushResultToOutcome, readCacheEnvelope, requestToData, requestToParameter, resolveContracts, resolveSetup, resolveTelemetryOptions, scanFlowRefs, serializeStoreValue, setByPath, setTraceUntil, startChain, stepId, storeCache, throttle, throwError, toEventList, transformData, traverseEnv, trim, tryCatch, tryCatchAsync, useHooks, validateStepEntry, verifyActivation, walkPath, wrapCacheEnvelope, wrapCondition, wrapFn, wrapValidate };
+export { type ActivationGrant, type AssembleJourneysOptions, type BatchResponse, type BatchedPosterOptions, type BreakerState, CLOCK_SKEW_MS, cache as Cache, type CacheEnvelope, type CacheResult, type ChainContinuation, type ChainFrame, type ChainStep, type ClickIdEntry, collector as Collector, type CompiledCache, Const, context as Context, type Credential, type Debounced, destination as Destination, type DestroyContext, type DestroyFn, type DroppedCounters, ENV_MARKER_PREFIX, elb as Elb, type EmitFn, type EventOutcome, type ExampleSummary, FatalError, Flow, type FlowConfigResolver, FlowCycleError, FlowReferenceError, type FlowState, type FlowStateBatch, type FlowStatePhase, type FlowStepType, type GetStore, hint as Hint, hooks as Hooks, type Ingest, type IngestEnvelope, type IngestMeta, InvalidEventError, type Journey, type JourneyAssembly, type JourneyBranch, type JourneyCorrelation, type JourneyEntry, type JourneyGap, type JourneyHop, type JourneyHopStatus, type JourneyPlatform, type JourneyStatus, type JourneyTopology, type JourneyTopologyNode, type JourneyUnattributed, type JsonSchema, Level, lifecycle as Lifecycle, type LifecycleContext, logger as Logger, MAX_SESSION_MS, mapping as Mapping, type MarketingParameters, matcher as Matcher, type MockLogger, type NextSteps, type NodeLikeRequest, OBSERVE_ENV_KEY, OBSERVE_STORAGE_KEY, type Observe, type ObserveCredential, type ObserveServer, type ObserveWeb, type ObservedEnv, type ObserverFn, on as On, type ParsedGrant, type ParsedTraceparent, type PosterFetch, type PosterResponse, type PreviewCrypto, type PreviewFailure, type PreviewKey, type PreviewSubtle, REF_CODE_PREFIX, REF_CONTRACT, REF_ENV, REF_FLOW, REF_SECRET, REF_STORE, REF_VAR_FULL, REF_VAR_INLINE, RESERVED_WINDOW_GLOBALS, request as Request, type ResolveContractsOptions, type ResolveOptions, type RespondFn, type RespondOptions, type RouteContinuation, type RouteDecision, type RouteGraphNode, type RouteLabel, SECRET_MARKER_PREFIX, SESSION_STORAGE_KEY, STEP_FIELD_ROLES, STEP_OPERATIVE_FIELDS, type ScheduleOptions, type SendDataValue, type SendHeaders, type SendResponse, type ServiceAccount, type SetupFn, simulation as Simulation, source as Source, type State, type StepEntryErrorCode, type StepEntryValidation, type StepField, type StepFieldRole, type StepKind, type StorageType, store as Store, StoreCodecError, type SwapActivatorConfig, type TelemetryLevel, type TelemetryOptions, type TelemetryOptionsSupplier, type Timer, transformer as Transformer, trigger as Trigger, URL_WINDOW_MS, type ValidateEvents, type VerifyParams, type VerifyResult, walkeros as WalkerOS, type WalkerOSPackage, type WalkerOSPackageInfo, type WalkerOSPackageMeta, type WindowCollectorCheck, advanceChain, anonymizeIP, applyState, applyUpdate, assembleJourneys, assign, batchResponse, branch, browserSwapActivator, buildScopeFromNodeRequest, castToProperty, castValue, checkCache, checkWindowCollector, clone, compileCache, compileMatcher, compileState, createBatchedPoster, createDestination, createEvent, createIngest, createLogger, createMappingRoot, createMockContext, createMockLogger, createRespond, createTelemetryObserver, createTimer, debounce, deepMerge, defaultClickIds, deleteByPath, deriveSpanId, deserializeStoreValue, emitStep, fetchPackage, fetchPackageSchema, filterValues, flattenIncludeSections, formatOut, getBrowser, getBrowserVersion, getByPath, getDeviceType, getErrorMessage, getEvent, getFlowSettings, getGrantedConsent, getHeaders, getId, getMappingEvent, getMappingValue, getMarketingParameters, getNextSteps, getOS, getOSVersion, getPlatform, getRouteGraph, getSpanId, getStepFieldRole, getStepRuntimeProps, getTraceId, getTraceUntil, isArguments, isArray, isBatchBody, isBoolean, isChainContinuation, isCommand, isDefined, isElementOrDocument, isEnvObserve, isFunction, isNumber, isObject, isPathStepEntry, isPropertyType, isRouteArray, isRouteConfigEntry, isRouteContinuation, isSameType, isSampled, isScope, isStoreValue, isString, mcpError, mcpResult, mergeContractSchemas, mergeMappingRule, mockEnv, normalizeBody, normalizeHeaders, normalizeQuery, observeEnv, observeFromEnv, packageNameToVariable, parseCallPath, parseGrant, parseObserveCredential, parseTraceparent, parseUserAgent, processEventMapping, pushResultToOutcome, readCacheEnvelope, requestToData, requestToParameter, resolveContracts, resolveSetup, resolveTelemetryOptions, scanFlowRefs, serializeStoreValue, setByPath, setTraceUntil, startChain, stepId, storeCache, throttle, throwError, toEventList, transformData, traverseEnv, trim, tryCatch, tryCatchAsync, useHooks, validateStepEntry, verifyActivation, walkPath, wrapCacheEnvelope, wrapCondition, wrapFn, wrapValidate };

package/dist/index.d.ts

@@ -892,6 +892,13 @@ interface State {
      * validation requires it for get/set.
      */
     value?: Value;
+    /**
+     * Shapes the value read (get) or the resolved payload (set) with a full
+     * mapping value. Paths are relative to that value, not to { event, ingest }.
+     * The result merges into the target: get into the `value` path, set into
+     * the stored entry. Runs on a miss too, so declared fallbacks apply.
+     */
+    mapping?: Value;
 }
 
 /**
@@ -1078,6 +1085,9 @@ interface Config$5<T extends TypesGeneric$3 = Types$4> {
     /**
      * Per-destination delivery timeout in ms (default 10000); a delivery that
      * does not settle within this window is routed to the DLQ like a thrown push.
+     * Also bounds an `on()` handler: a state handler that does not settle within
+     * the window is logged, and the destination is held (its events stay queued)
+     * until a later state delivery to it settles.
      */
     timeout?: number;
     /** Return this value instead of calling push(). Uses !== undefined check to support falsy values. */
@@ -1887,7 +1897,8 @@ declare namespace Flow {
         /**
          * Arbitrary key-value settings consumed by the platform runtime.
          *
-         * For web: typical keys include `windowCollector`.
+         * For web: `windowCollector` names the global the collector instance is
+         * assigned to (default `walkerOS`); it must be a JavaScript identifier.
          * For server: reserved for future server-specific options.
          *
          * The `windowElb` key is deprecated: the browser source is the single writer
@@ -2643,6 +2654,9 @@ interface OnConfig {
 /**
  * Destination `on` handler: receives the action type and a destination context.
  * Already context-style; kept for compatibility with the destination interface.
+ * The collector awaits the returned promise and bounds the wait by
+ * `Destination.Config.timeout`; the handler's effects therefore land before
+ * the destination's next push.
  */
 type OnFn<T extends TypesGeneric$3 = Types$4> = (type: Types$2, context: Context$5<T>) => PromiseOrValue<void>;
 type OnFnRuntime = (type: Types$2, context: Context$5) => PromiseOrValue<void>;
@@ -3376,7 +3390,8 @@ declare namespace walkeros {
 
 /**
  * A recorded function call made during simulation.
- * Captures what a destination called on its env (e.g., window.gtag).
+ * Captures what a destination called on its env (e.g., window.gtag), or a
+ * walker command a source issued (`fn: 'elb'`, first argument verbatim).
  */
 interface Call {
     /** Dot-path of the function called: "window.gtag", "dataLayer.push" */
@@ -3386,6 +3401,22 @@ interface Call {
     /** Unix timestamp in ms */
     ts: number;
 }
+/**
+ * Why a simulated destination sent nothing, read from the collector's own
+ * records:
+ * - `consent`: the event was skipped at the consent gate (or queued, with
+ *   `queue: true`). `required` is the destination's `config.consent`,
+ *   `granted` the collector consent plus the event's own consent.
+ * - `pending`: the destination is still waiting for its `require` entries
+ *   (listed in `require`), so it never started.
+ */
+interface Skipped {
+    reason: 'consent' | 'pending';
+    required?: Consent;
+    granted?: Consent;
+    /** `pending` only: the `require` entries still unmet. */
+    require?: string[];
+}
 /**
  * Result of simulating a single step.
  * Same shape for source, transformer, collector, and destination.
@@ -3403,7 +3434,14 @@ interface Result {
      * - destination: [] (destinations don't produce events)
      */
     events: DeepPartialEvent[];
-    /** Intercepted env calls. Populated for destinations, empty [] for others. */
+    /**
+     * Recorded calls, in time order:
+     * - source: its own walker commands (`fn: 'elb'`, e.g. a CMP's
+     *   `['walker consent', {...}]` or the session's `['user', {...}]`) and
+     *   its mock-env calls
+     * - destination: its intercepted env calls
+     * - transformer, collector: []
+     */
     calls: Call[];
     /** Execution time in ms */
     duration: number;
@@ -3416,14 +3454,20 @@ interface Result {
      * available.
      */
     mappingKey?: string;
+    /**
+     * Destination simulations only: why nothing was sent, when the collector
+     * recorded a consent skip or the destination is still pending.
+     */
+    skipped?: Skipped;
     /** Error if the step threw */
     error?: Error;
 }
 
 type simulation_Call = Call;
 type simulation_Result = Result;
+type simulation_Skipped = Skipped;
 declare namespace simulation {
-  export type { simulation_Call as Call, simulation_Result as Result };
+  export type { simulation_Call as Call, simulation_Result as Result, simulation_Skipped as Skipped };
 }
 
 interface Code {
@@ -3786,6 +3830,18 @@ declare class FlowReferenceError extends Error {
     readonly reference: string;
     constructor(code: 'MISSING_ENV' | 'WEB_SECRET_REF', reference: string, message: string);
 }
+/**
+ * A reference cycle the resolver cannot break. Carries a code and the chain
+ * of names, so tooling can report it structurally instead of matching text.
+ * - `FLOW_CYCLE`: `$flow` references that reach a flow already being
+ *   resolved (the entry flow included, so a flow reading itself cycles).
+ * - `VAR_CYCLE`: `$var` values that reference each other.
+ */
+declare class FlowCycleError extends Error {
+    readonly code: 'FLOW_CYCLE' | 'VAR_CYCLE';
+    readonly chain: string[];
+    constructor(code: 'FLOW_CYCLE' | 'VAR_CYCLE', chain: string[]);
+}
 /** Sentinel prefix for deferred $env resolution. Shared with CLI bundler. */
 declare const ENV_MARKER_PREFIX = "__WALKEROS_ENV:";
 /** Sentinel prefix for deferred $secret resolution. Shared with CLI bundler. */
@@ -5060,6 +5116,25 @@ declare function getOSVersion(userAgent: string): string | undefined;
  */
 declare function getDeviceType(userAgent: string): string | undefined;
 
+/**
+ * Globals the collector must never replace: the page's own and walkerOS's.
+ */
+declare const RESERVED_WINDOW_GLOBALS: readonly string[];
+type WindowCollectorCheck = {
+    ok: true;
+    name: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Check a resolved `config.settings.windowCollector` value: the global a web
+ * bundle assigns the collector to. It must be a JavaScript identifier (it is
+ * interpolated into generated code) and must not replace a reserved global.
+ * The `reason` completes a sentence about the value ("is not ...").
+ */
+declare function checkWindowCollector(value: unknown): WindowCollectorCheck;
+
 /**
  * Inline Code Wrapping Utilities
  *
@@ -5160,6 +5235,19 @@ interface WalkerOSPackage extends WalkerOSPackageInfo {
     source?: string;
     hintKeys: string[];
     exampleSummaries: ExampleSummary[];
+    /**
+     * Examples per export, keyed by export name. Present only for packages
+     * that ship several exports; `examples` then holds the default export's.
+     */
+    exportExamples?: Record<string, unknown>;
+    /**
+     * Schemas per export, keyed by export name, each entry shaped like
+     * `schemas` of a single-export package (`settings`, `mapping`, `setup`).
+     * Present only for packages that ship several exports.
+     */
+    exportSchemas?: Record<string, Record<string, unknown>>;
+    /** Declared exports (name to description) from `$meta.exports`. */
+    exports?: Record<string, string>;
 }
 declare function fetchPackage(packageName: string, options?: {
     version?: string;
@@ -5228,6 +5316,39 @@ declare function isEnvObserve(value: unknown): value is EnvObserve;
  * consecutive dots) is unresolvable and yields `[]`.
  */
 declare function parseCallPath(raw: string): string[];
+interface ObservedEnv<T extends object = Record<string, unknown>> {
+    /** Proxy view of the env; declared paths record, everything else passes through. */
+    env: T;
+    /**
+     * Mutable array: each call on a declared path is pushed here once. Stays
+     * empty when a `record` callback is given, which then receives every call.
+     */
+    calls: Call[];
+    /**
+     * Declared paths whose object intermediates or leaf are absent at wrap time,
+     * as the post-`call:` dot-path. A path that continues through a function
+     * (constructor, factory, method result) resolves lazily and is not listed.
+     */
+    unresolved: string[];
+}
+/**
+ * Observe calls on declared dot-paths of an env without touching it.
+ *
+ * Returns a Proxy view of `env`. Declared paths use the `parseCallPath`
+ * grammar; the recorded `fn` is the full path without `call:` and `args` are
+ * the leaf call's arguments. After an object, a segment is a property of it.
+ * After a function, a segment is a static (see `hasStatic`) or else continues
+ * on the call result (or constructed instance); a Promise result is followed
+ * with `.then`. An object whose tracked properties a Proxy may not substitute
+ * (frozen, or non-writable and non-configurable) is viewed through a shadow
+ * target, so its calls still record and the object itself is never changed. Apply and construct traps call the originals through
+ * `Reflect`, with `this` bound to the real target, so `instanceof`, statics and
+ * `#private` fields keep working and a chain that returns `this` records once.
+ * Nothing on the caller's objects or prototypes is replaced. `record`, when
+ * given, receives every call instead of `calls` (a long-lived view must not
+ * grow an array); a throw there never stops the real call.
+ */
+declare function observeEnv<T extends object = Record<string, unknown>>(env: T, paths: string[], record?: EnvObserve['record']): ObservedEnv<T>;
 
 declare function mcpResult(result: unknown, hints?: {
     next?: string[];
@@ -5776,9 +5897,19 @@ declare function compileState(state: State | State[]): State[];
  * by every event in the scope, so at a fan-out it loses per-event
  * attribution. `set` writes the resolved value to the store.
  *
+ * `mapping` shapes the value read (get) or the payload (set) with paths
+ * relative to that value. It runs on a miss too, so declared fallbacks apply;
+ * an empty result writes nothing. An object result merges into an object
+ * target (get: the `value` path, set: the stored entry), anything else
+ * replaces it. The set merge reads then writes, it is not atomic. Consent
+ * gates on the event's consent, not on a stored `consent` key. Exception:
+ * a `loop` item is mapped like any loop item, so a `consent` key on the item
+ * itself gates that item's mapping.
+ *
  * Each entry is fail-open: a store or resolution error is logged and the
- * event is left unmutated, the chain continues. A key that does not resolve
- * warns; a store miss is silent. Only `FatalError` rethrows (via
+ * event is left unmutated, the chain continues. An unknown store logs an
+ * error and a `file: true` store is skipped with a warning. A key that does
+ * not resolve warns; a store miss is silent. Only `FatalError` rethrows (via
  * `getMappingValue`).
  */
 declare function applyState<E extends DeepPartialEvent>(states: State[], getStore: GetStore, event: E, collector: Instance$6, ingest: Record<string, unknown> | undefined): Promise<E>;
@@ -5910,4 +6041,4 @@ declare const REF_CODE_PREFIX = "$code:";
  */
 declare function scanFlowRefs(value: unknown, into?: Set<string>): Set<string>;
 
-export { type ActivationGrant, type AssembleJourneysOptions, type BatchResponse, type BatchedPosterOptions, type BreakerState, CLOCK_SKEW_MS, cache as Cache, type CacheEnvelope, type CacheResult, type ChainContinuation, type ChainFrame, type ChainStep, type ClickIdEntry, collector as Collector, type CompiledCache, Const, context as Context, type Credential, type Debounced, destination as Destination, type DestroyContext, type DestroyFn, type DroppedCounters, ENV_MARKER_PREFIX, elb as Elb, type EmitFn, type EventOutcome, type ExampleSummary, FatalError, Flow, type FlowConfigResolver, FlowReferenceError, type FlowState, type FlowStateBatch, type FlowStatePhase, type FlowStepType, type GetStore, hint as Hint, hooks as Hooks, type Ingest, type IngestEnvelope, type IngestMeta, InvalidEventError, type Journey, type JourneyAssembly, type JourneyBranch, type JourneyCorrelation, type JourneyEntry, type JourneyGap, type JourneyHop, type JourneyHopStatus, type JourneyPlatform, type JourneyStatus, type JourneyTopology, type JourneyTopologyNode, type JourneyUnattributed, type JsonSchema, Level, lifecycle as Lifecycle, type LifecycleContext, logger as Logger, MAX_SESSION_MS, mapping as Mapping, type MarketingParameters, matcher as Matcher, type MockLogger, type NextSteps, type NodeLikeRequest, OBSERVE_ENV_KEY, OBSERVE_STORAGE_KEY, type Observe, type ObserveCredential, type ObserveServer, type ObserveWeb, type ObserverFn, on as On, type ParsedGrant, type ParsedTraceparent, type PosterFetch, type PosterResponse, type PreviewCrypto, type PreviewFailure, type PreviewKey, type PreviewSubtle, REF_CODE_PREFIX, REF_CONTRACT, REF_ENV, REF_FLOW, REF_SECRET, REF_STORE, REF_VAR_FULL, REF_VAR_INLINE, request as Request, type ResolveContractsOptions, type ResolveOptions, type RespondFn, type RespondOptions, type RouteContinuation, type RouteDecision, type RouteGraphNode, type RouteLabel, SECRET_MARKER_PREFIX, SESSION_STORAGE_KEY, STEP_FIELD_ROLES, STEP_OPERATIVE_FIELDS, type ScheduleOptions, type SendDataValue, type SendHeaders, type SendResponse, type ServiceAccount, type SetupFn, simulation as Simulation, source as Source, type State, type StepEntryErrorCode, type StepEntryValidation, type StepField, type StepFieldRole, type StepKind, type StorageType, store as Store, StoreCodecError, type SwapActivatorConfig, type TelemetryLevel, type TelemetryOptions, type TelemetryOptionsSupplier, type Timer, transformer as Transformer, trigger as Trigger, URL_WINDOW_MS, type ValidateEvents, type VerifyParams, type VerifyResult, walkeros as WalkerOS, type WalkerOSPackage, type WalkerOSPackageInfo, type WalkerOSPackageMeta, advanceChain, anonymizeIP, applyState, applyUpdate, assembleJourneys, assign, batchResponse, branch, browserSwapActivator, buildScopeFromNodeRequest, castToProperty, castValue, checkCache, clone, compileCache, compileMatcher, compileState, createBatchedPoster, createDestination, createEvent, createIngest, createLogger, createMappingRoot, createMockContext, createMockLogger, createRespond, createTelemetryObserver, createTimer, debounce, deepMerge, defaultClickIds, deleteByPath, deriveSpanId, deserializeStoreValue, emitStep, fetchPackage, fetchPackageSchema, filterValues, flattenIncludeSections, formatOut, getBrowser, getBrowserVersion, getByPath, getDeviceType, getErrorMessage, getEvent, getFlowSettings, getGrantedConsent, getHeaders, getId, getMappingEvent, getMappingValue, getMarketingParameters, getNextSteps, getOS, getOSVersion, getPlatform, getRouteGraph, getSpanId, getStepFieldRole, getStepRuntimeProps, getTraceId, getTraceUntil, isArguments, isArray, isBatchBody, isBoolean, isChainContinuation, isCommand, isDefined, isElementOrDocument, isEnvObserve, isFunction, isNumber, isObject, isPathStepEntry, isPropertyType, isRouteArray, isRouteConfigEntry, isRouteContinuation, isSameType, isSampled, isScope, isStoreValue, isString, mcpError, mcpResult, mergeContractSchemas, mergeMappingRule, mockEnv, normalizeBody, normalizeHeaders, normalizeQuery, observeFromEnv, packageNameToVariable, parseCallPath, parseGrant, parseObserveCredential, parseTraceparent, parseUserAgent, processEventMapping, pushResultToOutcome, readCacheEnvelope, requestToData, requestToParameter, resolveContracts, resolveSetup, resolveTelemetryOptions, scanFlowRefs, serializeStoreValue, setByPath, setTraceUntil, startChain, stepId, storeCache, throttle, throwError, toEventList, transformData, traverseEnv, trim, tryCatch, tryCatchAsync, useHooks, validateStepEntry, verifyActivation, walkPath, wrapCacheEnvelope, wrapCondition, wrapFn, wrapValidate };
+export { type ActivationGrant, type AssembleJourneysOptions, type BatchResponse, type BatchedPosterOptions, type BreakerState, CLOCK_SKEW_MS, cache as Cache, type CacheEnvelope, type CacheResult, type ChainContinuation, type ChainFrame, type ChainStep, type ClickIdEntry, collector as Collector, type CompiledCache, Const, context as Context, type Credential, type Debounced, destination as Destination, type DestroyContext, type DestroyFn, type DroppedCounters, ENV_MARKER_PREFIX, elb as Elb, type EmitFn, type EventOutcome, type ExampleSummary, FatalError, Flow, type FlowConfigResolver, FlowCycleError, FlowReferenceError, type FlowState, type FlowStateBatch, type FlowStatePhase, type FlowStepType, type GetStore, hint as Hint, hooks as Hooks, type Ingest, type IngestEnvelope, type IngestMeta, InvalidEventError, type Journey, type JourneyAssembly, type JourneyBranch, type JourneyCorrelation, type JourneyEntry, type JourneyGap, type JourneyHop, type JourneyHopStatus, type JourneyPlatform, type JourneyStatus, type JourneyTopology, type JourneyTopologyNode, type JourneyUnattributed, type JsonSchema, Level, lifecycle as Lifecycle, type LifecycleContext, logger as Logger, MAX_SESSION_MS, mapping as Mapping, type MarketingParameters, matcher as Matcher, type MockLogger, type NextSteps, type NodeLikeRequest, OBSERVE_ENV_KEY, OBSERVE_STORAGE_KEY, type Observe, type ObserveCredential, type ObserveServer, type ObserveWeb, type ObservedEnv, type ObserverFn, on as On, type ParsedGrant, type ParsedTraceparent, type PosterFetch, type PosterResponse, type PreviewCrypto, type PreviewFailure, type PreviewKey, type PreviewSubtle, REF_CODE_PREFIX, REF_CONTRACT, REF_ENV, REF_FLOW, REF_SECRET, REF_STORE, REF_VAR_FULL, REF_VAR_INLINE, RESERVED_WINDOW_GLOBALS, request as Request, type ResolveContractsOptions, type ResolveOptions, type RespondFn, type RespondOptions, type RouteContinuation, type RouteDecision, type RouteGraphNode, type RouteLabel, SECRET_MARKER_PREFIX, SESSION_STORAGE_KEY, STEP_FIELD_ROLES, STEP_OPERATIVE_FIELDS, type ScheduleOptions, type SendDataValue, type SendHeaders, type SendResponse, type ServiceAccount, type SetupFn, simulation as Simulation, source as Source, type State, type StepEntryErrorCode, type StepEntryValidation, type StepField, type StepFieldRole, type StepKind, type StorageType, store as Store, StoreCodecError, type SwapActivatorConfig, type TelemetryLevel, type TelemetryOptions, type TelemetryOptionsSupplier, type Timer, transformer as Transformer, trigger as Trigger, URL_WINDOW_MS, type ValidateEvents, type VerifyParams, type VerifyResult, walkeros as WalkerOS, type WalkerOSPackage, type WalkerOSPackageInfo, type WalkerOSPackageMeta, type WindowCollectorCheck, advanceChain, anonymizeIP, applyState, applyUpdate, assembleJourneys, assign, batchResponse, branch, browserSwapActivator, buildScopeFromNodeRequest, castToProperty, castValue, checkCache, checkWindowCollector, clone, compileCache, compileMatcher, compileState, createBatchedPoster, createDestination, createEvent, createIngest, createLogger, createMappingRoot, createMockContext, createMockLogger, createRespond, createTelemetryObserver, createTimer, debounce, deepMerge, defaultClickIds, deleteByPath, deriveSpanId, deserializeStoreValue, emitStep, fetchPackage, fetchPackageSchema, filterValues, flattenIncludeSections, formatOut, getBrowser, getBrowserVersion, getByPath, getDeviceType, getErrorMessage, getEvent, getFlowSettings, getGrantedConsent, getHeaders, getId, getMappingEvent, getMappingValue, getMarketingParameters, getNextSteps, getOS, getOSVersion, getPlatform, getRouteGraph, getSpanId, getStepFieldRole, getStepRuntimeProps, getTraceId, getTraceUntil, isArguments, isArray, isBatchBody, isBoolean, isChainContinuation, isCommand, isDefined, isElementOrDocument, isEnvObserve, isFunction, isNumber, isObject, isPathStepEntry, isPropertyType, isRouteArray, isRouteConfigEntry, isRouteContinuation, isSameType, isSampled, isScope, isStoreValue, isString, mcpError, mcpResult, mergeContractSchemas, mergeMappingRule, mockEnv, normalizeBody, normalizeHeaders, normalizeQuery, observeEnv, observeFromEnv, packageNameToVariable, parseCallPath, parseGrant, parseObserveCredential, parseTraceparent, parseUserAgent, processEventMapping, pushResultToOutcome, readCacheEnvelope, requestToData, requestToParameter, resolveContracts, resolveSetup, resolveTelemetryOptions, scanFlowRefs, serializeStoreValue, setByPath, setTraceUntil, startChain, stepId, storeCache, throttle, throwError, toEventList, transformData, traverseEnv, trim, tryCatch, tryCatchAsync, useHooks, validateStepEntry, verifyActivation, walkPath, wrapCacheEnvelope, wrapCondition, wrapFn, wrapValidate };