@walkeros/core 4.6.1 → 4.7.0-next-1790245733116

package/dist/index.d.mts

@@ -99,6 +99,18 @@ interface ValueConfig {
     validate?: Validate;
     value?: PropertyType;
 }
+/**
+ * Resolution root for paths that can address both the event and the
+ * pipeline ingest: state, cache keys and route matchers. Paths name their
+ * side explicitly, `event.data.id` or `ingest.site`. Every route resolves
+ * with the event its position holds. `event` is absent only for the
+ * request-scoped source cache key (one check per request, before per-event
+ * work) and in static tooling that has no event.
+ */
+type Root = {
+    event?: DeepPartialEvent;
+    ingest: Record<string, unknown>;
+};
 interface Context$6 {
     event: DeepPartialEvent;
     /** The surrounding mapping config: a Value (value-level) or a Rule (rule-level). */
@@ -118,6 +130,7 @@ type Map = {
 type mapping_Condition = Condition;
 type mapping_Loop = Loop;
 type mapping_Map = Map;
+type mapping_Root = Root;
 type mapping_Rule<Settings = unknown> = Rule<Settings>;
 type mapping_RulePatch<Settings = unknown> = RulePatch<Settings>;
 type mapping_Rules<T = Rule> = Rules<T>;
@@ -127,7 +140,7 @@ type mapping_ValueConfig = ValueConfig;
 type mapping_ValueType = ValueType;
 type mapping_Values = Values;
 declare namespace mapping {
-  export type { mapping_Condition as Condition, Config$7 as Config, Context$6 as Context, Data$1 as Data, Fn$4 as Fn, mapping_Loop as Loop, mapping_Map as Map, Policy$1 as Policy, Result$2 as Result, mapping_Rule as Rule, mapping_RulePatch as RulePatch, 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$7 as Config, Context$6 as Context, Data$1 as Data, Fn$4 as Fn, mapping_Loop as Loop, mapping_Map as Map, Policy$1 as Policy, Result$2 as Result, mapping_Root as Root, mapping_Rule as Rule, mapping_RulePatch as RulePatch, mapping_Rules as Rules, mapping_Validate as Validate, mapping_Value as Value, mapping_ValueConfig as ValueConfig, mapping_ValueType as ValueType, mapping_Values as Values };
 }
 
 interface BaseCacheRule {
@@ -366,7 +379,7 @@ interface FlowState {
     /** For phase === 'flush', the batch size + entry index. */
     batch?: FlowStateBatch;
     /** Discriminator when phase === 'skip'. */
-    skipReason?: 'consent' | 'cache_hit' | 'sampled_out' | 'disabled' | 'unknown';
+    skipReason?: 'consent' | 'cache_hit' | 'sampled_out' | 'disabled' | 'dropped' | 'unknown';
     /** Free-form metadata: store key/value, cached: true, etc. */
     meta?: Record<string, unknown>;
 }
@@ -448,6 +461,14 @@ interface Config$6 {
     name?: string;
     /** Config release id stamped into event.source.release for this flow. */
     release?: string;
+    /**
+     * The collector's own transformer chain. Runs once per completed event,
+     * after enrichment and before the destination fan-out, with the full route
+     * grammar. A `stop` (or a transformer returning `false`) drops the event for
+     * every destination; per-destination filtering belongs on
+     * `destination.before`. Swappable at runtime via `walker config`.
+     */
+    next?: Route;
 }
 /**
  * Initialization configuration that extends Config with initial state
@@ -601,7 +622,11 @@ interface PushOptions {
     ingest?: Ingest;
     respond?: RespondFn;
     mapping?: Config$7;
-    preChain?: string[];
+    /**
+     * Pre-collector chain (the source's `next` route, or a continuation of
+     * it). Resolved hop by hop by the chain runner with `{ ingest, event }`.
+     */
+    preChain?: Route;
     include?: string[];
     exclude?: string[];
 }
@@ -848,18 +873,21 @@ type Credential<T> = string | T;
 
 /**
  * Declarative store operation. Replaces `$code:` for simple fetch/stash.
- * key = store side, value = event side, mode = direction.
+ * key names the store slot, value the event or ingest side, mode the
+ * direction. Paths resolve against `{ event, ingest }`: `event.user.session`,
+ * `ingest.site`.
  */
 interface State {
     /** Direction. 'delete' is reserved for a later release. */
     mode: 'get' | 'set';
     /** Store id; defaults to the in-memory `__cache` store when omitted. */
     store?: string;
-    /** Resolves against the event to the store key. */
+    /** Resolves against `{ event, ingest }` to the store key. */
     key: Value;
     /**
-     * set: resolves to the payload to store.
-     * get: its `key`/bare-string path is the event write-target.
+     * set: resolves against `{ event, ingest }` to the payload to store.
+     * get: its string path (or `key`) is the write target, `event.` onto the
+     * event or `ingest.` into the ingest.
      * Optional at the type level to keep a future `delete` mode non-breaking;
      * validation requires it for get/set.
      */
@@ -1028,7 +1056,7 @@ interface Config$5<T extends TypesGeneric$3 = Types$4> {
     mapping?: Rules<Rule<Mapping$1<T>>>;
     /** Pre-processing rules applied to all events before mapping; modifies events in-place. */
     policy?: Policy;
-    /** Whether to queue events when consent is not granted; defaults to true. */
+    /** Whether a destination added after events were pushed receives the current run's earlier events (from `collector.queue`); defaults to true. Consent-denied events are queued regardless. */
     queue?: boolean;
     /** Defer destination initialization until these collector events fire (e.g., `['consent']`). */
     require?: string[];
@@ -1347,46 +1375,70 @@ declare namespace elb {
 /**
  * Unified route grammar for Flow v4. A `Route` is one of:
  * - a transformer ID string (`"redact"`)
- * - a sequence of routes (`["a", "b", "c"]` — sugar for chained `.next`)
- * - a `RouteConfig` — a gated / dispatching node.
+ * - a sequence of routes (`["a", "b", "c"]`, run in order)
+ * - a `RouteConfig`: a gated / dispatching node.
  *
- * `RouteConfig` is a disjoint union — set exactly one of `next`, `one`,
- * `many`, or neither (pure gate). The disjointness is enforced by `never`
- * sibling properties at the type level and `z.strictObject` at the schema
- * level.
+ * Exception: an array made only of route configs (no id, no nested array)
+ * is an implicit `one`, first match wins (`[gateA, gateB]` runs at most one
+ * of them). Write `{ one: [...] }` to say so, or add an id to make it a
+ * sequence (`["x", gateA, gateB]` evaluates both gates in order).
+ *
+ * `RouteConfig` is a disjoint union: set exactly one of `next`, `one`,
+ * `many`, `stop`, or none of them (pure gate). The disjointness is enforced
+ * by `never` sibling properties at the type level and `z.strictObject` at the
+ * schema level.
  *
  * Operators:
  * - `next`: single continuation.
  * - `one`: first-match dispatch (walk entries, first whose match passes wins).
- * - `many`: all-match terminal fan-out (every matching entry spawns an
- *   independent flow; main chain terminates here). Restricted to
- *   pre-collector positions (source.next, transformer.next, transformer.before).
+ * - `many`: all-match fan-out. Every matching entry is its own copy of the
+ *   event that finishes the rest of the path on its own. Valid in every chain
+ *   field.
+ * - `stop`: ends the running copy of the event (optionally gated by `match`).
+ *
+ * Sequences resolve lazily: a conditional segment is evaluated only when its
+ * position is reached, so it sees what earlier steps wrote.
  */
 type Route = string | Route[] | RouteConfig;
-type RouteConfig = RouteNextConfig | RouteOneConfig | RouteManyConfig | RouteGateConfig;
+type RouteConfig = RouteNextConfig | RouteOneConfig | RouteManyConfig | RouteStopConfig | RouteGateConfig;
 interface RouteNextConfig {
     match?: MatchExpression;
     next: Route;
     one?: never;
     many?: never;
+    stop?: never;
 }
 interface RouteOneConfig {
     match?: MatchExpression;
     one: Route[];
     next?: never;
     many?: never;
+    stop?: never;
 }
 interface RouteManyConfig {
     match?: MatchExpression;
     many: Route[];
     next?: never;
     one?: never;
+    stop?: never;
+}
+/**
+ * Ends the running copy of the event. Without `match` the stop is
+ * unconditional; with `match` a failing match falls through like a gate.
+ */
+interface RouteStopConfig {
+    match?: MatchExpression;
+    stop: true;
+    next?: never;
+    one?: never;
+    many?: never;
 }
 interface RouteGateConfig {
     match: MatchExpression;
     next?: never;
     one?: never;
     many?: never;
+    stop?: never;
 }
 /**
  * Base environment interface for walkerOS transformers.
@@ -1486,21 +1538,36 @@ interface Result$1<E = DeepPartialEvent> {
     respond?: RespondFn;
     next?: Route;
 }
+/**
+ * One finished copy of a chain run: its event and its own ingest. `E`
+ * narrows the event where the copy is known complete (a full event after
+ * `collector.next`).
+ */
+interface ChainCopy<E = DeepPartialEvent> {
+    event: E;
+    ingest: Ingest;
+}
 /**
  * Result of running a transformer chain.
- * Returns the processed event (singular, fan-out array, or null if dropped)
- * alongside the potentially wrapped respond function.
  *
- * `stopped` signals pipeline-halt — when set, the caller MUST NOT propagate
- * the event further downstream (no destinations, no subsequent chains).
- * Used by `cache.stop: true` on pre-collector transformers so the documented
- * "downstream transformers and destinations are skipped" semantic holds.
+ * `copies` is the one carrier of the outcome: every finished copy that
+ * continues downstream (one without a fork, one per surviving fork), each
+ * with the ingest it finished with. The next position goes on with each
+ * pair.
+ *
+ * - dropped (a transformer returned `false` or threw): `copies` empty,
+ *   `droppedBy` names the transformer.
+ * - route `stop`: `copies` empty, `stopped: true`; `droppedBy` names the
+ *   transformer whose route stopped it, absent for the start route.
+ * - `cache.stop: true` HIT: `copies` holds the cached copy, `stopped: true`.
+ *   The caller MUST NOT propagate it further downstream than its position
+ *   allows (pipeline halt).
  */
 interface ChainResult {
-    event: DeepPartialEvent | DeepPartialEvent[] | null;
+    copies: ChainCopy[];
     respond?: RespondFn;
     stopped?: true;
-    /** Transformer that stopped the chain (returned false or threw). */
+    /** Transformer that dropped or stopped the chain. */
     droppedBy?: string;
 }
 /**
@@ -1600,6 +1667,7 @@ declare function getTransformer<T extends TypesGeneric$2 = Types$3>(collector: {
     };
 }, id: string): Instance$4<T>;
 
+type transformer_ChainCopy<E = DeepPartialEvent> = ChainCopy<E>;
 type transformer_ChainResult = ChainResult;
 type transformer_InitTransformer<T extends TypesGeneric$2 = Types$3> = InitTransformer<T>;
 type transformer_InitTransformers = InitTransformers;
@@ -1609,10 +1677,11 @@ type transformer_RouteGateConfig = RouteGateConfig;
 type transformer_RouteManyConfig = RouteManyConfig;
 type transformer_RouteNextConfig = RouteNextConfig;
 type transformer_RouteOneConfig = RouteOneConfig;
+type transformer_RouteStopConfig = RouteStopConfig;
 type transformer_Transformers = Transformers;
 declare const transformer_getTransformer: typeof getTransformer;
 declare namespace transformer {
-  export { type BaseEnv$2 as BaseEnv, type transformer_ChainResult as ChainResult, type Config$4 as Config, type Context$4 as Context, type Env$2 as Env, type Fn$2 as Fn, type Init$2 as Init, type InitFn$1 as InitFn, type InitSettings$2 as InitSettings, type transformer_InitTransformer as InitTransformer, type transformer_InitTransformers as InitTransformers, type Instance$4 as Instance, type Result$1 as Result, type transformer_Route as Route, type transformer_RouteConfig as RouteConfig, type transformer_RouteGateConfig as RouteGateConfig, type transformer_RouteManyConfig as RouteManyConfig, type transformer_RouteNextConfig as RouteNextConfig, type transformer_RouteOneConfig as RouteOneConfig, type Settings$2 as Settings, type transformer_Transformers as Transformers, type Types$3 as Types, type TypesGeneric$2 as TypesGeneric, type TypesOf$2 as TypesOf, transformer_getTransformer as getTransformer };
+  export { type BaseEnv$2 as BaseEnv, type transformer_ChainCopy as ChainCopy, type transformer_ChainResult as ChainResult, type Config$4 as Config, type Context$4 as Context, type Env$2 as Env, type Fn$2 as Fn, type Init$2 as Init, type InitFn$1 as InitFn, type InitSettings$2 as InitSettings, type transformer_InitTransformer as InitTransformer, type transformer_InitTransformers as InitTransformers, type Instance$4 as Instance, type Result$1 as Result, type transformer_Route as Route, type transformer_RouteConfig as RouteConfig, type transformer_RouteGateConfig as RouteGateConfig, type transformer_RouteManyConfig as RouteManyConfig, type transformer_RouteNextConfig as RouteNextConfig, type transformer_RouteOneConfig as RouteOneConfig, type transformer_RouteStopConfig as RouteStopConfig, type Settings$2 as Settings, type transformer_Transformers as Transformers, type Types$3 as Types, type TypesGeneric$2 as TypesGeneric, type TypesOf$2 as TypesOf, transformer_getTransformer as getTransformer };
 }
 
 /**
@@ -1647,20 +1716,24 @@ type ValidateEvents = Record<string, Record<string, JsonSchema>>;
  * Sources use `before` for consent-exempt pre-source preprocessing
  * (decode, validate, authenticate raw input before the source.next chain).
  *
- * Destinations use `before` to connect to transformers (post-collector chain).
+ * The collector uses `next` for its own chain: it runs once per completed
+ * event, before the destination fan-out, so a `stop` there drops the event
+ * for every destination.
+ *
+ * Destinations use `before` to connect to transformers (per-destination chain).
  * Destinations use `next` for post-push processing.
  *
  * 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.
+ * The collector is never referenced as a target in connections. It sits
+ * between the source chain and the destination chains automatically.
  *
- * Circular `next` references are safely handled at runtime by `walkChain()`
- * in the collector module (visited-set detection).
+ * Circular member `next` references are cut at runtime by the chain
+ * runner's cycle guard (`advanceChain`) and bounded by its path cap.
  *
  * ```
- * Source → [before → Preprocessing] → [next → Transformer chain] → Collector → [before → Transformer chain] → Destination → [next → Post-push]
+ * Source → [before → Preprocessing] → [next → Transformer chain] → Collector → [collector.next → Transformer chain] → [before → Transformer chain] → Destination → [next → Post-push]
  * ```
  *
  * @packageDocumentation
@@ -1707,9 +1780,10 @@ interface Flow {
     /**
      * Transformer configurations (event transformation).
      *
-     * Pre-collector (source.next) or post-collector (destination.before).
+     * Pre-collector (source.next), collector-level (collector.next, once per
+     * event for every destination) or per destination (destination.before).
      *
-     * Key = unique transformer identifier (referenced by source.next or destination.before)
+     * Key = unique transformer identifier (referenced by any chain field)
      * Value = transformer reference with package and config
      */
     transformers?: Record<string, Flow.Transformer>;
@@ -1917,6 +1991,23 @@ declare namespace Flow {
          * Server flows only.
          */
         traceInclude?: string[];
+        /**
+         * Declared build-time values for web `$env` references.
+         *
+         * Web flows resolve `$env.NAME` when the bundle is built and inline the
+         * value. This map is the declared set the build resolves against, so the
+         * same config bundles identically wherever it is built. A local CLI build
+         * layers it over the shell environment; a hosted build uses it alone.
+         * Server flows ignore it: their `$env` references are read at runtime.
+         *
+         * Values are inlined into public web bundles. Never put secrets here.
+         *
+         * @example
+         * ```json
+         * { "GA4_MEASUREMENT_ID": "G-XXXXXXX" }
+         * ```
+         */
+        env?: Record<string, string>;
     }
     /**
      * Single bundle package entry.
@@ -2021,6 +2112,8 @@ declare namespace Flow {
         next?: Route;
         /** Cache configuration for this source. */
         cache?: Cache<EventCacheRule>;
+        /** Declarative store get/set. Paths resolve against `{ event, ingest }`. */
+        state?: State | State[];
         /**
          * Source-level variables (highest priority in cascade).
          * Overrides flow and root variables.
@@ -2069,7 +2162,7 @@ declare namespace Flow {
         /** Destination environment configuration, merged with default destination environment. */
         env?: unknown;
         /**
-         * First transformer in post-collector chain.
+         * First transformer in this destination's chain.
          *
          * Name of the transformer to execute before sending events to this destination.
          * If omitted, events are sent directly from the collector.
@@ -2086,6 +2179,8 @@ declare namespace Flow {
         next?: Route;
         /** Cache configuration for this destination. */
         cache?: Cache<EventCacheRule>;
+        /** Declarative store get/set. Paths resolve against `{ event, ingest }`. */
+        state?: State | State[];
         /** Destination-level variables (highest priority in cascade). */
         variables?: Variables;
         /**
@@ -2137,14 +2232,23 @@ declare namespace Flow {
          *
          * Name of the next transformer to execute after this one.
          * In a pre-collector chain (source.next), terminates at the collector.
-         * In a post-collector chain (destination.before), terminates at the destination.
+         * In collector.next, terminates at the destination fan-out.
+         * In a destination 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()`.
+         * Array values define an explicit chain; a member's own `next` is
+         * inserted right after it. Circular references are cut at runtime by the
+         * chain runner's cycle guard (`advanceChain`).
          */
         next?: Route;
         /** Cache configuration for this transformer. */
         cache?: Cache<EventCacheRule>;
+        /** Declarative store get/set. Paths resolve against `{ event, ingest }`. */
+        state?: State | State[];
+        /**
+         * Event mapping for a code-free transformer. The collector synthesizes a
+         * push that applies it to the event (a rule with `ignore: true` drops it).
+         */
+        mapping?: Config$7;
         /** Transformer-level variables (highest priority in cascade). */
         variables?: Variables;
         /**
@@ -3478,7 +3582,7 @@ interface JourneyBranch {
     /** Wall-clock duration of the branch, when measured. */
     durationMs?: number;
     /** Skip discriminator when the branch was skipped. */
-    skipReason?: 'consent' | 'cache_hit' | 'sampled_out' | 'disabled' | 'unknown';
+    skipReason?: 'consent' | 'cache_hit' | 'sampled_out' | 'disabled' | 'dropped' | 'unknown';
     /** Error info when the branch failed. */
     error?: {
         name?: string;
@@ -3525,7 +3629,7 @@ interface JourneyHop {
         message: string;
     };
     /** Skip discriminator when the hop's terminal phase is skip. */
-    skipReason?: 'consent' | 'cache_hit' | 'sampled_out' | 'disabled' | 'unknown';
+    skipReason?: 'consent' | 'cache_hit' | 'sampled_out' | 'disabled' | 'dropped' | 'unknown';
     /** Matched mapping rule, when one matched. */
     mappingKey?: string;
     /** Matched contract rule, when one matched. */
@@ -3652,7 +3756,10 @@ interface JourneyAssembly {
 declare function branch(event: DeepPartialEvent, next: Route): Result$1;
 
 /**
- * Anonymizes an IPv4 address by setting the last octet to 0.
+ * Anonymizes an IP address: IPv4 keeps its /24, IPv6 its /48.
+ *
+ * An IPv4-mapped IPv6 address (`::ffff:1.2.3.4`, what a dual-stack listener
+ * reports for an IPv4 client) is treated as the IPv4 address it carries.
  *
  * @param ip The IP address to anonymize.
  * @returns The anonymized IP address or an empty string if the IP is invalid.
@@ -3667,12 +3774,32 @@ declare function anonymizeIP(ip: string): string;
  * @packageDocumentation
  */
 
+/**
+ * A `$env` or `$secret` reference that cannot resolve for a build. Carries a
+ * code and the referenced NAME (never a value), so build tooling can report
+ * the failure structurally instead of matching message text.
+ * - `MISSING_ENV`: `$env.NAME` with no value in the build env and no default.
+ * - `WEB_SECRET_REF`: `$secret.NAME` in a web (non-deferred) flow.
+ */
+declare class FlowReferenceError extends Error {
+    readonly code: 'MISSING_ENV' | 'WEB_SECRET_REF';
+    readonly reference: string;
+    constructor(code: 'MISSING_ENV' | 'WEB_SECRET_REF', reference: string, message: 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. */
 declare const SECRET_MARKER_PREFIX = "__WALKEROS_SECRET:";
 interface ResolveOptions {
     deferred?: boolean;
+    /**
+     * The only source for non-deferred `$env` references. When set, `$env.NAME`
+     * reads this map (then the inline `:default`) and never `process.env`.
+     * Build tooling passes it so a web bundle cannot pick up whatever happens
+     * to be in the building process's environment. When omitted, `process.env`
+     * is used.
+     */
+    env?: Readonly<Record<string, string | undefined>>;
     /**
      * When false, unresolved `$flow.X.Y` refs (unknown flow, missing key,
      * empty value) trigger {@link onWarning} and the original `$flow…` string
@@ -3805,9 +3932,18 @@ declare function getByPath(event: unknown, key?: string, defaultValue?: unknown)
  * @param obj - The object to set the value in.
  * @param key - The dot-notation string.
  * @param value - The value to set.
- * @returns A new object with the updated value.
+ * @param options.mutable - Write into `obj` in place instead of a clone. For
+ *   shared mutable context such as ingest, where later steps must see the
+ *   write. Returns `obj` itself.
+ * @returns A new object with the updated value, or `obj` when mutable.
+ *
+ * Setting `undefined` removes the key instead, and creates nothing on a
+ * missing path. An own key holding `undefined` is a state walkerOS never
+ * produces, because JSON and JSON Schema treat it as absent.
  */
-declare function setByPath<T = unknown>(obj: T, key: string, value: unknown): T;
+declare function setByPath<T = unknown>(obj: T, key: string, value: unknown, options?: {
+    mutable?: boolean;
+}): T;
 /**
  * Deletes a value in an object by a dot-notation string.
  * Returns a new object; the input is not mutated. No-op when the path is
@@ -3906,6 +4042,14 @@ declare function getId(length?: number, charset?: string): string;
  */
 declare function getSpanId(): string;
 
+/**
+ * Deterministic child span id: 16 lowercase hex characters (the shape of
+ * `getSpanId`), derived from the parent id and the child's position. The
+ * same inputs always give the same id, different positions or parents give
+ * different ids, so forks of one event never collapse on `event.id`.
+ */
+declare function deriveSpanId(parentId: string, position: number | string): string;
+
 /**
  * W3C trace_id: 16 random bytes encoded as 32 lowercase hex characters.
  * Shared by every event of a collector run. Reference: W3C Trace Context.
@@ -4969,6 +5113,27 @@ declare function wrapFn(code: string): Fn$4;
  */
 declare function wrapValidate(code: string): Validate;
 
+/**
+ * Timer utilities for measuring execution time
+ */
+interface Timer {
+    start: () => void;
+    end: () => number;
+    getElapsed: () => number;
+    format: () => string;
+}
+/**
+ * Create a high-precision timer
+ */
+declare function createTimer(): Timer;
+
+/**
+ * Extract error message from unknown error type
+ * @param error - Unknown error object
+ * @returns Error message as string
+ */
+declare function getErrorMessage(error: unknown): string;
+
 interface ExampleSummary {
     name: string;
     description?: string;
@@ -5259,32 +5424,228 @@ declare function pushResultToOutcome(result: {
  */
 declare function compileMatcher(expr: MatchExpression | '*' | undefined): CompiledMatcher;
 
+/** Position inside a raw route spec, e.g. `['one', 0, 'next']`. */
+type RoutePath = (string | number)[];
+/**
+ * Where a compiled id or stop came from: the nearest enclosing decision
+ * (`one` / `many` entry or gated `next` / `stop`) with its SOURCE match
+ * expression, or, outside any decision, the plain position of the segment.
+ * Kept beside the compiled matcher so enumerations can label branches.
+ */
+interface RouteDecision {
+    kind: 'next' | 'one' | 'many' | 'sequence';
+    path: RoutePath;
+    match?: MatchExpression;
+    catchAll?: true;
+}
+/**
+ * A decision label plus `outer`, the enclosing decision whose match must
+ * also have held to reach this one (a gate inside a `one` entry, a `one`
+ * inside a gate, ...). The chain of `outer` links lists every decision on
+ * the way from the route's head.
+ */
+interface RouteLabel extends RouteDecision {
+    outer?: RouteLabel;
+}
+/**
+ * Internal: compiled route data. Not exported from the package's public
+ * surface (`@walkeros/core`), but exported here so adjacent files inside the
+ * core package can probe compilation.
+ */
+interface CompiledRoute {
+    match: CompiledMatcher;
+    source?: MatchExpression;
+    next: CompiledNext;
+}
+type CompiledIdNode = {
+    type: 'static';
+    value: string;
+    label: RouteLabel;
+} | {
+    type: 'chain';
+    value: string[];
+    label: RouteLabel;
+};
+type CompiledStopNode = {
+    type: 'stop';
+    label: RouteLabel;
+};
+type CompiledGateNode = {
+    type: 'gate';
+    match: CompiledMatcher;
+    source: MatchExpression;
+    next: CompiledNext;
+};
+type CompiledNext = CompiledIdNode | CompiledStopNode | CompiledGateNode | {
+    type: 'one';
+    routes: CompiledRoute[];
+} | {
+    type: 'many';
+    routes: CompiledRoute[];
+} | {
+    type: 'sequence';
+    value: CompiledNext[];
+};
+/**
+ * The unresolved remainder of a route: compiled segments still to walk,
+ * followed by the remainder of every enclosing level (`tail`). Treat it as
+ * opaque: only `getNextSteps` (and the chain helpers built on it) read it.
+ * It references the cached compiled nodes, so resuming never recompiles.
+ */
+interface RouteContinuation {
+    readonly type: 'continuation';
+    readonly segments: readonly CompiledNext[];
+    readonly at: number;
+    readonly tail?: RouteContinuation;
+}
+/**
+ * Result of resolving a route against one root.
+ *
+ * - `{ ids }`: run these ids in order. `ids: []` without `then` means the
+ *   route resolved to nothing (gate failed, no `one` entry matched, empty or
+ *   undefined spec): the caller continues with whatever follows the route.
+ * - `{ ids, then }`: run `ids`, then resolve `then` against the root as the
+ *   last of those steps left it (lazy sequences).
+ * - `{ ids: [], stop: true }`: a `stop` matched; the running copy ends.
+ * - `{ ids: [], forks }`: a `many` matched two or more entries. Each fork is
+ *   an independent copy that resolves its own continuation (which already
+ *   includes the rest of the enclosing sequence).
+ */
+type NextSteps = {
+    ids: string[];
+    then?: RouteContinuation;
+    stop?: never;
+    forks?: never;
+} | {
+    ids: [];
+    stop: true;
+    then?: never;
+    forks?: never;
+} | {
+    ids: [];
+    forks: RouteContinuation[];
+    stop?: never;
+    then?: never;
+};
 declare function isRouteConfigEntry(entry: unknown): boolean;
 /**
- * Pure RouteConfig array — every element is a RouteConfig object.
+ * Pure RouteConfig array: every element is a RouteConfig object.
  * Used to detect the legacy first-match shape (treated as implicit `one`).
  */
 declare function isRouteArray(next: Route): next is RouteConfig[];
+declare function isRouteContinuation(spec: Route | RouteContinuation): spec is RouteContinuation;
+/**
+ * The one route resolver. Resolves `spec` (a Route or a continuation handed
+ * back by an earlier call) against the resolution root `{ ingest, event }`
+ * of the position that is running.
+ *
+ * Deterministic for the SUPPLIED root only. Static tooling that needs every
+ * possible target uses `getRouteGraph`, the enumeration over the same
+ * compiled form.
+ */
+declare function getNextSteps(spec: Route | RouteContinuation | undefined, root: Root): NextSteps;
+
+/**
+ * One level of the continuation stack.
+ *
+ * - `ids` frame: resolved ids still to run, `at` is the next one.
+ * - `route` frame: a route (or a route continuation) not resolved yet. It is
+ *   resolved only when popped, i.e. with the root as the preceding step left
+ *   it. A member's own `next` is pushed as a route frame right after the
+ *   member runs.
+ *
+ * `ancestry` lists the members whose own `next` inserted this frame (outer
+ * first). A member already in its frame's ancestry is not run again: that is
+ * the cycle guard for member-next insertion. Frames of the explicit start
+ * route have an empty ancestry, so a step listed twice runs twice.
+ */
+type ChainFrame = {
+    ids: readonly string[];
+    at: number;
+    ancestry: readonly string[];
+} | {
+    route: Route | RouteContinuation;
+    ancestry: readonly string[];
+};
+/**
+ * Immutable continuation stack, top first. A fork copies it, so every copy
+ * carries the continuation of every enclosing level.
+ */
+type ChainContinuation = readonly ChainFrame[];
 /**
- * Resolve a Route spec against a matcher context. Returns the immediate
- * next transformer IDs.
- *
- * Return shape:
- *   []          → terminate (gate failed, empty many, all matchers failed,
- *                  undefined spec).
- *   ["x"]       → continue main chain at x.
- *   ["a","b",…] → fan-out, only produced by `many`. Main chain terminates
- *                  at this dispatch point; each branch is an independent
- *                  flow running to its own exit.
- *
- * Reachability vs prediction: `match` rules read arbitrary event fields.
- * `getNextSteps` is deterministic for the SUPPLIED context only. Static
- * analyzers without a real event must over-approximate by treating each
- * match as "may pass or fail" — see `flattenRouteTargets` in the CLI
- * validator. This function does NOT predict the path a future event will
- * take; it computes the path for the event you give it.
- */
-declare function getNextSteps(spec: Route | undefined, context?: Record<string, unknown>): string[];
+ * What to do next.
+ *
+ * - `run`: run step `id`, then advance `rest` with the root the step left.
+ *   `rest` already carries the member's own `next` on top (unresolved).
+ *   `ancestry` is that frame's ancestry (member included), for a caller that
+ *   pushes a further route on behalf of the member.
+ * - `fork`: run every branch to its end as an independent copy.
+ * - `stop`: this copy ends. `owner` is the member whose own route (its
+ *   `next`, or a route pushed on its behalf) resolved the stop; absent when
+ *   the stop came from the start route itself.
+ * - `done`: the path is finished.
+ */
+type ChainStep = {
+    kind: 'run';
+    id: string;
+    rest: ChainContinuation;
+    ancestry: readonly string[];
+} | {
+    kind: 'fork';
+    branches: ChainContinuation[];
+} | {
+    kind: 'stop';
+    owner?: string;
+} | {
+    kind: 'done';
+};
+/** Continuation stack for a chain field (`next`, `before`, ...). */
+declare function startChain(spec: Route | undefined): ChainContinuation;
+/**
+ * Tells a continuation stack apart from a Route. Route arrays hold ids,
+ * nested routes and route configs, never frames; an empty array means
+ * "nothing to run" either way.
+ */
+declare function isChainContinuation(value: Route | ChainContinuation): value is ChainContinuation;
+/**
+ * Advances the continuation stack to the next thing to do. Pure: no I/O and
+ * no transformer execution. Route frames are resolved through
+ * `getNextSteps` with `root`, only when popped.
+ */
+declare function advanceChain(stack: ChainContinuation, root: Root, transformers: Transformers): ChainStep;
+/**
+ * One branch of the route graph: `targets` run in order right after `from`
+ * (the position's head when `from` is absent). A branch ending in a `stop`
+ * has `stop: true`.
+ *
+ * - `kind`, `match`, `catchAll`: the decision that selected the branch, with
+ *   the SOURCE match expression (for labels and matcher path checks).
+ * - `path`: position of that decision (or plain segment) inside the raw
+ *   route; the route is the given spec, or `transformers[owner].config.next`
+ *   when `owner` is set (an inserted member `next`).
+ * - `via`: the enclosing decisions (outer first) that must also have held
+ *   to reach this branch, e.g. the `one` entry around a nested gate. Absent
+ *   when the branch sits directly under the route's head.
+ */
+interface RouteGraphNode {
+    from?: string;
+    targets: string[];
+    kind: RouteLabel['kind'];
+    match?: MatchExpression;
+    stop?: true;
+    catchAll?: true;
+    path: (string | number)[];
+    owner?: string;
+    via?: RouteDecision[];
+}
+/**
+ * Enumerates every branch of a route over the same compiled form and the
+ * same continuation stack as `advanceChain`: every `one` and `many` entry,
+ * both sides of a gate, sequence segments in order, stops marked. With
+ * `transformers`, each member's own `next` is drawn where it is inserted,
+ * and each fork continues through the rest of the path.
+ */
+declare function getRouteGraph(spec: Route | undefined, transformers?: Transformers): RouteGraphNode[];
 
 interface CompiledCacheRule {
     match: CompiledMatcher;
@@ -5305,10 +5666,11 @@ interface CacheResult {
     rule: CompiledCacheRule;
 }
 /**
- * Builds a structured context object for cache and routing operations.
- * Normalizes ingest (defaulting to {}) and optionally includes event.
+ * Builds the `{ event, ingest }` resolution root. Ingest defaults to `{}`.
+ * `event` is omitted when undefined, because `before` chains route on ingest
+ * before an event exists.
  */
-declare function buildCacheContext(ingest?: unknown, event?: unknown): Record<string, unknown>;
+declare function createMappingRoot(ingest?: Record<string, unknown>, event?: DeepPartialEvent): Root;
 declare function compileCache(cache: Cache<EventCacheRule>): CompiledCache;
 declare function checkCache(compiled: CompiledCache, store: Instance$1, context: Record<string, unknown>, namespace?: string): Promise<CacheResult | null>;
 declare function storeCache(store: Instance$1, key: string, value: unknown, ttlSeconds: number): void;
@@ -5405,13 +5767,21 @@ type GetStore = (id: string | undefined) => Instance$1 | undefined;
 declare function compileState(state: State | State[]): State[];
 /**
  * Apply declarative store operations against an event, in array order,
- * sequentially. `get` reads from the store and writes the fetched value to
- * the event's value path; `set` writes the resolved value to the store. Each
- * entry is fail-open: a store or resolution error is logged and the event is
- * left unmutated, the chain continues. Only `FatalError` rethrows (via
+ * sequentially.
+ *
+ * `key` and `value` resolve against `{ event, ingest }`, so every path names
+ * its side: `event.user.session`, `ingest.site`. `get` reads from the store
+ * and writes the fetched value to its `value` path: `event.x` onto the event
+ * (immutably), `ingest.x` into the ingest in place. An ingest write is shared
+ * by every event in the scope, so at a fan-out it loses per-event
+ * attribution. `set` writes the resolved value to the store.
+ *
+ * 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
  * `getMappingValue`).
  */
-declare function applyState<E extends DeepPartialEvent>(states: State[], getStore: GetStore, event: E, collector: Instance$6): Promise<E>;
+declare function applyState<E extends DeepPartialEvent>(states: State[], getStore: GetStore, event: E, collector: Instance$6, ingest: Record<string, unknown> | undefined): Promise<E>;
 
 /**
  * Single source of truth for step-entry validation across all four kinds.
@@ -5428,7 +5798,63 @@ declare function applyState<E extends DeepPartialEvent>(states: State[], getStor
  * - INVALID_IMPORT       `import` is set but is not a valid JS identifier
  * - INVALID_CODE_SHAPE   `code` is present but is neither an object nor a string
  */
-declare const STEP_OPERATIVE_FIELDS: Record<Flow.StepKind, readonly string[]>;
+/**
+ * The Flow step interface for each step kind.
+ */
+interface StepByKind {
+    Source: Flow.Source;
+    Transformer: Flow.Transformer;
+    Destination: Flow.Destination;
+    Store: Flow.Store;
+}
+/** A declared field name of the Flow step interface for `K`. */
+type StepField<K extends Flow.StepKind> = keyof StepByKind[K] & string;
+/**
+ * Lifecycle role of a declared step field.
+ *
+ * - `reference`: selects the implementation (`code`, `package`, `import`).
+ *   The bundler turns it into the emitted `code` value; it is never emitted
+ *   as-is.
+ * - `resolve`: consumed by flow resolution (the variable cascade). Kept on the
+ *   resolved flow, never emitted into a bundle.
+ * - `docs`: consumed by validate/simulate/test tooling. Stripped at flow
+ *   resolution, never emitted.
+ * - `runtime`: must reach the collector unchanged, on every emission path
+ *   (package step, inline code step, code-free path step).
+ */
+type StepFieldRole = 'reference' | 'resolve' | 'docs' | 'runtime';
+/**
+ * Single source of truth for what happens to each declared step field between
+ * the flow file and the running collector. Flow resolution (`getFlowSettings`)
+ * and the CLI bundler both derive their field handling from this table instead
+ * of hand-written field lists.
+ *
+ * Each entry is typed as a complete map over the Flow step interface, so adding
+ * a field to `Flow.Source` / `Flow.Transformer` / `Flow.Destination` /
+ * `Flow.Store` is a compile error here until the field is classified.
+ */
+declare const STEP_FIELD_ROLES: {
+    readonly [K in Flow.StepKind]: Readonly<Record<StepField<K>, StepFieldRole>>;
+};
+/**
+ * Role of `field` on a step of `kind`, or `undefined` when the field is not a
+ * declared Flow step field.
+ */
+declare function getStepFieldRole(kind: Flow.StepKind, field: string): StepFieldRole | undefined;
+/**
+ * The runtime fields of a step entry: every declared field classified as
+ * `runtime` whose value is set. This is what the bundler must emit for the
+ * step, whatever its emission path.
+ */
+declare function getStepRuntimeProps(step: object, kind: Flow.StepKind): Record<string, unknown>;
+/**
+ * Fields whose presence makes an entry operative (a real step rather than an
+ * empty no-op). Each is a declared Flow step field; see `STEP_FIELD_ROLES` for
+ * its lifecycle.
+ */
+declare const STEP_OPERATIVE_FIELDS: {
+    readonly [K in Flow.StepKind]: readonly StepField<K>[];
+};
 type StepEntryErrorCode = 'UNKNOWN_KEY' | 'CONFLICT' | 'MISSING_PACKAGE' | 'OBSOLETE_CODE_STRING' | 'INVALID_IMPORT' | 'INVALID_CODE_SHAPE';
 interface StepEntryValidation {
     ok: boolean;
@@ -5484,4 +5910,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 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, 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 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, SECRET_MARKER_PREFIX, SESSION_STORAGE_KEY, 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 StepKind, type StorageType, store as Store, StoreCodecError, type SwapActivatorConfig, type TelemetryLevel, type TelemetryOptions, type TelemetryOptionsSupplier, transformer as Transformer, trigger as Trigger, URL_WINDOW_MS, type ValidateEvents, type VerifyParams, type VerifyResult, walkeros as WalkerOS, type WalkerOSPackage, type WalkerOSPackageInfo, type WalkerOSPackageMeta, anonymizeIP, applyState, applyUpdate, assembleJourneys, assign, batchResponse, branch, browserSwapActivator, buildCacheContext, buildScopeFromNodeRequest, castToProperty, castValue, checkCache, clone, compileCache, compileMatcher, compileState, createBatchedPoster, createDestination, createEvent, createIngest, createLogger, createMockContext, createMockLogger, createRespond, createTelemetryObserver, debounce, deepMerge, defaultClickIds, deleteByPath, deserializeStoreValue, emitStep, fetchPackage, fetchPackageSchema, filterValues, flattenIncludeSections, formatOut, getBrowser, getBrowserVersion, getByPath, getDeviceType, getEvent, getFlowSettings, getGrantedConsent, getHeaders, getId, getMappingEvent, getMappingValue, getMarketingParameters, getNextSteps, getOS, getOSVersion, getPlatform, getSpanId, getTraceId, getTraceUntil, isArguments, isArray, isBatchBody, isBoolean, isCommand, isDefined, isElementOrDocument, isEnvObserve, isFunction, isNumber, isObject, isPathStepEntry, isPropertyType, isRouteArray, isRouteConfigEntry, 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, 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, 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 };