@walkeros/core 4.1.0-next-1778668930820 → 4.1.0

package/dist/index.d.mts

@@ -38,9 +38,15 @@ interface Rules<T = Rule> {
     [entity: string]: Record<string, T | Array<T>> | undefined;
 }
 interface Rule<Settings = unknown> {
-    batch?: number;
-    batchFn?: (destination: Instance$5, collector: Instance$6) => void;
-    batched?: Batch<Settings>;
+    /**
+     * Batch scheduling for this event mapping. A bare number is the
+     * debounce `wait` window (legacy form). Object form supports `wait`
+     * (debounce ms), `size` (count cap), and `age` (max ms since first
+     * entry). Destination-level `config.batch` provides upper bounds
+     * applied at scheduler creation; mapping-level values override
+     * destination-level for matched events.
+     */
+    batch?: number | BatchOptions;
     condition?: Condition;
     consent?: Consent;
     settings?: Settings;
@@ -99,16 +105,21 @@ 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_Rules as Rules, Validate$1 as Validate, mapping_Value as Value, mapping_ValueConfig as ValueConfig, mapping_ValueType as ValueType, mapping_Values as Values };
 }
 
-interface CacheRule {
+interface BaseCacheRule {
     /**
      * Optional match expression. Omitted means always-match.
      */
     match?: MatchExpression;
-    key: string[];
     ttl: number;
+}
+interface EventCacheRule extends BaseCacheRule {
+    key: string[];
     update?: Record<string, Value>;
 }
-interface Cache {
+interface StoreCacheRule extends BaseCacheRule {
+}
+type CacheRule = EventCacheRule | StoreCacheRule;
+interface Cache<R extends CacheRule = CacheRule> {
     /**
      * Stop the chain on cache HIT (default: false). When true, skip remaining steps and return cached value.
      */
@@ -118,13 +129,15 @@ interface Cache {
      * Optional key prefix written to the store. When absent, cache keys are written directly. Same store + same key + same namespace = same cache entry.
      */
     namespace?: string;
-    rules: CacheRule[];
+    rules: R[];
 }
 
-type cache_Cache = Cache;
+type cache_Cache<R extends CacheRule = CacheRule> = Cache<R>;
 type cache_CacheRule = CacheRule;
+type cache_EventCacheRule = EventCacheRule;
+type cache_StoreCacheRule = StoreCacheRule;
 declare namespace cache {
-  export type { cache_Cache as Cache, cache_CacheRule as CacheRule };
+  export type { cache_Cache as Cache, cache_CacheRule as CacheRule, cache_EventCacheRule as EventCacheRule, cache_StoreCacheRule as StoreCacheRule };
 }
 
 /**
@@ -182,6 +195,28 @@ interface Ingest {
 /** Create a fresh Ingest for a new pipeline invocation. */
 declare function createIngest(sourceId: string): Ingest;
 
+/** Identifies which kind of step a stepId belongs to. */
+type StepKind = 'collector' | 'source' | 'transformer' | 'destination';
+/**
+ * Build a stepId for use as a key in `Status.dropped` (and future
+ * status maps). The collector-level stepId is the literal "collector"
+ * (no id). Source/transformer/destination ids take the form
+ * `"<kind>.<id>"`, e.g. `"destination.ga4"`.
+ *
+ * The dot separator mirrors the vocabulary already used in collector
+ * log messages ("collector.queue overflow", "destination.dlq overflow").
+ */
+declare function stepId(kind: 'collector'): 'collector';
+declare function stepId(kind: 'source' | 'transformer' | 'destination', id: string): string;
+/**
+ * Drop counters at a single step. Each buffer is optional: a step kind
+ * may have only `queue` (collector), only `dlq`, both (destinations
+ * today), or neither. Counts are monotonic.
+ */
+interface DroppedCounters {
+    queue?: number;
+    dlq?: number;
+}
 /**
  * Core collector configuration interface
  */
@@ -194,6 +229,11 @@ interface Config$6 {
     sessionStatic: Partial<SessionData>;
     /** Logger configuration */
     logger?: Config$3;
+    /**
+     * Maximum number of events retained in `collector.queue` for late-registered
+     * destination backfill. Overflow drops oldest (FIFO). Default 1000.
+     */
+    queueMax?: number;
 }
 /**
  * Initialization configuration that extends Config with initial state
@@ -237,6 +277,16 @@ interface Status {
     failed: number;
     sources: Record<string, SourceStatus>;
     destinations: Record<string, DestinationStatus>;
+    /**
+     * Monotonic counts of events dropped due to buffer caps, keyed by
+     * stepId. See `stepId()` for key construction.
+     *
+     * Examples:
+     *  - `dropped["collector"]?.queue`: collector replay buffer drops
+     *  - `dropped["destination.ga4"]?.queue`: ga4's consent-denied buffer drops
+     *  - `dropped["destination.ga4"]?.dlq`: ga4's dead-letter queue drops
+     */
+    dropped: Record<string, DroppedCounters>;
 }
 interface SourceStatus {
     count: number;
@@ -248,6 +298,17 @@ interface DestinationStatus {
     failed: number;
     lastAt?: number;
     duration: number;
+    /** Current size of the destination's queuePush buffer (point-in-time). */
+    queuePushSize: number;
+    /** Current size of the destination's DLQ (point-in-time). */
+    dlqSize: number;
+    /**
+     * Number of events buffered in batch scheduler windows but not yet
+     * delivered to `pushBatch`. Incremented on enqueue, decremented on
+     * flush (whether the flush succeeds or fails). Operators read this
+     * to spot batches that never drain.
+     */
+    inFlightBatch?: number;
 }
 interface Sources {
     [id: string]: Instance$2;
@@ -287,9 +348,15 @@ interface PushFn$1 {
 interface CommandFn {
     (command: 'config', config: Partial<Config$6>): Promise<PushResult>;
     (command: 'consent', consent: Consent): Promise<PushResult>;
-    <T extends Types$4>(command: 'destination', destination: Init$3<T> | Instance$5<T>, config?: Config$5<T>): Promise<PushResult>;
-    <K extends keyof Functions>(command: 'hook', name: K, hookFn: Functions[K]): Promise<PushResult>;
-    (command: 'on', type: Types$2, rules: SingleOrArray<Subscription>): Promise<PushResult>;
+    <T extends Types$4>(command: 'destination', init: Init$3<T>): Promise<PushResult>;
+    <K extends keyof Functions>(command: 'hook', init: {
+        name: K;
+        fn: Functions[K];
+    }): Promise<PushResult>;
+    (command: 'on', init: {
+        type: Types$2;
+        rules: SingleOrArray<Subscription>;
+    }): Promise<PushResult>;
     (command: 'user', user: User): Promise<PushResult>;
     (command: 'run', runState?: {
         consent?: Consent;
@@ -297,7 +364,7 @@ interface CommandFn {
         globals?: Properties;
         custom?: Properties;
     }): Promise<PushResult>;
-    (command: string, data?: unknown, options?: unknown): Promise<PushResult>;
+    (command: string, data?: unknown): Promise<PushResult>;
 }
 interface Instance$6 {
     push: PushFn$1;
@@ -328,14 +395,17 @@ interface Instance$6 {
 type collector_CommandFn = CommandFn;
 type collector_CommandType = CommandType;
 type collector_DestinationStatus = DestinationStatus;
+type collector_DroppedCounters = DroppedCounters;
 type collector_InitConfig = InitConfig;
 type collector_PushOptions = PushOptions;
 type collector_SessionData = SessionData;
 type collector_SourceStatus = SourceStatus;
 type collector_Sources = Sources;
 type collector_Status = Status;
+type collector_StepKind = StepKind;
+declare const collector_stepId: typeof stepId;
 declare namespace collector {
-  export type { collector_CommandFn as CommandFn, collector_CommandType as CommandType, Config$6 as Config, collector_DestinationStatus as DestinationStatus, Destinations$1 as Destinations, collector_InitConfig as InitConfig, Instance$6 as Instance, PushFn$1 as PushFn, collector_PushOptions as PushOptions, collector_SessionData as SessionData, collector_SourceStatus as SourceStatus, collector_Sources as Sources, collector_Status as Status, Stores$1 as Stores, Transformers$1 as Transformers };
+  export { type collector_CommandFn as CommandFn, type collector_CommandType as CommandType, type Config$6 as Config, type collector_DestinationStatus as DestinationStatus, type Destinations$1 as Destinations, type collector_DroppedCounters as DroppedCounters, type collector_InitConfig as InitConfig, type Instance$6 as Instance, type PushFn$1 as PushFn, type collector_PushOptions as PushOptions, type collector_SessionData as SessionData, type collector_SourceStatus as SourceStatus, type collector_Sources as Sources, type collector_Status as Status, type collector_StepKind as StepKind, type Stores$1 as Stores, type Transformers$1 as Transformers, collector_stepId as stepId };
 }
 
 /**
@@ -511,15 +581,48 @@ interface Config$5<T extends TypesGeneric$3 = Types$4> {
      */
     setup?: boolean | SetupOptions$2<T>;
     /** Transformer chain to run after collector processing but before this destination. */
-    before?: RouteSpec;
+    before?: Route;
     /** Transformer chain to run after destination push completes. Push response available at ingest._response. */
-    next?: RouteSpec;
+    next?: Route;
     /** Cache configuration for deduplication (step-level: skip push on HIT). */
     cache?: Cache;
     /** Completely skip this destination — no init, no push, no queuing. */
     disabled?: boolean;
     /** Return this value instead of calling push(). Uses !== undefined check to support falsy values. */
     mock?: unknown;
+    /**
+     * Maximum number of consent-denied events retained in `queuePush` for
+     * this destination. Overflow drops oldest (FIFO). Default 1000.
+     */
+    queueMax?: number;
+    /**
+     * Maximum number of failed-push entries retained in `dlq` for this
+     * destination. Overflow drops oldest (FIFO). Default 100.
+     */
+    dlqMax?: number;
+    /**
+     * Per-destination batch upper bounds. Supplements the mapping-level
+     * `batch` setting on individual rules. A bare number is treated as
+     * the debounce `wait` window (legacy compat).
+     *
+     * - `wait`: debounce window in ms; the timer resets on every push.
+     * - `size`: hard count cap; flush immediately when entries reach this number. Default 1000 when batching is enabled.
+     * - `age`: time since the first entry of the current window. Forces a flush even if pushes keep arriving. Default 30000 (30s).
+     */
+    batch?: number | BatchOptions;
+}
+/**
+ * Batch scheduling options. Used at both the mapping-rule layer
+ * (`Mapping.Rule.batch`) and the destination-config layer
+ * (`Destination.Config.batch`). Same shape at both layers.
+ */
+interface BatchOptions {
+    /** Debounce window in ms. Timer resets on every push. */
+    wait?: number;
+    /** Hard count cap. Flushes immediately at this size. */
+    size?: number;
+    /** Hard age cap in ms since first entry of current window. */
+    age?: number;
 }
 type PartialConfig$2<T extends TypesGeneric$3 = Types$4> = Config$5<Types$4<Partial<Settings$3<T>> | Settings$3<T>, Partial<Mapping$1<T>> | Mapping$1<T>, Env$3<T>, InitSettings$3<T>, SetupOptions$2<T>>>;
 interface Policy {
@@ -530,8 +633,8 @@ type Init$3<T extends TypesGeneric$3 = Types$4> = {
     code: Code$1<T>;
     config?: Partial<Config$5<T>>;
     env?: Partial<Env$3<T>>;
-    before?: RouteSpec;
-    next?: RouteSpec;
+    before?: Route;
+    next?: Route;
     cache?: Cache;
     validate?: Validate;
 };
@@ -565,9 +668,24 @@ type PushEvent<Mapping = unknown> = {
     mapping?: Rule<Mapping>;
 };
 type PushEvents<Mapping = unknown> = Array<PushEvent<Mapping>>;
+interface BatchEntry<Mapping = unknown> {
+    event: Event;
+    ingest?: Ingest;
+    respond?: RespondFn;
+    rule?: Rule<Mapping>;
+    data?: Data;
+}
 interface Batch<Mapping> {
     key: string;
+    /**
+     * Per-event entries carrying per-event ingest, respond, rule, and data.
+     * Destinations needing per-event metadata should read this instead of
+     * (or in addition to) `events` and `data`.
+     */
+    entries: BatchEntry<Mapping>[];
+    /** Derived view: events from `entries`. Kept for back-compat. */
     events: Events;
+    /** Derived view: data from `entries`. Kept for back-compat. */
     data: Array<Data>;
     mapping?: Rule<Mapping>;
 }
@@ -575,6 +693,12 @@ interface BatchRegistry<Mapping> {
     [mappingKey: string]: {
         batched: Batch<Mapping>;
         batchFn: () => void;
+        /**
+         * Force a flush of the current batch immediately. Used by shutdown
+         * drain and by tests for deterministic flushing without timer
+         * advancement. Resolves after the underlying `pushBatch` settles.
+         */
+        flush: () => Promise<void>;
     };
 }
 type Data = Property | undefined | Array<Property | undefined>;
@@ -588,8 +712,29 @@ type Push$1 = {
     error?: unknown;
 };
 type DLQ = Array<[Event, unknown]>;
+/**
+ * Typed accessor for destinations registered on a collector.
+ *
+ * The collector's `destinations` bag indexes to `Destination.Instance`
+ * (defaults erase the generic). Use this helper at the call site to recover
+ * the narrow type without casts.
+ *
+ * @example
+ * type MyDestTypes = Destination.Types<MySettings, MyMapping>;
+ * const dest = getDestination<MyDestTypes>(collector, 'myDest');
+ * await dest.push(event, context);
+ *
+ * @throws Error with message `Destination not found: <id>` when the id is unknown.
+ */
+declare function getDestination<T extends TypesGeneric$3 = Types$4>(collector: {
+    destinations: {
+        [id: string]: Instance$5<any>;
+    };
+}, id: string): Instance$5<T>;
 
 type destination_Batch<Mapping> = Batch<Mapping>;
+type destination_BatchEntry<Mapping = unknown> = BatchEntry<Mapping>;
+type destination_BatchOptions = BatchOptions;
 type destination_BatchRegistry<Mapping> = BatchRegistry<Mapping>;
 type destination_DLQ = DLQ;
 type destination_Data = Data;
@@ -603,8 +748,9 @@ type destination_PushEvent<Mapping = unknown> = PushEvent<Mapping>;
 type destination_PushEvents<Mapping = unknown> = PushEvents<Mapping>;
 type destination_PushFn<T extends TypesGeneric$3 = Types$4> = PushFn<T>;
 type destination_Ref = Ref;
+declare const destination_getDestination: typeof getDestination;
 declare namespace destination {
-  export type { BaseEnv$3 as BaseEnv, destination_Batch as Batch, destination_BatchRegistry as BatchRegistry, Code$1 as Code, Config$5 as Config, Context$5 as Context, destination_DLQ as DLQ, destination_Data as Data, destination_Destinations as Destinations, Env$3 as Env, Init$3 as Init, destination_InitDestinations as InitDestinations, InitFn$2 as InitFn, InitSettings$3 as InitSettings, Instance$5 as Instance, Mapping$1 as Mapping, PartialConfig$2 as PartialConfig, destination_Policy as Policy, Push$1 as Push, destination_PushBatchContext as PushBatchContext, destination_PushBatchFn as PushBatchFn, destination_PushContext as PushContext, destination_PushEvent as PushEvent, destination_PushEvents as PushEvents, destination_PushFn as PushFn, destination_Ref as Ref, Settings$3 as Settings, SetupOptions$2 as SetupOptions, Types$4 as Types, TypesGeneric$3 as TypesGeneric, TypesOf$3 as TypesOf };
+  export { type BaseEnv$3 as BaseEnv, type destination_Batch as Batch, type destination_BatchEntry as BatchEntry, type destination_BatchOptions as BatchOptions, type destination_BatchRegistry as BatchRegistry, type Code$1 as Code, type Config$5 as Config, type Context$5 as Context, type destination_DLQ as DLQ, type destination_Data as Data, type destination_Destinations as Destinations, type Env$3 as Env, type Init$3 as Init, type destination_InitDestinations as InitDestinations, type InitFn$2 as InitFn, type InitSettings$3 as InitSettings, type Instance$5 as Instance, type Mapping$1 as Mapping, type PartialConfig$2 as PartialConfig, type destination_Policy as Policy, type Push$1 as Push, type destination_PushBatchContext as PushBatchContext, type destination_PushBatchFn as PushBatchFn, type destination_PushContext as PushContext, type destination_PushEvent as PushEvent, type destination_PushEvents as PushEvents, type destination_PushFn as PushFn, type destination_Ref as Ref, type Settings$3 as Settings, type SetupOptions$2 as SetupOptions, type Types$4 as Types, type TypesGeneric$3 as TypesGeneric, type TypesOf$3 as TypesOf, destination_getDestination as getDestination };
 }
 
 interface EventFn<R = Promise<PushResult>> {
@@ -617,11 +763,17 @@ interface Fn$3<R = Promise<PushResult>, Config = unknown> extends EventFn<R>, Wa
 interface WalkerCommands<R = Promise<PushResult>, Config = unknown> {
     (event: 'walker config', config: Partial<Config>): R;
     (event: 'walker consent', consent: Consent): R;
-    <T extends Types$4>(event: 'walker destination', destination: Init$3<T> | Instance$5<T>, config?: Config$5<T>): R;
-    <K extends keyof Functions>(event: 'walker hook', name: K, hookFn: Functions[K]): R;
-    (event: 'walker on', type: Types$2, rules: SingleOrArray<Subscription>): R;
+    <T extends Types$4>(event: 'walker destination', init: Init$3<T>): R;
+    <K extends keyof Functions>(event: 'walker hook', init: {
+        name: K;
+        fn: Functions[K];
+    }): R;
+    (event: 'walker on', init: {
+        type: Types$2;
+        rules: SingleOrArray<Subscription>;
+    }): R;
     (event: 'walker user', user: User): R;
-    (event: 'walker run', runState: {
+    (event: 'walker run', runState?: {
         consent?: Consent;
         user?: User;
         globals?: Properties;
@@ -650,38 +802,48 @@ declare namespace elb {
 
 /**
  * Unified route grammar for Flow v4. A `Route` is one of:
- * - a string transformer ID (`"redact"`)
+ * - a transformer ID string (`"redact"`)
  * - a sequence of routes (`["a", "b", "c"]` — sugar for chained `.next`)
  * - a `RouteConfig` — a gated / dispatching node.
  *
- * `RouteConfig` is a disjoint union: a single config may set either `next`,
- * `case`, or neither (pure gate), but never more than one operator.
+ * `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.
  *
- * The `branch` operator from the design plan is intentionally absent until
- * `docs/plans/2026-05-12-route-branch-semantics-design.md` resolves.
+ * 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).
  */
 type Route = string | Route[] | RouteConfig;
-type RouteConfig = RouteNextConfig | RouteCaseConfig | RouteGateConfig;
+type RouteConfig = RouteNextConfig | RouteOneConfig | RouteManyConfig | RouteGateConfig;
 interface RouteNextConfig {
     match?: MatchExpression;
     next: Route;
-    case?: never;
+    one?: never;
+    many?: never;
+}
+interface RouteOneConfig {
+    match?: MatchExpression;
+    one: Route[];
+    next?: never;
+    many?: never;
 }
-interface RouteCaseConfig {
+interface RouteManyConfig {
     match?: MatchExpression;
-    case: Route[];
+    many: Route[];
     next?: never;
+    one?: never;
 }
 interface RouteGateConfig {
     match: MatchExpression;
     next?: never;
-    case?: never;
+    one?: never;
+    many?: never;
 }
-/**
- * Backward-compatible alias. New code should use `Route` directly.
- * Kept for compatibility with existing imports across the codebase.
- */
-type RouteSpec = Route;
 /**
  * Base environment interface for walkerOS transformers.
  *
@@ -731,8 +893,8 @@ interface Config$4<T extends TypesGeneric$2 = Types$3> {
     env?: Env$2<T>;
     id?: string;
     logger?: Config$3;
-    before?: RouteSpec;
-    next?: RouteSpec;
+    before?: Route;
+    next?: Route;
     cache?: Cache;
     init?: boolean;
     disabled?: boolean;
@@ -776,7 +938,7 @@ interface Context$4<T extends TypesGeneric$2 = Types$3> extends Base<Config$4<T>
 interface Result$1<E = DeepPartialEvent> {
     event?: E;
     respond?: RespondFn;
-    next?: RouteSpec;
+    next?: Route;
 }
 /**
  * Result of running a transformer chain.
@@ -846,13 +1008,13 @@ type InitTransformer<T extends TypesGeneric$2 = Types$3> = {
      *
      * Validation: an entry without `code` must declare at least one of
      * `package`, `before`, `next`, `cache`, `mapping`. Enforced by
-     * `validateTransformerEntry` in `@walkeros/core`.
+     * `validateStepEntry` in `@walkeros/core`.
      */
     code?: Init$2<T>;
     config?: Partial<Config$4<T>>;
     env?: Partial<Env$2<T>>;
-    before?: RouteSpec;
-    next?: RouteSpec;
+    before?: Route;
+    next?: Route;
     cache?: Cache;
     mapping?: Config$7;
     validate?: Validate;
@@ -870,21 +1032,80 @@ interface InitTransformers {
 interface Transformers {
     [transformerId: string]: Instance$4;
 }
+/**
+ * Typed accessor for transformers registered on a collector.
+ *
+ * The collector's `transformers` bag indexes to `Transformer.Instance`
+ * (defaults erase the generic). Use this helper at the call site to recover
+ * the narrow type without casts.
+ *
+ * @example
+ * type MyTransformerTypes = Transformer.Types<MySettings>;
+ * const tx = getTransformer<MyTransformerTypes>(collector, 'redact');
+ * await tx.push(event, context);
+ *
+ * @throws Error with message `Transformer not found: <id>` when the id is unknown.
+ */
+declare function getTransformer<T extends TypesGeneric$2 = Types$3>(collector: {
+    transformers: {
+        [id: string]: Instance$4<any>;
+    };
+}, id: string): Instance$4<T>;
 
 type transformer_ChainResult = ChainResult;
 type transformer_InitTransformer<T extends TypesGeneric$2 = Types$3> = InitTransformer<T>;
 type transformer_InitTransformers = InitTransformers;
 type transformer_Route = Route;
-type transformer_RouteCaseConfig = RouteCaseConfig;
 type transformer_RouteConfig = RouteConfig;
 type transformer_RouteGateConfig = RouteGateConfig;
+type transformer_RouteManyConfig = RouteManyConfig;
 type transformer_RouteNextConfig = RouteNextConfig;
-type transformer_RouteSpec = RouteSpec;
+type transformer_RouteOneConfig = RouteOneConfig;
 type transformer_Transformers = Transformers;
+declare const transformer_getTransformer: typeof getTransformer;
 declare namespace transformer {
-  export type { BaseEnv$2 as BaseEnv, transformer_ChainResult as ChainResult, Config$4 as Config, Context$4 as Context, Env$2 as Env, Fn$2 as Fn, Init$2 as Init, InitFn$1 as InitFn, InitSettings$2 as InitSettings, transformer_InitTransformer as InitTransformer, transformer_InitTransformers as InitTransformers, Instance$4 as Instance, Result$1 as Result, transformer_Route as Route, transformer_RouteCaseConfig as RouteCaseConfig, transformer_RouteConfig as RouteConfig, transformer_RouteGateConfig as RouteGateConfig, transformer_RouteNextConfig as RouteNextConfig, transformer_RouteSpec as RouteSpec, Settings$2 as Settings, transformer_Transformers as Transformers, Types$3 as Types, TypesGeneric$2 as TypesGeneric, TypesOf$2 as TypesOf };
+  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 };
 }
 
+/**
+ * Flow Configuration System (v4)
+ *
+ * Core types for walkerOS unified configuration.
+ * Platform-agnostic, runtime-focused.
+ *
+ * The Flow system enables "one config to rule them all" - a single
+ * walkeros.config.json file that manages multiple flows
+ * (web_prod, web_stage, server_prod, etc.) with shared configuration
+ * and reusable variables.
+ *
+ * Single declaration merge: `Flow` is both the interface for one flow
+ * and the namespace holding all related types.
+ *
+ * ## Connection Rules
+ *
+ * Sources use `next` to connect to transformers (pre-collector chain).
+ * 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).
+ * 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.
+ *
+ * Circular `next` references are safely handled at runtime by `walkChain()`
+ * in the collector module (visited-set detection).
+ *
+ * ```
+ * Source → [before → Preprocessing] → [next → Transformer chain] → Collector → [before → Transformer chain] → Destination → [next → Post-push]
+ * ```
+ *
+ * @packageDocumentation
+ */
+
 /**
  * Single flow configuration.
  *
@@ -1139,13 +1360,27 @@ declare namespace Flow {
          */
         package?: string;
         /**
-         * Resolved import variable name (string) or inline code definition (Code).
+         * Inline code definition (object form only).
+         *
+         * Object: `{push, type?, init?}` for inline code definition.
+         * For named-export selection from a package, use the `import` field with `package`.
+         */
+        code?: Code;
+        /**
+         * Named export from `package` to import as this source's implementation.
+         *
+         * Requires `package` to be set. Mutually exclusive with `code`.
          *
-         * - String: auto-resolved from packages[package].imports[0] during getFlowSettings(),
-         *   or provided explicitly for advanced use cases.
-         * - Code: object with type, push, and optional init for inline code definition.
+         * - Top-level identifier only: `/^[A-Za-z_$][A-Za-z0-9_$]*$/`. No dotted paths.
+         * - `package: "X"` alone (no `import`, no `code`) loads X's default export.
+         * - `package: "X"` + `import: "fooFactory"` loads named export `fooFactory` from X.
+         *
+         * @example
+         * ```json
+         * { "package": "@walkeros/web-source-browser", "import": "sourceBrowser" }
+         * ```
          */
-        code?: string | Code;
+        import?: string;
         /**
          * Source-specific configuration. Structure depends on the source package.
          * Passed to the source's initialization function.
@@ -1173,7 +1408,7 @@ declare namespace Flow {
          * (decode, validate, authenticate, normalize raw input).
          * Raw request data is available in context.ingest.
          */
-        before?: RouteSpec;
+        before?: Route;
         /**
          * First transformer in pre-collector chain.
          *
@@ -1182,9 +1417,9 @@ declare namespace Flow {
          * If omitted, events route directly to the collector.
          * Can be an array for explicit chain control (bypasses transformer.next resolution).
          */
-        next?: RouteSpec;
+        next?: Route;
         /** Cache configuration for this source. */
-        cache?: Cache;
+        cache?: Cache<EventCacheRule>;
         validate?: Validate;
         /**
          * Source-level variables (highest priority in cascade).
@@ -1206,8 +1441,23 @@ declare namespace Flow {
     interface Destination {
         /** Package specifier with optional version. Optional when `code` is provided. */
         package?: string;
-        /** Resolved import variable name (string) or inline code definition (Code). */
-        code?: string | Code;
+        /**
+         * Inline code definition (object form only).
+         *
+         * Object: `{push, type?, init?}` for inline code definition.
+         * For named-export selection from a package, use the `import` field with `package`.
+         */
+        code?: Code;
+        /**
+         * Named export from `package` to import as this destination's implementation.
+         * See `Flow.Source.import` for full rules.
+         *
+         * @example
+         * ```json
+         * { "package": "@walkeros/web-destination-gtag", "import": "destinationGtag" }
+         * ```
+         */
+        import?: string;
         /**
          * Destination-specific configuration. Typically includes:
          * - settings: API keys, IDs, endpoints
@@ -1225,7 +1475,7 @@ declare namespace Flow {
          * If omitted, events are sent directly from the collector.
          * Can be an array for explicit chain control.
          */
-        before?: RouteSpec;
+        before?: Route;
         /**
          * First transformer in post-push chain.
          *
@@ -1233,9 +1483,9 @@ declare namespace Flow {
          * at context.ingest._response. Consent is inherited from the destination
          * gate - no separate consent check needed.
          */
-        next?: RouteSpec;
+        next?: Route;
         /** Cache configuration for this destination. */
-        cache?: Cache;
+        cache?: Cache<EventCacheRule>;
         validate?: Validate;
         /** Destination-level variables (highest priority in cascade). */
         variables?: Variables;
@@ -1254,8 +1504,23 @@ declare namespace Flow {
     interface Transformer {
         /** Package specifier with optional version. Optional when `code` is provided. */
         package?: string;
-        /** Resolved import variable name (string) or inline code definition (Code). */
-        code?: string | Code;
+        /**
+         * Inline code definition (object form only).
+         *
+         * Object: `{push, type?, init?}` for inline code definition.
+         * For named-export selection from a package, use the `import` field with `package`.
+         */
+        code?: Code;
+        /**
+         * Named export from `package` to import as this transformer's implementation.
+         * See `Flow.Source.import` for full rules.
+         *
+         * @example
+         * ```json
+         * { "package": "@walkeros/transformer-ga4", "import": "transformerGa4" }
+         * ```
+         */
+        import?: string;
         /** Transformer-specific configuration. Structure depends on the package. */
         config?: unknown;
         /** Transformer environment configuration. */
@@ -1267,7 +1532,7 @@ declare namespace Flow {
          * Enables pre-processing or context loading before the main transform.
          * Uses the same chain resolution as source.next and destination.before.
          */
-        before?: RouteSpec;
+        before?: Route;
         /**
          * Next transformer in chain.
          *
@@ -1278,9 +1543,9 @@ declare namespace Flow {
          * Array values define an explicit chain (no walking). Circular references
          * are safely detected at runtime by `walkChain()`.
          */
-        next?: RouteSpec;
+        next?: Route;
         /** Cache configuration for this transformer. */
-        cache?: Cache;
+        cache?: Cache<EventCacheRule>;
         validate?: Validate;
         /** Transformer-level variables (highest priority in cascade). */
         variables?: Variables;
@@ -1300,12 +1565,35 @@ declare namespace Flow {
     interface Store {
         /** Package specifier with optional version. Optional when `code` is provided. */
         package?: string;
-        /** Resolved import variable name (string) or inline code definition (Code). */
-        code?: string | Code;
+        /**
+         * Inline code definition (object form only).
+         *
+         * Object: `{push, type?, init?}` for inline code definition.
+         * For named-export selection from a package, use the `import` field with `package`.
+         */
+        code?: Code;
+        /**
+         * Named export from `package` to import as this store's implementation.
+         * See `Flow.Source.import` for full rules.
+         *
+         * @example
+         * ```json
+         * { "package": "@walkeros/server-store-fs", "import": "storeFs" }
+         * ```
+         */
+        import?: string;
         /** Store-specific configuration. */
         config?: unknown;
         /** Store environment configuration. */
         env?: unknown;
+        /**
+         * Cache configuration for this store.
+         *
+         * When present, the collector wraps the bare store with a cache layer
+         * (read-through, write-through, single-flight). The cache layer may
+         * recursively delegate to another store via `cache.store`.
+         */
+        cache?: Cache<StoreCacheRule>;
         /** Store-level variables (highest priority in cascade). */
         variables?: Variables;
         /**
@@ -1816,6 +2104,24 @@ interface Instance$2<T extends TypesGeneric$1 = Types$1> {
         data: unknown;
     }>;
 }
+/**
+ * Per-scope environment passed to the body of `Source.Context.withScope`.
+ *
+ * Each call to `withScope` builds a fresh `ScopeEnv` whose `push` captures
+ * the per-scope `ingest` and `respond`. Concurrent scopes cannot crosstalk:
+ * each one carries its own ingest and respond all the way through the
+ * pipeline. Server sources MUST use `withScope` per inbound request; sources
+ * with a single logical scope (browser tab lifetime, dataLayer) may skip it
+ * and use the factory-scope `env.push` directly.
+ */
+type ScopeEnv<T extends TypesGeneric$1 = Types$1> = Env$1<T> & {
+    /** Per-scope push: captures the scope's ingest and respond for this call. */
+    push: PushFn$1;
+    /** Ingest metadata extracted from the raw scope input (if config.ingest is set). */
+    ingest: Ingest;
+    /** Respond function bound to this scope (undefined for scopes without a response). */
+    respond?: RespondFn;
+};
 /**
  * Context provided to source init function.
  * Extends base context with source-specific properties.
@@ -1823,15 +2129,31 @@ interface Instance$2<T extends TypesGeneric$1 = Types$1> {
 interface Context$1<T extends TypesGeneric$1 = Types$1> extends Base<Partial<Config$1<T>>, Env$1<T>> {
     id: string;
     /**
-     * Sets ingest metadata for the current request.
-     * Extracts values from the raw request using config.ingest mapping.
-     * The extracted data is passed through to transformers and destinations.
+     * Bind ingest and respond to a single scope of work (e.g. one inbound
+     * HTTP request, one queue message). Builds a fresh `Ingest` from the
+     * raw input via `config.ingest` mapping, wires the per-scope `respond`,
+     * and invokes `body(scopeEnv)` with a push function that captures both.
+     *
+     * Server sources call this once per inbound request:
+     *
+     * ```ts
+     * await context.withScope(req, createRespond(sender), async (env) => {
+     *   await env.push(parsedData);
+     * });
+     * ```
+     *
+     * Browser sources with a single tab-lifetime scope may skip `withScope`
+     * and use `env.push` directly.
      *
-     * @param value - Raw request object (Express req, Lambda event, etc.)
+     * @param rawScope - Raw input for `config.ingest` mapping (Express req,
+     *   Lambda event, fetch Request, etc.). Pass `undefined` if no ingest
+     *   mapping applies.
+     * @param respond - Per-scope respond function, or `undefined` if the
+     *   scope produces no response.
+     * @param body - Async callback receiving the per-scope env.
+     * @returns The body's return value.
      */
-    setIngest: (value: unknown) => Promise<void>;
-    /** Sets respond function for the current request. Called by source per-request. */
-    setRespond: (fn: RespondFn | undefined) => void;
+    withScope: <R>(rawScope: unknown, respond: RespondFn | undefined, body: (env: ScopeEnv<T>) => Promise<R>) => Promise<R>;
 }
 type Init$1<T extends TypesGeneric$1 = Types$1> = (context: Context$1<T>) => Instance$2<T> | Promise<Instance$2<T>>;
 type InitSource<T extends TypesGeneric$1 = Types$1> = {
@@ -1839,8 +2161,8 @@ type InitSource<T extends TypesGeneric$1 = Types$1> = {
     config?: Partial<Config$1<T>>;
     env?: Partial<Env$1<T>>;
     primary?: boolean;
-    next?: RouteSpec;
-    before?: RouteSpec;
+    next?: Route;
+    before?: Route;
     cache?: Cache;
     validate?: Validate;
 };
@@ -1857,14 +2179,36 @@ interface InitSources {
  * - 'codebox': Source uses a JSON/code editor (default)
  */
 type Renderer = 'browser' | 'codebox';
+/**
+ * Typed accessor for sources registered on a collector.
+ *
+ * The collector's `sources` bag indexes to `Source.Instance` (defaults erase
+ * the generic), which collapses the source's declared `push` signature to
+ * `Elb.Fn`. Use this helper at the call site to recover the narrow type
+ * without casts.
+ *
+ * @example
+ * type TestSourceTypes = Source.Types<unknown, unknown, TestPushFn>;
+ * const src = getSource<TestSourceTypes>(collector, 'testSource');
+ * await src.push({ method: 'GET', path: '/api/data' }); // typed!
+ *
+ * @throws Error with message `Source not found: <id>` when the id is unknown.
+ */
+declare function getSource<T extends TypesGeneric$1 = Types$1>(collector: {
+    sources: {
+        [id: string]: Instance$2<any>;
+    };
+}, id: string): Instance$2<T>;
 
 type source_InitSource<T extends TypesGeneric$1 = Types$1> = InitSource<T>;
 type source_InitSources = InitSources;
 type source_Mapping<T extends TypesGeneric$1 = Types$1> = Mapping<T>;
 type source_Push<T extends TypesGeneric$1 = Types$1> = Push<T>;
 type source_Renderer = Renderer;
+type source_ScopeEnv<T extends TypesGeneric$1 = Types$1> = ScopeEnv<T>;
+declare const source_getSource: typeof getSource;
 declare namespace source {
-  export type { BaseEnv$1 as BaseEnv, Config$1 as Config, Context$1 as Context, Env$1 as Env, Init$1 as Init, InitSettings$1 as InitSettings, source_InitSource as InitSource, source_InitSources as InitSources, Instance$2 as Instance, source_Mapping as Mapping, PartialConfig$1 as PartialConfig, source_Push as Push, source_Renderer as Renderer, Settings$1 as Settings, SetupOptions$1 as SetupOptions, Types$1 as Types, TypesGeneric$1 as TypesGeneric, TypesOf$1 as TypesOf };
+  export { type BaseEnv$1 as BaseEnv, type Config$1 as Config, type Context$1 as Context, type Env$1 as Env, type Init$1 as Init, type InitSettings$1 as InitSettings, type source_InitSource as InitSource, type source_InitSources as InitSources, type Instance$2 as Instance, type source_Mapping as Mapping, type PartialConfig$1 as PartialConfig, type source_Push as Push, type source_Renderer as Renderer, type source_ScopeEnv as ScopeEnv, type Settings$1 as Settings, type SetupOptions$1 as SetupOptions, type Types$1 as Types, type TypesGeneric$1 as TypesGeneric, type TypesOf$1 as TypesOf, source_getSource as getSource };
 }
 
 interface BaseEnv {
@@ -1927,6 +2271,25 @@ interface InitStores {
 interface Stores {
     [storeId: string]: Instance$1;
 }
+/**
+ * Typed accessor for stores registered on a collector.
+ *
+ * The collector's `stores` bag indexes to `Store.Instance` (defaults erase
+ * the generic). Use this helper at the call site to recover the narrow type
+ * without casts.
+ *
+ * @example
+ * type MyStoreTypes = Store.Types<MySettings>;
+ * const store = getStore<MyStoreTypes>(collector, 'cache');
+ * await store.set('key', 'value');
+ *
+ * @throws Error with message `Store not found: <id>` when the id is unknown.
+ */
+declare function getStore<T extends TypesGeneric = Types>(collector: {
+    stores: {
+        [id: string]: Instance$1<any>;
+    };
+}, id: string): Instance$1<T>;
 
 type store_BaseEnv = BaseEnv;
 type store_Config<T extends TypesGeneric = Types> = Config<T>;
@@ -1947,8 +2310,9 @@ type store_Stores = Stores;
 type store_Types<S = unknown, E = BaseEnv, I = S, U = unknown> = Types<S, E, I, U>;
 type store_TypesGeneric = TypesGeneric;
 type store_TypesOf<I> = TypesOf<I>;
+declare const store_getStore: typeof getStore;
 declare namespace store {
-  export type { store_BaseEnv as BaseEnv, store_Config as Config, store_Context as Context, store_DeleteFn as DeleteFn, store_Env as Env, store_GetFn as GetFn, store_Init as Init, store_InitFn as InitFn, store_InitSettings as InitSettings, store_InitStore as InitStore, store_InitStores as InitStores, Instance$1 as Instance, store_PartialConfig as PartialConfig, store_SetFn as SetFn, store_Settings as Settings, store_SetupOptions as SetupOptions, store_Stores as Stores, store_Types as Types, store_TypesGeneric as TypesGeneric, store_TypesOf as TypesOf };
+  export { type store_BaseEnv as BaseEnv, type store_Config as Config, type store_Context as Context, type store_DeleteFn as DeleteFn, type store_Env as Env, type store_GetFn as GetFn, type store_Init as Init, type store_InitFn as InitFn, type store_InitSettings as InitSettings, type store_InitStore as InitStore, type store_InitStores as InitStores, type Instance$1 as Instance, type store_PartialConfig as PartialConfig, type store_SetFn as SetFn, type store_Settings as Settings, type store_SetupOptions as SetupOptions, type store_Stores as Stores, type store_Types as Types, type store_TypesGeneric as TypesGeneric, type store_TypesOf as TypesOf, store_getStore as getStore };
 }
 
 /**
@@ -2251,7 +2615,7 @@ interface SendResponse {
  * Creates a TransformerResult for dynamic chain routing.
  * Use this in transformer push functions to redirect the chain.
  */
-declare function branch(event: DeepPartialEvent, next: RouteSpec): Result$1;
+declare function branch(event: DeepPartialEvent, next: Route): Result$1;
 
 /**
  * Anonymizes an IPv4 address by setting the last octet to 0.
@@ -2539,20 +2903,54 @@ declare const defaultClickIds: ClickIdEntry[];
  */
 declare function getMarketingParameters(url: URL, custom?: MarketingParameters, clickIds?: ClickIdEntry[]): Properties;
 
+/**
+ * Options for scheduling primitives ({@link debounce}, {@link throttle}).
+ *
+ * - `wait`: Debounce window in ms. Timer resets on every call.
+ * - `size`: Hard call-count cap per window. Flush immediately when call
+ *   count reaches this number. Useful for batch buffers that must not
+ *   grow unbounded.
+ * - `age`: Hard age cap in ms since the first call of the current window.
+ *   Forces a flush even if calls keep arriving and reset the debounce.
+ *   Prevents debounce starvation under sustained load.
+ */
+interface ScheduleOptions {
+    wait?: number;
+    size?: number;
+    age?: number;
+}
+/**
+ * Returned by {@link debounce}: a callable that schedules `fn` plus
+ * deterministic `flush` / `cancel` controls.
+ */
+interface Debounced<P extends unknown[], R> {
+    (...args: P): Promise<R | undefined>;
+    /** Force an immediate flush with the most recent args. Resolves after `fn` settles. */
+    flush(): Promise<R | undefined>;
+    /** Cancel any pending invocation. No `fn` call, pending promises resolve to undefined. */
+    cancel(): void;
+    /** Number of scheduled calls since the current window opened. */
+    size(): number;
+}
 /**
  * Creates a debounced function that delays invoking `fn` until after `wait`
  * milliseconds have elapsed since the last time the debounced function was
  * invoked. The debounced function comes with a `cancel` method to cancel
  * delayed `fn` invocations and a `flush` method to immediately invoke them.
  *
+ * The second argument is either a `wait` number (legacy form) or a
+ * {@link ScheduleOptions} object. The object form adds `size` (hard count
+ * cap) and `age` (hard window-age cap) so the function flushes deterministically
+ * under sustained load instead of letting the debounce reset forever.
+ *
  * @template P, R
  * @param fn The function to debounce.
- * @param wait The number of milliseconds to delay.
+ * @param opts Either a wait-ms number or a {@link ScheduleOptions} object.
  * @param immediate Trigger the function on the leading edge, instead of the trailing.
- * @returns The new debounced function.
+ * @returns A {@link Debounced} callable with `flush`, `cancel`, and `size` methods.
  */
-declare function debounce<P extends unknown[], R>(fn: (...args: P) => R, wait?: number, immediate?: boolean): (...args: P) => Promise<R>;
-declare function throttle<P extends unknown[], R>(fn: (...args: P) => R | undefined, delay?: number): (...args: P) => R | undefined;
+declare function debounce<P extends unknown[], R>(fn: (...args: P) => R, opts?: number | ScheduleOptions, immediate?: boolean): Debounced<P, R>;
+declare function throttle<P extends unknown[], R>(fn: (...args: P) => R | undefined, opts?: number | ScheduleOptions): (...args: P) => R | undefined;
 
 /**
  * Checks if a value is an arguments object.
@@ -2944,6 +3342,24 @@ declare function tryCatch<P extends unknown[], R>(fn: (...args: P) => R | undefi
 declare function tryCatchAsync<P extends unknown[], R, S>(fn: (...args: P) => R, onError: (err: unknown) => S, onFinally?: () => void | Promise<void>): (...args: P) => Promise<R | S>;
 declare function tryCatchAsync<P extends unknown[], R>(fn: (...args: P) => R, onError?: undefined, onFinally?: () => void | Promise<void>): (...args: P) => Promise<R | undefined>;
 
+/**
+ * Error subclass for invariant violations or operator-initiated aborts
+ * that must escape the top-level boundary catches in `collector.push`
+ * and `collector.command`.
+ *
+ * Standard `Error` instances are absorbed by the boundary, logged, and
+ * counted on `collector.status.failed`. A `FatalError` rethrows so a
+ * runtime supervisor (CLI runner, Express server, container orchestrator)
+ * can terminate the process cleanly.
+ *
+ * Use sparingly. Most operational failures are recoverable and should
+ * be plain `Error`. Reserve `FatalError` for programmer-error invariant
+ * violations or explicit fail-stop signals.
+ */
+declare class FatalError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+
 /**
  * A utility function that wraps a function with hooks.
  *
@@ -3143,40 +3559,32 @@ declare function mcpError(error: unknown, hint?: string): {
  */
 declare function compileMatcher(expr: MatchExpression | '*' | undefined): CompiledMatcher;
 
-interface CompiledRoute {
-    match: CompiledMatcher;
-    next: CompiledNext;
-}
-type CompiledNext = {
-    type: 'static';
-    value: string;
-} | {
-    type: 'chain';
-    value: string[];
-} | {
-    type: 'case';
-    routes: CompiledRoute[];
-} | {
-    type: 'gate';
-    match: CompiledMatcher;
-    next?: CompiledNext;
-} | {
-    type: 'sequence';
-    value: CompiledNext[];
-};
 /**
- * Pure RouteConfig array — every element is a RouteConfig object.
- * Used to detect the legacy first-match `case` shape.
+ * 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 isRouteArray(next: Route): next is RouteConfig[];
-declare function compileNext(next: Route | undefined): CompiledNext | undefined;
-declare function resolveNext(compiled: CompiledNext | undefined, context?: Record<string, unknown>): string | string[] | undefined;
+declare function getNextSteps(spec: Route | undefined, context?: Record<string, unknown>): string[];
 
 interface CompiledCacheRule {
     match: CompiledMatcher;
     key: string[];
     ttl: number;
-    update?: CacheRule['update'];
+    update?: EventCacheRule['update'];
 }
 interface CompiledCache {
     stop: boolean;
@@ -3195,21 +3603,36 @@ interface CacheResult {
  * Normalizes ingest (defaulting to {}) and optionally includes event.
  */
 declare function buildCacheContext(ingest?: unknown, event?: unknown): Record<string, unknown>;
-declare function compileCache(cache: Cache): CompiledCache;
-declare function checkCache(compiled: CompiledCache, store: Instance$1, context: Record<string, unknown>, namespace?: string): CacheResult | null;
+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;
 declare function applyUpdate(value: unknown, update: Record<string, unknown> | undefined, context: Record<string, unknown>, collector: Instance$6): Promise<unknown>;
 
-declare const TRANSFORMER_OPERATIVE_FIELDS: readonly ["code", "package", "before", "next", "cache", "mapping"];
-type TransformerOperativeField = (typeof TRANSFORMER_OPERATIVE_FIELDS)[number];
-interface TransformerEntryValidation {
+/**
+ * Single source of truth for step-entry validation across all four kinds.
+ *
+ * An empty entry (no `code`, no `package`, no `import`) is a valid no-op
+ * step for all four kinds. The bundler emits no code; the runtime skips
+ * registration. No error is raised for empty steps.
+ *
+ * Error codes:
+ * - UNKNOWN_KEY          unknown top-level key on a step entry
+ * - CONFLICT             two of {code, package, import} together, or other mutually exclusive pairs
+ * - MISSING_PACKAGE      `import` set without `package`
+ * - OBSOLETE_CODE_STRING `code` is a string (legacy named-export shape; use `import` instead)
+ * - 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[]>;
+type StepEntryErrorCode = 'UNKNOWN_KEY' | 'CONFLICT' | 'MISSING_PACKAGE' | 'OBSOLETE_CODE_STRING' | 'INVALID_IMPORT' | 'INVALID_CODE_SHAPE';
+interface StepEntryValidation {
     ok: boolean;
     reason?: string;
-    code?: 'UNKNOWN_KEY' | 'CONFLICT';
+    code?: StepEntryErrorCode;
     key?: string;
 }
-declare function validateTransformerEntry(entry: Record<string, unknown>): TransformerEntryValidation;
-declare function isPathTransformerEntry(entry: Record<string, unknown>): boolean;
+declare function validateStepEntry(entry: Record<string, unknown>, kind: Flow.StepKind): StepEntryValidation;
+declare function isPathStepEntry(entry: Record<string, unknown>, kind: Flow.StepKind): boolean;
 
 type StepOut = Flow.StepOut;
 /**
@@ -3249,4 +3672,4 @@ declare const REF_STORE: RegExp;
 declare const REF_SECRET: RegExp;
 declare const REF_CODE_PREFIX = "$code:";
 
-export { cache as Cache, type CacheResult, type ClickIdEntry, collector as Collector, type CompiledCache, type CompiledNext, type CompiledRoute, Const, context as Context, destination as Destination, type DestroyContext, type DestroyFn, ENV_MARKER_PREFIX, elb as Elb, type ExampleSummary, Flow, type FlowConfigResolver, hint as Hint, hooks as Hooks, type Ingest, type IngestMeta, type JsonSchema, Level, lifecycle as Lifecycle, type LifecycleContext, logger as Logger, mapping as Mapping, type MarketingParameters, matcher as Matcher, type MockLogger, on as On, REF_CODE_PREFIX, REF_CONTRACT, REF_ENV, REF_FLOW, REF_SECRET, REF_STORE, REF_VAR_FULL, REF_VAR_INLINE, request as Request, type ResolveOptions, type RespondFn, type RespondOptions, type SendDataValue, type SendHeaders, type SendResponse, type SetupFn, simulation as Simulation, source as Source, type StorageType, store as Store, TRANSFORMER_OPERATIVE_FIELDS, transformer as Transformer, type TransformerEntryValidation, type TransformerOperativeField, trigger as Trigger, type Validate, type ValidateEvents, walkeros as WalkerOS, type WalkerOSPackage, type WalkerOSPackageInfo, type WalkerOSPackageMeta, anonymizeIP, applyUpdate, assign, branch, buildCacheContext, castToProperty, castValue, checkCache, clone, compileCache, compileMatcher, compileNext, createDestination, createEvent, createIngest, createLogger, createMockContext, createMockLogger, createRespond, debounce, deepMerge, defaultClickIds, fetchPackage, fetchPackageSchema, filterValues, flattenIncludeSections, formatOut, getBrowser, getBrowserVersion, getByPath, getDeviceType, getEvent, getFlowSettings, getGrantedConsent, getHeaders, getId, getMappingEvent, getMappingValue, getMarketingParameters, getOS, getOSVersion, getPlatform, getSpanId, isArguments, isArray, isBoolean, isCommand, isDefined, isElementOrDocument, isFunction, isNumber, isObject, isPathTransformerEntry, isPropertyType, isRouteArray, isSameType, isString, mcpError, mcpResult, mergeContractSchemas, mockEnv, packageNameToVariable, parseUserAgent, processEventMapping, requestToData, requestToParameter, resolveContracts, resolveNext, resolveSetup, setByPath, storeCache, throttle, throwError, transformData, traverseEnv, trim, tryCatch, tryCatchAsync, useHooks, validateTransformerEntry, walkPath, wrapCondition, wrapFn, wrapValidate };
+export { cache as Cache, type CacheResult, type ClickIdEntry, collector as Collector, type CompiledCache, Const, context as Context, type Debounced, destination as Destination, type DestroyContext, type DestroyFn, type DroppedCounters, ENV_MARKER_PREFIX, elb as Elb, type ExampleSummary, FatalError, Flow, type FlowConfigResolver, hint as Hint, hooks as Hooks, type Ingest, type IngestMeta, type JsonSchema, Level, lifecycle as Lifecycle, type LifecycleContext, logger as Logger, mapping as Mapping, type MarketingParameters, matcher as Matcher, type MockLogger, on as On, REF_CODE_PREFIX, REF_CONTRACT, REF_ENV, REF_FLOW, REF_SECRET, REF_STORE, REF_VAR_FULL, REF_VAR_INLINE, request as Request, type ResolveOptions, type RespondFn, type RespondOptions, STEP_OPERATIVE_FIELDS, type ScheduleOptions, type SendDataValue, type SendHeaders, type SendResponse, type SetupFn, simulation as Simulation, source as Source, type StepEntryErrorCode, type StepEntryValidation, type StepKind, type StorageType, store as Store, transformer as Transformer, trigger as Trigger, type Validate, type ValidateEvents, walkeros as WalkerOS, type WalkerOSPackage, type WalkerOSPackageInfo, type WalkerOSPackageMeta, anonymizeIP, applyUpdate, assign, branch, buildCacheContext, castToProperty, castValue, checkCache, clone, compileCache, compileMatcher, createDestination, createEvent, createIngest, createLogger, createMockContext, createMockLogger, createRespond, debounce, deepMerge, defaultClickIds, fetchPackage, fetchPackageSchema, filterValues, flattenIncludeSections, formatOut, getBrowser, getBrowserVersion, getByPath, getDeviceType, getEvent, getFlowSettings, getGrantedConsent, getHeaders, getId, getMappingEvent, getMappingValue, getMarketingParameters, getNextSteps, getOS, getOSVersion, getPlatform, getSpanId, isArguments, isArray, isBoolean, isCommand, isDefined, isElementOrDocument, isFunction, isNumber, isObject, isPathStepEntry, isPropertyType, isSameType, isString, mcpError, mcpResult, mergeContractSchemas, mockEnv, packageNameToVariable, parseUserAgent, processEventMapping, requestToData, requestToParameter, resolveContracts, resolveSetup, setByPath, stepId, storeCache, throttle, throwError, transformData, traverseEnv, trim, tryCatch, tryCatchAsync, useHooks, validateStepEntry, walkPath, wrapCondition, wrapFn, wrapValidate };